Example 6.2. Sample Code - Using IndexProviders

The following code shows how to apply a new IndexProvider to an IndexManager.

// Assuming that the topic map is already initialised
// and held in the variable tm.

// Assuming, also that the new IndexProvider interface is
// com.mycorp.tm4j.index.MyIndexProvider

// Note that if you have imported the pacakge symbols for 
// MySpecialIndex and MyIndexProvider explicitly, you can omit the
// long package names.

// Get the index manager fro the topic map
IndexManager im = tm.getIndexManager();

// Get a new instance of MyIndexProvider
IndexProvider myIxProvider = new com.mycorp.tm4j.index.MyIndexProvider();

// Register the IndexProvider
im.registerIndexProvider(myIndexProvider);

// We can now access the index interfaces that MyIndexProvider provides:
com.mycorp.tm4j.index.MySpecialIndex specialIndex = 
    (com.mycorp.tm4j.index.MySpecialIndex) im.getIndex (
                   com.mycorp.tm4j.index.MySpecialIndex.class);

Example 6.3. Sample Code - Creating a new IndexProvider

The following code sample shows a customised IndexProvider implementation which provides access to a single index. Although the code shown here has only one index in the provider, the pattern can be easily extended to support multiple indexes. You can find all of this code and the supporting files as well as a test application to run it in the examples subdirectory of your TM4J installation.

package examples.indexes;

import org.tm4j.topicmap.TopicMap;
import org.tm4j.topicmap.Occurrence;

import org.tm4j.topicmap.index.Index;
import org.tm4j.topicmap.index.IndexMeta;
import org.tm4j.topicmap.index.IndexMetaImpl;
import org.tm4j.topicmap.index.IndexProvider;

/**
 * A sample custom index provider.
 * <p>This index provider manages just one index implementation, however 
 * the basic design is extensible to support multiple indexes in a single
 * provider.</p>
 */

public class CustomIndexProvider implements IndexProvider
{
    /**
     * The class names of the indexes provided by this IndexProvider.
     */
    private static final String[] indexNames = { 
        "examples.indexes.CustomIndex" 
    };
    
    /**
     * The classes of the indexes provided by this IndexProvider. 
     * Note that these are in the same order as the class names in
     * <code>indexNames</code>
     */
    private static final Class[] indexClasses = { 
        examples.indexes.CustomIndex.class };

    /**
     * An array to hold the index instances once the index provider is
     * initialised.
     */
    private Index[] indexInstances  = null;

    /**
     * An array to hold the index meta data objects once the index 
     * provider is initialised.
     */
    private IndexMeta[] indexMeta = null;

    // Implementation of the IndexProvider interface:

    /**
     * Returns the class names of the indexes provided by this class.
     */
    public String[] getIndexNames() 
    {
	return indexNames;
    }

    /**
     * Returns the index with the specified class name.
     * @param interfaceName the full class name of the index required.
     */
    public Index getIndex(String interfaceName)
    {
	for(int i = 0; i < indexNames.length; i++)
	{
	    if (interfaceName.equals(indexNames[i]))
	    {
		return indexInstances[i];
	    }
	}
	return null;
    }

    /**
     * Returns the index which implements the specified class.
     * In this implementation we are not using interfaces to hide the index
     * implementation so <code>interfaceClass</code> is expected to be the
     * actual implementation class of the index to be returned.
     * @param interfaceClass the class of the required index or the
     *                       interface that it implements.
     */
    public Index getIndex(Class interfaceClass)
    {
	for(int i = 0; i < indexClasses.length; i++)
	{
	    if (interfaceClass.equals(indexClasses[i]))
	    {
		return indexInstances[i];
	    }
	}
	return null;
    }

    /**
     * Returns the meta data for the specified index.
     * @param interfaceName the name of the class of index to return
     *                      meta data for or the interface that the
     *                      index implements.
     */
    public IndexMeta getIndexMeta(String interfaceName)
    {
	for(int i = 0; i < indexNames.length; i++)
	{
	    if (interfaceName.equals(indexNames[i]))
	    {
		return indexMeta[i];
	    }
	}
	return null;
    }

    /**
     * Method invoked when the provider is registered with an IndexManager.
     * <p>This implementation uses this method to intialise the indexes and
     *    index meta data.</p>
     * @param tm the TopicMap to which the IndexProvider must bind its indexes.
     */
    public void initialise(TopicMap tm)
    {
	indexInstances = new Index[1];
	indexInstances[0] = new CustomIndex(tm);

	indexMeta = new IndexMeta[1];
	indexMeta[0] = new IndexMetaImpl(false, false);
    }

}

Example 6.4. Using a Custom Index Provider

The code snippet below shows how the custom index provider shown above can be used in a TM4J application.

TopicMap tm;

// Get the topic map
....

// Get the IndexManager which binds all indexes to the topic map
IndexManager ixMgr = tm.getIndexManager();

// Create the custom IndexProvider we wish to use with the topic map
CustomIndexProvider custIxProvider = new CustomIndexProvider();

// Register the custom IndexProvider with the IndexManager
ixMgr.registerIndexProvider(custIxProvider);

// Now we can get the indexes that the IndexProvider provides directly
// from the IndexManager.
CustomIndex custIx = (CustomIndex)ixMgr.getIndex(CustomIndex.class);

// Open the index and use it
custIx.open();

System.out.println(
  "Looking for all occurrences from authority: " + searchDomain);

Collection occs = custIx.getOccurrencesByAuthority(searchDomain);

System.out.println(
  "  Found " + occs.size() + " occurrences from authority " + searchDomain);

Iterator it = occs.iterator();
while (it.hasNext())
{
  Occurrence occ = (Occurrence)it.next();
  System.out.println("    " + occ.getDataLocator().getAddress());
}

// All done! Close the index to release any resources that it used
custIx.close();