org.ceryle.tm.assertion
Class AssertionQueryExecutor

java.lang.Object
  org.ceryle.tm.assertion.AssertionQueryExecutor

public class AssertionQueryExecutor
extends Object

A utility class used to handle assertion queries from a Topic Map. An assertion is a Topic Map Association typed as an Assertion, not to be confused with Assertion (which can be created by conversion from an Association). Assertions are simple logical sentences of the form:

      Subject Predicate Object
  

whose predicates (i.e., type and roles) are defined by an Association template.

A query takes the same form as the above triple, locating the Set of assertions using one of three logical operators:

• ALL return all assertions
• AND return matches only where all provided parameters are matched
• OR return matches where any of the provided parameters are matched

An empty query always returns an empty Set.

Notes

TM4J vs. TMAPI

This class began using native TM4J methods and is currently being converted over to TMAPI. The one issue is that the current Inference implementation is TM4J-based, so either a wrapper or alternative class needs to be written. Or: we need to dump TMAPI (gasp!).

Page Name Storage

Whereas the subject, predicate and object are part of the TopicMap Association (being the Association type and role Topics), the wiki page name could be connected to the Association in a number of different ways, such as: reifying the Association as a Topic and attaching it as a typed property, linking to the Association's ID from the wiki page Topic, etc. The simplest approach is to scope the Association by the page(s) that declared it and then query to see if a given page appears in that Association's scope. Since this is appropriate according to the model there's no real problem but it is a bit backhanded.

"Inferencing"

Once the substitution has been made, the TopicMap can then provide the set of over a dozen "inferencing" methods, as supplied by the Inferencer API (and, of course, InferencerImpl implementation). All inferencing is done over TopicMap objects, not wiki page names, but there should be a Topic for every wiki page, with conversion between via getTopicByName(String) and getPageForTopic(Topic).

Version:

$Id: AssertionQueryExecutor.java,v 1.1 2007-06-15 12:08:10 altheim Exp $

Author:

Murray Altheim

See Also:

for the constants used as parameters in Assertion queries., Assertion, WikiMapManager

Field Summary

protected boolean

USE_REGEX Use regular expression (regex) matching on Assertion parameters?

Constructor Summary

AssertionQueryExecutor(TopicMapProcessor tmproc, TopicMap topicmap, TopicNameIndex index)
Constructor for a AssertionQueryExecutor.

Method Summary

Collection	getAssertion(String pagename, String subject, String predicate, String object, int templateMode, int logicMode) Returns an assertion (an Association of type 'Assertion') having the wiki page name, predicate and terms.
int	getAssertionCount() Return the assertion count.
Collection	getAssertions() Returns the Collection of all Associations in the TopicMap having a Scope indicating that they are based on Assertions.
Collection	getAssertions(Collection associations, int templateMode) A filter that returns a Collection containing all the assertions (notably, Topic Map Associations, not Assertion objects) in the provided collection, or if null, the entire registry.
Collection	getAssertions(Collection associations, String pagename, String subject, String predicate, String object, int templateMode, int logicMode) Returns the Collection of all Associations matching Assertions (that is, Associations typed as Assertions) having subject (assertion[0]), predicate (assertion[1]), and/or object (assertion[2]) as Strings.
Collection	getAssertionTemplates() Returns a Collection containing all the Assertion templates in the registry.
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 a Set containing the subclasses of the Topic backing wiki page pagename.
Set	getSuperclasses(String pagename) Returns a Set containing the superclasses of the Topic backing wiki page pagename.
Topic	getTopicByName(String label) Returns a Topic with a base name in the XTM 'Display' scope of label, throwing a TopicMapException if provided with a null parameter or is unable to locate and/or create the Topic.
TopicMap	getTopicMap() Returns the TopicMap as a TM4J TopicMap.
TopicMapProcessor	getTopicMapProcessor() Return the TopicMapProcessor used by this AQE.
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 contained in the registry.
protected Collection	queryAssertions(Collection associations, String pagename, String subject, String predicate, String object, int templateMode, int logicMode, boolean returnFirst) Perform a query based on the parameters.

Methods inherited from class java.lang.Object

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

Field Detail

USE_REGEX

protected boolean USE_REGEX

Use regular expression (regex) matching on Assertion parameters?

Constructor Detail

AssertionQueryExecutor

public AssertionQueryExecutor(TopicMapProcessor tmproc,
                              TopicMap topicmap,
                              TopicNameIndex index)
                       throws TopicMapException

Constructor for a AssertionQueryExecutor.

Parameters:

tmproc - the parent TopicMapProcessor.

topicmap - the TopicMap to be queried.

index - the index of Topic names.

Throws:

TopicMapException

Method Detail

getTopicMapProcessor

public TopicMapProcessor getTopicMapProcessor()

Return the TopicMapProcessor used by this AQE.

getTopicMap

public TopicMap getTopicMap()

Returns the TopicMap as a TM4J TopicMap.

getAssertionCount

public int getAssertionCount()

Return the assertion count. This includes assertion templates.

getAssertions

public Collection getAssertions()

Returns the Collection of all Associations in the TopicMap having a Scope indicating that they are based on Assertions. This includes assertion templates.

getAssertionTemplates

public Collection getAssertionTemplates()

Returns a Collection containing all the Assertion templates in the registry. Returns the Collection of all Assertion Templates in the Topic Map, that is, all Associations having a Scope indicating that they are based on Assertions as well as being templates. This is a convenience method.

getAssertions

public Collection getAssertions(Collection associations,
                                int templateMode)

A filter that returns a Collection containing all the assertions (notably, Topic Map Associations, not Assertion objects) in the provided collection, or if null, the entire registry. This includes assertion templates.

Parameters:

associations - the base collection to query, or if null, the entire registry.

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

getAssertions

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

Returns the Collection of all Associations matching Assertions (that is, Associations typed as Assertions) having subject (assertion[0]), predicate (assertion[1]), and/or object (assertion[2]) as Strings. The first element of the array is the page name and (assertion[0]) is ignored. If there are no filter values, all Associations derived from Assertions are returned.

The logicMode determines the logic used for the query.

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

Parameters:

associations - the beginning Collection 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 logical query mode, as either AssertionQuery.LOGICAL_ALL, AssertionQuery.LOGICAL_AND, or AssertionQuery.LOGICAL_OR.

Returns:

a Collection of matching Associations; an empty Set if no match is found.

Throws:

AssertionQueryException

hasAssertion

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

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

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 logical query mode, as either AssertionQuery.LOGICAL_ALL, AssertionQuery.LOGICAL_AND, or AssertionQuery.LOGICAL_OR.

Returns:

true if a matching Assertion already exists in the registry.

Throws:

AssertionQueryException

getAssertion

public Collection getAssertion(String pagename,
                               String subject,
                               String predicate,
                               String object,
                               int templateMode,
                               int logicMode)
                        throws AssertionQueryException

Returns an assertion (an Association of type '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 more than one Assertion matches, this returns the first one found.

Even though this method only returns at most one object, we return a Collection so that both query methods use the same return type (well, except hasAssertion() with its boolean).

Throws:

AssertionQueryException

queryAssertions

protected Collection queryAssertions(Collection associations,
                                     String pagename,
                                     String subject,
                                     String predicate,
                                     String object,
                                     int templateMode,
                                     int logicMode,
                                     boolean returnFirst)
                              throws AssertionQueryException

Perform a query based on the parameters. This is the only method that actually performs a query; all others call this method.

If the value for pagename is AssertionQuery.PAGENAME_ANY the query will match on any page name value.

Parameters:

associations - the beginning collection of Associations to query; if null the entire Topic Map

pagename - the wiki page name of the query

subject - the subject of the query

predicate - the predicate of the query

object - the object of the query

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

logicMode - the logical query mode, as either AssertionQuery.LOGICAL_ALL, AssertionQuery.LOGICAL_AND, or AssertionQuery.LOGICAL_OR.

returnFirst - if true return upon first hit

Throws:

AssertionQueryException

getTopicByName

public Topic getTopicByName(String label)
                     throws TopicMapException

Returns a Topic with a base name in the XTM 'Display' scope of label, throwing a TopicMapException if provided with a null parameter or is unable to locate and/or create the Topic.

Parameters:

label - the label of the returned Topic

Throws:

TopicMapException - if unable to locate and/or create the Topic

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

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

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

getSubclasses

public Set getSubclasses(String pagename)
                  throws TopicMapException

Returns a Set containing the subclasses of the Topic backing wiki page pagename. The returned set does not contain the original pagename.

Throws:

TopicMapException

getSuperclasses

public Set getSuperclasses(String pagename)
                    throws TopicMapException

Returns a Set containing the superclasses of the Topic backing wiki page pagename. The returned set does not contain the original pagename.

Throws:

TopicMapException