org.tm4j.topicmap
Class TopicMapProviderFactory

java.lang.Object
  org.tm4j.topicmap.TopicMapProviderFactory

public abstract class TopicMapProviderFactory

extends java.lang.Object

Abstract class to be extended by implementations which allow access to TopicMaps using the TopicMapProvider interface. This class enables an application to retrieve a TopicMapProvider.

TM4J applications retrieve instances of this class using the newInstance() method, which selects, instantiates and returns the appropriate concrete implementation as determined by the following algorithm (listed here in descending order of precedence):

1. Look for a system property named org.tm4j.topicmap.TopicMapProviderFactory; if found, it is expected to contain the fully-qualified class name of the concrete, back end-dependent implementing class. If that system property is found, but the corresponding class cannot be loaded or instantiated, this is considered an error condition and newInstance() will throw a TopicMapProviderFactoryConfigurationError.
2. Likewise, look for a system property named provider, handle it equivalently. This is purely for reasons of backwards compatibility and will go away in future releases.
3. Find a resource on the Java classpath named META-INF/services/org.tm4j.topicmap.TopicMapProviderFactory; if found, it is expected to contain a single line of text denoting the fully-qualified class name of the concrete implementation class. This in line with the "Service Provider" section of the JAR File Specification. If that resource is found, but cannot be read, or the corresponding class cannot be loaded or instantiated, this is considered an error condition and newInstance() will throw a TopicMapProviderFactoryConfigurationError.
4. If neither an appropriate system property nor the service provider configuration file could be found, instantiate and return the default implementation, org.tm4j.topicmap.memory.TopicMapProviderFactoryImpl.

After the class has been properly instantiated, TopicMapProviders may be created using newTopicMapProvider() or newTopicMapProvider(Properties). The implementing subclass will ensure that the returned TopicMapProviders are appropriate for the underlying back-end implementation.

This approach enables TM4J application developers to write their applications in a back end-independent manner, leaving it up to the users to select the appropriate back-end implementation that best fits their requirements.

Author:

Kal Ahmed, Florian G. Haas

Constructor Summary

protected

TopicMapProviderFactory() The default constructor is protected on purpose.

Method Summary

TopicMapProvider	createTopicMapProvider(java.util.Properties props) Deprecated. as of 0.8.4, this method only invokes newTopicMapProvider(Properties), by which it will be replaced in the future.
static TopicMapProviderFactory	newInstance() Creates and returns a new instance of this class.
TopicMapProvider	newTopicMapProvider() Creates and returns a TopicMapProvider which may be used to retrieve one or more topic maps from the implementation's underlying store.
abstract TopicMapProvider	newTopicMapProvider(java.util.Properties props) Creates and returns a TopicMapProvider which may be used to retrieve one or more topic maps from the implementation's underlying store.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TopicMapProviderFactory

protected TopicMapProviderFactory()

The default constructor is protected on purpose. New instances should be created using the newInstance() method.

Method Detail

createTopicMapProvider

public TopicMapProvider createTopicMapProvider(java.util.Properties props)
                                        throws TopicMapProviderException

Deprecated. as of 0.8.4, this method only invokes newTopicMapProvider(Properties), by which it will be replaced in the future.

Creates and returns a TopicMapProvider object which may be used to retrieve one or more topic maps from the implementation's underlying store.

Parameters:

props - The configuration properties for the provider.

Returns:

The new TopicMapProvider object

Throws:

TopicMapProviderException

newTopicMapProvider

public TopicMapProvider newTopicMapProvider()
                                     throws TopicMapProviderException

Creates and returns a TopicMapProvider which may be used to retrieve one or more topic maps from the implementation's underlying store. The default implementation initializes the newly created TopicMapProvider with an empty set of configuration properties.

Returns:

The new TopicMapProvider object

Throws:

TopicMapProviderException

Since:

0.8.4

newTopicMapProvider

public abstract TopicMapProvider newTopicMapProvider(java.util.Properties props)
                                              throws TopicMapProviderException

Creates and returns a TopicMapProvider which may be used to retrieve one or more topic maps from the implementation's underlying store.

Parameters:

props - The configuration properties for the provider.

Returns:

The new TopicMapProvider object

Throws:

TopicMapProviderException

Since:

0.8.4

newInstance

public static TopicMapProviderFactory newInstance()

Creates and returns a new instance of this class. The concrete implementation returned depends on the class selection algorithm as described above.

Returns:

a new instance of the appropriate concrete implementation of this base class.

Throws:

TopicMapProviderFactoryConfigurationError - if the new instance could not be created. This may be due to the implementing subclass not being found by the class loader, a failure in class instantiation, or failure to read a service provider configuration file. The original exception is passed to the TopicMapProviderFactoryConfigurationError as its root cause.

Since:

0.8.4