The interface org.tmapi.core.TopicMapSystem represents a connection to a topic map processing system. The implementation of this interface may be using a collection of in-memory objects; a relational database system; an on-the-fly mapping of an information system; or any other persistent or non-persistent source of topic map information. However, all TopicMapSystem implementations have one thing in common: they manage a collection of topic maps.[2]
In a TopicMapSystem, the topic maps that it manages are each assigned a unique address specifed by the baseLocator property of the TopicMap instance. The method TopicMapSystem.getBaseLocators() returns a Set containing the baseLocator property value of all topic maps that are currently accesible through the TopicMapSystem. The TopicMapSystem methods getTopicMap(String), getTopicMap(String, String), and getTopicMap(Locator) all provide access methods to retrieve a TopicMap from the TopicMapSystem identified by its baseLocator address; the baseLocator address and notation, or the baseLocator represented as a Locator instance (see the section called “Addressing Using the Locator Interface” for more information about Locators, addresses and notations).
In addition, the TopicMapSystem interface may also allow you to create a new topic map in the underlying system. To create a new topic map, you will need to specify the unqiue address under which the topic map should be stored. If you specify an address which is already in use, a org.tmapi.core.TopicMapExists exception will be thrown. Some systems may be "read-only" in this respect in which case the implementation should throw a java.lang.UnsupportedOperationException.
A TopicMapSystem instance should never be created directly using the Java "new" operator. Instead you should always use the TopicMapSystemFactory class to retrieve a new TopicMapSystem instance. TopicMapSystemFactory is an abstract class which implements the runtime logic that will locate and load a TMAPI implementation from the classpath and which allows the user to override which implementation is used at run-time. This enables your code to be much more portable between processors and could be used to offer the end-user the ability to chose which topic map processor to deploy your code on.
The steps for creating a TopicMapSystem instance from a TopicMapSystemFactory are listed below.
Procedure 4. Connecting to a TopicMapSystem
Create a concrete TopicMapSystemFactory instance.
As already noted, the class org.tmapi.core.TopicMapSystemFactory is an abstract class. Each TMAPI implementation must provide its own concrete implementation of this class which will be instantiated and returned by the static method TopicMapSystemFactory.newInstance(). This method uses a procedure to determine at runtime which underlying TMAPI implementation to use and returns an instance of the appropriate TopicMapSystemFactory implementation. The lookup procedure is described in Lookup Procedure for TopicMapSystemFactory Implementations.
Set the Run-time Features and Properties Configuration for the TopicMapSystem
Features and properties are both used to specify runtime configuration information for a new TopicMapSystem. Typically features are used to specify some runtime behaviour which the TopicMapSystem may or may not support and properties are used to specify some runtime configuration (e.g. database username and password).
Features. The TMAPI 1.0 release specifies a small set of features which MUST be recognised by an implementation (although the implementation is not required to support all of these features). Other feature names MAY be recognized by an implementation, but if they are not, then the implementation MUST raise a org.tmapi.core.FeatureNotRecognized exception. Features are boolean flags set to true to turn the feature on and false to turn it off. Some implementations may not support particular feature settings and if not, they must raise a org.tmapi.core.FeatureNotSupported exception when an attempt is made to set a feature to an unsupported value.
Properties. Property values can be any valid String. TMAPI 1.0 does not specify any properties that an implementation is required to support, however different implementations may require different property settings in order to function correctly. Check the documentation for the implementation you are using. A typical use of properties would be to provide database connection information used by the TopicMapSystem implementation.
It should be clear by now that you should always document clearly the features and properties which are recognized and supported by your implementation as well as what the expected values are for any new features/properties that you define.
For maximum portability, you should make the properties used to create a TopicMapSystem instance configurable by the user. You may also choose to make the set of features configurable, although there are some cases where you may require certain features to be enabled/disabled for the rest of your application to run correctly (e.g. you may require support for the XTM 1.1 model, in which case you should always ensure that your code attempts to set the feature "http://tmapi.org/features/model/xtm1.1" to true).
Create the TopicMapSystem instance
The method TopicMapSystemFactory.newTopicMapSystem() will return a TopicMapSystem instance that is configured by the properties/features set in the previous step. Once the TopicMapSystem instance is created, the properties and features that configure it cannot be changed.
Procedure 5. Lookup Procedure for TopicMapSystemFactory Implementations
This is the procedure that is used to locate the TopicMapFactory implementation to be used by a TMAPI system.
Check System Property org.tmapi.core.TopicMapSystemFactory
If this system property is set, its value must be the fully-qualified Java class name of the TopicMapSystemFactory implementation to be used.
Check lib/tmapi.properties
This file is located in the home directory of the Java runtime being used (i.e. $JRE_HOME/lib/tmapi.properties). If this file exists, it should be in the standard Sun properties file format (see the Javadoc for the class java.util.Properties for details).
If the file contains a value for the property org.tmapi.core.TopicMapSystemFactory, the value of this property must be the fully-qualified Java class name of the TopicMapSystemFactory implementation to be used.
Use the JAR Services API
In this final step, the code will look for the resource /META-INF/services/org.tmapi.core.TopicMapSystemFactory on the current CLASSPATH (including looking in the JAR files). If this resource is found, then the first (and only) line in the resource must be the fully-qualified Java class name of the TopicMapSystemFactory implementation to be used.
It is strongly recommended that you include the resource /META-INF/services/org.tmapi.core.TopicMapSystemFactory in the JAR file that contains your implementation of the TopicMapSystemFactory interface with the content of the resource being the fully-qualified Java class name of your TopicMapSystemFactory implementation. This will allow users to make use of your implementation with minimum runtime configuration requirements.
[2] Of course, that collection may contain only a single topic map, and for newly created and unpopulated systems the collection may even be empty!