org.ceryle.tm
Class TM4JTopicMapBuilderImpl

java.lang.Object
  org.ceryle.tm.TM4JTopicMapBuilderImpl

All Implemented Interfaces:

TopicMapBuilder

public class TM4JTopicMapBuilderImpl
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 native interface within TM4J. 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: TM4JTopicMapBuilderImpl.java,v 3.1 2007-06-15 12:09:32 altheim Exp $

Author:

Murray Altheim

See Also:

TopicMapBuilder

Field Summary

static String	label_AT
static String	label_Description
static String	label_Display
static String	label_IsA
static String	label_KindOf
static String	label_Object
static String	label_Predicate
static String	label_Subject
static String	LABEL_UNKNOWN The label assigned unlabeled Topics.
static String	PROPERTY_BUILDER_PROVIDER The property name of the TopicMapBuilder provider backend.
static int	PROVIDER_HIBERNATE Indicator constant for Hibernate DB provider implementation.
static int	PROVIDER_MEMORY Indicator constant for in-memory provider implementation.
static int	PROVIDER_OZONE Indicator constant for Ozone DB provider implementation.
static String	thesaurus_publicId
static String	thesaurus_systemId

Constructor Summary

protected

TM4JTopicMapBuilderImpl() Default constructor.

Method Summary

void	clearTemplates() Clears any existing Association templates from the cache.
static Topic[]	convertScopeToArray(Set scope) Converts a Set of Topics into an array used as a Scope.
static Set	convertScopeToSet(Topic[] scope) Converts an array of Topics (comprising a Scope) into a Set used as a Scope.
String	generateID() Uses the existing IDGenerator to return a unique ID within this builder's TopicMap.
Object	getAssociation(String subject, String predicate, String object) Return an Association provided by the String identifiers (as Topic names) for the subject, predicate, and object of the assertion.
Set	getAssociations(Collection associations, String type, String scope) Return Associations in the TopicMap whose type is type and whose scope contains Topic scope.
String	getDisplayName(Topic topic, Topic[] scope) Returns a String which may be used as a display name in the specified scope.
String	getLabel(Topic topic) A convenience method that calls getLabel(Topic,Topic[]) with a null Scope parameter.
String	getLabel(Topic topic, Topic[] scope) Returns a label for the provided Topic topic in the optional Topic[] scope, in order of availability.
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.
Topic[]	getOrderedRolesForTemplate(Topic type) Returns the two player Topics of the Association template matching the Topic type, based on the directedness of the Association.
Object	getPredicateTopic() Returns the predicate typing Topic.
TopicMapProvider	getProvider(int backend) Returns the supporting TopicMapProvider.
Collection	getScope(String label) Returns a Collection of Topics acting as a Scope, provided the label of the single scoping Topic.
Topic[]	getScopeTemplate() Returns a Scope (an array of Topics) whose theme is the Ceryle "template" PSI.
String	getSortName(Topic topic, Topic[] scope) Returns a String which may be used as a sort name in the specified scope.
Object	getSubjectTopic() Returns the subject typing Topic.
int	getTemplateCount() Returns the number of Association templates for the given TopicMap, from the cache.
Association	getTemplateForType(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(boolean update) Returns any "association templates" for the builder's TopicMap.
Object	getTopicByName(String label) 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.
Object	getTopicWithSubject(String uri) Returns a new or existing Topic object having a subject indicator uri, a URI indicating the Topic subject.
BaseName	hasLabel(Topic topic, String label, Set scope) A check to see if the Topic already has the label.
boolean	hasSubject(Topic topic, Locator subject) Returns true if the supplied Topic topic has as one of its subject indicators the Locator subject.
boolean	hasSubject(Topic topic, String uri) Returns true if the supplied Topic topic has as one of its subject indicators a Locator whose address is the URI uri.
void	mergeTopicMap(Object topicmap) Merge the TopicMap topicmap with the existing Topicmap associated with this builder.
Locator	returnLocator(String uri) Returns a Locator whose address is uri.
BaseName	setDisplayName(Topic topic, String name, Set scope) A convenience method that sets a variant name String name on the provided Topic topic.
BaseName	setLabel(Topic topic, String label) A convenience method that calls setLabel(Topic,String,Set) with a null Scope parameter.
BaseName	setLabel(Topic topic, String label, Set scope) Sets a label for this Topic to the string label, as a Variant whose parameter (scope) is XTM 1.0's "display".
void	setLocator(String uri) Sets the Locator of the builder's TopicMap to uri.

Methods inherited from class java.lang.Object

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

Field Detail

PROPERTY_BUILDER_PROVIDER

public static final String PROPERTY_BUILDER_PROVIDER

The property name of the TopicMapBuilder provider backend. This should be set to one of: PROVIDER_MEMORY, PROVIDER_OZONE, or PROVIDER_HIBERNATE.

See Also:

Constant Field Values

PROVIDER_MEMORY

public static final int PROVIDER_MEMORY

Indicator constant for in-memory provider implementation.

See Also:

Constant Field Values

PROVIDER_OZONE

public static final int PROVIDER_OZONE

Indicator constant for Ozone DB provider implementation.

See Also:

Constant Field Values

PROVIDER_HIBERNATE

public static final int PROVIDER_HIBERNATE

Indicator constant for Hibernate DB provider implementation.

See Also:

Constant Field Values

LABEL_UNKNOWN

public static String LABEL_UNKNOWN

The label assigned unlabeled Topics. The value is a single question mark.

label_AT

public static String label_AT

label_IsA

public static String label_IsA

label_KindOf

public static String label_KindOf

label_Display

public static String label_Display

label_Description

public static String label_Description

label_Subject

public static String label_Subject

label_Predicate

public static String label_Predicate

label_Object

public static String label_Object

thesaurus_publicId

public static String thesaurus_publicId

thesaurus_systemId

public static String thesaurus_systemId

Constructor Detail

TM4JTopicMapBuilderImpl

protected TM4JTopicMapBuilderImpl()
                           throws TopicMapException

Default constructor. The System property for the backend should be set prior to instantiation if a provider other than the memory backend is desired.

Throws:

TopicMapException

Method Detail

setLocator

public void setLocator(String uri)
                throws IllegalStateException,
                       TopicMapException

Sets the Locator of the builder's TopicMap to uri. This causes creation of the initial TopicMap. Once set, further calls 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 - if an error occurs establishing services or the Topic Map

getTopicMap

public Object getTopicMap()

Return the TopicMap associated with this builder.

Specified by:

getTopicMap in interface TopicMapBuilder

Returns:

the TopicMap managed by this builder.

mergeTopicMap

public void mergeTopicMap(Object topicmap)
                   throws TopicMapException

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

Specified by:

mergeTopicMap in interface TopicMapBuilder

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'. This special-cases the frequently used Topics: IsA, KindOf, Display, Subject, Predicate, and Object.

Specified by:

getTopicByName in interface TopicMapBuilder

Parameters:

label - the Topic label (its primary identifier).

Returns:

the Topic whose label matches the parameter.

Throws:

TopicMapException

getTopicWithSubject

public Object getTopicWithSubject(String uri)
                           throws TopicMapException

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

Throws:

TopicMapException

returnLocator

public Locator returnLocator(String uri)
                      throws TopicMapException

Returns a Locator whose address is uri.

Parameters:

uri - the String used as the locator address

Throws:

TopicMapException

hasSubject

public boolean hasSubject(Topic topic,
                          String uri)
                   throws TopicMapException

Returns true if the supplied Topic topic has as one of its subject indicators a Locator whose address is the URI uri. This is a convenience method for hasSubject(Topic,Locator), returning false if any exception occurs during Locator creation.

Throws:

TopicMapException

hasSubject

public boolean hasSubject(Topic topic,
                          Locator subject)

Returns true if the supplied Topic topic has as one of its subject indicators the Locator subject. This includes the subjects of all merged topics.

setLabel

public BaseName setLabel(Topic topic,
                         String label)
                  throws TopicMapException

A convenience method that calls setLabel(Topic,String,Set) with a null Scope parameter.

Throws:

TopicMapException

setLabel

public BaseName setLabel(Topic topic,
                         String label,
                         Set scope)
                  throws TopicMapException

Sets a label for this Topic to the string label, as a Variant whose parameter (scope) is XTM 1.0's "display". If the Topic already has this particular label the method is ignored.

NOTE: This first locates any existing base names having a "display" variant name, eliminates those base names, and sets this as the only one. This is necessarily ignoring scoping on the base name itself, and is a bit dangerous if the base name itself if valuable. The problem with only removing the variant is we end up with a bunch of basenames whose only purpose was to provide a display name.

If the Scope is specified, it will be added to the resulting basename. This also allows for multiple display names on the same Topic.

Parameters:

topic - the Topic on which to set the name/label

label - the String used as the label

scope - an optional scope (as a Set of Topics) on the name/label

Returns:

the created BaseName (which has a display variant containing the value)

Throws:

TopicMapException

hasLabel

public BaseName hasLabel(Topic topic,
                         String label,
                         Set scope)
                  throws TopicMapException

A check to see if the Topic already has the label. If scope is specified, the BaseName must be in the specified Scope in addition to being a display variant.

Parameters:

topic - the Topic to check

label - the label to check for

scope - the optional Scope of the BaseName; if present, it must match

Throws:

TopicMapException - if anything goes wrong

setDisplayName

public BaseName setDisplayName(Topic topic,
                               String name,
                               Set scope)
                        throws TopicMapException

A convenience method that sets a variant name String name on the provided Topic topic. The optional Topic[] scope is used to provide individual Topic parameters on the display variant (In XTM, scope and parameters on variants are semantically identical). This necessarily creates a new BaseName as its parent container.

Returns:

the created BaseName (which has a display variant containing the value)

Throws:

TopicMapException

getDisplayName

public String getDisplayName(Topic topic,
                             Topic[] scope)

Returns a String which may be used as a display name in the specified scope.

getSortName

public String getSortName(Topic topic,
                          Topic[] scope)

Returns a String which may be used as a sort name in the specified scope.

getLabel

public String getLabel(Topic topic)

A convenience method that calls getLabel(Topic,Topic[]) with a null Scope parameter.

getLabel

public String getLabel(Topic topic,
                       Topic[] scope)

Returns a label for the provided Topic topic in the optional Topic[] scope, in order of availability. This is prioritized as:

1. its display name in the provided scope
2. a base name in the provided scope
3. any of its base names
4. or finally, its topic ID

If for some reason the supplied Topic is null, a '?' is returned.

See Also:

getDisplayName(Topic,Topic[])

getScope

public Collection getScope(String label)
                    throws TopicMapException

Returns a Collection of Topics acting as a Scope, provided the label of the single scoping Topic. This will create the Topic if it doesn't already exist. Because the number of scopes is typically small, newly-created scopes are cached.

Specified by:

getScope in interface TopicMapBuilder

Parameters:

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

Throws:

TopicMapException

convertScopeToSet

public static Set convertScopeToSet(Topic[] scope)

Converts an array of Topics (comprising a Scope) into a Set used as a Scope. This never returns a null, even if the provided array is null. This is a convenience method.

convertScopeToArray

public static Topic[] convertScopeToArray(Set scope)

Converts a Set of Topics into an array used as a Scope. This never returns a null, even if the provided Set is null. This is a convenience method.

getTemplateForType

public Association getTemplateForType(Topic type)
                               throws TopicMapException

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

Throws:

TopicMapException

getTemplates

public Set getTemplates(boolean update)
                 throws TopicMapException

Returns any "association templates" for the 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 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 (a Hashtable) and returned using the TopicMap as a key.

The cache is cleared with clearTemplates().

Parameters:

update - if true, regenerates the Set of templates

Throws:

TopicMapException

getScopeTemplate

public Topic[] getScopeTemplate()
                         throws TopicMapException

Returns a Scope (an array of Topics) whose theme is the Ceryle "template" PSI. This is a convenience method.

Throws:

TopicMapException

getTemplateCount

public int getTemplateCount()

Returns the number of Association templates for the given TopicMap, from the cache. If the TopicMap has not been processed previously it is not in the cache and the method returns -1.

clearTemplates

public void clearTemplates()

Clears any existing Association templates from the cache.

getAssociation

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

Return an Association provided by the String identifiers (as Topic names) for the subject, predicate, and object of the assertion. This is created as necessary; if a matching Association already exists, it is returned.

The predicate is used as the Association's typing topic, with the subject and object assigned subject and object roles. These three typing Topics can be retrieved using getSubjectTopic(), getPredicateTopic(), and getObjectTopic().

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

getOrderedRolesForTemplate

public Topic[] getOrderedRolesForTemplate(Topic type)
                                   throws TopicMapException

Returns the two player Topics of the Association template matching the Topic type, based on the directedness of the Association. The order will be (subject,object).

If there isn't an Association template for the provided Topic, null is returned. For example, getOrderedRolesForTemplate(SuperclassSubclass) ("KindOf") would return { Subclass, Superclass } in (subject,object) sentence order.

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

getProvider

public TopicMapProvider getProvider(int backend)
                             throws TopicMapException

Returns the supporting TopicMapProvider. The provider is lazily-created; if it hasn't already been created, a call to this method instantiates the TopicMapProvider with the backend determined by the int parameter in the constructor. If for any reason the provider is closed (and nullified), calling this method will re-create it.

The int backend indicates which backend the processor should use to store topic map information. An unrecognized value will default to the in-memory backend.

Allowed values include:

• In-memory (PROVIDER_MEMORY);
• Ozone/OODBMS (PROVIDER_OZONE); or
• Hibernate/JDBC (PROVIDER_HIBERNATE).

This method is part of an implementation of the TopicMapManager interface.

Throws:

TopicMapException

generateID

public String generateID()

Uses the existing IDGenerator to return a unique ID within this builder's TopicMap.