org.tmapi.core
Interface TopicMap

All Superinterfaces:

TopicMapObject

public interface TopicMap

extends TopicMapObject

Represents a topic map construct.

Method Summary

void	close() Closes use of this TopicMap.
Association	createAssociation() Creates a new association in the topic map.
Locator	createLocator(java.lang.String reference) Creates and returns a new Locator object.
Locator	createLocator(java.lang.String reference, java.lang.String notation) Creates a locator with the specified notation and reference.
Topic	createTopic() Creates a new topic in the topic map.
java.util.Set	getAssociations() Returns all of the associations in the topic map.
Locator	getBaseLocator() Returns the base locator of this topic map.
java.lang.Object	getHelperObject(java.lang.Class implementationInterface) Returns a concrete implementation of a specified helper object interface.
TopicMapObject	getObjectById(java.lang.String objectId) Returns the TopicMapObject managed by this TopicMap with the specified object ID.
Topic	getReifier() Returns the Topic that reifies this topic map.
TopicMapSystem	getTopicMapSystem() Returns the TopicMapSystem to which this topic map belongs.
java.util.Set	getTopics() Returns all of the topics in the topic map.
void	mergeIn(TopicMap other) Merges the TopicMap other into this TopicMap.
void	remove() Removes this TopicMap from the parent TopicMapSystem.

Methods inherited from interface org.tmapi.core.TopicMapObject

addSourceLocator, equals, getObjectId, getSourceLocators, getTopicMap, hashCode, removeSourceLocator

Method Detail

getTopicMapSystem

public TopicMapSystem getTopicMapSystem()

Returns the TopicMapSystem to which this topic map belongs.

Returns:

The TopicMapSystem object which manages this TopicMap.

getBaseLocator

public Locator getBaseLocator()

Returns the base locator of this topic map. This locator is used as the unique identifier for the TopicMap within the TopicMap system. It is also used for resolving references to resources external to the TopicMap during parsing.

getAssociations

public java.util.Set getAssociations()

Returns all of the associations in the topic map. The return value may be an empty Set, but is never null.

Returns:

an unmodifiable set of Association objects.

createAssociation

public Association createAssociation()

Creates a new association in the topic map. The newly created association has no type, no roles and is in the unconstrained scope.

Returns:

The newly created Association.

getTopics

public java.util.Set getTopics()

Returns all of the topics in the topic map. The return value may be an empty Set, but is never null.

Returns:

an unmodifiable set of Topic objects.

createTopic

public Topic createTopic()

Creates a new topic in the topic map. The newly created topic has no types, names or occurrences.

Returns:

The newly created Topic.

createLocator

public Locator createLocator(java.lang.String reference,
                             java.lang.String notation)

Creates a locator with the specified notation and reference.

Parameters:

reference - The reference string of the new locator.

notation - The notation of the new locator.

Returns:

The newly created Locator.

createLocator

public Locator createLocator(java.lang.String reference)

Creates and returns a new Locator object. The notation of the created object will be the same as that of the baseLocator.

Parameters:

reference - The address string of the new locator.

Returns:

The newly created Locator.

getReifier

public Topic getReifier()

Returns the Topic that reifies this topic map.

Returns:

A Topic instance or null if the topic map is not reified.

remove

public void remove()
            throws TMAPIException

Removes this TopicMap from the parent TopicMapSystem. This method also removes all contained Topic and Association objects.

Specified by:

remove in interface TopicMapObject

Throws:

TMAPIException - if the object cannot be removed from the container. Derived interfaces may define specific circumstances under which a subclass of TMAPIException must be raised. Implementations MUST NOT use a TMAPIException to wrap a failure raised in the underlying engine - such errors must always be wrapped in a TMAPIRuntimeException.

getObjectById

public TopicMapObject getObjectById(java.lang.String objectId)

Returns the TopicMapObject managed by this TopicMap with the specified object ID.

Parameters:

objectId - the object ID of the TopicMapObject to be returned

Returns:

the TopicMapObject with the specified ID or null if no TopicMapObject with that ID is managed by this TopicMap

mergeIn

public void mergeIn(TopicMap other)
             throws MergeException

Merges the TopicMap other into this TopicMap. All Topics and Associations and all of their contents in other will be added to this TopicMap. Topics in other will be merged with topics in this TopicMap as defined by XTM merging rules. The merge process will not modify other in any way.

Parameters:

other - the TopicMap to be merged with this TopicMap

Throws:

SubjectLocatorClashException - if merging of topics of this TopicMap instance and the other cannot be completed because of subjectLocator property conflicts and the XTM 1.0 processing model is enabled.

MergeException

getHelperObject

public java.lang.Object getHelperObject(java.lang.Class implementationInterface)
                                 throws UnsupportedHelperObjectException,
                                        HelperObjectInstantiationException,
                                        HelperObjectConfigurationException

Returns a concrete implementation of a specified helper object interface. TMAPI implementations are required to determine the concrete implementation class as follows where {interfacename} is replaced by the fully qualified Java class name of the helper object interface specified in the implementationInterface parameter.

• Return an instance of the class named by the value of the system property named {interfacename}.
• Use the properties file "lib/tmapi.properties" in the JRE directory. This configuration file must be in standard java.util.Properties format and contains the fully qualified name of the implementation class stored under the key {interfacename}.
• Use the Services API (as detailed in the JAR specification), if available, to determine the classname. The Services API will look for a classname in the file META-INF/services/{interfacename} in jars available to the runtime.

The steps must be applied in the order specified above, if a step does not result in a fully qualified Java class name being located, then the next step should be applied. If all steps are applied without finding an implementation class name, then an UnsupportedHelperObjectException exception must be thrown.

If a step results in a value being returned, that value shall be interpreted as a fully qualified Java class name. Implementations are free to return either a new instance of the specified class or a cached instance. If instantiation of the implementation class results in an exception, this should be propagated as a HelperObjectInstantiationException.

If the implementation class implements the interface TopicMapSystem.ConfigurableHelperObject, then before returning the implementation instance, the method TopicMapSystem.ConfigurableHelperObject.configure(TopicMap) must be invoked on the instance. If the method throws a HelperObjectConfigurationException, the exception must be propagated from this method.

Parameters:

implementationInterface - a Class that specifies the interface that the returned implementation object must implement.

Returns:

an implementation of implementationInterface.

Throws:

UnsupportedHelperObjectException - if no implementation of the specified helper interface can be found.

HelperObjectInstantiationException - if the specified implementation class could not be loaded or if a new instance of the helper class could not be instantiated.

HelperObjectConfigurationException - if the TopicMapSystem.ConfigurableHelperObject.configure(TopicMap) method of the helper object implementation raises an exception.

close

public void close()

Closes use of this TopicMap. This method should be invoked by the application once it is finished using the TopicMap instance. Implementations may release any resources required for the TopicMap instance or any of the TopicMapObject instances contained by the TopicMap instance.