org.geotoolkit.referencing.factory.epsg
Class ThreadedEpsgFactory

Object
  Factory
      ReferencingFactory
          AbstractAuthorityFactory
              CachingAuthorityFactory
                  ThreadedAuthorityFactory
                      ThreadedEpsgFactory

All Implemented Interfaces:

AuthorityFactory, CRSAuthorityFactory, CSAuthorityFactory, DatumAuthorityFactory, CoordinateOperationAuthorityFactory, Factory

@ThreadSafe
public class ThreadedEpsgFactory
extends ThreadedAuthorityFactory
implements CRSAuthorityFactory, CSAuthorityFactory, DatumAuthorityFactory, CoordinateOperationAuthorityFactory

The EPSG factory registered in AuthorityFactoryFinder. This class has the following responsibilities:

• Aquire a data source using a configuration file, JNDI or otherwise.
• Specify a worker class that will talk to the database in the event of a cache miss. The class will be specific to the dialect of SQL used by the database hosting the EPSG tables.

Note that we are working with the same tables as defined by EPSG. The only thing that changes is the database used to host these tables, and optionally the schema and table names. The EPSG database version can be determined by the edition attribute of the authority.

Users should not creates instance of this class directly. They should invoke one of AuthorityFactoryFinder.getFooAuthorityFactory("EPSG") methods instead, unless they want to derive their own subclass. In the later case, the following methods are good candidate for overriding:

• createDataSource(Properties) used to create a default DataSource when none was explicitly specified by the user (typically as a hint).
• createBackingStore(Hints) used to create a worker instance capable to speak the SQL dialect of that database.

Since:

2.1

Version:

3.18

Author:

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

See Also:

DirectEpsgFactory, List of authority codes

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

static String	CONFIGURATION_FILE The user configuration file, which is "EPSG-DataSource.properties".
protected String	password The password to be given to DataSource.getConnection(String,String), or null if none.
protected String	schema The name of the schema in the database where to look for the tables, or null if none.
protected String	user The user name to be given to DataSource.getConnection(String,String), or null if none.

Fields inherited from class AbstractAuthorityFactory

nameFactory

Fields inherited from class ReferencingFactory

LOGGER

Fields inherited from class Factory

EMPTY_HINTS, hints

Constructor Summary

ThreadedEpsgFactory()
Constructs an authority factory using the default set of factories.

ThreadedEpsgFactory(DataSource source)
Constructs an authority factory which will connect to an EPSG database using the given data source.

ThreadedEpsgFactory(Hints userHints)
Constructs an authority factory using a set of factories created from the specified hints.

Method Summary

protected boolean	canDisposeBackingStore(AbstractAuthorityFactory backingStore) Returns true if the backing store can be disposed now.
protected AbstractAuthorityFactory	createBackingStore() Creates the backing store authority factory.
protected AbstractAuthorityFactory	createBackingStore(Hints hints) Creates the backing store for the current data source.
protected DataSource	createDataSource(Properties properties) Creates a default data source, optionally using the given configuration.
protected void	dispose(boolean shutdown) Releases resources immediately instead of waiting for the garbage collector.
protected DataSource	getDataSource() Returns the data source for the EPSG database.
static String	getDefaultURL() Returns the default JDBC URL to use for connection to the EPSG embedded database.

Methods inherited from class ThreadedAuthorityFactory

getImplementationHints, getTimeout, isActive, setTimeout

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

Methods inherited from interface CRSAuthorityFactory

createCompoundCRS, createCoordinateReferenceSystem, createDerivedCRS, createEngineeringCRS, createGeocentricCRS, createGeographicCRS, createImageCRS, createProjectedCRS, createTemporalCRS, createVerticalCRS

Methods inherited from interface CSAuthorityFactory

createCartesianCS, createCoordinateSystem, createCoordinateSystemAxis, createCylindricalCS, createEllipsoidalCS, createPolarCS, createSphericalCS, createTimeCS, createUnit, createVerticalCS

Methods inherited from interface DatumAuthorityFactory

createDatum, createEllipsoid, createEngineeringDatum, createGeodeticDatum, createImageDatum, createPrimeMeridian, createTemporalDatum, createVerticalDatum

Methods inherited from interface CoordinateOperationAuthorityFactory

createCoordinateOperation, createFromCoordinateReferenceSystemCodes, createOperationMethod

Methods inherited from interface AuthorityFactory

createObject, getAuthority, getAuthorityCodes, getDescriptionText

Methods inherited from interface Factory

getVendor

Field Detail

CONFIGURATION_FILE

public static final String CONFIGURATION_FILE

The user configuration file, which is "EPSG-DataSource.properties". This file is used if no DataSource object were specified explicitly to the constructor, either directly or as a hint. In such case, ThreadedEpsgFactory will look for the first of the following files:

• "EPSG-DataSource.properties" in the current directory
• "EPSG-DataSource.properties" in the user's home directory
• "EPSG/DataSource.properties" in the Geotk application data directory

This file should contain the properties listed below.

Property	Type	Description
URL	String	URL to the database.
schema	String	The schema for the EPSG tables.
user	String	User used to make database connections.
password	String	Password used to make database connections.

Since:

3.00

See Also:

Constant Field Values

schema

protected String schema

The name of the schema in the database where to look for the tables, or null if none.

This property is read from the "EPSG-DataSource.properties" file by getDataSource(), and is used by createBackingStore(Hints). If a subclass wants to change this value, then overriding the createDataSource(Properties) method is a convenient way to do so.

Since:

3.00

user

protected String user

The user name to be given to DataSource.getConnection(String,String), or null if none. In the later case, DataSource.getConnection() will be used instead.

This property is read from the "EPSG-DataSource.properties" file by getDataSource(), and is used by createBackingStore(Hints). If a subclass wants to change this value, then overriding the createDataSource(Properties) method is a convenient way to do so.

Since:

3.00

password

protected String password

The password to be given to DataSource.getConnection(String,String), or null if none.

This property is read from the "EPSG-DataSource.properties" file by getDataSource(), and is used by createBackingStore(Hints). If a subclass wants to change this value, then overriding the createDataSource(Properties) method is a convenient way to do so.

Since:

3.00

Constructor Detail

ThreadedEpsgFactory

public ThreadedEpsgFactory()

Constructs an authority factory using the default set of factories. The instance created by this method will use the first of the following possibilities:

• The data source specified by Hints.EPSG_DATA_SOURCE in the system default hints, if any.
• The connection parameters specified in the "EPSG-DataSource.properties" if such file is found.
• The JavaDB (a.k.a. Derby) embedded database if the Derby JDBC driver is found on the classpath.
• The HSQL embedded database if the HSQL JDBC driver is found on the classpath.

ThreadedEpsgFactory

public ThreadedEpsgFactory(DataSource source)

Constructs an authority factory which will connect to an EPSG database using the given data source. The example below creates a data source for a connection to a PostgreSQL database on the local machine.

PGSimpleDataSource source = new PGSimpleDataSource();
ds.setServerName("localhost");
ds.setDatabaseName("EPSG");
ds.setUser("postgre");

Parameters:

source - The data source for the EPSG database, or null.

Since:

3.00

ThreadedEpsgFactory

public ThreadedEpsgFactory(Hints userHints)

Constructs an authority factory using a set of factories created from the specified hints. Hints of special interrest are:

• Hints.EPSG_DATA_SOURCE

This constructor recognizes also the CRS, CS, DATUM and MATH_TRANSFORM FACTORY hints.

Parameters:

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

Method Detail

getDefaultURL

public static String getDefaultURL()

Returns the default JDBC URL to use for connection to the EPSG embedded database. This method returns a URL using the JavaDB driver, connecting to the database in the installation directory specified by the setup program in the geotk-setup module. If this setup program has not been run, then a platform-dependent location relative to the user home directory is returned.

If no database exists in the above-cited directory, then a new EPSG database will be created by ThreadedEpsgFactory when first needed provided that the geotk-epsg module is reachable on the classpath.

Note that the directory may change in any Geotk version. More specifically, every upgrade of the embedded EPSG database may cause a change of the default directory.

Returns:

The default JDBC URL to use for the connection to the EPSG database.

Since:

3.00

getDataSource

protected DataSource getDataSource()
                            throws FactoryException

Returns the data source for the EPSG database. The default implementation performs the following steps:

1. If a DataSource object was given explicitly to the constructor, it is returned.

2. Otherwise if hint value is associated to the Hints.EPSG_DATA_SOURCE key, then there is a choice:

   • If that value is an instance of DataSource, it is returned.
   • If that value is an instance of Name, then a JNDI lookup is performed for that name.
   • If that value is an instance of String, then a JNDI lookup is performed for that name.

3. Otherwise if at least one of the following files exist, then the first one is used for etablishing a connection (See CONFIGURATION_FILE for more informations).

   • "EPSG-DataSource.properties" in the current directory
   • "EPSG-DataSource.properties" in the user's home directory
   • "EPSG/DataSource.properties" in the Geotk application data directory

4. Otherwise the default URL to the embedded database is used. If the database does not exist and the geotk-epsg.jar file is reachable on the classpath, then the EPSG database will be created when first needed.

The two last steps are actually encapsulated in a call to createDataSource(Properties). Subclasses can override that method if they want more control on that part (for example in order to perform different tasks depending the content of the properties file).

Returns:

The data source. Should never be null.

Throws:

FactoryException - if the operation failed (for example an I/O error while reading the configuration file, or a failure to lookup the JNDI name).

createDataSource

protected DataSource createDataSource(Properties properties)
                               throws FactoryException

Creates a default data source, optionally using the given configuration. This method is invoked by getDataSource() when no explicit value was provided for Hints.EPSG_DATA_SOURCE. If a configuration file has been found, its content is given as the sole argument to this method. Otherwise the properties argument is null.

The default implementation performs the following steps:

• If the properties is non-null, then the value associated to the "URL" key is taken. Otherwise the default URL to the embedded database is used.
• A new DataSource is created, which will use the above URL for fetching a connection through DriverManager.getConnection(String).

If the default URL was used and no database exists at that URL, then a new database will be created using the EpsgInstaller when first needed. This operation is possible only if the geotk-epsg.jar file is reachable on the classpath, otherwise an exception will be thrown the first time the factory will be used.

Subclasses should override this method if they can create a data source from other properties ("serverName", "databaseName", etc.), or if they can provide a default data source.

Parameters:

properties - The properties loaded from the configuration file if it was found, or null otherwise.

Returns:

A data source created from the properties, or null if this method can not create a data source.

Throws:

FactoryException - if the operation failed for an other reason.

Since:

3.00

createBackingStore

protected AbstractAuthorityFactory createBackingStore(Hints hints)
                                               throws FactoryException,
                                                      SQLException

Creates the backing store for the current data source. The default implementation tries to guess the most appropriate subclass of DirectEpsgFactory from the database metadata. Subclasses should override this method if they can return an instance tuned for the SQL dialect of the underlying database. Example for a Oracle data source:

protected AbstractAuthorityFactory createBackingStore(Hints hints) throws SQLException {
    return new OracleDialectEpsgFactory(hints, getDataSource().getConnection(user, password));
}

Parameters:

hints - A map of hints, including the low-level factories to use for CRS creation. This argument should be given unchanged to DirectEpsgFactory constructor.

Returns:

The EPSG factory using SQL dialect appropriate for this data source.

Throws:

SQLException - if the connection to the database failed.

FactoryException - if the operation failed for an other reason (for example a failure to get the data source).

See Also:

user, password

createBackingStore

protected AbstractAuthorityFactory createBackingStore()
                                               throws FactoryException

Creates the backing store authority factory. This method is invoked automatically by ThreadedAuthorityFactory when a new backing store is required, either because the previous one has been disposed after its timeout or because a new one is required for concurrency.

The default implementation invokes createBackingStore(Hints) with a map of hints derived from this factory hints, then logs a message at the CONFIG level. The log message contains the URL to the database.

Specified by:

createBackingStore in class ThreadedAuthorityFactory

Returns:

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

Throws:

FactoryException - if the constructor failed to connect to the EPSG database. This exception usually has a SQLException as its cause.

canDisposeBackingStore

protected boolean canDisposeBackingStore(AbstractAuthorityFactory backingStore)

Returns true if the backing store can be disposed now. This method is invoked automatically after the amount of time specified by ThreadedAuthorityFactory.setTimeout(long) if the factory were not used during that time.

Overrides:

canDisposeBackingStore in class ThreadedAuthorityFactory

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, which imply closing their connections.

Overrides:

dispose in class ThreadedAuthorityFactory

Parameters:

shutdown - false for normal disposal, or true if this method is invoked during the process of a JVM shutdown. In the later case this method may shutdown the embedded database, if there is one (for example JavaDB).