org.ceryle.tm
Class TMAPITopicMapBuilderImpl

java.lang.Object
  org.ceryle.tm.TMAPITopicMapBuilderImpl

All Implemented Interfaces:

TopicMapBuilder

public class TMAPITopicMapBuilderImpl
extends Object
implements TopicMapBuilder

Implements the TopicMapBuilder interface as a delegating builder/manager for TopicMap objects. To obtain an instance of this class, see TopicMapBuilderFactory.

Supplied with the TopicMap to be built/populated, it provides a builder that, like an event listener/handler, then receives simplified "events" (whose parameters are entirely text strings) that create Topics, Associations and other TopicMap objects for the TopicMap associated with the builder. This is designed to simplify creation of a TopicMap from the parsing of external source material, so not all TopicMap features are supported.

The public TopicMapBuilder methods are either externally or internally synchronized, as they're designed for thread safety when used in a multiuser (i.e., online) system.

This uses the TMAPI interface within TM4J rather than TM4J's native interface, and also takes advantage of TMAPI-utils to fill in the XML-related holes in the TMAPI interface. The rest of this documentation deals with the methods of the TopicMapBuilder interface.

Logical Sentences

Because the associations created by this builder require both an association and role types, we must assume a base ontology. This is supplied by the import of an external TopicMap from an LTM file. If the file is not available for import, stub topics are created as necessary.

Duplicate Suppression

Note that because this builder is expected to repeatedly receive the same set of events (since the source may be multiple users triggering the same event listeners), the builder takes responsibility for duplicate suppression of Topics, TopicNames, Associations, Occurrences, etc.

Version:

$Id: TMAPITopicMapBuilderImpl.java,v 3.1 2007-06-15 12:09:32 altheim Exp $

Author:

Murray Altheim

See Also:

TopicMapBuilder

Field Summary

static String	label_IsA
static String	label_KindOf
static String	thesaurus_publicId
static String	thesaurus_systemId

Constructor Summary

protected

TMAPITopicMapBuilderImpl() Constructor for a TMAPITopicMapBuilderImpl.

Method Summary

void	clearCaches() Clears any existing indices and the Association Template cache.
Object	getAssociation(String subject, String predicate, String object) Creates a new Association or returns an existing one matching the provided triple.
Set	getAssociations(Collection associations, String type, String scope) Return Associations in the TopicMap whose type is type and whose scope contains Topic scope.
static Properties	getDefaultProperties() Returns a property set to set the TMAPI TopicMapSystem to use the TM4J in-memory backend.
Object	getObjectTopic() Returns the object typing Topic.
Object	getOccurrence(String topic, String ref) Creates a new occurrence as a contained object in the Topic topic using the String ref as a resource Locator.
Object	getOccurrence(String topic, String type, String data) Creates a new occurrence as a contained object in the Topic topic using the String type as the Occurrence type and data as the occurrence data.
Object	getPredicateTopic() Returns the predicate typing Topic.
Collection	getScope(Object topic) Returns a Collection of Topics acting as a Scope, provided a scoping Topic.
Collection	getScope(String label) Returns a Collection of Topics acting as a Scope, provided with a single String, creating or retrieving a Topic (as necessary) based on that String as a Topic label.
org.tmapi.index.core.ScopedObjectsIndex	getScopedObjectsIndex() Returns an index over ScopedObjects for this builder's TopicMap.
Object	getSubjectTopic() Returns the subject typing Topic.
int	getTemplateCount() Returns the number of Association templates for this builder's TopicMap, from the cache.
org.tmapi.core.Association	getTemplateForType(org.tmapi.core.Topic type) Returns the Association used as the template for the provided Topic if it matches any of the available Association Template typing Topics.
Set	getTemplates() Returns any "association templates" for this builder's TopicMap.
Locator	getTM4JLocator(org.tmapi.core.Locator locator) Returns a TM4J Locator provided a TMAPI Locator.
Topic	getTM4JTopic(org.tmapi.core.Topic topic) Returns a TM4J Topic provided a TMAPI Topic.
TopicMap	getTM4JTopicMap(org.tmapi.core.TopicMap topicmap) Returns a TM4J TopicMap provided a TMAPI TopicMap.
Object	getTopicByName(String label) Returns either a new or existing Topic object with a Topic label, creating the Topic as necessary.
Object	getTopicByName(String label, Collection scope) Returns either a new or existing Topic object with a Topic label, creating the Topic as necessary.
Object	getTopicMap() Return the TopicMap associated with this builder.
org.tmapi.index.core.TopicNamesIndex	getTopicNamesIndex() Returns an index over the TopicNames for this builder's TopicMap.
org.tmapi.index.core.TopicsIndex	getTopicsIndex() Returns an index over the Topics for this builder's TopicMap.
Object	getTopicWithSubject(String uri) Returns a new or existing Topic object having a subject indicator uri, a URI indicating the Topic subject.
void	makeConsistent() Calls the static XTMUtils method of the same name to process this builder's TM4J TopicMap into a consistent Topic Map as according to the XTM 1.0 Specification.
void	mergeTopicMap(Object topicmap) Merge the TopicMap topicmap with the existing Topicmap associated with this builder.
void	postProcess() Performs any post-processing (such as consistency checking) on this builder's TopicMap.
void	setLocator(String uri) This causes creation of the initial TopicMap, setting its base Locator to uri.

Methods inherited from class java.lang.Object

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

Field Detail

thesaurus_publicId

public static String thesaurus_publicId

thesaurus_systemId

public static String thesaurus_systemId

label_IsA

public static String label_IsA

label_KindOf

public static String label_KindOf

Constructor Detail

TMAPITopicMapBuilderImpl

protected TMAPITopicMapBuilderImpl()
                            throws TopicMapException

Constructor for a TMAPITopicMapBuilderImpl.

Throws:

TopicMapException

Method Detail

setLocator

public void setLocator(String uri)
                throws IllegalStateException,
                       TopicMapException

This causes creation of the initial TopicMap, setting its base Locator to uri. Once set, further calls to this method throw an IllegalStateException.

Specified by:

setLocator in interface TopicMapBuilder

Parameters:

uri - the URI identifier of the TopicMap.

Throws:

IllegalStateException - if this method is called after the value has already been set.

TopicMapException

getTopicMap

public Object getTopicMap()

Return the TopicMap associated with this builder.

Specified by:

getTopicMap in interface TopicMapBuilder

Returns:

the TopicMap managed by this builder. This will be returned as the TopicMap implementing class for the given engine.

postProcess

public void postProcess()
                 throws TopicMapException

Performs any post-processing (such as consistency checking) on this builder's TopicMap.

This is not a TopicMapBuilder API method.

Throws:

TopicMapException

mergeTopicMap

public void mergeTopicMap(Object topicmap)

Merge the TopicMap topicmap with the existing Topicmap associated with this builder.

Specified by:

mergeTopicMap in interface TopicMapBuilder

getTM4JLocator

public Locator getTM4JLocator(org.tmapi.core.Locator locator)
                       throws TopicMapException

Returns a TM4J Locator provided a TMAPI Locator.

Parameters:

locator - the TMAPI Locator.

Returns:

an unwrapped TM4J Topic.

Throws:

TopicMapException

getTM4JTopic

public Topic getTM4JTopic(org.tmapi.core.Topic topic)
                   throws TopicMapException

Returns a TM4J Topic provided a TMAPI Topic.

Parameters:

topic - the TMAPI Topic.

Returns:

an unwrapped TM4J Topic.

Throws:

TopicMapException

getTM4JTopicMap

public TopicMap getTM4JTopicMap(org.tmapi.core.TopicMap topicmap)
                         throws TopicMapException

Returns a TM4J TopicMap provided a TMAPI TopicMap.

Parameters:

topicmap - the TMAPI TopicMap.

Returns:

an unwrapped TM4J TopicMap.

Throws:

TopicMapException

getSubjectTopic

public Object getSubjectTopic()
                       throws TopicMapException

Returns the subject typing Topic.

Specified by:

getSubjectTopic in interface TopicMapBuilder

Returns:

the Topic used as the "subject" typing Topic.

Throws:

TopicMapException

See Also:

PSIUtils.psiSubject(TopicMap)

getPredicateTopic

public Object getPredicateTopic()
                         throws TopicMapException

Returns the predicate typing Topic.

Specified by:

getPredicateTopic in interface TopicMapBuilder

Returns:

the Topic used as the "predicate" typing Topic.

Throws:

TopicMapException

See Also:

PSIUtils.psiPredicate(TopicMap)

getObjectTopic

public Object getObjectTopic()
                      throws TopicMapException

Returns the object typing Topic.

Specified by:

getObjectTopic in interface TopicMapBuilder

Returns:

the Topic used as the "object" typing Topic.

Throws:

TopicMapException

See Also:

PSIUtils.psiObject(TopicMap)

getTopicByName

public Object getTopicByName(String label)
                      throws TopicMapException

Returns either a new or existing Topic object with a Topic label, creating the Topic as necessary. A Topic label is a base name in the scope of the XTM PSI 'Display'.

Specified by:

getTopicByName in interface TopicMapBuilder

Parameters:

label - the Topic label (its primary identifier).

Returns:

the Topic whose label matches the parameter.

Throws:

TopicMapException

getTopicByName

public Object getTopicByName(String label,
                             Collection scope)
                      throws TopicMapException

Returns either a new or existing Topic object with a Topic label, creating the Topic as necessary. A Topic label is a base name in the scope of the XTM PSI 'Display'. If the scope parameter is present, this is added to the base name in addition to the 'Display' scope.

Parameters:

label - the Topic label (its primary identifier).

scope - the optional Scope on the label.

Returns:

the Topic whose label matches the parameter.

Throws:

TopicMapException

getTopicWithSubject

public Object getTopicWithSubject(String uri)

Returns a new or existing Topic object having a subject indicator uri, a URI indicating the Topic subject. No validation is done on the parameter value.

Specified by:

getTopicWithSubject in interface TopicMapBuilder

getScope

public Collection getScope(String label)
                    throws TopicMapException

Returns a Collection of Topics acting as a Scope, provided with a single String, creating or retrieving a Topic (as necessary) based on that String as a Topic label. Since scopes are commonly based on a single Topic and are commonly reused, this is a cached object.

Specified by:

getScope in interface TopicMapBuilder

Parameters:

label - the label of the Topic used for the Scope.

Returns:

a new or existing Collection (used as a Scope) whose sole Topic has the matching label.

Throws:

TopicMapException

getScope

public Collection getScope(Object topic)
                    throws TopicMapException

Returns a Collection of Topics acting as a Scope, provided a scoping Topic. This uses the first TopicName returned by the iterator as the cache key (so generally the Topic should have only one label). If there is currently no scope registered with that key, a new one is created with the Topic as its sole member. If the Topic has no TopicNames this will return a null value. Since scopes are commonly based on a single Topic and are commonly reused, this is a cached object.

Parameters:

topic - the Topic used for the Scope.

Returns:

a new or existing Collection (used as a Scope) containing the sole Topic.

Throws:

TopicMapException

getTemplateCount

public int getTemplateCount()

Returns the number of Association templates for this builder's TopicMap, from the cache.

clearCaches

public void clearCaches()

Clears any existing indices and the Association Template cache.

getTemplateForType

public org.tmapi.core.Association getTemplateForType(org.tmapi.core.Topic type)

Returns the Association used as the template for the provided Topic if it matches any of the available Association Template typing Topics.

getTemplates

public Set getTemplates()

Returns any "association templates" for this builder's TopicMap. These are Associations scoped by the "Template" PSI, used to determine edge direction in the displayed graph. Unless cleared, the Association templates are continuously maintained as a Set.

Since this method is often called repeatedly (e.g., during visualization), the TopicMaps used as parameters for this method are kept in a cache. The cache lookup only occurs if the parameter is null; if non-null, the provided HashSet is used as the container and forces a rebuild of the list of templates.

The template cache (as well as any existing indices) is cleared with clearCaches().

Returns:

the Set of Association Templates (i.e., Associations used as templates)

getScopedObjectsIndex

public org.tmapi.index.core.ScopedObjectsIndex getScopedObjectsIndex()

Returns an index over ScopedObjects for this builder's TopicMap.

getTopicsIndex

public org.tmapi.index.core.TopicsIndex getTopicsIndex()

Returns an index over the Topics for this builder's TopicMap.

getTopicNamesIndex

public org.tmapi.index.core.TopicNamesIndex getTopicNamesIndex()

Returns an index over the TopicNames for this builder's TopicMap.

getAssociation

public Object getAssociation(String subject,
                             String predicate,
                             String object)
                      throws TopicMapException

Creates a new Association or returns an existing one matching the provided triple. This relies on the ability to locate the correct Association Template for the given predicate/association type.

Specified by:

getAssociation in interface TopicMapBuilder

Parameters:

subject - The name of the subject of the assertion.

predicate - The name of the predicate of the assertion.

object - The name of the object of the assertion.

Throws:

TopicMapException

getAssociations

public Set getAssociations(Collection associations,
                           String type,
                           String scope)
                    throws TopicMapException

Return Associations in the TopicMap whose type is type and whose scope contains Topic scope. If the associations parameter is provided it acts as the source of the query, otherwise using all Associations in the TopicMap. Both the type and scope parameters are optional; in absence of each this acts as a pass-through filter. This returns an empty Set rather than null.

Specified by:

getAssociations in interface TopicMapBuilder

Parameters:

associations - the optional original collection of Associations; when null all in the TopicMap are used.

type - the label of the optional typing Topic

scope - the label of the optional scoping Topic

Returns:

the Set of matching Associations

Throws:

TopicMapException

getOccurrence

public Object getOccurrence(String topic,
                            String type,
                            String data)
                     throws TopicMapException

Creates a new occurrence as a contained object in the Topic topic using the String type as the Occurrence type and data as the occurrence data.

Specified by:

getOccurrence in interface TopicMapBuilder

Throws:

TopicMapException

getOccurrence

public Object getOccurrence(String topic,
                            String ref)
                     throws TopicMapException

Creates a new occurrence as a contained object in the Topic topic using the String ref as a resource Locator.

Specified by:

getOccurrence in interface TopicMapBuilder

Throws:

TopicMapException

makeConsistent

public void makeConsistent()
                    throws TopicMapException

Calls the static XTMUtils method of the same name to process this builder's TM4J TopicMap into a consistent Topic Map as according to the XTM 1.0 Specification.

Throws:

TopicMapException

See Also:

XTMUtils

getDefaultProperties

public static Properties getDefaultProperties()

Returns a property set to set the TMAPI TopicMapSystem to use the TM4J in-memory backend.