In order to ensure consistent and correct initialisation of a back-end storage model, applications should not create instances of the TopicMapProvider interface directly. Instead you should either use the newTopicMapProvider() method of the TopicMapProviderFactory class to create the TopicMapProvider, or initialise a new instance of the TopicMapProviderFactory implementation provided by the backend storage model you are using. Table 3.3, “TopicMapProviderFactory Implemenatations in TM4J” shows the current TopicMapProviderFactory implementations shipped with TM4J.

The method newInstance on the class org.tm4j.topicmap.TopicMapProviderFactory implements a search mechanism which checks the runtime environment for configuration information specifying which concrete implementation should be instantiated. The search procedure is as follows:

Once a concrete implementation of the TopicMapProviderFactory class is retrieved, the method newTopicMapProvider() can be used to initialise the TopicMapProvider object which represents your connection to the back-end storage model. You can optionally invoke this method with a Java Properties object which contains parameters for initialisation of the connection to the back-end store.

Each storage model will accept and process a different set of properties. To find out what parameters are expected and processed by this method, check the documentation for the back-end specific implementation of this interface (e.g. org.tm4j.topicmap.memory.TopicMapProviderImpl). You may choose, for example to simply pass the system properties (defined by the user on the command line in to this method, giving the user complete control over the initialisation of the back-end, or you may elect to provide the user with some more convenient UI for providing this configuration information.

The following example shows how a connection to a user-specificed provider can be made. The example makes use of the default search path of the TopicMapProviderFactory class. This means that to specify the backend to be used, the user need only provide a value for the System property org.tm4j.topicmap.TopicMapProviderFactory. Also the System properties are passed into the newTopicMapProvider method, so any configuration parameters can also be specified by the user as System properties.

// The following should appear somewhere at the top of the source file
import org.tm4j.topicmap.*;

...

try
{
  // Ask the TopicMapProviderFactory for a concrete implementation
  TopicMapProviderFactory tmpf = TopicMapProviderFactory.newInstance();

  // Ask the factory for a TopicMapProvider
  // In this case the system properties are used to initialise the TopicMapProvider
  // Your application may get the back-end configuration properties from some other source
  TopicMapProvider provider = tmpf.newTopicMapProvider(System.getProperties());
}
catch(TopicMapProviderFactoryConfigurationError ex)
{
  // Report the exception
  System.err.println("Error in specification of provider factory: " + ex.toString());
}
catch(TopicMapProviderException ex)
{
  // Report the exception
  System.err.println("Error creating back-end connection: " + ex.toString());
}
	  

// The following should appear somewhere at the top of the source file
import org.tm4j.topicmap.*;
import org.tm4j.topicmap.hibernate.TopicMapProviderFactoryImpl;

...

try
{
  // Create an instance of the Hibernate TopicMapProviderFactory
  TopicMapProviderFactory tmpf = new TopicMapProviderFactoryImpl();

  // Ask the factory for a TopicMapProvider
  // In this case, the configuration properties are read from a file
  Properties providerProps = new Properties();
  providerProps.load(new FileInputStream("provider.properties"));
  
  TopicMapProvider provider = tmpf.newTopicMapProvider(providerProps);
}
catch(TopicMapProviderException ex)
{
  // Report the exception
  System.err.println("Error creating back-end connection: " + ex.toString());
}
catch(IOException ex)
{
  // Thrown if the properties file could not be read
  System.err.println("Failed to find or read provider.properties file: " + ex.toString());
}

tm4j.topicmap.1 = /data/topicmaps/mytopicmap.xtm
tm4j.topicmap.2 = /data/topicmaps/geolang.xtm
tm4j.topicmap.base.2 = http://www.example.com/topicmaps/geolang.xtm
tm4j.topicmap.3 = /data/topicmaps/orgchart.lt
tm4j.topicmap.base.3 = http://www.example.com/topicmaps/orgchart.lt
tm4j.topicmap.notation.3 = LTM
tm4j.topicmap.5 = /data/topicmaps/i_am_not_loaded.xtm

	    

dburl=ozonedb:remote://localhost:3333

dburl=ozonedb:local:/data/ozone/topicmaps

hibernate.dialect=net.sf.hibernate.dialect.MySQLDialect
hibernate.connection.driver_class=com.mysql.jdbc.Driver
hibernate.connection.url=jdbc:mysql://localhost/tm4j-test
hibernate.connection.username=topicmap_user
hibernate.connection.password=iluvtms

Every topic map managed by a provider is identified by a Locator object. To retrieve the list of identifiers of topic maps known to the provider, call the method: getTopicMapBaseLocators(). This method returns a collection of Locator objects. To retrieve a specific TopicMap object, use the method: getTopicMap(Locator loc) passing in the base locator of the topic map you wish to retrieve.

The org.tm4j.topicmap.source.TopicMapSource interface is used to represent the combination of data and processing needed to populate a topic map. The standard implementation of this interface provided by the class org.tm4j.topicmap.source.SerializedTopicMapSource represents a serialized file (in XTM or LTM syntax) and the parsing logic for the file. To import a topic map into a provider, simply create the TopicMapSource implementation that represents your data, and pass it to one of the addTopicMap() methods of the TopicMapProvider interface.

You may choose to import a topic map from a TopicMapSource into an existing TopicMap managed by the provider. This can be done by using the addTopicMap() methods that take the existing TopicMap object as a parameter. As the TopicMapSource is processed, it will be merged with the exising TopicMap.

The method createTopicMap() can be used to create a new TopicMap object in the back-end storage managed by the TopicMapProvider object. You must pass this method a Locator object which specifies the URI of the topic map resource itself. To get a Locator object you need to use the LocatorFactory provided by the getLocatorFactory method of TopicMapProvider. This is shown in the example below.

TopicMapProviderFactory tmpf = new org.tm4j.topicmap.memory.TopicMapProviderFactoryImpl();
TopicMapProvider tmp;
		
//
// Create the TopicMapProvider (see "Creating The TopicMapProvider", above)
//
		
try
{
  Locator base = tmp.getLocatorFactory().createLocator("URI",
                                       "http://mycorp.com/xtm/mymap.xtm");
  TopicMap tm = tmp.createTopicMap(base);
}
catch(LocatorFactoryException ex)
{
  System.out.println("Error creating locator: " + ex.getMessage());
}
catch(TopicMapProviderException ex)
{
  System.out.println("Error creating new topic map: " + ex.getMessage());
}