org.geotools.referencing.factory.epsg
Class AbstractEpsgFactory

Object
  extended by AbstractFactory
      extended by ReferencingFactory
          extended by AbstractAuthorityFactory
              extended by AbstractCachedAuthorityFactory
                  extended by AbstractEpsgFactory
All Implemented Interfaces:
RegisterableService, BufferedFactory, Factory, AuthorityFactory, CRSAuthorityFactory, CSAuthorityFactory, DatumAuthorityFactory, CoordinateOperationAuthorityFactory
Direct Known Subclasses:
AccessDialectEpsgFactory, AnsiDialectEpsgFactory

public abstract class AbstractEpsgFactory
extends AbstractCachedAuthorityFactory

A coordinate reference system 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 makes use of a provided ObjectCache, and may be deployed in stand aline fashion; or as a worker for a MultiEpsgFactory.

This class is abstract - please see the subclasses for dialect specific implementations:

These factories accepts names as well as numerical identifiers. For example "NTF (Paris) / France I" and "27581" both fetchs 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(java.lang.String) method.

Since:
2.4
Author:
Yann Cézard, Martin Desruisseaux (IRD), Rueben Schulz, Matthias Basler, Andrea Aime
Module:
modules/library/referencing (gt-referencing.jar)

Field Summary
protected  DataSource dataSource
          A DataSource to the EPSG database being used.
 
Fields inherited from class AbstractCachedAuthorityFactory
cache, factories
 
Fields inherited from class ReferencingFactory
LOGGER
 
Fields inherited from class AbstractFactory
hints, MAXIMUM_PRIORITY, MINIMUM_PRIORITY, NORMAL_PRIORITY, priority
 
Constructor Summary
AbstractEpsgFactory(Hints userHints)
           
AbstractEpsgFactory(Hints userHints, Connection connection)
          Constructs an authority factory using the specified connection.
AbstractEpsgFactory(Hints userHints, DataSource dataSource)
           
 
Method Summary
protected abstract  String adaptSQL(String statement)
          Invoked when a new PreparedStatement is about to be created from a SQL string.
 void connect()
          Connect to the database in anticipation of of use.
 void disconnect()
          Disconnect from the database, and remain idle.
 void dispose()
          Disposes any resources hold by this object.
protected  void finalize()
          Invokes dispose() when this factory is garbage collected.
protected  Set<String> generateAuthorityCodes(Class type)
          Returns the set of authority codes of the given type.
 CoordinateOperation generateCoordinateOperation(String code)
          Returns a coordinate operation from a code.
 CoordinateReferenceSystem generateCoordinateReferenceSystem(String code)
          Returns a coordinate reference system from a code.
 CoordinateSystem generateCoordinateSystem(String code)
          Returns a coordinate system from a code.
 CoordinateSystemAxis generateCoordinateSystemAxis(String code)
          Returns a coordinate system axis from a code.
 Datum generateDatum(String code)
          Returns a datum from a code.
 Ellipsoid generateEllipsoid(String code)
          Returns an ellipsoid from a code.
 Extent generateExtent(String code)
          Returns an area of use.
 Set generateFromCoordinateReferenceSystemCodes(String sourceCode, String targetCode)
          Creates operations from coordinate reference system codes.
 IdentifiedObject generateObject(String code)
          Returns an arbitrary object from a code.
 OperationMethod generateOperationMethod(String code)
          Returns an operation method from a code.
 ParameterDescriptor generateParameterDescriptor(String code)
          Returns a parameter descriptor from a code.
 PrimeMeridian generatePrimeMeridian(String code)
          Returns a prime meridian, relative to Greenwich.
 Unit<?> generateUnit(String code)
          Returns an unit from a code.
 Citation getAuthority()
          Returns the authority for this EPSG database.
 String getBackingStoreDescription()
          Returns a description of the database engine.
protected  Connection getConnection()
          Access to the connection used by this EpsgFactory.
 InternationalString getDescriptionText(String code)
          Gets a description of the object corresponding to a code.
 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.
protected  void shutdown(boolean active)
          Shutdown the database engine.
 
Methods inherited from class AbstractCachedAuthorityFactory
createCartesianCS, createCompoundCRS, createCoordinateOperation, createCoordinateReferenceSystem, createCoordinateSystem, createCoordinateSystemAxis, createCylindricalCS, createDatum, createDerivedCRS, createEllipsoid, createEllipsoidalCS, createEngineeringCRS, createEngineeringDatum, createFromCoordinateReferenceSystemCodes, createGeocentricCRS, createGeodeticDatum, createGeographicCRS, createImageCRS, createImageDatum, createObject, createPolarCS, createPrimeMeridian, createProjectedCRS, createSphericalCS, createTemporalCRS, createTemporalDatum, createTimeCS, createUnit, createVerticalCRS, createVerticalCS, createVerticalDatum, getAuthorityCodes, getIdentifiedObjectFinder, noSuchAuthorityCode, toKey, trimAuthority
 
Methods inherited from class AbstractAuthorityFactory
createExtent, createOperationMethod, createParameterDescriptor, noSuchAuthorityCode
 
Methods inherited from class ReferencingFactory
ensureNonNull, getVendor
 
Methods inherited from class AbstractFactory
addImplementationHints, equals, getPriority, hashCode, onDeregistration, onRegistration, toString
 
Methods inherited from class Object
clone, getClass, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface Factory
getVendor
 
Methods inherited from interface Factory
getVendor
 
Methods inherited from interface Factory
getVendor
 
Methods inherited from interface Factory
getVendor
 
Methods inherited from interface Factory
getVendor
 

Field Detail

dataSource

protected DataSource dataSource
A DataSource to the EPSG database being used.

Constructor Detail

AbstractEpsgFactory

public AbstractEpsgFactory(Hints userHints)
                    throws FactoryException
Throws:
FactoryException

AbstractEpsgFactory

public AbstractEpsgFactory(Hints userHints,
                           DataSource dataSource)

AbstractEpsgFactory

public AbstractEpsgFactory(Hints userHints,
                           Connection connection)
Constructs an authority factory using the specified connection.

Parameters:
userHints - The underlying factories used for objects creation.
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 AbstractCachedAuthorityFactory

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.

Specified by:
getImplementationHints in interface Factory
Overrides:
getImplementationHints in class AbstractFactory
Returns:
The map of hints, or an empty map if none.

generateAuthorityCodes

protected Set<String> generateAuthorityCodes(Class type)
                                      throws FactoryException
Returns the set of authority codes of the given type.

Specified by:
generateAuthorityCodes in class AbstractCachedAuthorityFactory
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 FactoryException
Gets a description of the object corresponding to a code.

Specified by:
getDescriptionText in interface AuthorityFactory
Specified by:
getDescriptionText in class AbstractCachedAuthorityFactory
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.

generateObject

public IdentifiedObject generateObject(String code)
                                throws FactoryException
Returns an arbitrary object from a code. The default implementation invokes one of AbstractCachedAuthorityFactory.createCoordinateReferenceSystem(java.lang.String), AbstractCachedAuthorityFactory.createCoordinateSystem(java.lang.String), AbstractCachedAuthorityFactory.createDatum(java.lang.String), AbstractCachedAuthorityFactory.createEllipsoid(java.lang.String), or AbstractCachedAuthorityFactory.createUnit(java.lang.String) methods according the object type.

Specified by:
generateObject in class AbstractCachedAuthorityFactory
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 occured in the backing store. This exception usually have SQLException as its cause.

generateUnit

public Unit<?> generateUnit(String code)
                     throws FactoryException
Returns an unit from a code.

Specified by:
generateUnit in class AbstractCachedAuthorityFactory
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 occured in the backing store. This exception usually have SQLException as its cause.

generateEllipsoid

public Ellipsoid generateEllipsoid(String code)
                            throws FactoryException
Returns an ellipsoid from a code.

Specified by:
generateEllipsoid in class AbstractCachedAuthorityFactory
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 occured in the backing store. This exception usually have SQLException as its cause.

generatePrimeMeridian

public PrimeMeridian generatePrimeMeridian(String code)
                                    throws FactoryException
Returns a prime meridian, relative to Greenwich.

Specified by:
generatePrimeMeridian in class AbstractCachedAuthorityFactory
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 occured in the backing store. This exception usually have SQLException as its cause.

generateExtent

public Extent generateExtent(String code)
                      throws FactoryException
Returns an area of use.

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 occured in the backing store. This exception usually have SQLException as its cause.

generateDatum

public Datum generateDatum(String code)
                    throws FactoryException
Returns a datum from a code.

Specified by:
generateDatum in class AbstractCachedAuthorityFactory
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 occured in the backing store. This exception usually have SQLException as its cause.

generateCoordinateSystemAxis

public CoordinateSystemAxis generateCoordinateSystemAxis(String code)
                                                  throws FactoryException
Returns a coordinate system axis from a code.

Specified by:
generateCoordinateSystemAxis in class AbstractCachedAuthorityFactory
Parameters:
code - Value allocated by authority.
Throws:
NoSuchAuthorityCodeException - if the specified code was not found.
FactoryException - if the object creation failed for some other reason.

generateCoordinateSystem

public CoordinateSystem generateCoordinateSystem(String code)
                                          throws FactoryException
Returns a coordinate system from a code.

Specified by:
generateCoordinateSystem in class AbstractCachedAuthorityFactory
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 occured in the backing store. This exception usually have SQLException as its cause.

generateCoordinateReferenceSystem

public CoordinateReferenceSystem generateCoordinateReferenceSystem(String code)
                                                            throws FactoryException
Returns a coordinate reference system from a code.

Specified by:
generateCoordinateReferenceSystem in class AbstractCachedAuthorityFactory
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 occured in the backing store. This exception usually have SQLException as its cause.

generateParameterDescriptor

public ParameterDescriptor generateParameterDescriptor(String code)
                                                throws FactoryException
Returns a parameter descriptor from a code.

Parameters:
code - The parameter descriptor code allocated by EPSG authority.
Throws:
NoSuchAuthorityCodeException - if this method can't find the requested code.
FactoryException - if some other kind of failure occured in the backing store. This exception usually have SQLException as its cause.

generateOperationMethod

public OperationMethod generateOperationMethod(String code)
                                        throws FactoryException
Returns an operation method from a code.

Parameters:
code - The operation method code allocated by EPSG authority.
Throws:
NoSuchAuthorityCodeException - if this method can't find the requested code.
FactoryException - if some other kind of failure occured in the backing store. This exception usually have SQLException as its cause.

generateCoordinateOperation

public CoordinateOperation generateCoordinateOperation(String code)
                                                throws 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:
generateCoordinateOperation in class AbstractCachedAuthorityFactory
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 occured in the backing store. This exception usually have SQLException as its cause.

generateFromCoordinateReferenceSystemCodes

public Set generateFromCoordinateReferenceSystemCodes(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:
generateFromCoordinateReferenceSystemCodes in class AbstractCachedAuthorityFactory
Parameters:
sourceCode - Coded value of source coordinate reference system.
targetCode - Coded value of target coordinate reference system.
Throws:
FactoryException - if the object creation failed.

adaptSQL

protected abstract 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 some syntax specific to this particular database software (for example "SELECT * FROM [Coordinate Reference System]"). When prociding subclass targeting another database vendor, then this method should be overridden in order to adapt the local SQL syntax.

For example a subclass connecting to a PostgreSQL database could replace all spaces (" ") between watching braces ("[" and "]") by underscore ("_").

Parameters:
statement - The statement in MS-Access syntax.
Returns:
The SQL statement to use. The default implementation returns the string unchanged.

isPrimaryKey

protected boolean isPrimaryKey(String code)
                        throws FactoryException
Returns true if the specified code may be a primary key in some table. This method do not needs to checks 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 occured while inspecting the code.

dispose

public void dispose()
             throws FactoryException
Disposes any resources hold by this object.

Overrides:
dispose in class AbstractCachedAuthorityFactory
Throws:
FactoryException - if an error occurred while closing the connection.

connect

public void connect()
             throws FactoryException
Connect to the database in anticipation of of use.

Throws:
FactoryException

disconnect

public void disconnect()
                throws FactoryException
Disconnect from the database, and remain idle. We will still keep our internal data structures, we are not going to hold onto a database connection unless we are going to be used.

Throws:
FactoryException

getConnection

protected Connection getConnection()
                            throws SQLException
Access to the connection used by this EpsgFactory. The connection will be created as needed.

Returns:
the connection
Throws:
SQLException

shutdown

protected void shutdown(boolean active)
                 throws SQLException
Shutdown the database engine. This method is invoked twice by ThreadedEpsgFactory at JVM shutdown: one time before the connection is closed, and a second time after. This shutdown hook is useful for embedded database engine starting a server process in addition to the client process. Just closing the connection is not enough for them. Example:

The default implementation does nothing, which is sufficient for implementations connecting to a distant server (i.e. non-embedded database engine), for example MS-Access or PostgreSQL.

Parameters:
active - true if the connection is alive, or false otherwise. This method is invoked first with active set to true, then a second time with active set to false.
Throws:
SQLException - if this method failed to shutdown the database engine.

finalize

protected final void finalize()
                       throws Throwable
Invokes dispose() when this factory is garbage collected.

Overrides:
finalize in class Object
Throws:
Throwable - if an error occurred while closing the connection.


Copyright © 1996-2009 Geotools. All Rights Reserved.