org.ceryle.tm
Interface TopicMapBuilder

All Known Implementing Classes:

TM4JTopicMapBuilderImpl, TMAPITopicMapBuilderImpl

public interface TopicMapBuilder

A simple interface for a builder that delegates access and object creation for a TopicMap identified by its base Locator as a URI (keyed as a String). TopicMap object creation is managed exclusively through Strings (as Topic labels, i.e., base names in the XTM 'Display' scope). The 'Display' scope is automatic on all labels; when scope is used it generally is meant to express application-level scopes such as natural language, or to provide scoping for other parts of the API, such as scoping Associations.

Because things are often passed around as Java Objects, implementations will throw ClassCastExceptions if unexpected classes show up.

Topic Map Object Management

The builder has methods to create Topics, Associations, Occurrences, and Scopes provided with simple String tokens as Topic labels or resource data values. There are no "API implementation" objects in the API itself; everything is some form of Java object.

Topics

Topics in this builder are accessed entirely by either a label or subject identity/URI, and no Topics can be created without one or the other.

      public Topic getTopic( String label ) 

Scopes

Scopes in TMAPI are defined via Collections of Topics. This simplified interface provides a method to create a Scope from a single Topic (via its label). Since single Topic Scopes are the most common (e.g., "English") in this application, this suffices for most situations. The Topic creation method receives an optional Collection object for a Scope, so if necessary it's still relatively easy to create a Scope outside of the API.

      public Collection getScope( String label )
  

Associations

Associations are made entirely from triples: Topics, referenced by label, for subject, predicate (association type) and object. All three are required; i.e., there are no monadic relations or typeless Associations.

      public Association getAssociation( String subject, String predicate, String object ) 

Occurrences

Topic Occurrences are required to be typed by a Topic (referenced again by label). Occurrences that use references do not require nor support a type.

      public Object getOccurrence( String label, String type, String data )
      public Object getOccurrence( String label, String ref ) 

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 must take responsibility for duplicate suppression of Topics, TopicNames, Associations, Occurrences, etc.

Author:

Murray Altheim

Method Summary

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.
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(String label) Returns a Collection of Topics acting as a Scope, provided the label of the scoping Topic.
Object	getSubjectTopic() Returns the subject typing Topic.
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.
void	mergeTopicMap(Object topicmap) Merge the TopicMap topicmap with the existing Topicmap associated with this builder.
void	setLocator(String uri) Sets the Locator of the builder's TopicMap to uri.

Method Detail

setLocator

void setLocator(String uri)
                throws IllegalStateException,
                       TopicMapException

Sets the Locator of the builder's TopicMap to uri. Because an implementation may not create a new TopicMap object absent its base URI, this may cause the initial creation for this builder.

Once set it is permissable (but not required) for implementations to throw an IllegalStateException if the builder does not permit modification of the identifier after initially being set. It is also permissable for implementations to throw hissyfits if various methods are called prior to this method. I.e., this should be called early after builder instantiation.

Parameters:

uri - the URI identifier of the TopicMap.

Throws:

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

TopicMapException

getTopicMap

Object getTopicMap()

Return the TopicMap associated with this builder.

Returns:

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

mergeTopicMap

void mergeTopicMap(Object topicmap)
                   throws TopicMapException

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

Throws:

TopicMapException

getSubjectTopic

Object getSubjectTopic()
                       throws TopicMapException

Returns the subject typing Topic.

Returns:

the Topic used as the "subject" typing Topic.

Throws:

TopicMapException

See Also:

PSIUtils.psiSubject(TopicMap)

getPredicateTopic

Object getPredicateTopic()
                         throws TopicMapException

Returns the predicate typing Topic.

Returns:

the Topic used as the "predicate" typing Topic.

Throws:

TopicMapException

See Also:

PSIUtils.psiPredicate(TopicMap)

getObjectTopic

Object getObjectTopic()
                      throws TopicMapException

Returns the object typing Topic.

Returns:

the Topic used as the "object" typing Topic.

Throws:

TopicMapException

See Also:

PSIUtils.psiObject(TopicMap)

getTopicByName

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'.

Parameters:

label - the Topic label (its primary identifier).

Returns:

the Topic whose label matches the parameter.

Throws:

TopicMapException

getTopicWithSubject

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.

Throws:

TopicMapException

getScope

Collection getScope(String label)
                    throws TopicMapException

Returns a Collection of Topics acting as a Scope, provided the label of the scoping Topic.

Parameters:

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

Throws:

TopicMapException

getAssociation

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().

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

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.

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

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.

Throws:

TopicMapException

getOccurrence

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.

Throws:

TopicMapException