org.ceryle.wiki.plugin.assertion
Class AssertionHandlerImpl

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

All Implemented Interfaces:

AssertionHandler

Direct Known Subclasses:

WikiMapManager

public class AssertionHandlerImpl
extends Object
implements AssertionHandler

As a per-WikiEngine class, AssertionHandlers create Assertions, and receive and process AssertionEvents fired by AssertionPlugins. Methods of this class perform any necessary update processes to the registry. Note that the listener is enabled not by default; it must be enabled by calling setListenerEnabled(boolean).

Assertion Creation

Assertions are meant to be created from the AssertionHandler#getAssertion(String,Term,Predicate,Term,boolean) method in this handler (and those that aren't will be ignored by the rest of the processing machinery), as methods in this class keep duplicate wiki syntax declarations from repeatedly creating the same Assertion.

Duplicate Assertions

Because it's possible to declare the same Assertion from any number of wiki source pages, when a wiki page is modified or deleted it's necessary to see if any of the previously-unused Assertions (i.e., unused because they were at the time of creation a duplicate) might now be usable. So upon any any page modification, the cache of unused assertions is checked, first removing any from that cache that match the modified or deleted page.

Notes

WikiPage/Assertion Relationship

Any given WikiPage may contain zero or more Assertions. While these Assertions occur on that page, they may not necessarily be Assertions that have any specific relationship to the WikiPage itself. But for maintenance purposes it's important that the WikiPage contains references to all of its Assertions (stored within a HashSet in a page attribute), and each Assertion stores the name of its parent WikiPage.

Assertion Deletions

As changes to the wiki occur, events are fired so that the AssertionHandler for the WikiEngine can keep track of additions, changes, and deletions of Assertions as they occur. Because the wiki can be edited simultaneously by multiple users (though in theory only one person is editing a page at any given time, these events will be coming in from different pages all potentially containing Assertions that don't even (again, necessarily) have any relation to the pages. Additions and changes are not too difficult, as we know the source WikiPage and can simply add or compare them (resp.) with the existing set for the page. Deletions are a bit more difficult, as the Assertions for a page arrive as asynchronous events. The solution would be either:

1. Capture the beginning and ending page edit events and encapsulate the the editing session accordingly, removing any Assertions that weren't made within that period. This is a fairly complicated approach.
2. When an Assertion arrives for a WikiPage, remove all Assertions for that WikiPage older than a certain period of time, as being of a different editing session. This is the simpler but riskier approach.

What we actually do is somewhat of a combination, and we avoid having to encapsulate the session. When the end-edit event for a page editing session shows up we check all the Assertions for that page and see if any are older than the threshold set by the value of ASSERTION_LIFESPAN. This is a long value representing the number of milliseconds before an Assertion is considered "old" and likely to be from a previous editing session. This really only has to be the maximum amount of time between the first and last Assertion events occurring for a given page scan. The default value is a conservative 10,000 (10 sec).

IMPORTANT:

We've concentrated our efforts on getting the post-harvest processing in order, such that the WikiMapManager may handle changes to the wiki that aren't yet supported in the AssertionHandlerImpl (such as assertion additions, changes, deletions). At some point in the future there might be some time to go back and get this functionality to work in the pre-harvest world, but it's not really a priority — the real functionality is meant to happen post-harvest, once the Topic Map is made available.

AssertionHandler Listener Modes

The AssertionHandler provides a registry of Assertions in order to keep from recreating them repeatedly, and also to catalog the entire set initially. Once they have been harvested by the WikiMapManager and the handler has had its listener and registry disabled, it stops storing in its registry and simply responds with a newly-created Assertion on each request.

See Also:

WikiEvent, WikiPageEvent, WikiEventListener, Assertion, AssertionEvent

Field Summary

static long	ASSERTION_LIFESPAN The value of the assertion lifespan in milliseconds.
protected static org.apache.log4j.Logger	log
protected WikiEngine	m_engine
protected WikiEventListener	m_listener
protected ReferenceInfoProvider	m_refip
static String	templateName The name of the wiki page describing assertion templates.

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

SYNCHRONIZED, UNSYNCHRONIZED

Constructor Summary

protected

AssertionHandlerImpl(WikiEngine engine) Create an AssertionHandler for the provided WikiEngine.

Method Summary

protected void	clearRegistry() Clear the registry and page cache.
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 provided its parameters.
protected void	disableRegistry() Disables further use of the registry and page cache.
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, Property property, boolean create) Returns an Assertion having the wiki page name, Predicate and Property.
Assertion	getAssertion(String pagename, Term subject, Predicate predicate, Term object, boolean isTemplate, boolean create) Returns an Assertion from the registry having the same page name, Predicate and Terms if it has already been registered, null if it is not in the registry or was not added.
Collection	getAssertions() Returns a Collection containing all the Assertions in the registry.
Collection	getAssertions(Collection assertions, String pagename, String subject, String predicate, String object, int templateMode, int logicMode) Returns the Collection of all Assertions matching any of the optional parameters: pagename, subject, predicate, and/or object as Strings.
WikiEngine	getEngine() Returns the WikiEngine associated with this AssertionHandler.
protected Assertion	getFromRegistry(String signature) Returns true if the cache contains the Assertion indicated by the provided signature.
ReferenceInfoProvider	getReferenceInfoProvider() Returns the ReferenceInfoProvider associated with this AssertionHandler.
boolean	hasAssertion(String pagename, String subject, String predicate, String object) Returns true if an Assertion equivalent to one created with the provided subject, predicate, and object is contained in the registry.
boolean	isListenerEnabled() Returns the enabled state of this AssertionHandler's WikiEventListener.
protected boolean	isSynchronizing()
boolean	removeAssertion(Assertion assertion) Returns true if the Assertion was removed from the registry.
protected boolean	removeFromPageCache(String pagename)
void	setListenerEnabled(boolean enable) Enables or disables this AssertionHandler's WikiEventListener so that it tracks or no longer tracks changes to the wiki.
protected void	setRegistryIsChanging(boolean changing)
protected void	setSynchronizing(boolean sync)
void	synchronize(String pagename, ActionListener listener) Checks to see that the map of plugin-to-page for the entire wiki is up to date, and if not, fires up an AssertionCrawler thread to handle it.
String	toXHTML(WikiContext context, Assertion assertion) Format the assertion into XHTML output suitable for display on a web page.
protected void	updateCacheForPage(String pagename) Update the WikiPage's internally-stored attribute containing its Assertions, and add the page to the internal cache.

Methods inherited from class java.lang.Object

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

Field Detail

log

protected static org.apache.log4j.Logger log

ASSERTION_LIFESPAN

public static long ASSERTION_LIFESPAN

The value of the assertion lifespan in milliseconds. The default value is 10,000 (10 sec).

templateName

public static String templateName

The name of the wiki page describing assertion templates. The default value is "Template".

m_listener

protected WikiEventListener m_listener

m_engine

protected WikiEngine m_engine

m_refip

protected ReferenceInfoProvider m_refip

Constructor Detail

AssertionHandlerImpl

protected AssertionHandlerImpl(WikiEngine engine)

Create an AssertionHandler for the provided WikiEngine.

Parameters:

engine - the WikiEngine backing the event handling.

Method Detail

synchronize

public void synchronize(String pagename,
                        ActionListener listener)

Checks to see that the map of plugin-to-page for the entire wiki is up to date, and if not, fires up an AssertionCrawler thread to handle it. The AssertionCrawler automatically removes the listener following successful synchronization.

This is an AssertionHandler API method.

Note: If the listener is disabled, this method does nothing.

Specified by:

synchronize in interface AssertionHandler

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.

getEngine

public WikiEngine getEngine()

Returns the WikiEngine associated with this AssertionHandler.

This is an AssertionHandler API method.

Specified by:

getEngine in interface AssertionHandler

getReferenceInfoProvider

public ReferenceInfoProvider getReferenceInfoProvider()

Returns the ReferenceInfoProvider associated with this AssertionHandler.

This is an AssertionHandler API method.

Specified by:

getReferenceInfoProvider in interface AssertionHandler

setListenerEnabled

public void setListenerEnabled(boolean enable)

Enables or disables this AssertionHandler's WikiEventListener so that it tracks or no longer tracks changes to the wiki.

The listener is created upon class instantiation, and removed from the WikiEventManager and destroyed when this method is called with a parameter value of false.

This is an AssertionHandler API method.

Specified by:

setListenerEnabled in interface AssertionHandler

isListenerEnabled

public boolean isListenerEnabled()

Returns the enabled state of this AssertionHandler's WikiEventListener. If the listener is disabled, the internal registry should be considered invalid.

This is an AssertionHandler API method.

Specified by:

isListenerEnabled in interface AssertionHandler

getAssertions

public Collection getAssertions()
                         throws AssertionException

Returns a Collection containing all the Assertions in the registry. The Collection should be considered unmodifiable, i.e., modifications may throw an ConcurrentModificationException or UnsupportedOperationException. This returns an empty Set rather than null, until the registry is disabled (after which null).

This is an AssertionHandler API method.

Specified by:

getAssertions in interface AssertionHandler

Throws:

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

getAssertion

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

Returns an Assertion from the registry having the same page name, Predicate and Terms if it has already been registered, null if it is not in the registry or was not added. If create is true, a new Assertion will be created and registered if not found in the registry. If not found and the value is false, null is returned.

Note: This is the only way to add an Assertion to the registry; there is no addAssertion() method. This keeps any Assertions not created by the AssertionHandler from entering into the system.

This is an AssertionHandler API method.

Specified by:

getAssertion in interface AssertionHandler

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

getAssertion

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

Returns an Assertion having the wiki page name, Predicate and Property. (This style of assertion is considered a property assertion.) 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: This is the only way to add a property Assertion to the registry; there is no addAssertion() method. This keeps any Assertions not created by the AssertionHandler from entering into the system.

This is an AssertionHandler API method.

Specified by:

getAssertion in interface AssertionHandler

Parameters:

pagename - the wiki page name source of the Assertion

subject - the subject Term of the Assertion

predicate - the property assignment Predicate (or property name) of the Assertion

property - the property value of the Assertion

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

getAssertions

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

Returns the Collection of all Assertions matching any of the optional parameters: pagename, subject, predicate, and/or object as Strings. If there are no filter values, all Assertions are returned.

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

See AssertionQuery for a description of the permitted values for the template and logical mode. Null values are ignored.

Parameters:

assertions - the beginning Collection of Assertions to query; if null, the entire collection 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 org.ceryle.tm.assertion.AssertionQueryExecutor#TEMPLATES_EXCLUDE, org.ceryle.tm.assertion.AssertionQueryExecutor#TEMPLATES_ONLY, or org.ceryle.tm.assertion.AssertionQueryExecutor#TEMPLATES_INCLUDE.

logicMode - the query is done as org.ceryle.tm.assertion.AssertionQueryExecutor#LOGICAL_ALL, org.ceryle.tm.assertion.AssertionQueryExecutor#LOGICAL_AND, or org.ceryle.tm.assertion.AssertionQueryExecutor#LOGICAL_OR.

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. This is not expected to return assertion templates nor property assertions.

Returns null if unable to locate a matching Assertion. The pagename parameter is optional; it is only used as an additional query filter if provided.

This is an AssertionHandler API method.

Specified by:

getAssertion in interface AssertionHandler

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)

Returns true if an Assertion equivalent to one created with the provided subject, predicate, and object is contained in the registry. This is not expected to match assertion templates nor property assertions. The pagename parameter is optional; it is only used as an additional query filter if provided.

This is an AssertionHandler API method.

Specified by:

hasAssertion in interface AssertionHandler

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

Returns:

true if a matching Assertion already exists in the registry.

removeAssertion

public boolean removeAssertion(Assertion assertion)

Returns true if the Assertion was removed from the registry.

This is an AssertionHandler API method.

Specified by:

removeAssertion in interface AssertionHandler

Parameters:

assertion - the Assertion to be removed.

toXHTML

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

Format the assertion into XHTML output suitable for display on a web page. This simply calls Assertion.toXHTML(WikiContext,Assertion).

The Terms are displayed square-bracketed; the Predicate not.

This is an AssertionHandler API method.

Specified by:

toXHTML in interface AssertionHandler

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

createAssertion

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

Creates and returns a new 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

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

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

clearRegistry

protected void clearRegistry()

Clear the registry and page cache.

disableRegistry

protected void disableRegistry()

Disables further use of the registry and page cache. This permits subclasses to begin using their own.

setRegistryIsChanging

protected void setRegistryIsChanging(boolean changing)

setSynchronizing

protected void setSynchronizing(boolean sync)

isSynchronizing

protected boolean isSynchronizing()

getFromRegistry

protected Assertion getFromRegistry(String signature)

Returns true if the cache contains the Assertion indicated by the provided signature. We want to determine if the same Assertion is being made regardless of source page or Object identity.

Parameters:

signature - The signature of the Assertion to match.

Returns:

the existing Assertion, or null.

updateCacheForPage

protected void updateCacheForPage(String pagename)

Update the WikiPage's internally-stored attribute containing its Assertions, and add the page to the internal cache.

Note: If the listener is disabled, this method does nothing.

removeFromPageCache

protected boolean removeFromPageCache(String pagename)