org.ceryle.wiki.plugin.assertion
Class WikiMapManager

java.lang.Object
  org.ceryle.wiki.plugin.assertion.AssertionHandlerImpl
      org.ceryle.wiki.plugin.assertion.WikiMapManager

All Implemented Interfaces:

AssertionHandler

public class WikiMapManager
extends AssertionHandlerImpl
implements AssertionHandler

Usurps the function of an existing AssertionHandler by first harvesting its Assertions, disabling it, and then managing further maintenance of a TopicMap that is then synchronized by the events provided from the WikiEventManager for a given WikiEngine. Whereas the AssertionHandler provided support for its getAssertion() method via an internal cache of Assertions, once the WikiMapManager has taken over those queries are made directly on its managed TopicMap.

The initial harvest that builds the TopicMap from the wiki is done by an AssertionHarvester, which is part of the bootstrap process initiated by substituteManager().

Post-harvest, the WikiMapManager has the responsibility of converting all Topic Map objects into wiki-compatible objects, basically Strings and Assertions. It does not return anything within the org.ceryle.tm.* package.

Notes

Basically, if there are any AssertionPlugins on the wiki, it's likely that the AssertionHandler's cache is close to being in sync. The WikiMapManager's task is to explicitly call the AssertionHandler, request an synchronization whilst supplying a listener for the end of that AssertionCrawler task. If the synchronizer comes back successfully, this then triggers the next stage of the process:

1. Call the AssertionHandler and explicitly request a synchronize(), supplying a listener for the end-of-task ActionEvent.
2. Upon receiving notification that the synchronize task is successfully completed, attach a listener to the WikiEventManager so that further events fired by changes to the wiki are caught by the WikiMapManager.
3. Disable the handler's listener.
4. Obtain the current Set of Assertions and then clear its caches.
5. Launch a separate Thread to begin building a TopicMap based on the Assertions in the cache (noting that new events/Assertions may be coming in all the time.

TM4J vs. TMAPI

This class began using native TM4J methods and was at one point being converted over to TMAPI, which was abandoned as the latter was not sufficient. Another issue is that the current Inference implementation is TM4J-based, so either a wrapper or alternative class needs to be written.

Note on Usurpation

The one thing we haven't figured yet is when to trigger the usurpation, i.e., when to call the substituteManager() method. Currently this is being done in a rather pipe cleaners-and-glue way, simply waiting ten seconds after the wiki has been started. Ideally this should come from a post-instantiation event.

Version:

$Id: WikiMapManager.java,v 1.3 2007-06-15 12:10:14 altheim Exp $

Author:

Murray Altheim

Field Summary

static String	PROPERTY_WIKI_TOPICMAP_PATH Ceryle property determining the location of the written XTM TopicMap.
static String	PROPERTY_WIKIMAP_ENABLED The System property name for the property enabling the usurpation of AssertionHandler by WikiMapManager.
static String	THREAD_GROUP_NAME The name of the ThreadGroup used by the WikiMapManager and any assertion-related Threads.
static String	TOPICMAP_CATALOG The filename of the TopicMap file meant to be loaded on wiki startup.

Fields inherited from class org.ceryle.wiki.plugin.assertion.AssertionHandlerImpl

ASSERTION_LIFESPAN, m_engine, m_listener, m_refip, templateName

Fields inherited from interface org.ceryle.wiki.plugin.assertion.AssertionHandler

SYNCHRONIZED, UNSYNCHRONIZED

Constructor Summary

WikiMapManager(AssertionHandler handler, TopicMapProcessor tmprocessor)
Constructor for a WikiMapManager for the provided AssertionHandler that will be replaced by this WikiMapManager.

Method Summary

Assertion	convertAssociation(Association association) Provided an Associations, returns its corresponding Assertion.
Collection	convertAssociations(Collection associations) Provided a Collection of Associations, returns a Collection of corresponding Assertions.
Assertion	createAssertion(String pagename, Term subject, Predicate predicate, Property property) Creates and returns a new property Assertion provided its parameters.
Assertion	createAssertion(String pagename, Term subject, Predicate predicate, Term object, boolean isTemplate) Creates and returns a new Assertion, also creating its backing Topic Map Association.
Assertion	getAssertion(String pagename, String subject, String predicate, String object) Queries the set of existing Assertions for an Assertion matching the provided Subject, Predicate and Object.
Assertion	getAssertion(String pagename, Term subject, Predicate predicate, Term object, boolean isTemplate, boolean create) Returns an Assertion having the wiki page name, Predicate and Terms.
int	getAssertionCount() Returns the count of all the Assertions.
Collection	getAssertions() Returns a Collection containing all the Assertions (including Assertion templates).
Collection	getAssertions(Collection associations) Returns the Collection of all Associations in the TopicMap having a Scope indicating that they are based on Assertions.
Collection	getAssertions(Collection associations, String pagename, String subject, String predicate, String object, int templateMode, int logicMode) Returns the Collection of all Associations matching Assertions having pagename, subject, predicate, and/or object as Strings.
Collection	getAssertionTemplates() Returns a Collection containing all the Assertion templates.
String	getBaseURI() Return the base URI of the generated TopicMap.
String	getLabelForPage(String pagename) A convenience method that returns a Topic-based label for the given page (referenced by name), returning the original pagename if the Topic does not provide an alternative.
String	getPageForTopic(Topic topic) A convenience method that "converts" the Topic topic to its wiki page name (returning its label).
Collection	getPredicatesOfType(Collection associations, Topic predicate) Returns a Set view of all the Associations in the TopicMap tm having a Scope indicating that they are based on Assertions.
Set	getSubclasses(String pagename) Returns the Set containing all subclasses of wiki page pagename, an empty Set if there are none.
Set	getSuperclasses(String pagename) Returns the Set containing all superclasses of wiki page pagename, an empty Set if there are none.
ThreadGroup	getThreadGroup() Returns the ThreadGroup used with the WikiMapManager and other assertion-related Threads (named "WikiMap").
Topic	getTopicByName(TopicMap tm, String label, boolean create, int errortype) Returns a Topic with a base name in the XTM 'Display' scope of label, returning null if unable to locate the Topic or an error occurs (in the latter case the error is logged).
TopicMap	getTopicMap() Returns the TopicMap created by the WikiMapManager for the WikiEngine as a TM4J TopicMap, null if the harvest process (that creates it) has not yet run.
TopicMapProcessor	getTopicMapProcessor() Return the TopicMapProcessor used by this WikiMapManager.
TopicNameIndex	getTopicNameIndex() Return the TopicNameIndex.
protected void	harvestComplete(AssertionHarvester harvester) Called by the AssertionHarvester upon completion.
protected void	harvestTopicMap() Upon receiving notification that the synchronization has successfully completed, begins the Rest of the Story.
boolean	hasAssertion(String pagename, String subject, String predicate, String object, int templateMode, int logicMode) Returns true if an Assertion equivalent to one created with the provided subject, predicate, and object is available.
boolean	isHarvested() Returns true if the map has been harvested.
boolean	removeAssertion(Assertion assertion) Returns true if the Assertion was successfully removed.
void	setTopicMapPath(File file) Sets the path to file for the written XTM TopicMap.
void	substituteManager() Begins the substitution process by replace the existing handler with this manager, disabling its listener and enabling the our own synchronize the existing AssertionHandler's caches, attaching a listener so that upon completion of the synchronization, begin harvesting the assertions into a Topic Map The actual substitution occurs after the synchronization thread has finished, by the harvestTopicMap() method.
void	synchronize(String pagename, ActionListener listener) Synchronizes the AssertionHandler's registry with the current set of wiki pages.
String	toXHTML(WikiContext context, Assertion assertion) Overrides the method in AssertionHandlerImpl, substituting Topic names where available, formatting the assertion into XHTML output suitable for display on the page.

Methods inherited from class org.ceryle.wiki.plugin.assertion.AssertionHandlerImpl

clearRegistry, disableRegistry, getAssertion, getEngine, getFromRegistry, getReferenceInfoProvider, hasAssertion, isListenerEnabled, isSynchronizing, removeFromPageCache, setListenerEnabled, setRegistryIsChanging, setSynchronizing, updateCacheForPage

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.ceryle.wiki.plugin.assertion.AssertionHandler

getAssertion, getEngine, getReferenceInfoProvider, hasAssertion, isListenerEnabled, setListenerEnabled

Field Detail

PROPERTY_WIKIMAP_ENABLED

public static final String PROPERTY_WIKIMAP_ENABLED

The System property name for the property enabling the usurpation of AssertionHandler by WikiMapManager. The value is "ceryle.wikimapmanager.enabled".

See Also:

Constant Field Values

PROPERTY_WIKI_TOPICMAP_PATH

public static final String PROPERTY_WIKI_TOPICMAP_PATH

Ceryle property determining the location of the written XTM TopicMap. The value is "http://purl.org/ceryle/wiki/topicmap-path".

See Also:

Constant Field Values

THREAD_GROUP_NAME

public static final String THREAD_GROUP_NAME

The name of the ThreadGroup used by the WikiMapManager and any assertion-related Threads. The value is "WikiMap".

See Also:

Constant Field Values

TOPICMAP_CATALOG

public static final String TOPICMAP_CATALOG

The filename of the TopicMap file meant to be loaded on wiki startup. This is generally a simple LTM file containing #MERGEMAP directives for any additional LTM or XTM files to be loaded. The filepath is $WIKI_HOME/tm/"catalog.ltm".

See Also:

Constant Field Values

Constructor Detail

WikiMapManager

public WikiMapManager(AssertionHandler handler,
                      TopicMapProcessor tmprocessor)

Constructor for a WikiMapManager for the provided AssertionHandler that will be replaced by this WikiMapManager. The WikiEngine reference will be supplied by the AssertionHandler.

Parameters:

handler - the AssertionHandler to be replaced by this WikiMapManager.

tmprocessor - the TopicMapProcessor used.

Throws:

IllegalArgumentException - if the AssertionHandler parameter is actually a WikiMapManager.

WikiMapException - if unable to create the manager.

Method Detail

synchronize

public void synchronize(String pagename,
                        ActionListener listener)

Synchronizes the AssertionHandler's registry with the current set of wiki pages.

This is an AssertionHandler API method.

Specified by:

synchronize in interface AssertionHandler

Overrides:

synchronize in class AssertionHandlerImpl

Parameters:

pagename - the optional name of the wiki page that fired the event triggering synchronization, used to check for page-specific changes.

listener - the optional listener may be used to receive notification (via an ActionEvent fired by the AssertionCrawler) that the synchronization process has finished.

Throws:

IllegalStateException - if this method is called, as it is only to override and disable the superclass' method.

getAssertions

public Collection getAssertions()
                         throws AssertionException

Returns a Collection containing all the Assertions (including Assertion templates). This is expensive and could use caching or optimization. This returns an empty Set (logging the error) rather than throwing an exception.

This is an AssertionHandler API method.

Specified by:

getAssertions in interface AssertionHandler

Overrides:

getAssertions in class AssertionHandlerImpl

Throws:

AssertionException - if an error occurs while creating the Collection of assertions.

getAssertionTemplates

public Collection getAssertionTemplates()
                                 throws AssertionException

Returns a Collection containing all the Assertion templates. This is expensive and could use caching or optimization. This returns an empty Set (logging the error) rather than throwing an exception.

This is not an AssertionHandler API method.

Throws:

AssertionException

isHarvested

public boolean isHarvested()

Returns true if the map has been harvested.

getAssertion

public Assertion getAssertion(String pagename,
                              Term subject,
                              Predicate predicate,
                              Term object,
                              boolean isTemplate,
                              boolean create)
                       throws AssertionException

Returns an Assertion having the wiki page name, Predicate and Terms. If a registry is being maintained, this should return the existing Assertion if one matching exists. If create is false, null is returned when no match is found; this can be used as a surrogate for a hasAssertion() method. Note that this does not return Assertion templates.

This is an AssertionHandler API method.

Specified by:

getAssertion in interface AssertionHandler

Overrides:

getAssertion in class AssertionHandlerImpl

Parameters:

pagename - the wiki page name source of the Assertion

subject - the subject Term of the Assertion

predicate - the Predicate of the Assertion

object - the subject Term of the Assertion

isTemplate - when true, queries for an assertion template

create - when true, permits creation of Assertion to fulfill a match

Returns:

a new or existing Assertion, depending on the value of create

Throws:

AssertionException - if an error occurs while creating the new Assertion

createAssertion

public Assertion createAssertion(String pagename,
                                 Term subject,
                                 Predicate predicate,
                                 Term object,
                                 boolean isTemplate)
                          throws AssertionException

Creates and returns a new Assertion, also creating its backing Topic Map Association.

NOTE: while this is a public method by virtue of it being part of the API, it should not be called directly since creation of Assertions is meant to be handled internal to the process.

Specified by:

createAssertion in interface AssertionHandler

Overrides:

createAssertion in class AssertionHandlerImpl

Parameters:

pagename - the wiki page source of the Assertion

subject - the subject Term of the Assertion

predicate - the Predicate of the Assertion

object - the subject Term of the Assertion

isTemplate - if true, the assertion is created as an assertion template.

Throws:

AssertionException - if unable to create the new Assertion.

See Also:

to create an assertion or assertion template, to create a property assertion

createAssertion

public Assertion createAssertion(String pagename,
                                 Term subject,
                                 Predicate predicate,
                                 Property property)
                          throws AssertionException

Creates and returns a new property Assertion provided its parameters.

NOTE: while this is a public method by virtue of it being part of the API, it should not be called directly since creation of Assertions is meant to be handled internal to the process.

Specified by:

createAssertion in interface AssertionHandler

Overrides:

createAssertion in class AssertionHandlerImpl

Parameters:

pagename - the wiki page source of the Assertion

subject - the subject Term of the Assertion

predicate - the Predicate of the Assertion

property - the Property being asserted.

Throws:

AssertionException - if unable to create the new Assertion.

See Also:

to create an assertion or assertion template

convertAssociation

public Assertion convertAssociation(Association association)
                             throws AssertionException

Provided an Associations, returns its corresponding Assertion. This does assume that the Association is typed correctly and suitable for conversion; if it's not will return null.

Throws:

AssertionException - if an error occurs during conversion

IllegalStateException - if this method is called prior to creation of the TopicMap

convertAssociations

public Collection convertAssociations(Collection associations)
                               throws AssertionException

Provided a Collection of Associations, returns a Collection of corresponding Assertions. This does assume that the Associations are typed correctly and suitable for conversion; those that aren't are simply not included in the result.

Throws:

IllegalStateException - if this method is called prior to creation of the TopicMap

AssertionException

getAssertion

public Assertion getAssertion(String pagename,
                              String subject,
                              String predicate,
                              String object)
                       throws AssertionException

Queries the set of existing Assertions for an Assertion matching the provided Subject, Predicate and Object. Returns null if unable to locate a matching Assertion. Note that the page name is optional; the query only includes (i.e., requires a match on) page name if the parameter is non-null.

Specified by:

getAssertion in interface AssertionHandler

Overrides:

getAssertion in class AssertionHandlerImpl

Parameters:

pagename - the wiki page name source of the Assertion

subject - the wiki page name of the Assertion's subject

predicate - the wiki page name of the Assertion's predicate

object - the wiki page name of the Assertion's object

Throws:

AssertionException

hasAssertion

public boolean hasAssertion(String pagename,
                            String subject,
                            String predicate,
                            String object,
                            int templateMode,
                            int logicMode)
                     throws AssertionException

Returns true if an Assertion equivalent to one created with the provided subject, predicate, and object is available. The pagename parameter is optional; it is only used as an additional query filter if provided.

This is an AssertionHandler API method.

Parameters:

pagename - the wiki page source of the Assertion

subject - the wiki page name of the Assertion's subject

predicate - the wiki page name of the Assertion's predicate

object - the wiki page name of the Assertion's object

templateMode - assertions or templates or both, as AssertionQuery.TEMPLATES_EXCLUDE, AssertionQuery.TEMPLATES_ONLY, or AssertionQuery.TEMPLATES_INCLUDE.

logicMode - the query is done as AssertionQuery.LOGICAL_ALL, AssertionQuery.LOGICAL_AND, or AssertionQuery.LOGICAL_OR.

Returns:

true if a matching Assertion already exists.

Throws:

AssertionException

removeAssertion

public boolean removeAssertion(Assertion assertion)

Returns true if the Assertion was successfully removed. This performs any necessary update processes.

This is an AssertionHandler API method.

Specified by:

removeAssertion in interface AssertionHandler

Overrides:

removeAssertion in class AssertionHandlerImpl

Parameters:

assertion - the Assertion to be removed.

Throws:

IllegalStateException - if this method is called prior to creation of the TopicMap

toXHTML

public String toXHTML(WikiContext context,
                      Assertion assertion)
               throws AssertionException

Overrides the method in AssertionHandlerImpl, substituting Topic names where available, formatting the assertion into XHTML output suitable for display on the page. The Terms are displayed square-bracketed; the Predicate not.

If the TopicMap is available it will be used to query for Topic labels for subject, predicate and object.

This is an AssertionHandler API method.

Specified by:

toXHTML in interface AssertionHandler

Overrides:

toXHTML in class AssertionHandlerImpl

Parameters:

context - optional; if supplied, used to provide link markup.

assertion - the Assertion to be displayed.

Returns:

an XHTML compliant HTML fragment, all tags to be closed and balanced.

Throws:

AssertionException

getAssertionCount

public int getAssertionCount()
                      throws AssertionException

Returns the count of all the Assertions.

This is not an AssertionHandler API method.

Throws:

AssertionException

getThreadGroup

public ThreadGroup getThreadGroup()

Returns the ThreadGroup used with the WikiMapManager and other assertion-related Threads (named "WikiMap").

getTopicMapProcessor

public TopicMapProcessor getTopicMapProcessor()

Return the TopicMapProcessor used by this WikiMapManager.

substituteManager

public void substituteManager()

Begins the substitution process by

1. replace the existing handler with this manager, disabling its listener and enabling the our own
2. synchronize the existing AssertionHandler's caches, attaching a listener so that upon completion of the synchronization,
3. begin harvesting the assertions into a Topic Map

The actual substitution occurs after the synchronization thread has finished, by the harvestTopicMap() method.

If the harvest has already occurred, this method does nothing.

harvestTopicMap

protected void harvestTopicMap()

Upon receiving notification that the synchronization has successfully completed, begins the Rest of the Story. The Rest of the Story involves taking the initial TM4J TopicMap and obtaining its wrapped TMAPI version so that the rest of the class can use TMAPI objects instead of native TM4J ones.

If the harvest has already occurred, this method does nothing.

harvestComplete

protected void harvestComplete(AssertionHarvester harvester)

Called by the AssertionHarvester upon completion. This also writes the TOpicMap to an accessible location on the server.

getBaseURI

public String getBaseURI()

Return the base URI of the generated TopicMap.

getAssertions

public Collection getAssertions(Collection associations)

Returns the Collection of all Associations in the TopicMap having a Scope indicating that they are based on Assertions. If the parameter is null, the source to the filter is all the Collections in the TopicMap.

Parameters:

associations - the beginning Collection to query; if null, the entire TopicMap

Throws:

IllegalStateException - if this method is called prior to creation of the TopicMap

getAssertions

public Collection getAssertions(Collection associations,
                                String pagename,
                                String subject,
                                String predicate,
                                String object,
                                int templateMode,
                                int logicMode)
                         throws AssertionException

Returns the Collection of all Associations matching Assertions having pagename, subject, predicate, and/or object as Strings. If there are no filter values, all Associations derived from Assertions are returned.

NOTE: Despite a similar signature to the method in AssertionHandlerImpl, this is not an API method and queries the Topic Map, returning associations rather than Assertions. If you want Assertions, pass the result through #WikiMapManager#convertAssociations(Collection).

See org.ceryle.wiki.plugin.assertion.AssertionQuery for a description of the permitted values for the template and logical mode.

Null values are ignored; the String array must either be null or contain exactly three elements (any or all of which can be null).

NOTE: Despite a similar signature (the difference being the type of content in the Collection) to the method in AssertionHandlerImpl, this is not an API method and queries the WikiMapManager's Topic Map, returning Associations rather than Assertions as in the AssertionHandlerImpl.

See org.ceryle.wiki.plugin.assertion.AssertionQuery for a description of the permitted values for the template and logical mode. Null values are ignored.

Overrides:

getAssertions in class AssertionHandlerImpl

Parameters:

associations - the beginning Collection of Topic Map Associations to query; if null, the entire TopicMap is queried

pagename - the name of the wiki page where the assertion was made

subject - the WikiName identifier for the subject of the query

predicate - the WikiName identifier for the predicate of the query

object - the WikiName identifier for the object of the query

templateMode - assertions or templates or both, as AssertionQuery.TEMPLATES_EXCLUDE, AssertionQuery.TEMPLATES_ONLY, or AssertionQuery.TEMPLATES_INCLUDE.

logicMode - the query is done as AssertionQuery.LOGICAL_ALL, AssertionQuery.LOGICAL_AND, or AssertionQuery.LOGICAL_OR.

Throws:

IllegalStateException - if this method is called prior to creation of the TopicMap

AssertionException - if an error occurs during the query

getPredicatesOfType

public Collection getPredicatesOfType(Collection associations,
                                      Topic predicate)

Returns a Set view of all the Associations in the TopicMap tm having a Scope indicating that they are based on Assertions. The optional Topic type serves as a filter on the result: if non-null the resulting Collection will contain only those Associations having that type.

Throws:

IllegalStateException - if this method is called prior to creation of the TopicMap

getTopicByName

public Topic getTopicByName(TopicMap tm,
                            String label,
                            boolean create,
                            int errortype)
                     throws AssertionException

Returns a Topic with a base name in the XTM 'Display' scope of label, returning null if unable to locate the Topic or an error occurs (in the latter case the error is logged).

Parameters:

tm - the parent TopicMap

label - the label of the returned Topic

create - if true and the Topic is not found, will create

errortype - the AssertionException error type

Throws:

IllegalStateException - if this method is called prior to creation of the TopicMap

AssertionException

getSuperclasses

public Set getSuperclasses(String pagename)

Returns the Set containing all superclasses of wiki page pagename, an empty Set if there are none. The values are returned as Strings.

getSubclasses

public Set getSubclasses(String pagename)

Returns the Set containing all subclasses of wiki page pagename, an empty Set if there are none. The values are returned as Strings.

getLabelForPage

public String getLabelForPage(String pagename)

A convenience method that returns a Topic-based label for the given page (referenced by name), returning the original pagename if the Topic does not provide an alternative. This throws no exceptions, returning the original pagename if unsuccessful in obtaining a Topic label.

Throws:

IllegalStateException - if this method is called prior to creation of the TopicMap

getPageForTopic

public String getPageForTopic(Topic topic)

A convenience method that "converts" the Topic topic to its wiki page name (returning its label). This does not pay attention to whether or not the page actually exists.

Throws:

IllegalStateException - if this method is called prior to creation of the TopicMap

getTopicMap

public TopicMap getTopicMap()

Returns the TopicMap created by the WikiMapManager for the WikiEngine as a TM4J TopicMap, null if the harvest process (that creates it) has not yet run.

getTopicNameIndex

public TopicNameIndex getTopicNameIndex()

Return the TopicNameIndex.

setTopicMapPath

public void setTopicMapPath(File file)

Sets the path to file for the written XTM TopicMap. If not set, no file will be written.