How to use EPSG geodetic dataset
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 Facilities are published by 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.
In order to use the EPSG geodetic dataset with Apache SIS, apply one of the following choices:
Install a local copy with command-line tool¶
If the command-line tool has been downloaded and installed, just query any CRS. For example:
sis crs EPSG:6676
The first time that the command-line tool needs to query EPSG, it will prompt the user for authorization
copy of the EPSG geodetic dataset will be created and stored in the
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
This is normally not needed with Oracle JDK6, JDK7 or 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.
For using the installed EPSG geodetic dataset in your own application, apply one of the following choices:
- Set the
SIS_DATAenvironment variable to the path to the
apache-sis-0.7/datadirectory (preferred choice).
- Set the
derby.system.homeJava property to the path to the
derby.system.home can be set to the path of any other directory which contain the same files.
Add a Maven dependency¶
if they add a dependency to the
artifact in their project.
<dependency> fragment to use in
pom.xml files is given in the download page.
In addition, users need to apply one of the following choices:
- Set the
SIS_DATAenvironment variable to the path of an initially empty directory (preferred choice).
- Set the
derby.system.homeJava property to the path of an initially empty directory, or a directory that contain other Derby databases.
- Register a
java:comp/env/jdbc/SpatialMetadataname in a JNDI directory (see next section). The database must exist but can be initially empty.
The directory referenced by
derby.system.home must exist.
Sub-directories in that directory will be created as needed.
Use Java Naming and Directory Interface¶
While Apache SIS uses Apache Derby by default, it is also possible to use another database software like HSQL or PostgreSQL.
The database must exist but can be empty, in which case it will be populated with an EPSG schema when first needed
org.apache.sis.non-free:sis-epsg:0.7 dependency is on the classpath
(see above section).
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.
Registration by Java code¶
Registration can be done by the following Java code, provided that a JNDI implementation is available on the classpath:
// 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);
Registration in web application containers¶
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
If using Derby, copy
$CATALINA_HOME/webappsdirectory and specify the directory where the Derby databases are located (skip this step if another database is used):
Declare the JNDI name in application
<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>
Configure the data source in
$CATALINA_HOME/conf/context.xmlor in application
META-INF/context.xmlfile (change attribute values as needed for the chosen JDBC driver):
<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>
If using Derby, verify on the
localhost:8080/derby/derbynetpage (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