sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1804163 - in /sis/branches/JDK8: core/sis-feature/src/main/java/org/apache/sis/feature/ storage/sis-storage/src/main/java/org/apache/sis/storage/
Date Fri, 04 Aug 2017 22:55:04 GMT
Author: desruisseaux
Date: Fri Aug  4 22:55:03 2017
New Revision: 1804163

URL: http://svn.apache.org/viewvc?rev=1804163&view=rev
Log:
Minor code adjustement and add documentation.

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

Modified: sis/branches/JDK8/core/sis-feature/src/main/java/org/apache/sis/feature/FeatureFormat.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-feature/src/main/java/org/apache/sis/feature/FeatureFormat.java?rev=1804163&r1=1804162&r2=1804163&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-feature/src/main/java/org/apache/sis/feature/FeatureFormat.java
[UTF-8] (original)
+++ sis/branches/JDK8/core/sis-feature/src/main/java/org/apache/sis/feature/FeatureFormat.java
[UTF-8] Fri Aug  4 22:55:03 2017
@@ -535,7 +535,7 @@ public class FeatureFormat extends Tabul
                                             }
                                             try {
                                                 final int n = MathFunctions.toNanOrdinal(f);
-                                                if (n > 0) buffer.append(" #").append(n);
+                                                if (n > 0) t.append(" #").append(n);
                                             } catch (IllegalArgumentException e) {
                                                 // May happen if the NaN is a signaling NaN
instead than a quiet NaN.
                                                 final int bits = Float.floatToRawIntBits(f);

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=1804163&r1=1804162&r2=1804163&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] Fri Aug  4 22:55:03 2017
@@ -171,20 +171,28 @@ public abstract class DataStore implemen
     }
 
     /**
-     * Returns information about the dataset as a whole. The returned metadata object, if
any, can contain
-     * information such as the spatiotemporal extent of the dataset, contact information
about the creator
-     * or distributor, data quality, update frequency, usage constraints and more.
+     * Returns information about the data store as a whole. The returned metadata object
can contain
+     * information such as the spatiotemporal extent of all contained {@linkplain Resource
resources},
+     * contact information about the creator or distributor, data quality, update frequency,
usage constraints,
+     * file format and more.
      *
-     * @return information about the dataset, or {@code null} if none.
+     * @return information about resources in the data store, or {@code null} if none.
      * @throws DataStoreException if an error occurred while reading the data.
+     *
+     * @see Resource#getMetadata()
      */
     public abstract Metadata getMetadata() throws DataStoreException;
 
     /**
-     * Get root data store resource.
+     * Returns the starting point from which all resources in this data store can be accessed.
+     * A resource can be for example a air temperature map or the set of all bridges in a
city.
+     * If this data store contains only one resource, then that resource is returned directly.
+     * Otherwise if this data store contains more than one resource, then this method returns
+     * an {@link Aggregate} from which other resources can be accessed.
      *
-     * @return Resource, may be null
-     * @throws DataStoreException if an I/O or decoding error occurs.
+     * @return the starting point of all resources in this data store,
+     *         or {@code null} if this data store does not contains any resources.
+     * @throws DataStoreException if an error occurred while reading the data.
      */
     public abstract Resource getRootResource() throws DataStoreException;
 
@@ -193,7 +201,7 @@ public abstract class DataStore implemen
      *
      * @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 I/O error occurs
+     * @throws DataStoreException if an error occurred while reading the data.
      * @throws IllegalNameException if input name is not found.
      */
     public Resource findResource(final String name) throws DataStoreException, IllegalNameException
{

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=1804163&r1=1804162&r2=1804163&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] Fri Aug  4 22:55:03 2017
@@ -19,28 +19,100 @@ package org.apache.sis.storage;
 import org.opengis.geometry.Envelope;
 import org.opengis.metadata.Metadata;
 
+
 /**
- * A resource is an accessor to geospatial data.
- * The user should test if the resource is a {@code CoverageResource} or {@code FeatureResource}.
+ * Provides access to geospatial data in a {@code DataStore}. The ISO 19115 specification
defines resource as
+ * an <cite>“identifiable asset or means that fulfills a requirement”</cite>.
For example a resource can be a
+ * coverage of Sea Surface Temperature, or a coverage of water salinity, or the set of all
buoys in a harbor,
+ * or an aggregation of all the above. A resource is not necessarily digital; it can be a
paper document or an
+ * organization, in which case only metadata are provided. If the resource is digital, then
{@code Resource}s
+ * should be instances of sub-types like {@link Aggregate} or {@link FeatureSet}.
+ *
+ * <p>The resources contained in a data store can be obtained by a call to {@link DataStore#getRootResource()}.
+ * If the data store contains resources for many feature types or coverages, then the root
resource will be an
+ * instance of {@link Aggregate}. The {@linkplain Aggregate#components() components} of an
aggregate can be
+ * themselves other aggregates, thus forming a tree.</p>
+ *
+ * <div class="note"><b>Relationship with ISO 19115:</b>
+ * this type is closely related to the {@code DS_Resource} type defined by ISO 19115.
+ * The Apache SIS type differs from the ISO type by being more closely related to data extraction,
+ * as can been seen from the checked {@link DataStoreException} thrown by most methods.
+ * Convenience methods for frequently requested information – for example {@link #getEnvelope()}
– were added.
+ * The sub-types performing the actual data extraction – for example {@link FeatureSet}
– are specific to Apache SIS.
+ * </div>
  *
- * @author Johann Sorel (Geomatys)
+ * @author  Johann Sorel (Geomatys)
+ * @version 0.8
+ *
+ * @see DataStore#getRootResource()
+ * @see org.apache.sis.metadata.iso.identification.AbstractIdentification#getAssociatedResources()
+ *
+ * @since 0.8
+ * @module
  */
 public interface Resource {
-
     /**
-     * Gets resource metadata object.
+     * 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()}.
      *
-     * @return metadata about the resource, never null.
-     * @throws DataStoreException if an I/O error occurs.
+     * <p>Some relationships between metadata and resources are:</p>
+     * <ul class="verbose">
+     *   <li>{@code metadata} /
+     *       {@link org.apache.sis.metadata.iso.DefaultMetadata#getParentMetadata() parentMetadata}
/
+     *       {@link org.apache.sis.metadata.iso.citation.DefaultCitation#getTitle() title}:<br>
+     *       a human-readable caption for {@link DataStore#getMetadata()} (if not redundant
with this metadata).</li>
+     *   <li>{@code 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#getTitle() title}:<br>
+     *       a human-readable designation for this resource.</li>
+     *   <li>{@code metadata} /
+     *       {@link org.apache.sis.metadata.iso.DefaultMetadata#getIdentificationInfo() identificationInfo}
/
+     *       {@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>
+     *   <li>{@code metadata} /
+     *       {@link org.apache.sis.metadata.iso.DefaultMetadata#getContentInfo() contentInfo}
/
+     *       {@link org.apache.sis.metadata.iso.content.DefaultFeatureCatalogueDescription#getFeatureTypeInfo()
featureType} /
+     *       {@link org.apache.sis.metadata.iso.content.DefaultFeatureTypeInfo#getFeatureTypeName()
featureTypeName}:<br>
+     *       names of feature types included in this resource. Example: “bridge”, “road”,
“river”. <i>etc.</i></li>
+     *   <li>{@code metadata} /
+     *       {@link org.apache.sis.metadata.iso.DefaultMetadata#getContentInfo() contentInfo}
/
+     *       {@link org.apache.sis.metadata.iso.content.DefaultCoverageDescription#getAttributeGroups()
attributeGroup} /
+     *       {@link org.apache.sis.metadata.iso.content.DefaultAttributeGroup#getAttributes()
attribute} /
+     *       {@link org.apache.sis.metadata.iso.content.DefaultRangeDimension#getSequenceIdentifier()
sequenceIdentifier}:<br>
+     *       sample dimension names (or band numbers in simpler cases) of coverages or rasters
included in this resource.</li>
+     * </ul>
+     *
+     * @return information about this resource. Should not be {@code null}.
+     * @throws DataStoreException if an error occurred while reading the metadata.
+     *
+     * @see DataStore#getMetadata()
      */
     Metadata getMetadata() throws DataStoreException;
 
     /**
-     * Returns the spatio-temporal envelope of this resource.
+     * Returns the spatio-temporal extent of this resource in its most natural coordinate
reference system.
+     * 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} /
+     *       {@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
+     *       {@link org.apache.sis.metadata.iso.DefaultMetadata#getReferenceSystemInfo()
referenceSystemInfo}.</li>
+     * </ul>
      *
-     * @return the spatio-temporal envelope, never null.
-     * @throws DataStoreException if an I/O or decoding error occurs.
+     * The envelope should use the coordinate reference system (CRS)
+     * 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.
+     *
+     * @return the spatio-temporal resource extent. Should not be {@code null}.
+     * @throws DataStoreException if an error occurred while reading the metadata.
      */
     Envelope getEnvelope() throws DataStoreException;
-
 }



Mime
View raw message