org.geotools.factory
Class FactoryRegistry

java.lang.Object
  javax.imageio.spi.ServiceRegistry
      org.geotools.factory.FactoryRegistry

Direct Known Subclasses:

FactoryCreator

public class FactoryRegistry

extends javax.imageio.spi.ServiceRegistry

A registry for factories, organized by categories (usualy by interface).

For example CRSFactory.class is a category, and MathTransformFactory.class is an other category.

For each category, implementations are registered in a file placed in the directory, as specified in the ServiceRegistry javadoc. Those files are usually bundled into the JAR file distributed by the vendor. If the same file appears many time in different JARs, they are processed as if their content were merged.

Example use:

 Set categories = Collections.singleton(new Class[] {MathTransformProvider.class});
 FactoryRegistry registry = new FactoryRegistry(categories);
 
 // get the providers
 Iterator providers = registry.getProviders(MathTransformProvider.class)
 

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

Version:

$Id: FactoryRegistry.java 18017 2006-02-14 11:41:34Z desruisseaux $

Author:

Martin Desruisseaux, Richard Gould, Jody Garnett

See Also:

FactoryFinder

Nested Class Summary

Nested classes inherited from class javax.imageio.spi.ServiceRegistry

javax.imageio.spi.ServiceRegistry.Filter

Field Summary

protected static java.util.logging.Logger

LOGGER The logger for all events related to factory registry.

Constructor Summary

FactoryRegistry(java.util.Collection categories)
Constructs a new registry for the specified categories.

Method Summary

java.util.Set	getClassLoaders() Returns all class loaders to be used for scanning plugins.
java.lang.Object	getServiceProvider(java.lang.Class category, javax.imageio.spi.ServiceRegistry.Filter filter, Hints hints, Hints.Key key) Returns the first provider in the registry for the specified category, using the specified map of hints (if any).
java.util.Iterator	getServiceProviders(java.lang.Class category) Returns the providers in the registry for the specified category.
protected boolean	isAcceptable(java.lang.Object provider, java.lang.Class category, Hints hints) Returns if the specified meets the requirements specified by a map of .
void	scanForPlugins() Scans for factory plug-ins on the application class path.
boolean	setOrdering(java.lang.Class base, boolean set, javax.imageio.spi.ServiceRegistry.Filter service1, javax.imageio.spi.ServiceRegistry.Filter service2) Sets or unsets a pairwise ordering between all services meeting a criterion.
boolean	setOrdering(java.lang.Class category, java.util.Comparator comparator) Set pairwise ordering between all services according a comparator.

Methods inherited from class javax.imageio.spi.ServiceRegistry

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

Methods inherited from class java.lang.Object

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

Field Detail

LOGGER

protected static final java.util.logging.Logger LOGGER

The logger for all events related to factory registry.

Constructor Detail

FactoryRegistry

public FactoryRegistry(java.util.Collection categories)

Constructs a new registry for the specified categories.

Parameters:

categories - The categories.

Method Detail

getServiceProviders

public java.util.Iterator getServiceProviders(java.lang.Class category)

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

Parameters:

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

Returns:

Factories ready to use for the specified category.

getServiceProvider

public java.lang.Object getServiceProvider(java.lang.Class category,
                                           javax.imageio.spi.ServiceRegistry.Filter filter,
                                           Hints hints,
                                           Hints.Key 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 FactoryCreator class change this behavior however.

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 if none. This is used for example in order to select the first factory for some authority.

hints - A map of hints, or if none.

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

Returns:

A factory ready to use for the specified category and hints. The returns type is instead of Factory because the factory implementation doesn't need to be a Geotools 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), FactoryCreator.getServiceProvider(java.lang.Class, javax.imageio.spi.ServiceRegistry.Filter, org.geotools.factory.Hints, org.geotools.factory.Hints.Key)

isAcceptable

protected boolean isAcceptable(java.lang.Object provider,
                               java.lang.Class category,
                               Hints hints)

Returns if the specified meets the requirements specified by a map of . This method is invoked automatically when the is known to meets standard requirements.

The default implementation always returns . Override this method if more checks are needed, typically for non-Geotools implementation. For example a JTS geometry factory finder may overrides this method in order to check if a GeometryFactory uses the required CoordinateSequenceFactory.

Parameters:

provider - The provider to checks.

category - The factory's category. Usually an interface class.

hints - The user requirements.

Returns:

if the meets the user requirements.

getClassLoaders

public final java.util.Set 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.

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 boolean setOrdering(java.lang.Class category,
                           java.util.Comparator comparator)

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

• if is preferred to
• if is preferred to
• if there is no preferred order between and

Parameters:

category - The category to set ordering.

comparator - The comparator to use for ordering.

Returns:

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

setOrdering

public boolean setOrdering(java.lang.Class base,
                           boolean set,
                           javax.imageio.spi.ServiceRegistry.Filter service1,
                           javax.imageio.spi.ServiceRegistry.Filter service2)

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

Parameters:

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

set - for setting the ordering, or for unsetting.

service1 - filter for the preferred service.

service2 - filter for the service to which is preferred.