Author: desruisseaux
Date: Thu Oct 5 16:11:46 2017
New Revision: 1811217
URL: http://svn.apache.org/viewvc?rev=1811217&view=rev
Log:
Merge from JDK7 branch.
Modified:
sis/trunk/ (props changed)
sis/trunk/application/sis-console/src/main/java/org/apache/sis/console/ResourcesDownloader.java
sis/trunk/core/sis-metadata/src/main/java/org/apache/sis/internal/metadata/sql/Initializer.java
sis/trunk/core/sis-metadata/src/main/java/org/apache/sis/metadata/sql/MetadataSource.java
sis/trunk/core/sis-metadata/src/test/java/org/apache/sis/internal/metadata/sql/TestDatabase.java
sis/trunk/core/sis-utility/src/main/java/org/apache/sis/internal/system/DataDirectory.java
sis/trunk/core/sis-utility/src/main/java/org/apache/sis/setup/About.java
sis/trunk/core/sis-utility/src/main/java/org/apache/sis/setup/InstallationResources.java
sis/trunk/pom.xml
Propchange: sis/trunk/
------------------------------------------------------------------------------
--- svn:mergeinfo (original)
+++ svn:mergeinfo Thu Oct 5 16:11:46 2017
@@ -1,5 +1,5 @@
/sis/branches/Android:1430670-1480699
/sis/branches/JDK6:1394364-1758914
-/sis/branches/JDK7:1394913-1810976
-/sis/branches/JDK8:1584960-1810974
+/sis/branches/JDK7:1394913-1811216
+/sis/branches/JDK8:1584960-1811215
/sis/branches/JDK9:1773327-1803064
Modified:
sis/trunk/application/sis-console/src/main/java/org/apache/sis/console/ResourcesDownloader.java
URL:
http://svn.apache.org/viewvc/sis/trunk/application/sis-console/src/main/java/org/apache/sis/console/ResourcesDownloader.java?rev=1811217&r1=1811216&r2=1811217&view=diff
==============================================================================
---
sis/trunk/application/sis-console/src/main/java/org/apache/sis/console/ResourcesDownloader.java
[UTF-8] (original)
+++
sis/trunk/application/sis-console/src/main/java/org/apache/sis/console/ResourcesDownloader.java
[UTF-8] Thu Oct 5 16:11:46 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/trunk/core/sis-metadata/src/main/java/org/apache/sis/internal/metadata/sql/Initializer.java
URL:
http://svn.apache.org/viewvc/sis/trunk/core/sis-metadata/src/main/java/org/apache/sis/internal/metadata/sql/Initializer.java?rev=1811217&r1=1811216&r2=1811217&view=diff
==============================================================================
---
sis/trunk/core/sis-metadata/src/main/java/org/apache/sis/internal/metadata/sql/Initializer.java
[UTF-8] (original)
+++
sis/trunk/core/sis-metadata/src/main/java/org/apache/sis/internal/metadata/sql/Initializer.java
[UTF-8] Thu Oct 5 16:11:46 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/trunk/core/sis-metadata/src/main/java/org/apache/sis/metadata/sql/MetadataSource.java
URL:
http://svn.apache.org/viewvc/sis/trunk/core/sis-metadata/src/main/java/org/apache/sis/metadata/sql/MetadataSource.java?rev=1811217&r1=1811216&r2=1811217&view=diff
==============================================================================
---
sis/trunk/core/sis-metadata/src/main/java/org/apache/sis/metadata/sql/MetadataSource.java
[UTF-8] (original)
+++
sis/trunk/core/sis-metadata/src/main/java/org/apache/sis/metadata/sql/MetadataSource.java
[UTF-8] Thu Oct 5 16:11:46 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/trunk/core/sis-metadata/src/test/java/org/apache/sis/internal/metadata/sql/TestDatabase.java
URL:
http://svn.apache.org/viewvc/sis/trunk/core/sis-metadata/src/test/java/org/apache/sis/internal/metadata/sql/TestDatabase.java?rev=1811217&r1=1811216&r2=1811217&view=diff
==============================================================================
---
sis/trunk/core/sis-metadata/src/test/java/org/apache/sis/internal/metadata/sql/TestDatabase.java
[UTF-8] (original)
+++
sis/trunk/core/sis-metadata/src/test/java/org/apache/sis/internal/metadata/sql/TestDatabase.java
[UTF-8] Thu Oct 5 16:11:46 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/trunk/core/sis-utility/src/main/java/org/apache/sis/internal/system/DataDirectory.java
URL:
http://svn.apache.org/viewvc/sis/trunk/core/sis-utility/src/main/java/org/apache/sis/internal/system/DataDirectory.java?rev=1811217&r1=1811216&r2=1811217&view=diff
==============================================================================
---
sis/trunk/core/sis-utility/src/main/java/org/apache/sis/internal/system/DataDirectory.java
[UTF-8] (original)
+++
sis/trunk/core/sis-utility/src/main/java/org/apache/sis/internal/system/DataDirectory.java
[UTF-8] Thu Oct 5 16:11:46 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/trunk/core/sis-utility/src/main/java/org/apache/sis/setup/About.java
URL:
http://svn.apache.org/viewvc/sis/trunk/core/sis-utility/src/main/java/org/apache/sis/setup/About.java?rev=1811217&r1=1811216&r2=1811217&view=diff
==============================================================================
--- sis/trunk/core/sis-utility/src/main/java/org/apache/sis/setup/About.java
[UTF-8] (original)
+++ sis/trunk/core/sis-utility/src/main/java/org/apache/sis/setup/About.java
[UTF-8] Thu Oct 5 16:11:46 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/trunk/core/sis-utility/src/main/java/org/apache/sis/setup/InstallationResources.java
URL:
http://svn.apache.org/viewvc/sis/trunk/core/sis-utility/src/main/java/org/apache/sis/setup/InstallationResources.java?rev=1811217&r1=1811216&r2=1811217&view=diff
==============================================================================
---
sis/trunk/core/sis-utility/src/main/java/org/apache/sis/setup/InstallationResources.java
[UTF-8] (original)
+++
sis/trunk/core/sis-utility/src/main/java/org/apache/sis/setup/InstallationResources.java
[UTF-8] Thu Oct 5 16:11:46 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/trunk/pom.xml
URL:
http://svn.apache.org/viewvc/sis/trunk/pom.xml?rev=1811217&r1=1811216&r2=1811217&view=diff
==============================================================================
--- sis/trunk/pom.xml (original)
+++ sis/trunk/pom.xml Thu Oct 5 16:11:46 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.-->
