The Core Interfaces

The core TM4J API consists of a number of interfaces which represent the basic constructs of a topic map, plus implementations of those interfaces which are held in memory. However, not all constructs of the XTM 1.0 specification map directly to an interface and implementation in the core API.

Some of the interfaces provide "factory" methods which are used to create child objects. So, for example the TopicMap interface provides methods to create Topic, Association and Scope objects which are all created as children of the TopicMap object on which the factory method was invoked.

The following table shows which elements of the XTM 1.0 interchange DTD map to interfaces and implementations in the API, and what objects can be created as child objects of that implementation using factory methods.

Table 3.2. TM4J Interfaces and their relation to objects in the XTM data model and DTD

XTM ElementTM4J InterfaceProvides Factory Metods For
<topic>org.tm4j.topicmap.Topicorg.tm4j.topicmap.BaseName
  org.tm4j.topicmap.Occurrence
<topicMap>org.tm4j.topicmap.TopicMaporg.tmj.topicmap.Topic
  org.tmj.topicmap.Association
<baseName>org.tm4j.topicmap.BaseNameorg.tm4j.topicmap.Variant
<variant>org.tm4j.topicmap.Variantorg.tm4j.topicmap.VariantName
  org.tm4j.topicmap.Variant
<variantName>org.tm4j.topicmap.VariantName 
<association>org.tm4j.topicmap.Associationorg.tm4j.topicmap.Member
<member>org.tm4j.topicmap.Member 
<occurrence>org.tm4j.topicmap.Occurrence 

Note that the above list does not cover all of the element types found in the XTM 1.0 DTD. Most of the other element types are represented as properties in one of the interfaces listed in the table above. For example, the <instanceOf> element is represented by the type property of the Association and Occurrence interfaces and by the types property of the Topic interface and these properties may be accessed using the getType() or getTypes() and setType() or setTypes() methods of those interfaces.

The diagram below shows the inheritance hierarchy of the core interfaces. The diagram uses standard UML static structure notation.

Figure 3.2. TM4J Core Interface Hierarchy

TM4J Core Interface Hierarchy

As you will see from the diagram, there are three interfaces which do not have a direct mapping to an XTM element. These are TopicMapObject, DataObject, and VariantContainer.

The interface DataObject provides an interface for accessing the data value of an object that can have either a String or a Locator data value. This interface is common to both the Occurrence and VariantName interfaces. The data provides access to the String value and the dataLocator property provides access to the Locator value. Only one of these properties can be non-NULL at any given time, so setting the data property will not only overwrite any previous value for that property, but will also set the dataLocator property to NULL and vice-versa. This interface also provides a method isDataInline which returns true if the data property is not NULL and false if the dataLocator property is not NULL.

The interface VariantContainer defines a common interface for objects which can have one or more Variant objects as chilren. The interface defines a Collection property variants and methods for accessing and manipulating the value of this property. This interface is common to the BaseName and Variant interfaces.

The TopicMapObject interface is common to all interfaces that represent some construct in a topic map. It provides a number of common methods and services and is described in more detail in the next section.