Author: desruisseaux
Date: Mon Aug 7 14:22:09 2017
New Revision: 1804339
URL: http://svn.apache.org/viewvc?rev=1804339&view=rev
Log:
Prepare refactoring of FeatureStore as FeatureSet. This commit adds
AbstractResource and AbstractFeatureSet classes (not in public API for now) and
edits some documentation.
Added:
sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/AbstractFeatureSet.java
(with props)
sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/AbstractResource.java
(with props)
Modified:
sis/branches/JDK8/core/sis-raster/src/main/java/org/apache/sis/image/TransferType.java
sis/branches/JDK8/pom.xml
sis/branches/JDK8/storage/sis-earth-observation/src/main/java/org/apache/sis/storage/earthobservation/LandsatStore.java
sis/branches/JDK8/storage/sis-geotiff/src/main/java/org/apache/sis/storage/geotiff/GeoTiffStore.java
sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/MetadataBuilder.java
sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/wkt/Store.java
sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/xml/Store.java
sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/Aggregate.java
sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStore.java
sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/FeatureSet.java
Modified:
sis/branches/JDK8/core/sis-raster/src/main/java/org/apache/sis/image/TransferType.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-raster/src/main/java/org/apache/sis/image/TransferType.java?rev=1804339&r1=1804338&r2=1804339&view=diff
==============================================================================
---
sis/branches/JDK8/core/sis-raster/src/main/java/org/apache/sis/image/TransferType.java
[UTF-8] (original)
+++
sis/branches/JDK8/core/sis-raster/src/main/java/org/apache/sis/image/TransferType.java
[UTF-8] Mon Aug 7 14:22:09 2017
@@ -140,6 +140,9 @@ public final class TransferType<T extend
/**
* Returns a unique instance on deserialization.
+ *
+ * @return the object to use after deserialization.
+ * @throws ObjectStreamException if the serialized object defines an
unknown data type.
*/
Object readResolve() throws ObjectStreamException {
try {
Modified: sis/branches/JDK8/pom.xml
URL:
http://svn.apache.org/viewvc/sis/branches/JDK8/pom.xml?rev=1804339&r1=1804338&r2=1804339&view=diff
==============================================================================
--- sis/branches/JDK8/pom.xml (original)
+++ sis/branches/JDK8/pom.xml Mon Aug 7 14:22:09 2017
@@ -823,7 +823,7 @@ Apache SIS is a free software, Java lang
</group>
<group>
<title>Coverage and raster</title>
-
<packages>org.apache.sis.coverage*:org.apache.sis.raster*</packages>
+
<packages>org.apache.sis.coverage*:org.apache.sis.image*</packages>
</group>
<group>
<title>Feature and Geometry</title>
Modified:
sis/branches/JDK8/storage/sis-earth-observation/src/main/java/org/apache/sis/storage/earthobservation/LandsatStore.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK8/storage/sis-earth-observation/src/main/java/org/apache/sis/storage/earthobservation/LandsatStore.java?rev=1804339&r1=1804338&r2=1804339&view=diff
==============================================================================
---
sis/branches/JDK8/storage/sis-earth-observation/src/main/java/org/apache/sis/storage/earthobservation/LandsatStore.java
[UTF-8] (original)
+++
sis/branches/JDK8/storage/sis-earth-observation/src/main/java/org/apache/sis/storage/earthobservation/LandsatStore.java
[UTF-8] Mon Aug 7 14:22:09 2017
@@ -107,7 +107,7 @@ public class LandsatStore extends DataSt
public synchronized Metadata getMetadata() throws DataStoreException {
if (metadata == null && source != null) try {
try (BufferedReader reader = (source instanceof BufferedReader) ?
(BufferedReader) source : new LineNumberReader(source)) {
- source = null; // Will be closed at the end of this
try-catch block.
+ source = null; // Will be closed at the end of this
try-finally block.
final LandsatReader parser = new
LandsatReader(getDisplayName(), listeners);
parser.read(reader);
metadata = parser.getMetadata();
@@ -121,7 +121,11 @@ public class LandsatStore extends DataSt
}
/**
- * This implementation do not provide any resource yet.
+ * Current implementation does not provide any resource yet.
+ * Future versions may return an aggregate of all raster data in the
GeoTIFF files associated with this metadata.
+ *
+ * @return the starting point of all resources in this data store.
+ * @throws DataStoreException if an error occurred while reading the data.
*/
@Override
public Resource getRootResource() throws DataStoreException {
Modified:
sis/branches/JDK8/storage/sis-geotiff/src/main/java/org/apache/sis/storage/geotiff/GeoTiffStore.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK8/storage/sis-geotiff/src/main/java/org/apache/sis/storage/geotiff/GeoTiffStore.java?rev=1804339&r1=1804338&r2=1804339&view=diff
==============================================================================
---
sis/branches/JDK8/storage/sis-geotiff/src/main/java/org/apache/sis/storage/geotiff/GeoTiffStore.java
[UTF-8] (original)
+++
sis/branches/JDK8/storage/sis-geotiff/src/main/java/org/apache/sis/storage/geotiff/GeoTiffStore.java
[UTF-8] Mon Aug 7 14:22:09 2017
@@ -133,7 +133,11 @@ public class GeoTiffStore extends DataSt
}
/**
- * This implementation do not provide any resource yet.
+ * Current implementation does not provide any resource yet.
+ * A future version will return the raster data in a coverage resource.
+ *
+ * @return the starting point of all resources in this data store.
+ * @throws DataStoreException if an error occurred while reading the data.
*/
@Override
public Resource getRootResource() throws DataStoreException {
Added:
sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/AbstractFeatureSet.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/AbstractFeatureSet.java?rev=1804339&view=auto
==============================================================================
---
sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/AbstractFeatureSet.java
(added)
+++
sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/AbstractFeatureSet.java
[UTF-8] Mon Aug 7 14:22:09 2017
@@ -0,0 +1,44 @@
+/*
+ * 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.internal.storage;
+
+import org.apache.sis.storage.DataStore;
+import org.apache.sis.storage.FeatureSet;
+import org.apache.sis.util.logging.WarningListeners;
+
+
+/**
+ * Base implementation of feature sets contained in data stores.
+ *
+ * @author Martin Desruisseaux (Geomatys)
+ * @version 0.8
+ * @since 0.8
+ * @module
+ *
+ * @todo this class may be removed if we refactor {@link FeatureSet} as an
abstract class.
+ */
+public abstract class AbstractFeatureSet extends AbstractResource implements
FeatureSet {
+ /**
+ * Creates a new resource.
+ *
+ * @param owner the data store which contains this resource.
+ * @param listeners the set of registered warning listeners for the data
store.
+ */
+ protected AbstractFeatureSet(final DataStore owner, final
WarningListeners<DataStore> listeners) {
+ super(owner, listeners);
+ }
+}
Propchange:
sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/AbstractFeatureSet.java
------------------------------------------------------------------------------
svn:eol-style = native
Propchange:
sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/AbstractFeatureSet.java
------------------------------------------------------------------------------
svn:mime-type = text/plain;charset=UTF-8
Added:
sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/AbstractResource.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/AbstractResource.java?rev=1804339&view=auto
==============================================================================
---
sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/AbstractResource.java
(added)
+++
sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/AbstractResource.java
[UTF-8] Mon Aug 7 14:22:09 2017
@@ -0,0 +1,111 @@
+/*
+ * 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.internal.storage;
+
+import org.opengis.geometry.Envelope;
+import org.opengis.metadata.Metadata;
+import org.opengis.metadata.extent.Extent;
+import org.opengis.metadata.extent.GeographicBoundingBox;
+import org.opengis.metadata.identification.Identification;
+import org.apache.sis.storage.Resource;
+import org.apache.sis.storage.DataStore;
+import org.apache.sis.storage.DataStoreException;
+import org.apache.sis.geometry.GeneralEnvelope;
+import org.apache.sis.util.logging.WarningListeners;
+import org.opengis.metadata.extent.GeographicExtent;
+
+
+/**
+ * Base implementation of resources contained in data stores.
+ *
+ * @author Martin Desruisseaux (Geomatys)
+ * @version 0.8
+ * @since 0.8
+ * @module
+ *
+ * @todo this class may be removed if we refactor {@link Resource} as an
abstract class.
+ */
+public abstract class AbstractResource implements Resource {
+ /**
+ * The data store which contains this resource.
+ */
+ protected final DataStore owner;
+
+ /**
+ * The set of registered warning listeners for the data store.
+ *
+ * @todo Remove this field if we move {@code AbstractResource} to the
{@code org.apache.sis.storage} package,
+ * since we would be able to access {@code DataStore.listeners}
directly.
+ */
+ private final WarningListeners<DataStore> listeners;
+
+ /**
+ * Creates a new resource.
+ *
+ * @param owner the data store which contains this resource.
+ * @param listeners the set of registered warning listeners for the data
store.
+ */
+ protected AbstractResource(final DataStore owner, final
WarningListeners<DataStore> listeners) {
+ this.owner = owner;
+ this.listeners = listeners;
+ }
+
+ /**
+ * Returns the spatio-temporal envelope of this resource.
+ * The default implementation computes the union of all {@link
GeographicBoundingBox} in the resource metadata,
+ * assuming the {@linkplain
org.apache.sis.referencing.CommonCRS#defaultGeographic() default geographic CRS}
+ * (usually WGS 84).
+ *
+ * @return the spatio-temporal resource extent.
+ * @throws DataStoreException if an error occurred while reading or
computing the envelope.
+ */
+ @Override
+ public Envelope getEnvelope() throws DataStoreException {
+ final Metadata metadata = getMetadata();
+ GeneralEnvelope bounds = null;
+ if (metadata != null) {
+ for (final Identification identification :
metadata.getIdentificationInfo()) {
+ if (identification != null) {
// Paranoiac check.
+ for (final Extent extent : identification.getExtents()) {
+ if (extent != null) {
// Paranoiac check.
+ for (final GeographicExtent ge :
extent.getGeographicElements()) {
+ if (ge instanceof GeographicBoundingBox) {
+ final GeneralEnvelope env = new
GeneralEnvelope((GeographicBoundingBox) ge);
+ if (bounds == null) {
+ bounds = env;
+ } else {
+ bounds.add(env);
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+ return bounds;
+ }
+
+ /**
+ * The set of registered warning listeners for the data store.
+ *
+ * @return the registered warning listeners for the data store.
+ */
+ protected final WarningListeners<DataStore> listeners() {
+ return listeners;
+ }
+}
Propchange:
sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/AbstractResource.java
------------------------------------------------------------------------------
svn:eol-style = native
Propchange:
sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/AbstractResource.java
------------------------------------------------------------------------------
svn:mime-type = text/plain;charset=UTF-8
Modified:
sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/MetadataBuilder.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/MetadataBuilder.java?rev=1804339&r1=1804338&r2=1804339&view=diff
==============================================================================
---
sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/MetadataBuilder.java
[UTF-8] (original)
+++
sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/MetadataBuilder.java
[UTF-8] Mon Aug 7 14:22:09 2017
@@ -52,8 +52,8 @@ import org.opengis.metadata.identificati
import org.opengis.metadata.distribution.Format;
import org.opengis.metadata.quality.Element;
import org.opengis.geometry.DirectPosition;
+import org.opengis.referencing.ReferenceSystem;
import org.opengis.referencing.crs.VerticalCRS;
-import org.opengis.referencing.crs.CoordinateReferenceSystem;
import org.opengis.referencing.operation.TransformException;
import org.apache.sis.geometry.AbstractEnvelope;
import org.apache.sis.metadata.iso.DefaultMetadata;
@@ -1605,7 +1605,7 @@ parse: for (int i = 0; i < length;)
*
* @param crs the coordinate reference system to add to the metadata, or
{@code null} for no-operation.
*/
- public final void addReferenceSystem(final CoordinateReferenceSystem crs) {
+ public final void addReferenceSystem(final ReferenceSystem crs) {
if (crs != null) {
addIfNotPresent(metadata().getReferenceSystemInfo(), crs);
}
Modified:
sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/wkt/Store.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/wkt/Store.java?rev=1804339&r1=1804338&r2=1804339&view=diff
==============================================================================
---
sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/wkt/Store.java
[UTF-8] (original)
+++
sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/wkt/Store.java
[UTF-8] Mon Aug 7 14:22:09 2017
@@ -17,8 +17,8 @@
package org.apache.sis.internal.storage.wkt;
import java.util.List;
-import java.util.ArrayList;
import java.util.Arrays;
+import java.util.ArrayList;
import java.util.logging.Level;
import java.util.logging.LogRecord;
import java.io.Reader;
@@ -33,13 +33,13 @@ import org.apache.sis.internal.storage.R
import org.apache.sis.internal.system.Loggers;
import org.apache.sis.io.wkt.WKTFormat;
import org.apache.sis.io.wkt.Warnings;
+import org.apache.sis.storage.Resource;
import org.apache.sis.storage.DataStore;
import org.apache.sis.storage.StorageConnector;
import org.apache.sis.storage.DataStoreException;
import org.apache.sis.storage.DataStoreContentException;
import org.apache.sis.internal.referencing.DefinitionVerifier;
-import org.apache.sis.metadata.iso.DefaultMetadata;
-import org.apache.sis.storage.Resource;
+import org.apache.sis.internal.storage.MetadataBuilder;
import org.apache.sis.util.resources.Errors;
import org.apache.sis.util.CharSequences;
@@ -172,7 +172,7 @@ final class Store extends DataStore {
/**
* Returns the metadata associated to the parsed objects, or {@code null}
if none.
* The current implementation retains only instances of {@link
ReferenceSystem}
- * and ignore other cases.
+ * and ignore other objects.
*
* @return the metadata associated to the parsed object, or {@code null}
if none.
* @throws DataStoreException if an error occurred during the parsing
process.
@@ -181,20 +181,21 @@ final class Store extends DataStore {
public synchronized Metadata getMetadata() throws DataStoreException {
if (metadata == null) {
parse();
- DefaultMetadata md = null;
+ final MetadataBuilder builder = new MetadataBuilder();
+ builder.addTitle(getDisplayName());
for (final Object object : objects) {
if (object instanceof ReferenceSystem) {
- if (md == null) md = new DefaultMetadata();
- md.getReferenceSystemInfo().add((ReferenceSystem) object);
+ builder.addReferenceSystem((ReferenceSystem) object);
}
}
- metadata = md;
+ metadata = builder.build(true);
}
return metadata;
}
/**
- * This implementation do not provide any resource.
+ * There is currently no resource associated to Well Known Text format
since we parse only CRS.
+ * Future versions may return resources if we parse also geometries.
*/
@Override
public Resource getRootResource() throws DataStoreException {
Modified:
sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/xml/Store.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/xml/Store.java?rev=1804339&r1=1804338&r2=1804339&view=diff
==============================================================================
---
sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/xml/Store.java
[UTF-8] (original)
+++
sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/xml/Store.java
[UTF-8] Mon Aug 7 14:22:09 2017
@@ -30,6 +30,7 @@ import org.opengis.util.FactoryException
import org.opengis.referencing.ReferenceSystem;
import org.opengis.referencing.crs.CoordinateReferenceSystem;
import org.apache.sis.xml.XML;
+import org.apache.sis.storage.Resource;
import org.apache.sis.storage.DataStore;
import org.apache.sis.storage.StorageConnector;
import org.apache.sis.storage.DataStoreException;
@@ -37,11 +38,9 @@ import org.apache.sis.metadata.iso.Defau
import org.apache.sis.util.logging.WarningListener;
import org.apache.sis.util.resources.Errors;
import org.apache.sis.internal.system.Loggers;
+import org.apache.sis.internal.storage.MetadataBuilder;
import org.apache.sis.internal.referencing.DefinitionVerifier;
-import static java.util.Collections.singleton;
-import org.apache.sis.storage.Resource;
-
/**
* A data store which creates data objects from a XML file.
@@ -200,16 +199,18 @@ final class Store extends DataStore {
if (object instanceof Metadata) {
metadata = (Metadata) object;
} else if (object instanceof ReferenceSystem) {
- final DefaultMetadata md = new DefaultMetadata();
- md.setReferenceSystemInfo(singleton((ReferenceSystem) object));
- metadata = md;
+ final MetadataBuilder builder = new MetadataBuilder();
+ builder.addReferenceSystem((ReferenceSystem) object);
+ builder.addTitle(getDisplayName());
+ metadata = builder.build(true);
}
}
return metadata;
}
/**
- * This implementation do not provide any resource.
+ * Current implementation does not provide any resource since it is only
about metadata.
+ * Futures versions may return resources if Apache SIS provides a wider
GML support.
*/
@Override
public Resource getRootResource() throws DataStoreException {
Modified:
sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/Aggregate.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/Aggregate.java?rev=1804339&r1=1804338&r2=1804339&view=diff
==============================================================================
---
sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/Aggregate.java
[UTF-8] (original)
+++
sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/Aggregate.java
[UTF-8] Mon Aug 7 14:22:09 2017
@@ -69,9 +69,7 @@ public interface Aggregate extends Resou
* <blockquote><code><b>this</b>.metadata</code> /
* {@link
org.apache.sis.metadata.iso.DefaultMetadata#getIdentificationInfo()
identificationInfo} /
* {@link
org.apache.sis.metadata.iso.identification.AbstractIdentification#getAssociatedResources()
associatedResource}
- * with {@link
org.opengis.metadata.identification.AssociationType#IS_COMPOSED_OF} /
- * {@link
org.apache.sis.metadata.iso.identification.DefaultAssociatedResource#getName()
name} /
- * {@link org.apache.sis.metadata.iso.citation.DefaultCitation#getTitle()
title}</blockquote>
+ * with {@link
org.opengis.metadata.identification.AssociationType#IS_COMPOSED_OF}</blockquote>
*
* The name of each child resource in the returned collection is given by
the following metadata element:
*
Modified:
sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStore.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStore.java?rev=1804339&r1=1804338&r2=1804339&view=diff
==============================================================================
---
sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStore.java
[UTF-8] (original)
+++
sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStore.java
[UTF-8] Mon Aug 7 14:22:09 2017
@@ -21,14 +21,13 @@ import java.util.Map;
import java.util.IdentityHashMap;
import java.util.NoSuchElementException;
import org.opengis.metadata.Metadata;
-import org.opengis.metadata.citation.Citation;
import org.opengis.metadata.identification.Identification;
import org.apache.sis.util.Localized;
import org.apache.sis.util.ArgumentChecks;
import org.apache.sis.util.logging.WarningListener;
import org.apache.sis.util.logging.WarningListeners;
-import org.apache.sis.internal.metadata.NameToIdentifier;
import org.apache.sis.internal.storage.Resources;
+import org.apache.sis.internal.util.Citations;
/**
@@ -241,8 +240,7 @@ public abstract class DataStore implemen
if (metadata != null) {
for (final Identification identification :
metadata.getIdentificationInfo()) {
if (identification != null) {
// Paranoiac check.
- final Citation citation = identification.getCitation();
- if (citation != null &&
NameToIdentifier.isHeuristicMatchForIdentifier(citation.getIdentifiers(),
identifier)) {
+ if
(Citations.identifierMatches(identification.getCitation(), null, identifier)) {
return candidate;
}
}
Modified:
sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/FeatureSet.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/FeatureSet.java?rev=1804339&r1=1804338&r2=1804339&view=diff
==============================================================================
---
sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/FeatureSet.java
[UTF-8] (original)
+++
sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/FeatureSet.java
[UTF-8] Mon Aug 7 14:22:09 2017
@@ -24,8 +24,9 @@ import org.opengis.feature.FeatureType;
/**
* A dataset providing access to a stream of features.
* All features share a common set of properties described by {@link
#getType()}.
- * Each {@linkplain org.apache.sis.feature.AbstractFeature feature instance}
can be associated to a geometry,
- * but not necessarily. The geometries (if any) may or may not be parts of a
coverage.
+ * The common set of properties does not need to enumerate all possible
properties since additional properties
+ * can be defined in subtypes. In many cases at least one property is a
geometry, but features without geometry
+ * are also allowed.
*
* @author Johann Sorel (Geomatys)
* @version 0.8
@@ -44,6 +45,24 @@ public interface FeatureSet extends Data
* <li>{@linkplain org.opengis.referencing.crs.CoordinateReferenceSystem
Coordinate Reference System}.</li>
* </ul>
*
+ * All features returned by {@link #features(boolean)} will be either of
that type, or a sub-type of it.
+ *
+ * <div class="note"><b>Relationship with metadata:</b>
+ * if subtypes exist, their list may be obtained from the {@linkplain
#getMetadata() metadata} like below
+ * (if the {@code FeatureSet} implementation provides that information):
+ *
+ * {@preformat java
+ * for (ContentInformation content : metadata.getContentInfo()) {
+ * if (content instanceof FeatureCatalogueDescription) {
+ * for (FeatureTypeInfo info : ((FeatureCatalogueDescription)
content).getFeatureTypeInfo()) {
+ * GenericName name = info.getFeatureTypeName();
+ * // ... add the name to some list ...
+ * }
+ * }
+ * }
+ * }
+ * </div>
+ *
* @return description of common properties (never {@code null}).
* @throws DataStoreException if an error occurred while reading
definitions from the underlying data store.
*/
@@ -58,12 +77,13 @@ public interface FeatureSet extends Data
*
* Most implementations will create {@code Feature} instances on-the-fly
when the stream terminal operation is executed.
* A {@code try} … {@code finally} block should be used for releasing
{@link DataStore} resources used by the operation.
- * If an error happen during stream execution, an unchecked {@link
org.apache.sis.util.collection.BackingStoreException}
- * will be thrown. The following code shows how this stream can be used:
+ * If a checked exception happens during stream execution, that exception
will be wrapped in an unchecked
+ * {@link org.apache.sis.util.collection.BackingStoreException}.
+ * The following code shows how this stream can be used:
*
* {@preformat java
* void myReadOperation() throws DataStoreException {
- * try (Stream<Feature> features = myDataStore.features()) {
+ * try (Stream<Feature> features = myDataStore.features(false)) {
* // Use the stream here.
* } catch (BackingStoreException e) {
* throw e.unwrapOrRethrow(DataStoreException.class);
@@ -71,11 +91,13 @@ public interface FeatureSet extends Data
* }
* }
*
- * For performance reasons, some {@code Feature} instances may be recycled
during stream execution.
- * Consequently if the caller needs to keep property values, (s)he should
copy the data in her own structure.
+ * The {@code parallel} argument specifies whether a parallelized stream
is desired. If {@code false}, the stream
+ * is guaranteed to be sequential. If {@code true}, the stream may or may
not be parallel; implementations are free
+ * to ignore this argument if they do not support parallelism.
*
+ * @param parallel {@code true} for a parallel stream (if supported), or
{@code false} for a sequential stream.
* @return all features contained in this dataset.
* @throws DataStoreException if an error occurred while creating the
stream.
*/
- Stream<Feature> features() throws DataStoreException;
+ Stream<Feature> features(boolean parallel) throws DataStoreException;
}
