    001/*
    002    Licensed to the Apache Software Foundation (ASF) under one
    003    or more contributor license agreements.  See the NOTICE file
    004    distributed with this work for additional information
    005    regarding copyright ownership.  The ASF licenses this file
    006    to you under the Apache License, Version 2.0 (the
    007    "License"); you may not use this file except in compliance
    008    with the License.  You may obtain a copy of the License at
    009
    010       http://www.apache.org/licenses/LICENSE-2.0
    011
    012    Unless required by applicable law or agreed to in writing,
    013    software distributed under the License is distributed on an
    014    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    015    KIND, either express or implied.  See the License for the
    016    specific language governing permissions and limitations
    017    under the License.
    018 */
    019package org.apache.wiki.providers;
    020
    021import org.apache.wiki.WikiPage;
    022import org.apache.wiki.WikiProvider;
    023import org.apache.wiki.api.exceptions.ProviderException;
    024import org.apache.wiki.search.QueryItem;
    025import org.apache.wiki.search.SearchResult;
    026
    027import java.util.Collection;
    028import java.util.Date;
    029import java.util.List;
    030
    031
    032/**
    033 *  Each Wiki page provider should implement this interface.
    034 *  <P>
    035 *  You can build whatever page providers based on this, just leave the unused methods do something useful.
    036 *  <P>
    037 *  WikiPageProvider uses Strings and ints to refer to pages.  This may be a bit odd, since WikiAttachmentProviders all use Attachment
    038 *  instead of name/version.  We will perhaps modify these in the future.  In the mean time, name/version is quite sufficient.
    039 *  <P>
    040 *  FIXME: In reality we should have an AbstractWikiPageProvider, which would provide intelligent backups for subclasses.
    041 * @deprecated use {@link org.apache.wiki.api.providers.PageProvider} instead
    042 * @see org.apache.wiki.api.providers.PageProvider
    043 */
    044@Deprecated
    045public interface WikiPageProvider extends WikiProvider {
    046
    047    /**
    048     *  Attempts to save the page text for page "page".  Note that the provider creates a new version regardless of what the version
    049     *  parameter of the WikiPage is.
    050     *
    051     *  @param page The WikiPage to save
    052     *  @param text The text to save.
    053     *  @throws ProviderException If something goes wrong.
    054     */
    055    void putPageText( WikiPage page, String text ) throws ProviderException;
    056
    057    /**
    058     *  Return true, if page exists.
    059     *
    060     *  @param page The page name.
    061     *  @return true, if the page exists; false otherwise.
    062     */
    063    boolean pageExists( String page );
    064
    065    /**
    066     * Return true, if page with a particular version exists.
    067     *
    068     * @param page    The page name to check for
    069     * @param version The version to check
    070     * @return True, if page exists; false otherwise.
    071     */
    072    boolean pageExists( String page, int version );
    073
    074    /**
    075     *  Finds pages based on the query.   Only applicable to providers which implement the FastSearch interface.  Otherwise JSPWiki
    076     *  will use its internal cache.
    077     *  <p>
    078     *  This method should really be a part of the FastSearch IF.
    079     *
    080     *  @param query An array of QueryItems to match
    081     *  @return A Collection of WikiPages.
    082     */
    083    Collection< SearchResult > findPages( QueryItem[] query );
    084
    085    /**
    086     *  Returns info about the page.
    087     *
    088     *  @return A filled WikiPage.
    089     *  @param page The page name
    090     *  @param version The version number
    091     *  @throws ProviderException If something goes wrong.
    092     */
    093    WikiPage getPageInfo( String page, int version ) throws ProviderException;
    094
    095    /**
    096     *  Returns all pages.  Each element in the returned Collection should be a WikiPage.
    097     *
    098     *  @return A collection of WikiPages
    099     *  @throws ProviderException If something goes wrong.
    100     */
    101    Collection< WikiPage > getAllPages() throws ProviderException;
    102
    103    /**
    104     *  Gets a list of recent changes.
    105     *
    106     *  @param date The date to check from
    107     *  @return A Collection of WikiPages
    108     *  @since 1.6.4
    109     */
    110    Collection< WikiPage > getAllChangedSince( Date date );
    111
    112    /**
    113     *  Gets the number of pages.
    114     *
    115     *  @return The number of pages in the repository
    116     *  @throws ProviderException If something goes wrong
    117     *  @since 1.6.4
    118     */
    119    int getPageCount() throws ProviderException;
    120
    121    /**
    122     *  Returns version history.  Each element should be a WikiPage.
    123     *
    124     *  @param page The name of the page to get the history from.
    125     *  @return A collection of WikiPages.
    126     *  @throws ProviderException If something goes wrong.
    127     */
    128    List< WikiPage > getVersionHistory( String page ) throws ProviderException;
    129
    130    /**
    131     *  Gets a specific version out of the repository.
    132     *
    133     *  @param page Name of the page to fetch.
    134     *  @param version Version of the page to fetch.
    135     *  @return The content of the page, or null, if the page does not exist.
    136     *  @throws ProviderException If something goes wrong.
    137     */
    138    String getPageText( String page, int version ) throws ProviderException;
    139
    140    /**
    141     *  Removes a specific version from the repository.  The implementations should really do no more security checks, since that is the
    142     *  domain of the PageManager.  Just delete it as efficiently as you can.
    143     *
    144     *  @since 2.0.17.
    145     *  @param pageName Name of the page to be removed.
    146     *  @param version  Version of the page to be removed.  May be LATEST_VERSION.
    147     *  @throws ProviderException If the page cannot be removed for some reason.
    148     */
    149    void deleteVersion( String pageName, int version ) throws ProviderException;
    150
    151    /**
    152     *  Removes an entire page from the repository.  The implementations should really do no more security checks, since that is the domain
    153     *  of the PageManager.  Just delete it as efficiently as you can.  You should also delete any auxiliary files that belong to this page,
    154     *  IF they were created by this provider.
    155     *
    156     *  <P>The reason why this is named differently from deleteVersion() (logically, this method should be an overloaded version) is that
    157     *  I want to be absolutely sure I don't accidentally use the wrong method.  With overloading something like that happens sometimes...
    158     *
    159     *  @since 2.0.17.
    160     *  @param pageName Name of the page to be removed completely.
    161     *  @throws ProviderException If the page could not be removed for some reason.
    162     */
    163    void deletePage( String pageName ) throws ProviderException;
    164
    165    /**
    166     * Move a page
    167     *
    168     * @param from  Name of the page to move.
    169     * @param to    New name of the page.
    170     * @throws ProviderException If the page could not be moved for some reason.
    171     */
    172    void movePage(String from, String to) throws ProviderException;
    173
    174}