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;
