org.tmapi.core
Interface TopicMapSystem

public interface TopicMapSystem

A generic interface to a TMAPI system. Any TMAPI system must be capable of providing access to one or more TopicMap objects. A TMAPI system may be capable of allowing a client to create a new TopicMap object.

Every TopicMap managed by a TopicMapSystem must be uniquely identifiable by a locator. This locator must be specified when creating a new TopicMap and is the identifier used to retrieve a TopicMap from the TopicMapSystem.

Nested Class Summary

static interface

TopicMapSystem.ConfigurableHelperObject An interface for a helper object implementation which requires notification of the TopicMap instance it acts upon.

Method Summary

void	close() Applications SHOULD call this method when the TopicMapSystem instance is no longer required.
TopicMap	createTopicMap(java.lang.String baseLocatorReference) Creates a new topic map with a specified base locator.
TopicMap	createTopicMap(java.lang.String baseLocatorReference, java.lang.String baseLocatorNotation) Creates a new topic map with a specified base locator.
java.util.Set	getBaseLocators() Returns the base locators of the topic maps managed by the system.
boolean	getFeature(java.lang.String featureName) Returns the value of the feature specified by featureName for this TopicMapSystem instance.
java.lang.String	getProperty(java.lang.String propertyName) Gets a property in the underlying implementation of TopicMapSystem.
TopicMap	getTopicMap(Locator baseLocator) Retrieves the topic map managed by the system with the specified base locator.
TopicMap	getTopicMap(java.lang.String baseLocatorReference) Retrieves the topic map managed by the system with the specified base locator reference.
TopicMap	getTopicMap(java.lang.String baseLocatorReference, java.lang.String baseLocatorNotation) Retrieves the topic map managed by the system with the specified base locator.

Method Detail

createTopicMap

public TopicMap createTopicMap(java.lang.String baseLocatorReference,
                               java.lang.String baseLocatorNotation)
                        throws TopicMapExistsException

Creates a new topic map with a specified base locator.

Parameters:

baseLocatorReference - The data part of the base locator reference.

baseLocatorNotation - The notation of the base locator reference.

Returns:

the newly created TopicMap object.

Throws:

TopicMapExistsException - if the TopicMapSystem already manages a TopicMap with the specified base locator.

createTopicMap

public TopicMap createTopicMap(java.lang.String baseLocatorReference)
                        throws TopicMapExistsException

Creates a new topic map with a specified base locator. The locator reference string is assumed to be in URI notation.

Parameters:

baseLocatorReference - The data part of the base locator reference. The value must be a valid URI.

Returns:

the newly created TopicMap object.

Throws:

TopicMapExistsException - if the TopicMapSystem already manages a TopicMap with the specified base locator.

getTopicMap

public TopicMap getTopicMap(java.lang.String baseLocatorReference,
                            java.lang.String baseLocatorNotation)

Retrieves the topic map managed by the system with the specified base locator.

Parameters:

baseLocatorReference - The data part of the base locator reference.

baseLocatorNotation - The notation of the base locator reference.

Returns:

The TopicMap object managed by the TopicMapSystem which has the specified base locator, or null if no such TopicMap is found.

getTopicMap

public TopicMap getTopicMap(java.lang.String baseLocatorReference)

Retrieves the topic map managed by the system with the specified base locator reference. The locator reference is assumed to be in URI notation.

Parameters:

baseLocatorReference - The data part of the base locator reference. The value must be a valid URI.

Returns:

The TopicMap object managed by the TopicMapSystem which has the specified base locator, or null if no such TopicMap is found.

getTopicMap

public TopicMap getTopicMap(Locator baseLocator)

Retrieves the topic map managed by the system with the specified base locator. The only way to get a base locator without creating or having a topicmap instance is the method getBaseLocators() which returns a set of base locators

Parameters:

baseLocator - The base locator object.

Returns:

The TopicMap object managed by the TopicMapSystem which has the specified base locator, or null if no such TopicMap is found.

getBaseLocators

public java.util.Set getBaseLocators()

Returns the base locators of the topic maps managed by the system. Implementations MUST return the base locator of every TopicMap that would be accessible by a getTopicMap() call. The return value may be an empty Set if no TopicMaps are currently managed by the TopicMapSystem, but must never be null.

Returns:

An unmodifiable Set of base locator objects

getProperty

public java.lang.String getProperty(java.lang.String propertyName)

Gets a property in the underlying implementation of TopicMapSystem. A list of the core properties defined by TMAPI can be found at http://tmapi.org/properties/. An implementation is free to support properties other than the core ones. The properties supported by the TopicMapSystem and the value for each property is set when the TopicMapSystem is created by a call to TopicMapSystemFactory.newTopicMapSystem() and cannot be modified subsequently.

Parameters:

propertyName - the name of the property to retrieve.

Returns:

the value set for this property or null if no value is set for the property.

getFeature

public boolean getFeature(java.lang.String featureName)
                   throws FeatureNotRecognizedException

Returns the value of the feature specified by featureName for this TopicMapSystem instance. The features supported by the TopicMapSystem and the value for each feature is set when the TopicMapSystem is created by a call to TopicMapSystemFactory.newTopicMapSystem() and cannot be modified subsequently.

Parameters:

featureName - the name of the feature to check

Returns:

true if the named feature is enabled for TopicMapSystem instances created by this factory; false if the named feature is disabled for TopicMapSystem instances created by this factory.

Throws:

FeatureNotRecognizedException - if the underlying implementation does not recongnize the named feature.

close

public void close()

Applications SHOULD call this method when the TopicMapSystem instance is no longer required. Once the TopicMapSystem instance is closed, the TopicMapSystem and any object retrieved from or created in this TopicMapSystem MUST NOT be used by the application.

An implementation of the TopicMapSystem interface may use this method to clean up any resources used by the implementation.