sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
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

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



Mime
View raw message