The EPSG geodetic dataset is a de-facto standard providing thousands of Coordinate Reference System (CRS) definitions 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. 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
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 are incompatible with Apache license. The following items are quoted from those terms of use:
In order to use the EPSG geodetic dataset with Apache SIS, apply one of the following choices:
{{< toc >}}
If the command-line tool has been downloaded and installed, just query any CRS. For example:
{{< highlight bash >}} sis crs EPSG:6676 {{< / highlight >}}
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) 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:
{{< highlight 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 {{< / highlight >}}
For using the installed EPSG geodetic dataset in your own application, apply one of the following choices:
SIS_DATA
environment variable to the path of apache-sis-1.0/data
directory (preferred choice).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:
{{< highlight bash >}} export SIS_DATA=apache-sis-1.0/data java -classpath apache-sis-1.0/lib/sis.jar:myApp.jar myMainClass {{< / highlight >}}
If the SIS_DATA
environment variable can not be set, Java property can be used as a fallback:
{{< highlight java >}} java -Dderby.system.home=apache-sis-1.0/data/Databases -classpath apache-sis-1.0/lib/sis.jar:myApp.jar myMainClass {{< / highlight >}}
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.
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:
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.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.DataSource
under the java:comp/env/jdbc/SpatialMetadata
name in a JNDI directory (see next section). The database must exist but can be initially empty.DataSource
from Java code.The Maven dependency is as below (the Derby dependency can be replaced by another database driver if that database is specified by JNDI):
{{< highlight xml >}} org.apache.sis.non-free sis-epsg 1.0 runtime
See the download page for more information about Maven dependency declaration.
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:
CRS.forCode(…)
and CRS.findCoordinateOperation(…)
methods, unless the JAR file is uncompressed.This dependency can be declared as below (see the download 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:
{{< highlight xml >}} org.apache.sis.non-free sis-embedded-data 1.0 runtime {{< / highlight >}}
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.
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 org.apache.sis.non-free:sis-epsg:1.0 dependency is on the classpath (see above section).
Registration can be done by the following Java code, provided that a JNDI implementation is available on the classpath:
{{< highlight 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); {{< / highlight >}}
If there is no JNDI environment, the org.apache.sis.setup.Configuration
class can be used as a fallback:
{{< highlight java >}} // Fallback if no JNDI environment is available. Configuration.current().setDatabase(() -> ds); {{< / highlight >}}
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:
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.
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):
{{< highlight bash >}} export JAVA_OPTS=-Dderby.system.home=$SIS_DATA/Databases {{< / highlight >}}
WEB-INF/web.xml
file:{{< highlight xml >}} EPSG dataset and other metadata used by Apache SIS. jdbc/SpatialMetadata javax.sql.DataSource Container {{< / highlight >}}
$CATALINA_HOME/conf/context.xml
or in application META-INF/context.xml
file (change attribute values as needed for the chosen JDBC driver):{{< highlight xml >}} WEB-INF/web.xml {{< / highlight >}}
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.