sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1811325 - in /sis/site/trunk/content: downloads.mdtext epsg.mdtext
Date Fri, 06 Oct 2017 12:52:56 GMT
Author: desruisseaux
Date: Fri Oct  6 12:52:56 2017
New Revision: 1811325

URL: http://svn.apache.org/viewvc?rev=1811325&view=rev
Log:
Update instruction about how to use EPSG database.

Modified:
    sis/site/trunk/content/downloads.mdtext
    sis/site/trunk/content/epsg.mdtext

Modified: sis/site/trunk/content/downloads.mdtext
URL: http://svn.apache.org/viewvc/sis/site/trunk/content/downloads.mdtext?rev=1811325&r1=1811324&r2=1811325&view=diff
==============================================================================
--- sis/site/trunk/content/downloads.mdtext [UTF-8] (original)
+++ sis/site/trunk/content/downloads.mdtext [UTF-8] Fri Oct  6 12:52:56 2017
@@ -107,23 +107,15 @@ If you accept those terms of use, then t
     <dependencies>
       <dependency>
         <groupId>org.apache.sis.non-free</groupId>
-        <artifactId>sis-epsg</artifactId>
+        <artifactId>sis-embedded-data</artifactId>
         <version>${sis.version}</version>
         <scope>runtime</scope>
       </dependency>
-
-      <!-- Following dependency can be omitted on Oracle JDK6, JDK7 or JDK8
-           since those Java distributions contain Derby (a.k.a JavaDB). -->
-      <dependency>
-        <groupId>org.apache.derby</groupId>
-        <artifactId>derby</artifactId>
-        <version>10.12.1.1</version>
-        <scope>runtime</scope>
-      </dependency>
     </dependencies>
 
-In addition, user should set the `SIS_DATA` environment variable to an initially empty directory
-where Apache SIS will store the EPSG geodetic database.
+Above dependency uses a read-only embedded Derby database.
+But it is also possible to use an EPSG database on HSQL or PostgreSQL,
+or a database allowing additions of user definitions.
 See [How to use EPSG geodetic dataset](epsg.html) page for more information.
 
 

Modified: sis/site/trunk/content/epsg.mdtext
URL: http://svn.apache.org/viewvc/sis/site/trunk/content/epsg.mdtext?rev=1811325&r1=1811324&r2=1811325&view=diff
==============================================================================
--- sis/site/trunk/content/epsg.mdtext [UTF-8] (original)
+++ sis/site/trunk/content/epsg.mdtext [UTF-8] Fri Oct  6 12:52:56 2017
@@ -58,19 +58,29 @@ For example:
 
 The first time that the command-line tool 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 `apache-sis-0.7/data`
sub-directory.
+copy of the EPSG geodetic dataset will be created and stored in the `apache-sis-0.8/data`
sub-directory.
 
 If the command-line tool does not offer to download the EPSG geodetic dataset,
-try adding a `derby-<version>.jar` file (download lib-distribution from [Derby project][Derby])
in the `apache-sis-0.7/lib` sub-directory.
+try adding a `derby-<version>.jar` file (download lib-distribution from [Derby project][Derby])
in the `apache-sis-0.8/lib` sub-directory.
 This is normally not needed with Oracle JDK6, JDK7 or JDK8 because Apache SIS tries to use
the JavaDB embedded
 in those distributions, but may be necessary with other distributions or in security-constrained
environments.
 
 For using the installed EPSG geodetic dataset in your own application, apply *one* of the
following choices:
 
-  * Set the `SIS_DATA` environment variable to the path to the `apache-sis-0.7/data` directory
_(preferred choice)_.
-  * Set the `derby.system.home` Java property to the path to the `apache-sis-0.7/data/Databases`
directory.
+  * Set the `SIS_DATA` environment variable to the path of `apache-sis-0.8/data` directory
_(preferred choice)_.
+  * Set the `derby.system.home` Java property to the path of `apache-sis-0.8/data/Databases`
directory.
 
 Alternatively `SIS_DATA` or `derby.system.home` can be set to the path of any other directory
which contain the same files.
+Examples are shown below for Unix systems, assuming that the current directory is the directory
where `apache-sis-0.8-bin.zip`
+has been unzipped:
+
+    :::bash
+    export SIS_DATA=apache-sis-0.8/data
+    java -classpath apache-sis-0.8/lib/sis.jar:myApp.jar myMainClass
+
+If the `SIS_DATA` environment variable can not be set, Java property can be used as a fallback:
+
+    java -Dderby.system.home=apache-sis-0.8/data/Databases -classpath apache-sis-0.8/lib/sis.jar:myApp.jar
myMainClass
 
 
 
@@ -78,22 +88,72 @@ Add a Maven dependency    {#maven}
 ==============================================================
 
 Maven projects can get the EPSG geodetic dataset automatically, _without any prompt for terms
of use agreement_,
-if they add a dependency to the
-<code style="white-space:normal">org.apache.sis.non-free:​sis-epsg:​0.7</code>
-artifact in their project.
-We assume that developers who add this dependency explicitely in their project agree with
EPSG terms of use.
-The `<dependency>` fragment to use in `pom.xml` files is given in the [download](downloads.html#epsg)
page.
+if they add a `sis-epsg` or `sis-embedded-data` dependency (from `org.apache.sis.non-free`
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 explicitely in their
project agree with
+[EPSG terms of use][EPSG-ToU].
+
 
-In addition, users need to apply *one* of the following choices:
+
+As database installer     {#maven-epsg}
+---------------------------------------
+
+With `sis-epsg` artifact on the classpath, Apache SIS will create a local copy of EPSG database
when first needed.
+The target database must be specified by users with *one* of the following choices:
 
   * Set the `SIS_DATA` environment variable to the path of an initially empty directory _(preferred
choice)_.
+    The specified directory must exist, but sub-directories will be created as needed.
   * Set the `derby.system.home` Java property to the path of an initially empty directory,
-    or a directory that contain other Derby databases.
+    or a directory that contain other Derby databases. The specified directory must exist.
   * 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.
+The Maven dependency is as below (the Derby dependency can be replaced by another database
driver
+if that database is specified by JNDI):
+
+    :::xml
+    <dependencies>
+      <dependency>
+        <groupId>org.apache.sis.non-free</groupId>
+        <artifactId>sis-epsg</artifactId>
+        <version>${sis.version}</version>
+        <scope>runtime</scope>
+      </dependency>
+
+      <!-- Following dependency can be omitted on Oracle JDK6, JDK7 or JDK8
+           since those Java distributions contain Derby (a.k.a JavaDB). -->
+      <dependency>
+        <groupId>org.apache.derby</groupId>
+        <artifactId>derby</artifactId>
+        <version>10.13.1.1</version>
+        <scope>runtime</scope>
+      </dependency>
+    </dependencies>
+
+See the [download](downloads.html#epsg) page for more information about Maven dependency
declaration.
+
+
+
+As embedded database     {#maven-embedded}
+------------------------------------------
+
+With `sis-embedded-data` artifact on the classpath, there is no need to setup environment
variable, Java property or JNDI.
+However this simplicity come with the following inconvenient: a larger download, no option
for choosing which data to use
+(and consequently which license to accept), no possibility to choose the database engine
(i.e. the database software is
+fixed to Derby), and no possibility to add user data (i.e. the database is read-only).
+This dependency can be declared as below (note that `sis-epsg` should *not* be specified
in the same project than `sis-embedded-data`):
+
+    :::xml
+    <dependencies>
+      <dependency>
+        <groupId>org.apache.sis.non-free</groupId>
+        <artifactId>sis-embedded-data</artifactId>
+        <version>${sis.version}</version>
+        <scope>runtime</scope>
+      </dependency>
+    </dependencies>
+
+See the [download](downloads.html#epsg) page for more information about Maven dependency
declaration.
 
 
 
@@ -101,12 +161,11 @@ Use Java Naming and Directory Interface
 ==================================================
 
 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.
+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.8</code>
dependency is on the classpath
+(see [above section](#maven-epsg)).
 
 
 



Mime
View raw message