org.geotools.referencing.factory.epsg
Class FactoryUsingSQL

java.lang.Object
  extended byorg.geotools.factory.AbstractFactory
      extended byorg.geotools.referencing.factory.AbstractFactory
          extended byorg.geotools.referencing.factory.AbstractAuthorityFactory
              extended byorg.geotools.referencing.factory.epsg.FactoryUsingSQL
All Implemented Interfaces:
org.opengis.referencing.AuthorityFactory, org.opengis.referencing.operation.CoordinateOperationAuthorityFactory, org.opengis.referencing.crs.CRSAuthorityFactory, org.opengis.referencing.cs.CSAuthorityFactory, org.opengis.referencing.datum.DatumAuthorityFactory, Factory, org.opengis.referencing.Factory, javax.imageio.spi.RegisterableService
Direct Known Subclasses:
FactoryUsingAnsiSQL

public class FactoryUsingSQL
extends AbstractAuthorityFactory

Default implementation for a coordinate reference system factory backed by the EPSG database. 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 doesn't cache any result. Any call to a method will send a new query to the EPSG database. For caching, this factory should be wrapped in some buffered factory like DefaultFactory.

This factory accepts names as well as numerical identifiers. For example "NTF (Paris) / France I" and 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.

This factory uses the MS-Access dialect of SQL, because the primary distribution format for the EPSG database is MS-Access. For translating this SQL dialect into an other one, subclasses should override the adaptSQL(java.lang.String) method.

Since:
2.1
Version:
$Id: FactoryUsingSQL.java 17672 2006-01-19 00:25:55Z desruisseaux $
Author:
Yann C?zard, Martin Desruisseaux, Rueben Schulz, Matthias Basler

Field Summary
protected  java.sql.Connection connection
          The connection to the EPSG database.
 
Fields inherited from class org.geotools.referencing.factory.AbstractAuthorityFactory
factories
 
Fields inherited from class org.geotools.referencing.factory.AbstractFactory
LOGGER
 
Fields inherited from class org.geotools.factory.AbstractFactory
hints, MAXIMUM_PRIORITY, MINIMUM_PRIORITY, NORMAL_PRIORITY, priority
 
Constructor Summary
FactoryUsingSQL(FactoryGroup factories, java.sql.Connection connection)
          Deprecated. Use FactoryUsingSQL(Hints,Connection) instead.
FactoryUsingSQL(Hints hints, java.sql.Connection connection)
          Constructs an authority factory using the specified connection.
 
Method Summary
protected  java.lang.String adaptSQL(java.lang.String statement)
          Invoked when a new PreparedStatement is about to be created from a SQL string.
 org.opengis.referencing.operation.CoordinateOperation createCoordinateOperation(java.lang.String code)
          Returns a coordinate operation from a code.
 org.opengis.referencing.crs.CoordinateReferenceSystem createCoordinateReferenceSystem(java.lang.String code)
          Returns a coordinate reference system from a code.
 org.opengis.referencing.cs.CoordinateSystem createCoordinateSystem(java.lang.String code)
          Returns a coordinate system from a code.
 org.opengis.referencing.cs.CoordinateSystemAxis createCoordinateSystemAxis(java.lang.String code)
          Returns a coordinate system axis from a code.
 org.opengis.referencing.datum.Datum createDatum(java.lang.String code)
          Returns a datum from a code.
 org.opengis.referencing.datum.Ellipsoid createEllipsoid(java.lang.String code)
          Returns an ellipsoid from a code.
 org.opengis.metadata.extent.Extent createExtent(java.lang.String code)
          Returns an area of use.
 java.util.Set createFromCoordinateReferenceSystemCodes(java.lang.String sourceCode, java.lang.String targetCode)
          Creates operations from coordinate reference system codes.
 org.opengis.referencing.IdentifiedObject createObject(java.lang.String code)
          Returns an arbitrary object from a code.
 org.opengis.referencing.operation.OperationMethod createOperationMethod(java.lang.String code)
          Returns an operation method from a code.
 org.opengis.parameter.ParameterDescriptor createParameterDescriptor(java.lang.String code)
          Returns a parameter descriptor from a code.
 org.opengis.referencing.datum.PrimeMeridian createPrimeMeridian(java.lang.String code)
          Returns a prime meridian, relative to Greenwich.
 javax.units.Unit createUnit(java.lang.String code)
          Returns an unit from a code.
 void dispose()
          Disposes any resources hold by this object.
protected  void finalize()
          Invokes dispose() when this factory is garbage collected.
 org.opengis.metadata.citation.Citation getAuthority()
          Returns the authority for this EPSG database.
 java.util.Set getAuthorityCodes(java.lang.Class type)
          Returns the set of authority codes of the given type.
 java.lang.String getBackingStoreDescription()
          Returns a description of the database engine.
 org.opengis.util.InternationalString getDescriptionText(java.lang.String code)
          Gets a description of the object corresponding to a code.
protected  boolean isPrimaryKey(java.lang.String code)
          Returns 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 org.geotools.referencing.factory.AbstractAuthorityFactory
createCartesianCS, createCompoundCRS, createCylindricalCS, createDerivedCRS, createEllipsoidalCS, createEngineeringCRS, createEngineeringDatum, createGeocentricCRS, createGeodeticDatum, createGeographicCRS, createImageCRS, createImageDatum, createPolarCS, createProjectedCRS, createSphericalCS, createTemporalCRS, createTemporalDatum, createTimeCS, createVerticalCRS, createVerticalCS, createVerticalDatum, getImplementationHints, noSuchAuthorityCode, onRegistration, trimAuthority
 
Methods inherited from class org.geotools.referencing.factory.AbstractFactory
ensureNonNull, getVendor
 
Methods inherited from class org.geotools.factory.AbstractFactory
onDeregistration
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface org.opengis.referencing.Factory
getVendor
 

Field Detail

connection

protected final java.sql.Connection connection
The connection to the EPSG database.

Constructor Detail

FactoryUsingSQL

public FactoryUsingSQL(FactoryGroup factories,
                       java.sql.Connection connection)
Deprecated. Use FactoryUsingSQL(Hints,Connection) instead.

Constructs an authority factory using the specified connection.

Parameters:
factories - The underlying factories used for objects creation.
connection - The connection to the underlying EPSG database.

FactoryUsingSQL

public FactoryUsingSQL(Hints hints,
                       java.sql.Connection connection)
Constructs an authority factory using the specified connection.

Parameters:
hints - The underlying factories used for objects creation.
connection - The connection to the underlying EPSG database.
Since:
2.2
Method Detail

getAuthority

public org.opengis.metadata.citation.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 org.opengis.referencing.AuthorityFactory
Specified by:
getAuthority in class AbstractAuthorityFactory

getBackingStoreDescription

public java.lang.String getBackingStoreDescription()
                                            throws org.opengis.referencing.FactoryException
Returns a description of the database engine.

Overrides:
getBackingStoreDescription in class AbstractAuthorityFactory
Throws:
org.opengis.referencing.FactoryException - if the database's metadata can't be fetched.
To Do:
localize

getAuthorityCodes

public java.util.Set getAuthorityCodes(java.lang.Class type)
                                throws org.opengis.referencing.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(typeothers)
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.

Parameters:
type - The spatial reference objects type (may be ).
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:
org.opengis.referencing.FactoryException - if access to the underlying database failed.
Since:
2.2

getDescriptionText

public org.opengis.util.InternationalString getDescriptionText(java.lang.String code)
                                                        throws org.opengis.referencing.FactoryException
Gets a description of the object corresponding to a code.

Parameters:
code - Value allocated by authority.
Returns:
A description of the object, or if the object corresponding to the specified has no description.
Throws:
org.opengis.referencing.NoSuchAuthorityCodeException - if the specified was not found.
org.opengis.referencing.FactoryException - if the query failed for some other reason.
Since:
2.2

createObject

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

Specified by:
createObject in interface org.opengis.referencing.AuthorityFactory
Overrides:
createObject in class AbstractAuthorityFactory
Parameters:
code - The EPSG value.
Returns:
The object.
Throws:
org.opengis.referencing.NoSuchAuthorityCodeException - if this method can't find the requested code.
org.opengis.referencing.FactoryException - if some other kind of failure occured in the backing store. This exception usually have SQLException as its cause.
See Also:
AbstractAuthorityFactory.createCoordinateReferenceSystem(java.lang.String), AbstractAuthorityFactory.createDatum(java.lang.String), AbstractAuthorityFactory.createEllipsoid(java.lang.String), AbstractAuthorityFactory.createUnit(java.lang.String)

createUnit

public javax.units.Unit createUnit(java.lang.String code)
                            throws org.opengis.referencing.FactoryException
Returns an unit from a code.

Specified by:
createUnit in interface org.opengis.referencing.cs.CSAuthorityFactory
Overrides:
createUnit in class AbstractAuthorityFactory
Parameters:
code - Value allocated by authority.
Returns:
The unit object.
Throws:
org.opengis.referencing.NoSuchAuthorityCodeException - if this method can't find the requested code.
org.opengis.referencing.FactoryException - if some other kind of failure occured in the backing store. This exception usually have SQLException as its cause.

createEllipsoid

public org.opengis.referencing.datum.Ellipsoid createEllipsoid(java.lang.String code)
                                                        throws org.opengis.referencing.FactoryException
Returns an ellipsoid from a code.

Specified by:
createEllipsoid in interface org.opengis.referencing.datum.DatumAuthorityFactory
Overrides:
createEllipsoid in class AbstractAuthorityFactory
Parameters:
code - The EPSG value.
Returns:
The ellipsoid object.
Throws:
org.opengis.referencing.NoSuchAuthorityCodeException - if this method can't find the requested code.
org.opengis.referencing.FactoryException - if some other kind of failure occured in the backing store. This exception usually have SQLException as its cause.
See Also:
AbstractAuthorityFactory.createGeodeticDatum(java.lang.String)

createPrimeMeridian

public org.opengis.referencing.datum.PrimeMeridian createPrimeMeridian(java.lang.String code)
                                                                throws org.opengis.referencing.FactoryException
Returns a prime meridian, relative to Greenwich.

Specified by:
createPrimeMeridian in interface org.opengis.referencing.datum.DatumAuthorityFactory
Overrides:
createPrimeMeridian in class AbstractAuthorityFactory
Parameters:
code - Value allocated by authority.
Returns:
The prime meridian object.
Throws:
org.opengis.referencing.NoSuchAuthorityCodeException - if this method can't find the requested code.
org.opengis.referencing.FactoryException - if some other kind of failure occured in the backing store. This exception usually have SQLException as its cause.
See Also:
AbstractAuthorityFactory.createGeodeticDatum(java.lang.String)

createExtent

public org.opengis.metadata.extent.Extent createExtent(java.lang.String code)
                                                throws org.opengis.referencing.FactoryException
Returns an area of use.

Overrides:
createExtent in class AbstractAuthorityFactory
Parameters:
code - Value allocated by authority.
Returns:
The area of use.
Throws:
org.opengis.referencing.NoSuchAuthorityCodeException - if this method can't find the requested code.
org.opengis.referencing.FactoryException - if some other kind of failure occured in the backing store. This exception usually have SQLException as its cause.

createDatum

public org.opengis.referencing.datum.Datum createDatum(java.lang.String code)
                                                throws org.opengis.referencing.FactoryException
Returns a datum from a code.

Specified by:
createDatum in interface org.opengis.referencing.datum.DatumAuthorityFactory
Overrides:
createDatum in class AbstractAuthorityFactory
Parameters:
code - Value allocated by authority.
Returns:
The datum object.
Throws:
org.opengis.referencing.NoSuchAuthorityCodeException - if this method can't find the requested code.
org.opengis.referencing.FactoryException - if some other kind of failure occured in the backing store. This exception usually have SQLException as its cause.
See Also:
AbstractAuthorityFactory.createGeodeticDatum(java.lang.String), AbstractAuthorityFactory.createVerticalDatum(java.lang.String), AbstractAuthorityFactory.createTemporalDatum(java.lang.String)
To Do:
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 org.opengis.referencing.cs.CoordinateSystemAxis createCoordinateSystemAxis(java.lang.String code)
                                                                           throws org.opengis.referencing.FactoryException
Returns a coordinate system axis from a code.

Specified by:
createCoordinateSystemAxis in interface org.opengis.referencing.cs.CSAuthorityFactory
Overrides:
createCoordinateSystemAxis in class AbstractAuthorityFactory
Parameters:
code - Value allocated by authority.
Throws:
org.opengis.referencing.NoSuchAuthorityCodeException - if the specified was not found.
org.opengis.referencing.FactoryException - if the object creation failed for some other reason.
To Do:
Not yet implemented.

createCoordinateSystem

public org.opengis.referencing.cs.CoordinateSystem createCoordinateSystem(java.lang.String code)
                                                                   throws org.opengis.referencing.FactoryException
Returns a coordinate system from a code.

Specified by:
createCoordinateSystem in interface org.opengis.referencing.cs.CSAuthorityFactory
Overrides:
createCoordinateSystem in class AbstractAuthorityFactory
Parameters:
code - Value allocated by authority.
Returns:
The coordinate system object.
Throws:
org.opengis.referencing.NoSuchAuthorityCodeException - if this method can't find the requested code.
org.opengis.referencing.FactoryException - if some other kind of failure occured in the backing store. This exception usually have SQLException as its cause.

createCoordinateReferenceSystem

public org.opengis.referencing.crs.CoordinateReferenceSystem createCoordinateReferenceSystem(java.lang.String code)
                                                                                      throws org.opengis.referencing.FactoryException
Returns a coordinate reference system from a code.

Specified by:
createCoordinateReferenceSystem in interface org.opengis.referencing.crs.CRSAuthorityFactory
Overrides:
createCoordinateReferenceSystem in class AbstractAuthorityFactory
Parameters:
code - Value allocated by authority.
Returns:
The coordinate reference system object.
Throws:
org.opengis.referencing.NoSuchAuthorityCodeException - if this method can't find the requested code.
org.opengis.referencing.FactoryException - if some other kind of failure occured in the backing store. This exception usually have SQLException as its cause.
See Also:
AbstractAuthorityFactory.createGeographicCRS(java.lang.String), AbstractAuthorityFactory.createProjectedCRS(java.lang.String), AbstractAuthorityFactory.createVerticalCRS(java.lang.String), AbstractAuthorityFactory.createTemporalCRS(java.lang.String), AbstractAuthorityFactory.createCompoundCRS(java.lang.String)

createParameterDescriptor

public org.opengis.parameter.ParameterDescriptor createParameterDescriptor(java.lang.String code)
                                                                    throws org.opengis.referencing.FactoryException
Returns a parameter descriptor from a code.

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

createOperationMethod

public org.opengis.referencing.operation.OperationMethod createOperationMethod(java.lang.String code)
                                                                        throws org.opengis.referencing.FactoryException
Returns an operation method from a code.

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

createCoordinateOperation

public org.opengis.referencing.operation.CoordinateOperation createCoordinateOperation(java.lang.String code)
                                                                                throws org.opengis.referencing.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 org.opengis.referencing.operation.CoordinateOperationAuthorityFactory
Overrides:
createCoordinateOperation in class AbstractAuthorityFactory
Parameters:
code - Value allocated by authority.
Returns:
The coordinate operation object.
Throws:
org.opengis.referencing.NoSuchAuthorityCodeException - if this method can't find the requested code.
org.opengis.referencing.FactoryException - if some other kind of failure occured in the backing store. This exception usually have SQLException as its cause.
Since:
2.2

createFromCoordinateReferenceSystemCodes

public java.util.Set createFromCoordinateReferenceSystemCodes(java.lang.String sourceCode,
                                                              java.lang.String targetCode)
                                                       throws org.opengis.referencing.FactoryException
Creates operations from coordinate reference system codes. The returned set is ordered with the most accurate operations first.

Specified by:
createFromCoordinateReferenceSystemCodes in interface org.opengis.referencing.operation.CoordinateOperationAuthorityFactory
Overrides:
createFromCoordinateReferenceSystemCodes in class AbstractAuthorityFactory
Parameters:
sourceCode - Coded value of source coordinate reference system.
targetCode - Coded value of target coordinate reference system.
Throws:
org.opengis.referencing.FactoryException - if the object creation failed.
Since:
2.2
To Do:
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 unknow accuracy last). Unfortunatly, 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).

adaptSQL

protected java.lang.String adaptSQL(java.lang.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]"). If the EPSG database is ported to an other software, then this method should be overriden in order to adapt the 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(java.lang.String code)
                        throws org.opengis.referencing.FactoryException
Returns 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 if all non-space characters are digits.

When this method returns , some 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 primary key. Both should fetch the same object.

If this method returns in all cases, then this factory never search for matching names. In such case, an appropriate exception will be thrown in 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:
if the code is probably a primary key.
Throws:
org.opengis.referencing.FactoryException - if an unexpected error occured while inspecting the code.
Since:
2.2

dispose

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

Overrides:
dispose in class AbstractAuthorityFactory
Throws:
org.opengis.referencing.FactoryException - if an error occured while closing the connection.

shutdown

protected void shutdown(boolean active)
                 throws java.sql.SQLException
Shutdown the database engine. This method is invoked twice by DefaultFactory at JVM shutdown: one time before the connection is closed, and a second time after. This shutdown hook is usefull 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 suffisient for implementations connecting to a distant server (i.e. non-embedded database engine), for example MS-Access or PostgreSQL.

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

finalize

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

Throws:
java.lang.Throwable - if an error occured while closing the connection.


Copyright © GeoTools. All Rights Reserved.