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;
 }


Reply via email to