You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sis.apache.org by de...@apache.org on 2017/08/04 22:55:04 UTC
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/
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;
-
}