The interface org.tmapi.index.Index defines a generic interface for an index over the data in a single TopicMap instance. The Index interface provides methods for opening and closing an index; for retrieving metadata about the index; and for forcing the reindexing of the underlying topic map. The Index interface does not define any methods for actually accessing the index. These are defined by interfaces derived from the Index interface.

Index instances are retrieved using the method TopicMap.getHelperObject() passing in a Class parameter that is the Class of the derived Index interface you want to access. For example to access an instance of the org.tmapi.index.core.TopicsIndex for a TopicMap you will use code such as the following:

TopicsIndex ti = (TopicsIndex)tm.getHelperObject(TopicsIndex.class);

The org.tmapi.index.IndexFlags interface provides access to basic metadata about an index implementation. Different TMAPI implementations will provide different forms of indexing with different runtime properties, and the IndexFlags interface allows you to determine at runtime what kind of index you are dealing with. You can retrieve the IndexFlags for an index by calling the method Index.getFlags().

In TMAPI 1.0, the IndexFlags interface defines a single method, IndexFlags.isAutoUpdated() that returns a boolean value. If this method returns true, then the index instance is automatically updated whenever the content of the topic map is altered and there is never any need to invoke the Index.reindex() method. If the isAutoUpdated() method returns false, then the index is only guaranteed to be synchronized with the content of the topic map immediately after creation and immediately after a call to reindex().

When your application no longer needs an index, it is recommended that you indicate this to the underlying implementation by calling the method Index.close(). Depending upon the implementation, calling the close() method may free up significant resources.

The following listing shows how to combine the Index methods to open, use and close an index.

  // Retrieve an index over a topic map. In this case the TopicsIndex
  TopicsIndex ti = (TopicsIndex)tm.getHelperObject(TopicsIndex.class);
  
  // Open the index
  ti.open();

  // Use the index
  Collection c = ti.getTopicsOfType(fooType);

  // ... other code here ...

  // Update the index if necessary
  if (!ti.getIndexFlags().isAutoUpdated())
    ti.reindex();

  // Use the index again
  Collection c = ti.getTopicsOfType(fooType);

  // Close the index when done
  ti.close();