sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1732973 - in /sis/branches/JDK8: application/sis-console/src/main/java/org/apache/sis/console/ application/sis-console/src/main/resources/META-INF/ application/sis-console/src/main/resources/META-INF/services/ core/sis-referencing/src/main...
Date Mon, 29 Feb 2016 23:41:25 GMT
Author: desruisseaux
Date: Mon Feb 29 23:41:25 2016
New Revision: 1732973

URL: http://svn.apache.org/viewvc?rev=1732973&view=rev
Log:
First draft of automatic EPSG geodetic dataset download and installation, after asking user
to accept EPSG terms of use.
This initial draft downloads the data from a temporary URL. This URL will be changed after
discussion on the mailing list.

Added:
    sis/branches/JDK8/application/sis-console/src/main/java/org/apache/sis/console/LicensedDataProvider.java
  (with props)
    sis/branches/JDK8/application/sis-console/src/main/resources/META-INF/
    sis/branches/JDK8/application/sis-console/src/main/resources/META-INF/services/
    sis/branches/JDK8/application/sis-console/src/main/resources/META-INF/services/org.apache.sis.referencing.factory.sql.InstallationScriptProvider
  (with props)
    sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/internal/util/Fallback.java
  (with props)
    sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/setup/InstallationResources.java
  (with props)
Modified:
    sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/EPSGFactoryFallback.java
    sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/factory/sql/EPSGInstaller.java
    sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/factory/sql/InstallationScriptProvider.java
    sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/factory/sql/package-info.java
    sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/setup/package-info.java

Added: sis/branches/JDK8/application/sis-console/src/main/java/org/apache/sis/console/LicensedDataProvider.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/application/sis-console/src/main/java/org/apache/sis/console/LicensedDataProvider.java?rev=1732973&view=auto
==============================================================================
--- sis/branches/JDK8/application/sis-console/src/main/java/org/apache/sis/console/LicensedDataProvider.java
(added)
+++ sis/branches/JDK8/application/sis-console/src/main/java/org/apache/sis/console/LicensedDataProvider.java
[UTF-8] Mon Feb 29 23:41:25 2016
@@ -0,0 +1,222 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.sis.console;
+
+import java.util.Locale;
+import java.io.Console;
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.BufferedReader;
+import java.net.URL;
+import java.net.URLClassLoader;
+import java.util.ServiceLoader;
+import java.io.FileNotFoundException;
+import java.nio.file.AccessDeniedException;
+import java.sql.Connection;                             // For javadoc.
+import org.apache.sis.internal.util.Constants;
+import org.apache.sis.referencing.factory.sql.InstallationScriptProvider;
+import org.apache.sis.internal.util.Fallback;
+
+
+/**
+ * A provider for data licensed under different terms of use than the Apache license.
+ * This class is in charge of asking user's agreement before to install those data.
+ *
+ * @author  Martin Desruisseaux (Geomatys)
+ * @since   0.7
+ * @version 0.7
+ * @module
+ */
+@Fallback
+public class LicensedDataProvider extends InstallationScriptProvider {
+    /**
+     * Where to download the EPSG scripts after user has approved the terms of use.
+     *
+     * THIS IS A TEMPORARY LINK to be moved to another location after discussion on the mailing
list.
+     * This temporary link is provided in order to allow experimentations by other SIS developers.
+     */
+    private static final String DOWNLOAD_URL = "http://home.apache.org/~desruisseaux/Temporary/geotk-epsg-4.0-SNAPSHOT.jar";
+
+    /**
+     * The console to use for printing EPSG terms of use and asking for agreement, or {@code
null} if none.
+     */
+    private final Console console;
+
+    /**
+     * The locale to use for text display.
+     */
+    private final Locale locale;
+
+    /**
+     * The provider to use for fetching the actual licensed data after we got user's agreement.
+     */
+    private InstallationScriptProvider provider;
+
+    /**
+     * {@code true} if the user has accepted the EPSG terms of use, {@code false} if (s)he
refused,
+     * or {@code null} if (s)he did not yet answered that question.
+     */
+    private Boolean accepted;
+
+    /**
+     * Creates a new installation scripts provider.
+     */
+    public LicensedDataProvider() {
+        console = System.console();
+        locale = Locale.getDefault();
+    }
+
+    /**
+     * Returns the name of the authority who provides data under non-Apache terms of use.
+     * If this {@code LicensedDataProvider} can not ask user's agreement because there is
+     * no {@link Console} attached to the current Java virtual machine, then this method
+     * returns {@code "unavailable"}.
+     *
+     * @return {@code "EPSG"} or {@code "unavailable"}.
+     */
+    @Override
+    public String getAuthority() {
+        return (console != null) ? Constants.EPSG : "unavailable";
+    }
+
+    /**
+     * Downloads the provider to use for fetching the actual licensed data after we got user's
agreement.
+     */
+    private static InstallationScriptProvider download() throws IOException {
+        for (final InstallationScriptProvider c : ServiceLoader.load(InstallationScriptProvider.class,
+                new URLClassLoader(new URL[] {new URL(DOWNLOAD_URL)})))
+        {
+            if (!c.getClass().isAnnotationPresent(Fallback.class)) {
+                return c;
+            }
+        }
+        throw new FileNotFoundException();      // Should not happen.
+    }
+
+    /**
+     * Returns the provider to use for fetching the actual licensed data after we got user's
agreement.
+     * This method asks for user's agreement when first invoked.
+     *
+     * @param  requireAgreement {@code true} if license agreement is required.
+     * @throws AccessDeniedException if the user does not accept to install the EPSG dataset.
+     * @throws IOException if an error occurred while reading the {@link #DOWNLOAD_URL}.
+     */
+    private synchronized InstallationScriptProvider provider(final boolean requireAgreement)
throws IOException {
+        if (provider == null) {
+            if (console == null) {
+                throw new IllegalStateException();
+            }
+            console.format("%nInstallation of EPSG geodetic dataset is recommended for this
operation.%n");
+            if (!accept("Download and install now? (Yes/No) ")) {
+                console.format("%n");
+                throw new AccessDeniedException(null);
+            }
+            console.format("Downloading...%n");
+            provider = download();
+        }
+        if (requireAgreement && accepted == null) {
+            final String license = getLicense(locale, "text/plain");
+            if (license != null) {
+                console.format("%n").writer().write(license);
+            }
+            accepted = accept("%nAccept License Agreement? (Yes/No) ");
+            if (accepted) {
+                console.format("Installing...");
+            }
+            console.format("%n");
+        }
+        if (accepted != null && !accepted) {
+            throw new AccessDeniedException(null);
+        }
+        return provider;
+    }
+
+    /**
+     * Asks the user to answer by "Yes" or "No".
+     *
+     * @param prompt Message to show to the user.
+     * @return The user's answer.
+     */
+    private boolean accept(final String prompt) {
+        String line;
+        do {
+            line = console.readLine(prompt);
+            if (line.equalsIgnoreCase("n") || line.equalsIgnoreCase("no")) {
+                return false;
+            }
+        } while (!line.equalsIgnoreCase("y") && !line.equalsIgnoreCase("yes"));
+        return true;
+    }
+
+    /**
+     * Returns the terms of use of the dataset, or {@code null} if none.
+     * The terms of use can be returned in either plain text or HTML.
+     *
+     * @param  mimeType Either {@code "text/plain"} or {@code "text/html"}.
+     * @return The terms of use in plain text or HTML, or {@code null} if none.
+     * @throws IOException if an error occurred while reading the license file.
+     */
+    @Override
+    public String getLicense(Locale locale, String mimeType) throws IOException {
+        return provider(false).getLicense(locale, mimeType);
+    }
+
+    /**
+     * Returns the names of all SQL scripts to execute.
+     * This method is invoked by {@link org.apache.sis.referencing.factory.sql.EPSGFactory#install(Connection)}
+     * for listing the SQL scripts to execute during EPSG dataset installation.
+     *
+     * <p>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.</p>
+     *
+     * @return The names of all SQL scripts to execute.
+     * @throws IOException if an error occurred while fetching the script names.
+     */
+    @Override
+    public String[] getScriptNames() throws IOException {
+        return provider(true).getScriptNames();
+    }
+
+    /**
+     * Returns a reader for the SQL 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.
+     *
+     * <p>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.</p>
+     *
+     * @param  index Index of the SQL script to read, from 0 inclusive to
+     *         <code>{@linkplain #getScriptNames()}.length</code> exclusive.
+     * @return A reader for the content of SQL script to execute.
+     * @throws IOException if an error occurred while creating the reader.
+     */
+    @Override
+    public BufferedReader getScriptContent(final int index) throws IOException {
+        return provider(true).getScriptContent(index);
+    }
+
+    /**
+     * Unsupported operation.
+     *
+     * @param name Ignored.
+     * @return {@code null}.
+     */
+    @Override
+    protected InputStream open(String name) {
+        return null;
+    }
+}

Propchange: sis/branches/JDK8/application/sis-console/src/main/java/org/apache/sis/console/LicensedDataProvider.java
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: sis/branches/JDK8/application/sis-console/src/main/java/org/apache/sis/console/LicensedDataProvider.java
------------------------------------------------------------------------------
    svn:mime-type = text/plain;charset=UTF-8

Added: sis/branches/JDK8/application/sis-console/src/main/resources/META-INF/services/org.apache.sis.referencing.factory.sql.InstallationScriptProvider
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/application/sis-console/src/main/resources/META-INF/services/org.apache.sis.referencing.factory.sql.InstallationScriptProvider?rev=1732973&view=auto
==============================================================================
--- sis/branches/JDK8/application/sis-console/src/main/resources/META-INF/services/org.apache.sis.referencing.factory.sql.InstallationScriptProvider
(added)
+++ sis/branches/JDK8/application/sis-console/src/main/resources/META-INF/services/org.apache.sis.referencing.factory.sql.InstallationScriptProvider
[UTF-8] Mon Feb 29 23:41:25 2016
@@ -0,0 +1,2 @@
+# Licensed to the Apache Software Foundation (ASF) under one or more contributor license
agreements.
+org.apache.sis.console.LicensedDataProvider

Propchange: sis/branches/JDK8/application/sis-console/src/main/resources/META-INF/services/org.apache.sis.referencing.factory.sql.InstallationScriptProvider
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: sis/branches/JDK8/application/sis-console/src/main/resources/META-INF/services/org.apache.sis.referencing.factory.sql.InstallationScriptProvider
------------------------------------------------------------------------------
    svn:mime-type = text/plain;charset=UTF-8

Modified: sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/EPSGFactoryFallback.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/EPSGFactoryFallback.java?rev=1732973&r1=1732972&r2=1732973&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/EPSGFactoryFallback.java
[UTF-8] (original)
+++ sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/EPSGFactoryFallback.java
[UTF-8] Mon Feb 29 23:41:25 2016
@@ -34,6 +34,7 @@ import org.apache.sis.metadata.iso.citat
 import org.apache.sis.referencing.factory.GeodeticAuthorityFactory;
 import org.apache.sis.internal.referencing.provider.TransverseMercator;
 import org.apache.sis.internal.util.Constants;
+import org.apache.sis.internal.util.Fallback;
 import org.apache.sis.util.iso.SimpleInternationalString;
 import org.apache.sis.util.iso.DefaultNameSpace;
 import org.apache.sis.util.resources.Errors;
@@ -51,6 +52,7 @@ import org.apache.sis.util.Debug;
  * @version 0.7
  * @module
  */
+@Fallback
 final class EPSGFactoryFallback extends GeodeticAuthorityFactory implements CRSAuthorityFactory
{
     /**
      * Whether to disallow {@code CommonCRS} to use {@link org.apache.sis.referencing.factory.sql.EPSGFactory}

Modified: sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/factory/sql/EPSGInstaller.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/factory/sql/EPSGInstaller.java?rev=1732973&r1=1732972&r2=1732973&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/factory/sql/EPSGInstaller.java
[UTF-8] (original)
+++ sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/factory/sql/EPSGInstaller.java
[UTF-8] Mon Feb 29 23:41:25 2016
@@ -38,6 +38,7 @@ import org.apache.sis.util.CharSequences
 import org.apache.sis.util.resources.Messages;
 import org.apache.sis.util.logging.Logging;
 import org.apache.sis.util.logging.PerformanceLevel;
+import org.apache.sis.internal.util.Fallback;
 
 
 /**
@@ -265,12 +266,16 @@ final class EPSGInstaller extends Script
      * Searches for a SQL script provider on the classpath before to fallback on the default
provider.
      */
     private static InstallationScriptProvider lookupProvider() {
-        for (final InstallationScriptProvider p : ServiceLoader.load(InstallationScriptProvider.class))
{
-            if (Constants.EPSG.equals(p.getAuthority())) {
-                return p;
+        InstallationScriptProvider fallback = null;
+        for (final InstallationScriptProvider provider : ServiceLoader.load(InstallationScriptProvider.class))
{
+            if (Constants.EPSG.equals(provider.getAuthority())) {
+                if (provider.getClass().isAnnotationPresent(Fallback.class)) {
+                    return provider;
+                }
+                fallback = provider;
             }
         }
-        return new InstallationScriptProvider.Default();
+        return (fallback != null) ? fallback : new InstallationScriptProvider.Default();
     }
 
     /**

Modified: sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/factory/sql/InstallationScriptProvider.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/factory/sql/InstallationScriptProvider.java?rev=1732973&r1=1732972&r2=1732973&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/factory/sql/InstallationScriptProvider.java
[UTF-8] (original)
+++ sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/factory/sql/InstallationScriptProvider.java
[UTF-8] Mon Feb 29 23:41:25 2016
@@ -16,6 +16,7 @@
  */
 package org.apache.sis.referencing.factory.sql;
 
+import java.util.Locale;
 import java.sql.Connection;
 import java.io.BufferedReader;
 import java.io.LineNumberReader;
@@ -24,11 +25,11 @@ import java.io.InputStreamReader;
 import java.io.IOException;
 import java.io.FileNotFoundException;
 import java.nio.charset.Charset;
-import org.opengis.util.InternationalString;
-import org.apache.sis.internal.util.Constants;
 import org.apache.sis.util.resources.Errors;
 import org.apache.sis.util.ArgumentChecks;
+import org.apache.sis.setup.InstallationResources;
 import org.apache.sis.internal.system.DataDirectory;
+import org.apache.sis.internal.util.Constants;
 
 // Branch-dependent imports
 import java.nio.charset.StandardCharsets;
@@ -49,7 +50,7 @@ import java.nio.file.Path;
  *     META-INF/services/org.apache.sis.referencing.factory.sql.InstallationScriptProvider
  * }
  *
- * <div class="section">How this interface is used</div>
+ * <div class="section">How this class is used</div>
  * The first time that an {@link EPSGDataAccess} needs to be instantiated, {@link EPSGFactory}
verifies
  * if the EPSG database exists. If it does not, then:
  * <ol>
@@ -67,7 +68,7 @@ import java.nio.file.Path;
  * @version 0.7
  * @module
  */
-public abstract class InstallationScriptProvider {
+public abstract class InstallationScriptProvider extends InstallationResources {
     /**
      * A sentinel value for the content of the script to execute before the SQL scripts provided
by the authority.
      * This is an Apache SIS build-in script for constraining the values of some {@code VARCHAR}
columns
@@ -98,10 +99,12 @@ public abstract class InstallationScript
      *   <caption>Typical argument values</caption>
      *   <tr>
      *     <th>Authority</th>
-     *     <th>Argument</th>
+     *     <th class="sep">Argument values</th>
      *   </tr><tr>
      *     <td>{@code EPSG}</td>
-     *     <td><code>{@linkplain #PREPARE}, "EPSG_Tables.sql", "EPSG_Data.sql",
"EPSG_FKeys.sql", {@linkplain #FINISH}</code></td>
+     *     <td class="sep"><code>
+     *       {{@linkplain #PREPARE}, "EPSG_Tables.sql", "EPSG_Data.sql", "EPSG_FKeys.sql",
{@linkplain #FINISH}}
+     *     </code></td>
      *   </tr>
      * </table>
      *
@@ -117,15 +120,19 @@ public abstract class InstallationScript
 
     /**
      * Returns the identifier of the dataset installed by the SQL scripts.
-     * The values recognized by SIS are:
+     * The values recognized by SIS are listed below
+     * (note that this list may be expanded in future SIS versions if more authorities are
supported):
      *
      * <ul>
      *   <li>{@code "EPSG"}</li>
      * </ul>
      *
-     * The above list may be expanded in future SIS versions if more authorities are supported.
+     * SIS will ignore any {@code InstallationScriptProvider} instance
+     * for which {@code getAuthority()} returns a value not present in the above list.
+     * It is okay for example to return {@code "unavailable"} if the provider does not
+     * have the resources or the permission for returning the installation scripts.
      *
-     * @return {@code "EPSG"} or other authority acronym.
+     * @return {@code "EPSG"} or other value.
      */
     public abstract String getAuthority();
 
@@ -140,7 +147,8 @@ public abstract class InstallationScript
      * @return The terms of use in plain text or HTML, or {@code null} if none.
      * @throws IOException if an error occurred while reading the license file.
      */
-    public abstract InternationalString getLicense(String mimeType) throws IOException;
+    @Override
+    public abstract String getLicense(Locale locale, String mimeType) throws IOException;
 
     /**
      * Returns the names of all SQL scripts to execute.
@@ -148,8 +156,9 @@ public abstract class InstallationScript
      * Those names are often filenames, but not necessarily (they may be just labels).
      *
      * @return The names of all SQL scripts to execute.
+     * @throws IOException if fetching the script names required an I/O operation and that
operation failed.
      */
-    public String[] getScriptNames() {
+    public String[] getScriptNames() throws IOException {
         return names.clone();
     }
 
@@ -302,7 +311,7 @@ public abstract class InstallationScript
          * @return The terms of use in plain text or HTML, or {@code null} if the license
is presumed already accepted.
          */
         @Override
-        public InternationalString getLicense(String mimeType) {
+        public String getLicense(Locale locale, String mimeType) {
             return null;
         }
 

Modified: sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/factory/sql/package-info.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/factory/sql/package-info.java?rev=1732973&r1=1732972&r2=1732973&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/factory/sql/package-info.java
[UTF-8] (original)
+++ sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/factory/sql/package-info.java
[UTF-8] Mon Feb 29 23:41:25 2016
@@ -31,9 +31,9 @@
  * <ol>
  *   <li>If a {@linkplain javax.naming.InitialContext JNDI context} exists,
  *       the {@link javax.sql.DataSource} registered under the {@code "java:comp/env/jdbc/SpatialMetadata"}
name.</li>
- *   <li>If the {@code SIS_DATA} {@linkplain System#getenv(String) environment variable}
is defined,
+ *   <li>If the {@code SIS_DATA} {@linkplain java.lang.System#getenv(String) environment
variable} is defined,
  *       a JDBC connection for the {@code "jdbc:derby:$SIS_DATA/Databases/SpatialMetadata"}
URL.</li>
- *   <li>If the {@code "derby.system.home"} {@linkplain System#getProperty(String)
property} is defined,
+ *   <li>If the {@code "derby.system.home"} {@linkplain java.lang.System#getProperty(String)
property} is defined,
  *       a JDBC connection for the {@code "jdbc:derby:SpatialMetadata"} URL.</li>
  * </ol>
  *
@@ -67,10 +67,10 @@
  *
  * <ul>
  *   <li>Deprecated objects are not listed in the collection returned by the
- *       {@link org.apache.sis.referencing.factory.sql.EPSGDataAccess#getAuthorityCodes getAuthorityCodes(…)}
method.</li>
+ *       {@link org.apache.sis.referencing.factory.sql.EPSGDataAccess#getAuthorityCodes EPSGDataAccess.getAuthorityCodes(…)}
method.</li>
  *   <li>All method expecting an EPSG code in argument accept also the codes of deprecated
objects.</li>
- *   <li>If a deprecated object is created by a call to {@code createFoo(…)}, a warning
will be logged
- *       with a message proposing a replacement.</li>
+ *   <li>If a deprecated object is created by a call to {@code EPSGDataAccess.createFoo(…)},
+ *       a warning will be logged with a message proposing a replacement.</li>
  * </ul>
  *
  * @author  Martin Desruisseaux (IRD, Geomatys)

Added: sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/internal/util/Fallback.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/internal/util/Fallback.java?rev=1732973&view=auto
==============================================================================
--- sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/internal/util/Fallback.java
(added)
+++ sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/internal/util/Fallback.java
[UTF-8] Mon Feb 29 23:41:25 2016
@@ -0,0 +1,44 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.sis.internal.util;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+
+/**
+ * Controls the preferred service provider when there is more than
+ * one implementation of the same Service Provider Interface (SPI).
+ * Providers marked with this {@code Fallback} annotation will be used only if there is no
other provider.
+ * Service providers without this annotation are returned immediately, without scanning other
providers.
+ *
+ * <p>Providers without this annotation are assumed to have a priority of zero.</p>
+ *
+ * <p>This is not a committed API.
+ * The way Apache SIS selects its preferred service provider may change in any future version.</p>
+ *
+ * @author  Martin Desruisseaux (Geomatys)
+ * @since   0.7
+ * @version 0.7
+ * @module
+ */
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface Fallback {
+}

Propchange: sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/internal/util/Fallback.java
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/internal/util/Fallback.java
------------------------------------------------------------------------------
    svn:mime-type = text/plain;charset=UTF-8

Added: sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/setup/InstallationResources.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/setup/InstallationResources.java?rev=1732973&view=auto
==============================================================================
--- sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/setup/InstallationResources.java
(added)
+++ sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/setup/InstallationResources.java
[UTF-8] Mon Feb 29 23:41:25 2016
@@ -0,0 +1,61 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.sis.setup;
+
+import java.util.Locale;
+import java.io.IOException;
+
+
+/**
+ * Resources needed for installation of third-party or optional components.
+ * {@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>
+ * 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.
+ *
+ * <p>On the other hand, the <a href="http://www.epsg.org/">EPSG geodetic dataset</a>
is important for most users.
+ * Codes like {@code "EPSG:4326"} became a <i>de-facto</i> standard in various
places like <cite>Web Map Services</cite>,
+ * images encoded in GeoTIFF format, <i>etc</i>. But the <a href="http://www.epsg.org/TermsOfUse">EPSG
terms of use</a>
+ * are more restrictive than the Apache license and require that we inform the users about
those conditions.</p>
+ * </div>
+ *
+ * @author  Martin Desruisseaux (Geomatys)
+ * @since   0.7
+ * @version 0.7
+ * @module
+ */
+public abstract class InstallationResources {
+    /**
+     * For subclass constructors.
+     */
+    protected InstallationResources() {
+    }
+
+    /**
+     * Returns the terms of use of the resources, or {@code null} if none.
+     * The terms of use can be returned in either plain text or HTML.
+     *
+     * @param  locale The preferred locale for the terms of use.
+     * @param  mimeType Either {@code "text/plain"} or {@code "text/html"}.
+     * @return The terms of use in plain text or HTML, or {@code null} if none.
+     * @throws IOException if an error occurred while reading the license file.
+     */
+    public abstract String getLicense(Locale locale, String mimeType) throws IOException;
+}

Propchange: sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/setup/InstallationResources.java
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/setup/InstallationResources.java
------------------------------------------------------------------------------
    svn:mime-type = text/plain;charset=UTF-8

Modified: sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/setup/package-info.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/setup/package-info.java?rev=1732973&r1=1732972&r2=1732973&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/setup/package-info.java
[UTF-8] (original)
+++ sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/setup/package-info.java
[UTF-8] Mon Feb 29 23:41:25 2016
@@ -20,7 +20,7 @@
  *
  * @author  Martin Desruisseaux (Geomatys)
  * @since   0.3
- * @version 0.3
+ * @version 0.7
  * @module
  */
 package org.apache.sis.setup;



Mime
View raw message