This is an automated email from the ASF dual-hosted git repository.
desruisseaux pushed a commit to branch geoapi-4.0
in repository https://gitbox.apache.org/repos/asf/sis.git
The following commit(s) were added to refs/heads/geoapi-4.0 by this push:
new ced1aae Clarifications in documentation.
ced1aae is described below
commit ced1aae9afb015187fa214da6f1bbb7dc31ed763
Author: Martin Desruisseaux <[email protected]>
AuthorDate: Sun Mar 24 21:59:11 2019 +0100
Clarifications in documentation.
---
.../apache/sis/storage/GridCoverageResource.java | 11 ++-
.../sis/storage/IllegalFeatureTypeException.java | 3 +
.../org/apache/sis/storage/WritableAggregate.java | 4 +-
.../org/apache/sis/storage/WritableFeatureSet.java | 43 +++++++-----
.../sis/storage/WritableGridCoverageResource.java | 78 +++++++++++++++-------
5 files changed, 98 insertions(+), 41 deletions(-)
diff --git
a/storage/sis-storage/src/main/java/org/apache/sis/storage/GridCoverageResource.java
b/storage/sis-storage/src/main/java/org/apache/sis/storage/GridCoverageResource.java
index b9f273b..1c9cb2e 100644
---
a/storage/sis-storage/src/main/java/org/apache/sis/storage/GridCoverageResource.java
+++
b/storage/sis-storage/src/main/java/org/apache/sis/storage/GridCoverageResource.java
@@ -24,7 +24,16 @@ import org.apache.sis.coverage.grid.GridCoverage;
/**
* Access to data values in a <var>n</var>-dimensional grid.
- * A coverage resource may be a member of {@link Aggregate} if a single file
can provide many images.
+ * A coverage is a kind of function with the following properties:
+ *
+ * <ul class="verbose">
+ * <li>The function input is a position valid in the coverage
<cite>domain</cite>. In the particular case of
+ * {@link GridCoverage}, the domain is described by a {@linkplain
#getGridGeometry() grid geometry}.</li>
+ * <li>The function output is a record of values in the coverage
<cite>range</cite>. In the particular case of
+ * {@link GridCoverage}, the range is described by a list of {@linkplain
#getSampleDimensions() sample dimensions}.</li>
+ * </ul>
+ *
+ * A coverage resource may be a member of {@link Aggregate} if a single file
can provide many rasters.
*
* @author Martin Desruisseaux (Geomatys)
* @version 1.0
diff --git
a/storage/sis-storage/src/main/java/org/apache/sis/storage/IllegalFeatureTypeException.java
b/storage/sis-storage/src/main/java/org/apache/sis/storage/IllegalFeatureTypeException.java
index 667b6f3..267c21a 100644
---
a/storage/sis-storage/src/main/java/org/apache/sis/storage/IllegalFeatureTypeException.java
+++
b/storage/sis-storage/src/main/java/org/apache/sis/storage/IllegalFeatureTypeException.java
@@ -23,6 +23,9 @@ import org.opengis.util.GenericName;
/**
* Thrown when a store can not write the given feature because its type is not
one of the supported types.
+ * The {@link org.opengis.feature.FeatureType} is given by {@link
org.opengis.feature.Feature#getType()},
+ * and the type expected by the data store is given by {@link
FeatureSet#getType()}. Those two values must
+ * match, except when the type of the feature set is {@linkplain
WritableFeatureSet#updateType updated}.
*
* @author Martin Desruisseaux (Geomatys)
* @version 0.8
diff --git
a/storage/sis-storage/src/main/java/org/apache/sis/storage/WritableAggregate.java
b/storage/sis-storage/src/main/java/org/apache/sis/storage/WritableAggregate.java
index e8f3614..45b9d3a 100644
---
a/storage/sis-storage/src/main/java/org/apache/sis/storage/WritableAggregate.java
+++
b/storage/sis-storage/src/main/java/org/apache/sis/storage/WritableAggregate.java
@@ -18,7 +18,8 @@ package org.apache.sis.storage;
/**
- * An {@linkplain Aggregate} with writing capabilities.
+ * An {@link Aggregate} with writing capabilities. {@code WritableAggregate}
inherits the reading capabilities from its
+ * parent and adds the capabilities to {@linkplain #add(Resource) add} or
{@linplain #remove(Resource) remove} resources.
*
* @author Johann Sorel (Geomatys)
* @version 1.0
@@ -31,6 +32,7 @@ public interface WritableAggregate extends Aggregate {
* The given {@link Resource} will be copied, and the <cite>effectively
added</cite> resource returned.
* The effectively added resource may differ from the given resource in
many aspects.
* The possible changes may include the followings but not only:
+ *
* <ul>
* <li>types and properties names</li>
* <li>{@link org.opengis.referencing.crs.CoordinateReferenceSystem}</li>
diff --git
a/storage/sis-storage/src/main/java/org/apache/sis/storage/WritableFeatureSet.java
b/storage/sis-storage/src/main/java/org/apache/sis/storage/WritableFeatureSet.java
index 68cd591..29cc254 100644
---
a/storage/sis-storage/src/main/java/org/apache/sis/storage/WritableFeatureSet.java
+++
b/storage/sis-storage/src/main/java/org/apache/sis/storage/WritableFeatureSet.java
@@ -27,7 +27,9 @@ import org.opengis.feature.FeatureType;
/**
- * Subtype of {@linkplain FeatureSet} with writing capabilities.
+ * A {@link FeatureSet} with writing capabilities. {@code WritableFeatureSet}
inherits the reading capabilities from
+ * its parent and adds the capabilities to {@linkplain #add(Iterator) add},
{@linkplain #removeIf(Predicate) remove}
+ * or {@linkplain #replaceIf(Predicate, UnaryOperator) replace} feature
instances.
*
* @author Johann Sorel (Geomatys)
* @version 1.0
@@ -49,11 +51,20 @@ public interface WritableFeatureSet extends FeatureSet {
* @throws IllegalFeatureTypeException if the given type is not compatible
with the types supported by the store.
* @throws DataStoreException if another error occurred while changing the
feature type.
*/
- void updateType(FeatureType newType) throws IllegalFeatureTypeException,
DataStoreException;
+ void updateType(FeatureType newType) throws DataStoreException;
/**
- * Inserts new features in this {@code FeatureSet}.
- * Any feature already present in the {@link FeatureSet} will remain
unmodified.
+ * Inserts new feature instances in this {@code FeatureSet}.
+ * Any feature already present in this {@link FeatureSet} will remain
unmodified.
+ * If a {@linkplain Feature#getProperty feature property} is used as
unique identifier, then:
+ *
+ * <ul>
+ * <li>If a given feature assigns to that property a value already in
use, an exception will be thrown.</li>
+ * <li>If given features do not assign value to that property,
identifiers should be generated by the data store.</li>
+ * </ul>
+ *
+ * After successful insertion, the new features may appear after the
features already present
+ * but not necessarily; ordering is {@link DataStore} specific.
*
* <div class="note"><b>API note:</b>
* this method expects an {@link Iterator} rather then a {@link Stream}
for easing
@@ -61,36 +72,38 @@ public interface WritableFeatureSet extends FeatureSet {
* than implementing a {@link Stream}. On the other side if the user has a
{@link Stream},
* obtaining an {@link Iterator} can be done by a call to {@link
Stream#iterator()}.</div>
*
- * @param features features to insert in this {@code FeatureSet}.
+ * @param features feature instances to insert or copy in this {@code
FeatureSet}.
+ * @throws IllegalFeatureTypeException if a feature given by the iterator
is not of the type expected by this {@code FeatureSet}.
* @throws DataStoreException if another error occurred while storing new
features.
*/
void add(Iterator<? extends Feature> features) throws DataStoreException;
/**
- * Removes all features from this {@code FeatureSet} which matches the
given predicate.
+ * Removes all feature instances from this {@code FeatureSet} which
matches the given predicate.
*
- * @param filter a predicate which returns true for resources to be
removed.
+ * @param filter a predicate which returns {@code true} for feature
instances to be removed.
* @return {@code true} if any elements were removed.
- * @throws DataStoreException if another error occurred while removing
features.
+ * @throws DataStoreException if an error occurred while removing features.
*/
boolean removeIf(Predicate<? super Feature> filter) throws
DataStoreException;
/**
- * Updates all features from this {@code FeatureSet} which matches the
given predicate.
+ * Updates all feature instances from this {@code FeatureSet} which match
the given predicate.
* For each {@link Feature} instance matching the given {@link Predicate},
* the <code>{@linkplain UnaryOperator#apply
UnaryOperator.apply(Feature)}</code> method will be invoked.
- * {@code UnaryOperator}s are free to modify the given {@code Feature}
<i>in-place</i> or to return a
- * different feature instance. Two behaviors are possible:
+ * {@code UnaryOperator}s are free to modify the given {@code Feature}
<i>in-place</i>
+ * or to return a different feature instance. Two behaviors are possible:
+ *
* <ul>
* <li>If the operator returns a non-null {@link Feature}, then the
modified feature is stored
* in replacement of the previous feature (not necessarily at the
same location).</li>
* <li>If the operator returns {@code null}, then the feature will be
removed from the {@code FeatureSet}.</li>
* </ul>
*
- * @param filter a predicate which returns true for resources to be
updated.
- * @param updater operation called for each matching {@link Feature}.
+ * @param filter a predicate which returns {@code true} for feature
instances to be updated.
+ * @param updater operation called for each matching {@link Feature}
instance.
+ * @throws IllegalFeatureTypeException if a feature given by the operator
is not of the type expected by this {@code FeatureSet}.
* @throws DataStoreException if another error occurred while replacing
features.
*/
- void replaceIf(Predicate<? super Feature> filter, UnaryOperator<Feature>
updater)
- throws DataStoreException;
+ void replaceIf(Predicate<? super Feature> filter, UnaryOperator<Feature>
updater) throws DataStoreException;
}
diff --git
a/storage/sis-storage/src/main/java/org/apache/sis/storage/WritableGridCoverageResource.java
b/storage/sis-storage/src/main/java/org/apache/sis/storage/WritableGridCoverageResource.java
index 17ef40c..e377c97 100644
---
a/storage/sis-storage/src/main/java/org/apache/sis/storage/WritableGridCoverageResource.java
+++
b/storage/sis-storage/src/main/java/org/apache/sis/storage/WritableGridCoverageResource.java
@@ -19,58 +19,88 @@ package org.apache.sis.storage;
import org.apache.sis.coverage.grid.GridCoverage;
import org.apache.sis.coverage.grid.GridGeometry;
+
/**
- * Subtype of {@linkplain GridCoverageResource} with writing capabilities.
+ * A {@link GridCoverageResource} with writing capabilities. {@code
WritableGridCoverageResource} inherits the reading
+ * capabilities from its parent and adds a {@linkplain #write write}
operation. Some aspects of the write operation can
+ * be controlled by options, which may be {@link DataStore}-specific.
*
- * @author Johann Sorel (Geomatys)
+ * @author Johann Sorel (Geomatys)
* @version 1.0
* @since 1.0
* @module
*/
public interface WritableGridCoverageResource extends GridCoverageResource {
-
/**
- * Coverage writing options.
- * Common options can be found in {@link CommonOption}.
- * Different {@linkplain DataStoreProvider} may declare specific options
- * for example : compression, version, encryption.
+ * Configuration of the process of writing a coverage in a data store.
+ * By default, the {@linkplain #write write operation} is conservative: no
operation is executed
+ * if it would result in data lost. {@code Option} allows to modify this
behavior for example by
+ * allowing the {@linkplain CommonOption#TRUNCATE replacement} of previous
data.
+ * Options can also configure other aspects like compression, version or
encryption.
+ *
+ * <p>Some options may be {@link DataStore}-specific.
+ * Options that may apply to any data store are provided in the {@link
CommonOption} enumeration.
+ * Other options may be defined by the {@linkplain DataStoreProvider} of
specific formats.</p>
+ *
+ * @author Johann Sorel (Geomatys)
+ * @version 1.0
+ * @since 1.0
+ * @module
*/
interface Option {}
/**
- * Common writing options.
+ * Write options that may apply to any data store. The coverage
{@linkplain #write write operation}
+ * is configured by instances of {@link Option}, sometime in a {@link
DataStore}-specific basis.
+ * This {@code CommonOption} enumeration provides options that do not
depend on the data store.
+ *
+ * @author Johann Sorel (Geomatys)
+ * @version 1.0
+ * @since 1.0
+ * @module
*/
enum CommonOption implements Option {
/**
+ * Instructs the write operation to replace existing coverage if one
exists.
+ * By default the {@linkplain #write write operation} does not
overwrite existing data.
+ * If this option is specified, then there is a choice:
+ *
* <ul>
- * <li>If a coverage already exist it will erase and replace existing
datas
- * by the new coverage.</li>
- * <li>If there are no previous datas the new datas are inserted
- * as if this option wasn't defined.</li>
+ * <li>If a coverage already exists in the {@link
GridCoverageResource}, then it will be erased.
+ * The existing data will be replaced by the new coverage.</li>
+ * <li>If there are no existing coverage in the {@link
GridCoverageResource},
+ * then the new coverage will be inserted as if this option was
not provided.</li>
* </ul>
*/
TRUNCATE,
+
/**
- * Update or append existing coverage with new datas.
+ * Updates or appends existing coverage with new data.
+ * If a coverage already exists when the {@linkplain #write write
operation} is executed with this option, then:
+ *
* <ul>
- * <li>Areas of the provided {@linkplain GridCoverage} that are within
the exisintg {@linkplain GridGeometry}
- * will overwrite the existing datas.</li>
- * <li>Areas outside the existing {@linkplain GridGeometry} will
result in expanding the
- * {@linkplain GridGeometry} with the new datas.</li>
- * <li>If there are no previous datas the new datas are inserted
- * as if this option wasn't defined.</li>
+ * <li>Areas of the provided {@link GridCoverage} that are within
the existing {@link GridGeometry}
+ * will overwrite the existing data.</li>
+ * <li>Areas outside the existing {@link GridGeometry} will result
in expanding the grid geometry
+ * with the new data.</li>
* </ul>
+ *
+ * If there are no previous coverage, then the new coverage is
inserted as if this option was not provided.
*/
UPDATE
}
/**
- * Write new datas in the resource.
+ * Writes a new coverage in the data store for this resource. If a
coverage already exists for this resource,
+ * then the behavior of this method is determined by the given options. If
no option is specified, the default
+ * behavior is to fail if writing a coverage would cause an existing
coverage to be overwritten.
+ * This behavior can be modified by requesting the {@linkplain
CommonOption#TRUNCATE replacement}
+ * or {@linkplain CommonOption#UPDATE update} of existing coverages.
*
- * @param coverage new datas to write, should not be null
- * @param options specific writing options
- * @throws org.apache.sis.storage.DataStoreException if an error occurred
while writing datas in the underlying data store.
+ * @param coverage new data to write in the data store for this resource.
+ * @param options configuration of the write operation. May be {@link
DataStore}-specific options
+ * (e.g. for compression, encryption, <i>etc</i>).
+ * @throws DataStoreException if an error occurred while writing data in
the underlying data store.
*/
void write(GridCoverage coverage, Option... options) throws
DataStoreException;
-
}
