    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.pages;
    020
    021import org.apache.wiki.api.core.Context;
    022import org.apache.wiki.api.core.Page;
    023import org.apache.wiki.api.exceptions.ProviderException;
    024import org.apache.wiki.api.exceptions.WikiException;
    025import org.apache.wiki.api.providers.PageProvider;
    026import org.apache.wiki.event.WikiEventListener;
    027
    028import java.util.Collection;
    029import java.util.List;
    030import java.util.Set;
    031
    032
    033public interface PageManager extends WikiEventListener {
    034
    035    /** The property value for setting the current page provider.  Value is {@value}. */
    036    String PROP_PAGEPROVIDER = "jspwiki.pageProvider";
    037    /** The property value for setting the amount of time before the page locks expire. Value is {@value}. */
    038    String PROP_LOCKEXPIRY = "jspwiki.lockExpiryTime";
    039
    040    /**
    041     * Returns the page provider currently in use.
    042     *
    043     * @return A WikiPageProvider instance.
    044     */
    045    PageProvider getProvider();
    046
    047    /**
    048     * Returns all pages in some random order.  If you need just the page names,
    049     * please see {@link org.apache.wiki.references.ReferenceManager#findCreated() ReferenceManager#findCreated()}, which is probably a lot
    050     * faster.  This method may cause repository access.
    051     *
    052     * @return A Collection of WikiPage objects.
    053     * @throws ProviderException If the backend has problems.
    054     */
    055    Collection< Page > getAllPages() throws ProviderException;
    056
    057    /**
    058     * Fetches the page text from the repository.  This method also does some sanity checks, like checking for the pageName validity, etc.
    059     * Also, if the page repository has been modified externally, it is smart enough to handle such occurrences.
    060     *
    061     * @param pageName The name of the page to fetch.
    062     * @param version  The version to find
    063     * @return The page content as a raw string
    064     * @throws ProviderException If the backend has issues.
    065     */
    066    String getPageText( String pageName, int version ) throws ProviderException;
    067
    068    /**
    069     *  Returns the pure text of a page, no conversions.  Use this if you are writing something that depends on the parsing
    070     *  of the page. Note that you should always check for page existence through pageExists() before attempting to fetch
    071     *  the page contents.
    072     *
    073     *  This method is pretty similar to {@link #getPageText(String, int)}, except that it doesn't throw {@link ProviderException},
    074     *  it logs and swallows them.
    075     *
    076     *  @param page The name of the page to fetch.
    077     *  @param version If WikiPageProvider.LATEST_VERSION, then uses the latest version.
    078     *  @return The page contents.  If the page does not exist, returns an empty string.
    079     */
    080    String getPureText( String page, int version );
    081
    082    /**
    083     *  Returns the pure text of a page, no conversions.  Use this if you are writing something that depends on the parsing
    084     *  the page. Note that you should always check for page existence through pageExists() before attempting to fetch
    085     *  the page contents.
    086     *
    087     *  This method is pretty similar to {@link #getPageText(String, int)}, except that it doesn't throw {@link ProviderException},
    088     *  it logs and swallows them.
    089     *
    090     *  @param page A handle to the WikiPage
    091     *  @return String of WikiText.
    092     *  @since 2.1.13, moved to PageManager on 2.11.0.
    093     */
    094    default String getPureText( final Page page ) {
    095        return getPureText( page.getName(), page.getVersion() );
    096    }
    097
    098    /**
    099     *  Returns the un-HTMLized text of the given version of a page. This method also replaces the &lt; and &amp; -characters with
    100     *  their respective HTML entities, thus making it suitable for inclusion on an HTML page.  If you want to have the page text
    101     *  without any conversions, use {@link #getPureText(String, int)}.
    102     *
    103     * @param page WikiName of the page to fetch
    104     * @param version  Version of the page to fetch
    105     * @return WikiText.
    106     */
    107    String getText( String page, int version );
    108
    109    /**
    110     *  Returns the un-HTMLized text of the latest version of a page. This method also replaces the &lt; and &amp; -characters with
    111     *  their respective HTML entities, thus making it suitable for inclusion on an HTML page.  If you want to have the page text
    112     *  without any conversions, use {@link #getPureText(String, int)}.
    113     *
    114     *  @param page WikiName of the page to fetch.
    115     *  @return WikiText.
    116     */
    117    default String getText( final String page ) {
    118        return getText( page, PageProvider.LATEST_VERSION );
    119    }
    120
    121    /**
    122     *  Returns the un-HTMLized text of the given version of a page in the given context.  USE THIS METHOD if you don't know what doing.
    123     *  <p>
    124     *  This method also replaces the &lt; and &amp; -characters with their respective HTML entities, thus making it suitable
    125     *  for inclusion on an HTML page.  If you want to have the page text without any conversions, use {@link #getPureText(Page)}.
    126     *
    127     *  @since 1.9.15.
    128     *  @param page A page reference (not an attachment)
    129     *  @return The page content as HTMLized String.
    130     *  @see PageManager#getPureText(Page)
    131     */
    132    default String getText( final Page page ) {
    133        return getText( page.getName(), page.getVersion() );
    134    }
    135
    136    /**
    137     *  Writes the WikiText of a page into the page repository. If the <code>jspwiki.properties</code> file contains
    138     *  the property <code>jspwiki.approver.workflow.saveWikiPage</code> and its value resolves to a valid user,
    139     *  {@link org.apache.wiki.auth.authorize.Group} or {@link org.apache.wiki.auth.authorize.Role}, this method will
    140     *  place a {@link org.apache.wiki.workflow.Decision} in the approver's workflow inbox and throw a
    141     *  {@link org.apache.wiki.workflow.DecisionRequiredException}. If the submitting user is authenticated and the
    142     *  page save is rejected, a notification will be placed in the user's decision queue.
    143     *
    144     *  @since 2.1.28, moved to PageManager on 2.11.0
    145     *  @param context The current WikiContext
    146     *  @param text    The Wiki markup for the page.
    147     *  @throws WikiException if the save operation encounters an error during the save operation. If the page-save
    148     *  operation requires approval, the exception will be of type {@link org.apache.wiki.workflow.DecisionRequiredException}.
    149     *  Individual PageFilters, such as the {@link org.apache.wiki.filters.SpamFilter} may also throw a
    150     *  {@link org.apache.wiki.api.exceptions.RedirectException}.
    151     */
    152    void saveText( Context context, String text ) throws WikiException;
    153
    154    /**
    155     * Puts the page text into the repository.  Note that this method does NOT update
    156     * JSPWiki internal data structures, and therefore you should always use saveText()
    157     *
    158     * @param page    Page to save
    159     * @param content Wikimarkup to save
    160     * @throws ProviderException If something goes wrong in the saving phase
    161     */
    162    void putPageText( Page page, String content ) throws ProviderException;
    163
    164    /**
    165     * Locks page for editing.  Note, however, that the PageManager will in no way prevent you from actually editing this page;
    166     * the lock is just for information.
    167     *
    168     * @param page WikiPage to lock
    169     * @param user Username to use for locking
    170     * @return null, if page could not be locked.
    171     */
    172    PageLock lockPage( Page page, String user );
    173
    174    /**
    175     * Marks a page free to be written again.  If there has not been a lock, will fail quietly.
    176     *
    177     * @param lock A lock acquired in lockPage().  Safe to be null.
    178     */
    179    void unlockPage( PageLock lock );
    180
    181    /**
    182     * Returns the current lock owner of a page.  If the page is not locked, will return null.
    183     *
    184     * @param page The page to check the lock for
    185     * @return Current lock, or null, if there is no lock
    186     */
    187    PageLock getCurrentLock( Page page );
    188
    189    /**
    190     * Returns a list of currently applicable locks.  Note that by the time you get the list,
    191     * the locks may have already expired, so use this only for informational purposes.
    192     *
    193     * @return List of PageLock objects, detailing the locks.  If no locks exist, returns an empty list.
    194     * @since 2.0.22.
    195     */
    196    List< PageLock > getActiveLocks();
    197
    198    /**
    199     *  Finds the corresponding WikiPage object based on the page name.  It always finds
    200     *  the latest version of a page.
    201     *
    202     *  @param pagereq The name of the page to look for.
    203     *  @return A WikiPage object, or null, if the page by the name could not be found.
    204     */
    205    Page getPage( String pagereq );
    206
    207    /**
    208     *  Finds the corresponding WikiPage object base on the page name and version.
    209     *
    210     *  @param pagereq The name of the page to look for.
    211     *  @param version The version number to look for.  May be WikiProvider.LATEST_VERSION,
    212     *  in which case it will look for the latest version (and this method then becomes
    213     *  the equivalent of getPage(String).
    214     *
    215     *  @return A WikiPage object, or null, if the page could not be found; or if there
    216     *  is no such version of the page.
    217     *  @since 1.6.7 (moved to PageManager on 2.11.0).
    218     */
    219    Page getPage( String pagereq, int version );
    220
    221    /**
    222     * Finds a WikiPage object describing a particular page and version.
    223     *
    224     * @param pageName The name of the page
    225     * @param version  A version number
    226     * @return A WikiPage object, or null, if the page does not exist
    227     * @throws ProviderException If there is something wrong with the page name or the repository
    228     */
    229    Page getPageInfo( String pageName, int version ) throws ProviderException;
    230
    231    /**
    232     * Gets a version history of page.  Each element in the returned List is a WikiPage.
    233     *
    234     * @param pageName The name of the page or attachment to fetch history for
    235     * @return If the page does not exist or there's some problem retrieving the version history, returns null,
    236     *         otherwise a List of WikiPages / Attachments, each corresponding to a different revision of the page / attachment.
    237     */
    238    < T extends Page > List< T > getVersionHistory( String pageName );
    239
    240    /**
    241     *  Returns the provider name.
    242     *
    243     *  @return The full class name of the current page provider.
    244     */
    245    String getCurrentProvider();
    246
    247    /**
    248     * Returns a human-readable description of the current provider.
    249     *
    250     * @return A human-readable description.
    251     */
    252    String getProviderDescription();
    253
    254    /**
    255     * Returns the total count of all pages in the repository. This
    256     * method is equivalent of calling getAllPages().size(), but
    257     * it swallows the ProviderException and returns -1 instead of
    258     * any problems.
    259     *
    260     * @return The number of pages, or -1, if there is an error.
    261     */
    262    int getTotalPageCount();
    263
    264    /**
    265     *  Returns a Collection of WikiPages, sorted in time order of last change (i.e. first object is the most recently changed).
    266     *  This method also includes attachments.
    267     *
    268     *  @return Set of WikiPage objects.
    269     */
    270    Set< Page > getRecentChanges();
    271
    272    /**
    273     * Returns true, if the page exists (any version) on the underlying WikiPageProvider.
    274     *
    275     * @param pageName Name of the page.
    276     * @return A boolean value describing the existence of a page
    277     * @throws ProviderException If the backend fails or the name is illegal.
    278     */
    279    boolean pageExists( String pageName ) throws ProviderException;
    280
    281    /**
    282     * Checks for existence of a specific page and version on the underlying WikiPageProvider.
    283     *
    284     * @param pageName Name of the page
    285     * @param version  The version to check
    286     * @return <code>true</code> if the page exists, <code>false</code> otherwise
    287     * @throws ProviderException If backend fails or name is illegal
    288     * @since 2.3.29
    289     */
    290    boolean pageExists( String pageName, int version ) throws ProviderException;
    291
    292    /**
    293     *  Checks for existence of a specific page and version denoted by a WikiPage on the underlying WikiPageProvider.
    294     *
    295     *  @param page A WikiPage object describing the name and version.
    296     *  @return true, if the page (or alias, or attachment) exists.
    297     *  @throws ProviderException If something goes badly wrong.
    298     *  @since 2.0
    299     */
    300    default boolean pageExists( final Page page ) throws ProviderException {
    301        if( page != null ) {
    302            return pageExists( page.getName(), page.getVersion() );
    303        }
    304        return false;
    305    }
    306
    307    /**
    308     *  Returns true, if the requested page (or an alias) exists.  Will consider any version as existing. Will check for all types of
    309     *  WikiPages: wiki pages themselves, attachments and special pages (non-existant references to other pages).
    310     *
    311     *  @param page WikiName of the page.
    312     *  @return true, if page (or attachment) exists.
    313     */
    314    boolean wikiPageExists( String page );
    315
    316    /**
    317     *  Returns true, if the requested page (or an alias) exists with the requested version. Will check for all types of
    318     *  WikiPages: wiki pages themselves, attachments and special pages (non-existant references to other pages).
    319     *
    320     *  @param page Page name
    321     *  @param version Page version
    322     *  @return True, if page (or alias, or attachment) exists
    323     *  @throws ProviderException If the provider fails.
    324     */
    325    boolean wikiPageExists( String page, int version ) throws ProviderException;
    326
    327    /**
    328     *  Returns true, if the requested page (or an alias) exists, with the specified version in the WikiPage. Will check for all types of
    329     *  WikiPages: wiki pages themselves, attachments and special pages (non-existant references to other pages).
    330     *
    331     *  @param page A WikiPage object describing the name and version.
    332     *  @return true, if the page (or alias, or attachment) exists.
    333     *  @throws ProviderException If something goes badly wrong.
    334     *  @since 2.0
    335     */
    336    default boolean wikiPageExists( final Page page ) throws ProviderException {
    337        if( page != null ) {
    338            return wikiPageExists( page.getName(), page.getVersion() );
    339        }
    340        return false;
    341    }
    342
    343    /**
    344     * Deletes only a specific version of a WikiPage.
    345     *
    346     * @param page The page to delete.
    347     * @throws ProviderException if the page fails
    348     */
    349    void deleteVersion( Page page ) throws ProviderException;
    350
    351    /**
    352     *  Deletes a page or an attachment completely, including all versions.  If the page does not exist, does nothing.
    353     *
    354     * @param pageName The name of the page.
    355     * @throws ProviderException If something goes wrong.
    356     */
    357    void deletePage( String pageName ) throws ProviderException;
    358
    359    /**
    360     * Deletes an entire page, all versions, all traces.
    361     *
    362     * @param page The WikiPage to delete
    363     * @throws ProviderException If the repository operation fails
    364     */
    365    void deletePage( Page page ) throws ProviderException;
    366
    367    /**
    368     * Returns the configured {@link PageSorter}.
    369     *
    370     * @return the configured {@link PageSorter}.
    371     */
    372    PageSorter getPageSorter();
    373
    374}