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 new TopicMap instances.

Version:
$Rev: 122 $ - $Date: 2009-10-01 19:08:29 +0200 (Do, 01 Okt 2009) $
Author:
The TMAPI Project

Method Summary
 void close()
          Applications SHOULD call this method when the TopicMapSystem instance is no longer required.
 Locator createLocator(java.lang.String reference)
           
 TopicMap createTopicMap(Locator iri)
          Creates a new TopicMap and stores it within the system under the specified iri.
 TopicMap createTopicMap(java.lang.String iri)
          Creates a new TopicMap and stores it within the system under the specified iri.
 boolean getFeature(java.lang.String featureName)
          Returns the value of the feature specified by featureName for this TopicMapSystem instance.
 java.util.Set<Locator> getLocators()
          Returns all storage addresses of TopicMap instances known by this system.
 java.lang.Object getProperty(java.lang.String propertyName)
          Returns a property in the underlying implementation of TopicMapSystem.
 TopicMap getTopicMap(Locator iri)
          Retrieves a TopicMap managed by this system with the specified storage address iri.
 TopicMap getTopicMap(java.lang.String iri)
          Retrieves a TopicMap managed by this system with the specified storage address iri.
 

Method Detail

getTopicMap

TopicMap getTopicMap(java.lang.String iri)
Retrieves a TopicMap managed by this system with the specified storage address iri. The string is assumed to be in IRI notation.

This method should return the same result as the following code:

      TopicMapSystem tmSys = ... // Assumed to be there
      String iri = "http://www.example.org/tm";
      TopicMap tm = tmSys.getTopicMap(tmSys.createLocator(iri));
 

Parameters:
iri - The storage address to retrieve the TopicMap from.
Returns:
The TopicMap instance managed by this system which is stored at the specified iri, or null if no such TopicMap is found.
See Also:
getTopicMap(Locator)

getTopicMap

TopicMap getTopicMap(Locator iri)
Retrieves a TopicMap managed by this system with the specified storage address iri.

Parameters:
iri - The storage address to retrieve the TopicMap from.
Returns:
The TopicMap instance managed by this system which is stored at the specified iri, or null if no such TopicMap is found.
See Also:
getTopicMap(String)

getLocators

java.util.Set<Locator> getLocators()
Returns all storage addresses of TopicMap instances known by this system. The return value may be empty but must never be null.

Returns:
An unmodifiable set of Locators which represent IRIs of known TopicMap instances.

createLocator

Locator createLocator(java.lang.String reference)
                      throws MalformedIRIException
Throws:
MalformedIRIException
See Also:
TopicMap.createLocator(String reference)

createTopicMap

TopicMap createTopicMap(Locator iri)
                        throws TopicMapExistsException
Creates a new TopicMap and stores it within the system under the specified iri.

Parameters:
iri - The address which should be used to store the TopicMap.
Returns:
The newly created TopicMap instance.
Throws:
TopicMapExistsException - If this TopicMapSystem already manages a TopicMap under the specified IRI.
See Also:
createTopicMap(String)

createTopicMap

TopicMap createTopicMap(java.lang.String iri)
                        throws TopicMapExistsException
Creates a new TopicMap and stores it within the system under the specified iri. The string is assumed to be in IRI notation.

This method should return the same result as the following code:

      TopicMapSystem tmSys = ... // Assumed to be there
      String iri = "http://www.example.org/tm";
      TopicMap tm = tmSys.createTopicMap(tmSys.createLocator(iri));
 

Parameters:
iri - The address which should be used to store the TopicMap.
Returns:
The newly created TopicMap instance.
Throws:
TopicMapExistsException - If this TopicMapSystem already manages a TopicMap under the specified IRI.
See Also:
createTopicMap(Locator)

getFeature

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 this TopicMapSystem instance; false if the named feature is disabled for this instance.
Throws:
FeatureNotRecognizedException - If the underlying implementation does not recognize the named feature.

getProperty

java.lang.Object getProperty(java.lang.String propertyName)
Returns 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 the property or null if no value is set for the specified propertyName.

close

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.