Package org.apache.wiki.references

# Class DefaultReferenceManager

java.lang.Object
org.apache.wiki.api.filters.BasePageFilter
org.apache.wiki.references.DefaultReferenceManager

All Implemented Interfaces:
  `Serializable`, `EventListener`, `org.apache.wiki.api.filters.PageFilter`, `org.apache.wiki.event.WikiEventListener`, `InternalModule`, `ReferenceManager`

public class DefaultReferenceManager extends org.apache.wiki.api.filters.BasePageFilter implements ReferenceManager, Serializable
Keeps track of wikipage references:

- What pages a given page refers to
- What pages refer to a given page

This is a quick'n'dirty approach without any finesse in storage and searching algorithms; we trust java.util.*.

This class contains two HashMaps, m_refersTo and m_referredBy. The first is indexed by WikiPage names and contains a Collection of all WikiPages the page refers to. (Multiple references are not counted, naturally.) The second is indexed by WikiPage names and contains a Set of all pages that refer to the indexing page. (Notice - the keys of both Maps should be kept in sync.)

When a page is added or edited, its references are parsed, a Collection is received, and we crudely replace anything previous with this new Collection. We then check each referenced page name and make sure they know they are referred to by the new page.

Based on this information, we can perform non-optimal searches for e.g. unreferenced pages, top ten lists, etc.

The owning class must take responsibility of filling in any pre-existing information, probably by loading each and every WikiPage and calling this class to update the references when created.

Since:
  1.6.1 (as of 2.11.0, moved to org.apache.wiki.references)
See Also:
  - Serialized Form

## Field Summary

### Fields inherited from class org.apache.wiki.api.filters.BasePageFilter

`m_engine`

## Constructor Summary

Constructors
Constructor
Description
`DefaultReferenceManager(org.apache.wiki.api.core.Engine engine)`
Builds a new ReferenceManager.

## Method Summary

Modifier and Type
Method
Description
`void`
`actionPerformed(org.apache.wiki.event.WikiEvent event)`
`void`
`clearPageEntries(String pagename)`
Clears the references to a certain page, so it's no longer in the map.
`int`
`deepHashCode()`
This 'deepHashCode' can be used to determine if there were any modifications made to the underlying to and by maps of the ReferenceManager.
`Set<String>`
`findCreated()`
Returns a list of all pages that the ReferenceManager knows about.
`Set<String>`
`findReferredBy(String pageName)`
Returns all pages that refer to this page.
`Set<String>`
`findReferrers(String pagename)`
Find all pages that refer to this page.
`Collection<String>`
`findRefersTo(String pageName)`
Returns all pages that this page refers to.
`Collection<String>`
`findUncreated()`
Finds all references to non-existant pages.
`Collection<String>`
`findUnreferenced()`
Finds all unreferenced pages.
`protected Map<String,Set<String>>`
`getReferredBy()`
Returns the referred-by list.
`protected Map<String,Collection<String>>`
`getRefersTo()`
Returns the refers-to list.
`void`
`initialize(Collection<org.apache.wiki.api.core.Page> pages)`
Initializes the entire reference manager with the initial set of pages from the collection.
`void`
`pageRemoved(org.apache.wiki.api.core.Page page)`
Updates the m_referedTo and m_referredBy hashmaps when a page has been deleted.
`void`
`postSave(org.apache.wiki.api.core.Context context, String content)`
After the page has been saved, updates the reference lists.
`Collection<String>`
`scanWikiLinks(org.apache.wiki.api.core.Page page, String pagedata)`
Reads a WikiPageful of data from a String and returns all links internal to this Wiki in a Collection.
`void`
`updateReferences(String page, Collection<String> references)`
Updates the referred pages of a new or edited WikiPage.
`void`
`updateReferences(org.apache.wiki.api.core.Page page)`
Updates all references for the given page.

### Methods inherited from class org.apache.wiki.api.filters.BasePageFilter

`initialize`

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Methods inherited from interface org.apache.wiki.api.filters.PageFilter

`destroy, initialize, postTranslate, preSave, preTranslate`

## Constructor Details

### DefaultReferenceManager

public DefaultReferenceManager(org.apache.wiki.api.core.Engine engine)
Builds a new ReferenceManager.

Parameters:
  `engine` - The Engine to which this is managing references to.

## Method Details

### initialize

public void initialize(Collection<org.apache.wiki.api.core.Page> pages) throws org.apache.wiki.api.exceptions.ProviderException
Initializes the entire reference manager with the initial set of pages from the collection.

Specified by:
  `initialize` in interface `ReferenceManager`
Parameters:
  `pages` - A collection of all pages you want to be included in the reference count.
Throws:
  `org.apache.wiki.api.exceptions.ProviderException` - If reading of pages fails.
Since:
  2.2

### postSave

public void postSave(org.apache.wiki.api.core.Context context, String content)
After the page has been saved, updates the reference lists.

Specified by:
  `postSave` in interface `org.apache.wiki.api.filters.PageFilter`
Parameters:
  `context` -
  `content` -

### scanWikiLinks

public Collection<String> scanWikiLinks(org.apache.wiki.api.core.Page page, String pagedata)
Reads a WikiPageful of data from a String and returns all links internal to this Wiki in a Collection.

Specified by:
  `scanWikiLinks` in interface `ReferenceManager`
Parameters:
  `page` - The WikiPage to scan
  `pagedata` - The page contents
Returns:
  a Collection of Strings

### pageRemoved

public void pageRemoved(org.apache.wiki.api.core.Page page)
Updates the m_referedTo and m_referredBy hashmaps when a page has been deleted.

Within the m_refersTo map the pagename is a key. The whole key-value-set has to be removed to keep the map clean. Within the m_referredBy map the name is stored as a value. Since a key can have more than one value we have to delete just the key-value-pair referring page:deleted page.

Specified by:
  `pageRemoved` in interface `ReferenceManager`
Parameters:
  `page` - Name of the page to remove from the maps.

### updateReferences

public void updateReferences(org.apache.wiki.api.core.Page page)
Updates all references for the given page.

Specified by:
  `updateReferences` in interface `ReferenceManager`
Parameters:
  `page` - wiki page for which references should be updated

### updateReferences

public void updateReferences(String page, Collection<String> references)
Updates the referred pages of a new or edited WikiPage. If a refersTo entry for this page already exists, it is removed and a new one is built from scratch. Also calls updateReferredBy() for each referenced page.

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 referred pages of the references. Use this method during run-time.

Specified by:
  `updateReferences` in interface `ReferenceManager`
Parameters:
  `page` - Name of the page to update.
  `references` - A Collection of Strings, each one pointing to a page this page references.

### getRefersTo

protected Map<String,Collection<String>> getRefersTo()
Returns the refers-to list. For debugging.

Returns:
  The refers-to list.

### getReferredBy

protected Map<String,Set<String>> getReferredBy()
Returns the referred-by list. For debugging.

Returns:
  Referred-by lists.

### clearPageEntries

public void clearPageEntries(String pagename)
Clears the references to a certain page, so it's no longer in the map.

Specified by:
  `clearPageEntries` in interface `ReferenceManager`
Parameters:
  `pagename` - Name of the page to clear references for.

### findUnreferenced

public Collection<String> findUnreferenced()
Finds all unreferenced pages. This requires a linear scan through m_referredBy to locate keys with null or empty values.

Specified by:
  `findUnreferenced` in interface `ReferenceManager`
Returns:
  The Collection of Strings

### findUncreated

public Collection<String> findUncreated()
Finds all references to non-existant pages. This requires a linear scan through m_refersTo values; each value must have a corresponding key entry in the reference Maps, otherwise such a page has never been created.

Returns a Collection containing Strings of unreferenced page names. Each non-existant page name is shown only once - we don't return information on who referred to it.

Specified by:
  `findUncreated` in interface `ReferenceManager`
Returns:
  A Collection of Strings

### findReferrers

public Set<String> findReferrers(String pagename)
Find all pages that refer to this page. Returns null if the page does not exist or is not referenced at all, otherwise returns a collection containing page names (String) that refer to this one.

Specified by:
  `findReferrers` in interface `ReferenceManager`
Parameters:
  `pagename` - The page to find referrers for.
Returns:
  A Set of Strings. May return null, if the page does not exist, or if it has no references.

### findReferredBy

public Set<String> findReferredBy(String pageName)
Returns all pages that refer to this page. Note that this method returns an unmodifiable Map, which may be abruptly changed. So any access to any iterator may result in a ConcurrentModificationException.

The advantages of using this method over findReferrers() is that it is very fast, as it does not create a new object. The disadvantages are that it does not do any mapping between plural names, and you may end up getting a ConcurrentModificationException.

Specified by:
  `findReferredBy` in interface `ReferenceManager`
Parameters:
  `pageName` - Page name to query.
Returns:
  A Set of Strings containing the names of all the pages that refer to this page. May return null, if the page does not exist or has not been indexed yet.
Since:
  2.2.33

### findRefersTo

public Collection<String> findRefersTo(String pageName)
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 that it does not link any InterWiki, image, or external links. It does contain attachments, though.

The Collection returned is unmutable, so you cannot change it. It does reflect the current status and thus is a live object. So, if you are using any kind of an iterator on it, be prepared for ConcurrentModificationExceptions.

The returned value is a Collection, because a page may refer to another page multiple times.

Specified by:
  `findRefersTo` in interface `ReferenceManager`
Parameters:
  `pageName` - Page name to query
Returns:
  A Collection of Strings containing the names of the pages that this page refers to. May return null, if the page does not exist or has not been indexed yet.
Since:
  2.2.33

### deepHashCode

public int deepHashCode()
This 'deepHashCode' can be used to determine if there were any modifications made to the underlying to and by maps of the ReferenceManager. The maps of the ReferenceManager are not synchronized, so someone could add/remove entries in them while the hashCode is being computed. This method traps and retries if a concurrent modification occurs.

Returns:
  Sum of the hashCodes for the to and by maps of the ReferenceManager
Since:
  2.3.24

### findCreated

public Set<String> findCreated()
Returns a list of all pages that the ReferenceManager knows about. This should be roughly equivalent to PageManager.getAllPages(), but without the potential disk access overhead. Note that this method is not guaranteed to return a Set of really all pages (especially during startup), but it is very fast.

Specified by:
  `findCreated` in interface `ReferenceManager`
Returns:
  A Set of all defined page names that ReferenceManager knows about.
Since:
  2.3.24

### actionPerformed

public void actionPerformed(org.apache.wiki.event.WikiEvent event)

Specified by:
  `actionPerformed` in interface `org.apache.wiki.event.WikiEventListener`