sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1508957 - in /sis/branches/JDK7: core/sis-utility/src/main/java/org/apache/sis/xml/ storage/sis-netcdf/src/main/java/org/apache/sis/storage/netcdf/ storage/sis-netcdf/src/test/java/org/apache/sis/storage/netcdf/ storage/sis-storage/src/mai...
Date Wed, 31 Jul 2013 16:46:50 GMT
Author: desruisseaux
Date: Wed Jul 31 16:46:50 2013
New Revision: 1508957

URL: http://svn.apache.org/r1508957
Log:
First proposal of 'DataStoreProvider' using OpenOptions.

Modified:
    sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/xml/package-info.java
    sis/branches/JDK7/storage/sis-netcdf/src/main/java/org/apache/sis/storage/netcdf/NetcdfStoreProvider.java
    sis/branches/JDK7/storage/sis-netcdf/src/test/java/org/apache/sis/storage/netcdf/NetcdfStoreProviderTest.java
    sis/branches/JDK7/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStore.java
    sis/branches/JDK7/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStoreProvider.java
    sis/branches/JDK7/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStoreRegistry.java
    sis/branches/JDK7/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStores.java
    sis/branches/JDK7/storage/sis-storage/src/main/java/org/apache/sis/storage/StorageConnector.java
    sis/branches/JDK7/storage/sis-storage/src/main/java/org/apache/sis/storage/package-info.java

Modified: sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/xml/package-info.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/xml/package-info.java?rev=1508957&r1=1508956&r2=1508957&view=diff
==============================================================================
--- sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/xml/package-info.java
[UTF-8] (original)
+++ sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/xml/package-info.java
[UTF-8] Wed Jul 31 16:46:50 2013
@@ -59,7 +59,7 @@
  * @author  Guilhem Legal (Geomatys)
  * @author  Martin Desruisseaux (Geomatys)
  * @since   0.3 (derived from geotk-3.00)
- * @version 0.3
+ * @version 0.4
  * @module
  */
 package org.apache.sis.xml;

Modified: sis/branches/JDK7/storage/sis-netcdf/src/main/java/org/apache/sis/storage/netcdf/NetcdfStoreProvider.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/storage/sis-netcdf/src/main/java/org/apache/sis/storage/netcdf/NetcdfStoreProvider.java?rev=1508957&r1=1508956&r2=1508957&view=diff
==============================================================================
--- sis/branches/JDK7/storage/sis-netcdf/src/main/java/org/apache/sis/storage/netcdf/NetcdfStoreProvider.java
[UTF-8] (original)
+++ sis/branches/JDK7/storage/sis-netcdf/src/main/java/org/apache/sis/storage/netcdf/NetcdfStoreProvider.java
[UTF-8] Wed Jul 31 16:46:50 2013
@@ -16,8 +16,12 @@
  */
 package org.apache.sis.storage.netcdf;
 
+import java.util.Set;
+import java.util.Collections;
 import java.io.IOException;
 import java.nio.ByteBuffer;
+import java.nio.file.OpenOption;
+import java.nio.file.StandardOpenOption;
 import java.lang.reflect.Method;
 import java.lang.reflect.Constructor;
 import java.lang.reflect.InvocationTargetException;
@@ -45,7 +49,7 @@ import org.apache.sis.util.ThreadSafe;
  *
  * @author  Martin Desruisseaux (Geomatys)
  * @since   0.3
- * @version 0.3
+ * @version 0.4
  * @module
  *
  * @see NetcdfStore
@@ -95,25 +99,30 @@ public class NetcdfStoreProvider extends
     }
 
     /**
+     * The open options of NetCDF files.
+     */
+    private static final Set<OpenOption> OPTIONS = Collections.<OpenOption>singleton(StandardOpenOption.READ);
+
+    /**
      * Creates a new provider.
      */
     public NetcdfStoreProvider() {
     }
 
     /**
-     * Returns {@code TRUE} if the given storage appears to be supported by {@link NetcdfStore}.
-     * Returning {@code TRUE} from this method does not guarantee that reading or writing
will succeed,
+     * Returns a non-empty set if the given storage appears to be supported by {@link NetcdfStore}.
+     * Returning a non-empty set from this method does not guarantee that reading or writing
will succeed,
      * only that there appears to be a reasonable chance of success based on a brief inspection
of the
      * {@linkplain StorageConnector#getStorage() storage object} or contents.
      *
      * @param  storage Information about the storage (URL, stream, {@link ucar.nc2.NetcdfFile}
instance, <i>etc</i>).
-     * @return {@link Boolean#TRUE} if the given storage seems to be usable by the {@code
NetcdfStore} instances,
-     *         {@link Boolean#FALSE} if {@code NetcdfStore} will not be able to use the given
storage,
+     * @return A non-empty set if the given storage seems to be usable by the {@code NetcdfStore}
instances,
+     *         an empty set if {@code NetcdfStore} will not be able to use the given storage,
      *         or {@code null} if this method does not have enough information.
      * @throws DataStoreException if an I/O error occurred.
      */
     @Override
-    public Boolean canOpen(StorageConnector storage) throws DataStoreException {
+    public Set<OpenOption> getOpenCapabilities(StorageConnector storage) throws DataStoreException
{
         final ByteBuffer buffer = storage.getStorageAs(ByteBuffer.class);
         if (buffer != null) {
             if (buffer.remaining() < Integer.SIZE / Byte.SIZE) {
@@ -121,7 +130,7 @@ public class NetcdfStoreProvider extends
             }
             final int header = buffer.getInt(buffer.position());
             if ((header & 0xFFFFFF00) == ChannelDecoder.MAGIC_NUMBER) {
-                return Boolean.TRUE;
+                return OPTIONS;
             }
         }
         /*
@@ -132,7 +141,7 @@ public class NetcdfStoreProvider extends
             ensureInitialized();
             final Method method = canOpenFromPath;
             if (method != null) try {
-                return (Boolean) method.invoke(null, path);
+                return ((Boolean) method.invoke(null, path)) ? OPTIONS : Collections.<OpenOption>emptySet();
             } catch (IllegalAccessException e) {
                 throw new AssertionError(e); // Should never happen, since the method is
public.
             } catch (InvocationTargetException e) {
@@ -150,10 +159,10 @@ public class NetcdfStoreProvider extends
          */
         for (Class<?> type = storage.getStorage().getClass(); type != null; type =
type.getSuperclass()) {
             if (UCAR_CLASSNAME.equals(type.getName())) {
-                return Boolean.TRUE;
+                return OPTIONS;
             }
         }
-        return Boolean.FALSE;
+        return Collections.emptySet();
     }
 
     /**

Modified: sis/branches/JDK7/storage/sis-netcdf/src/test/java/org/apache/sis/storage/netcdf/NetcdfStoreProviderTest.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/storage/sis-netcdf/src/test/java/org/apache/sis/storage/netcdf/NetcdfStoreProviderTest.java?rev=1508957&r1=1508956&r2=1508957&view=diff
==============================================================================
--- sis/branches/JDK7/storage/sis-netcdf/src/test/java/org/apache/sis/storage/netcdf/NetcdfStoreProviderTest.java
[UTF-8] (original)
+++ sis/branches/JDK7/storage/sis-netcdf/src/test/java/org/apache/sis/storage/netcdf/NetcdfStoreProviderTest.java
[UTF-8] Wed Jul 31 16:46:50 2013
@@ -16,7 +16,9 @@
  */
 package org.apache.sis.storage.netcdf;
 
+import java.util.Collections;
 import java.io.IOException;
+import java.nio.file.StandardOpenOption;
 import ucar.nc2.NetcdfFile;
 import org.opengis.wrapper.netcdf.IOTestCase;
 import org.apache.sis.internal.netcdf.TestCase;
@@ -45,7 +47,7 @@ import static org.opengis.test.Assert.*;
 })
 public final strictfp class NetcdfStoreProviderTest extends IOTestCase {
     /**
-     * Tests {@link NetcdfStoreProvider#canOpen(StorageConnector)} for an input stream which
shall
+     * Tests {@link NetcdfStoreProvider#getOpenCapabilities(StorageConnector)} for an input
stream which shall
      * be recognized as a classic NetCDF file.
      *
      * @throws DataStoreException Should never happen.
@@ -54,12 +56,12 @@ public final strictfp class NetcdfStoreP
     public void testCanOpenFromStream() throws DataStoreException {
         final StorageConnector c = new StorageConnector(IOTestCase.class.getResourceAsStream(NCEP));
         final NetcdfStoreProvider provider = new NetcdfStoreProvider();
-        assertTrue(provider.canOpen(c));
+        assertEquals(Collections.singleton(StandardOpenOption.READ), provider.getOpenCapabilities(c));
         c.closeAllExcept(null);
     }
 
     /**
-     * Tests {@link NetcdfStoreProvider#canOpen(StorageConnector)} for a UCAR {@link NetcdfFile}
object.
+     * Tests {@link NetcdfStoreProvider#getOpenCapabilities(StorageConnector)} for a UCAR
{@link NetcdfFile} object.
      *
      * @throws IOException If an error occurred while opening the NetCDF file.
      * @throws DataStoreException Should never happen.
@@ -69,7 +71,7 @@ public final strictfp class NetcdfStoreP
         final NetcdfFile file = open(NCEP);
         final StorageConnector c = new StorageConnector(file);
         final NetcdfStoreProvider provider = new NetcdfStoreProvider();
-        assertTrue(provider.canOpen(c));
+        assertEquals(Collections.singleton(StandardOpenOption.READ), provider.getOpenCapabilities(c));
         file.close();
     }
 

Modified: sis/branches/JDK7/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStore.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStore.java?rev=1508957&r1=1508956&r2=1508957&view=diff
==============================================================================
--- sis/branches/JDK7/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStore.java
[UTF-8] (original)
+++ sis/branches/JDK7/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStore.java
[UTF-8] Wed Jul 31 16:46:50 2013
@@ -26,7 +26,7 @@ import org.apache.sis.util.logging.Warni
 
 
 /**
- * A storage object which manage a series of features, coverages or sensor data.
+ * Manages a series of features, coverages or sensor data.
  *
  * {@section Thread safety policy}
  * This {@code DataStore} base class is thread-safe. However subclasses are usually not.

Modified: sis/branches/JDK7/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStoreProvider.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStoreProvider.java?rev=1508957&r1=1508956&r2=1508957&view=diff
==============================================================================
--- sis/branches/JDK7/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStoreProvider.java
[UTF-8] (original)
+++ sis/branches/JDK7/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStoreProvider.java
[UTF-8] Wed Jul 31 16:46:50 2013
@@ -16,12 +16,23 @@
  */
 package org.apache.sis.storage;
 
+import java.util.Set;
+import java.nio.file.OpenOption;
+import java.nio.file.StandardOpenOption;
 import org.apache.sis.util.ThreadSafe;
 
 
 /**
- * Creates {@link DataStore} instances for a specific format from a given {@link StorageConnector}
input.
- * There is typically a different {@code DataStoreProvider} instance for each format provided
by a library.
+ * Provides information about a specific {@link DataStore} implementation.
+ * There is typically one {@code DataStoreProvider} instance for each format supported by
a library.
+ * Each {@code DataStoreProvider} instances provides the following services:
+ *
+ * <ul>
+ *   <li>Provide generic information about the storage (name, <i>etc.</i>).</li>
+ *   <li>Create instances of the {@link DataStore} implementation described by this
provider.</li>
+ *   <li>Test if a {@code DataStore} instance created by this provider would have reasonable
chances
+ *       to open a given {@link StorageConnector}.</li>
+ * </ul>
  *
  * {@section Packaging data stores}
  * JAR files that provide implementations of this class shall contain an entry with exactly
the following path:
@@ -40,7 +51,7 @@ import org.apache.sis.util.ThreadSafe;
  *
  * @author  Martin Desruisseaux (Geomatys)
  * @since   0.3
- * @version 0.3
+ * @version 0.4
  * @module
  */
 @ThreadSafe
@@ -52,53 +63,79 @@ public abstract class DataStoreProvider 
     }
 
     /**
-     * Returns {@code TRUE} if the given storage appears to be supported by the {@code DataStore}.
-     * Returning {@code TRUE} from this method does not guarantee that reading or writing
will succeed,
+     * Returns a non-empty set if the given storage appears to be supported by the {@code
DataStore}.
+     * Returning a non-empty set from this method does not guarantee that reading or writing
will succeed,
      * only that there appears to be a reasonable chance of success based on a brief inspection
of the
      * {@linkplain StorageConnector#getStorage() storage object} or contents.
      *
-     * <p>Implementations will typically check the first bytes of the stream for a
"magic number"
-     * associated with the format, as in the following example:</p>
+     * <p>If the given storage is supported, then the returned set shall contain at
least one of the
+     * following values:</p>
+     *
+     * <table class="sis">
+     *   <tr><th>Value</th>                                 <th>Meaning</th></tr>
+     *   <tr><td>{@link StandardOpenOption#READ}</td>       <td>Can
read data from the given storage.</td></tr>
+     *   <tr><td>{@link StandardOpenOption#WRITE}</td>      <td>Can
overwrite existing data.</td></tr>
+     *   <tr><td>{@link StandardOpenOption#APPEND}</td>     <td>Can
write new data.</td></tr>
+     *   <tr><td>{@link StandardOpenOption#CREATE_NEW}</td> <td>Can
create a new storage at the given location.</td></tr>
+     * </table>
+     *
+     * Other values may be present at implementation choice.
+     *
+     * {@section Implementation note}
+     * Implementations will typically check the first bytes of the stream for a "magic number"
associated
+     * with the format, as in the following example:
      *
      * {@preformat java
-     *     final ByteBuffer buffer = storage.getStorageAs(ByteBuffer.class);
-     *     if (buffer == null) {
-     *         // If StorageConnector can not provide a ByteBuffer, then the storage is probably
-     *         // not a File, URL, URI, InputStream neither a ReadableChannel. In this example,
-     *         // our provider can not handle such unknown source.
-     *         return Boolean.FALSE;
-     *     }
-     *     if (buffer.remaining() < Integer.SIZE / Byte.SIZE) {
-     *         // If the buffer does not contain enough bytes for the 'int' type, this is
not necessarily
-     *         // because the file is truncated. It may be because the data were not yet
available at the
-     *         // time this method has been invoked. Returning 'null' means "don't know".
-     *         return null;
+     *     public Set<OpenOption> getOpenCapabilities(StorageConnector storage) throws
DataStoreException {
+     *         final ByteBuffer buffer = storage.getStorageAs(ByteBuffer.class);
+     *         if (buffer != null) {
+     *             if (buffer.remaining() < Integer.SIZE / Byte.SIZE) {
+     *                 return null; // See notes below.
+     *             }
+     *             if (buffer.getInt(buffer.position()) == MAGIC_NUMBER) {
+     *                 return EnumSet.of(StandardOpenOption.READ);
+     *             }
+     *         }
+     *         return Collections.emptySet();
      *     }
-     *     // Use ByteBuffer.getInt(int) instead than ByteBuffer.getInt() in order to keep
buffer position
-     *     // unchanged after this method call.
-     *     return buffer.getInt(buffer.position()) == MAGIC_NUMBER;
      * }
      *
+     * {@note <ul>
+     *   <li>If <code>StorageConnector</code> can not provide a <code>ByteBuffer</code>,
then the storage is
+     *       probably not a <code>File</code>, <code>URL</code>,
<code>URI</code>, <code>InputStream</code>
+     *       neither a <code>ReadableChannel</code>. In the above example, our
provider can not handle such
+     *       unknown source.</li>
+     *   <li>Above example uses <code>ByteBuffer.getInt(int)</code> instead
than <code>ByteBuffer.getInt()</code>
+     *       in order to keep the buffer position unchanged after this method call.</li>
+     *   <li>If the buffer does not contain enough bytes for the <code>int</code>
type, this is not necessarily
+     *       because the file is truncated. It may be because the data were not yet available
at the time this
+     *       method has been invoked. Returning <code>null</code> means "don't
know".</li>
+     * </ul>}
+     *
      * Implementors are responsible for restoring the input to its original stream position
on return of this method.
      * Implementors can use a mark/reset pair for this purpose. Marks are available as
      * {@link java.nio.ByteBuffer#mark()}, {@link java.io.InputStream#mark(int)} and
      * {@link javax.imageio.stream.ImageInputStream#mark()}.
      *
-     * <table width="80%" align="center" cellpadding="18" border="4" bgcolor="#FFE0B0">
-     *   <tr><td>
-     *     <b>Warning:</b> this method is likely to change. SIS 0.4 will probably
return a set of enumeration
-     *     values describing how the file can be open (read, write, append) similar to JDK7
open mode.
-     *   </td></tr>
-     * </table>
-     *
      * @param  storage Information about the storage (URL, stream, JDBC connection, <i>etc</i>).
-     * @return {@link Boolean#TRUE} if the given storage seems to be usable by the {@code
DataStore} instances
-     *         create by this provider, {@link Boolean#FALSE} if the {@code DataStore} will
not be able to use
+     * @return A non-empty set if the given storage seems to be usable by the {@code DataStore}
instances
+     *         create by this provider, an empty set if the {@code DataStore} will not be
able to use
      *         the given storage, or {@code null} if this method does not have enough information.
      * @throws DataStoreException if an I/O or SQL error occurred. The error shall be unrelated
to the logical
      *         structure of the storage.
+     *
+     * @since 0.4
      */
-    public abstract Boolean canOpen(StorageConnector storage) throws DataStoreException;
+    public abstract Set<OpenOption> getOpenCapabilities(StorageConnector storage) throws
DataStoreException;
+
+    /**
+     * @deprecated Replaced by {@link #getOpenCapabilities(StorageConnector)}.
+     */
+    @Deprecated
+    public Boolean canOpen(StorageConnector storage) throws DataStoreException {
+        final Set<OpenOption> options = getOpenCapabilities(storage);
+        return (options == null) ? null : options.contains(StandardOpenOption.READ);
+    }
 
     /**
      * Returns a data store implementation associated with this provider.

Modified: sis/branches/JDK7/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStoreRegistry.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStoreRegistry.java?rev=1508957&r1=1508956&r2=1508957&view=diff
==============================================================================
--- sis/branches/JDK7/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStoreRegistry.java
[UTF-8] (original)
+++ sis/branches/JDK7/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStoreRegistry.java
[UTF-8] Wed Jul 31 16:46:50 2013
@@ -16,7 +16,9 @@
  */
 package org.apache.sis.storage;
 
+import java.util.Set;
 import java.util.ServiceLoader;
+import java.nio.file.OpenOption;
 import org.apache.sis.util.ThreadSafe;
 import org.apache.sis.util.ArgumentChecks;
 import org.apache.sis.util.resources.Errors;
@@ -77,11 +79,18 @@ final class DataStoreRegistry {
      * </ul>
      *
      * @param  storage The input/output object as a URL, file, image input stream, <i>etc.</i>.
+     * @param  options The open options. Shall contain at least one element,
+     *                 typically {@link java.nio.file.StandardOpenOption#READ}.
      * @return The object to use for reading geospatial data from the given storage.
      * @throws UnsupportedStorageException if no {@link DataStoreProvider} is found for a
given storage object.
      * @throws DataStoreException If an error occurred while opening the storage.
      */
-    public DataStore open(final Object storage) throws DataStoreException {
+    public DataStore open(final Object storage, final Set<OpenOption> options) throws
DataStoreException {
+        ArgumentChecks.ensureNonNull("storage", storage);
+        ArgumentChecks.ensureNonNull("options", options);
+        if (options.isEmpty()) {
+            throw new IllegalArgumentException(Errors.format(Errors.Keys.EmptyArgument_1,
"options"));
+        }
         StorageConnector connector;
         if (storage instanceof StorageConnector) {
             connector = (StorageConnector) storage;
@@ -92,10 +101,10 @@ final class DataStoreRegistry {
             DataStoreProvider provider = null;
             synchronized (loader) {
                 for (final DataStoreProvider candidate : loader) {
-                    final Boolean canOpen = candidate.canOpen(connector);
-                    if (canOpen == null) {
+                    final Set<OpenOption> capabilities = candidate.getOpenCapabilities(connector);
+                    if (capabilities == null) {
                         // TODO: not enough information.
-                    } else if (canOpen) {
+                    } else if (capabilities.containsAll(options)) {
                         provider = candidate;
                         break;
                     }

Modified: sis/branches/JDK7/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStores.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStores.java?rev=1508957&r1=1508956&r2=1508957&view=diff
==============================================================================
--- sis/branches/JDK7/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStores.java
[UTF-8] (original)
+++ sis/branches/JDK7/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStores.java
[UTF-8] Wed Jul 31 16:46:50 2013
@@ -16,6 +16,10 @@
  */
 package org.apache.sis.storage;
 
+import java.util.Set;
+import java.util.Collections;
+import java.nio.file.OpenOption;
+import java.nio.file.StandardOpenOption;
 import org.apache.sis.util.Static;
 import org.apache.sis.internal.system.Modules;
 import org.apache.sis.internal.system.SystemListener;
@@ -56,14 +60,22 @@ public final class DataStores extends St
     }
 
     /**
+     * The options for opening storage in read mode.
+     */
+    private static final Set<OpenOption> READ = Collections.<OpenOption>singleton(StandardOpenOption.READ);
+
+    /**
      * Do not allow instantiation of this class.
      */
     private DataStores() {
     }
 
     /**
-     * Creates a {@link DataStore} for reading the given storage.
-     * The {@code storage} argument can be any of the following types:
+     * Creates a {@link DataStore} for the given storage using its default set of {@code
OpenOption}s.
+     * The data store is guaranteed to be opened at least with {@link StandardOpenOption#READ}.
+     * Whether the data store has also write or append capabilities is implementation dependent.
+     *
+     * <p>The {@code storage} argument can be any of the following types:</p>
      *
      * <ul>
      *   <li>A {@link java.nio.file.Path} or a {@link java.io.File} for a file or a
directory.</li>
@@ -81,6 +93,30 @@ public final class DataStores extends St
      * @throws DataStoreException If an error occurred while opening the storage.
      */
     public static DataStore open(final Object storage) throws DataStoreException {
+        return open(storage, READ);
+    }
+
+    /**
+     * Creates a {@link DataStore} for the given storage using the given set of {@code OpenOption}s.
+     * The {@code storage} argument can be any of the following types:
+     *
+     * <ul>
+     *   <li>A {@link java.nio.file.Path} or a {@link java.io.File} for a file or a
directory.</li>
+     *   <li>A {@link java.net.URI} or a {@link java.net.URL} to a distant resource.</li>
+     *   <li>A {@link java.lang.CharSequence} interpreted as a filename or a URL.</li>
+     *   <li>A {@link java.nio.channels.Channel} or a {@link java.io.DataInput}.</li>
+     *   <li>A {@link javax.sql.DataSource} or a {@link java.sql.Connection} to a JDBC
database.</li>
+     *   <li>Any other {@code DataStore}-specific object, for example {@link ucar.nc2.NetcdfFile}.</li>
+     *   <li>An existing {@link StorageConnector} instance.</li>
+     * </ul>
+     *
+     * @param  storage The input/output object as a URL, file, image input stream, <i>etc.</i>.
+     * @param  options The open options. Shall contain at least one element, typically {@link
StandardOpenOption#READ}.
+     * @return The object to use for reading geospatial data from the given storage.
+     * @throws UnsupportedStorageException if no {@link DataStoreProvider} is found for a
given storage object.
+     * @throws DataStoreException If an error occurred while opening the storage.
+     */
+    public static DataStore open(final Object storage, final Set<OpenOption> options)
throws DataStoreException {
         DataStoreRegistry r = registry;
         if (r == null) {
             synchronized (DataStores.class) {
@@ -90,6 +126,6 @@ public final class DataStores extends St
                 }
             }
         }
-        return r.open(storage);
+        return r.open(storage, options);
     }
 }

Modified: sis/branches/JDK7/storage/sis-storage/src/main/java/org/apache/sis/storage/StorageConnector.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/storage/sis-storage/src/main/java/org/apache/sis/storage/StorageConnector.java?rev=1508957&r1=1508956&r2=1508957&view=diff
==============================================================================
--- sis/branches/JDK7/storage/sis-storage/src/main/java/org/apache/sis/storage/StorageConnector.java
[UTF-8] (original)
+++ sis/branches/JDK7/storage/sis-storage/src/main/java/org/apache/sis/storage/StorageConnector.java
[UTF-8] Wed Jul 31 16:46:50 2013
@@ -295,9 +295,9 @@ public class StorageConnector implements
      * </ul>
      *
      * Multiple invocations of this method on the same {@code StorageConnector} instance
will try
-     * to return the same instance on a <cite>best effort</cite> basis. Consequently,
implementations
-     * of {@link DataStoreProvider#canOpen(StorageConnector)} methods shall not close the
stream or
-     * database connection returned by this method. In addition, those {@code canOpen(StorageConnector)}
+     * to return the same instance on a <cite>best effort</cite> basis. Consequently,
implementations of
+     * {@link DataStoreProvider#getOpenCapabilities(StorageConnector)} methods shall not
close the stream or
+     * database connection returned by this method. In addition, those {@code getOpenCapabilities(StorageConnector)}
      * methods are responsible for restoring the stream or byte buffer to its original position
on return.
      *
      * @param  <T>  The compile-time type of the {@code type} argument.

Modified: sis/branches/JDK7/storage/sis-storage/src/main/java/org/apache/sis/storage/package-info.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/storage/sis-storage/src/main/java/org/apache/sis/storage/package-info.java?rev=1508957&r1=1508956&r2=1508957&view=diff
==============================================================================
--- sis/branches/JDK7/storage/sis-storage/src/main/java/org/apache/sis/storage/package-info.java
[UTF-8] (original)
+++ sis/branches/JDK7/storage/sis-storage/src/main/java/org/apache/sis/storage/package-info.java
[UTF-8] Wed Jul 31 16:46:50 2013
@@ -19,24 +19,15 @@
  * {@linkplain org.apache.sis.storage.DataStore Data store} base types for retrieving and
saving geospatial data
  * in various storage formats.
  *
- * <p>Different {@code DataStore} implementations will want different kind of input/output
objects. Some examples are
- * {@link java.lang.String}, {@link java.nio.file.Path}, {@link java.io.File}, {@link java.net.URI},
{@link java.net.URL},
- * {@link java.io.InputStream}, {@link javax.imageio.stream.ImageInputStream}, {@link java.nio.channels.ReadableChannel},
- * JDBC {@link java.sql.Connection} or {@link javax.sql.DataSource}, or even
- * datastore-specific objects like {@link ucar.nc2.NetcdfFile}.
- * Because of this variety, SIS does not know which kind of object to accept before the appropriate
{@code DataStore}
- * instance has been found. For this reason, storages are represented by arbitrary {@link
java.lang.Object} encapsulated
- * in {@link org.apache.sis.storage.StorageConnector}. The later can open the object in various
ways, for example
- * as {@link java.io.DataInput} or as {@link java.nio.ByteBuffer}, depending on {@code DataStore
needs}.
- * Future versions may contain additional information like login/password.</p>
- *
- * <p>{@code StorageConnector} is used only for the "discovery" phase, and discarded
once the actual
- * {@code DataStore} instance has been created.</p>
+ * <p>{@code DataStore} provides the methods for reading or writing geospatial data
in a given storage.
+ * A storage may be a file, a directory, a connection to a database or any other implementation
specific mechanism.
+ * Suitable {@code DataStore} implementation for a given storage can be discovered and opened
by the static methods
+ * provided in {@link org.apache.sis.storage.DataStores}.</p>
  *
  * @author  Johann Sorel (Geomatys)
  * @author  Martin Desruisseaux (Geomatys)
  * @since   0.3 (derived from geotk-3.10)
- * @version 0.3
+ * @version 0.4
  * @module
  */
 package org.apache.sis.storage;



Mime
View raw message