Return-Path: X-Original-To: apmail-sis-commits-archive@www.apache.org Delivered-To: apmail-sis-commits-archive@www.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id B2DF4105BF for ; Wed, 31 Jul 2013 16:47:24 +0000 (UTC) Received: (qmail 5644 invoked by uid 500); 31 Jul 2013 16:47:24 -0000 Delivered-To: apmail-sis-commits-archive@sis.apache.org Received: (qmail 5482 invoked by uid 500); 31 Jul 2013 16:47:20 -0000 Mailing-List: contact commits-help@sis.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: sis-dev@sis.apache.org Delivered-To: mailing list commits@sis.apache.org Received: (qmail 5377 invoked by uid 99); 31 Jul 2013 16:47:19 -0000 Received: from nike.apache.org (HELO nike.apache.org) (192.87.106.230) by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 31 Jul 2013 16:47:19 +0000 X-ASF-Spam-Status: No, hits=-2000.0 required=5.0 tests=ALL_TRUSTED X-Spam-Check-By: apache.org Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4) by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 31 Jul 2013 16:47:13 +0000 Received: from eris.apache.org (localhost [127.0.0.1]) by eris.apache.org (Postfix) with ESMTP id 4D426238889B; Wed, 31 Jul 2013 16:46:51 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit 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 -0000 To: commits@sis.apache.org From: desruisseaux@apache.org X-Mailer: svnmailer-1.0.9 Message-Id: <20130731164651.4D426238889B@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org 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 OPTIONS = Collections.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, etc). - * @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 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.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: + * + *
    + *
  • Provide generic information about the storage (name, etc.).
    • + *
  • Create instances of the {@link DataStore} implementation described by this provider.
    • + *
  • Test if a {@code DataStore} instance created by this provider would have reasonable chances + * to open a given {@link StorageConnector}.
    • + *
* * {@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. * - *

Implementations will typically check the first bytes of the stream for a "magic number" - * associated with the format, as in the following example:

+ *

If the given storage is supported, then the returned set shall contain at least one of the + * following values:

+ * + * + * + * + * + * + * + *
Value Meaning
{@link StandardOpenOption#READ} Can read data from the given storage.
{@link StandardOpenOption#WRITE} Can overwrite existing data.
{@link StandardOpenOption#APPEND} Can write new data.
{@link StandardOpenOption#CREATE_NEW} Can create a new storage at the given location.
+ * + * 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 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
    + *
  • If StorageConnector can not provide a ByteBuffer, then the storage is + * probably not a File, URL, URI, InputStream + * neither a ReadableChannel. In the above example, our provider can not handle such + * unknown source.
    • + *
  • Above example uses ByteBuffer.getInt(int) instead than ByteBuffer.getInt() + * in order to keep the buffer position unchanged after this method call.
    • + *
  • 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".
    • + *
} + * * 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()}. * - * - * - *
- * Warning: 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. - *
- * * @param storage Information about the storage (URL, stream, JDBC connection, etc). - * @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 getOpenCapabilities(StorageConnector storage) throws DataStoreException; + + /** + * @deprecated Replaced by {@link #getOpenCapabilities(StorageConnector)}. + */ + @Deprecated + public Boolean canOpen(StorageConnector storage) throws DataStoreException { + final Set 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 { * * * @param storage The input/output object as a URL, file, image input stream, etc.. + * @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 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 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 READ = Collections.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. + * + *

The {@code storage} argument can be any of the following types:

* *
    *
  • A {@link java.nio.file.Path} or a {@link java.io.File} for a file or a directory.
    • @@ -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: + * + *
      + *
    • A {@link java.nio.file.Path} or a {@link java.io.File} for a file or a directory.
      • + *
    • A {@link java.net.URI} or a {@link java.net.URL} to a distant resource.
      • + *
    • A {@link java.lang.CharSequence} interpreted as a filename or a URL.
      • + *
    • A {@link java.nio.channels.Channel} or a {@link java.io.DataInput}.
      • + *
    • A {@link javax.sql.DataSource} or a {@link java.sql.Connection} to a JDBC database.
      • + *
    • Any other {@code DataStore}-specific object, for example {@link ucar.nc2.NetcdfFile}.
      • + *
    • An existing {@link StorageConnector} instance.
      • + *
    + * + * @param storage The input/output object as a URL, file, image input stream, etc.. + * @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 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 *
* * Multiple invocations of this method on the same {@code StorageConnector} instance will try - * to return the same instance on a best effort 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 best effort 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 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. * - *

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.

- * - *

{@code StorageConnector} is used only for the "discovery" phase, and discarded once the actual - * {@code DataStore} instance has been created.

+ *

{@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}.

* * @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;