content/epsg.mdtext

Title:  How to use EPSG geodetic dataset
Notice: Licensed to the Apache Software Foundation (ASF) under one
        or more contributor license agreements.  See the NOTICE file
        distributed with this work for additional information
        regarding copyright ownership.  The ASF licenses this file
        to you under the Apache License, Version 2.0 (the
        "License"); you may not use this file except in compliance
        with the License.  You may obtain a copy of the License at
        .
          http://www.apache.org/licenses/LICENSE-2.0
        .
        Unless required by applicable law or agreed to in writing,
        software distributed under the License is distributed on an
        "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
        KIND, either express or implied.  See the License for the
        specific language governing permissions and limitations
        under the License.



The [EPSG geodetic dataset][EPSG] is a de-facto standard providing
[thousands of Coordinate Reference System (CRS) definitions](tables/CoordinateReferenceSystems.html)
together with information about how to perform coordinate operations, their accuracies and their domains of validity.
The EPSG dataset is owned and maintained by the [International Association of Oil & Gas producers][IOGP].
Usage of EPSG dataset with Apache SIS is optional but strongly recommended:
without that geodetic dataset, only a small subset of CRS definitions will be available
(basically the constants enumerated in the [`CommonCRS`](apidocs/org/apache/sis/referencing/CommonCRS.html) Java class)
unless full definitions are provided in _Well Known Text_ (WKT) or _Geographic Markup Language_ (GML) formats.
Furthermore, coordinate operations between any given pair of CRS may be less accurate
and their domains of validity may be unspecified if Apache SIS can not query EPSG.

The EPSG geodetic dataset is not distributed with Apache SIS because the [EPSG terms of use][EPSG-ToU]
are incompatible with Apache license. The following items are quoted from those terms of use:

  * The [EPSG][EPSG] Facilities are published by [IOGP][IOGP] at no charge. Distribution for profit is forbidden.
  * The data may be included in any commercial package provided that any commerciality is based on value added
    by the provider and not on a value ascribed to the EPSG Dataset which is made available at no charge.
  * Ownership of the EPSG Dataset by IOGP must be acknowledged in any publication or transmission
    (by whatever means) thereof (including permitted modifications).
  * Modification of parameter values is permitted as described in the table 1 to allow change to the content
    of the information provided that numeric equivalence is achieved.
  * No data that has been modified other than as permitted in these Terms of Use shall be attributed to the EPSG Dataset.

In order to use the EPSG geodetic dataset with Apache SIS, apply *one* of the following choices:

[TOC]



Install a local copy with command-line tool    {#command-line}
==============================================================

If the [command-line tool](command-line.html) has been downloaded and installed, just query any CRS.
For example:

    :::bash
    sis crs EPSG:6676

The first time that the command-line tool needs to query EPSG, it will prompt the user for authorization
to download EPSG geodetic dataset from Maven Central. If the user accepts EPSG terms of use, then a local
copy of the EPSG geodetic dataset will be created and stored in the `apache-sis-1.0/data` sub-directory.

If the command-line tool does not offer to download the EPSG geodetic dataset,
try adding a `derby-<version>.jar` file (download lib-distribution from [Derby project][Derby]) in the `apache-sis-1.0/lib` sub-directory.
This is normally not needed with Oracle JDK8 because Apache SIS tries to use the JavaDB embedded
in those distributions, but may be necessary with other distributions or in security-constrained environments:

    :::bash
    cd apache-sis-1.0/lib
    wget http://repo1.maven.org/maven2/org/apache/derby/derby/10.14.2.0/derby-10.14.2.0.jar



Use the local copy in other applications    {#use-local}
--------------------------------------------------------

For using the installed EPSG geodetic dataset in your own application, apply *one* of the following choices:

  * Set the `SIS_DATA` environment variable to the path of `apache-sis-1.0/data` directory _(preferred choice)_.
  * Set the `derby.system.home` Java property to the path of `apache-sis-1.0/data/Databases` directory.

Alternatively `SIS_DATA` or `derby.system.home` can be set to the path of any other directory which contain the same files.
Examples are shown below for Unix systems, assuming that the current directory is the directory where `apache-sis-1.0-bin.zip`
has been unzipped:

    :::bash
    export SIS_DATA=apache-sis-1.0/data
    java -classpath apache-sis-1.0/lib/sis.jar:myApp.jar myMainClass

If the `SIS_DATA` environment variable can not be set, Java property can be used as a fallback:

    java -Dderby.system.home=apache-sis-1.0/data/Databases -classpath apache-sis-1.0/lib/sis.jar:myApp.jar myMainClass



Add a Maven dependency    {#maven}
==============================================================

Maven projects can get the EPSG geodetic dataset automatically, _without any prompt for terms of use agreement_,
if they add a `sis-epsg` or `sis-embedded-data` dependency (from `org.apache.sis.non-free` group) in their project.
Those two approaches have advantages and inconvenient described in following sub-sections.
In both cases, we assume that developers who add those dependencies explicitely in their project agree with
[EPSG terms of use][EPSG-ToU].



As database installer     {#maven-epsg}
---------------------------------------

With `sis-epsg` artifact on the classpath, Apache SIS will create a local copy of EPSG database when first needed.
The target database must be specified by users with *one* of the following choices:

  * Set the `SIS_DATA` environment variable to the path of an initially empty directory _(preferred choice)_.
    The specified directory must exist, but sub-directories will be created as needed.
  * Set the `derby.system.home` Java property to the path of an initially empty directory,
    or a directory that contain other Derby databases. The specified directory must exist.
  * Register a `DataSource` under the `java:comp/env/jdbc/SpatialMetadata` name in a JNDI directory
    (see [next section](#jndi)). The database must exist but can be initially empty.
  * Set a `DataSource` [from Java code](./apidocs/org/apache/sis/setup/Configuration.html).

The Maven dependency is as below (the Derby dependency can be replaced by another database driver
if that database is specified by JNDI):

    :::xml
    <dependencies>
      <dependency>
        <groupId>org.apache.sis.non-free</groupId>
        <artifactId>sis-epsg</artifactId>
        <version>1.0</version>
        <scope>runtime</scope>
      </dependency>

      <!-- Following dependency can be omitted on Oracle JDK8
           since that Java distributions contain Derby (a.k.a JavaDB). -->
      <dependency>
        <groupId>org.apache.derby</groupId>
        <artifactId>derby</artifactId>
        <version>10.14.2.0</version>
        <scope>runtime</scope>
      </dependency>
    </dependencies>

See the [download](downloads.html#epsg) page for more information about Maven dependency declaration.



As embedded database     {#maven-embedded}
------------------------------------------

With `sis-embedded-data` artifact on the classpath, there is no need to setup environment variable, Java property or JNDI.
However this simplicity come with the following inconvenient:

  * a larger download,
  * no option for choosing which data to use (and consequently which license to accept),
  * no possibility to choose the database engine (i.e. the database software is fixed to Derby),
  * no possibility to add user data (i.e. the database is read-only),
  * slower execution of `CRS.forCode(…)` and `CRS.findCoordinateOperation(…)` methods, unless the JAR file is uncompressed.

This dependency can be declared as below
(see the [download](downloads.html#epsg) page for more information about Maven dependency declaration).
Note that `sis-epsg` and `sis-embedded-data` should not be specified in the same project; only one is needed:

    :::xml
    <dependencies>
      <dependency>
        <groupId>org.apache.sis.non-free</groupId>
        <artifactId>sis-embedded-data</artifactId>
        <version>1.0</version>
        <scope>runtime</scope>
      </dependency>
    </dependencies>

The performance issue can be avoided if the JAR file is uncompressed.
But uncompressed `sis-embedded-data.jar` file is more than 5 times larger than the compressed file.
Given that `CRS​.forCode(…)` and `CRS​.findCoordinateOperation(…)` should not be invoked too often,
and that performance degradation does not apply to the `CoordinateOperation` instances created by those method calls,
the JAR file is distributed on the Maven repository in its compressed form.
If desired, better performance can be achieved by using one of the other configurations described in this page,
or by uncompressing the `sis-embedded-data.jar` file locally.



Use Java Naming and Directory Interface    {#jndi}
==================================================

While Apache SIS uses Apache Derby by default, it is also possible to use another database software like HSQL or PostgreSQL.
For using an arbitrary database, register a `javax.sql.DataSource` instance through the Java Naming and Directory Interface (JNDI).
That registration can be done programmatically (by Java code) or by configuring XML files in some environments.
The database must exist but can be empty, in which case it will be populated with an EPSG schema when first needed
if the <code style="white-space:normal">org.apache.sis.non-free:​sis-epsg:​1.0</code> dependency is on the classpath
(see [above section](#maven-epsg)).



Registration by Java code    {#jndi-java}
-----------------------------------------

Registration can be done by the following Java code, provided that a JNDI implementation is available on the classpath:

    :::java
    // Example using PostgreSQL data source (org.postgresql.ds.PGSimpleDataSource)
    PGSimpleDataSource ds = new PGSimpleDataSource();
    ds.setServerName("localhost");
    ds.setDatabaseName("SpatialMetadata");

    // Registration assuming that a JNDI implementation is available
    Context env = (Context) InitialContext.doLookup("java:comp/env");
    env.bind("jdbc/SpatialMetadata", ds);

If there is no JNDI environment, the `org.apache.sis.setup.Configuration` class can be used as a fallback:

    :::java
    // Fallback if no JNDI environment is available.
    Configuration.current().setDatabase(() -> ds);



Registration in web application containers    {#jndi-webapp}
------------------------------------------------------------

JNDI implementations are provided by web application containers like Apache Tomcat.
When Apache SIS is used in a JavaEE container, the data source can be configured as below:

1. Make the JDBC driver available to the web container and its applications.
   On Tomcat, this is accomplished by installing the driver's JAR files into the `$CATALINA_HOME/lib` directory.

2. If using Derby, copy `derby.war` into the `$CATALINA_HOME/webapps` directory and specify the directory where
   the Derby databases are located (skip this step if another database is used):

        :::bash
        export JAVA_OPTS=-Dderby.system.home=$SIS_DATA/Databases

3. Declare the JNDI name in application `WEB-INF/web.xml` file:

        :::xml
        <resource-ref>
          <description>EPSG dataset and other metadata used by Apache SIS.</description>
          <res-ref-name>jdbc/SpatialMetadata</res-ref-name>
          <res-type>javax.sql.DataSource</res-type>
          <res-auth>Container</res-auth>
        </resource-ref>

4. Configure the data source in `$CATALINA_HOME/conf/context.xml` or in application `META-INF/context.xml` file
   (change attribute values as needed for the chosen JDBC driver):

        :::xml
        <Context crossContext="true">
          <WatchedResource>WEB-INF/web.xml</WatchedResource>
          <Resource name            = "jdbc/SpatialMetadata"
                    auth            = "Container"
                    type            = "javax.sql.DataSource"
                    username        = "sa"
                    password        = "sa"
                    driverClassName = "org.apache.derby.jdbc.EmbeddedDriver"
                    url             = "jdbc:derby:SpatialMetadata"/>
        </Context>

5. If using Derby, verify on the `localhost:8080/derby/derbynet` page (skip this step if another database is used).

More advanced configurations are possible. For example Tomcat can invoke a custom Java method instead than
fetching the data source from the `context.xml` file.




[IOGP]:     https://www.iogp.org/
[EPSG]:     https://epsg.org/
[EPSG-ToU]: https://epsg.org/terms-of-use.html
[Derby]:    http://db.apache.org/derby/derby_downloads.html