org.geotools.factory
Class AbstractFactory

java.lang.Object
  org.geotools.factory.AbstractFactory

All Implemented Interfaces:

Factory, javax.imageio.spi.RegisterableService

Direct Known Subclasses:

AbstractFactory, BBOXDataStoreFactory, FactoryUsingVolatileDependencies, GridCoverageFactory, JDBCDataStoreFactory, LocationsXYDataStoreFactory

public class AbstractFactory

extends java.lang.Object

implements Factory, javax.imageio.spi.RegisterableService

Skeletal implementation of factories. This base classe provides no methods, (they must be provided by subclasses), but provides two convenience features:

• An initially empty map of hints to be filled by subclasses constructors. They are the hints to be returned by getImplementationHints().
• An automatic ordering applied on the basis of subclasses-provided priority rank.

When more than one factory implementation is registered for the same category (i.e. they implement the same Factory sub-interface), 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.

The ordering is unspecified for every pairs of factories with the same priority. This implies that the ordering is unspecified between all factories created with the default constructor, since they all have the same default priority level.

How hints are set

Hints are used for two purposes. The distinction is important because the set of hints may not be identical in both cases:

1. Hints are used for creating new factories.
2. Hints are used in order to check if an existing factory is suitable.

do not provides any facility for the first case. Factories implementations shall inspect themselves all relevant hints supplied by the user, and pass them to any dependencies. Do not uses the hints field for that; uses the hints provided by the user in the constructor. If all dependencies are created at construction time (constructor injection), there is no need to keep user's hints once the construction is finished.

The hints field is for the second case only. Implementations shall copy in this field only the user's hints that are know to be relevant to this factory. Only direct dependencies shall be put in the hints map. Indirect dependencies (i.e. hints used by other factories used by this factory) will be inspected automatically by FactoryRegistry in a recursive way.

The lack of constructor expecting a Map argument is intentional. Implementations should not copy blindly all user-supplied hints into the hints field. Instead, they should pickup only the relevant hints and put them in the hints field. An exception to this rule is when not all factories can be created at construction time. In this case, all user-supplied hints must be kept.

Example: Lets two factories, A and B. Factory A need an instance of Factory B. Factory A can be implemented as below:

class FactoryA extends AbstractFactory { FactoryB fb; FactoryA(Hints userHints) { fb = FactoryFinder.getFactoryB(userHints); this.hints.put(Hints.FACTORY_B, fb); } }

Observations: The user-supplied map () is never modified. All hints relevant to other factories are used in the constructor. Hints relevant to factory B are used when is invoked. The constructor stores only the hints relevant to . Indirect dependencies (e.g. hints relevant to ) will be inspected recursively by FactoryRegistry. In the above example, hints will never be used for creating new factories.

Since:

2.1

Version:

$Id: AbstractFactory.java 17672 2006-01-19 00:25:55Z desruisseaux $

Author:

Martin Desruisseaux

Field Summary

protected Hints	hints The implementation hints.
static int	MAXIMUM_PRIORITY The maximum priority for a factory, which is 100.
static int	MINIMUM_PRIORITY The minimum priority for a factory, which is 1.
static int	NORMAL_PRIORITY The default priority, which is 50.
int	priority The priority for this factory.

Constructor Summary

protected	AbstractFactory() Creates a new factory with the default priority.
protected	AbstractFactory(int priority) Constructs a factory with the specified priority.

Method Summary

java.util.Map	getImplementationHints() Returns an unmodifiable view of hints.
void	onDeregistration(javax.imageio.spi.ServiceRegistry registry, java.lang.Class category) Called when this factory is removed from the given of the given .
void	onRegistration(javax.imageio.spi.ServiceRegistry registry, java.lang.Class category) Called when this factory is added to the given of the given .

Methods inherited from class java.lang.Object

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

Field Detail

MINIMUM_PRIORITY

public static final int MINIMUM_PRIORITY

The minimum priority for a factory, which is 1. Factories with lowest priority will be used only if there is no other factory in the same category.

See Also:

onRegistration(javax.imageio.spi.ServiceRegistry, java.lang.Class), Constant Field Values

NORMAL_PRIORITY

public static final int NORMAL_PRIORITY

The default priority, which is 50.

See Also:

onRegistration(javax.imageio.spi.ServiceRegistry, java.lang.Class), Constant Field Values

MAXIMUM_PRIORITY

public static final int MAXIMUM_PRIORITY

The maximum priority for a factory, which is 100. Factories with highest priority will be preferred to any other factory in the same category.

See Also:

onRegistration(javax.imageio.spi.ServiceRegistry, java.lang.Class), Constant Field Values

priority

public final int priority

The priority for this factory.

hints

protected final Hints hints

The implementation hints. This map should be filled by subclasses at construction time. If possible, constructors should not copy blindly all user-provided hints. They should select only the relevant hints and resolve them as of implementation hints contract.

Reminder: the primary use of this map is to check if this factory can be reused. It is not for creating new factories.

Once the hints are accessibles to the user (this usually means when the subclass construction is finished), this map should not change anymore.

Constructor Detail

AbstractFactory

protected AbstractFactory()

Creates a new factory with the default priority.

AbstractFactory

protected AbstractFactory(int priority)

Constructs a factory with the specified priority.

Parameters:

priority - The priority for this factory, as a number between MINIMUM_PRIORITY and MAXIMUM_PRIORITY inclusive.

Method Detail

getImplementationHints

public java.util.Map getImplementationHints()

Returns an unmodifiable view of hints.

Specified by:

getImplementationHints in interface Factory

Returns:

The map of hints, or an empty map if none.

onRegistration

public void onRegistration(javax.imageio.spi.ServiceRegistry registry,
                           java.lang.Class category)

Called when this factory is added to the given of the given . The factory may already be registered under another category or categories.

This method is invoked automatically when this factory is registered as a plugin, and should not be invoked directly by the user. The default implementation iterates through all services under the same category that extends the class, and set the ordering according the priority given at construction time.

Specified by:

onRegistration in interface javax.imageio.spi.RegisterableService

Parameters:

registry - A service registry where this factory has been registered.

category - The registry category under which this object has been registered.

See Also:

MINIMUM_PRIORITY, MAXIMUM_PRIORITY

onDeregistration

public void onDeregistration(javax.imageio.spi.ServiceRegistry registry,
                             java.lang.Class category)

Called when this factory is removed from the given of the given . The object may still be registered under another category or categories.

This method is invoked automatically when this factory is no longer registered as a plugin, and should not be invoked directly by the user.

Specified by:

onDeregistration in interface javax.imageio.spi.RegisterableService

Parameters:

registry - A service registry from which this object is being (wholly or partially) deregistered.

category - The registry category from which this object is being deregistered.