Author: desruisseaux
Date: Thu May 19 21:08:30 2016
New Revision: 1744639
URL: http://svn.apache.org/viewvc?rev=1744639&view=rev
Log:
Add information about configuration through JNDI.
Modified:
sis/site/trunk/content/epsg.mdtext
Modified: sis/site/trunk/content/epsg.mdtext
URL:
http://svn.apache.org/viewvc/sis/site/trunk/content/epsg.mdtext?rev=1744639&r1=1744638&r2=1744639&view=diff
==============================================================================
--- sis/site/trunk/content/epsg.mdtext [UTF-8] (original)
+++ sis/site/trunk/content/epsg.mdtext [UTF-8] Thu May 19 21:08:30 2016
@@ -41,13 +41,12 @@ are incompatible with Apache license. Th
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, there is two
possibilities:
+In order to use the EPSG geodetic dataset with Apache SIS, there is the
following possibilities:
[TOC]
-
Install a local copy with command-line tool {#command-line}
==============================================================
@@ -75,7 +74,6 @@ Alternatively `SIS_DATA` or `derby.syste
-
Add a Maven dependency {#maven}
==============================================================
@@ -91,12 +89,92 @@ In addition, users need to apply *one* o
* Set the `SIS_DATA` environment variable to the path of an initially empty
directory _(preferred choice)_.
* Set the `derby.system.home` Java property to the path of an initially
empty directory,
or a directory that contain other Derby databases.
+ * 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.
The directory referenced by `SIS_DATA` or `derby.system.home` must exist.
Sub-directories in that directory will be created as needed.
+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.
+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 [above section](#maven)).
+
+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 {#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);
+
+
+
+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]: http://www.iogp.org/
[EPSG]: http://www.epsg.org/
[EPSG-ToU]: http://www.epsg.org/TermsOfUse
