sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1804191 - in /sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage: Aggregate.java DataSet.java DataStore.java FeatureSet.java Resource.java
Date Sat, 05 Aug 2017 15:11:48 GMT
Author: desruisseaux
Date: Sat Aug  5 15:11:48 2017
New Revision: 1804191

URL: http://svn.apache.org/viewvc?rev=1804191&view=rev
Log:
Complete javadoc for the Resource subtypes.

Modified:
    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/DataSet.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
    sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/Resource.java

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=1804191&r1=1804190&r2=1804191&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] Sat Aug  5 15:11:48 2017
@@ -18,18 +18,69 @@ package org.apache.sis.storage;
 
 import java.util.Collection;
 
+
 /**
- * An Aggregate is a resources which references a list of children resources.
+ * A collection of resources. An aggregate can have two or more components.
+ * Each component can be another aggregate, thus forming a tree of resources.
+ * Different kinds of aggregate may exist for various reasons, for example (adapted from
ISO 19115):
+ *
+ * <ul class="verbose">
+ *   <li><b>Series:</b> a generic collection of resources that share similar
characteristics
+ *       (theme, date, resolution, <i>etc.</i>). The exact definition is determined
by the data provider.
+ *       See {@link org.opengis.metadata.maintenance.ScopeCode#SERIES} for more examples.</li>
+ *   <li><b>Sensor series:</b> a collection of resources observed by the
same sensor.</li>
+ *   <li><b>Platform series:</b> a collection of resources observed by
sensors installed on the same platform.
+ *       The {@linkplain #components() components} of a platform series are <cite>sensor
series</cite>.
+ *       Those components usually share the same geospatial geometry.</li>
+ *   <li><b>Production series:</b> a collection of resources produced using
the same process. Members of a production
+ *       series share {@linkplain org.apache.sis.metadata.iso.DefaultMetadata#getResourceLineages()
lineage} and
+ *       {@linkplain org.apache.sis.metadata.iso.lineage.DefaultLineage#getProcessSteps()
processing history}.</li>
+ *   <li><b>Initiative:</b> a collection of resources related by their
participation in a common initiative.</li>
+ *   <li><b>Transfer aggregate:</b> a set of resources collected for the
purpose of transfer.
+ *       The {@linkplain #components() components} may be the results of an ad hoc query,
for example on a Web Service.</li>
+ * </ul>
+ *
+ * The same resource may be part of more than one aggregate. For example the same resource
could be part of
+ * a <cite>production series</cite> and a <cite>transfer aggregate</cite>.
In Apache SIS implementation,
+ * those two kinds of aggregate will usually be created by different {@link DataStore} instances.
  *
- * @author Johann Sorel (Geomatys)
+ * <div class="section">Metadata</div>
+ * Aggregates should have {@link #getMetadata() metadata} /
+ * {@link org.apache.sis.metadata.iso.DefaultMetadata#getMetadataScopes() metadataScope}
/
+ * {@link org.apache.sis.metadata.iso.DefaultMetadataScope#getResourceScope() resourceScope}
sets to
+ * {@link org.opengis.metadata.maintenance.ScopeCode#SERIES} or
+ * {@link org.opengis.metadata.maintenance.ScopeCode#INITIATIVE} if applicable.
+ * If not too expensive to compute, the names of all components should be listed as
+ * {@linkplain org.apache.sis.metadata.iso.identification.AbstractIdentification#getAssociatedResources()
+ * associated resources} with an {@link org.opengis.metadata.identification.AssociationType#IS_COMPOSED_OF}
relation.
+ *
+ * @author  Johann Sorel (Geomatys)
+ * @version 0.8
+ * @since   0.8
+ * @module
  */
 public interface Aggregate extends Resource {
-
     /**
-     * List children resources of this aggregate.
+     * Returns the children resources of this aggregate. The returned collection contains
at least all
+     * the resources listed by their name in the following {@linkplain #getMetadata() metadata}
elements.
+     * The returned collection may contain more resources if the metadata are incomplete,
+     * and the resources do not need to be in the same order:
      *
-     * @return collection of children {@link Resource}, never null, can be empty
+     * <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>
+     *
+     * The name of each child resource in the returned collection is given by the following
metadata element:
+     *
+     * <blockquote><code><b>child</b>.metadata</code> /
+     * {@link org.apache.sis.metadata.iso.DefaultMetadata#getIdentificationInfo() identificationInfo}
/
+     * {@link org.apache.sis.metadata.iso.identification.AbstractIdentification#getCitation()
citation} /
+     * {@link org.apache.sis.metadata.iso.citation.DefaultCitation#getTitle() title}</blockquote>
+     *
+     * @return all children resources that are components of this aggregate. Never {@code
null}.
      */
     Collection<Resource> components();
-
 }

Modified: sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/DataSet.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/DataSet.java?rev=1804191&r1=1804190&r2=1804191&view=diff
==============================================================================
--- sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/DataSet.java
[UTF-8] (original)
+++ sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/DataSet.java
[UTF-8] Sat Aug  5 15:11:48 2017
@@ -18,12 +18,31 @@ package org.apache.sis.storage;
 
 
 /**
- * A dataset is a resource which manage a data type.
- * Multiple subtypes may exist.
+ * Collection of features that share a common set of attributes or properties.
+ * Features may be organized in coverages, but not necessarily.
+ * The common set of properties is described by {@linkplain org.apache.sis.feature.DefaultFeatureType
feature types},
+ * grid geometries or sample dimensions, depending on the {@code DataSet} subtype.
+ * The actual values are provided by methods defined in {@code DataSet} subtypes.
  *
- * @author Johann Sorel (Geomatys)
+ * <div class="note"><b>Example:</b>
+ * the features contained in a {@code DataSet} could be all bridges in a city. A {@code DataSet}
can be associated to
+ * one {@code FeatureType} which specifies that all bridges shall have {@code "construction
date"} and {@code "height"}
+ * attributes, and an arbitrary amount of {@code Feature} instances which contains the actual
values for all bridges in
+ * the dataset.</div>
+ *
+ * <div class="section">Metadata</div>
+ * Datasets should have {@link #getMetadata() metadata} /
+ * {@link org.apache.sis.metadata.iso.DefaultMetadata#getMetadataScopes() metadataScope}
/
+ * {@link org.apache.sis.metadata.iso.DefaultMetadataScope#getResourceScope() resourceScope}
sets to
+ * {@link org.opengis.metadata.maintenance.ScopeCode#DATASET}.
+ * If this datasets is part of a series or an {@link Aggregate}, the aggregate name should
be declared
+ * as the {@linkplain org.apache.sis.metadata.iso.DefaultMetadata#getParentMetadata() parent
metadata}.
+ * That parent metadata is often the same instance than {@link DataStore#getMetadata()}.
+ *
+ * @author  Johann Sorel (Geomatys)
+ * @version 0.8
+ * @since   0.8
+ * @module
  */
 public interface DataSet extends Resource {
-
-
 }

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=1804191&r1=1804190&r2=1804191&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] Sat Aug  5 15:11:48 2017
@@ -197,14 +197,25 @@ public abstract class DataStore implemen
     public abstract Resource getRootResource() throws DataStoreException;
 
     /**
-     * Search for a resource identified by given name.
+     * Searches for a resource identified by the given identifier.
+     * The given identifier should match the following metadata element of a resource:
+     *
+     * <blockquote>{@link Resource#getMetadata() metadata} /
+     * {@link org.apache.sis.metadata.iso.DefaultMetadata#getIdentificationInfo() identificationInfo}
/
+     * {@link org.apache.sis.metadata.iso.identification.AbstractIdentification#getCitation()
citation} /
+     * {@link org.apache.sis.metadata.iso.citation.DefaultCitation#getIdentifiers() identifier}</blockquote>
+     *
+     * The default implementation verifies the {@linkplain #getRootResource() root resource},
then iterates over all
+     * components of all {@link Aggregate}s. If exactly one match is found, the associated
resource is returned.
+     * Otherwise an exception is thrown. Subclasses are encouraged to override this method
with a more efficient
+     * implementation.
      *
      * @param  name  identifier of the data to acquire. Must be non-null.
-     * @return resource associated to the given input name, never null.
-     * @throws DataStoreException if an error occurred while reading the data.
-     * @throws IllegalNameException if input name is not found.
+     * @return resource associated to the given identifier (never {@code null}).
+     * @throws IllegalNameException if no resource is found for the given identifier, or
if more than one resource is found.
+     * @throws DataStoreException if another kind of error occurred while searching resources.
      */
-    public Resource findResource(final String name) throws DataStoreException, IllegalNameException
{
+    public Resource findResource(final String name) throws DataStoreException {
         ArgumentChecks.ensureNonEmpty("Name of the searched resource", name);
 
         final Resource root = getRootResource();

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=1804191&r1=1804190&r2=1804191&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] Sat Aug  5 15:11:48 2017
@@ -20,34 +20,62 @@ import java.util.stream.Stream;
 import org.opengis.feature.Feature;
 import org.opengis.feature.FeatureType;
 
+
 /**
- * Specialized type of DataSet which manage features.
+ * 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.
  *
- * @author Johann Sorel (Geomatys)
+ * @author  Johann Sorel (Geomatys)
+ * @version 0.8
+ * @since   0.8
+ * @module
  */
 public interface FeatureSet extends DataSet {
-
     /**
-     * Get dataset feature type.
-     * The feature type contains the definition of all fields, including but not only :
+     * Returns a description of properties that are common to all features in this dataset.
+     * The feature type contains the definition of all properties, including but not only:
      * <ul>
-     * <li>description</li>
-     * <li>primitive type</li>
-     * <li>cardinality</li>
-     * <li>{@link org.opengis.referencing.crs.CoordinateReferenceSystem}</li>
+     *   <li>Name to use for accessing the property</li>
+     *   <li>Human-readable description</li>
+     *   <li>Type of values</li>
+     *   <li>Cardinality (minimum and maximum number of occurrences)</li>
+     *   <li>{@linkplain org.opengis.referencing.crs.CoordinateReferenceSystem Coordinate
Reference System}.</li>
      * </ul>
      *
-     * @return the feature type, never null.
-     * @throws DataStoreException if an I/O or decoding error occurs.
+     * @return description of common properties (never {@code null}).
+     * @throws DataStoreException if an error occurred while reading definitions from the
underlying data store.
      */
     FeatureType getType() throws DataStoreException;
 
     /**
-     * Reads features from the dataset.
+     * Returns a stream of all features contained in this dataset.
+     * For all features, the following condition shall be true:
+     *
+     * <blockquote><code>{@linkplain #getType()}.{@linkplain org.apache.sis.feature.DefaultFeatureType#isAssignableFrom
+     * isAssignableFrom}(feature.{@linkplain org.apache.sis.feature.AbstractFeature#getType()
getType()})</code></blockquote>
+     *
+     * 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:
      *
-     * @return stream of features.
-     * @throws DataStoreException if an I/O or decoding error occurs.
+     * {@preformat java
+     *     void myReadOperation() throws DataStoreException {
+     *         try (Stream<Feature> features = myDataStore.features()) {
+     *             // Use the stream here.
+     *         } catch (BackingStoreException e) {
+     *             throw e.unwrapOrRethrow(DataStoreException.class);
+     *         }
+     *     }
+     * }
+     *
+     * 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.
+     *
+     * @return all features contained in this dataset.
+     * @throws DataStoreException if an error occurred while creating the stream.
      */
     Stream<Feature> features() throws DataStoreException;
-
 }

Modified: sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/Resource.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/Resource.java?rev=1804191&r1=1804190&r2=1804191&view=diff
==============================================================================
--- sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/Resource.java
[UTF-8] (original)
+++ sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/Resource.java
[UTF-8] Sat Aug  5 15:11:48 2017
@@ -45,7 +45,7 @@ import org.opengis.metadata.Metadata;
  * @version 0.8
  *
  * @see DataStore#getRootResource()
- * @see org.apache.sis.metadata.iso.identification.AbstractIdentification#getAssociatedResources()
+ * @see Aggregate#components()
  *
  * @since 0.8
  * @module
@@ -55,6 +55,12 @@ public interface Resource {
      * Returns information about this resource.
      * If this resource is the {@linkplain DataStore#getRootResource() data store root resource},
      * then this method may return the same metadata instance than {@link DataStore#getMetadata()}.
+     * If this resource is an {@link Aggregate}, then the metadata may enumerate characteristics
+     * (spatio-temporal extents, feature types, range dimensions, <i>etc.</i>)
of all
+     * {@linkplain Aggregate#components() components} in the aggregate, or summarize them
(for example by omitting
+     * {@linkplain org.apache.sis.metadata.iso.extent.DefaultExtent extents} that are fully
included in larger extents).
+     * If this resource is a {@link DataSet}, then the metadata shall contain only the information
that apply to that
+     * particular dataset, optionally with a reference to the parent metadata (see below).
      *
      * <p>Some relationships between metadata and resources are:</p>
      * <ul class="verbose">
@@ -72,7 +78,16 @@ public interface Resource {
      *       {@link org.apache.sis.metadata.iso.identification.AbstractIdentification#getAssociatedResources()
associatedResource} /
      *       {@link org.apache.sis.metadata.iso.identification.DefaultAssociatedResource#getName()
name} /
      *       {@link org.apache.sis.metadata.iso.citation.DefaultCitation#getTitle() title}:<br>
-     *       a human-readable designation for parent, children or other related resources.</li>
+     *       a human-readable designation for parent, children or other related resources.
+     *       May be omitted if too expensive to compute.</li>
+     *   <li>{@code metadata} /
+     *       {@link org.apache.sis.metadata.iso.DefaultMetadata#getMetadataScopes() metadataScope}
/
+     *       {@link org.apache.sis.metadata.iso.DefaultMetadataScope#getResourceScope() resourceScope}:<br>
+     *       {@link org.opengis.metadata.maintenance.ScopeCode#DATASET} if the resource is
a {@link DataSet}, or
+     *       {@link org.opengis.metadata.maintenance.ScopeCode#SERVICE} if the resource is
a web service, or
+     *       {@link org.opengis.metadata.maintenance.ScopeCode#SERIES} or
+     *       {@link org.opengis.metadata.maintenance.ScopeCode#INITIATIVE}
+     *       if the resource is an {@link Aggregate} other than a transfer aggregate.</li>
      *   <li>{@code metadata} /
      *       {@link org.apache.sis.metadata.iso.DefaultMetadata#getContentInfo() contentInfo}
/
      *       {@link org.apache.sis.metadata.iso.content.DefaultFeatureCatalogueDescription#getFeatureTypeInfo()
featureType} /
@@ -98,7 +113,8 @@ public interface Resource {
      * The following relationship to {@linkplain #getMetadata()} should hold:
      *
      * <ul>
-     *   <li>The envelope should be contained in the geographic, vertical or temporal
extents described by {@code metadata} /
+     *   <li>The envelope should be contained in the union of all geographic, vertical
or temporal extents
+     *       described by {@code metadata} /
      *       {@link org.apache.sis.metadata.iso.DefaultMetadata#getIdentificationInfo() identificationInfo}
/
      *       {@link org.apache.sis.metadata.iso.identification.AbstractIdentification#getExtents()
extent}.</li>
      *   <li>The coordinate reference system should be one of the instances returned
by
@@ -109,10 +125,11 @@ public interface Resource {
      * that most closely matches the geometry of the resource storage. It is often a
      * {@linkplain org.apache.sis.referencing.crs.DefaultProjectedCRS projected CRS}, but
other types like
      * {@linkplain org.apache.sis.referencing.crs.DefaultEngineeringCRS engineering CRS}
are also allowed.
-     * The envelope may contain supplemental dimensions after the spatio-temporal ones.
+     * If this resource uses many different CRS with none of them covering all data, then
the envelope should use a
+     * global system (typically a {@linkplain org.apache.sis.referencing.crs.DefaultGeocentricCRS
geographic CRS}).
      *
      * @return the spatio-temporal resource extent. Should not be {@code null}.
-     * @throws DataStoreException if an error occurred while reading the metadata.
+     * @throws DataStoreException if an error occurred while reading or computing the envelope.
      */
     Envelope getEnvelope() throws DataStoreException;
 }



Mime
View raw message