org.apache.sis.referencing.factory.sql

Class EPSGDataAccess

Object

AbstractFactory

GeodeticAuthorityFactory

EPSGDataAccess

All Implemented Interfaces:

AutoCloseable, Localized, AuthorityFactory, CRSAuthorityFactory, CSAuthorityFactory, DatumAuthorityFactory, CoordinateOperationAuthorityFactory, Factory

public class EPSGDataAccess
extends GeodeticAuthorityFactory
implements CRSAuthorityFactory, CSAuthorityFactory, DatumAuthorityFactory, CoordinateOperationAuthorityFactory, Localized, AutoCloseable

Data Access Object (DAO) creating geodetic objects from a JDBC connection to an 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.

Object identifier (code or name)

EPSG codes are numerical identifiers. For example code 3395 stands for "WGS 84 / World Mercator". Coordinate Reference Objects are normally created from their numerical codes, but this factory accepts also names. For example create­Projected­CRS("3395") and create­Projected­CRS("WGS 84 / World Mercator") 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 instance. If such an ambiguity is found, an exception will be thrown.

Life cycle and caching

EPSGData­Access instances should be short-lived since they may hold a significant amount of JDBC resources. EPSGData­Access instances are created on the fly by EPSGFactory and closed after a relatively short timeout. In addition EPSGFactory caches the most recently created objects, which reduce greatly the amount of EPSGData­Access instantiations (and consequently the amount of database accesses) in the common case where only a few EPSG codes are used by an application. EPSGData­Access.create­Foo(String) methods do not cache by themselves and query the database on every invocation.

SQL dialects

Because the primary distribution format for the EPSG dataset is MS-Access, this class uses SQL statements formatted for the MS-Access dialect. For usage with other database software products like PostgreSQL or Derby, a SQLTranslator instance is provided to the constructor.

Since:

0.7

See Also:

List of authority codes

Defined in the sis-referencing module

Field Summary

Fields

Modifier and Type	Field and Description
protected Connection	connection The connection to the EPSG database.
protected EPSGFactory	owner The Concurrent­Authority­Factory that created this Data Access Object (DAO).
protected SQLTranslator	translator The translator from the SQL statements using MS-Access dialect to SQL statements using the dialect of the actual database.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	EPSGDataAccess(EPSGFactory owner, Connection connection, SQLTranslator translator) Creates a factory using the given connection.

Method Summary

Modifier and Type	Method and Description
void	close() Closes the JDBC connection used by this factory.
CoordinateOperation	createCoordinateOperation(String code) Creates an operation for transforming coordinates in the source CRS to coordinates in the target CRS.
CoordinateReferenceSystem	createCoordinateReferenceSystem(String code) Creates an arbitrary coordinate reference system from a code.
CoordinateSystem	createCoordinateSystem(String code) Creates an arbitrary coordinate system from a code.
CoordinateSystemAxis	createCoordinateSystemAxis(String code) Creates a coordinate system axis with name, direction, unit and range of values.
Datum	createDatum(String code) Creates an arbitrary datum from a code.
Ellipsoid	createEllipsoid(String code) Creates a geometric figure that can be used to describe the approximate shape of the earth.
Extent	createExtent(String code) Creates information about spatial, vertical, and temporal extent (usually a domain of validity) from a code.
Set<CoordinateOperation>	createFromCoordinateReferenceSystemCodes(String sourceCRS, String targetCRS) Creates operations from source and target coordinate reference system codes.
IdentifiedObject	createObject(String code) Returns an arbitrary object from a code.
OperationMethod	createOperationMethod(String code) Creates description of the algorithm and parameters used to perform a coordinate operation.
ParameterDescriptor<?>	createParameterDescriptor(String code) Creates a definition of a single parameter used by an operation method.
PrimeMeridian	createPrimeMeridian(String code) Creates a prime meridian defining the origin from which longitude values are determined.
Unit<?>	createUnit(String code) Creates an unit of measurement from a code.
Citation	getAuthority() Returns the authority for this EPSG dataset.
Set<String>	getAuthorityCodes(Class<? extends IdentifiedObject> type) Returns the set of authority codes of the given type.
Set<String>	getCodeSpaces() Returns an empty set since this data access class expects no namespace.
InternationalString	getDescriptionText(String code) Gets a description of the object corresponding to a code.
Locale	getLocale() Returns the locale used by this factory for producing error messages.
IdentifiedObjectFinder	newIdentifiedObjectFinder() Returns a finder which can be used for looking up unidentified objects.

Methods inherited from class GeodeticAuthorityFactory

create­Cartesian­CS, create­Compound­CRS, create­Cylindrical­CS, create­Derived­CRS, create­Ellipsoidal­CS, create­Engineering­CRS, create­Engineering­Datum, create­Geocentric­CRS, create­Geodetic­Datum, create­Geographic­CRS, create­Image­CRS, create­Image­Datum, create­Parametric­CRS, create­Parametric­CS, create­Parametric­Datum, create­Polar­CS, create­Projected­CRS, create­Spherical­CS, create­Temporal­CRS, create­Temporal­Datum, create­Time­CS, create­Vertical­CRS, create­Vertical­CS, create­Vertical­Datum, to­String, trim­Namespace

Methods inherited from class AbstractFactory

get­Vendor

Methods inherited from class Object

clone, equals, finalize, get­Class, hash­Code, notify, notify­All, wait, wait, wait

Methods inherited from interface CRSAuthorityFactory

create­Compound­CRS, create­Derived­CRS, create­Engineering­CRS, create­Geocentric­CRS, create­Geographic­CRS, create­Image­CRS, create­Projected­CRS, create­Temporal­CRS, create­Vertical­CRS

Methods inherited from interface CSAuthorityFactory

create­Cartesian­CS, create­Cylindrical­CS, create­Ellipsoidal­CS, create­Polar­CS, create­Spherical­CS, create­Time­CS, create­Vertical­CS

Methods inherited from interface DatumAuthorityFactory

create­Engineering­Datum, create­Geodetic­Datum, create­Image­Datum, create­Temporal­Datum, create­Vertical­Datum

Methods inherited from interface Factory

get­Vendor

Field Detail

owner

protected final EPSGFactory owner

The Concurrent­Authority­Factory that created this Data Access Object (DAO). The owner supplies caching for all create­Foo(String) methods.

connection

protected final Connection connection

The connection to the EPSG database. This connection is specified at construction time and closed by the close() method.

See Also:

close()

translator

protected final SQLTranslator translator

The translator from the SQL statements using MS-Access dialect to SQL statements using the dialect of the actual database.

Constructor Detail

EPSGDataAccess

protected EPSGDataAccess(EPSGFactory owner,
                         Connection connection,
                         SQLTranslator translator)

Creates a factory using the given connection. The connection will be closed when this factory will be closed.

API design note: this constructor is protected because EPSGData­Access instances should not be created as standalone factories. This constructor is for allowing definition of custom EPSGData­Access subclasses, which are then instantiated by the EPSGFactory.new­Data­Access(Connection, SQLTranslator) method of a corresponding custom EPSGFactory subclass.

Parameters:

owner - the EPSGFactory which is creating this Data Access Object (DAO).

connection - the connection to the underlying EPSG database.

translator - the translator from the SQL statements using MS-Access dialect to SQL statements using the dialect of the actual database.

See Also:

EPSGFactory.new­Data­Access(Connection, SQLTranslator)

Method Detail

getLocale

public Locale getLocale()

Returns the locale used by this factory for producing error messages. This locale does not change the way data are read from the EPSG database.

Specified by:

get­Locale in interface Localized

Returns:

the locale for error messages.

getAuthority

public Citation getAuthority()

Returns the authority for this EPSG dataset. The returned citation contains the database version in the edition attribute, together with date of last update in the edition date. Example (the exact content will vary with Apache SIS versions, JDBC driver and EPSG dataset versions):

Citation
├─ Title ……………………………………………………… EPSG Geodetic Parameter Dataset
├─ Identifier ………………………………………… EPSG
├─ Online resource (1 of 2)
│  ├─ Linkage ………………………………………… http://epsg-registry.org/
│  └─ Function ……………………………………… Browse
└─ Online resource (2 of 2)
   ├─ Linkage ………………………………………… jdbc:derby:/my/path/to/SIS_DATA/Databases/SpatialMetadata
   ├─ Description ……………………………… EPSG dataset version 8.9 on “Apache Derby Embedded JDBC Driver” version 10.12.
   └─ Function ……………………………………… Connection

Specified by:

get­Authority in interface Authority­Factory

Specified by:

get­Authority in class Geodetic­Authority­Factory

Returns:

the organization responsible for definition of the database, or null if unknown.

See Also:

Abstract­Factory.get­Vendor()

getAuthorityCodes

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

Returns the set of authority codes of the given type. This returned set may keep a connection to the EPSG database, so the set can execute efficiently idioms like the following one:

getAuthorityCodes(type).containsAll(others)

The returned set should not be referenced for a long time, as it may prevent this factory to release JDBC resources. If the set of codes is needed for a long time, their values should be copied in another collection object.

Handling of deprecated objects

The collection returned by this method gives an enumeration of EPSG codes for valid objects only. The EPSG codes of deprecated objects are not included in iterations, computation of Set.size() value, Set.to­String() result, etc. with one exception: a call to Set.contains(…) will return true if the given identifier exists for a deprecated object, even if that identifier does not show up in iterations.

An other point of view could be to said that the returned collection behaves as if the deprecated codes were included in the set but invisible.

Specified by:

get­Authority­Codes in interface Authority­Factory

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 (may be an empty set).

Throws:

Factory­Exception - if access to the underlying database failed.

getCodeSpaces

public Set<String> getCodeSpaces()

Returns an empty set since this data access class expects no namespace. Code shall be given to create­Foo(String) methods directly, without "EPSG:" prefix.

Overrides:

get­Code­Spaces in class Geodetic­Authority­Factory

Returns:

empty set.

getDescriptionText

public InternationalString getDescriptionText(String code)
                                       throws NoSuchAuthorityCodeException,
                                              FactoryException

Gets a description of the object corresponding to a code. This method returns the object name in a lightweight manner, without creating the full Identified­Object.

Specified by:

get­Description­Text in interface Authority­Factory

Overrides:

get­Description­Text in class Geodetic­Authority­Factory

Parameters:

code - value allocated by authority.

Returns:

the object name, or null if the object corresponding to the specified code has no name.

Throws:

No­Such­Authority­Code­Exception - if the specified code was not found.

Factory­Exception - 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 delegates to more specific methods, for example create­Coordinate­Reference­System(String), create­Datum(String), etc. until a successful one is found.

Note that this method may be ambiguous since the same EPSG code can be used for different kind of objects. This method throws an exception if it detects an ambiguity on a best-effort basis. It is recommended to invoke the most specific create­Foo(String) method when the desired type is known, both for performance reason and for avoiding ambiguity.

Specified by:

create­Object in interface Authority­Factory

Specified by:

create­Object in class Geodetic­Authority­Factory

Parameters:

code - value allocated by EPSG.

Returns:

the object for the given code.

Throws:

No­Such­Authority­Code­Exception - if the specified code was not found.

Factory­Exception - if the object creation failed for some other reason.

See Also:

create­Coordinate­Reference­System(String), create­Datum(String), create­Coordinate­System(String)

createCoordinateReferenceSystem

public CoordinateReferenceSystem createCoordinateReferenceSystem(String code)
                                                          throws NoSuchAuthorityCodeException,
                                                                 FactoryException

Creates an arbitrary coordinate reference system from a code. The returned object will typically be an instance of Geographic­CRS, Projected­CRS, Vertical­CRS or Compound­CRS.

Example: some EPSG codes for coordinate reference systems are:

Code	Type	Description
4326	Geographic	World Geodetic System 1984
4979	Geographic 3D	World Geodetic System 1984
4978	Geocentric	World Geodetic System 1984
3395	Projected	WGS 84 / World Mercator
5714	Vertical	Mean Sea Level height
6349	Compound	NAD83(2011) + NAVD88 height
5800	Engineering	Astra Minas Grid

Specified by:

create­Coordinate­Reference­System in interface CRSAuthority­Factory

Overrides:

create­Coordinate­Reference­System in class Geodetic­Authority­Factory

Parameters:

code - value allocated by EPSG.

Returns:

the coordinate reference system for the given code.

Throws:

No­Such­Authority­Code­Exception - if the specified code was not found.

Factory­Exception - if the object creation failed for some other reason.

See Also:

Abstract­CRS, CRS.for­Code(String)

createDatum

public Datum createDatum(String code)
                  throws NoSuchAuthorityCodeException,
                         FactoryException

Creates an arbitrary datum from a code. The returned object will typically be an instance of Geodetic­Datum, Vertical­Datum or Temporal­Datum.

Example: some EPSG codes for datums are:

Code	Type	Description
6326	Geodetic	World Geodetic System 1984
6322	Geodetic	World Geodetic System 1972
1027	Vertical	EGM2008 geoid
5100	Vertical	Mean Sea Level
9315	Engineering	Seismic bin grid datum

Specified by:

create­Datum in interface Datum­Authority­Factory

Overrides:

create­Datum in class Geodetic­Authority­Factory

Parameters:

code - value allocated by EPSG.

Returns:

the datum for the given code.

Throws:

No­Such­Authority­Code­Exception - if the specified code was not found.

Factory­Exception - if the object creation failed for some other reason.

See Also:

Abstract­Datum

createEllipsoid

public Ellipsoid createEllipsoid(String code)
                          throws NoSuchAuthorityCodeException,
                                 FactoryException

Creates a geometric figure that can be used to describe the approximate shape of the earth. In mathematical terms, it is a surface formed by the rotation of an ellipse about its minor axis.

Example: some EPSG codes for ellipsoids are:

Code	Description
7030	WGS 84
7034	Clarke 1880
7048	GRS 1980 Authalic Sphere

Specified by:

create­Ellipsoid in interface Datum­Authority­Factory

Overrides:

create­Ellipsoid in class Geodetic­Authority­Factory

Parameters:

code - value allocated by EPSG.

Returns:

the ellipsoid for the given code.

Throws:

No­Such­Authority­Code­Exception - if the specified code was not found.

Factory­Exception - if the object creation failed for some other reason.

See Also:

Geodetic­Authority­Factory.create­Geodetic­Datum(String), Geodetic­Authority­Factory.create­Ellipsoidal­CS(String), Default­Ellipsoid

createPrimeMeridian

public PrimeMeridian createPrimeMeridian(String code)
                                  throws NoSuchAuthorityCodeException,
                                         FactoryException

Creates a prime meridian defining the origin from which longitude values are determined.

Example: some EPSG codes for prime meridians are:

Code	Description
8901	Greenwich
8903	Paris
8904	Bogota
8905	Madrid
8906	Rome

Specified by:

create­Prime­Meridian in interface Datum­Authority­Factory

Overrides:

create­Prime­Meridian in class Geodetic­Authority­Factory

Parameters:

code - value allocated by EPSG.

Returns:

the prime meridian for the given code.

Throws:

No­Such­Authority­Code­Exception - if the specified code was not found.

Factory­Exception - if the object creation failed for some other reason.

See Also:

Geodetic­Authority­Factory.create­Geodetic­Datum(String), Default­Prime­Meridian

createExtent

public Extent createExtent(String code)
                    throws NoSuchAuthorityCodeException,
                           FactoryException

Creates information about spatial, vertical, and temporal extent (usually a domain of validity) from a code.

Example: some EPSG codes for extents are:

Code	Description
1262	World
3391	World - between 80°S and 84°N

Overrides:

create­Extent in class Geodetic­Authority­Factory

Parameters:

code - value allocated by EPSG.

Returns:

the extent for the given code.

Throws:

No­Such­Authority­Code­Exception - if the specified code was not found.

Factory­Exception - if the object creation failed for some other reason.

See Also:

create­Coordinate­Reference­System(String), create­Datum(String), Default­Extent

createCoordinateSystem

public CoordinateSystem createCoordinateSystem(String code)
                                        throws NoSuchAuthorityCodeException,
                                               FactoryException

Creates an arbitrary coordinate system from a code. The returned object will typically be an instance of Ellipsoidal­CS, Cartesian­CS or Vertical­CS.

Example: some EPSG codes for coordinate systems are:

Code	Type	Axes	Orientations	Unit
4406	Cartesian 2D CS	easting, northing (E,N)	east, north	kilometre
4496	Cartesian 2D CS	easting, northing (E,N)	east, north	metre
4500	Cartesian 2D CS	northing, easting (N,E)	north, east	metre
4491	Cartesian 2D CS	westing, northing (W,N)	west, north	metre
6422	Ellipsoidal 2D CS	latitude, longitude	north, east	degree
6424	Ellipsoidal 2D CS	longitude, latitude	east, north	degree
6429	Ellipsoidal 2D CS	longitude, latitude	east, north	radian
6423	Ellipsoidal 3D CS	latitude, longitude, ellipsoidal height	north, east, up	degree, degree, metre
6404	Spherical 3D CS	latitude, longitude, radius	north, east, up	degree, degree, metre
6498	Vertical CS	depth (D)	down	metre
6499	Vertical CS	height (H)	up	metre

Specified by:

create­Coordinate­System in interface CSAuthority­Factory

Overrides:

create­Coordinate­System in class Geodetic­Authority­Factory

Parameters:

code - value allocated by EPSG.

Returns:

the coordinate system for the given code.

Throws:

No­Such­Authority­Code­Exception - if the specified code was not found.

Factory­Exception - if the object creation failed for some other reason.

See Also:

Abstract­CS, Coordinate­Systems.get­Epsg­Code(Unit, Axis­Direction...)

createCoordinateSystemAxis

public CoordinateSystemAxis createCoordinateSystemAxis(String code)
                                                throws NoSuchAuthorityCodeException,
                                                       FactoryException

Creates a coordinate system axis with name, direction, unit and range of values.

Example: some EPSG codes for axes are:

Code	Description	Unit
106	Latitude (φ)	degree
107	Longitude (λ)	degree
1	Easting (E)	metre
2	Northing (N)	metre

Specified by:

create­Coordinate­System­Axis in interface CSAuthority­Factory

Overrides:

create­Coordinate­System­Axis in class Geodetic­Authority­Factory

Parameters:

code - value allocated by EPSG.

Returns:

the axis for the given code.

Throws:

No­Such­Authority­Code­Exception - if the specified code was not found.

Factory­Exception - if the object creation failed for some other reason.

See Also:

create­Coordinate­System(String), Default­Coordinate­System­Axis

createUnit

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

Creates an unit of measurement from a code. Current implementation first checks if Units.value­Of­EPSG(int) can provide a hard-coded unit for the given code before to try to parse the information found in the database. This is done that way for better support of non-straightforward units like sexagesimal degrees (EPSG:9110 and 9111).

Example: some EPSG codes for units are:

Code	Description
9002	decimal degree
9001	metre
9030	kilometre
1040	second
1029	year

Specified by:

create­Unit in interface CSAuthority­Factory

Overrides:

create­Unit in class Geodetic­Authority­Factory

Parameters:

code - value allocated by EPSG.

Returns:

the unit of measurement for the given code.

Throws:

No­Such­Authority­Code­Exception - if the specified code was not found.

Factory­Exception - if the object creation failed for some other reason.

See Also:

Units.value­Of­EPSG(int)

createParameterDescriptor

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

Creates a definition of a single parameter used by an operation method.

Example: some EPSG codes for parameters are:

Code	Description
8801	Latitude of natural origin
8802	Longitude of natural origin
8805	Scale factor at natural origin
8806	False easting
8807	False northing

Overrides:

create­Parameter­Descriptor in class Geodetic­Authority­Factory

Parameters:

code - value allocated by EPSG.

Returns:

the parameter descriptor for the given code.

Throws:

No­Such­Authority­Code­Exception - if the specified code was not found.

Factory­Exception - if the object creation failed for some other reason.

See Also:

Default­Parameter­Descriptor

createOperationMethod

public OperationMethod createOperationMethod(String code)
                                      throws NoSuchAuthorityCodeException,
                                             FactoryException

Creates description of the algorithm and parameters used to perform a coordinate operation. An Operation­Method is a kind of metadata: it does not perform any coordinate operation (e.g. map projection) by itself, but tells us what is needed in order to perform such operation.

Example: some EPSG codes for operation methods are:

Code	Description
9804	Mercator (variant A)
9802	Lambert Conic Conformal (2SP)
9810	Polar Stereographic (variant A)
9624	Affine parametric transformation

Specified by:

create­Operation­Method in interface Coordinate­Operation­Authority­Factory

Overrides:

create­Operation­Method in class Geodetic­Authority­Factory

Parameters:

code - value allocated by EPSG.

Returns:

the operation method for the given code.

Throws:

No­Such­Authority­Code­Exception - if the specified code was not found.

Factory­Exception - if the object creation failed for some other reason.

See Also:

Default­Operation­Method, Apache SIS™ Coordinate Operation Methods

createCoordinateOperation

public CoordinateOperation createCoordinateOperation(String code)
                                              throws NoSuchAuthorityCodeException,
                                                     FactoryException

Creates an operation for transforming coordinates in the source CRS to coordinates in the target CRS. The returned object will either be a Conversion or a Transformation, depending on the code.

Example: some EPSG codes for coordinate transformations are:

Code	Description
1133	ED50 to WGS 84 (1)
1241	NAD27 to NAD83 (1)
1173	NAD27 to WGS 84 (4)
6326	NAD83(2011) to NAVD88 height (1)

Specified by:

create­Coordinate­Operation in interface Coordinate­Operation­Authority­Factory

Overrides:

create­Coordinate­Operation in class Geodetic­Authority­Factory

Parameters:

code - value allocated by EPSG.

Returns:

the operation for the given code.

Throws:

No­Such­Authority­Code­Exception - if the specified code was not found.

Factory­Exception - if the object creation failed for some other reason.

See Also:

Abstract­Coordinate­Operation

createFromCoordinateReferenceSystemCodes

public Set<CoordinateOperation> createFromCoordinateReferenceSystemCodes(String sourceCRS,
                                                                         String targetCRS)
                                                                  throws FactoryException

Creates operations from source and target coordinate reference system codes. This method only extract the information explicitely declared in the EPSG database; it does not attempt to infer by itself operations that are not explicitely recorded in the database.

The returned set is ordered with the most accurate operations first. Deprecated operations are not included in the set; if a deprecated operation is really wanted, it can be fetched by an explicit call to create­Coordinate­Operation(String).

Specified by:

create­From­Coordinate­Reference­System­Codes in interface Coordinate­Operation­Authority­Factory

Overrides:

create­From­Coordinate­Reference­System­Codes in class Geodetic­Authority­Factory

Parameters:

source­CRS - coded value of source coordinate reference system.

target­CRS - coded value of target coordinate reference system.

Returns:

the operations from source­CRS to target­CRS.

Throws:

No­Such­Authority­Code­Exception - if a specified code was not found.

Factory­Exception - if the object creation failed for some other reason.

newIdentifiedObjectFinder

public IdentifiedObjectFinder newIdentifiedObjectFinder()
                                                 throws FactoryException

Returns a finder which can be used for looking up unidentified objects. The finder tries to fetch a fully identified object from an incomplete one, for example from an object without "ID[…]" or "AUTHORITY[…]" element in Well Known Text.

Overrides:

new­Identified­Object­Finder in class Geodetic­Authority­Factory

Returns:

a finder to use for looking up unidentified objects.

Throws:

Factory­Exception - if the finder can not be created.

See Also:

Identified­Objects.new­Finder(String)

close

public void close()
           throws FactoryException

Closes the JDBC connection used by this factory. If this EPSGData­Access is used by an EPSGFactory, then this method will be automatically invoked after some timeout.

Specified by:

close in interface Auto­Closeable

Throws:

Factory­Exception - if an error occurred while closing the connection.

See Also:

connection