sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1811216 - in /sis/branches/JDK7: ./ application/sis-console/src/main/java/org/apache/sis/console/ core/sis-metadata/src/main/java/org/apache/sis/internal/metadata/sql/ core/sis-metadata/src/main/java/org/apache/sis/metadata/sql/ core/sis-m...
Date Thu, 05 Oct 2017 16:08:13 GMT
Author: desruisseaux
Date: Thu Oct  5 16:08:12 2017
New Revision: 1811216

URL: http://svn.apache.org/viewvc?rev=1811216&view=rev
Log:
Merge from the JDK8 branch.

Modified:
    sis/branches/JDK7/   (props changed)
    sis/branches/JDK7/application/sis-console/src/main/java/org/apache/sis/console/ResourcesDownloader.java
    sis/branches/JDK7/core/sis-metadata/src/main/java/org/apache/sis/internal/metadata/sql/Initializer.java
    sis/branches/JDK7/core/sis-metadata/src/main/java/org/apache/sis/metadata/sql/MetadataSource.java
    sis/branches/JDK7/core/sis-metadata/src/test/java/org/apache/sis/internal/metadata/sql/TestDatabase.java
    sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/internal/system/DataDirectory.java
    sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/setup/About.java
    sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/setup/InstallationResources.java
    sis/branches/JDK7/pom.xml

Propchange: sis/branches/JDK7/
------------------------------------------------------------------------------
--- svn:mergeinfo (original)
+++ svn:mergeinfo Thu Oct  5 16:08:12 2017
@@ -1,5 +1,5 @@
 /sis/branches/Android:1430670-1480699
 /sis/branches/JDK6:1394913-1508480
-/sis/branches/JDK8:1584960-1810974
+/sis/branches/JDK8:1584960-1811215
 /sis/branches/JDK9:1773327-1803064
 /sis/trunk:1394364-1508466,1519089-1519674

Modified: sis/branches/JDK7/application/sis-console/src/main/java/org/apache/sis/console/ResourcesDownloader.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/application/sis-console/src/main/java/org/apache/sis/console/ResourcesDownloader.java?rev=1811216&r1=1811215&r2=1811216&view=diff
==============================================================================
--- sis/branches/JDK7/application/sis-console/src/main/java/org/apache/sis/console/ResourcesDownloader.java
[UTF-8] (original)
+++ sis/branches/JDK7/application/sis-console/src/main/java/org/apache/sis/console/ResourcesDownloader.java
[UTF-8] Thu Oct  5 16:08:12 2017
@@ -51,7 +51,7 @@ import static org.apache.sis.internal.ut
  * </ul>
  *
  * @author  Martin Desruisseaux (Geomatys)
- * @version 0.7
+ * @version 0.8
  * @since   0.7
  * @module
  */
@@ -264,6 +264,26 @@ public class ResourcesDownloader extends
     }
 
     /**
+     * Returns an installation resource for the given authority.
+     * If that question has not already been asked, this method asks to the user if (s)he
accepts
+     * EPSG terms of use. If (s)he refuses, an {@link AccessDeniedException} will be thrown.
+     *
+     * @param  authority  one of the values returned by {@link #getAuthorities()}.
+     * @param  index      index of the resource to get, from 0 inclusive to
+     *         <code>{@linkplain #getResourceNames(String) getResourceNames}(authority).length</code>
exclusive.
+     * @return the resource as an URL or any other type, at implementation choice.
+     * @throws IllegalArgumentException if the given {@code authority} argument is not one
of the expected values.
+     * @throws IndexOutOfBoundsException if the given {@code resource} argument is out of
bounds.
+     * @throws IOException if an error occurred while fetching the resource.
+     *
+     * @since 0.8
+     */
+    @Override
+    public Object getResource(final String authority, final int index) throws IOException
{
+        return provider(authority, true).getResource(authority, index);
+    }
+
+    /**
      * Returns a reader for the installation script at the given index.
      * This method is invoked by {@link org.apache.sis.referencing.factory.sql.EPSGFactory#install(Connection)}
      * for getting the SQL scripts to execute during EPSG dataset installation.

Modified: sis/branches/JDK7/core/sis-metadata/src/main/java/org/apache/sis/internal/metadata/sql/Initializer.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-metadata/src/main/java/org/apache/sis/internal/metadata/sql/Initializer.java?rev=1811216&r1=1811215&r2=1811216&view=diff
==============================================================================
--- sis/branches/JDK7/core/sis-metadata/src/main/java/org/apache/sis/internal/metadata/sql/Initializer.java
[UTF-8] (original)
+++ sis/branches/JDK7/core/sis-metadata/src/main/java/org/apache/sis/internal/metadata/sql/Initializer.java
[UTF-8] Thu Oct  5 16:08:12 2017
@@ -22,6 +22,7 @@ import java.net.URLClassLoader;
 import java.nio.file.Files;
 import java.nio.file.Path;
 import java.nio.file.Paths;
+import java.io.IOException;
 import java.util.concurrent.Callable;
 import java.util.logging.Level;
 import java.util.logging.LogRecord;
@@ -41,6 +42,7 @@ import javax.naming.event.EventContext;
 import javax.naming.event.NamingEvent;
 import javax.naming.event.NamingExceptionEvent;
 import javax.naming.event.ObjectChangeListener;
+import org.apache.sis.setup.InstallationResources;
 import org.apache.sis.internal.system.DefaultFactories;
 import org.apache.sis.internal.system.DataDirectory;
 import org.apache.sis.internal.system.Shutdown;
@@ -58,6 +60,15 @@ import org.apache.sis.util.logging.Loggi
  *   META-INF/services/org.apache.sis.internal.metadata.sql.Initializer
  * }
  *
+ * {@code Initializer} implementations should define the following methods:
+ *
+ * <ul>
+ *   <li>{@link #createSchema(Connection)} — invoked when a new database is created.</li>
+ *   <li>{@link #dataSourceChanged()} — invoked when the data source changed.</li>
+ * </ul>
+ *
+ * All other methods are related to getting the {@code DataSource} instance, through JNDI
or otherwise.
+ *
  * @author  Martin Desruisseaux (Geomatys)
  * @version 0.8
  * @since   0.7
@@ -67,8 +78,11 @@ public abstract class Initializer {
     /**
      * Name of the database to open in the {@code $SIS_DATA/Databases} directory or the directory
given by
      * the {@code derby.system.home} property.
+     *
+     * <div class="note"><b>Note:</b>
+     * this field is public for the needs of {@code non-free:sis-embedded-data} module.</div>
      */
-    private static final String DATABASE = "SpatialMetadata";
+    public static final String DATABASE = "SpatialMetadata";
 
     /**
      * The property name for the home of Derby databases.
@@ -81,6 +95,11 @@ public abstract class Initializer {
     public static final String JNDI = "jdbc/" + DATABASE;
 
     /**
+     * A pseudo-authority name used by {@link InstallationResources} for the embedded data
resources.
+     */
+    public static final String EMBEDDED = "Embedded";
+
+    /**
      * The class loader for JavaDB (i.e. the Derby database distributed with the JDK), created
when first needed.
      * This field is never reset to {@code null} even if the classpath changed because this
class loader is for
      * a JAR file the JDK installation directory, and we presume that the JDK installation
do not change.
@@ -100,6 +119,7 @@ public abstract class Initializer {
     /**
      * {@code true} if {@link #connected(DatabaseMetaData)} has been invoked at least once.
      * This is reset to {@code false} if the {@link #source} is changed.
+     * We use this information for logging purpose.
      */
     private static boolean connected;
 
@@ -239,6 +259,10 @@ public abstract class Initializer {
                     Listener.register((EventContext) env);
                 }
                 return source;
+                /*
+                 * No Derby shutdown hook for DataSource fetched fron JNDI.
+                 * We presume that shutdowns are handled by the container.
+                 */
             } catch (NameNotFoundException e) {
                 final LogRecord record = Messages.getResources(null).getLogRecord(
                         Level.CONFIG, Messages.Keys.JNDINotSpecified_1, JNDI);
@@ -248,42 +272,55 @@ public abstract class Initializer {
             /*
              * At this point we determined that there is no JNDI context or no object binded
to "jdbc/SpatialMetadata".
              * As a fallback, try to open the Derby database located in $SIS_DATA/Databases/SpatialMetadata
directory.
+             * Only if the SIS_DATA environment variable is not set, verify first if the
'sis-embedded-data' module is
+             * on the classpath. Note that if SIS_DATA is defined and valid, it has precedence.
              */
             final boolean create;
-            final String home = AccessController.doPrivileged(new PrivilegedAction<String>()
{
-                @Override public String run() {
-                    return System.getProperty(DERBY_HOME_KEY);
-                }
-            });
-            final Path dir = DataDirectory.DATABASES.getDirectory();
-            if (dir != null) {
-                Path path = dir.resolve(DATABASE);
-                if (home != null) try {
+            final boolean isEnvClear = DataDirectory.isEnvClear();
+            if (isEnvClear && (source = embedded()) != null) {
+                create = false;
+            } else {
+                final String home = AccessController.doPrivileged(new PrivilegedAction<String>()
{
+                    @Override public String run() {
+                        return System.getProperty(DERBY_HOME_KEY);
+                    }
+                });
+                final Path dir = DataDirectory.DATABASES.getDirectory();
+                if (dir != null) {
+                    Path path = dir.resolve(DATABASE);
+                    if (home != null) try {
+                        /*
+                         * If a "derby.system.home" property is set, we may be able to get
a shorter path by making it
+                         * relative to Derby home. The intend is to have a nicer URL like
"jdbc:derby:SpatialMetadata"
+                         * instead than "jdbc:derby:/a/long/path/to/SIS/Data/Databases/SpatialMetadata".
In addition
+                         * to making loggings and EPSGDataAccess.getAuthority() output nicer,
it also reduces the risk
+                         * of encoding issues if the path contains spaces or non-ASCII characters.
+                         */
+                        path = Paths.get(home).relativize(path);
+                    } catch (IllegalArgumentException | SecurityException e) {
+                        // The path can not be relativized. This is okay.
+                        Logging.recoverableException(Logging.getLogger(Loggers.SQL), Initializer.class,
"getDataSource", e);
+                    }
                     /*
-                     * If a "derby.system.home" property is set, we may be able to get a
shorter path by making it
-                     * relative to Derby home. The intend is to have a nicer URL like "jdbc:derby:SpatialMetadata"
-                     * instead than "jdbc:derby:/a/long/path/to/SIS/Data/Databases/SpatialMetadata".
In addition
-                     * to making loggings and EPSGDataAccess.getAuthority() output nicer,
it also reduces the risk
-                     * of encoding issues if the path contains spaces or non-ASCII characters.
+                     * Create the Derby data source using the context class loader if possible,
+                     * or otherwise a URL class loader to the JavaDB distributed with the
JDK.
                      */
-                    path = Paths.get(home).relativize(path);
-                } catch (IllegalArgumentException | SecurityException e) {
-                    // The path can not be relativized. This is okay.
-                    Logging.recoverableException(Logging.getLogger(Loggers.SQL), Initializer.class,
"getDataSource", e);
+                    path   = path.normalize();
+                    create = !Files.exists(path);
+                    source = forJavaDB(path.toString().replace(path.getFileSystem().getSeparator(),
"/"));
+                } else if (home != null) {
+                    final Path path = Paths.get(home);
+                    create = !Files.exists(path.resolve(DATABASE)) && Files.isDirectory(path);
+                    source = forJavaDB(DATABASE);
+                } else if (!isEnvClear) {
+                    create = false;
+                    source = embedded();        // Try only if we did not already tried after
above JNDI check.
+                    if (source == null) {
+                        return null;
+                    }
+                } else {
+                    return null;
                 }
-                /*
-                 * Create the Derby data source using the context class loader if possible,
-                 * or otherwise a URL class loader to the JavaDB distributed with the JDK.
-                 */
-                path   = path.normalize();
-                create = !Files.exists(path);
-                source = forJavaDB(path.toString().replace(path.getFileSystem().getSeparator(),
"/"));
-            } else if (home != null) {
-                final Path path = Paths.get(home);
-                create = !Files.exists(path.resolve(DATABASE)) && Files.isDirectory(path);
-                source = forJavaDB(DATABASE);
-            } else {
-                return null;
             }
             /*
              * Register the shutdown hook before to attempt any operation on the database
in order to close
@@ -330,6 +367,34 @@ public abstract class Initializer {
     }
 
     /**
+     * If the {@code non-free:sis-embedded-data} module is present on the classpath,
+     * returns the data source for embedded Derby database. Otherwise returns {@code null}.
+     *
+     * @see <a href="https://issues.apache.org/jira/browse/SIS-337">SIS-337</a>
+     *
+     * @since 0.8
+     */
+    private static DataSource embedded() {
+        for (InstallationResources res : DefaultFactories.createServiceLoader(InstallationResources.class))
{
+            if (res.getAuthorities().contains(EMBEDDED)) try {
+                final String[] names = res.getResourceNames(EMBEDDED);
+                for (int i=0; i<names.length; i++) {
+                    if (DATABASE.equals(names[i])) {
+                        final Object ds = res.getResource(EMBEDDED, i);
+                        if (ds instanceof DataSource) {
+                            return (DataSource) ds;
+                        }
+                    }
+                }
+            } catch (IOException e) {
+                Logging.unexpectedException(Logging.getLogger(Loggers.SQL), Initializer.class,
"getDataSource", e);
+                // Continue - the system will fallback on the hard-coded subset of EPSG definitions.
+            }
+        }
+        return null;
+    }
+
+    /**
      * Prepares a log record saying that a connection to the spatial metadata database has
been created.
      * This method can be invoked after {@link DataSource#getConnection()}. When invoked
for the first time,
      * the record level is set to {@link Level#CONFIG}. On next calls, the level become {@link
Level#FINE}.
@@ -458,10 +523,13 @@ public abstract class Initializer {
     /**
      * Returns {@code true} if the given exception is the one that we expect in successful
shutdown of a Derby database.
      *
+     * <div class="note"><b>Note:</b>
+     * this method is public for the needs of {@code non-free:sis-embedded-data} module.</div>
+     *
      * @param  e  the exception thrown by Derby.
      * @return {@code true} if the exception indicates a successful shutdown.
      */
-    static boolean isSuccessfulShutdown(final SQLException e) {
+    public static boolean isSuccessfulShutdown(final SQLException e) {
         final String state = e.getSQLState();
         return "08006".equals(state) ||     // Database 'SpatialMetadata' shutdown.
                "XJ004".equals(state);       // Database 'SpatialMetadata' not found (may
happen if we failed to open it in the first place).

Modified: sis/branches/JDK7/core/sis-metadata/src/main/java/org/apache/sis/metadata/sql/MetadataSource.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-metadata/src/main/java/org/apache/sis/metadata/sql/MetadataSource.java?rev=1811216&r1=1811215&r2=1811216&view=diff
==============================================================================
--- sis/branches/JDK7/core/sis-metadata/src/main/java/org/apache/sis/metadata/sql/MetadataSource.java
[UTF-8] (original)
+++ sis/branches/JDK7/core/sis-metadata/src/main/java/org/apache/sis/metadata/sql/MetadataSource.java
[UTF-8] Thu Oct  5 16:08:12 2017
@@ -414,6 +414,9 @@ public class MetadataSource implements A
      *   <li>The schema name must be {@code "metadata"}, as this is the name used unquoted
in SQL scripts.</li>
      * </ul>
      *
+     * Maintenance note: this method is invoked by reflection in {@code non-free:sis-embedded-data}
module.
+     * If we make this method public in a future Apache SIS version, then we can remove the
reflection code.
+     *
      * @throws MetadataStoreException if an error occurred while inserting the metadata.
      */
     final synchronized void install() throws MetadataStoreException {

Modified: sis/branches/JDK7/core/sis-metadata/src/test/java/org/apache/sis/internal/metadata/sql/TestDatabase.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-metadata/src/test/java/org/apache/sis/internal/metadata/sql/TestDatabase.java?rev=1811216&r1=1811215&r2=1811216&view=diff
==============================================================================
--- sis/branches/JDK7/core/sis-metadata/src/test/java/org/apache/sis/internal/metadata/sql/TestDatabase.java
[UTF-8] (original)
+++ sis/branches/JDK7/core/sis-metadata/src/test/java/org/apache/sis/internal/metadata/sql/TestDatabase.java
[UTF-8] Thu Oct  5 16:08:12 2017
@@ -50,7 +50,7 @@ import static org.junit.Assume.*;
  *
  * <p><b>References:</b>
  * <ul>
- *   <li><a href="https://db.apache.org/derby/docs/10.2/adminguide/radminembeddedserverex.html">Embedded
server example</a></li>
+ *   <li><a href="https://db.apache.org/derby/docs/10.13/adminguide/radminembeddedserverex.html">Embedded
server example</a></li>
  * </ul>
  *
  * @author  Martin Desruisseaux (Geomatys)

Modified: sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/internal/system/DataDirectory.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/internal/system/DataDirectory.java?rev=1811216&r1=1811215&r2=1811216&view=diff
==============================================================================
--- sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/internal/system/DataDirectory.java
[UTF-8] (original)
+++ sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/internal/system/DataDirectory.java
[UTF-8] Thu Oct  5 16:08:12 2017
@@ -33,7 +33,7 @@ import org.apache.sis.util.resources.Mes
  * Sub-directories of {@code SIS_DATA} where SIS looks for EPSG database, datum shift grids
and other resources.
  *
  * @author  Martin Desruisseaux (Geomatys)
- * @version 0.7
+ * @version 0.8
  * @since   0.7
  * @module
  */
@@ -106,6 +106,44 @@ public enum DataDirectory {
     }
 
     /**
+     * Returns the value of {@value #ENV} environment variable, or {@code null} if none.
+     * This method does not perform any logging and does not verify if the directory exists.
+     * If the intend is to perform I/O operations, use {@link #getRootDirectory()} instead.
+     *
+     * @return the {@value #ENV} environment variable, or {@code null} if none.
+     * @throws SecurityException if this method is not allowed to query the environment variable.
+     *
+     * @see System#getenv(String)
+     *
+     * @since 0.8
+     */
+    public static String getenv() throws SecurityException {
+        return AccessController.doPrivileged(new PrivilegedAction<String>() {
+            @Override public String run() {
+                return System.getenv(ENV);
+            }
+        });
+    }
+
+    /**
+     * Returns {@code true} if the {@value #ENV} environment variable is unset. In case of
doubt, this method
+     * returns {@code false}. This method is used for avoiding or at leat delaying the log
messages emitted by
+     * {@link #getRootDirectory()} when a fallback exists in absence of any user attempt
to configure the system.
+     *
+     * @return {@code true} if the {@value #ENV} environment variable is unset.
+     *
+     * @since 0.8
+     */
+    public static synchronized boolean isEnvClear() {
+        if (rootDirectory == null) try {
+            return getenv() == null;
+        } catch (SecurityException e) {
+            Logging.recoverableException(Logging.getLogger(Loggers.SYSTEM), DataDirectory.class,
"isEnvClear", e);
+        }
+        return false;
+    }
+
+    /**
      * Returns the root directory fetched from the {@code SIS_DATA} environment variable.
      * If the environment variable is not set or the directory does not exist, then this
method returns {@code null}.
      *
@@ -113,11 +151,7 @@ public enum DataDirectory {
      */
     public static synchronized Path getRootDirectory() {
         if (rootDirectory == null) try {
-            final String dir = AccessController.doPrivileged(new PrivilegedAction<String>()
{
-                @Override public String run() {
-                    return System.getenv(ENV);
-                }
-            });
+            final String dir = getenv();
             if (dir == null || dir.isEmpty()) {
                 warning("getRootDirectory", null, Messages.Keys.DataDirectoryNotSpecified_1,
ENV);
             } else try {

Modified: sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/setup/About.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/setup/About.java?rev=1811216&r1=1811215&r2=1811216&view=diff
==============================================================================
--- sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/setup/About.java [UTF-8]
(original)
+++ sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/setup/About.java [UTF-8]
Thu Oct  5 16:08:12 2017
@@ -39,8 +39,6 @@ import java.text.DateFormat;
 import java.text.FieldPosition;
 import java.nio.file.Path;
 import java.nio.charset.Charset;
-import java.security.AccessController;
-import java.security.PrivilegedAction;
 import org.apache.sis.util.ArgumentChecks;
 import org.apache.sis.util.CharSequences;
 import org.apache.sis.util.Exceptions;
@@ -382,11 +380,7 @@ fill:   for (int i=0; ; i++) {
                     if (sections.contains(PATHS)) {
                         nameKey = Vocabulary.Keys.DataDirectory;
                         try {
-                            value = AccessController.doPrivileged(new PrivilegedAction<String>()
{
-                                @Override public String run() {
-                                    return System.getenv(DataDirectory.ENV);
-                                }
-                            });
+                            value = DataDirectory.getenv();
                         } catch (SecurityException e) {
                             value = e.toString();
                         }

Modified: sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/setup/InstallationResources.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/setup/InstallationResources.java?rev=1811216&r1=1811215&r2=1811216&view=diff
==============================================================================
--- sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/setup/InstallationResources.java
[UTF-8] (original)
+++ sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/setup/InstallationResources.java
[UTF-8] Thu Oct  5 16:08:12 2017
@@ -27,7 +27,7 @@ import java.io.BufferedReader;
  * {@code InstallationResources} can be used for downloading large files that may not be
of interest
  * to every users, or data that are subject to more restricting terms of use than the Apache
license.
  *
- * <div class="note"><b>Examples:</b><ul>
+ * <div class="note"><b>Examples:</b><ul class="verbose">
  * <li>The NADCON grid files provide <cite>datum shifts</cite> data for
North America.
  *     Since those files are in the public domain, they could be bundled in Apache SIS.
  *     But the weight of those files (about 2.4 Mb) is unnecessary for users who do not live
in North America.</li>
@@ -37,8 +37,18 @@ import java.io.BufferedReader;
  *     are more restrictive than the Apache license and require that we inform the users
about those conditions.</li>
  * </ul></div>
  *
- * Some classes that depend on installation resources are:
- * {@link org.apache.sis.referencing.factory.sql.EPSGFactory}.
+ * Some authorities implemented in Apache SIS modules are listed below.
+ * In this list, {@code "Embedded"} is a pseudo-authority for an embedded database containing
EPSG and other data.
+ * The embedded database is provided as a convenience for avoiding the need to define a {@code
SIS_DATA} directory
+ * on the local machine.
+ *
+ * <table class="sis">
+ *   <caption>Authorities supported by Apache SIS</caption>
+ *   <tr><th>Authority</th>          <th>Provided by Maven module</th>
                         <th>Used by class</th></tr>
+ *   <tr><td>{@code "EPSG"}</td>     <td>{@code org.apache.sis.non-free:sis-epsg}</td>
         <td>{@link org.apache.sis.referencing.factory.sql.EPSGFactory}</td></tr>
+ *   <tr><td>{@code "Embedded"}</td> <td>{@code org.apache.sis.non-free:sis-embedded-data}</td>
<td>All the above</td></tr>
+ * </table>
+ *
  * In order to allow those classes to discover which resources are available,
  * {@code InstallationResources} implementations shall be declared in the following file:
  *
@@ -47,13 +57,13 @@ import java.io.BufferedReader;
  * }
  *
  * Above registration is usually done automatically when extension modules are added on the
classpath.
- * For example adding the {@code org.apache.sis.non-free:​sis-epsg} Maven dependency as
documented on
+ * For example adding the {@code org.apache.sis.non-free:sis-epsg} Maven dependency as documented
on
  * the <a href="http://sis.apache.org/epsg.html">Apache SIS web site</a> is the
only step needed for
  * allowing Apache SIS to read the EPSG scripts (however SIS still needs an installation
directory
  * for writing the database; see above-cited web page for more information).
  *
  * @author  Martin Desruisseaux (Geomatys)
- * @version 0.7
+ * @version 0.8
  * @since   0.7
  * @module
  */
@@ -69,9 +79,19 @@ public abstract class InstallationResour
      * The values recognized by SIS are listed below
      * (note that this list may be expanded in any future SIS versions):
      *
-     * <ul>
-     *   <li>{@code "EPSG"} for the EPSG geodetic dataset.</li>
-     * </ul>
+     * <table class="sis">
+     *   <caption>Authorities supported by Apache SIS</caption>
+     *   <tr><th>Authority</th>          <th>Resources</th></tr>
+     *   <tr><td>{@code "EPSG"}</td>     <td>SQL installation scripts
for EPSG geodetic dataset.</td></tr>
+     *   <tr><td>{@code "Embedded"}</td> <td>Data source of embedded
database containing EPSG and other resources.</td></tr>
+     * </table>
+     *
+     * <div class="note"><b>Note:</b>
+     * {@code "Embedded"} is a pseudo-authority for an embedded database containing EPSG
and other data.
+     * This embedded database is provided by the {@code org.apache.sis.non-free:sis-embedded-data}
module
+     * as a convenience for avoiding the need to define a {@code SIS_DATA} directory on the
local machine.
+     * In this particular case, the resource is more for execution than for installation.
+     * </div>
      *
      * This method may return an empty set if this {@code InstallationResources} instance
did not find the
      * resources (for example because of files not found) or does not have the permission
to distribute them.
@@ -84,10 +104,19 @@ public abstract class InstallationResour
      * Returns the terms of use of the resources distributed by the specified authority,
or {@code null} if none.
      * The terms of use can be returned in either plain text or HTML.
      *
-     * <div class="note"><b>Example:</b>
-     * For the {@code "EPSG"} authority, this method may return a copy of the
-     * <a href="http://www.epsg.org/TermsOfUse">http://www.epsg.org/TermsOfUse</a>
page.
-     * </div>
+     * <table class="sis">
+     *   <caption>Licenses for some supported authorities</caption>
+     *   <tr>
+     *     <th>Authority</th>
+     *     <th>License</th>
+     *   </tr><tr>
+     *     <td>{@code "EPSG"}</td>
+     *     <td>A copy of the <a href="http://www.epsg.org/TermsOfUse">http://www.epsg.org/TermsOfUse</a>
page.</td>
+     *   </tr><tr>
+     *     <td>{@code "Embedded"}</td>
+     *     <td>Above EPSG license.</td>
+     *   </tr>
+     * </table>
      *
      * @param  authority  one of the values returned by {@link #getAuthorities()}.
      * @param  locale     the preferred locale for the terms of use.
@@ -101,12 +130,18 @@ public abstract class InstallationResour
     /**
      * Returns the names of all resources of the specified authority that are distributed
by this instance.
      * The resources will be used in the order they appear in the array.
+     * Examples:
      *
-     * <div class="note"><b>Example:</b>
-     * for the {@code "EPSG"} authority, this method may return the filenames of all SQL
scripts to execute.
-     * One of the first script creates tables, followed by a script that populates tables
with data,
-     * followed by a script that creates foreigner keys.
-     * </div>
+     * <ul class="verbose">
+     *   <li><b>{@code "EPSG"} authority:</b>
+     *     the resource names are the filenames of all SQL scripts to execute. One of the
first script creates tables,
+     *     followed by a script that populates tables with data, followed by a script that
creates foreigner keys.
+     *   </li>
+     *   <li><b>{@code "Embedded"} pseudo-authority:</b>
+     *     the database name, which is {@code "SpatialMetadata"}.
+     *     When embedded, this database is read-only.
+     *   </li>
+     * </ul>
      *
      * @param  authority  one of the values returned by {@link #getAuthorities()}.
      * @return the names of all resources of the given authority that are distributed by
this instance.
@@ -116,6 +151,31 @@ public abstract class InstallationResour
     public abstract String[] getResourceNames(String authority) throws IOException;
 
     /**
+     * Returns an installation resource for the given authority, or {@code null} if not available.
+     * The return value may be an instance of any type, at implementation choice.
+     * This may be for example a {@link java.net.URL} referencing the actual resource.
+     *
+     * <p>The default implementation returns {@code null}. A null value means that
the resource is fetched by
+     * {@link #openScript(String, int)} instead than this method. We do not return {@link
java.net.URL} to text
+     * files in order to ensure that the file is opened with proper character encoding.</p>
+     *
+     * @param  authority  one of the values returned by {@link #getAuthorities()}.
+     * @param  index      index of the resource to get, from 0 inclusive to
+     *         <code>{@linkplain #getResourceNames(String) getResourceNames}(authority).length</code>
exclusive.
+     * @return the resource as an URL or any other type (at implementation choice), or {@code
null} if not available.
+     * @throws IllegalArgumentException if the given {@code authority} argument is not one
of the expected values.
+     * @throws IndexOutOfBoundsException if the given {@code resource} argument is out of
bounds.
+     * @throws IOException if an error occurred while fetching the resource.
+     *
+     * @see ClassLoader#getResource(String)
+     *
+     * @since 0.8
+     */
+    public Object getResource(String authority, int index) throws IOException {
+        return null;
+    }
+
+    /**
      * Returns a reader for the resources at the given index.
      * The resource may be a SQL script or any other resources readable as a text.
      * The returned {@link BufferedReader} instance shall be closed by the caller.

Modified: sis/branches/JDK7/pom.xml
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/pom.xml?rev=1811216&r1=1811215&r2=1811216&view=diff
==============================================================================
--- sis/branches/JDK7/pom.xml (original)
+++ sis/branches/JDK7/pom.xml Thu Oct  5 16:08:12 2017
@@ -431,6 +431,11 @@ Apache SIS is a free software, Java lang
 
       <!-- Databases -->
       <dependency>
+        <groupId>org.apache.derby</groupId>
+        <artifactId>derby</artifactId>
+        <version>10.13.1.1</version>
+      </dependency>
+      <dependency>
         <groupId>org.hsqldb</groupId>
         <artifactId>hsqldb</artifactId>
         <version>2.3.5</version>                <!-- Last version compatible
with JDK7.-->



Mime
View raw message