Package org.geotoolkit.factory

Utility classes which enable dynamic binding to factory implementations at runtime.

See:
Description

Interface Summary

FactoryIteratorProvider

Provides iterators over factories of specified categories.

Class Summary

AuthorityFactoryFinder	Defines static methods used to access the application's authority factory implementations.
DynamicFactoryRegistry	A factory registry having the additional capability to create new factory instances on the fly.
Factories	Static methods relative to the factories.
Factory	Base class for Geotoolkit.org factories.
FactoryFinder	Defines static methods used to access the application factory implementations.
FactoryRegistry	A registry for factories organized by categories.
Hints	A set of hints providing control on factories to be used.
Hints.ClassKey	A key for value that may be specified either as instance of T, or as Class<T>.
Hints.FileKey	Key for hints to be specified as a File.
Hints.IntegerKey	A hint used to capture a configuration setting as an integer.
Hints.Key	The type for keys used to control various aspects of the factory creation.
Hints.OptionKey	Key that allows the choice of several options.

Exception Summary

FactoryNotFoundException	Thrown when a factory can't be found in the registry.
FactoryRegistryException	Thrown when a factory can't be found or can't be instantiate.
RecursiveSearchException	Thrown when FactoryRegistry is invoked recursively for the same category.

Package org.geotoolkit.factory Description

Utility classes which enable dynamic binding to factory implementations at runtime. Because Geotk core API consists mostly of interfaces (including GeoAPI), factories play a role in how developers use the API. Although the interfaces that are declared in GeoAPI are implemented in various Geotk packages, they should not be used directly. Instead they should be obtained through factories.

Factories are some interfaces that define services (also called providers) for instantiating other objects. In the Geotk library they extend the Factory class, but this is not mandatory. For example the CRSAuthorityFactory GeoAPI interface (implemented in Geotk by ReferencingObjectFactory) is a service allowing instantiation of CoordinateReferenceSystem objects from identifiers.

Factories are registered for use in a services registry, which acts as a container for service implementations. Service registries don't need to be a Geotk implementation. They can be (but are not limited to) instances of:

• ServiceLoader provided since Java 6
• ServiceRegistry provided since Java 4
• FactoryRegistry provided since GeoTools 2.1

Getting started
FactoryFinder and AuthorityFactoryFinder provide convenience static methods for getting implementations of service interfaces. They are the only methods for getting started with Geotk factories.

Registering a factory
To declare a factory implementation, a services subdirectory is placed within the META-INF directory that is present in every JAR file. This directory contains a file for each factory interface that has one or more implementation classes present in the JAR file. For example if a JAR file provides one or more DatumFactory implementations, then it must provide the following file:

META-INF/services/org.opengis.referencing.datum.DatumFactory

with a content similar to the one below:

com.mycompany.MyDatumFactory1
com.mycompany.MyDatumFactory2
com.mycompany.MyDatumFactory3

The ordering is initially unspecified. Users can set an ordering explicitly themselves, or implementations can do that automatically on registration.

Note that the factory classes should be lightweight and quick to load. Implementations of these interfaces should avoid complex dependencies on other classes and on native code. A usual pattern for more complex services is to register a lightweight proxy for the heavyweight service.

Fetching a factory
The example below iterates over all registered DatumFactory using the standard service loader bundled in Java 6. Those factories may by registered in many different JAR files.

ServiceLoader registry = ServiceLoader.load(DatumFactory.class);
Iterator<DatumFactory> providers = registry.iterator();

Following does the same using the Geotk factory registry, which allows more control.

Class<?>[] categories = new Class[] {
    DatumFactory.class
    // Put more categories here, if desired.
};
FactoryRegistry registry = new FactoryRegistry(categories);

// Get the providers
Filter filter = null;
Hints  hints  = null;
Iterator<DatumFactory> providers = registry.getServiceProviders(DatumFactory.class, filter, hints);

Users wanting a specific implementation can iterates through registered ones and pickup the desired implementation themself. An alternative is to bundle the criterions in a map of hints and lets the factory registry (Geotk extension only) selects an implementation accordingly. Note that the hints, if provided, don't need to apply directly to the requested factory. They may apply indirectly through factory dependencies.

Since:

2.1

Version:

3.03

Author:

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

Module:

utility/geotk-utility (download)