org.geotoolkit.factory
Class FactoryRegistry

Object
  ServiceRegistry
      FactoryRegistry

Direct Known Subclasses:

DynamicFactoryRegistry

@NotThreadSafe
public class FactoryRegistry
extends ServiceRegistry

A registry for factories organized by categories. A category is an interface for a service as described in the package javadoc. FactoryRegistry extends ServiceRegistry with the following functionalities:

• A scanForPlugins() method that scans for plugins in the registry class loader, the thread context class loader and the system class loader.

• When more than one implementation is available for the same Factory subclass, an optional set of hints can specifies the criterion that the desired implementation must meets. If a factory implementation depends on other factories, the dependencies hints are checked recursively.

• Optionally, if no factory matches the given hints, a new instance can be automatically created.

When more than one factory implementation is registered for the same category, the actual instance to be used is selected according their ordering and user-supplied hints. Hints have precedence. If more than one factory matches the hints (including the common case where the user doesn't provide any hint at all), then ordering matter.

NOTE: This class is not thread safe. Users are responsible for synchronization. This is usually done in an utility class wrapping this service registry (e.g. FactoryFinder).

Since:

2.1

Version:

3.03

Author:

Martin Desruisseaux (IRD, Geomatys), Richard Gould, Jody Garnett (Refractions)

See Also:

Factory, Hints

Module:

utility/geotk-utility (download)

View source code for this class

Nested Class Summary

Nested classes/interfaces inherited from class ServiceRegistry

ServiceRegistry.Filter

Field Summary

protected static Logger

LOGGER The logger for all events related to factory registry.

Constructor Summary

FactoryRegistry(Class<?> category)
Constructs a new registry for the specified category.

FactoryRegistry(Class<?>[] categories)
Constructs a new registry for the specified categories.

FactoryRegistry(Collection<Class<?>> categories)
Constructs a new registry for the specified categories.

Method Summary

Set<ClassLoader>	getClassLoaders() Returns all class loaders to be used for scanning plugins.
<T> T	getServiceProvider(Class<T> category, ServiceRegistry.Filter filter, Hints hints, Hints.ClassKey key) Returns the first provider in the registry for the specified category, using the specified map of hints (if any).
<T> Iterator<T>	getServiceProviders(Class<T> category, ServiceRegistry.Filter filter, Hints hints, Hints.ClassKey key) Returns the providers in the registry for the specified category, filter and hints.
protected <T> boolean	isAcceptable(T provider, Class<T> category, Hints hints) Returns true if the specified provider meets the requirements specified by a map of hints.
void	scanForPlugins() Scans for factory plug-ins on the application class path.
<T> boolean	setOrdering(Class<T> category, Comparator<T> comparator) Sets pairwise ordering between all factories according a comparator.
<T> boolean	setOrdering(Class<T> base, ServiceRegistry.Filter service1, ServiceRegistry.Filter service2) Sets or unsets a pairwise ordering between all factories meeting a criterion.
String	toString() Returns a string representation of this registry for debugging purpose.
<T> boolean	unsetOrdering(Class<T> base, ServiceRegistry.Filter service1, ServiceRegistry.Filter service2) Unset an previously set ordering.

Methods inherited from class ServiceRegistry

contains, deregisterAll, deregisterAll, deregisterServiceProvider, deregisterServiceProvider, finalize, getCategories, getServiceProviderByClass, getServiceProviders, getServiceProviders, lookupProviders, lookupProviders, registerServiceProvider, registerServiceProvider, registerServiceProviders, setOrdering, unsetOrdering

Methods inherited from class Object

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

Field Detail

LOGGER

protected static final Logger LOGGER

The logger for all events related to factory registry.

Constructor Detail

FactoryRegistry

public FactoryRegistry(Class<?> category)

Constructs a new registry for the specified category.

Parameters:

category - The single category.

Since:

2.4

FactoryRegistry

public FactoryRegistry(Class<?>[] categories)

Constructs a new registry for the specified categories.

Parameters:

categories - The categories.

Since:

2.4

FactoryRegistry

public FactoryRegistry(Collection<Class<?>> categories)

Constructs a new registry for the specified categories.

Parameters:

categories - The categories.

Method Detail

getServiceProviders

public <T> Iterator<T> getServiceProviders(Class<T> category,
                                           ServiceRegistry.Filter filter,
                                           Hints hints,
                                           Hints.ClassKey key)

Returns the providers in the registry for the specified category, filter and hints. Providers that are not available will be ignored. This method will scan for plugins the first time it is invoked for the given category.

Type Parameters:

T - The class represented by the category argument.

Parameters:

category - The category to look for. Usually an interface class (not the actual implementation class).

filter - The optional filter, or null.

hints - The optional user requirements, or null.

key - The key to use for looking for a user-provided instance in the hints map, or null if none.

Returns:

Factories ready to use for the specified category, filter and hints.

Since:

3.03 (derived from 2.3)

getServiceProvider

public <T> T getServiceProvider(Class<T> category,
                                ServiceRegistry.Filter filter,
                                Hints hints,
                                Hints.ClassKey key)
                     throws FactoryRegistryException

Returns the first provider in the registry for the specified category, using the specified map of hints (if any). This method may scan for plugins the first time it is invoked. Except as a result of this scan, no new provider instance is created by the default implementation of this method. The DynamicFactoryRegistry class change this behavior however.

Type Parameters:

T - The class represented by the category argument.

Parameters:

category - The category to look for. Must be one of the categories declared to the constructor. Usually an interface class (not the actual implementation class).

filter - An optional filter, or null if none. This is used for example in order to select the first factory for some authority.

hints - A map of hints, or null if none.

key - The key to use for looking for a user-provided instance in the hints, or null if none.

Returns:

A factory available for use for the specified category and hints. The returns type is Object instead of Factory because the factory implementation doesn't need to be a Geotk one.

Throws:

FactoryNotFoundException - if no factory was found for the specified category, filter and hints.

FactoryRegistryException - if a factory can't be returned for some other reason.

See Also:

getServiceProviders(java.lang.Class, javax.imageio.spi.ServiceRegistry.Filter, org.geotoolkit.factory.Hints, org.geotoolkit.factory.Hints.ClassKey), getServiceProvider(java.lang.Class, javax.imageio.spi.ServiceRegistry.Filter, org.geotoolkit.factory.Hints, org.geotoolkit.factory.Hints.ClassKey)

isAcceptable

protected <T> boolean isAcceptable(T provider,
                                   Class<T> category,
                                   Hints hints)

Returns true if the specified provider meets the requirements specified by a map of hints. The default implementation always returns true. There is no need to override this method for Factory implementations, since their hints are automatically checked. Override this method for non-Geotk implementations. For example a JTS geometry factory finder may overrides this method in order to check if a com.vividsolutions.jts.geom.GeometryFactory uses the required com.vividsolutions.jts.geom.CoordinateSequenceFactory. Such method should be implemented as below, since this method may be invoked for various kind of objects:

if (provider instanceof GeometryFactory) {
    // ... Check the GeometryFactory state here.
}

Type Parameters:

T - The class represented by the category argument.

Parameters:

provider - The provider to check.

category - The factory category. Usually an interface.

hints - The user requirements, or null if none.

Returns:

true if the provider meets the user requirements.

getClassLoaders

public Set<ClassLoader> getClassLoaders()

Returns all class loaders to be used for scanning plugins. Current implementation returns the following class loaders:

• This object class loader
• The thread context class loader
• The system class loader

The actual number of class loaders may be smaller if redundancies was found. If some more classloaders should be scanned, they shall be added into the code of this method.

Returns:

All classloaders to be used for scanning plugins.

scanForPlugins

public void scanForPlugins()

Scans for factory plug-ins on the application class path. This method is needed because the application class path can theoretically change, or additional plug-ins may become available. Rather than re-scanning the classpath on every invocation of the API, the class path is scanned automatically only on the first invocation. Clients can call this method to prompt a re-scan. Thus this method need only be invoked by sophisticated applications which dynamically make new plug-ins available at runtime.

setOrdering

public <T> boolean setOrdering(Class<T> category,
                               Comparator<T> comparator)

Sets pairwise ordering between all factories according a comparator. Calls to compare(factory1, factory2) should returns:

• -1 if factory1 is preferred to factory2
• +1 if factory2 is preferred to factory1
• 0 if there is no preferred order between factory1 and factory2

Type Parameters:

T - The class represented by the category argument.

Parameters:

category - The category to set ordering.

comparator - The comparator to use for ordering.

Returns:

true if at least one ordering setting has been modified as a consequence of this call.

setOrdering

public <T> boolean setOrdering(Class<T> base,
                               ServiceRegistry.Filter service1,
                               ServiceRegistry.Filter service2)

Sets or unsets a pairwise ordering between all factories meeting a criterion. For example in the CRS framework, this is used for setting ordering between all factories provided by two vendors, or for two authorities. If one or both factories are not currently registered, or if the desired ordering is already set/unset, nothing happens and false is returned.

Type Parameters:

T - The class represented by the base argument.

Parameters:

base - The base category. Only categories assignable to base will be processed.

service1 - Filter for the preferred factory.

service2 - Filter for the factory to which service1 is preferred.

Returns:

true if the ordering changed as a result of this call.

unsetOrdering

public <T> boolean unsetOrdering(Class<T> base,
                                 ServiceRegistry.Filter service1,
                                 ServiceRegistry.Filter service2)

Unset an previously set ordering.

Type Parameters:

T - The class represented by the base argument.

Parameters:

base - The base category. Only categories assignable to base will be processed.

service1 - Filter for the preferred factory.

service2 - Filter for the factory to which service1 was preferred.

Returns:

true if the ordering changed as a result of this call.

toString

public String toString()

Returns a string representation of this registry for debugging purpose. The default implementation list the providers in a tabular format.

Overrides:

toString in class Object

Returns:

A string representation of this registry content.