Author: desruisseaux
Date: Wed Jun 5 14:12:57 2013
New Revision: 1489882
URL: http://svn.apache.org/r1489882
Log:
Initial commit of NetcdfStore public API.
Added:
sis/branches/JDK7/storage/sis-netcdf/src/main/java/org/apache/sis/storage/netcdf/NetcdfStore.java
(with props)
sis/branches/JDK7/storage/sis-netcdf/src/test/java/org/apache/sis/storage/netcdf/NetcdfStoreTest.java
(with props)
Modified:
sis/branches/JDK7/storage/sis-netcdf/src/main/java/org/apache/sis/internal/netcdf/impl/ChannelDecoder.java
sis/branches/JDK7/storage/sis-netcdf/src/main/java/org/apache/sis/internal/netcdf/ucar/DecoderWrapper.java
sis/branches/JDK7/storage/sis-netcdf/src/main/java/org/apache/sis/storage/netcdf/MetadataReader.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/MetadataReaderTest.java
sis/branches/JDK7/storage/sis-netcdf/src/test/java/org/apache/sis/storage/netcdf/NetcdfStoreProviderTest.java
sis/branches/JDK7/storage/sis-netcdf/src/test/java/org/apache/sis/test/suite/NetcdfTestSuite.java
sis/branches/JDK7/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStoreConnection.java
sis/branches/JDK7/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStoreProvider.java
Modified:
sis/branches/JDK7/storage/sis-netcdf/src/main/java/org/apache/sis/internal/netcdf/impl/ChannelDecoder.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK7/storage/sis-netcdf/src/main/java/org/apache/sis/internal/netcdf/impl/ChannelDecoder.java?rev=1489882&r1=1489881&r2=1489882&view=diff
==============================================================================
---
sis/branches/JDK7/storage/sis-netcdf/src/main/java/org/apache/sis/internal/netcdf/impl/ChannelDecoder.java
[UTF-8] (original)
+++
sis/branches/JDK7/storage/sis-netcdf/src/main/java/org/apache/sis/internal/netcdf/impl/ChannelDecoder.java
[UTF-8] Wed Jun 5 14:12:57 2013
@@ -720,4 +720,18 @@ nextVar: for (final VariableInfo vari
public void close() throws IOException {
input.channel.close();
}
+
+ /**
+ * Returns a string representation to be inserted in {@link
org.apache.sis.storage.netcdf.NetcdfStore#toString()}
+ * result. This is for debugging purpose only any may change in any future
SIS version.
+ */
+ @Override
+ public String toString() {
+ final StringBuilder buffer = new StringBuilder();
+ buffer.append("SIS driver: “").append(input.filename).append('”');
+ if (!input.channel.isOpen()) {
+ buffer.append(" (closed)");
+ }
+ return buffer.toString();
+ }
}
Modified:
sis/branches/JDK7/storage/sis-netcdf/src/main/java/org/apache/sis/internal/netcdf/ucar/DecoderWrapper.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK7/storage/sis-netcdf/src/main/java/org/apache/sis/internal/netcdf/ucar/DecoderWrapper.java?rev=1489882&r1=1489881&r2=1489882&view=diff
==============================================================================
---
sis/branches/JDK7/storage/sis-netcdf/src/main/java/org/apache/sis/internal/netcdf/ucar/DecoderWrapper.java
[UTF-8] (original)
+++
sis/branches/JDK7/storage/sis-netcdf/src/main/java/org/apache/sis/internal/netcdf/ucar/DecoderWrapper.java
[UTF-8] Wed Jun 5 14:12:57 2013
@@ -353,4 +353,13 @@ public final class DecoderWrapper extend
public void close() throws IOException {
file.close();
}
+
+ /**
+ * Returns a string representation to be inserted in {@link
org.apache.sis.storage.netcdf.NetcdfStore#toString()}
+ * result. This is for debugging purpose only any may change in any future
SIS version.
+ */
+ @Override
+ public String toString() {
+ return "UCAR driver: “" + file.getLocation() + '”';
+ }
}
Modified:
sis/branches/JDK7/storage/sis-netcdf/src/main/java/org/apache/sis/storage/netcdf/MetadataReader.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK7/storage/sis-netcdf/src/main/java/org/apache/sis/storage/netcdf/MetadataReader.java?rev=1489882&r1=1489881&r2=1489882&view=diff
==============================================================================
---
sis/branches/JDK7/storage/sis-netcdf/src/main/java/org/apache/sis/storage/netcdf/MetadataReader.java
[UTF-8] (original)
+++
sis/branches/JDK7/storage/sis-netcdf/src/main/java/org/apache/sis/storage/netcdf/MetadataReader.java
[UTF-8] Wed Jun 5 14:12:57 2013
@@ -830,6 +830,7 @@ final class MetadataReader extends Warni
/**
* Creates an ISO {@code Metadata} object from the information found in
the NetCDF file.
+ * The returned metadata will be unmodifiable in order to allow the caller
to cache it.
*
* @return The ISO metadata object.
* @throws IOException If an I/O operation was necessary but failed.
@@ -919,6 +920,7 @@ final class MetadataReader extends Warni
metadata.getSpatialRepresentationInfo().add(createSpatialRepresentationInfo(cs));
}
}
+ metadata.freeze();
return metadata;
}
}
Added:
sis/branches/JDK7/storage/sis-netcdf/src/main/java/org/apache/sis/storage/netcdf/NetcdfStore.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK7/storage/sis-netcdf/src/main/java/org/apache/sis/storage/netcdf/NetcdfStore.java?rev=1489882&view=auto
==============================================================================
---
sis/branches/JDK7/storage/sis-netcdf/src/main/java/org/apache/sis/storage/netcdf/NetcdfStore.java
(added)
+++
sis/branches/JDK7/storage/sis-netcdf/src/main/java/org/apache/sis/storage/netcdf/NetcdfStore.java
[UTF-8] Wed Jun 5 14:12:57 2013
@@ -0,0 +1,108 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.sis.storage.netcdf;
+
+import java.io.IOException;
+import org.opengis.metadata.Metadata;
+import org.apache.sis.util.ArgumentChecks;
+import org.apache.sis.storage.AbstractDataStore;
+import org.apache.sis.storage.DataStoreException;
+import org.apache.sis.storage.DataStoreConnection;
+import org.apache.sis.internal.netcdf.Decoder;
+
+
+/**
+ * A data store backed by NetCDF files.
+ * Instances of this data store are created by {@link
NetcdfStoreProvider#open(DataStoreConnection)}.
+ *
+ * @author Martin Desruisseaux (Geomatys)
+ * @since 0.3
+ * @version 0.3
+ * @module
+ *
+ * @see NetcdfStoreProvider
+ */
+public class NetcdfStore extends AbstractDataStore {
+ /**
+ * The object to use for decoding the NetCDF file content. There is two
different implementations,
+ * depending on whether we are using the embedded SIS decoder or a wrapper
around the UCAR library.
+ */
+ private final Decoder decoder;
+
+ /**
+ * The object returned by {@link #getMetadata()}, created when first
needed and cached.
+ */
+ private Metadata metadata;
+
+ /**
+ * Creates a new NetCDF store from the given file, URL, stream or {@link
ucar.nc2.NetcdfFile} object.
+ * This constructor invokes {@link
DataStoreConnection#closeAllExcept(Object)}, keeping open only the
+ * needed resource.
+ *
+ * @param storage Information about the storage (URL, stream, {@link
ucar.nc2.NetcdfFile} instance, <i>etc</i>).
+ * @throws DataStoreException If an error occurred while opening the
NetCDF file.
+ */
+ public NetcdfStore(final DataStoreConnection storage) throws
DataStoreException {
+ ArgumentChecks.ensureNonNull("storage", storage);
+ try {
+ decoder = NetcdfStoreProvider.decoder(null, storage);
+ } catch (IOException e) {
+ throw new DataStoreException(e);
+ }
+ }
+
+ /**
+ * Returns information about the dataset as a whole. The returned metadata
object can contain information
+ * such as the spatiotemporal extent of the dataset, contact information
about the creator or distributor,
+ * data quality, usage constraints and more.
+ *
+ * @return Information about the dataset.
+ * @throws DataStoreException If an error occurred while reading the data.
+ */
+ @Override
+ public Metadata getMetadata() throws DataStoreException {
+ if (metadata == null) try {
+ final MetadataReader reader = new MetadataReader(decoder);
+ metadata = reader.read(); // Umodifiable object.
+ } catch (IOException e) {
+ throw new DataStoreException(e);
+ }
+ return metadata;
+ }
+
+ /**
+ * Closes this NetCDF store and releases any underlying resources.
+ */
+ @Override
+ public void close() throws DataStoreException {
+ metadata = null;
+ try {
+ decoder.close();
+ } catch (IOException e) {
+ throw new DataStoreException(e);
+ }
+ }
+
+ /**
+ * Returns a string representation of this NetCDF store for debugging
purpose.
+ * The content of the string returned by this method may change in any
future SIS version.
+ */
+ @Override
+ public String toString() {
+ return getClass().getSimpleName() + '[' + decoder + ']';
+ }
+}
Propchange:
sis/branches/JDK7/storage/sis-netcdf/src/main/java/org/apache/sis/storage/netcdf/NetcdfStore.java
------------------------------------------------------------------------------
svn:eol-style = native
Propchange:
sis/branches/JDK7/storage/sis-netcdf/src/main/java/org/apache/sis/storage/netcdf/NetcdfStore.java
------------------------------------------------------------------------------
svn:mime-type = text/plain;charset=UTF-8
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=1489882&r1=1489881&r2=1489882&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 Jun 5 14:12:57 2013
@@ -44,6 +44,8 @@ import org.apache.sis.storage.DataStoreE
* @since 0.3
* @version 0.3
* @module
+ *
+ * @see NetcdfStore
*/
public class NetcdfStoreProvider extends DataStoreProvider {
/**
@@ -130,7 +132,7 @@ public class NetcdfStoreProvider extends
* We check classnames instead of netcdfFileClass.isInstance(storage)
* in order to avoid loading the UCAR library if not needed.
*/
- for (Class<?> type = storage.getStorage().getClass(); type != null;
type=type.getSuperclass()) {
+ for (Class<?> type = storage.getStorage().getClass(); type != null;
type = type.getSuperclass()) {
if (UCAR_CLASSNAME.equals(type.getName())) {
return Boolean.TRUE;
}
@@ -139,40 +141,51 @@ public class NetcdfStoreProvider extends
}
/**
- * Returns a {@link NetcdfStore} implementation associated with this
provider.
+ * Returns a {@link NetcdfStore} implementation associated with this
provider. This method invokes
+ * {@link DataStoreConnection#closeAllExcept(Object)} after data store
creation, keeping open only
+ * the needed resource.
*
* @param storage Information about the storage (URL, stream, {@link
ucar.nc2.NetcdfFile} instance, <i>etc</i>).
*/
@Override
- public DataStore open(DataStoreConnection storage) throws
DataStoreException {
- throw new UnsupportedOperationException("Not supported yet."); // TODO
+ public DataStore open(final DataStoreConnection storage) throws
DataStoreException {
+ return new NetcdfStore(storage);
}
/**
- * Creates a decoder for the given input.
+ * Creates a decoder for the given input. This method invokes
+ * {@link DataStoreConnection#closeAllExcept(Object)} after the decoder
has been created.
*
- * @param sink Where to send the warnings, or {@code null} if none.
- * @param connection Information about the input (file, input stream,
<i>etc.</i>)
+ * @param sink Where to send the warnings, or {@code null} if none.
+ * @param storage Information about the input (file, input stream,
<i>etc.</i>)
* @return The decoder for the given input.
* @throws IOException If an error occurred while opening the NetCDF file.
* @throws DataStoreException If a logical error (other than I/O) occurred.
*/
- static Decoder decoder(final WarningProducer sink, final
DataStoreConnection connection)
+ static Decoder decoder(final WarningProducer sink, final
DataStoreConnection storage)
throws IOException, DataStoreException
{
- final ChannelDataInput input =
connection.getStorageAs(ChannelDataInput.class);
+ Decoder decoder;
+ Object keepOpen;
+ final ChannelDataInput input =
storage.getStorageAs(ChannelDataInput.class);
if (input != null) try {
- return new ChannelDecoder(sink, input);
+ decoder = new ChannelDecoder(sink, input);
+ keepOpen = input;
} catch (DataStoreException e) {
- final String path = connection.getStorageAs(String.class);
+ final String path = storage.getStorageAs(String.class);
if (path != null) try {
- return createByReflection(sink, path, false);
+ decoder = createByReflection(sink, path, false);
+ keepOpen = path;
} catch (IOException | DataStoreException s) {
e.addSuppressed(s);
}
throw e;
+ } else {
+ keepOpen = storage.getStorage();
+ decoder = createByReflection(sink, keepOpen, true);
}
- return createByReflection(sink, connection.getStorage(), true);
+ storage.closeAllExcept(keepOpen);
+ return decoder;
}
/**
Modified:
sis/branches/JDK7/storage/sis-netcdf/src/test/java/org/apache/sis/storage/netcdf/MetadataReaderTest.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK7/storage/sis-netcdf/src/test/java/org/apache/sis/storage/netcdf/MetadataReaderTest.java?rev=1489882&r1=1489881&r2=1489882&view=diff
==============================================================================
---
sis/branches/JDK7/storage/sis-netcdf/src/test/java/org/apache/sis/storage/netcdf/MetadataReaderTest.java
[UTF-8] (original)
+++
sis/branches/JDK7/storage/sis-netcdf/src/test/java/org/apache/sis/storage/netcdf/MetadataReaderTest.java
[UTF-8] Wed Jun 5 14:12:57 2013
@@ -75,8 +75,9 @@ public final strictfp class MetadataRead
/**
* Compares the string representation of the given metadata object with
the expected one.
+ * The given metadata shall have been created from the {@link #NCEP}
dataset.
*/
- private static void compareToExpected(final Metadata actual) {
+ static void compareToExpected(final Metadata actual) {
assertMultilinesEquals(
"DefaultMetadata\n" +
" ├─File identifier…………………………………………………………………………
edu.ucar.unidata:NCEP/SST/Global_5x2p5deg/SST_Global_5x2p5deg_20050922_0000.nc\n"
+
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=1489882&r1=1489881&r2=1489882&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 Jun 5 14:12:57 2013
@@ -20,8 +20,8 @@ import java.io.IOException;
import ucar.nc2.NetcdfFile;
import org.opengis.wrapper.netcdf.IOTestCase;
import org.apache.sis.internal.netcdf.Decoder;
-import org.apache.sis.internal.netcdf.impl.ChannelDecoder;
import org.apache.sis.internal.netcdf.ucar.DecoderWrapper;
+import org.apache.sis.internal.netcdf.impl.ChannelDecoder;
import org.apache.sis.internal.netcdf.impl.ChannelDecoderTest;
import org.apache.sis.storage.DataStoreConnection;
import org.apache.sis.storage.DataStoreException;
@@ -29,7 +29,6 @@ import org.apache.sis.test.DependsOn;
import org.junit.Test;
import static org.opengis.test.Assert.*;
-import static org.opengis.wrapper.netcdf.IOTestCase.NCEP;
/**
Added:
sis/branches/JDK7/storage/sis-netcdf/src/test/java/org/apache/sis/storage/netcdf/NetcdfStoreTest.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK7/storage/sis-netcdf/src/test/java/org/apache/sis/storage/netcdf/NetcdfStoreTest.java?rev=1489882&view=auto
==============================================================================
---
sis/branches/JDK7/storage/sis-netcdf/src/test/java/org/apache/sis/storage/netcdf/NetcdfStoreTest.java
(added)
+++
sis/branches/JDK7/storage/sis-netcdf/src/test/java/org/apache/sis/storage/netcdf/NetcdfStoreTest.java
[UTF-8] Wed Jun 5 14:12:57 2013
@@ -0,0 +1,65 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.sis.storage.netcdf;
+
+import org.opengis.metadata.Metadata;
+import org.opengis.wrapper.netcdf.IOTestCase;
+import org.apache.sis.storage.DataStoreConnection;
+import org.apache.sis.storage.DataStoreException;
+import org.apache.sis.test.DependsOn;
+import org.junit.Test;
+
+import static org.opengis.test.Assert.*;
+
+
+/**
+ * Tests {@link NetcdfStore}.
+ *
+ * @author Martin Desruisseaux (Geomatys)
+ * @since 0.3
+ * @version 0.3
+ * @module
+ */
+@DependsOn({
+ MetadataReaderTest.class,
+ NetcdfStoreProviderTest.class
+})
+public final strictfp class NetcdfStoreTest extends IOTestCase {
+ /**
+ * Returns a new NetCDF store to test.
+ *
+ * @param dataset The name of the datastore to load.
+ * @throws DataStoreException If an error occurred while reading the
NetCDF file.
+ */
+ private static NetcdfStore create(final String dataset) throws
DataStoreException {
+ return new NetcdfStore(new
DataStoreConnection(IOTestCase.class.getResource(dataset)));
+ }
+
+ /**
+ * Tests {@link NetcdfStore#getMetadata()}.
+ *
+ * @throws DataStoreException If an error occurred while reading the
NetCDF file.
+ */
+ @Test
+ public void testGetMetadata() throws DataStoreException {
+ final NetcdfStore store = create(NCEP);
+ final Metadata metadata = store.getMetadata();
+ assertSame("Should be cached.", metadata, store.getMetadata());
+ store.close();
+ MetadataReaderTest.compareToExpected(metadata);
+ }
+}
Propchange:
sis/branches/JDK7/storage/sis-netcdf/src/test/java/org/apache/sis/storage/netcdf/NetcdfStoreTest.java
------------------------------------------------------------------------------
svn:eol-style = native
Propchange:
sis/branches/JDK7/storage/sis-netcdf/src/test/java/org/apache/sis/storage/netcdf/NetcdfStoreTest.java
------------------------------------------------------------------------------
svn:mime-type = text/plain;charset=UTF-8
Modified:
sis/branches/JDK7/storage/sis-netcdf/src/test/java/org/apache/sis/test/suite/NetcdfTestSuite.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK7/storage/sis-netcdf/src/test/java/org/apache/sis/test/suite/NetcdfTestSuite.java?rev=1489882&r1=1489881&r2=1489882&view=diff
==============================================================================
---
sis/branches/JDK7/storage/sis-netcdf/src/test/java/org/apache/sis/test/suite/NetcdfTestSuite.java
[UTF-8] (original)
+++
sis/branches/JDK7/storage/sis-netcdf/src/test/java/org/apache/sis/test/suite/NetcdfTestSuite.java
[UTF-8] Wed Jun 5 14:12:57 2013
@@ -40,7 +40,8 @@ import org.junit.BeforeClass;
org.apache.sis.internal.netcdf.impl.GridGeometryInfoTest.class,
org.apache.sis.storage.netcdf.MetadataReaderTest.class,
org.apache.sis.storage.netcdf.ConformanceTest.class,
- org.apache.sis.storage.netcdf.NetcdfStoreProviderTest.class
+ org.apache.sis.storage.netcdf.NetcdfStoreProviderTest.class,
+ org.apache.sis.storage.netcdf.NetcdfStoreTest.class
})
public final strictfp class NetcdfTestSuite extends TestSuite {
/**
Modified:
sis/branches/JDK7/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStoreConnection.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK7/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStoreConnection.java?rev=1489882&r1=1489881&r2=1489882&view=diff
==============================================================================
---
sis/branches/JDK7/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStoreConnection.java
[UTF-8] (original)
+++
sis/branches/JDK7/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStoreConnection.java
[UTF-8] Wed Jun 5 14:12:57 2013
@@ -523,6 +523,7 @@ public class DataStoreConnection impleme
* @throws DataStoreException If an error occurred while closing the
stream or database connection.
*
* @see #getStorageAs(Class)
+ * @see DataStoreProvider#open(DataStoreConnection)
*/
public void closeAllExcept(final Object view) throws DataStoreException {
/*
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=1489882&r1=1489881&r2=1489882&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 Jun 5 14:12:57 2013
@@ -78,6 +78,10 @@ public abstract class DataStoreProvider
/**
* Returns a data store implementation associated with this provider.
*
+ * <p><b>Implementation note:</b>
+ * Implementors shall invoke {@link
DataStoreConnection#closeAllExcept(Object)} after {@code DataStore}
+ * creation, keeping open only the needed resource.</p>
+ *
* @param storage Information about the storage (URL, stream, JDBC
connection, <i>etc</i>).
* @return A data store implementation associated with this provider for
the given storage.
* @throws DataStoreException if an error occurred while creating the data
store instance.
