# 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 `DataSource` providing connections to an EPSG database.

## Connection to the database

Apache SIS uses the Apache Derby database by default. However, connection to the EPSG dataset should work with any SQL compliant databases (tested on PostgreSQL and HSQL). The database connection is obtained by the first of the following data sources which is found:

1. If a JNDI context exists, the `DataSource` registered under the `"java:comp/env/jdbc/SpatialMetadata"` name.
2. If the `SIS_DATA` environment variable is defined, a JDBC connection for the `"jdbc:derby:$SIS_DATA/Databases/SpatialMetadata"` URL.
3. If the `"derby​.system​.home"` property is defined, a JDBC connection for the `"jdbc:derby:SpatialMetadata"` 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:

- `createProjectedCRS("27572")`
- `createProjectedCRS("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 `EPSGDataAccess​.getAuthorityCodes(…)` 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 `EPSGDataAccess​.createFoo(…)`, a warning will be logged with a message proposing a replacement.

Since:
  0.7
See Also:
  - `org​.apache​.sis​.metadata​.sql`

- Related Packages
  Module
  Package
  Description
  org.apache.sis.referencing
  org.apache.sis.referencing.factory
  Creates Coordinate Reference System (CRS) objects from given properties or authority codes.
  org.apache.sis.referencing.epsg
  org.apache.sis.referencing.factory.sql.epsg
  SQL scripts for EPSG geodetic data set installation.
- 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 the SQL scripts needed for creating a local copy of a geodetic dataset.
  SQLTranslator
  Translator of SQL statements for variations in schema, table and column names.