Author: buildbot
Date: Thu May 19 21:08:36 2016
New Revision: 988680
Log:
Staging update by buildbot for sis
Modified:
websites/staging/sis/trunk/content/ (props changed)
websites/staging/sis/trunk/content/epsg.html
Propchange: websites/staging/sis/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Thu May 19 21:08:36 2016
@@ -1 +1 @@
-1744633
+1744639
Modified: websites/staging/sis/trunk/content/epsg.html
==============================================================================
--- websites/staging/sis/trunk/content/epsg.html (original)
+++ websites/staging/sis/trunk/content/epsg.html Thu May 19 21:08:36 2016
@@ -115,11 +115,16 @@ are incompatible with Apache license. Th
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 SIS, there is two
possibilities:</p>
+<p>In order to use the EPSG geodetic dataset with Apache SIS, there is the
following possibilities:</p>
<div class="toc">
<ul>
<li><a href="#command-line">Install a local copy with command-line
tool</a></li>
<li><a href="#maven">Add a Maven dependency</a></li>
+<li><a href="#jndi">Use Java Naming and Directory Interface</a><ul>
+<li><a href="#jndi-java">Registration by Java code</a></li>
+<li><a href="#jndi-webapp">Registration in web application containers</a></li>
+</ul>
+</li>
</ul>
</div>
<h1 id="command-line">Install a local copy with command-line tool<a
class="headerlink" href="#command-line" title="Permanent link">¶</a></h1>
@@ -154,9 +159,76 @@ The <code><dependency></code> frag
<li>Set the <code>SIS_DATA</code> environment variable to the path of an
initially empty directory <em>(preferred choice)</em>.</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.</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>
</ul>
<p>The directory referenced by <code>SIS_DATA</code> or
<code>derby.system.home</code> must exist.
Sub-directories in that directory will be created as needed.</p>
+<h1 id="jndi">Use Java Naming and Directory Interface<a class="headerlink"
href="#jndi" title="Permanent link">¶</a></h1>
+<p>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
+if the <code
style="white-space:normal">org.apache.sis.non-free:âsis-epsg:â0.7</code>
dependency is on the classpath
+(see <a href="#maven">above section</a>).</p>
+<p>For using an arbitrary database, register a
<code>javax.sql.DataSource</code> 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.</p>
+<h2 id="jndi-java">Registration by Java code<a class="headerlink"
href="#jndi-java" title="Permanent link">¶</a></h2>
+<p>Registration can be done by the following Java code, provided that a JNDI
implementation is available on the classpath:</p>
+<div class="codehilite"><pre><span class="c1">// Example using PostgreSQL data
source (org.postgresql.ds.PGSimpleDataSource)</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 class="n">ds</span><span class="o">.</span><span
class="na">setServerName</span><span class="o">(</span><span
class="s">"localhost"</span><span class="o">);</span>
+<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 class="c1">// Registration assuming that a JNDI implementation is
available</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 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>
+</pre></div>
+
+
+<h2 id="jndi-webapp">Registration in web application containers<a
class="headerlink" href="#jndi-webapp" title="Permanent link">¶</a></h2>
+<p>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:</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>
+<p>:::bash
+ export JAVA_OPTS=-Dderby.system.home=$SIS_DATA/Databases</p>
+</li>
+<li>
+<p>Declare the JNDI name in application <code>WEB-INF/web.xml</code> file:</p>
+<p>:::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></p>
+</li>
+<li>
+<p>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):</p>
+<p>:::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></p>
+</li>
+<li>
+<p>If using Derby, verify on the <code>localhost:8080/derby/derbynet</code>
page (skip this step if another database is used).</p>
+</li>
+</ol>
+<p>More advanced configurations are possible. For example Tomcat can invoke a
custom Java method instead than
+fetching the data source from the <code>context.xml</code> file.</p>
</article>
</section>
</div><!--/span-->
