Package org.apache.sis.referencing.factory.sql

Class EPSGDataAccess

java.lang.Object
org.apache.sis.util.iso.AbstractFactory
org.apache.sis.referencing.factory.GeodeticAuthorityFactory
org.apache.sis.referencing.factory.sql.EPSGDataAccess
All Implemented Interfaces:
AutoCloseable, Localized, org.opengis.referencing.AuthorityFactory, org.opengis.referencing.crs.CRSAuthorityFactory, org.opengis.referencing.cs.CSAuthorityFactory, org.opengis.referencing.datum.DatumAuthorityFactory, org.opengis.referencing.operation.CoordinateOperationAuthorityFactory, org.opengis.util.Factory
public class EPSGDataAccess extends GeodeticAuthorityFactory implements org.opengis.referencing.crs.CRSAuthorityFactory, org.opengis.referencing.cs.CSAuthorityFactory, org.opengis.referencing.datum.DatumAuthorityFactory, org.opengis.referencing.operation.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 https://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, createProjectedCRS("3395") and createProjectedCRS("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

EPSGDataAccess instances should be short-lived since they may hold a significant amount of JDBC resources. EPSGDataAccess 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 EPSGDataAccess instantiations (and consequently the amount of database accesses) in the common case where only a few EPSG codes are used by an application. EPSGDataAccess.createFoo(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
Version:
1.2
Author:
Yann Cézard (IRD), Martin Desruisseaux (IRD, Geomatys), Rueben Schulz (UBC), Matthias Basler, Andrea Aime (TOPP), Johann Sorel (Geomatys)
See Also:

  • Field Details

    • owner

      protected final EPSGFactory owner
      The ConcurrentAuthorityFactory that created this Data Access Object (DAO). The owner supplies caching for all createFoo(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:

    • 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 Details

    • 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 EPSGDataAccess instances should not be created as standalone factories. This constructor is for allowing definition of custom EPSGDataAccess subclasses, which are then instantiated by the EPSGFactory.newDataAccess(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:

  • Method Details

    • 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:
      getLocale in interface Localized
      Returns:
      the locale for error messages.

    • getAuthority

      public org.opengis.metadata.citation.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):
      Specified by:
      getAuthority in interface org.opengis.referencing.AuthorityFactory
      Specified by:
      getAuthority in class GeodeticAuthorityFactory
      Returns:
      the organization responsible for definition of the database, or null if unknown.
      See Also:

    • getAuthorityCodes

      public Set<String> getAuthorityCodes(Class<? extends org.opengis.referencing.IdentifiedObject> type) throws org.opengis.util.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: 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.toString() 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. In other words, the returned collection behaves as if deprecated codes were included in the set but invisible.
      Specified by:
      getAuthorityCodes in interface org.opengis.referencing.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 (may be an empty set).
      Throws:
      org.opengis.util.FactoryException - 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 createFoo(String) methods directly, without "EPSG:" prefix.
      Overrides:
      getCodeSpaces in class GeodeticAuthorityFactory
      Returns:
      empty set.

    • getDescriptionText

      public org.opengis.util.InternationalString getDescriptionText(String code) throws org.opengis.referencing.NoSuchAuthorityCodeException, org.opengis.util.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 IdentifiedObject.
      Specified by:
      getDescriptionText in interface org.opengis.referencing.AuthorityFactory
      Overrides:
      getDescriptionText in class GeodeticAuthorityFactory
      Parameters:
      code - value allocated by authority.
      Returns:
      the object name, or null if the object corresponding to the specified code has no name.
      Throws:
      org.opengis.referencing.NoSuchAuthorityCodeException - if the specified code was not found.
      org.opengis.util.FactoryException - if the query failed for some other reason.

    • createObject

      public org.opengis.referencing.IdentifiedObject createObject(String code) throws org.opengis.referencing.NoSuchAuthorityCodeException, org.opengis.util.FactoryException
      Returns an arbitrary object from a code. The default implementation delegates to more specific methods, for example createCoordinateReferenceSystem(String), createDatum(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 kinds 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 createFoo(String) method when the desired type is known, both for performance reason and for avoiding ambiguity.

      Specified by:
      createObject in interface org.opengis.referencing.AuthorityFactory
      Specified by:
      createObject in class GeodeticAuthorityFactory
      Parameters:
      code - value allocated by EPSG.
      Returns:
      the object for the given code.
      Throws:
      org.opengis.referencing.NoSuchAuthorityCodeException - if the specified code was not found.
      org.opengis.util.FactoryException - if the object creation failed for some other reason.
      See Also:

    • createCoordinateReferenceSystem

      public org.opengis.referencing.crs.CoordinateReferenceSystem createCoordinateReferenceSystem(String code) throws org.opengis.referencing.NoSuchAuthorityCodeException, org.opengis.util.FactoryException
      Creates an arbitrary coordinate reference system from a code. The returned object will typically be an instance of GeographicCRS, ProjectedCRS, VerticalCRS or CompoundCRS.
      Example: some EPSG codes for coordinate reference systems are:
      EPSG codes examples
      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:
      createCoordinateReferenceSystem in interface org.opengis.referencing.crs.CRSAuthorityFactory
      Overrides:
      createCoordinateReferenceSystem in class GeodeticAuthorityFactory
      Parameters:
      code - value allocated by EPSG.
      Returns:
      the coordinate reference system for the given code.
      Throws:
      org.opengis.referencing.NoSuchAuthorityCodeException - if the specified code was not found.
      org.opengis.util.FactoryException - if the object creation failed for some other reason.
      See Also:

    • createDatum

      public org.opengis.referencing.datum.Datum createDatum(String code) throws org.opengis.referencing.NoSuchAuthorityCodeException, org.opengis.util.FactoryException
      Creates an arbitrary datum from a code. The returned object will typically be an instance of GeodeticDatum, VerticalDatum or TemporalDatum.
      Example: some EPSG codes for datums are:
      EPSG codes examples
      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:
      createDatum in interface org.opengis.referencing.datum.DatumAuthorityFactory
      Overrides:
      createDatum in class GeodeticAuthorityFactory
      Parameters:
      code - value allocated by EPSG.
      Returns:
      the datum for the given code.
      Throws:
      org.opengis.referencing.NoSuchAuthorityCodeException - if the specified code was not found.
      org.opengis.util.FactoryException - if the object creation failed for some other reason.
      See Also:

    • createEllipsoid

      public org.opengis.referencing.datum.Ellipsoid createEllipsoid(String code) throws org.opengis.referencing.NoSuchAuthorityCodeException, org.opengis.util.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:
      EPSG codes examples
      Code Description
      7030 WGS 84
      7034 Clarke 1880
      7048 GRS 1980 Authalic Sphere
      Specified by:
      createEllipsoid in interface org.opengis.referencing.datum.DatumAuthorityFactory
      Overrides:
      createEllipsoid in class GeodeticAuthorityFactory
      Parameters:
      code - value allocated by EPSG.
      Returns:
      the ellipsoid for the given code.
      Throws:
      org.opengis.referencing.NoSuchAuthorityCodeException - if the specified code was not found.
      org.opengis.util.FactoryException - if the object creation failed for some other reason.
      See Also:

    • createPrimeMeridian

      public org.opengis.referencing.datum.PrimeMeridian createPrimeMeridian(String code) throws org.opengis.referencing.NoSuchAuthorityCodeException, org.opengis.util.FactoryException
      Creates a prime meridian defining the origin from which longitude values are determined.
      Example: some EPSG codes for prime meridians are:
      EPSG codes examples
      Code Description
      8901 Greenwich
      8903 Paris
      8904 Bogota
      8905 Madrid
      8906 Rome
      Specified by:
      createPrimeMeridian in interface org.opengis.referencing.datum.DatumAuthorityFactory
      Overrides:
      createPrimeMeridian in class GeodeticAuthorityFactory
      Parameters:
      code - value allocated by EPSG.
      Returns:
      the prime meridian for the given code.
      Throws:
      org.opengis.referencing.NoSuchAuthorityCodeException - if the specified code was not found.
      org.opengis.util.FactoryException - if the object creation failed for some other reason.
      See Also:

    • createExtent

      public org.opengis.metadata.extent.Extent createExtent(String code) throws org.opengis.referencing.NoSuchAuthorityCodeException, org.opengis.util.FactoryException
      Creates information about spatial, vertical, and temporal extent (usually a domain of validity) from a code.
      Example: some EPSG codes for extents are:
      EPSG codes examples
      Code Description
      1262 World
      3391 World - between 80°S and 84°N
      Overrides:
      createExtent in class GeodeticAuthorityFactory
      Parameters:
      code - value allocated by EPSG.
      Returns:
      the extent for the given code.
      Throws:
      org.opengis.referencing.NoSuchAuthorityCodeException - if the specified code was not found.
      org.opengis.util.FactoryException - if the object creation failed for some other reason.
      See Also:

    • createCoordinateSystem

      public org.opengis.referencing.cs.CoordinateSystem createCoordinateSystem(String code) throws org.opengis.referencing.NoSuchAuthorityCodeException, org.opengis.util.FactoryException
      Creates an arbitrary coordinate system from a code. The returned object will typically be an instance of EllipsoidalCS, CartesianCS or VerticalCS.
      Example: some EPSG codes for coordinate systems are:
      EPSG codes examples
      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:
      createCoordinateSystem in interface org.opengis.referencing.cs.CSAuthorityFactory
      Overrides:
      createCoordinateSystem in class GeodeticAuthorityFactory
      Parameters:
      code - value allocated by EPSG.
      Returns:
      the coordinate system for the given code.
      Throws:
      org.opengis.referencing.NoSuchAuthorityCodeException - if the specified code was not found.
      org.opengis.util.FactoryException - if the object creation failed for some other reason.
      See Also:

    • createCoordinateSystemAxis

      public org.opengis.referencing.cs.CoordinateSystemAxis createCoordinateSystemAxis(String code) throws org.opengis.referencing.NoSuchAuthorityCodeException, org.opengis.util.FactoryException
      Creates a coordinate system axis with name, direction, unit and range of values.
      Example: some EPSG codes for axes are:
      EPSG codes examples
      Code Description Unit
      106 Latitude (φ) degree
      107 Longitude (λ) degree
      1 Easting (E) metre
      2 Northing (N) metre
      Specified by:
      createCoordinateSystemAxis in interface org.opengis.referencing.cs.CSAuthorityFactory
      Overrides:
      createCoordinateSystemAxis in class GeodeticAuthorityFactory
      Parameters:
      code - value allocated by EPSG.
      Returns:
      the axis for the given code.
      Throws:
      org.opengis.referencing.NoSuchAuthorityCodeException - if the specified code was not found.
      org.opengis.util.FactoryException - if the object creation failed for some other reason.
      See Also:

    • createUnit

      public javax.measure.Unit<?> createUnit(String code) throws org.opengis.referencing.NoSuchAuthorityCodeException, org.opengis.util.FactoryException
      Creates an unit of measurement from a code. Current implementation first checks if Units.valueOfEPSG(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:
      EPSG codes examples
      Code Description
      9002 decimal degree
      9001 metre
      9030 kilometre
      1040 second
      1029 year
      Specified by:
      createUnit in interface org.opengis.referencing.cs.CSAuthorityFactory
      Overrides:
      createUnit in class GeodeticAuthorityFactory
      Parameters:
      code - value allocated by EPSG.
      Returns:
      the unit of measurement for the given code.
      Throws:
      org.opengis.referencing.NoSuchAuthorityCodeException - if the specified code was not found.
      org.opengis.util.FactoryException - if the object creation failed for some other reason.
      See Also:

    • createParameterDescriptor

      public org.opengis.parameter.ParameterDescriptor<?> createParameterDescriptor(String code) throws org.opengis.referencing.NoSuchAuthorityCodeException, org.opengis.util.FactoryException
      Creates a definition of a single parameter used by an operation method.
      Example: some EPSG codes for parameters are:
      EPSG codes examples
      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:
      createParameterDescriptor in class GeodeticAuthorityFactory
      Parameters:
      code - value allocated by EPSG.
      Returns:
      the parameter descriptor for the given code.
      Throws:
      org.opengis.referencing.NoSuchAuthorityCodeException - if the specified code was not found.
      org.opengis.util.FactoryException - if the object creation failed for some other reason.
      See Also:

    • createOperationMethod

      public org.opengis.referencing.operation.OperationMethod createOperationMethod(String code) throws org.opengis.referencing.NoSuchAuthorityCodeException, org.opengis.util.FactoryException
      Creates description of the algorithm and parameters used to perform a coordinate operation. An OperationMethod 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:
      EPSG codes examples
      Code Description
      9804 Mercator (variant A)
      9802 Lambert Conic Conformal (2SP)
      9810 Polar Stereographic (variant A)
      9624 Affine parametric transformation
      Specified by:
      createOperationMethod in interface org.opengis.referencing.operation.CoordinateOperationAuthorityFactory
      Overrides:
      createOperationMethod in class GeodeticAuthorityFactory
      Parameters:
      code - value allocated by EPSG.
      Returns:
      the operation method for the given code.
      Throws:
      org.opengis.referencing.NoSuchAuthorityCodeException - if the specified code was not found.
      org.opengis.util.FactoryException - if the object creation failed for some other reason.
      See Also:

    • createCoordinateOperation

      public org.opengis.referencing.operation.CoordinateOperation createCoordinateOperation(String code) throws org.opengis.referencing.NoSuchAuthorityCodeException, org.opengis.util.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:
      EPSG codes examples
      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:
      createCoordinateOperation in interface org.opengis.referencing.operation.CoordinateOperationAuthorityFactory
      Overrides:
      createCoordinateOperation in class GeodeticAuthorityFactory
      Parameters:
      code - value allocated by EPSG.
      Returns:
      the operation for the given code.
      Throws:
      org.opengis.referencing.NoSuchAuthorityCodeException - if the specified code was not found.
      org.opengis.util.FactoryException - if the object creation failed for some other reason.
      See Also:

    • createFromCoordinateReferenceSystemCodes

      public Set<org.opengis.referencing.operation.CoordinateOperation> createFromCoordinateReferenceSystemCodes(String sourceCRS, String targetCRS) throws org.opengis.util.FactoryException
      Creates operations from source and target coordinate reference system codes. This method only extract the information explicitly declared in the EPSG database; it does not attempt to infer by itself operations that are not explicitly 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 createCoordinateOperation(String).

      Specified by:
      createFromCoordinateReferenceSystemCodes in interface org.opengis.referencing.operation.CoordinateOperationAuthorityFactory
      Overrides:
      createFromCoordinateReferenceSystemCodes in class GeodeticAuthorityFactory
      Parameters:
      sourceCRS - coded value of source coordinate reference system.
      targetCRS - coded value of target coordinate reference system.
      Returns:
      the operations from sourceCRS to targetCRS.
      Throws:
      org.opengis.referencing.NoSuchAuthorityCodeException - if a specified code was not found.
      org.opengis.util.FactoryException - if the object creation failed for some other reason.

    • newIdentifiedObjectFinder

      public IdentifiedObjectFinder newIdentifiedObjectFinder() throws org.opengis.util.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:
      newIdentifiedObjectFinder in class GeodeticAuthorityFactory
      Returns:
      a finder to use for looking up unidentified objects.
      Throws:
      org.opengis.util.FactoryException - if the finder cannot be created.
      See Also:

    • close

      public void close() throws org.opengis.util.FactoryException
      Closes the JDBC connection used by this factory. If this EPSGDataAccess is used by an EPSGFactory, then this method will be automatically invoked after some timeout.
      Specified by:
      close in interface AutoCloseable
      Throws:
      org.opengis.util.FactoryException - if an error occurred while closing the connection.
      See Also: