org.geotoolkit.referencing.factory.epsg
Class DirectEpsgFactory

Object
  Factory
      ReferencingFactory
          AbstractAuthorityFactory
              DirectAuthorityFactory
                  DirectEpsgFactory

All Implemented Interfaces:

AuthorityFactory, CRSAuthorityFactory, CSAuthorityFactory, DatumAuthorityFactory, CoordinateOperationAuthorityFactory, Factory

Direct Known Subclasses:

AnsiDialectEpsgFactory

@ThreadSafe
public class DirectEpsgFactory
extends DirectAuthorityFactory
implements CRSAuthorityFactory, CSAuthorityFactory, DatumAuthorityFactory, CoordinateOperationAuthorityFactory

A CRS authority factory backed by the EPSG database tables. The EPSG database is freely available at http://www.epsg.org. Current version of this class requires EPSG database version 6.6 or above.

This factory accepts names as well as numerical identifiers. For example "NTF (Paris) / France I" and "27581" both fetch the same object. However, names may be ambiguous since the same name may be used for more than one object. This is the case of "WGS 84" for example. If such an ambiguity is found, an exception will be thrown. If names are not wanted as a legal EPSG code, subclasses can override the isPrimaryKey(String) method.

This factory doesn't cache any result. Any call to a createFoo method will send a new query to the EPSG database. For caching, this factory should be wrapped in some buffered factory like ThreadedEpsgFactory.

Because the primary distribution format for the EPSG database is MS-Access, this class uses SQL statements formatted for the MS-Access syntax. For usage with an other database software, a dialect-specific subclass must be used.

Since:

1.2

Version:

3.18

Author:

Yann Cézard (IRD), Martin Desruisseaux (IRD, Geomatys), Rueben Schulz (UBC), Matthias Basler, Andrea Aime (TOPP)

See Also:

ThreadedEpsgFactory, 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

protected Connection

connection The connection to the EPSG database.

Fields inherited from class DirectAuthorityFactory

factories

Fields inherited from class AbstractAuthorityFactory

nameFactory

Fields inherited from class ReferencingFactory

LOGGER

Fields inherited from class Factory

EMPTY_HINTS, hints

Constructor Summary

DirectEpsgFactory(Hints userHints, Connection connection)
Creates a factory using the given connection.

Method Summary

protected String	adaptSQL(String statement) Invoked when a new PreparedStatement is about to be created from a SQL string.
CoordinateOperation	createCoordinateOperation(String code) Returns a coordinate operation from a code.
CoordinateReferenceSystem	createCoordinateReferenceSystem(String code) Returns a coordinate reference system from a code.
CoordinateSystem	createCoordinateSystem(String code) Returns a coordinate system from a code.
CoordinateSystemAxis	createCoordinateSystemAxis(String code) Returns a coordinate system axis from a code.
Datum	createDatum(String code) Returns a datum from a code.
Ellipsoid	createEllipsoid(String code) Returns an ellipsoid from a code.
Extent	createExtent(String code) Returns an area of use.
Set<CoordinateOperation>	createFromCoordinateReferenceSystemCodes(String sourceCode, String targetCode) Creates operations from coordinate reference system codes.
IdentifiedObject	createObject(String code) Returns an arbitrary object from a code.
OperationMethod	createOperationMethod(String code) Returns an operation method from a code.
ParameterDescriptor<?>	createParameterDescriptor(String code) Returns a parameter descriptor from a code.
PrimeMeridian	createPrimeMeridian(String code) Returns a prime meridian, relative to Greenwich.
Unit<?>	createUnit(String code) Returns an unit from a code.
protected void	dispose(boolean shutdown) Closes the JDBC connection used by this factory.
protected void	finalize() Invokes dispose(false) when this factory is garbage collected.
Citation	getAuthority() Returns the authority for this EPSG database.
Set<String>	getAuthorityCodes(Class<? extends IdentifiedObject> type) Returns the set of authority codes of the given type.
String	getBackingStoreDescription() Returns a description of the database engine.
InternationalString	getDescriptionText(String code) Gets a description of the object corresponding to a code.
IdentifiedObjectFinder	getIdentifiedObjectFinder(Class<? extends IdentifiedObject> type) Returns a finder which can be used for looking up unidentified objects.
Map<RenderingHints.Key,?>	getImplementationHints() Returns the implementation hints for this factory.
protected boolean	isPrimaryKey(String code) Returns true if the specified code may be a primary key in some table.

Methods inherited from class AbstractAuthorityFactory

createCartesianCS, createCompoundCRS, createCylindricalCS, createDerivedCRS, createEllipsoidalCS, createEngineeringCRS, createEngineeringDatum, createGeocentricCRS, createGeodeticDatum, createGeographicCRS, createImageCRS, createImageDatum, createPolarCS, createProjectedCRS, createSphericalCS, createTemporalCRS, createTemporalDatum, createTimeCS, createVerticalCRS, createVerticalCS, createVerticalDatum, noSuchAuthorityCode, trimAuthority

Methods inherited from class ReferencingFactory

ensureNonNull, getVendor

Methods inherited from class Factory

availability, equals, hasCompatibleHints, hashCode, setOrdering, toString

Methods inherited from class Object

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

Methods inherited from interface CRSAuthorityFactory

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

Methods inherited from interface CSAuthorityFactory

createCartesianCS, createCylindricalCS, createEllipsoidalCS, createPolarCS, createSphericalCS, createTimeCS, createVerticalCS

Methods inherited from interface DatumAuthorityFactory

createEngineeringDatum, createGeodeticDatum, createImageDatum, createTemporalDatum, createVerticalDatum

Methods inherited from interface Factory

getVendor

Field Detail

connection

protected final Connection connection

The connection to the EPSG database. This connection is specified at construction time and closed by the dispose(boolean) method, or when this DirectEpsgFactory instance if garbage collected.

Constructor Detail

DirectEpsgFactory

public DirectEpsgFactory(Hints userHints,
                         Connection connection)

Creates a factory using the given connection. The connection is closed when this factory is disposed.

Note: we recommend to avoid keeping the connection open for a long time. An easy way to get the connection created only when first needed and closed automatically after a short timeout is to instantiate this DirectEpsgFactory class only in a ThreadedAuthorityFactory. This approach also gives concurrency and caching services in bonus.

Parameters:

userHints - The underlying factories used for objects creation, or null for the default ones.

connection - The connection to the underlying EPSG database.

Method Detail

getAuthority

public Citation getAuthority()

Returns the authority for this EPSG database. This authority will contains the database version in the edition attribute, together with the edition date.

Specified by:

getAuthority in interface AuthorityFactory

Specified by:

getAuthority in class AbstractAuthorityFactory

getBackingStoreDescription

public String getBackingStoreDescription()
                                  throws FactoryException

Returns a description of the database engine.

Overrides:

getBackingStoreDescription in class AbstractAuthorityFactory

Returns:

The description of the underlying backing store, or null.

Throws:

FactoryException - if the database's metadata can't be fetched.

getImplementationHints

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

Returns the implementation hints for this factory. The returned map contains all the values specified in subclass, with the addition of VERSION.

Overrides:

getImplementationHints in class DirectAuthorityFactory

getAuthorityCodes

public Set<String> getAuthorityCodes(Class<? extends IdentifiedObject> type)
                              throws FactoryException

Returns the set of authority codes of the given type.

NOTE: This method returns a living connection to the underlying database. This means that the returned set can executes efficiently idioms like the following one:

getAuthorityCodes(type).containsAll(others)

But do not keep the returned reference for a long time. The returned set should stay valid even if retained for a long time (as long as this factory has not been disposed), but the existence of those long-living connections may prevent this factory to release some resources. If the set of codes is needed for a long time, copy their values in an other collection object.

Specified by:

getAuthorityCodes in interface AuthorityFactory

Parameters:

type - The spatial reference objects type (may be Object.class).

Returns:

The set of authority codes for spatial reference objects of the given type. If this factory doesn't contains any object of the given type, then this method returns an empty set.

Throws:

FactoryException - if access to the underlying database failed.

getDescriptionText

public InternationalString getDescriptionText(String code)
                                       throws NoSuchAuthorityCodeException,
                                              FactoryException

Gets a description of the object corresponding to a code.

Specified by:

getDescriptionText in interface AuthorityFactory

Parameters:

code - Value allocated by authority.

Returns:

A description of the object, or null if the object corresponding to the specified code has no description.

Throws:

NoSuchAuthorityCodeException - if the specified code was not found.

FactoryException - if the query failed for some other reason.

createObject

public IdentifiedObject createObject(String code)
                              throws NoSuchAuthorityCodeException,
                                     FactoryException

Returns an arbitrary object from a code. The default implementation invokes one of createCoordinateReferenceSystem, createCoordinateSystem, createDatum, createEllipsoid, or createUnit methods according the object type.

Specified by:

createObject in interface AuthorityFactory

Overrides:

createObject in class AbstractAuthorityFactory

Parameters:

code - The EPSG value.

Returns:

The object.

Throws:

NoSuchAuthorityCodeException - if this method can't find the requested code.

FactoryException - if some other kind of failure occurred in the backing store. This exception usually have SQLException as its cause.

createUnit

public Unit<?> createUnit(String code)
                   throws NoSuchAuthorityCodeException,
                          FactoryException

Returns an unit from a code.

Specified by:

createUnit in interface CSAuthorityFactory

Overrides:

createUnit in class AbstractAuthorityFactory

Parameters:

code - Value allocated by authority.

Returns:

The unit object.

Throws:

NoSuchAuthorityCodeException - if this method can't find the requested code.

FactoryException - if some other kind of failure occurred in the backing store. This exception usually have SQLException as its cause.

createEllipsoid

public Ellipsoid createEllipsoid(String code)
                          throws NoSuchAuthorityCodeException,
                                 FactoryException

Returns an ellipsoid from a code.

Specified by:

createEllipsoid in interface DatumAuthorityFactory

Overrides:

createEllipsoid in class AbstractAuthorityFactory

Parameters:

code - The EPSG value.

Returns:

The ellipsoid object.

Throws:

NoSuchAuthorityCodeException - if this method can't find the requested code.

FactoryException - if some other kind of failure occurred in the backing store. This exception usually have SQLException as its cause.

createPrimeMeridian

public PrimeMeridian createPrimeMeridian(String code)
                                  throws NoSuchAuthorityCodeException,
                                         FactoryException

Returns a prime meridian, relative to Greenwich.

Specified by:

createPrimeMeridian in interface DatumAuthorityFactory

Overrides:

createPrimeMeridian in class AbstractAuthorityFactory

Parameters:

code - Value allocated by authority.

Returns:

The prime meridian object.

Throws:

NoSuchAuthorityCodeException - if this method can't find the requested code.

FactoryException - if some other kind of failure occurred in the backing store. This exception usually have SQLException as its cause.

createExtent

public Extent createExtent(String code)
                    throws NoSuchAuthorityCodeException,
                           FactoryException

Returns an area of use.

Overrides:

createExtent in class AbstractAuthorityFactory

Parameters:

code - Value allocated by authority.

Returns:

The area of use.

Throws:

NoSuchAuthorityCodeException - if this method can't find the requested code.

FactoryException - if some other kind of failure occurred in the backing store. This exception usually have SQLException as its cause.

createDatum

public Datum createDatum(String code)
                  throws NoSuchAuthorityCodeException,
                         FactoryException

Returns a datum from a code.

Specified by:

createDatum in interface DatumAuthorityFactory

Overrides:

createDatum in class AbstractAuthorityFactory

Parameters:

code - Value allocated by authority.

Returns:

The datum object.

Throws:

NoSuchAuthorityCodeException - if this method can't find the requested code.

FactoryException - if some other kind of failure occurred in the backing store. This exception usually have SQLException as its cause.

TODO:

Current implementation maps all "vertical" datum to VerticalDatumType.GEOIDAL. We don't know yet how to maps the exact vertical datum type from the EPSG database.

createCoordinateSystemAxis

public CoordinateSystemAxis createCoordinateSystemAxis(String code)
                                                throws NoSuchAuthorityCodeException,
                                                       FactoryException

Returns a coordinate system axis from a code.

Specified by:

createCoordinateSystemAxis in interface CSAuthorityFactory

Overrides:

createCoordinateSystemAxis in class AbstractAuthorityFactory

Parameters:

code - Value allocated by authority.

Returns:

The axis for the given code.

Throws:

NoSuchAuthorityCodeException - if the specified code was not found.

FactoryException - if the object creation failed for some other reason.

createCoordinateSystem

public CoordinateSystem createCoordinateSystem(String code)
                                        throws NoSuchAuthorityCodeException,
                                               FactoryException

Returns a coordinate system from a code.

Specified by:

createCoordinateSystem in interface CSAuthorityFactory

Overrides:

createCoordinateSystem in class AbstractAuthorityFactory

Parameters:

code - Value allocated by authority.

Returns:

The coordinate system object.

Throws:

NoSuchAuthorityCodeException - if this method can't find the requested code.

FactoryException - if some other kind of failure occurred in the backing store. This exception usually have SQLException as its cause.

createCoordinateReferenceSystem

public CoordinateReferenceSystem createCoordinateReferenceSystem(String code)
                                                          throws NoSuchAuthorityCodeException,
                                                                 FactoryException

Returns a coordinate reference system from a code.

Specified by:

createCoordinateReferenceSystem in interface CRSAuthorityFactory

Overrides:

createCoordinateReferenceSystem in class AbstractAuthorityFactory

Parameters:

code - Value allocated by authority.

Returns:

The coordinate reference system object.

Throws:

NoSuchAuthorityCodeException - if this method can't find the requested code.

FactoryException - if some other kind of failure occurred in the backing store. This exception usually have SQLException as its cause.

createParameterDescriptor

public ParameterDescriptor<?> createParameterDescriptor(String code)
                                                 throws NoSuchAuthorityCodeException,
                                                        FactoryException

Returns a parameter descriptor from a code.

Overrides:

createParameterDescriptor in class AbstractAuthorityFactory

Parameters:

code - The parameter descriptor code allocated by EPSG authority.

Returns:

The coordinate reference system for the given code.

Throws:

NoSuchAuthorityCodeException - if this method can't find the requested code.

FactoryException - if some other kind of failure occurred in the backing store. This exception usually have SQLException as its cause.

createOperationMethod

public OperationMethod createOperationMethod(String code)
                                      throws NoSuchAuthorityCodeException,
                                             FactoryException

Returns an operation method from a code.

Specified by:

createOperationMethod in interface CoordinateOperationAuthorityFactory

Overrides:

createOperationMethod in class AbstractAuthorityFactory

Parameters:

code - The operation method code allocated by EPSG authority.

Returns:

The operation method for the given code.

Throws:

NoSuchAuthorityCodeException - if this method can't find the requested code.

FactoryException - if some other kind of failure occurred in the backing store. This exception usually have SQLException as its cause.

createCoordinateOperation

public CoordinateOperation createCoordinateOperation(String code)
                                              throws NoSuchAuthorityCodeException,
                                                     FactoryException

Returns a coordinate operation from a code. The returned object will either be a conversion or a transformation, depending on the code.

Specified by:

createCoordinateOperation in interface CoordinateOperationAuthorityFactory

Overrides:

createCoordinateOperation in class AbstractAuthorityFactory

Parameters:

code - Value allocated by authority.

Returns:

The coordinate operation object.

Throws:

NoSuchAuthorityCodeException - if this method can't find the requested code.

FactoryException - if some other kind of failure occurred in the backing store. This exception usually have SQLException as its cause.

createFromCoordinateReferenceSystemCodes

public Set<CoordinateOperation> createFromCoordinateReferenceSystemCodes(String sourceCode,
                                                                         String targetCode)
                                                                  throws FactoryException

Creates operations from coordinate reference system codes. The returned set is ordered with the most accurate operations first.

Specified by:

createFromCoordinateReferenceSystemCodes in interface CoordinateOperationAuthorityFactory

Overrides:

createFromCoordinateReferenceSystemCodes in class AbstractAuthorityFactory

Parameters:

sourceCode - Coded value of source coordinate reference system.

targetCode - Coded value of target coordinate reference system.

Returns:

The operations from sourceCRS to targetCRS.

Throws:

FactoryException - if the object creation failed.

TODO:

The ordering is not consistent among all database software, because the "accuracy" column may contains null values. When used in an "ORDER BY" clause, PostgreSQL put null values last, while Access and HSQL put them first. The PostgreSQL's behavior is better for what we want (put operations with unknown accuracy last). Unfortunately, I don't know yet how to instruct Access to put null values last using standard SQL ("IIF" is not standard, and Access doesn't seem to understand "CASE ... THEN" clauses).

getIdentifiedObjectFinder

public IdentifiedObjectFinder getIdentifiedObjectFinder(Class<? extends IdentifiedObject> type)
                                                 throws FactoryException

Returns a finder which can be used for looking up unidentified objects.

Overrides:

getIdentifiedObjectFinder in class AbstractAuthorityFactory

Parameters:

type - The type of objects to look for.

Returns:

A finder to use for looking up unidentified objects.

Throws:

FactoryException - if the finder can not be created.

adaptSQL

protected String adaptSQL(String statement)

Invoked when a new PreparedStatement is about to be created from a SQL string. Since the EPSG database is available mainly in MS-Access format, SQL statements are formatted using a syntax specific to this particular database software (for example "SELECT * FROM [Coordinate Reference System]"). When a subclass targets another database vendor, it must overrides this method in order to adapt the local SQL syntax. For example a subclass connecting to a PostgreSQL database could replace the watching braces ('[' and ']') by the quote character ('"').

The default implementation returns the given statement unchanged.

Parameters:

statement - The statement in MS-Access syntax.

Returns:

The SQL statement adapted to the syntax of the target database.

isPrimaryKey

protected boolean isPrimaryKey(String code)
                        throws FactoryException

Returns true if the specified code may be a primary key in some table. This method does not need to check any entry in the database. It should just checks from the syntax if the code looks like a valid EPSG identifier. The default implementation returns true if all non-space characters are digits.

When this method returns false, some createFoo(...) methods look for the code in the name column instead of the primary key column. This allows to accept the "NTF (Paris) / France I" string (for example) in addition to the "27581" primary key. Both should fetch the same object.

If this method returns true in all cases, then this factory never search for matching names. In such case, an appropriate exception will be thrown in createFoo(...) methods if the code is not found in the primary key column. Subclasses can overrides this method that way if this is the intended behavior.

Parameters:

code - The code the inspect.

Returns:

true if the code is probably a primary key.

Throws:

FactoryException - if an unexpected error occurred while inspecting the code.

dispose

protected void dispose(boolean shutdown)

Closes the JDBC connection used by this factory.

Overrides:

dispose in class AbstractAuthorityFactory

Parameters:

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

finalize

protected final void finalize()

Invokes dispose(false) when this factory is garbage collected.

Overrides:

finalize in class Object