| <!DOCTYPE html> |
| <html lang="en"> |
| <head> |
| |
| |
| <title>Apache SIS - How to use EPSG geodetic dataset</title> |
| <meta charset="utf-8"> |
| <meta name="viewport" content="width=device-width, initial-scale=1"> |
| <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.1.1/dist/css/bootstrap.min.css" |
| rel="stylesheet" integrity="sha384-F3w7mX95PdgyTmZZMECAngseQB83DfGTowi0iMjiWaeVhAn4FJkqJByhZMI3AhiU" crossorigin="anonymous"> |
| <link rel="stylesheet" type="text/css" media="screen" href="./syntax.css"> |
| <link rel="stylesheet" type="text/css" media="screen" href="./sis.css"> |
| </head> |
| |
| <body> |
| |
| <nav class="navbar navbar-expand-md navbar-dark fixed-top bg-dark"> |
| <div class="container-fluid"> |
| <a class="navbar-brand" href="./index.html"> Apache SIS™</a> |
| <ul class="navbar-nav me-auto mb-2 mb-md-0"> |
| <li class="nav-item dropdown"> |
| <a class="nav-link dropdown-toggle" id="menuAbout" data-bs-toggle="dropdown" aria-expanded="false">About</a> |
| <ul class="dropdown-menu" aria-labelledby="menuAbout"> |
| <li><a class="dropdown-item" href="http://www.apache.org/licenses/">License</a></li> |
| <li><a class="dropdown-item" href="./mail-lists.html">Mailing Lists</a></li> |
| <li><a class="dropdown-item" href="./team-list.html">Project Team</a></li> |
| <li><a class="dropdown-item" href="https://privacy.apache.org/policies/privacy-policy-public.html">Privacy policy</a></li> |
| </ul> |
| </li> |
| <li class="nav-item dropdown"> |
| <a class="nav-link dropdown-toggle" id="menuDownload" data-bs-toggle="dropdown" aria-expanded="false">Download</a> |
| <ul class="dropdown-menu" aria-labelledby="menuDownload"> |
| <li><a class="dropdown-item" href="./downloads.html">Downloads</a></li> |
| <li><a class="dropdown-item" href="./source.html">Checkout Sources</a></li> |
| <li><a class="dropdown-item" href="./epsg.html">EPSG Database</a></li> |
| </ul> |
| </li> |
| <li class="nav-item dropdown"> |
| <a class="nav-link dropdown-toggle" id="menuDocumentation" data-bs-toggle="dropdown" aria-expanded="false">Documentation</a> |
| <ul class="dropdown-menu" aria-labelledby="menuDocumentation"> |
| <li><a class="dropdown-item" href="./apidocs/index.html">Online Javadoc</a></li> |
| <li><a class="dropdown-item" href="./book/en/developer-guide.html">Developer Guide</a></li> |
| <li><a class="dropdown-item" href="./howto.html">How to…</a></li> |
| <li><a class="dropdown-item" href="./formats.html">Supported formats</a></li> |
| <li><a class="dropdown-item" href="./tables/CoordinateReferenceSystems.html">Supported CRS</a></li> |
| <li><a class="dropdown-item" href="./tables/CoordinateOperationMethods.html">Map Projections</a></li> |
| <li><a class="dropdown-item" href="./code-patterns.html">Code Patterns</a></li> |
| <li><a class="dropdown-item" href="./faq.html">FAQ</a></li> |
| </ul> |
| </li> |
| <li class="nav-item dropdown"> |
| <a class="nav-link dropdown-toggle" id="menuContribute" data-bs-toggle="dropdown" aria-expanded="false">Contribute</a> |
| <ul class="dropdown-menu" aria-labelledby="menuContribute"> |
| <li><a class="dropdown-item" href="./contributor.html">New Contributor</a></li> |
| <li><a class="dropdown-item" href="./coding-conventions.html">Coding Conventions</a></li> |
| <li><a class="dropdown-item" href="./mail-lists.html">Mailing Lists</a></li> |
| <li><a class="dropdown-item" href="https://issues.apache.org/jira/browse/SIS">Issue Tracker</a></li> |
| <li><a class="dropdown-item" href="https://github.com/apache/sis">GitHub mirror</a></li> |
| <li><a class="dropdown-item" href="https://cwiki.apache.org/confluence/display/SIS">Wiki</a></li> |
| <li><hr class="dropdown-divider"></li> |
| <li><a class="dropdown-item" href="./release-management.html">Release management</a></li> |
| </ul> |
| </li> |
| <li class="nav-item dropdown"> |
| <a class="nav-link dropdown-toggle" id="menuASF" data-bs-toggle="dropdown" aria-expanded="false">The Foundation</a> |
| <ul class="dropdown-menu" aria-labelledby="menuASF"> |
| <li><a class="dropdown-item" href="http://www.apache.org">The Foundation</a></li> |
| <li><a class="dropdown-item" href="http://www.apache.org/foundation/sponsorship.html">Donate</a></li> |
| <li><a class="dropdown-item" href="http://www.apache.org/foundation/thanks.html">Thanks</a></li> |
| <li><a class="dropdown-item" href="http://www.apache.org/security/">Security</a></li> |
| </ul> |
| </li> |
| </ul> |
| <ul class="navbar-nav ml-auto mb-2 mb-md-0"> |
| <li class="nav-item"> |
| <a href="https://www.apache.org/events/current-event.html"> |
| <img class="apache-con" src="https://www.apache.org/events/current-event-234x60.png" alt="ApacheCon"/> |
| </a> |
| </li> |
| </ul> |
| </div> |
| </nav> |
| |
| |
| <div class="row flex-nowrap"> |
| <div class="d-flex flex-column flex-shrink-0 p-3 text-white bg-dark" style="width:13rem; min-height:40rem"> |
| <ul class="nav nav-pills flex-column mb-auto position-fixed"> |
| <li><a class="nav-link text-white " href="./index.html">Home</a></li> |
| <li><a class="nav-link text-white" href="http://www.apache.org/licenses/">License</a></li> |
| <li><a class="nav-link text-white " href="./downloads.html">Downloads</a></li> |
| <li><a class="nav-link text-white " href="./howto.html">How to…</a></li> |
| <li><a class="nav-link text-white " href="./standards.html">Standards</a></li> |
| <li><a class="nav-link text-white " href="./formats.html">Data formats</a></li> |
| <li><a class="nav-link active " href="./epsg.html">EPSG Database</a></li> |
| <li><a class="nav-link text-white " href="./javafx.html">Application (demo)</a></li> |
| <li><a class="nav-link text-white" href="./apidocs/index.html">Online Javadoc</a></li> |
| <li><a class="nav-link text-white" href="./book/en/developer-guide.html">Developer Guide</a></li> |
| <li><a class="nav-link text-white " href="./code-patterns.html">Code patterns</a></li> |
| <li><a class="nav-link text-white " href="./faq.html">FAQ</a></li> |
| </ul> |
| </div> |
| <div class="col"> |
| <main class="container"> |
| <article> |
| <img src="./images/logo.png" class="sis-logo" align="left"/> |
| <p class="page-title">How to use EPSG geodetic dataset</p> |
| |
| <p>The <a href="https://epsg.org/">EPSG geodetic dataset</a> is a de-facto standard providing |
| <a href="tables/CoordinateReferenceSystems.html">thousands of Coordinate Reference System (CRS) definitions</a> |
| 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 <a href="https://www.iogp.org/">International Association of Oil & Gas producers</a>. |
| Usage of EPSG dataset with Apache <abbr title="Spatial Information System">SIS</abbr> 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 <a href="apidocs/org/apache/sis/referencing/CommonCRS.html"><code>CommonCRS</code></a> Java class) |
| unless full definitions are provided in <em>Well Known Text</em> (WKT) or <em>Geographic Markup Language</em> (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 <abbr title="Spatial Information System">SIS</abbr> cannot query EPSG.</p> |
| <p>The EPSG geodetic dataset is not distributed with Apache <abbr title="Spatial Information System">SIS</abbr> because the <a href="https://epsg.org/terms-of-use.html">EPSG terms of use</a> |
| are incompatible with Apache license. The following items are quoted from those terms of use:</p> |
| <ul> |
| <li>The <a href="https://epsg.org/">EPSG</a> Facilities are published by <a href="https://www.iogp.org/">IOGP</a> at no charge. Distribution for profit is forbidden.</li> |
| <li>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.</li> |
| <li>Ownership of the EPSG Dataset by IOGP must be acknowledged in any publication or transmission |
| (by whatever means) thereof (including permitted modifications).</li> |
| <li>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.</li> |
| <li>No data that has been modified other than as permitted in these Terms of Use shall be attributed to the EPSG Dataset.</li> |
| </ul> |
| <p>In order to use the EPSG geodetic dataset with Apache <abbr title="Spatial Information System">SIS</abbr>, apply <em>one</em> of the following choices:</p> |
| <nav id="TableOfContents"> |
| <ul> |
| <li><a href="#command-line">Install a local copy with command-line tool </a> |
| <ul> |
| <li><a href="#use-local">How to use the local copy in other applications </a></li> |
| </ul> |
| </li> |
| <li><a href="#maven">Add a Maven dependency </a> |
| <ul> |
| <li><a href="#maven-epsg">As database installer </a></li> |
| <li><a href="#maven-embedded">As embedded database </a></li> |
| </ul> |
| </li> |
| <li><a href="#existing">Use an existing EPSG database </a> |
| <ul> |
| <li><a href="#setup">Registration by Java code </a></li> |
| <li><a href="#jndi-java">Registration by Java Naming and Directory Interface </a></li> |
| <li><a href="#jndi-webapp">Registration in web application containers </a></li> |
| </ul> |
| </li> |
| </ul> |
| </nav> |
| <h1 id="command-line">Install a local copy with command-line tool </h1> |
| <p>The installation process described in this section makes clear that EPSG dataset |
| is distributed under a different license and asks users for their agreement. |
| This process can be used with the <a href="downloads.html#bundles">Apache SIS 1.4 binary bundle</a>. |
| If the <a href="command-line.html">command-line tool</a> has been downloaded and installed, just query any CRS. |
| For example:</p> |
| <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">sis crs EPSG:6676</span></span></code></pre></div> |
| <p>Alternatively if the <a href="javafx.html">JavaFX application</a> is used, just start the application. |
| It may be necessary to open a random data file for triggering the EPSG dataset initialization. |
| In both cases, the first time that the command-line tool or JavaFX application 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 <code>apache-sis-1.4/data</code> sub-directory.</p> |
| <h2 id="use-local">How to use the local copy in other applications </h2> |
| <p>The EPSG dataset installed by the command-line tools or the JavaFX application can also be used with other applications. |
| For using the installed EPSG geodetic dataset in your own application, apply <em>one</em> of the following choices:</p> |
| <ul> |
| <li>Set the <code>SIS_DATA</code> environment variable to the path of <code>apache-sis-1.4/data</code> directory <em>(recommended)</em>.</li> |
| <li>Set the <code>derby.system.home</code> Java property to the path of <code>apache-sis-1.4/data/Databases</code> directory.</li> |
| </ul> |
| <p>Examples are shown below for Unix systems, assuming that the current directory is the directory where <code>apache-sis-1.4-bin.zip</code> |
| has been unzipped (replace <code>myApp</code> and <code>MyMainClass</code> by the application to launch):</p> |
| <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="nb">export</span> <span class="nv">SIS_DATA</span><span class="o">=</span>apache-sis-1.4/data |
| </span></span><span class="line"><span class="cl">java --class-path apache-sis-1.4/lib/sis-referencing.jar:myApp.jar MyMainClass</span></span></code></pre></div> |
| <p>If the <code>SIS_DATA</code> environment variable cannot be set, Java property can be used as a fallback:</p> |
| <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">java -Dderby.system.home<span class="o">=</span>apache-sis-1.4/data/Databases <span class="se">\ |
| </span></span></span><span class="line"><span class="cl"><span class="se"></span> --class-path apache-sis-1.4/lib/sis-referencing.jar:myApp.jar <span class="se">\ |
| </span></span></span><span class="line"><span class="cl"><span class="se"></span> MyMainClass</span></span></code></pre></div> |
| <p>Alternatively <code>SIS_DATA</code> or <code>derby.system.home</code> can be set to the path of any other directory which contain the same files.</p> |
| <h1 id="maven">Add a Maven dependency </h1> |
| <p>Maven projects can get the EPSG geodetic dataset automatically, <em>without any prompt for terms of use agreement</em>, |
| if they add a <code>sis-epsg</code> or <code>sis-embedded-data</code> dependency (from <code>org.apache.sis.non-free</code> 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 explicitly in their project agree with |
| <a href="https://epsg.org/terms-of-use.html">EPSG terms of use</a>.</p> |
| <h2 id="maven-epsg">As database installer </h2> |
| <p>With <code>sis-epsg</code> artifact on the classpath, Apache <abbr title="Spatial Information System">SIS</abbr> will create a local copy of EPSG database when first needed. |
| The target database must be specified by users with <em>one</em> of the following choices:</p> |
| <ul> |
| <li>Set the <code>SIS_DATA</code> environment variable to the path of an initially empty directory <em>(recommended)</em>. |
| The specified directory must exist, but sub-directories will be created as needed.</li> |
| <li>Set the <code>derby.system.home</code> Java property to the path of an initially empty directory, |
| or a directory that contain other Derby databases. The specified directory must exist.</li> |
| <li>Register a <code>DataSource</code> under the <code>java:comp/env/jdbc/SpatialMetadata</code> name in a JNDI directory |
| (see <a href="#jndi">next section</a>). The database must exist but can be initially empty.</li> |
| <li>Set a <code>DataSource</code> <a href="./apidocs/org/apache/sis/setup/Configuration.html">from Java code</a>.</li> |
| </ul> |
| <p>The Maven dependency is as below (the Derby dependency can be replaced by another database driver |
| if that database is specified by JNDI):</p> |
| <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-xml" data-lang="xml"><span class="line"><span class="cl"><span class="nt"><dependencies></span> |
| </span></span><span class="line"><span class="cl"> <span class="nt"><dependency></span> |
| </span></span><span class="line"><span class="cl"> <span class="nt"><groupId></span>org.apache.sis.non-free<span class="nt"></groupId></span> |
| </span></span><span class="line"><span class="cl"> <span class="nt"><artifactId></span>sis-epsg<span class="nt"></artifactId></span> |
| </span></span><span class="line"><span class="cl"> <span class="nt"><version></span>1.4<span class="nt"></version></span> |
| </span></span><span class="line"><span class="cl"> <span class="nt"><scope></span>runtime<span class="nt"></scope></span> |
| </span></span><span class="line"><span class="cl"> <span class="nt"></dependency></span> |
| </span></span><span class="line"><span class="cl"> <span class="nt"><dependency></span> |
| </span></span><span class="line"><span class="cl"> <span class="nt"><groupId></span>org.apache.derby<span class="nt"></groupId></span> |
| </span></span><span class="line"><span class="cl"> <span class="nt"><artifactId></span>derby<span class="nt"></artifactId></span> |
| </span></span><span class="line"><span class="cl"> <span class="nt"><version></span>10.14.2.0<span class="nt"></version></span> |
| </span></span><span class="line"><span class="cl"> <span class="nt"><scope></span>runtime<span class="nt"></scope></span> |
| </span></span><span class="line"><span class="cl"> <span class="nt"></dependency></span> |
| </span></span><span class="line"><span class="cl"><span class="nt"></dependencies></span></span></span></code></pre></div> |
| <p>See the <a href="downloads.html#epsg">download</a> page for more information about Maven dependency declaration.</p> |
| <h2 id="maven-embedded">As embedded database </h2> |
| <p>With <code>sis-embedded-data</code> artifact on the classpath, there is no need to setup environment variable, Java property or JNDI. |
| However this simplicity come with the following inconvenient:</p> |
| <ul> |
| <li>a larger download,</li> |
| <li>no option for choosing which data to use (and consequently which license to accept),</li> |
| <li>no possibility to choose the database engine (i.e. the database software is fixed to Derby),</li> |
| <li>no possibility to add user data (i.e. the database is read-only),</li> |
| <li>slower execution of <code>CRS.forCode(…)</code> and <code>CRS.findCoordinateOperation(…)</code> methods, unless the JAR file is uncompressed.</li> |
| </ul> |
| <p>This dependency can be declared as below |
| (see the <a href="downloads.html#epsg">download</a> page for more information about Maven dependency declaration). |
| Note that <code>sis-epsg</code> and <code>sis-embedded-data</code> should not be specified in the same project; only one is needed:</p> |
| <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-xml" data-lang="xml"><span class="line"><span class="cl"><span class="nt"><dependencies></span> |
| </span></span><span class="line"><span class="cl"> <span class="nt"><dependency></span> |
| </span></span><span class="line"><span class="cl"> <span class="nt"><groupId></span>org.apache.sis.non-free<span class="nt"></groupId></span> |
| </span></span><span class="line"><span class="cl"> <span class="nt"><artifactId></span>sis-embedded-data<span class="nt"></artifactId></span> |
| </span></span><span class="line"><span class="cl"> <span class="nt"><version></span>1.4<span class="nt"></version></span> |
| </span></span><span class="line"><span class="cl"> <span class="nt"><scope></span>runtime<span class="nt"></scope></span> |
| </span></span><span class="line"><span class="cl"> <span class="nt"></dependency></span> |
| </span></span><span class="line"><span class="cl"><span class="nt"></dependencies></span></span></span></code></pre></div> |
| <p>The performance issue can be avoided if the JAR file is uncompressed. |
| But uncompressed <code>sis-embedded-data.jar</code> file is more than 5 times larger than the compressed file. |
| Given that <code>CRS.forCode(…)</code> and <code>CRS.findCoordinateOperation(…)</code> should not be invoked too often, |
| and that performance degradation does not apply to the <code>CoordinateOperation</code> 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 <code>sis-embedded-data.jar</code> file locally.</p> |
| <h1 id="existing">Use an existing EPSG database </h1> |
| <p>Applications can use their own EPSG database. |
| In addition of Derby, Apache <abbr title="Spatial Information System">SIS</abbr> is also tested on HSQL and PostgreSQL. |
| For using an arbitrary database, register a <code>javax.sql.DataSource</code> instance through one of the methods described below. |
| 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.4</code> dependency is on the classpath |
| (see <a href="#maven-epsg">above section</a>). |
| If non-empty, the database should contain the tables created by SQL scripts downloaded from <a href="https://epsg.org/">EPSG</a>. |
| <strong>Note thas as of Apache SIS 1.2, only EPSG dataset version 9 is supported. |
| EPSG datasets version 10 and later are not yet supported.</strong></p> |
| <h2 id="setup">Registration by Java code </h2> |
| <p>The data source can be specified by Java code as below |
| (replace the <code>main</code> method by any method where initialization occurs):</p> |
| <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">javax.sql.DataSource</span><span class="o">;</span> |
| </span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">org.apache.sis.setup.Configuration</span><span class="o">;</span> |
| </span></span><span class="line"><span class="cl"> |
| </span></span><span class="line"><span class="cl"><span class="kd">public</span> <span class="kt">void</span> <span class="n">MyApp</span> <span class="o">{</span> |
| </span></span><span class="line"><span class="cl"> <span class="kd">public</span> <span class="kd">static</span> <span class="kt">void</span> <span class="nf">main</span><span class="o">(</span><span class="n">String</span><span class="o">[]</span> <span class="n">args</span><span class="o">)</span> <span class="o">{</span> |
| </span></span><span class="line"><span class="cl"> <span class="n">Configuration</span><span class="o">.</span><span class="na">current</span><span class="o">().</span><span class="na">setDatabase</span><span class="o">(</span><span class="n">MyApp</span><span class="o">::</span><span class="n">createDataSource</span><span class="o">);</span> |
| </span></span><span class="line"><span class="cl"> <span class="o">}</span> |
| </span></span><span class="line"><span class="cl"> |
| </span></span><span class="line"><span class="cl"> <span class="kd">private</span> <span class="kd">static</span> <span class="n">DataSource</span> <span class="nf">createDataSource</span><span class="o">()</span> <span class="o">{</span> |
| </span></span><span class="line"><span class="cl"> <span class="n">DataSource</span> <span class="n">ds</span> <span class="o">=</span> <span class="o">...;</span> <span class="c1">// Initialize the data source here. |
| </span></span></span><span class="line"><span class="cl"><span class="c1"></span> <span class="k">return</span> <span class="n">ds</span><span class="o">;</span> |
| </span></span><span class="line"><span class="cl"> <span class="o">}</span> |
| </span></span><span class="line"><span class="cl"><span class="o">}</span></span></span></code></pre></div> |
| <h2 id="jndi-java">Registration by Java Naming and Directory Interface </h2> |
| <p>Registration in JNDI can be done programmatically (by Java code) or by configuring XML files in some environments. |
| Registration can be done by the following Java code, provided that a JNDI implementation is available on the classpath:</p> |
| <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="c1">// Example using PostgreSQL data source (org.postgresql.ds.PGSimpleDataSource) |
| </span></span></span><span class="line"><span class="cl"><span class="c1"></span><span class="n">PGSimpleDataSource</span> <span class="n">ds</span> <span class="o">=</span> <span class="k">new</span> <span class="n">PGSimpleDataSource</span><span class="o">();</span> |
| </span></span><span class="line"><span class="cl"><span class="n">ds</span><span class="o">.</span><span class="na">setDatabaseName</span><span class="o">(</span><span class="s">"SpatialMetadata"</span><span class="o">);</span> |
| </span></span><span class="line"><span class="cl"><span class="c1">// Server default to "localhost". |
| </span></span></span><span class="line"><span class="cl"><span class="c1"></span> |
| </span></span><span class="line"><span class="cl"><span class="c1">// Registration assuming that a JNDI implementation is available |
| </span></span></span><span class="line"><span class="cl"><span class="c1"></span><span class="n">Context</span> <span class="n">env</span> <span class="o">=</span> <span class="o">(</span><span class="n">Context</span><span class="o">)</span> <span class="n">InitialContext</span><span class="o">.</span><span class="na">doLookup</span><span class="o">(</span><span class="s">"java:comp/env"</span><span class="o">);</span> |
| </span></span><span class="line"><span class="cl"><span class="n">env</span><span class="o">.</span><span class="na">bind</span><span class="o">(</span><span class="s">"jdbc/SpatialMetadata"</span><span class="o">,</span> <span class="n">ds</span><span class="o">);</span></span></span></code></pre></div> |
| <p>If there is no JNDI environment, the <code>org.apache.sis.setup.Configuration</code> class can be used as a fallback:</p> |
| <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">// Fallback <span class="k">if</span> no JNDI environment is available. |
| </span></span><span class="line"><span class="cl">Configuration.current<span class="o">()</span>.setDatabase<span class="o">(()</span> -> ds<span class="o">)</span><span class="p">;</span></span></span></code></pre></div> |
| <h2 id="jndi-webapp">Registration in web application containers </h2> |
| <p>JNDI implementations are provided by web application containers like Apache Tomcat. |
| When Apache <abbr title="Spatial Information System">SIS</abbr> is used in a JavaEE container, the data source can be configured as below:</p> |
| <ol> |
| <li> |
| <p>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 <code>$CATALINA_HOME/lib</code> directory.</p> |
| </li> |
| <li> |
| <p>If using Derby, copy <code>derby.war</code> into the <code>$CATALINA_HOME/webapps</code> directory and specify the directory where |
| the Derby databases are located (skip this step if another database is used):</p> |
| </li> |
| </ol> |
| <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="nb">export</span> <span class="nv">JAVA_OPTS</span><span class="o">=</span>-Dderby.system.home<span class="o">=</span><span class="nv">$SIS_DATA</span>/Databases</span></span></code></pre></div> |
| <ol start="3"> |
| <li>Declare the JNDI name in application <code>WEB-INF/web.xml</code> file:</li> |
| </ol> |
| <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-xml" data-lang="xml"><span class="line"><span class="cl"><span class="nt"><resource-ref></span> |
| </span></span><span class="line"><span class="cl"> <span class="nt"><description></span>EPSG dataset and other metadata used by Apache SIS.<span class="nt"></description></span> |
| </span></span><span class="line"><span class="cl"> <span class="nt"><res-ref-name></span>jdbc/SpatialMetadata<span class="nt"></res-ref-name></span> |
| </span></span><span class="line"><span class="cl"> <span class="nt"><res-type></span>javax.sql.DataSource<span class="nt"></res-type></span> |
| </span></span><span class="line"><span class="cl"> <span class="nt"><res-auth></span>Container<span class="nt"></res-auth></span> |
| </span></span><span class="line"><span class="cl"><span class="nt"></resource-ref></span></span></span></code></pre></div> |
| <ol start="4"> |
| <li>Configure the data source in <code>$CATALINA_HOME/conf/context.xml</code> or in application <code>META-INF/context.xml</code> file |
| (change attribute values as needed for the chosen JDBC driver):</li> |
| </ol> |
| <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-xml" data-lang="xml"><span class="line"><span class="cl"><span class="nt"><Context</span> <span class="na">crossContext=</span><span class="s">"true"</span><span class="nt">></span> |
| </span></span><span class="line"><span class="cl"> <span class="nt"><WatchedResource></span>WEB-INF/web.xml<span class="nt"></WatchedResource></span> |
| </span></span><span class="line"><span class="cl"> <span class="nt"><Resource</span> <span class="na">name =</span> <span class="s">"jdbc/SpatialMetadata"</span> |
| </span></span><span class="line"><span class="cl"> <span class="na">auth =</span> <span class="s">"Container"</span> |
| </span></span><span class="line"><span class="cl"> <span class="na">type =</span> <span class="s">"javax.sql.DataSource"</span> |
| </span></span><span class="line"><span class="cl"> <span class="na">username =</span> <span class="s">"sa"</span> |
| </span></span><span class="line"><span class="cl"> <span class="na">password =</span> <span class="s">"sa"</span> |
| </span></span><span class="line"><span class="cl"> <span class="na">driverClassName =</span> <span class="s">"org.apache.derby.jdbc.EmbeddedDriver"</span> |
| </span></span><span class="line"><span class="cl"> <span class="na">url =</span> <span class="s">"jdbc:derby:SpatialMetadata"</span><span class="nt">/></span> |
| </span></span><span class="line"><span class="cl"><span class="nt"></Context></span></span></span></code></pre></div> |
| <ol start="5"> |
| <li>If using Derby, verify on the <code>localhost:8080/derby/derbynet</code> page (skip this step if another database is used).</li> |
| </ol> |
| <p>More advanced configurations are possible. For example Tomcat can invoke a custom Java method instead of |
| fetching the data source from the <code>context.xml</code> file.</p> |
| |
| |
| </article> |
| </main> |
| <footer class="footer"> |
| <div class="container"> |
| <p> |
| Copyright © 2013-2023 The Apache Software Foundation, Licensed under the |
| <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.<br/> |
| Apache SIS, Apache, the Apache feather logo are trademarks of The Apache Software Foundation. |
| </p> |
| </div> |
| </footer> |
| </div> |
| </div> |
| |
| <script src="https://cdn.jsdelivr.net/npm/bootstrap@5.1.1/dist/js/bootstrap.bundle.min.js" |
| integrity="sha384-/bQdsTh/da6pkI1MST/rWKFNjaCP5gBSY4sEBT38Q/9RBh9AH40zEOg7Hlq2THRZ" crossorigin="anonymous"></script> |
| |
| </body> |
| </html> |
