sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1807187 - in /sis/branches/JDK8: core/sis-referencing/src/main/java/org/apache/sis/parameter/ core/sis-utility/src/main/java/org/apache/sis/internal/jaxb/gco/ core/sis-utility/src/main/java/org/apache/sis/internal/jaxb/gml/ core/sis-utilit...
Date Mon, 04 Sep 2017 01:14:08 GMT
Author: desruisseaux
Date: Mon Sep  4 01:14:07 2017
New Revision: 1807187

URL: http://svn.apache.org/viewvc?rev=1807187&view=rev
Log:
Javadoc update and adjustment in DataStoreProvider.open(ParameterValueGroup), including addition
of a specalized exception.

Added:
    sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/IllegalOpenParameterException.java
  (with props)
Modified:
    sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/parameter/DefaultParameterValue.java
    sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/internal/jaxb/gco/UnitAdapter.java
    sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/internal/jaxb/gml/CodeListUID.java
    sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/internal/util/DefinitionURI.java
    sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/xml/NilReason.java
    sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/xml/ReferenceResolver.java
    sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/Resources.java
    sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/Resources.properties
    sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/Resources_fr.properties
    sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/csv/Store.java
    sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/io/IOUtilities.java
    sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/wkt/FirstKeywordPeek.java
    sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/wkt/Store.java
    sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/xml/Store.java
    sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStoreProvider.java
    sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/UnsupportedStorageException.java
    sis/branches/JDK8/storage/sis-xmlstore/src/main/java/org/apache/sis/internal/storage/gpx/Link.java
    sis/branches/JDK8/storage/sis-xmlstore/src/main/java/org/apache/sis/internal/storage/xml/stream/StaxStreamReader.java

Modified: sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/parameter/DefaultParameterValue.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/parameter/DefaultParameterValue.java?rev=1807187&r1=1807186&r2=1807187&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/parameter/DefaultParameterValue.java
[UTF-8] (original)
+++ sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/parameter/DefaultParameterValue.java
[UTF-8] Mon Sep  4 01:14:07 2017
@@ -473,7 +473,7 @@ public class DefaultParameterValue<T> ex
      * {@link URI}, {@link URL}, {@link Path}, {@link File}.
      *
      * @return the reference to a file containing parameter values.
-     * @throws InvalidParameterTypeException if the value is not a reference to a file or
an URI.
+     * @throws InvalidParameterTypeException if the value is not a reference to a file or
a URI.
      * @throws IllegalStateException if the value is not defined and there is no default
value.
      *
      * @see #getValue()

Modified: sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/internal/jaxb/gco/UnitAdapter.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/internal/jaxb/gco/UnitAdapter.java?rev=1807187&r1=1807186&r2=1807187&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/internal/jaxb/gco/UnitAdapter.java
[UTF-8] (original)
+++ sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/internal/jaxb/gco/UnitAdapter.java
[UTF-8] Mon Sep  4 01:14:07 2017
@@ -66,7 +66,7 @@ public class UnitAdapter extends XmlAdap
     }
 
     /**
-     * A variant of {@link UnitAdapter} which marshal units as an URN for Coordinate System
(CS) axes.
+     * A variant of {@link UnitAdapter} which marshal units as a URN for Coordinate System
(CS) axes.
      * Example: {@code "urn:ogc:def:uom:EPSG::9001"}.
      *
      * The difference between coordinate system axis and other uses (prime meridian, etc.)
is in the choice of EPSG

Modified: sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/internal/jaxb/gml/CodeListUID.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/internal/jaxb/gml/CodeListUID.java?rev=1807187&r1=1807186&r2=1807187&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/internal/jaxb/gml/CodeListUID.java
[UTF-8] (original)
+++ sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/internal/jaxb/gml/CodeListUID.java
[UTF-8] Mon Sep  4 01:14:07 2017
@@ -32,7 +32,7 @@ import org.apache.sis.util.iso.Types;
  */
 public final class CodeListUID {
     /**
-     * The code space of the {@link #value} as an URI, or {@code null}.
+     * The code space of the {@link #value} as a URI, or {@code null}.
      */
     @XmlAttribute
     String codeSpace;

Modified: sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/internal/util/DefinitionURI.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/internal/util/DefinitionURI.java?rev=1807187&r1=1807186&r2=1807187&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/internal/util/DefinitionURI.java
[UTF-8] (original)
+++ sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/internal/util/DefinitionURI.java
[UTF-8] Mon Sep  4 01:14:07 2017
@@ -557,7 +557,7 @@ loop:   for (int p=0; ; p++) {
 
     /**
      * Returns a string representation of this URI. If the URI were originally a GML's URL,
then this method formats
-     * the URI in the {@code "http://www.opengis.net/gml/srs/"} namespace. Otherwise the
URI were originally an URL,
+     * the URI in the {@code "http://www.opengis.net/gml/srs/"} namespace. Otherwise the
URI were originally a URL,
      * then this method formats the URI in the {@code "http://www.opengis.net/"} namespace.
      * Otherwise this method formats the URI as a URN.
      *

Modified: sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/xml/NilReason.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/xml/NilReason.java?rev=1807187&r1=1807186&r2=1807187&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/xml/NilReason.java [UTF-8]
(original)
+++ sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/xml/NilReason.java [UTF-8]
Mon Sep  4 01:14:07 2017
@@ -145,7 +145,7 @@ public final class NilReason implements
 
     /**
      * Either the XML value as a {@code String} (including the explanation if the prefix
-     * is "{@code other}", or an {@link URI}.
+     * is "{@code other}", or a {@link URI}.
      */
     private final Object reason;
 

Modified: sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/xml/ReferenceResolver.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/xml/ReferenceResolver.java?rev=1807187&r1=1807186&r2=1807187&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/xml/ReferenceResolver.java
[UTF-8] (original)
+++ sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/xml/ReferenceResolver.java
[UTF-8] Mon Sep  4 01:14:07 2017
@@ -112,7 +112,7 @@ public class ReferenceResolver {
      * The default implementation performs the following lookups:
      *
      * <ul>
-     *   <li>If the {@link XLink#getHRef() xlink:href} attribute is an {@linkplain
URI#getFragment() URI fragment}
+     *   <li>If the {@link XLink#getHRef() xlink:href} attribute is a {@linkplain URI#getFragment()
URI fragment}
      *       of the form {@code "#foo"} and if an object of class {@code type} with the {@code
gml:id="foo"} attribute
      *       has previously been seen in the same XML document, then that object is returned.</li>
      *   <li>Otherwise returns {@code null}.</li>

Modified: sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/Resources.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/Resources.java?rev=1807187&r1=1807186&r2=1807187&view=diff
==============================================================================
--- sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/Resources.java
[UTF-8] (original)
+++ sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/Resources.java
[UTF-8] Mon Sep  4 01:14:07 2017
@@ -189,6 +189,11 @@ public final class Resources extends Ind
         public static final short StreamIsWriteOnce_1 = 21;
 
         /**
+         * Can not open {0} data store without “{1}” parameter.
+         */
+        public static final short UndefinedParameter_2 = 27;
+
+        /**
          * Format of “{0}” is not recognized.
          */
         public static final short UnknownFormatFor_1 = 14;

Modified: sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/Resources.properties
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/Resources.properties?rev=1807187&r1=1807186&r2=1807187&view=diff
==============================================================================
--- sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/Resources.properties
[ISO-8859-1] (original)
+++ sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/Resources.properties
[ISO-8859-1] Mon Sep  4 01:14:07 2017
@@ -44,4 +44,5 @@ StreamIsNotReadable_1             = Stre
 StreamIsNotWritable_1             = Stream \u201c{0}\u201d is not writable.
 StreamIsReadOnce_1                = The \u201c{0}\u201d data store can be read only once.
 StreamIsWriteOnce_1               = Can not modify previously written data in \u201c{0}\u201d.
+UndefinedParameter_2              = Can not open {0} data store without \u201c{1}\u201d parameter.
 UnknownFormatFor_1                = Format of \u201c{0}\u201d is not recognized.

Modified: sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/Resources_fr.properties
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/Resources_fr.properties?rev=1807187&r1=1807186&r2=1807187&view=diff
==============================================================================
--- sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/Resources_fr.properties
[ISO-8859-1] (original)
+++ sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/Resources_fr.properties
[ISO-8859-1] Mon Sep  4 01:14:07 2017
@@ -49,4 +49,5 @@ StreamIsNotReadable_1             = Les
 StreamIsNotWritable_1             = Le flux de donn\u00e9es \u00ab\u202f{0}\u202f\u00bb ne
g\u00e8re pas les \u00e9critures.
 StreamIsReadOnce_1                = Les donn\u00e9es de \u00ab\u202f{0}\u202f\u00bb ne peuvent
\u00eatre lues qu\u2019une seule fois.
 StreamIsWriteOnce_1               = Ne peut pas revenir sur les donn\u00e9es d\u00e9j\u00e0
\u00e9crites dans \u00ab\u202f{0}\u202f\u00bb.
+UndefinedParameter_2              = Ne peut pas ouvrir une source de donn\u00e9es {0} sans
le param\u00e8tre \u00ab\u202f{1}\u202f\u00bb.
 UnknownFormatFor_1                = Le format de \u00ab\u202f{0}\u202f\u00bb n\u2019est pas
reconnu.

Modified: sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/csv/Store.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/csv/Store.java?rev=1807187&r1=1807186&r2=1807187&view=diff
==============================================================================
--- sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/csv/Store.java
[UTF-8] (original)
+++ sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/csv/Store.java
[UTF-8] Mon Sep  4 01:14:07 2017
@@ -56,6 +56,7 @@ import org.apache.sis.storage.DataStore;
 import org.apache.sis.storage.DataStoreException;
 import org.apache.sis.storage.DataStoreContentException;
 import org.apache.sis.storage.DataStoreReferencingException;
+import org.apache.sis.storage.UnsupportedStorageException;
 import org.apache.sis.storage.StorageConnector;
 import org.apache.sis.setup.OptionKey;
 import org.apache.sis.util.ArraysExt;
@@ -239,7 +240,8 @@ public final class Store extends DataSto
         }
         connector.closeAllExcept(r);
         if (r == null) {
-            throw new DataStoreException(Errors.format(Errors.Keys.CanNotOpen_1, super.getDisplayName()));
+            throw new UnsupportedStorageException(super.getLocale(), "CSV",
+                    connector.getStorage(), connector.getOption(OptionKey.OPEN_OPTIONS));
         }
         source = (r instanceof BufferedReader) ? (BufferedReader) r : new LineNumberReader(r);
         geometries = Geometries.implementation(connector.getOption(OptionKey.GEOMETRY_LIBRARY));

Modified: sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/io/IOUtilities.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/io/IOUtilities.java?rev=1807187&r1=1807186&r2=1807187&view=diff
==============================================================================
--- sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/io/IOUtilities.java
[UTF-8] (original)
+++ sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/io/IOUtilities.java
[UTF-8] Mon Sep  4 01:14:07 2017
@@ -237,7 +237,7 @@ public final class IOUtilities extends S
             return null;
         }
         /*
-         * Convert the URL to an URI, taking in account the encoding if any.
+         * Convert the URL to a URI, taking in account the encoding if any.
          *
          * Note: URL.toURI() is implemented as new URI(URL.toString()) where toString()
          * delegates to toExternalForm(), and all those methods are final. So we really

Modified: sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/wkt/FirstKeywordPeek.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/wkt/FirstKeywordPeek.java?rev=1807187&r1=1807186&r2=1807187&view=diff
==============================================================================
--- sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/wkt/FirstKeywordPeek.java
[UTF-8] (original)
+++ sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/wkt/FirstKeywordPeek.java
[UTF-8] Mon Sep  4 01:14:07 2017
@@ -42,6 +42,7 @@ public abstract class FirstKeywordPeek {
 
     /**
      * The read-ahead limit when reading a text from a {@link Reader}.
+     * Should be no more than {@code StorageConnector.DEFAULT_BUFFER_SIZE / 2}.
      */
     static final int READ_AHEAD_LIMIT = 2048;
 
@@ -188,7 +189,7 @@ public abstract class FirstKeywordPeek {
     }
 
     /**
-     * Returns {@code true} if the given first non-white character after the keywordis one
of the expected characters.
+     * Returns {@code true} if the given first non-white character after the keyword is one
of the expected characters.
      *
      * @param  c  the first non-white character after the keyword, or -1 if we reached the
end of stream.
      * @return {@code true} if the given character is one of the expected post-keyword characters.

Modified: sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/wkt/Store.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/wkt/Store.java?rev=1807187&r1=1807186&r2=1807187&view=diff
==============================================================================
--- sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/wkt/Store.java
[UTF-8] (original)
+++ sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/wkt/Store.java
[UTF-8] Mon Sep  4 01:14:07 2017
@@ -30,6 +30,7 @@ import org.opengis.metadata.Metadata;
 import org.opengis.util.FactoryException;
 import org.opengis.referencing.ReferenceSystem;
 import org.opengis.referencing.crs.CoordinateReferenceSystem;
+import org.opengis.parameter.ParameterValueGroup;
 import org.apache.sis.internal.storage.Resources;
 import org.apache.sis.internal.system.Loggers;
 import org.apache.sis.io.wkt.WKTFormat;
@@ -39,12 +40,12 @@ import org.apache.sis.storage.DataStore;
 import org.apache.sis.storage.StorageConnector;
 import org.apache.sis.storage.DataStoreException;
 import org.apache.sis.storage.DataStoreContentException;
+import org.apache.sis.storage.UnsupportedStorageException;
 import org.apache.sis.internal.referencing.DefinitionVerifier;
 import org.apache.sis.internal.storage.MetadataBuilder;
 import org.apache.sis.parameter.Parameters;
-import org.apache.sis.util.resources.Errors;
+import org.apache.sis.setup.OptionKey;
 import org.apache.sis.util.CharSequences;
-import org.opengis.parameter.ParameterValueGroup;
 
 
 /**
@@ -98,7 +99,8 @@ final class Store extends DataStore {
         }
         connector.closeAllExcept(source);
         if (source == null) {
-            throw new DataStoreException(Errors.format(Errors.Keys.CanNotOpen_1, super.getDisplayName()));
+            throw new UnsupportedStorageException(super.getLocale(), "WKT",
+                    connector.getStorage(), connector.getOption(OptionKey.OPEN_OPTIONS));
         }
     }
 

Modified: sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/xml/Store.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/xml/Store.java?rev=1807187&r1=1807186&r2=1807187&view=diff
==============================================================================
--- sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/xml/Store.java
[UTF-8] (original)
+++ sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/xml/Store.java
[UTF-8] Mon Sep  4 01:14:07 2017
@@ -30,11 +30,13 @@ import org.opengis.metadata.Metadata;
 import org.opengis.util.FactoryException;
 import org.opengis.referencing.ReferenceSystem;
 import org.opengis.referencing.crs.CoordinateReferenceSystem;
+import org.opengis.parameter.ParameterValueGroup;
 import org.apache.sis.xml.XML;
 import org.apache.sis.storage.Resource;
 import org.apache.sis.storage.DataStore;
 import org.apache.sis.storage.StorageConnector;
 import org.apache.sis.storage.DataStoreException;
+import org.apache.sis.storage.UnsupportedStorageException;
 import org.apache.sis.metadata.iso.DefaultMetadata;
 import org.apache.sis.util.logging.WarningListener;
 import org.apache.sis.util.resources.Errors;
@@ -42,7 +44,7 @@ import org.apache.sis.internal.system.Lo
 import org.apache.sis.internal.storage.MetadataBuilder;
 import org.apache.sis.internal.referencing.DefinitionVerifier;
 import org.apache.sis.parameter.Parameters;
-import org.opengis.parameter.ParameterValueGroup;
+import org.apache.sis.setup.OptionKey;
 
 
 /**
@@ -106,7 +108,8 @@ final class Store extends DataStore {
         final Closeable c = input(source);
         connector.closeAllExcept(c);
         if (c == null) {
-            throw new DataStoreException(Errors.format(Errors.Keys.CanNotOpen_1, super.getDisplayName()));
+            throw new UnsupportedStorageException(super.getLocale(), "XML",
+                    connector.getStorage(), connector.getOption(OptionKey.OPEN_OPTIONS));
         }
     }
 

Modified: sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStoreProvider.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStoreProvider.java?rev=1807187&r1=1807186&r2=1807187&view=diff
==============================================================================
--- sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStoreProvider.java
[UTF-8] (original)
+++ sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStoreProvider.java
[UTF-8] Mon Sep  4 01:14:07 2017
@@ -16,17 +16,17 @@
  */
 package org.apache.sis.storage;
 
+import org.opengis.parameter.ParameterValueGroup;
+import org.opengis.parameter.ParameterDescriptorGroup;
+import org.opengis.parameter.ParameterNotFoundException;
 import org.opengis.metadata.distribution.Format;
 import org.apache.sis.internal.simple.SimpleFormat;
+import org.apache.sis.internal.storage.Resources;
 import org.apache.sis.metadata.iso.citation.DefaultCitation;
 import org.apache.sis.metadata.iso.distribution.DefaultFormat;
 import org.apache.sis.measure.Range;
 import org.apache.sis.util.ArgumentChecks;
 import org.apache.sis.util.Version;
-import org.opengis.parameter.ParameterDescriptorGroup;
-import org.opengis.parameter.ParameterNotFoundException;
-import org.opengis.parameter.ParameterValue;
-import org.opengis.parameter.ParameterValueGroup;
 
 
 /**
@@ -57,24 +57,28 @@ import org.opengis.parameter.ParameterVa
  * However the {@code DataStore} instances created by the providers do not need to be thread-safe.
  *
  * @author  Martin Desruisseaux (Geomatys)
+ * @author  Johann Sorel (Geomatys)
  * @version 0.8
  * @since   0.3
  * @module
  */
 public abstract class DataStoreProvider {
-
     /**
-     * Name of the parameter used to create StorageConnector instances.
+     * Name of the parameter that specifies the data store location.
+     * A parameter named {@value} should be included in the group of parameters returned
by {@link #getOpenParameters()}.
+     * The parameter value is often a {@link java.net.URI} or a {@link java.nio.file.Path},
but other types are allowed.
      *
      * <p>Implementors are encouraged to define a parameter with this name
      * to ensure a common and consistent definition among providers.
-     * The parameter should be defined as mandatory and declared with a
-     * very common java class such as URI, Path, stream, JDBC connection, <i>etc</i>.
-     * </p>
+     * The parameter should be defined as mandatory and declared with a well-known Java class
such as
+     * {@link java.net.URI}, {@link java.nio.file.Path}, JDBC {@linkplain javax.sql.DataSource},
<i>etc</i>.
+     * The type should have a compact textual representation, for serialization in XML or
configuration files.
+     * Consequently {@link java.io.InputStream} and {@link java.nio.channels.Channel} should
be avoided.</p>
+     *
+     * @see #getOpenParameters()
      */
     public static final String LOCATION = "location";
 
-
     /**
      * Creates a new provider.
      */
@@ -148,18 +152,31 @@ public abstract class DataStoreProvider
     }
 
     /**
-     * Returns a description of all opening parameters accepted by this provider.
-     *
-     * <p>Implementors are responsible for declaring all parameters and there mandatory
states.
-     * It is recommended to use at least the LOCATION parameter name. This parameter will
-     * be recognized by the default datastore provider methods and used whenever a
+     * Returns a description of all parameters accepted by this provider for opening a data
store.
+     * Those parameters provide an alternative to {@link StorageConnector} for opening a
{@link DataStore}
+     * from a path or URL, together with additional information like character encoding.
+     *
+     * <p>Implementors are responsible for declaring all parameters and whether they
are mandatory or optional.
+     * It is recommended to define at least a parameter named {@value #LOCATION}.
+     * That parameter will be recognized by the default {@code DataStoreProvider} methods
and used whenever a
      * {@link StorageConnector} is required.</p>
      *
-     * <p>This description can be used to dynamically generate user configuration interfaces
-     * and provide fine grain control over the store general behavior such as caching,
-     * time-outs, encoding, <i>etc</i>.</p>
+     * <div class="note"><b>Alternative:</b>
+     * the main differences between the use of {@code StorageConnector} and parameters are:
+     * <ul class="verbose">
+     *   <li>{@code StorageConnector} is designed for use with file or stream of unknown
format;
+     *       the format is automatically detected. By contrast, the use of parameters require
to
+     *       determine the format first (i.e. select a {@code DataStoreProvider}).</li>
+     *   <li>Parameters can be used to dynamically generate user configuration interfaces
+     *       and provide fine grain control over the store general behavior such as caching,
+     *       time-outs, encoding, <i>etc</i>.</li>
+     *   <li>Parameters can more easily be serialized in XML or configuration files.</li>
+     * </ul></div>
+     *
+     * @return description of the parameters required for opening a {@link DataStore}.
      *
-     * @return Description of the parameters required for opening a {@link org.apache.sis.storage.DataStore}.
+     * @see #open(ParameterValueGroup)
+     * @see DataStore#getOpenParameters()
      */
     public abstract ParameterDescriptorGroup getOpenParameters();
 
@@ -221,6 +238,10 @@ public abstract class DataStoreProvider
 
     /**
      * Returns a data store implementation associated with this provider.
+     * This method is typically invoked when the format is not known in advance
+     * (the {@link #probeContent(StorageConnector)} method can be tested on many providers)
+     * or when the input is not a type accepted by {@link #open(ParameterValueGroup)}
+     * (for example an {@link java.io.InputStream}).
      *
      * <div class="section">Implementation note</div>
      * Implementors shall invoke {@link StorageConnector#closeAllExcept(Object)} after {@code
DataStore}
@@ -235,33 +256,46 @@ public abstract class DataStoreProvider
     public abstract DataStore open(StorageConnector connector) throws DataStoreException;
 
     /**
-     * Returns a data store implementation associated with this provider.
+     * Returns a data store implementation associated with this provider for the given parameters.
+     * The {@code DataStoreProvider} instance needs to be known before parameters are initialized,
+     * since the parameters are implementation-dependent. Example:
      *
-     * <div class="section">Implementation note</div>
-     * Implementors shall invoke {@link StorageConnector#closeAllExcept(Object)} after {@code
DataStore}
-     * creation, keeping open only the needed resource.
+     * {@preformat java
+     *     DataStoreProvider provider = ...;
+     *     ParameterValueGroup pg = provider.getOpenParameters().createValue();
+     *     pg.parameter(DataStoreProvider.LOCATION, myURL);
+     *     // Set any other parameters if desired.
+     *     try (DataStore ds = provider.open(pg)) {
+     *         // Use the data store.
+     *     }
+     * }
      *
      * <div class="section">Implementation note</div>
-     * The default implementation of this method searches for the {@link #LOCATION} parameter
-     * to create a StorageConnector which is then passed to {@link #open(org.apache.sis.storage.StorageConnector)
}.
+     * The default implementation gets the value of a parameter named {@value #LOCATION}.
+     * That value (typically a path or URL) is given to {@link StorageConnector} constructor,
+     * which is then passed to {@link #open(StorageConnector)}.
      *
-     * @param  parameters opening parameters as defined by {@link #getOpenParameters() }
-     * @return a data store implementation associated with this provider for the given storage.
+     * @param  parameters  opening parameters as defined by {@link #getOpenParameters()}.
+     * @return a data store implementation associated with this provider for the given parameters.
      * @throws DataStoreException if an error occurred while creating the data store instance.
      *
-     * @see DataStores#open(Object)
+     * @see #getOpenParameters()
      */
-    public DataStore open(ParameterValueGroup parameters) throws DataStoreException {
+    public DataStore open(final ParameterValueGroup parameters) throws DataStoreException
{
         ArgumentChecks.ensureNonNull("parameter", parameters);
-
-        final ParameterValue<?> locationParameter;
+        ParameterNotFoundException cause = null;
+        Object location;
         try {
-            locationParameter = parameters.parameter(LOCATION);
-        } catch (ParameterNotFoundException ex) {
-            throw new DataStoreException("Location parameter not defined.",ex);
+            location = parameters.parameter(LOCATION).getValue();
+        } catch (ParameterNotFoundException e) {
+            location = null;
+            cause = e;
         }
-        final StorageConnector connector = new StorageConnector(locationParameter.getValue());
+        if (location == null) {
+            throw new IllegalOpenParameterException(Resources.format(Resources.Keys.UndefinedParameter_2,
+                    getShortName(), LOCATION), cause);
+        }
+        final StorageConnector connector = new StorageConnector(location);
         return open(connector);
     }
-
 }

Added: sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/IllegalOpenParameterException.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/IllegalOpenParameterException.java?rev=1807187&view=auto
==============================================================================
--- sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/IllegalOpenParameterException.java
(added)
+++ sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/IllegalOpenParameterException.java
[UTF-8] Mon Sep  4 01:14:07 2017
@@ -0,0 +1,67 @@
+/*
+ * 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.storage;
+
+
+/**
+ * Thrown when a {@code DataStore} can not be opened because of invalid parameters.
+ *
+ * @author  Martin Desruisseaux (Geomatys)
+ * @version 0.8
+ * @since   0.8
+ * @module
+ */
+public class IllegalOpenParameterException extends DataStoreException {
+    /**
+     * For cross-version compatibility.
+     */
+    private static final long serialVersionUID = 8167257397599018311L;
+
+    /**
+     * Creates an exception with no cause and no details message.
+     */
+    public IllegalOpenParameterException() {
+    }
+
+    /**
+     * Creates an exception with the specified details message.
+     *
+     * @param message  the detail message.
+     */
+    public IllegalOpenParameterException(final String message) {
+        super(message);
+    }
+
+    /**
+     * Creates an exception with the specified cause and no details message.
+     *
+     * @param cause  the cause for this exception.
+     */
+    public IllegalOpenParameterException(final Throwable cause) {
+        super(cause);
+    }
+
+    /**
+     * Creates an exception with the specified details message and cause.
+     *
+     * @param message  the detail message.
+     * @param cause    the cause for this exception.
+     */
+    public IllegalOpenParameterException(final String message, final Throwable cause) {
+        super(message, cause);
+    }
+}

Propchange: sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/IllegalOpenParameterException.java
------------------------------------------------------------------------------
    svn:eol-style = native

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

Modified: sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/UnsupportedStorageException.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/UnsupportedStorageException.java?rev=1807187&r1=1807186&r2=1807187&view=diff
==============================================================================
--- sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/UnsupportedStorageException.java
[UTF-8] (original)
+++ sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/UnsupportedStorageException.java
[UTF-8] Mon Sep  4 01:14:07 2017
@@ -25,8 +25,8 @@ import org.apache.sis.internal.storage.i
 
 /**
  * Thrown when no {@link DataStoreProvider} is found for a given storage object.
- * May also be thrown if a {@code DataStore} is instantiated directly (without {@code DataStoreProvider}
- * for verifying the input) but the data store can not handle the given input or output object.
+ * May also be thrown if a {@code DataStore} is instantiated directly but the data store
+ * can not handle the given input or output object.
  *
  * @author  Martin Desruisseaux (Geomatys)
  * @version 0.8

Modified: sis/branches/JDK8/storage/sis-xmlstore/src/main/java/org/apache/sis/internal/storage/gpx/Link.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/storage/sis-xmlstore/src/main/java/org/apache/sis/internal/storage/gpx/Link.java?rev=1807187&r1=1807186&r2=1807187&view=diff
==============================================================================
--- sis/branches/JDK8/storage/sis-xmlstore/src/main/java/org/apache/sis/internal/storage/gpx/Link.java
[UTF-8] (original)
+++ sis/branches/JDK8/storage/sis-xmlstore/src/main/java/org/apache/sis/internal/storage/gpx/Link.java
[UTF-8] Mon Sep  4 01:14:07 2017
@@ -116,7 +116,7 @@ public final class Link implements Onlin
      *   </link>
      * }
      *
-     * If we fail to convert the text to an URI, we will leave the object state as-is.
+     * If we fail to convert the text to a URI, we will leave the object state as-is.
      */
     final void afterUnmarshal(Unmarshaller um, Object parent) {
         if (uri == null && text != null) {

Modified: sis/branches/JDK8/storage/sis-xmlstore/src/main/java/org/apache/sis/internal/storage/xml/stream/StaxStreamReader.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/storage/sis-xmlstore/src/main/java/org/apache/sis/internal/storage/xml/stream/StaxStreamReader.java?rev=1807187&r1=1807186&r2=1807187&view=diff
==============================================================================
--- sis/branches/JDK8/storage/sis-xmlstore/src/main/java/org/apache/sis/internal/storage/xml/stream/StaxStreamReader.java
[UTF-8] (original)
+++ sis/branches/JDK8/storage/sis-xmlstore/src/main/java/org/apache/sis/internal/storage/xml/stream/StaxStreamReader.java
[UTF-8] Mon Sep  4 01:14:07 2017
@@ -332,12 +332,12 @@ public abstract class StaxStreamReader e
     }
 
     /**
-     * Returns the current value of {@link XMLStreamReader#getElementText()} as an URI,
+     * Returns the current value of {@link XMLStreamReader#getElementText()} as a URI,
      * or {@code null} if that value is null or empty.
      *
-     * @return the current text element as an URI, or {@code null} if empty.
+     * @return the current text element as a URI, or {@code null} if empty.
      * @throws XMLStreamException if a text element can not be returned.
-     * @throws URISyntaxException if the text can not be parsed as an URI.
+     * @throws URISyntaxException if the text can not be parsed as a URI.
      */
     protected final URI getElementAsURI() throws XMLStreamException, URISyntaxException {
         final Context context = Context.current();



Mime
View raw message