    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.references;
    020
    021import org.apache.wiki.api.core.Page;
    022import org.apache.wiki.api.exceptions.ProviderException;
    023import org.apache.wiki.api.filters.PageFilter;
    024import org.apache.wiki.event.WikiEventListener;
    025import org.apache.wiki.modules.InternalModule;
    026
    027import java.util.Collection;
    028import java.util.Set;
    029
    030/**
    031 *  Keeps track of wikipage references:
    032 *  <ul>
    033 *  <li>What pages a given page refers to</li>
    034 *  <li>What pages refer to a given page</li>
    035 *  </ul>
    036 *
    037 *  When a page is added or edited, its references are parsed, a Collection is received, and we crudely replace anything previous with
    038 *  this new Collection. We then check each referenced page name and make sure they know they are referred to by the new page.
    039 *  <p>
    040 *  Based on this information, we can perform non-optimal searches for e.g. unreferenced pages, top ten lists, etc.
    041 *  <p>
    042 *  The owning class must take responsibility of filling in any pre-existing information, probably by loading each and every WikiPage
    043 *  and calling this class to update the references when created.
    044 */
    045public interface ReferenceManager extends PageFilter, InternalModule, WikiEventListener {
    046
    047    /**
    048     *  Initializes the entire reference manager with the initial set of pages from the collection.
    049     *
    050     *  @param pages A collection of all pages you want to be included in the reference count.
    051     *  @since 2.2
    052     *  @throws ProviderException If reading of pages fails.
    053     */
    054    void initialize( final Collection< Page > pages ) throws ProviderException;
    055
    056    /**
    057     *  Reads a WikiPageful of data from a String and returns all links internal to this Wiki in a Collection.
    058     *
    059     *  @param page The WikiPage to scan
    060     *  @param pagedata The page contents
    061     *  @return a Collection of Strings
    062     */
    063    Collection< String > scanWikiLinks( final Page page, final String pagedata );
    064
    065    /**
    066     * Updates the m_referedTo and m_referredBy hashmaps when a page has been deleted.
    067     * <P>
    068     * Within the m_refersTo map the pagename is a key. The whole key-value-set has to be removed to keep the map clean.
    069     * Within the m_referredBy map the name is stored as a value. Since a key can have more than one value we have to
    070     * delete just the key-value-pair referring page:deleted page.
    071     *
    072     *  @param page Name of the page to remove from the maps.
    073     */
    074    void pageRemoved( final Page page );
    075
    076    /**
    077     *  Updates all references for the given page.
    078     *
    079     *  @param page wiki page for which references should be updated
    080     */
    081    void updateReferences( final Page page );
    082
    083    /**
    084     *  Updates the referred pages of a new or edited WikiPage. If a refersTo entry for this page already exists, it is removed
    085     *  and a new one is built from scratch. Also calls updateReferredBy() for each referenced page.
    086     *  <P>
    087     *  This is the method to call when a new page has been created and we want to a) set up its references and b) notify the
    088     *  referred pages of the references. Use this method during run-time.
    089     *
    090     *  @param page Name of the page to update.
    091     *  @param references A Collection of Strings, each one pointing to a page this page references.
    092     */
    093    void updateReferences( final String page, final Collection<String> references );
    094
    095    /**
    096     * Clears the references to a certain page so it's no longer in the map.
    097     *
    098     * @param pagename  Name of the page to clear references for.
    099     */
    100    void clearPageEntries( String pagename );
    101
    102
    103    /**
    104     *  Finds all unreferenced pages. This requires a linear scan through m_referredBy to locate keys with null or empty values.
    105     *
    106     *  @return The Collection of Strings
    107     */
    108    Collection< String > findUnreferenced();
    109
    110    /**
    111     * Finds all references to non-existant pages. This requires a linear scan through m_refersTo values; each value
    112     * must have a corresponding key entry in the reference Maps, otherwise such a page has never been created.
    113     * <P>
    114     * Returns a Collection containing Strings of unreferenced page names. Each non-existant page name is shown only
    115     * once - we don't return information on who referred to it.
    116     *
    117     * @return A Collection of Strings
    118     */
    119    Collection< String > findUncreated();
    120
    121    /**
    122     * Find all pages that refer to this page. Returns null if the page does not exist or is not referenced at all,
    123     * otherwise returns a collection containing page names (String) that refer to this one.
    124     * <p>
    125     * @param pagename The page to find referrers for.
    126     * @return A Set of Strings.  May return null, if the page does not exist, or if it has no references.
    127     */
    128    Set< String > findReferrers( String pagename );
    129
    130    /**
    131     *  Returns all pages that refer to this page.  Note that this method returns an unmodifiable Map, which may be abruptly changed.
    132     *  So any access to any iterator may result in a ConcurrentModificationException.
    133     *  <p>
    134     *  The advantages of using this method over findReferrers() is that it is very fast, as it does not create a new object.
    135     *  The disadvantages are that it does not do any mapping between plural names, and you may end up getting a
    136     *  ConcurrentModificationException.
    137     *
    138     * @param pageName Page name to query.
    139     * @return A Set of Strings containing the names of all the pages that refer to this page.  May return null, if the page does
    140     *         not exist or has not been indexed yet.
    141     * @since 2.2.33
    142     */
    143    Set< String > findReferredBy( String pageName );
    144
    145    /**
    146     *  Returns all pages that this page refers to.  You can use this as a quick way of getting the links from a page, but note
    147     *  that it does not link any InterWiki, image, or external links.  It does contain attachments, though.
    148     *  <p>
    149     *  The Collection returned is unmutable, so you cannot change it.  It does reflect the current status and thus is a live
    150     *  object.  So, if you are using any kind of an iterator on it, be prepared for ConcurrentModificationExceptions.
    151     *  <p>
    152     *  The returned value is a Collection, because a page may refer to another page multiple times.
    153     *
    154     * @param pageName Page name to query
    155     * @return A Collection of Strings containing the names of the pages that this page refers to. May return null, if the page
    156     *         does not exist or has not been indexed yet.
    157     * @since 2.2.33
    158     */
    159    Collection< String > findRefersTo( String pageName );
    160
    161    /**
    162     *  Returns a list of all pages that the ReferenceManager knows about. This should be roughly equivalent to
    163     *  PageManager.getAllPages(), but without the potential disk access overhead.  Note that this method is not guaranteed
    164     *  to return a Set of really all pages (especially during startup), but it is very fast.
    165     *
    166     *  @return A Set of all defined page names that ReferenceManager knows about.
    167     *  @since 2.3.24
    168     */
    169    Set< String > findCreated();
    170
    171}