Creating Topic Maps Programmatically

A new instance of the org.tm4j.topicmap.TopicMap interface may be created and added to a TopicMapProvider programmatically by using the createTopicMap() method of the TopicMapProvider interface. Every TopicMap is uniquely identified by its baseLocator, which specifies the locator address against which all references to resources outside the topic map itself should be resolved. When creating a TopicMap programatically, you may specify any locator you like for the baseLocator of the topic map, this is passed in as the only parameter to the createTopicMap() method.

Note

The baseLocator property is often useful in creating topic maps which index other resources - by using the baseLocator property and then specifying all occurrence addresses as addresses relative to the baseLocator, you can create a "portable" topic map which can be moved from one server to antoher as long as the topic map and all of the indexed resources remain in the same directory structure.

To create other objects in the topic map, you must use the factory methods provided by the parent objects. TM4J defines a strict containment relationship between classes as shown in the following table.

Table 4.1. Containment Hierarchy of TM4J core objects

ContainerContainees
TopicMapTopic, Association
TopicBaseName, Occurrence
BaseNameVariant
VariantVariantName, Variant
AssociationMember

Each container interface has methods for creating instances of its containee interfaces, which also automatically add the newly created containee instance to the list of children of the container instance. So calling the TopicMap.createTopic() method will not only create a new instance of the Topic interface, but will also add that new instance as one of the topics in the topic map.

All of the createXXX() methods support at least a single String parameter which is used to supply a unique identifier for the new object. If you pass in NULL for this parameter, the backend will automatically generate an identifier, if you pass in any other value, you are responsible for ensuring that the value is unique across all topic maps currently managed by that backend. It is strongly recommended that you pass NULL for this parameter except for very small topic maps with a short lifespan.

Some of the createXXX() methods allow other parameters which are used to initialise the object being created. For example there are a selection of createName() methods in the Topic interface which allow you to specifiy the string value of the name and the scope for the name.

Tip

Use the constructor that allows you to initialise the object you are creating as much as possible - these methods are more efficient because they do not result in multiple event notifications and for some backends they can also reduce the indexing overhead of adding the new object.