TM4J Architecture Overview

Before getting into the details of TM4J classes and utilities, we shall start with a quick tour of the basic architecture of the TM4J system. The diagram in Figure 3.1, “Basic Architecture of TM4J” shows a simplified overview of how each of the various components of TM4J that are involved in retrieving or creating topic maps are related to one another.

Figure 3.1. Basic Architecture of TM4J

Basic Architecture of TM4J

The TopicMapProviderFactory Class

The class TopicMapProviderFactory is an abstract class with separate implementations for each supported back-end. The sole purpose of the TopicMapProviderFactory is to enable the creation of a connection to one or more back-ends of the same type. All concrete implementations of this class provide a default no-args constructor which you may use to instantiate the factory for the back-end you wish to use. However, it is recommended that you make use of the method newInstance which determines the concrete implementation to return based on system properties or service provider configuration information from the CLASSPATH (refer to the section called “Creating the TopicMapProvider” for more details).

Once a concrete implementation of the TopicMapProviderFactory class has been created, this may be used to create an instance of the TopicMapProvider interface by calling the newTopicMapProvider method. The TopicMapProvider represents an entry point to the topic maps managed by the back-end, providing methods for importing new topic maps and removing existing topic maps. Each of the different back-ends support and/or require configuration properties to be passed in when creating the provider, such as database connection strings. These properties can be specified by passing a java.util.Properties object as a parameter in the call to newTopicMapProvider.

The usual procedure for using the TopicMapProviderFactory to create a TopicMapProvider is described in more detail in the section called “Creating the TopicMapProvider”

TopicMapProvider

The TopicMapProvider interface represents the 'connection' to the storage mechanism used. The TopicMapProvider interface manages a collection of TopicMap objects. The methods of the TopicMapProvider interface may be used to add new TopicMap instances to this collection or remove TopicMap instances from the collection, as well as providing the means to access these objects programmatically. Adding new TopicMap instances to the TopicMapProvider may be done either by parsing a file in one of the supported topic map interchange formats; or by programmatically creating and populating the topic map.

TopicMapSource

The TopicMapSource interface is an abstraction of some combination of data and/or processing which generates a topic map. The most commmon source of a topic map is a topic map file in XTM or LTM syntax which generates a topic map when it is processed by a TopicMapBuilder. However, other sources may also generate topic maps, for example TMHarvest is a subproject of the TM4J project which generates topic maps by processing sources such as CSV files, document meta data, and arbitrary XML documents by applying user-defined rules. The TopicMapSource interface allows a TMHarvest process to be treated in the same way as a normal XTM file. When you pass the TopicMapSource to a TopicMapProvider, the TopicMapSource's processing is invoked to populate a TopicMap managed by the provider.

TM4J ships with one implementation of the TopicMapSource interface, org.tm4j.topicmap.source.SerializedTopicMapSource. This implementation is capable of parsing from both XTM and LTM syntax files. It encapsulates all of the logic for performing the parse, making it possible to import a file without having to set up and configure XML parsers or worry about differentiating between XTM and LTM files. An example of the use of the SerializedTopicMapSource class can be found in the section called “Parsing Topic Maps From File”.

TopicMap

The TopicMap interface represents a single topic map in the storage managed by its parent TopicMapProvider. While a TopicMap object may often represent a single XTM or LTM file, it is also possible that a TopicMap object actually represents the results of merging several such files and/or programmatically creating, modifying or removing items. As well as representing the topic map, the TopicMap interface provides access to the indexes and utilities which are needed by the developer to work with the topic map information.

The TopicMap interface also provides factory methods for creating Topic and Association objects (see the section called “Factory Methods”).

LocatorFactory

The LocatorFactory interface provides methods for creating objects which represent resource addresses. There is exactly one LocatorFactory instance for every TopicMapProvider instance, which may be retrieved either by calling the getLocatorFactory() method of the TopicMapProvider interface, or by calling the getLocatorFactory() method of the TopicMap interface.

Locator

The Locator interface provides a notation-independent construct for representing resource addresses. Although in practice most applications will only ever use URI notation addresses for pointing to resources, TM4J allows other notations to be handled within its framework. In TM4J, all resource addresses are simply strings in a specified notation. A Locator instance is therefore is simply a store of the address notation and the address string itself. The Locator interface also defines the basic operations which may be performed on such an address. You can get and set both the notation and address strings and you can use one Locator as the base locator to resolve another, relative address. Obviously, the logic for doing this is notation-specific and TM4J provides a way for you to hook in your own implementations of the Locator interface with the LocatorFactory as described in the section called “Locators”.

TopicMapFactory

The TopicMapFactory interface provides methods to assist in copying objects from one TopicMap to another.

The copy methods allow both deep and shallow copies of objects to be made. A deep copy copies the object and all of its child objects and references. A shallow copy makes a copy of the object itself and in some cases some of its child objects, but references to Topics are not copied in a shallow copy.

Copying using the TopicMapFactory is covered in more detail in the section called “Copying Topic Map Objects”.

IndexManager

The IndexManager interface provides access to indexes of the objects contain in a single topic map. Each TopicMap instance has exactly one IndexManager instance which may be retrieved by calling the getIndexManager method of the TopicMap interface. The IndexManager interface provides access to any number of instances of the Index interfafce, each of which may be retrieved by calling the getIndex method of the IndexManager interface.

This interface is described in more detail in the section called “The IndexManager Interface”

Index

The Index interface represents a single index of objects in a single topic map. The Index interface itself does not specify methods for querying the index - those are defined by the interfaces subclassed from the Index interface. However, the Index interface does define common methods for opening and closing indexes and for determining whether or not an index is open. Instances of the Index interface are only ever retrieved by calling the getIndex method of the IndexManager interface.

This interface is described in more detail in the section called “The Index Interface”