You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sis.apache.org by de...@apache.org on 2019/09/14 12:15:26 UTC

[sis] 03/03: Clarification about whether a DataStore.getFoo() method can return null. Contain one last-minute API change before 1.0 release: getOpenParameters() return Optional.

This is an automated email from the ASF dual-hosted git repository.

desruisseaux pushed a commit to branch 1.0-RC
in repository https://gitbox.apache.org/repos/asf/sis.git

commit 04e45b87ecd8f8169d28e6197fc281e24577e6ff
Author: Martin Desruisseaux <ma...@geomatys.com>
AuthorDate: Sat Sep 14 14:14:49 2019 +0200

    Clarification about whether a DataStore.getFoo() method can return null.
    Contain one last-minute API change before 1.0 release: getOpenParameters() return Optional.
---
 .../sis/storage/earthobservation/LandsatStore.java | 27 +++++++++++++---------
 .../apache/sis/storage/geotiff/GeoTiffStore.java   | 12 +++++-----
 .../org/apache/sis/storage/netcdf/NetcdfStore.java |  6 ++---
 .../java/org/apache/sis/storage/sql/SQLStore.java  |  6 ++---
 .../apache/sis/internal/storage/URIDataStore.java  |  7 +++---
 .../apache/sis/internal/storage/folder/Store.java  |  4 ++--
 .../java/org/apache/sis/storage/DataStore.java     | 14 +++++++----
 .../org/apache/sis/storage/DataStoreProvider.java  |  2 +-
 .../java/org/apache/sis/storage/DataStoreMock.java |  7 +++---
 9 files changed, 48 insertions(+), 37 deletions(-)

diff --git a/storage/sis-earth-observation/src/main/java/org/apache/sis/storage/earthobservation/LandsatStore.java b/storage/sis-earth-observation/src/main/java/org/apache/sis/storage/earthobservation/LandsatStore.java
index 02bcaf6..770b330 100644
--- a/storage/sis-earth-observation/src/main/java/org/apache/sis/storage/earthobservation/LandsatStore.java
+++ b/storage/sis-earth-observation/src/main/java/org/apache/sis/storage/earthobservation/LandsatStore.java
@@ -20,6 +20,7 @@ import java.io.Reader;
 import java.io.BufferedReader;
 import java.io.LineNumberReader;
 import java.io.IOException;
+import java.nio.file.StandardOpenOption;
 import java.net.URI;
 import java.util.Optional;
 import org.opengis.metadata.Metadata;
@@ -28,6 +29,7 @@ import org.opengis.util.FactoryException;
 import org.opengis.parameter.ParameterValueGroup;
 import org.apache.sis.storage.DataStore;
 import org.apache.sis.storage.DataStoreException;
+import org.apache.sis.storage.DataStoreClosedException;
 import org.apache.sis.storage.DataStoreReferencingException;
 import org.apache.sis.storage.UnsupportedStorageException;
 import org.apache.sis.storage.StorageConnector;
@@ -114,18 +116,18 @@ public class LandsatStore extends DataStore {
 
     /**
      * Returns the parameters used to open this Landsat data store.
-     * If non-null, the parameters are described by {@link LandsatStoreProvider#getOpenParameters()} and contains at
-     * least a parameter named {@value org.apache.sis.storage.DataStoreProvider#LOCATION} with a {@link URI} value.
-     * This method may return {@code null} if the storage input can not be described by a URI
+     * The parameters are described by {@link LandsatStoreProvider#getOpenParameters()} and contains at least
+     * a parameter named {@value org.apache.sis.storage.DataStoreProvider#LOCATION} with a {@link URI} value.
+     * The return value may be empty if the storage input can not be described by a URI
      * (for example a Landsat file reading directly from a {@link java.nio.channels.ReadableByteChannel}).
      *
-     * @return parameters used for opening this data store, or {@code null} if not available.
+     * @return parameters used for opening this data store.
      *
      * @since 0.8
      */
     @Override
-    public ParameterValueGroup getOpenParameters() {
-        return URIDataStore.parameters(provider, location);
+    public Optional<ParameterValueGroup> getOpenParameters() {
+        return Optional.ofNullable(URIDataStore.parameters(provider, location));
     }
 
     /**
@@ -156,17 +158,20 @@ public class LandsatStore extends DataStore {
      */
     @Override
     public synchronized Metadata getMetadata() throws DataStoreException {
-        if (metadata == null && source != null) try {
+        if (metadata == null) {
+            if (source == null) {
+                throw new DataStoreClosedException(getLocale(), LandsatStoreProvider.NAME, StandardOpenOption.READ);
+            }
             try (BufferedReader reader = (source instanceof BufferedReader) ? (BufferedReader) source : new LineNumberReader(source)) {
                 source = null;      // Will be closed at the end of this try-finally block.
                 final LandsatReader parser = new LandsatReader(getDisplayName(), listeners);
                 parser.read(reader);
                 metadata = parser.getMetadata();
+            } catch (IOException e) {
+                throw new DataStoreException(e);
+            } catch (FactoryException e) {
+                throw new DataStoreReferencingException(e);
             }
-        } catch (IOException e) {
-            throw new DataStoreException(e);
-        } catch (FactoryException e) {
-            throw new DataStoreReferencingException(e);
         }
         return metadata;
     }
diff --git a/storage/sis-geotiff/src/main/java/org/apache/sis/storage/geotiff/GeoTiffStore.java b/storage/sis-geotiff/src/main/java/org/apache/sis/storage/geotiff/GeoTiffStore.java
index 3778951..a3707ea 100644
--- a/storage/sis-geotiff/src/main/java/org/apache/sis/storage/geotiff/GeoTiffStore.java
+++ b/storage/sis-geotiff/src/main/java/org/apache/sis/storage/geotiff/GeoTiffStore.java
@@ -154,16 +154,16 @@ public class GeoTiffStore extends DataStore implements Aggregate {
 
     /**
      * Returns the parameters used to open this GeoTIFF data store.
-     * If non-null, the parameters are described by {@link GeoTiffStoreProvider#getOpenParameters()} and contains at
-     * least a parameter named {@value org.apache.sis.storage.DataStoreProvider#LOCATION} with a {@link URI} value.
-     * This method may return {@code null} if the storage input can not be described by a URI
+     * The parameters are described by {@link GeoTiffStoreProvider#getOpenParameters()} and contains at least
+     * a parameter named {@value org.apache.sis.storage.DataStoreProvider#LOCATION} with a {@link URI} value.
+     * The return value may be empty if the storage input can not be described by a URI
      * (for example a GeoTIFF file reading directly from a {@link java.nio.channels.ReadableByteChannel}).
      *
-     * @return parameters used for opening this data store, or {@code null} if not available.
+     * @return parameters used for opening this data store.
      */
     @Override
-    public ParameterValueGroup getOpenParameters() {
-        return URIDataStore.parameters(provider, location);
+    public Optional<ParameterValueGroup> getOpenParameters() {
+        return Optional.ofNullable(URIDataStore.parameters(provider, location));
     }
 
     /**
diff --git a/storage/sis-netcdf/src/main/java/org/apache/sis/storage/netcdf/NetcdfStore.java b/storage/sis-netcdf/src/main/java/org/apache/sis/storage/netcdf/NetcdfStore.java
index 6094911..afaf805 100644
--- a/storage/sis-netcdf/src/main/java/org/apache/sis/storage/netcdf/NetcdfStore.java
+++ b/storage/sis-netcdf/src/main/java/org/apache/sis/storage/netcdf/NetcdfStore.java
@@ -129,13 +129,13 @@ public class NetcdfStore extends DataStore implements Aggregate {
      * This method may return {@code null} if the storage input can not be described by a URI
      * (for example a netCDF file reading directly from a {@link java.nio.channels.ReadableByteChannel}).
      *
-     * @return parameters used for opening this data store, or {@code null} if not available.
+     * @return parameters used for opening this data store.
      *
      * @since 0.8
      */
     @Override
-    public ParameterValueGroup getOpenParameters() {
-        return URIDataStore.parameters(provider, location);
+    public Optional<ParameterValueGroup> getOpenParameters() {
+        return Optional.ofNullable(URIDataStore.parameters(provider, location));
     }
 
     /**
diff --git a/storage/sis-sqlstore/src/main/java/org/apache/sis/storage/sql/SQLStore.java b/storage/sis-sqlstore/src/main/java/org/apache/sis/storage/sql/SQLStore.java
index 4ecf249..67a7c0d 100644
--- a/storage/sis-sqlstore/src/main/java/org/apache/sis/storage/sql/SQLStore.java
+++ b/storage/sis-sqlstore/src/main/java/org/apache/sis/storage/sql/SQLStore.java
@@ -135,14 +135,14 @@ public class SQLStore extends DataStore implements Aggregate {
      * @return parameters used for opening this data store.
      */
     @Override
-    public ParameterValueGroup getOpenParameters() {
+    public Optional<ParameterValueGroup> getOpenParameters() {
         if (provider == null) {
-            return null;
+            return Optional.empty();
         }
         final ParameterValueGroup pg = provider.getOpenParameters().createValue();
         pg.parameter(SQLStoreProvider.LOCATION).setValue(source);
         pg.parameter(SQLStoreProvider.TABLES).setValue(tableNames);
-        return pg;
+        return Optional.of(pg);
     }
 
     /**
diff --git a/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/URIDataStore.java b/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/URIDataStore.java
index 26525c3..069e503 100644
--- a/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/URIDataStore.java
+++ b/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/URIDataStore.java
@@ -17,6 +17,7 @@
 package org.apache.sis.internal.storage;
 
 import java.net.URI;
+import java.util.Optional;
 import java.nio.file.Path;
 import java.nio.file.Paths;
 import java.nio.file.FileSystemNotFoundException;
@@ -103,11 +104,11 @@ public abstract class URIDataStore extends DataStore implements StoreResource, R
     /**
      * Returns the parameters used to open this data store.
      *
-     * @return parameters used for opening this {@code DataStore}, or {@code null} if not available.
+     * @return parameters used for opening this {@code DataStore}.
      */
     @Override
-    public ParameterValueGroup getOpenParameters() {
-        return parameters(provider, location);
+    public Optional<ParameterValueGroup> getOpenParameters() {
+        return Optional.ofNullable(parameters(provider, location));
     }
 
     /**
diff --git a/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/folder/Store.java b/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/folder/Store.java
index a147a4e..d331551 100644
--- a/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/folder/Store.java
+++ b/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/folder/Store.java
@@ -210,7 +210,7 @@ class Store extends DataStore implements StoreResource, Aggregate, DirectoryStre
      * Returns the parameters used to open this data store.
      */
     @Override
-    public ParameterValueGroup getOpenParameters() {
+    public Optional<ParameterValueGroup> getOpenParameters() {
         final String format = StoreUtilities.getFormatName(componentProvider);
         final ParameterValueGroup pg = (provider != null ? provider.getOpenParameters() : FolderStoreProvider.PARAMETERS).createValue();
         pg.parameter(DataStoreProvider.LOCATION).setValue(location);
@@ -218,7 +218,7 @@ class Store extends DataStore implements StoreResource, Aggregate, DirectoryStre
         if (timezone != null) pg.parameter("timezone").setValue(timezone);
         if (encoding != null) pg.parameter("encoding").setValue(encoding);
         if (format   != null) pg.parameter("format"  ).setValue(format);
-        return pg;
+        return Optional.of(pg);
     }
 
     /**
diff --git a/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStore.java b/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStore.java
index 3c258c6..9eb0c0f 100644
--- a/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStore.java
+++ b/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStore.java
@@ -121,7 +121,7 @@ public abstract class DataStore implements Resource, Localized, AutoCloseable {
 
     /**
      * Creates a new instance for the given storage (typically file or database).
-     * The {@code provider} argument is an optional information.
+     * The {@code provider} argument is an optional but recommended information.
      * The {@code connector} argument is mandatory.
      *
      * @param  provider   the factory that created this {@code DataStore} instance, or {@code null} if unspecified.
@@ -175,6 +175,10 @@ public abstract class DataStore implements Resource, Localized, AutoCloseable {
      * The provider gives additional information on this {@code DataStore} such as a format description
      * and a list of parameters that can be used for opening data stores of the same class.
      *
+     * <p>The return value should never be null if this {@code DataStore} has been created by
+     * {@link DataStores#open(Object)} or by a {@link DataStoreProvider} {@code open(…)} method.
+     * However it may be null if this object has been instantiated by a direct call to its constructor.</p>
+     *
      * @return the factory that created this {@code DataStore} instance, or {@code null} if unspecified.
      *
      * @see #provider
@@ -198,15 +202,15 @@ public abstract class DataStore implements Resource, Localized, AutoCloseable {
      *
      * <p>In some cases, for stores reading in-memory data or other inputs that can not fit with
      * {@code ParameterDescriptorGroup} requirements (for example an {@link java.io.InputStream}
-     * connected to unknown or no {@link java.net.URL}), this method may return null.</p>
+     * connected to unknown or no {@link java.net.URL}), this method may return an empty value.</p>
      *
-     * @return parameters used for opening this {@code DataStore}, or {@code null} if not available.
+     * @return parameters used for opening this {@code DataStore}.
      *
      * @see DataStoreProvider#getOpenParameters()
      *
      * @since 0.8
      */
-    public abstract ParameterValueGroup getOpenParameters();
+    public abstract Optional<ParameterValueGroup> getOpenParameters();
 
     /**
      * Sets the locale to use for formatting warnings and other messages.
@@ -351,7 +355,7 @@ public abstract class DataStore implements Resource, Localized, AutoCloseable {
      * contact information about the creator or distributor, data quality, update frequency, usage constraints,
      * file format and more.
      *
-     * @return information about resources in the data store, or {@code null} if none.
+     * @return information about resources in the data store. Should not be {@code null}.
      * @throws DataStoreException if an error occurred while reading the data.
      *
      * @see #getIdentifier()
diff --git a/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStoreProvider.java b/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStoreProvider.java
index fd206c5..d8091d3 100644
--- a/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStoreProvider.java
+++ b/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStoreProvider.java
@@ -199,7 +199,7 @@ public abstract class DataStoreProvider {
      * <p>Implementers 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}, completed by {@value #CREATE}
      * if the data store supports write operations.
-     * That parameter will be recognized by the default {@code DataStoreProvider} methods and used whenever a
+     * Those parameters will be recognized by the default {@code DataStoreProvider} methods and used whenever a
      * {@link StorageConnector} is required.</p>
      *
      * <div class="note"><b>Alternative:</b>
diff --git a/storage/sis-storage/src/test/java/org/apache/sis/storage/DataStoreMock.java b/storage/sis-storage/src/test/java/org/apache/sis/storage/DataStoreMock.java
index cbbce51..d14b8c5 100644
--- a/storage/sis-storage/src/test/java/org/apache/sis/storage/DataStoreMock.java
+++ b/storage/sis-storage/src/test/java/org/apache/sis/storage/DataStoreMock.java
@@ -16,6 +16,7 @@
  */
 package org.apache.sis.storage;
 
+import java.util.Optional;
 import org.opengis.metadata.Metadata;
 import org.opengis.parameter.ParameterValueGroup;
 import org.apache.sis.storage.event.StoreListeners;
@@ -53,11 +54,11 @@ public final strictfp class DataStoreMock extends DataStore {
     }
 
     /**
-     * Returns {@code null} since there is no open parameters.
+     * Returns empty optional since there is no open parameters.
      */
     @Override
-    public ParameterValueGroup getOpenParameters() {
-        return null;
+    public Optional<ParameterValueGroup> getOpenParameters() {
+        return Optional.empty();
     }
 
     /**