Each of the types of item defined by the topic maps data model is represented in TMAPI by an interface. The names of the interfaces may be slightly unfamiliar to users of the XTM syntax because they are based on a more abstract model of a topic map called the "Topic Maps Data Model" (TMDM). This model is currently under development as part of the next version of ISO 13250 (although it is currently thought to be stable enough for our purposes!) and so the TMAPI interfaces cover both this model and a slightly modified version of it for XTM 1.0 topic maps. For more information about TMDM see http://www.isotopicmaps.org/sam/sam-model/.
The TopicMapObject interface is the base interface for all interfaces that represent items in a topic map and for the TopicMap interface itself. The TopicMapObject interface provides access to the sourceLocators property. Source locators are identifiers for a TopicMapObject. A TopicMapObject can have any number of source locators, but it is an error for two different TopicMapObjects to have a common source locator.
The objectId property is a read-only String which specifies the unique identifier assigned to the object by the underlying TMAPI implementation. Implementations are free to use any format for the objectId string.
The TopicMapObject interface also defines some very basic equality rules. If two TopicMapObject instances return the same value for the objectId property, then the equals() method must return true, otherwise it must return false.
TMAPI does not define any operations for comparing TopicMapObject instances from different TopicMapSystem instances. You should never compare such objects directly using the equals() method nor should you rely on the hashCode() method for maintaining hashed sets/maps of TopicMapObject instances from multiple TopicMapSystem instances.
The TopicMap interface provides access to the basic properties of a topic map, including the topics and associations that it contains. This interface also defines two special methods mergeIn(TopicMap) and getHelperObject(Class).
The method TopicMap.mergeIn(TopicMap) can be used to merge one TopicMap instance into another TopicMap. The TopicMap on which the method is invoked will be modified, gaining all of the topics and associations of the other TopicMap. The other TopicMap will not be modified in anyway by this method.
The method TopicMap.getHelperObject(Class) is used to retrieve instances of particular "helper" interfaces from the underlying TopicMap implementation. In TMAPI 1.0, all of the core indexes of a TopicMap can be retrieved in this way. In future versions of TMAPI additional helper object interfaces may be defined to support import, export or query functions.
The single parameter to this method is a Class object which must be the Class object retrieved from the interface that the helper object implements. For example to retrieve the implementation of the org.tmapi.index.core.TopicsIndex for a particular topic map you would use code like this:
TopicsIndex ti = (TopicsIndex)tm.getHelperObject(TopicsIndex.class);
The exact implementation to be used is determined at run-time using a procedure almost exactly the same as that described in Lookup Procedure for TopicMapSystemFactory Implementations except with the string "org.tmapi.core.TopicMapSystemFactory" replaced by the name of the helper object interface.
You should, therefore also provide resources in /META-INF/services for each of the helper objects that you implement.
Instances of the TMAPI core interfaces should never be constructed directly. Doing this would make your code non-portable[3]. Instead each of the TMAPI core interfaces provide factory methods to create an instance and add it as a child. These methods are all named createXXX where XXX is the name of the interface that will be instantiated and added to this object. For example, the method Topic.createTopicName() creates a new TopicName instance and automatically adds it as a child of the Topic instance on which the method is invoked.
There are no methods to remove a TopicMapObject instance from its parent. An instance can only be removed by calling the remove() method which not only removes the instance from the parent, but also destroys it. You must not attempt to access a TopicMapObject after calling the remove method on it. This is vitally important and if you try and do this you are likely to end up with runtime errors (or worse!) so it bears repeating:
You MUST NOT attempt to access a TopicMapObject instance after calling its remove() method.
The following list shows the mappings that are made between XTM elements and TMAPI interfaces and properties.
Where ever the following list talks about the foo property of an interface, it means that the interface provides methods for accessing and manipulating that property. These will be getFoo() to retrieve the property value and possibly setFoo() or addFoo() to modify the property.
Whenever a subjectIndicatorRef element is encountered where its parent is not a subjectIdentity element, it is mapped to a Topic with the subjectIndicatorRef address as one of its subjectIdentifiers property values or one of its sourceLocators property values.
Whenever a topic element has a subjectIdentity/subjectIndicatorRef element that points to another XTM element, the resulting Topic instance will be specified as the value of the reifier property for the TMAPI object that represents the addressed XTM element.
The TopicName interface and topicNames property of the Topic interface map to the XTM baseName element.
The subjectLocators property of Topic maps to the subjectIdentity/resourceRef element.
Under the XTM 1.0 data model, a Topic can only have one subject locator. However the proposed XTM 1.1 data model extends this to allow a Topic to have multiple subject locators. In TMAPI, the property is represented as a Set of Locators, but if the feature for the XTM 1.0 data model is enabled, an exception will be raised if you attempt to add more than one Locator to this set.
The subjectIdentifiers property of Topic maps to the subjectIdentity/subjectIndicatorRef elements.
Each AssociationRole instance maps to one combination of roleSpec and topicRef or subjectIndicatorRef inside an association/member element. The member element actually allows multiple topicRef or subjectIndicatorRef elements to appear after the roleSpec, however in TMAPI, these are "flattened" into a list of pairs of Topics. For example given an association like this in XTM:
<association>
<instanceOf><topicRef xlink:href="#works-for"/></instanceOf>
<member>
<roleSpec><topicRef xlink:href="#employer"/></roleSpec>
<topicRef xlink:href="#boulder-rock-company"/>
</member>
<member>
<roleSpec><topicRef xlink:href="#employee"/></roleSpec>
<topicRef xlink:href="#fred"/>
<topicRef xlink:href="#barney"/>
</member>
</association>
The resulting TMAPI representation would be an Association instance containing three AssociationRole instances (in its associationRoles property).
Nested variant elements in XTM syntax are "flattened" in TMAPI to a single level of Variant children of the TopicName instance. The Variant instances have all the parameters specified on the variant element itself plus all those specified on its ancestor variant elements.
The list of parameters for a variant can be found in the scopingTopics property of the ScopedObjects interface (which is a superclass of the Variant interface).
If the content of an occurrence or baseName is a resourceData element, then the string content of the resourceData element can be retrieved from the value property of the Occurrence or TopicName interface. If the content is a resourceRef element, then the Locator which represents the address pointed to be the resourceRef link can be retrieved from the resource property instead.
[3] In fact, implementors of TMAPI are strongly advised to limit the visibility of such constructors to package scope, to discourage them from being accessed by users of the implementation.