sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject svn commit: r1744639 - /sis/site/trunk/content/epsg.mdtext
Date Thu, 19 May 2016 21:08:31 GMT
Author: desruisseaux
Date: Thu May 19 21:08:30 2016
New Revision: 1744639

Add information about configuration through JNDI.


Modified: sis/site/trunk/content/epsg.mdtext
--- 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:
 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
   * 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
+    (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`
+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`
+   (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.

View raw message