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
See Also:

  • Field Details

    • VERTICAL_DATUM_TYPE

      static final org.opengis.referencing.datum.VerticalDatumType VERTICAL_DATUM_TYPE
      The vertical datum type, which is fixed to a hard-coded value for all vertical datum for now. Note that vertical datum type is no longer part of ISO 19111:2007.

    • EPSG_CODE_PARAMETERS

      private static final int[] EPSG_CODE_PARAMETERS
      EPSG codes of parameters containing the EPSG code of another object. Those parameters are integers (stored as double in the database) without unit (associated to Units.UNITY in the database).

    • DEPRECATED_CS

      @Workaround(library="EPSG:6401-6420", version="8.9") private static final Map<Integer,Integer> DEPRECATED_CS
      The deprecated ellipsoidal coordinate systems and their replacements. Those coordinate systems are deprecated because they use a unit of measurement which is no longer supported by OGC (for example degree-minute-second). Those replacements can be used only if the ellipsoidal CS is used for the base geographic CRS of a derived or projected CRS, because the units of measurement of the base CRS do not impact the units of measurements of the derived CRS.

      We perform those replacements for avoiding a "Unit conversion from “DMS” to “°” is non-linear" exception at projected CRS creation time.

      See Also:

    • namespace

      private final org.opengis.util.NameSpace namespace
      The namespace of EPSG names and codes. This namespace is needed by all createFoo(String) methods. The EPSGDataAccess constructor relies on the EPSGFactory.nameFactory caching mechanism for giving us the same NameSpace instance than the one used by previous EPSGDataAccess instances, if any.

    • lastTableForName

      private String lastTableForName
      The last table in which object name were looked for. This is for internal use by toPrimaryKeys(java.lang.String, java.lang.String, java.lang.String, java.lang.String...) only.

    • calendar

      private Calendar calendar
      The calendar instance for creating Date objects from a year (the "epoch" in datum definition). We use the UTC timezone, which may not be quite accurate. But there is no obvious timezone for "epoch", and the "epoch" is an approximation anyway.
      See Also:

    • dateFormat

      private DateFormat dateFormat
      The object to use for parsing dates, created when first needed. This is used for parsing the origin of temporal datum. This is an Apache SIS specific extension.

    • statements

      private final Map<String,PreparedStatement> statements
      A pool of prepared statements. Keys are String objects related to their originating method (for example "Ellipsoid" for createEllipsoid(String)).

    • authorityCodes

      private final Map<Class<?>,CloseableReference> authorityCodes
      The set of authority codes for different types. This map is used by the getAuthorityCodes(Class) method as a cache for returning the set created in a previous call. We do not want this map to exist for a long time anyway.

      Note that this EPSGDataAccess instance cannot be closed as long as this map is not empty, since AuthorityCodes caches some SQL statements and consequently require the connection to be open. This is why we use weak references rather than hard ones, in order to know when no AuthorityCodes are still in use.

      The CloseableReference.dispose() method takes care of closing the statements used by the map. The AuthorityCodes reference in this map is then cleared by the garbage collector. The canClose() method checks if there is any remaining live reference in this map, and returns false if some are found (thus blocking the call to close() by the ConcurrentAuthorityFactory timer).

    • axisNames

      private final Map<Integer,AxisName> axisNames
      Cache for axis names. This service is not provided by ConcurrentAuthorityFactory since AxisName objects are particular to the EPSG database.
      See Also:

    • csDimensions

      private final Map<Integer,Integer> csDimensions
      Cache for the number of dimensions of coordinate systems. This service is not provided by ConcurrentAuthorityFactory since the number of dimension is used internally in this class.
      See Also:

    • isProjection

      private final Map<Integer,Boolean> isProjection
      Cache for whether conversions are projections. This service is not provided by ConcurrentAuthorityFactory since the check for conversion type is used internally in this class.
      See Also:

    • namingSystems

      private final Map<String,org.opengis.util.NameSpace> namingSystems
      Cache of naming systems other than EPSG. There is usually few of them (at most 15). This is used for aliases.
      See Also:

    • properties

      private final Map<String,Object> properties
      The properties to be given the objects to construct. Reused every time createProperties(…) is invoked.

    • safetyGuard

      private final Map<Integer,Class<?>> safetyGuard
      A safety guard for preventing never-ending loops in recursive calls to some createFoo(String) methods. Recursivity may happen while creating Bursa-Wolf parameters, projected CRS if the database has erroneous data, compound CRS if there is cycles, or coordinate operations.
      Example: createDatum(String) invokes createBursaWolfParameters(PrimeMeridian, Integer), which creates a target datum. The target datum could have its own Bursa-Wolf parameters, with one of them pointing again to the source datum.
      Keys are EPSG codes and values are the type of object being constructed (but those values are not yet used).

    • quiet

      transient boolean quiet
      true for disabling the logging of warnings when this factory creates deprecated objects. This flag should be always false, except during EPSGCodeFinder.find(IdentifiedObject) execution since that method may temporarily creates deprecated objects which are later discarded. May also be false when creating base CRS of deprecated projected or derived CRS.

    • replaceDeprecatedCS

      private transient boolean replaceDeprecatedCS
      true if createCoordinateReferenceSystem(String) is allowed to replace deprecated coordinate system at CRS creation time. This flag should be set to true only when creating the base CRS of a projected or derived CRS.
      See Also:

    • 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

    • deprecatedCS

      static Map<Integer,Integer> deprecatedCS()

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

    • getCalendar

      private Calendar getCalendar()
      Returns the calendar to use for reading dates in the database.

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

    • getCodeMap

      private Map<String,String> getCodeMap(Class<?> type) throws SQLException
      Returns a map of EPSG authority codes as keys and object names as values. The cautions documented in getAuthorityCodes(Class) apply also to this map.
      Throws:
      SQLException
      See Also:

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

    • isPrimaryKey

      private boolean isPrimaryKey(String code) throws org.opengis.util.FactoryException
      Returns true if the specified code may be a primary key in some table. This method does not need to check any entry in the database. It should just check from the syntax if the code looks like a valid EPSG identifier.

      When this method returns false, createFoo(String) methods may look for the code in the name column instead of the primary key column. This allows to accept the "WGS 84 / World Mercator" string (for example) in addition to the "3395" primary key. Both string values should fetch the same object.

      If this method returns true, then this factory does not search for matching names. In such case, an appropriate exception will be thrown in createFoo(String) methods if the code is not found in the primary key column.

      Default implementation

      The default implementation returns true if all characters are decimal digits 0 to 9.
      Parameters:
      code - the code the inspect.
      Returns:
      true if the code is probably a primary key.
      Throws:
      org.opengis.util.FactoryException - if an unexpected error occurred while inspecting the code.

    • toPrimaryKeys

      private int[] toPrimaryKeys(String table, String codeColumn, String nameColumn, String... codes) throws SQLException, org.opengis.util.FactoryException
      Converts EPSG codes or EPSG names to the numerical identifiers (the primary keys).
      Note: this method could be seen as the converse of above getDescriptionText(String) method.
      Parameters:
      table - the table where the code should appears, or null if codeColumn is null.
      codeColumn - the column name for the codes, or null if none.
      nameColumn - the column name for the names, or null if none.
      codes - the codes or names to convert to primary keys, as an array of length 1 or 2.
      Returns:
      the numerical identifiers (i.e. the table primary key values).
      Throws:
      SQLException - if an error occurred while querying the database.
      org.opengis.util.FactoryException

    • executeQuery

      private ResultSet executeQuery(String table, String codeColumn, String nameColumn, String sql, String... codes) throws SQLException, org.opengis.util.FactoryException
      Creates a statement and executes for the given codes. The first code value is assigned to parameter #1, the second code value (if any) is assigned to parameter #2, etc. If a given code is not a primary key, then this method assumes that the code is the object name and will search for its primary key value.
      Parameters:
      table - the table where the code should appears.
      codeColumn - the column name for the codes, or null if none.
      nameColumn - the column name for the names, or null if none.
      sql - the SQL statement to use for creating the PreparedStatement object. Will be used only if no prepared statement was already created for the given code.
      codes - the codes of the object to create, as an array of length 1 or 2.
      Returns:
      the result of the query.
      Throws:
      SQLException - if an error occurred while querying the database.
      org.opengis.util.FactoryException

    • executeQuery

      private ResultSet executeQuery(String table, String sql, int... codes) throws SQLException
      Creates a statement and executes for the given codes. The first code value is assigned to parameter #1, the second code value (if any) is assigned to parameter #2, etc.
      Parameters:
      table - a key uniquely identifying the caller (e.g. "Ellipsoid" for createEllipsoid(String)).
      sql - the SQL statement to use for creating the PreparedStatement object. Will be used only if no prepared statement was already created for the specified key.
      codes - the codes of the object to create, as an array of length 1 or 2.
      Returns:
      the result of the query.
      Throws:
      SQLException - if an error occurred while querying the database.

    • executeMetadataQuery

      private ResultSet executeMetadataQuery(String key, String sql, String table, int code) throws SQLException
      Executes a query of the form "SELECT … FROM Alias WHERE OBJECT_TABLE_NAME=? AND OBJECT_CODE=?". The first argument shall be the name of a database table.
      Parameters:
      key - a key uniquely identifying the caller.
      sql - the SQL statement to use for creating the PreparedStatement object.
      table - the table to set in the first parameter.
      code - the object code to set in the second parameter.
      Returns:
      the result of the query.
      Throws:
      SQLException - if an error occurred while querying the database.

    • prepareStatement

      private PreparedStatement prepareStatement(String table, String sql) throws SQLException
      Returns the cached statement or create a new one for the given table. The table argument shall be a key uniquely identifying the caller. The sql argument is used for preparing a new statement if no cached instance exists.
      Throws:
      SQLException

    • getOptionalString

      private static String getOptionalString(ResultSet result, int columnIndex) throws SQLException
      Gets the value from the specified ResultSet, or null if none.
      Parameters:
      result - the result set to fetch value from.
      columnIndex - the column index (1-based).
      Returns:
      the string at the specified column, or null.
      Throws:
      SQLException - if an error occurred while querying the database.

    • getOptionalDouble

      private static double getOptionalDouble(ResultSet result, int columnIndex) throws SQLException
      Gets the value from the specified ResultSet, or NaN if none.
      Parameters:
      result - the result set to fetch value from.
      columnIndex - the column index (1-based).
      Returns:
      the number at the specified column, or NaN.
      Throws:
      SQLException - if an error occurred while querying the database.

    • getOptionalInteger

      private static Integer getOptionalInteger(ResultSet result, int columnIndex) throws SQLException
      Gets the value from the specified ResultSet, or null if none.
      Parameters:
      result - the result set to fetch value from.
      columnIndex - the column index (1-based).
      Returns:
      the integer at the specified column, or null.
      Throws:
      SQLException - if an error occurred while querying the database.

    • getOptionalBoolean

      private boolean getOptionalBoolean(ResultSet result, int columnIndex) throws SQLException
      Gets the value from the specified ResultSet, or false if none. The EPSG database stores boolean values as integers instead of using the SQL type.
      Parameters:
      result - the result set to fetch value from.
      columnIndex - the column index (1-based).
      Returns:
      the boolean at the specified column, or null.
      Throws:
      SQLException - if an error occurred while querying the database.

    • nullValue

      private String nullValue(ResultSet result, int columnIndex, Comparable<?> code) throws SQLException
      Formats an error message for an unexpected null value.
      Throws:
      SQLException

    • getString

      private String getString(String code, ResultSet result, int columnIndex, int columnFault) throws SQLException, FactoryDataException
      Same as getString(Comparable, ResultSet, int), but reports the fault on an alternative column if the value is null.
      Throws:
      SQLException
      FactoryDataException

    • getString

      private String getString(Comparable<?> code, ResultSet result, int columnIndex) throws SQLException, FactoryDataException
      Gets the string from the specified ResultSet. The string is required to be non-null. A null string will throw an exception.
      Parameters:
      code - the identifier of the record where the string was found.
      result - the result set to fetch value from.
      columnIndex - the column index (1-based).
      Returns:
      the string at the specified column.
      Throws:
      SQLException - if an error occurred while querying the database.
      FactoryDataException - if a null value was found.

    • getDouble

      private double getDouble(Comparable<?> code, ResultSet result, int columnIndex) throws SQLException, FactoryDataException
      Gets the value from the specified ResultSet. The value is required to be non-null. A null value (i.e. blank) will throw an exception.
      Parameters:
      code - the identifier of the record where the double was found.
      result - the result set to fetch value from.
      columnIndex - the column index (1-based).
      Returns:
      the double at the specified column.
      Throws:
      SQLException - if an error occurred while querying the database.
      FactoryDataException - if a null value was found.

    • getInteger

      private Integer getInteger(Comparable<?> code, ResultSet result, int columnIndex) throws SQLException, FactoryDataException
      Gets the value from the specified ResultSet. The value is required to be non-null. A null value (i.e. blank) will throw an exception.

      We return the value as the Integer wrapper instead of the int primitive type because the caller will often need that value as an object (for use as key in HashMap, etc.).

      Parameters:
      code - the identifier of the record where the integer was found.
      result - the result set to fetch value from.
      columnIndex - the column index (1-based).
      Returns:
      the integer at the specified column.
      Throws:
      SQLException - if an error occurred while querying the database.
      FactoryDataException - if a null value was found.

    • ensureSingleton

      private <T> T ensureSingleton(T newValue, T oldValue, Comparable<?> code) throws FactoryDataException
      Makes sure that an object constructed from the database is not incoherent. If the code supplied to a createFoo(String) method exists in the database, then we should find only one record. However, we will do a paranoiac check and verify if there is more records, using a while (results.next()) loop instead of if (results.next()). This method is invoked in the loop for making sure that, if there is more than one record (which should never happen), at least they have identical content.
      Parameters:
      newValue - the newly constructed object.
      oldValue - the object previously constructed, or null if none.
      code - the EPSG code (for formatting error message).
      Throws:
      FactoryDataException - if a duplication has been detected.

    • ensureNoCycle

      private void ensureNoCycle(Class<?> type, Integer code) throws org.opengis.util.FactoryException
      Ensures that this factory is not already building an object of the given code. This method shall be followed by a try ... finally block like below:
      Throws:
      org.opengis.util.FactoryException

    • endOfRecursivity

      private void endOfRecursivity(Class<?> type, Integer code) throws org.opengis.util.FactoryException
      Invoked after the block protected against infinite recursivity.
      Throws:
      org.opengis.util.FactoryException

    • getSupersession

      private String getSupersession(String table, Integer code, Locale locale) throws SQLException
      Logs a warning saying that the given code is deprecated and returns the code of the proposed replacement.
      Parameters:
      table - the table of the deprecated code.
      code - the deprecated code.
      Returns:
      the proposed replacement (may be the "(none)" text).
      Throws:
      SQLException

    • createProperties

      private Map<String,Object> createProperties(String table, String name, Integer code, CharSequence remarks, boolean deprecated) throws SQLException, FactoryDataException
      Returns the name and aliases for the IdentifiedObject to construct.
      Parameters:
      table - the table on which a query has been executed.
      name - the name for the IdentifiedObject to construct.
      code - the EPSG code of the object to construct.
      remarks - remarks as a String or InternationalString, or null if none.
      deprecated - true if the object to create is deprecated.
      Returns:
      the name together with a set of properties.
      Throws:
      SQLException
      FactoryDataException

    • createProperties

      private Map<String,Object> createProperties(String table, String name, Integer code, String domainCode, String scope, String remarks, boolean deprecated) throws SQLException, org.opengis.util.FactoryException
      Returns the name, aliases and domain of validity for the IdentifiedObject to construct.
      Parameters:
      table - the table on which a query has been executed.
      name - the name for the IdentifiedObject to construct.
      code - the EPSG code of the object to construct.
      domainCode - the code for the domain of validity, or null if none.
      scope - the scope, or null if none.
      remarks - remarks, or null if none.
      deprecated - true if the object to create is deprecated.
      Returns:
      the name together with a set of properties.
      Throws:
      SQLException
      org.opengis.util.FactoryException

    • toLikePattern

      private static String toLikePattern(String name)
      Returns a string like the given string but with accented letters replaced by ASCII letters and all characters that are not letter or digit replaced by the wildcard % character.

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

    • createBursaWolfParameters

      private BursaWolfParameters[] createBursaWolfParameters(org.opengis.referencing.datum.PrimeMeridian meridian, Integer code) throws SQLException, org.opengis.util.FactoryException
      Returns Bursa-Wolf parameters for a geodetic datum. If the specified datum has no conversion information, then this method returns null.

      This method is for compatibility with Well Known Text (WKT) version 1 formatting. That legacy format had a TOWGS84 element which needs the information provided by this method. Note that TOWGS84 is a deprecated element as of WKT 2 (ISO 19162).

      Parameters:
      meridian - the source datum prime meridian, used for discarding any target datum using a different meridian.
      code - the EPSG code of the source GeodeticDatum.
      Returns:
      an array of Bursa-Wolf parameters, or null.
      Throws:
      SQLException
      org.opengis.util.FactoryException

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

    • getDimensionForCS

      private Integer getDimensionForCS(Integer cs) throws SQLException
      Returns the number of dimension for the specified Coordinate System, or null if not found.
      Parameters:
      cs - the EPSG code for the coordinate system.
      Returns:
      the number of dimensions, or null if not found.
      Throws:
      SQLException
      See Also:

    • createCoordinateSystemAxes

      private org.opengis.referencing.cs.CoordinateSystemAxis[] createCoordinateSystemAxes(Integer cs, int dimension) throws SQLException, org.opengis.util.FactoryException
      Returns the coordinate system axis from an EPSG code for a CoordinateSystem.

      WARNING: The EPSG database uses "ORDER" as a column name. This is tolerated by Access, but MySQL does not accept that name.

      Parameters:
      cs - the EPSG code for the coordinate system.
      dimension - of the coordinate system, which is also the size of the returned array.
      Returns:
      an array of coordinate system axis.
      Throws:
      SQLException - if an error occurred during database access.
      org.opengis.util.FactoryException - if the code has not been found.

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

    • getAxisName

      private AxisName getAxisName(Integer code) throws org.opengis.util.FactoryException, SQLException
      Returns the name and description for the specified CoordinateSystemAxis code. Many axes share the same name and description, so it is worth to cache them.
      Throws:
      org.opengis.util.FactoryException
      SQLException

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

    • createParameterDescriptors

      private org.opengis.parameter.ParameterDescriptor<?>[] createParameterDescriptors(Integer method) throws org.opengis.util.FactoryException, SQLException
      Returns all parameter descriptors for the specified method.
      Parameters:
      method - the operation method code.
      Returns:
      the parameter descriptors.
      Throws:
      SQLException - if a SQL statement failed.
      org.opengis.util.FactoryException

    • fillParameterValues

      private void fillParameterValues(Integer method, Integer operation, org.opengis.parameter.ParameterValueGroup parameters) throws org.opengis.util.FactoryException, SQLException
      Sets the values of all parameters in the given group.
      Parameters:
      method - the EPSG code for the operation method.
      operation - the EPSG code for the operation (conversion or transformation).
      parameters - the parameter values to fill.
      Throws:
      SQLException - if a SQL statement failed.
      org.opengis.util.FactoryException

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

    • isProjection

      final boolean isProjection(Integer code) throws SQLException
      Returns true if the CoordinateOperation for the specified code is a Projection. The caller must have verified that the designed operation is a Conversion before to invoke this method.
      Throws:
      SQLException - if an error occurred while querying the database.

    • getDimensionsForMethod

      private Integer[] getDimensionsForMethod(Integer method) throws SQLException
      Returns the source and target dimensions for the specified method, provided that they are the same for all operations using that method. The returned array has a length of 2 and is never null, but some elements in that array may be null.
      Parameters:
      method - the EPSG code of the operation method for which to get the dimensions.
      Returns:
      the dimensions in an array of length 2.
      Throws:
      SQLException
      See Also:

    • sort

      final boolean sort(String table, Object[] codes) throws SQLException, org.opengis.util.FactoryException
      Sorts an array of codes in preference order. This method orders pairwise the codes according the information provided in the supersession table. If the same object is superseded by more than one object, then the most recent one is inserted first. Except for the codes moved as a result of pairwise ordering, this method tries to preserve the old ordering of the supplied codes (since deprecated operations should already be last). The ordering is performed in place.
      Parameters:
      table - the table of the objects for which to check for supersession.
      codes - the codes, usually as an array of String. If the array do not contains string objects, then the Object.toString() method must return the code for each element.
      Returns:
      true if the array changed as a result of this method call.
      Throws:
      SQLException
      org.opengis.util.FactoryException

    • noSuchAuthorityCode

      private org.opengis.referencing.NoSuchAuthorityCodeException noSuchAuthorityCode(Class<?> type, String code)
      Creates an exception for an unknown authority code. This convenience method is provided for implementation of createFoo(String) methods.
      Parameters:
      type - the GeoAPI interface that was to be created (e.g. CoordinateReferenceSystem.class).
      code - the unknown authority code.
      Returns:
      an exception initialized with an error message built from the specified information.

    • databaseFailure

      final org.opengis.util.FactoryException databaseFailure(Class<?> type, Comparable<?> code, SQLException cause)
      Constructs an exception for a database failure.

    • error

      private Errors error()
      Minor shortcut for fetching the error resources.

    • resources

      private Resources resources()
      Minor shortcut for fetching the resources specific to the sis-referencing module.

    • unexpectedException

      private static void unexpectedException(String method, Exception exception)
      Logs a warning about an unexpected but non-fatal exception.
      Parameters:
      method - the source method.
      exception - the exception to log.

    • canClose

      final boolean canClose()
      Returns true if it is safe to close this factory. This method is invoked indirectly by EPSGFactory after some timeout in order to release resources. This method will block the disposal if some AuthorityCodes are still in use.
      Returns:
      true if this Data Access Object can be closed.
      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: