org.geotoolkit.referencing.factory
Class ThreadedAuthorityFactory

Object
  Factory
      ReferencingFactory
          AbstractAuthorityFactory
              CachingAuthorityFactory
                  ThreadedAuthorityFactory

All Implemented Interfaces:

AuthorityFactory, Factory

Direct Known Subclasses:

ThreadedEpsgFactory

@ThreadSafe
public abstract class ThreadedAuthorityFactory
extends CachingAuthorityFactory

A caching authority factory which delegates to different instances of a backing store for concurrency in multi-thread environment. This factory delays the creation of a backing store until first needed, and dispose it after some timeout. This approach allows to establish a connection to a database (for example) and keep it only for a relatively short amount of time.

Multi-threading
If two or more threads are accessing this factory in same time, then two or more instances of the backing store may be created. The maximal amount of instances to create is specified at ThreadedAuthorityFactory construction time. If more backing store instances are needed, some of the threads will block until an instance become available.

Since:

2.1

Version:

3.04

Author:

Martin Desruisseaux (IRD, Geomatys)

Module:

referencing/geotk-referencing (download)

View source code for this class

Nested Class Summary

Nested classes/interfaces inherited from class Factory

Factory.Availability, Factory.Organizer

Field Summary

Fields inherited from class AbstractAuthorityFactory

nameFactory

Fields inherited from class ReferencingFactory

LOGGER

Fields inherited from class Factory

EMPTY_HINTS, hints

Constructor Summary

protected	ThreadedAuthorityFactory(Hints userHints) Constructs an instance using the default setting.
protected	ThreadedAuthorityFactory(Hints userHints, int maxStrongReferences, int maxBackingStores) Constructs an instance using the given setting.

Method Summary

protected boolean	canDisposeBackingStore(AbstractAuthorityFactory backingStore) Returns true if the given backing store can be disposed now.
protected abstract AbstractAuthorityFactory	createBackingStore() Creates the backing store authority factory.
protected void	dispose(boolean shutdown) Releases resources immediately instead of waiting for the garbage collector.
Map<RenderingHints.Key,?>	getImplementationHints() Returns the implementation hints.
long	getTimeout() Returns the current timeout.
boolean	isActive() Returns true if this factory contains at least one active backing store.
void	setTimeout(long delay) Sets a timer for disposing the backing store after the specified amount of milliseconds of inactivity.

Methods inherited from class CachingAuthorityFactory

availability, createCartesianCS, createCompoundCRS, createCoordinateOperation, createCoordinateReferenceSystem, createCoordinateSystem, createCoordinateSystemAxis, createCylindricalCS, createDatum, createDerivedCRS, createEllipsoid, createEllipsoidalCS, createEngineeringCRS, createEngineeringDatum, createExtent, createFromCoordinateReferenceSystemCodes, createGeocentricCRS, createGeodeticDatum, createGeographicCRS, createImageCRS, createImageDatum, createObject, createOperationMethod, createParameterDescriptor, createPolarCS, createPrimeMeridian, createProjectedCRS, createSphericalCS, createTemporalCRS, createTemporalDatum, createTimeCS, createUnit, createVerticalCRS, createVerticalCS, createVerticalDatum, getAuthority, getAuthorityCodes, getBackingStoreDescription, getDescriptionText, getIdentifiedObjectFinder, getVendor, printCacheContent, setKeyCollisionAllowed

Methods inherited from class AbstractAuthorityFactory

noSuchAuthorityCode, trimAuthority

Methods inherited from class ReferencingFactory

ensureNonNull

Methods inherited from class Factory

equals, hasCompatibleHints, hashCode, setOrdering, toString

Methods inherited from class Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

ThreadedAuthorityFactory

protected ThreadedAuthorityFactory(Hints userHints)

Constructs an instance using the default setting. Subclasses are responsible for creating an appropriate backing store when the createBackingStore() method is invoked.

Parameters:

userHints - An optional set of hints, or null for the default ones.

Since:

2.2

ThreadedAuthorityFactory

protected ThreadedAuthorityFactory(Hints userHints,
                                   int maxStrongReferences,
                                   int maxBackingStores)

Constructs an instance using the given setting. Subclasses are responsible for creating an appropriate backing store when the createBackingStore() method is invoked.

Parameters:

userHints - An optional set of hints, or null for the default ones.

maxStrongReferences - The maximum number of objects to keep by strong reference.

maxBackingStores - The maximal amount of backing stores to create. This is the maximal amount of threads that can use this factory without blocking each other when the requested objects are not in the cache.

Since:

3.00

Method Detail

getImplementationHints

public Map<RenderingHints.Key,?> getImplementationHints()

Returns the implementation hints. At the opposite of most factories that delegate their work to an other factory (like the CachingAuthorityFactory parent class), this method does not set Hints.CRS_AUTHORITY_FACTORY and its friends to the backing store. This is because the backing stores may be created and destroyed at any time, while the implementation hints are expected to be stable. Instead, the implementation hints of a backing store are copied straight in this ThreadedAuthorityFactory hint map.

Overrides:

getImplementationHints in class Factory

createBackingStore

protected abstract AbstractAuthorityFactory createBackingStore()
                                                        throws NoSuchFactoryException,
                                                               FactoryException

Creates the backing store authority factory. This method is invoked the first time a createXXX(...) method is invoked. It may also be invoked again if additional factories are needed in different threads, or if all factories have been disposed after the timeout.

Synchronization
This method needs to be thread-safe. ThreadedAuthorityFactory does not hold a lock when invoking this method. Subclasses are responsible to apply their own synchronization if needed, but are encouraged to avoid doing so if possible.

In addition, implementations should not invoke availability(), getImplementationHints(), getAuthority(), getVendor() or any createXXX() method in order to avoid never-ending loop. If hints are needed, use the code below instead but keep in mind that the map may not contains the definitive set of hints at this stage:

final Hints localHints = EMPTY_HINTS.clone();
synchronized (this) {
    localHints.putAll(hints);
}

Returns:

The backing store to uses in createXXX(...) methods.

Throws:

NoSuchFactoryException - if the backing store has not been found.

FactoryException - if the creation of backing store failed for an other reason.

isActive

public boolean isActive()

Returns true if this factory contains at least one active backing store. A backing store is "active" if it has been created for a previous request and not yet disposed after a period of inactivity equals to the timeout.

A return value of false typically implies that every connection to the underlying database (if any) used by this factory have been closed. Note however that this information is only approximative. Because of the concurrent nature of ThreadedAuthorityFactory, we may have a small delay between the time when the first connection is created and the time when this method returns true.

Returns:

true if this factory contains at least one active backing store.

Since:

3.00

getTimeout

public long getTimeout()

Returns the current timeout.

Returns:

The current timeout.

Since:

3.00

setTimeout

public void setTimeout(long delay)

Sets a timer for disposing the backing store after the specified amount of milliseconds of inactivity. If a new backing store is needed after the disposal of the current one, then the createBackingStore() method will be invoked again.

Note that the backing store disposal can be vetoed if canDisposeBackingStore(org.geotoolkit.referencing.factory.AbstractAuthorityFactory) returns false.

Parameters:

delay - The delay of inactivity (in milliseconds) before to close a backing store.

canDisposeBackingStore

protected boolean canDisposeBackingStore(AbstractAuthorityFactory backingStore)

Returns true if the given backing store can be disposed now. This method is invoked automatically after the amount of time specified by setTimeout(long), providing that the factory was not used during that time. The default implementation always returns true. Subclasses should override this method and returns false if they want to prevent the backing store disposal under some circumstances.

Parameters:

backingStore - The backing store in process of being disposed.

Returns:

true if the backing store can be disposed now.

dispose

protected void dispose(boolean shutdown)

Releases resources immediately instead of waiting for the garbage collector. This method disposes all backing stores. This instance should not be used anymore after this method has been invoked.

Overrides:

dispose in class CachingAuthorityFactory

Parameters:

shutdown - false for normal disposal, or true if this method is invoked during the process of a JVM shutdown.