Package org.tmapi.index

This package defines the core of the TMAPI indexing interfaces.

See:
Description

Interface Summary

Index	Abstract representation of a topic map index.
IndexFlags	Interface representing static index meta data.

Exception Summary

TMAPIIndexException

Class of exceptions raised by index access and update methods.

Package org.tmapi.index Description

This package defines the core of the TMAPI indexing interfaces.

The TMAPI index interface model is an extensible set of interfaces each of which provide a different index of the objects in a single TopicMap. Each Index implements an interface derived from the org.tmapi.index.Index interface which is extended to provide the index-specific functions.

The steps in creating and accessing an index are as follows:

1. Call the method TopicMap.getHelperObject(Class) to get an implementation of an index. The value of the Class parameter passed to this method must be a Class instance that represents the Index interface you want to use.
   NOTE you should specify the interface that you want the returned Index to implement, not the specific implementaton class. For example, to get a TMAPI core Associations index implementation you would use the code:

   tm.getHelperObject(org.tmapi.index.core.AssociationsIndex.class);

   The return type of the getHelperObject method is java.lang.Object so you will need to cast the return value to the index interface you wanted:

   AssociationsIndex ix = (AssociationsIndex) tm.getHelperObject("org.tmapi.index.core.AssociationsIndex");

2. You may now access the index. Before accessing the index for the first time, you must first call the Index.open() method. This call initialises the index. Depending upon the implementation, opening an index may take some time, so you should only invoke this function when necessary. To check if an index is already open, use the Index.isOpen() method.
3. Once the index is open, use the methods of the interface that the index implements to access the index. For example, the interface org.tmapi.index.core.AssociationsIndex defines two methods: getAssociationsOfType(Topic) and getAssociationTypes().
4. As the topic map that the index is for changes, some index implementations will be able to automatically reflect those changes whereas other index implementations will require an explicit call to reindex them. This property of the index can be determined by retrieving the IndexFlags object for the Index by calling Index.getFlags(). The IndexFlags object provides methods for retrieving meta-data about the index implementation. Currently only the method IndexFlags.isAutoUpdated() is defined. If this method returns true then the index stays in synch with the indexed TopicMap as it is modified. If this method returns false then you must make a call to Index.reindex() to force the index to synchronise itself to the indexed TopicMap.
5. When you are finished using the Index in your application, you should call the Index.close() method. Depending upon the implementation, this may free up system resources that were used by the index.