Module org.apache.sis.referencing

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

package org.apache.sis.referencing.factory.sql
Factories for geodetic objects defined in a SQL database, typically the EPSG dataset. This package provides support for all codes prefixed by "EPSG:" in the Apache SIS's list of authority codes. The main class in this package is EPSGFactory, which requires a Data­Source providing connections to an EPSG database.

Connection to the database

By default Apache SIS uses Apache Derby, but the database can also be PostgreSQL or MS-Access. The database connection is obtained by the first of the following data sources which is found:
  1. If a JNDI context exists, the Data­Source registered under the "java:comp/env/jdbc/Spatial­Metadata" name.
  2. If the SIS_DATA environment variable is defined, a JDBC connection for the "jdbc:derby:$SIS_DATA/Databases/Spatial­Metadata" URL.
  3. If the "derby​.system​.home" property is defined, a JDBC connection for the "jdbc:derby:Spatial­Metadata" URL.
  4. If the org​.apache​.sis​.referencing​.database module is present on the module path, a read-only connection to the database in the JAR file.
In choice 1, the JDBC driver must be provided by the application container (e.g. Apache Tomcat). With other choices, an Apache Derby driver should be available on the module path.

The EPSG dataset

A widely-used factory is the EPSG geodetic dataset. EPSG codes are numerical identifiers. For example, "EPSG:4326" is the EPSG identifier for the "WGS 84" geographic CRS. As an extension, the Apache SIS implementation accepts names as well as numeric identifiers. For example, the two following method calls fetch the same object:
  • create­Projected­CRS("27572")
  • create­Projected­CRS("NTF (Paris) / Lambert zone II")
Note that names may be ambiguous since the same name may be used for more than one object. This is the case of "WGS 84" for example. If such an ambiguity is found, an exception will be thrown. For more determinism, the numerical codes are preferred.

How deprecated entries are handled

When an error is discovered in a Coordinate Reference System (CRS) definition, the EPSG group does not apply the correction directly on the erroneous object (unless the correction is very minor). Instead, the erroneous object is deprecated and a new one is created. Apache SIS handles deprecated objects as below:
  • Deprecated objects are not listed in the collection returned by the EPSGData­Access​.get­Authority­Codes(…) method.
  • All method expecting an EPSG code in argument accept also the codes of deprecated objects.
  • If a deprecated object is created by a call to EPSGData­Access​.create­Foo(…), a warning will be logged with a message proposing a replacement.
Since:
0.7
See Also:
  • Classes
    Class
    Description
    EPSGDataAccess
    Data Access Object (DAO) creating geodetic objects from a JDBC connection to an EPSG database.
    EPSGFactory
    A geodetic object factory backed by the EPSG database.
    InstallationScriptProvider
    Provides SQL scripts needed for creating a local copy of a dataset.
    SQLTranslator
    Converts the SQL statements from MS-Access dialect to standard SQL.