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 6e97a0c713 Documentation improvements in `CoverageAggregator`,
`GridExent` and exception messages.
6e97a0c713 is described below
commit 6e97a0c713e280cc610d651349ebb8e9bd222611
Author: Martin Desruisseaux <martin.desruisse...@geomatys.com>
AuthorDate: Thu Sep 15 10:56:23 2022 +0200
Documentation improvements in `CoverageAggregator`, `GridExent` and
exception messages.
---
.../org/apache/sis/coverage/grid/GridExtent.java | 7 ++--
.../apache/sis/internal/referencing/Resources.java | 5 +--
.../sis/internal/referencing/Resources.properties | 2 +-
.../internal/referencing/Resources_fr.properties | 2 +-
.../DefaultCoordinateOperationFactory.java | 5 +--
.../transform/DefaultMathTransformFactory.java | 4 ++-
.../java/org/apache/sis/internal/util/URLs.java | 7 +++-
.../org/apache/sis/internal/storage/Resources.java | 3 +-
.../storage/aggregate/CoverageAggregator.java | 41 +++++++++++++++++++---
9 files changed, 59 insertions(+), 17 deletions(-)
diff --git
a/core/sis-feature/src/main/java/org/apache/sis/coverage/grid/GridExtent.java
b/core/sis-feature/src/main/java/org/apache/sis/coverage/grid/GridExtent.java
index d7cbff64fe..1e6f66f825 100644
---
a/core/sis-feature/src/main/java/org/apache/sis/coverage/grid/GridExtent.java
+++
b/core/sis-feature/src/main/java/org/apache/sis/coverage/grid/GridExtent.java
@@ -1739,7 +1739,7 @@ public class GridExtent implements GridEnvelope,
LenientComparable, Serializable
* @param other the grid to intersect with.
* @return the intersection result. May be one of the existing instances.
* @throws MismatchedDimensionException if the two extents do not have the
same number of dimensions.
- * @throws IllegalArgumentException} if axis types are specified but
inconsistent for at least one dimension.
+ * @throws IllegalArgumentException if axis types are specified but
inconsistent in at least one dimension.
*
* @since 1.3
*/
@@ -1756,7 +1756,7 @@ public class GridExtent implements GridEnvelope,
LenientComparable, Serializable
* @param other the grid to combine with.
* @return the union result. May be one of the existing instances.
* @throws MismatchedDimensionException if the two extents do not have the
same number of dimensions.
- * @throws IllegalArgumentException} if axis types are specified but
inconsistent for at least one dimension.
+ * @throws IllegalArgumentException if axis types are specified but
inconsistent in at least one dimension.
*
* @since 1.3
*/
@@ -1774,7 +1774,8 @@ public class GridExtent implements GridEnvelope,
LenientComparable, Serializable
throw new MismatchedDimensionException(Errors.format(
Errors.Keys.MismatchedDimension_3, "other", m,
other.getDimension()));
}
- if (types != null && other.types != null) {
+ // First condition below is a fast check for a common case.
+ if (types != other.types && types != null && other.types != null) {
for (int i=0; i<m; i++) {
final DimensionNameType t1 = types[i];
if (t1 != null) {
diff --git
a/core/sis-referencing/src/main/java/org/apache/sis/internal/referencing/Resources.java
b/core/sis-referencing/src/main/java/org/apache/sis/internal/referencing/Resources.java
index 9e17d27b82..f06dc76c55 100644
---
a/core/sis-referencing/src/main/java/org/apache/sis/internal/referencing/Resources.java
+++
b/core/sis-referencing/src/main/java/org/apache/sis/internal/referencing/Resources.java
@@ -427,9 +427,10 @@ public final class Resources extends IndexedResourceBundle
{
public static final short NoSuchAuthorityCode_3 = 49;
/**
- * No operation method found for name or identifier “{0}”.
+ * No operation method found for name or identifier “{0}”. Only
methods associated to Java code
+ * are supported. See {1} for the list of available methods.
*/
- public static final short NoSuchOperationMethod_1 = 50;
+ public static final short NoSuchOperationMethod_2 = 50;
/**
* The coordinate system axes in the given “{0}” description do not
conform to the expected
diff --git
a/core/sis-referencing/src/main/java/org/apache/sis/internal/referencing/Resources.properties
b/core/sis-referencing/src/main/java/org/apache/sis/internal/referencing/Resources.properties
index 17b98e8681..e9c24f3adc 100644
---
a/core/sis-referencing/src/main/java/org/apache/sis/internal/referencing/Resources.properties
+++
b/core/sis-referencing/src/main/java/org/apache/sis/internal/referencing/Resources.properties
@@ -111,7 +111,7 @@ NotAnAffineTransform = Transform is not affine.
NotASkewSymmetricMatrix = Matrix is not skew-symmetric.
NoSuchAuthorityCode_3 = No \u2018{1}\u2019 object found for code
\u201c{2}\u201d in the \u201c{0}\u201d geodetic dataset.
NoSuchAuthorityCodeInSubset_4 = No \u2018{1}\u2019 object found for code
\u201c{2}\u201d. However only a subset of the {0} geodetic dataset has been
queried. See {3} for instruction about how to install the full {0} database.
-NoSuchOperationMethod_1 = No operation method found for name or
identifier \u201c{0}\u201d.
+NoSuchOperationMethod_2 = No operation method found for name or
identifier \u201c{0}\u201d. Only methods associated to Java code are supported.
See {1} for the list of available methods.
OperationHasNoTransform_2 = Operation \u201c{1}\u201d of class
\u2018{0}\u2019 has no mathematical transform.
ParameterNotFound_2 = No parameter named \u201c{1}\u201d has
been found in \u201c{0}\u201d.
PointsAreNotOnRegularGrid = Points are not on a regular grid.
diff --git
a/core/sis-referencing/src/main/java/org/apache/sis/internal/referencing/Resources_fr.properties
b/core/sis-referencing/src/main/java/org/apache/sis/internal/referencing/Resources_fr.properties
index e81f00e250..48044061cc 100644
---
a/core/sis-referencing/src/main/java/org/apache/sis/internal/referencing/Resources_fr.properties
+++
b/core/sis-referencing/src/main/java/org/apache/sis/internal/referencing/Resources_fr.properties
@@ -116,7 +116,7 @@ NotAnAffineTransform = La transformation
n\u2019est pas affine.
NotASkewSymmetricMatrix = La matrice n\u2019est pas
antisym\u00e9trique.
NoSuchAuthorityCode_3 = Aucun objet de type \u2018{1}\u2019
n\u2019a \u00e9t\u00e9 trouv\u00e9 pour le code \u00ab\u202f{2}\u202f\u00bb
dans la base de donn\u00e9es g\u00e9od\u00e9siques \u00ab\u202f{0}\u202f\u00bb.
NoSuchAuthorityCodeInSubset_4 = Aucun objet de type \u2018{1}\u2019
n\u2019a \u00e9t\u00e9 trouv\u00e9 pour le code \u00ab\u202f{2}\u202f\u00bb.
Toutefois seul un sous-ensemble de la base de donn\u00e9es
g\u00e9od\u00e9siques {0} a \u00e9t\u00e9 interrog\u00e9. Voir {3} pour des
instructions d\u2019installation de la base de donn\u00e9es {0} compl\u00e8te.
-NoSuchOperationMethod_1 = Aucune m\u00e9thode n\u2019a \u00e9t\u00e9
trouv\u00e9e pour le nom ou l\u2019identifiant \u00ab\u202f{0}\u202f\u00bb.
+NoSuchOperationMethod_2 = Aucune m\u00e9thode n\u2019a \u00e9t\u00e9
trouv\u00e9e pour le nom ou l\u2019identifiant \u00ab\u202f{0}\u202f\u00bb.
Seules les m\u00e9thodes associ\u00e9es \u00e0 du code Java sont
support\u00e9es. Voir {1} pour la liste des m\u00e9thodes disponibles.
OperationHasNoTransform_2 = L\u2019op\u00e9ration
\u00ab\u202f{1}\u202f\u00bb de classe \u2018{0}\u2019 n\u2019a pas de
transformation math\u00e9matique.
ParameterNotFound_2 = Aucun param\u00e8tre nomm\u00e9
\u00ab\u202f{1}\u202f\u00bb n\u2019a \u00e9t\u00e9 trouv\u00e9 dans
\u00ab\u202f{0}\u202f\u00bb.
PointsAreNotOnRegularGrid = Les points ne sont pas sur une grille
r\u00e9guli\u00e8re.
diff --git
a/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/DefaultCoordinateOperationFactory.java
b/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/DefaultCoordinateOperationFactory.java
index 833d3f4bdc..89efcff65b 100644
---
a/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/DefaultCoordinateOperationFactory.java
+++
b/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/DefaultCoordinateOperationFactory.java
@@ -43,6 +43,7 @@ import
org.apache.sis.internal.referencing.ReferencingUtilities;
import org.apache.sis.internal.system.DefaultFactories;
import org.apache.sis.internal.util.CollectionsExt;
import org.apache.sis.internal.util.Constants;
+import org.apache.sis.internal.util.URLs;
import org.apache.sis.referencing.CRS;
import org.apache.sis.referencing.IdentifiedObjects;
import org.apache.sis.referencing.AbstractIdentifiedObject;
@@ -84,7 +85,7 @@ import org.apache.sis.util.Utilities;
* The second approach is the most frequently used.
*
* @author Martin Desruisseaux (IRD, Geomatys)
- * @version 1.1
+ * @version 1.3
* @since 0.6
* @module
*/
@@ -293,7 +294,7 @@ public class DefaultCoordinateOperationFactory extends
AbstractFactory implement
return method;
}
throw new
NoSuchIdentifierException(Resources.forProperties(defaultProperties)
- .getString(Resources.Keys.NoSuchOperationMethod_1, name),
name);
+ .getString(Resources.Keys.NoSuchOperationMethod_2, name,
URLs.OPERATION_METHODS), name);
}
/**
diff --git
a/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/DefaultMathTransformFactory.java
b/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/DefaultMathTransformFactory.java
index f7543926c4..8a266312d8 100644
---
a/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/DefaultMathTransformFactory.java
+++
b/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/DefaultMathTransformFactory.java
@@ -54,6 +54,7 @@ import org.opengis.util.FactoryException;
import org.opengis.util.NoSuchIdentifierException;
import org.apache.sis.io.wkt.Parser;
+import org.apache.sis.internal.util.URLs;
import org.apache.sis.internal.util.Strings;
import org.apache.sis.internal.util.Constants;
import org.apache.sis.internal.referencing.LazySet;
@@ -475,7 +476,8 @@ public class DefaultMathTransformFactory extends
AbstractFactory implements Math
method = CoordinateOperations.getOperationMethod(methods,
identifier);
}
if (method == null) {
- throw new
NoSuchIdentifierException(Resources.format(Resources.Keys.NoSuchOperationMethod_1,
identifier), identifier);
+ throw new NoSuchIdentifierException(Resources.format(
+ Resources.Keys.NoSuchOperationMethod_2, identifier,
URLs.OPERATION_METHODS), identifier);
}
/*
* Remember the method we just found, for faster check next time.
diff --git
a/core/sis-utility/src/main/java/org/apache/sis/internal/util/URLs.java
b/core/sis-utility/src/main/java/org/apache/sis/internal/util/URLs.java
index 50ea417881..2c1c15f333 100644
--- a/core/sis-utility/src/main/java/org/apache/sis/internal/util/URLs.java
+++ b/core/sis-utility/src/main/java/org/apache/sis/internal/util/URLs.java
@@ -29,7 +29,7 @@ import org.apache.sis.util.Static;
* </ul>
*
* @author Martin Desruisseaux (Geomatys)
- * @version 1.2
+ * @version 1.3
* @since 1.2
* @module
*/
@@ -49,6 +49,11 @@ public final class URLs extends Static {
*/
public static final String EPSG_INSTALL =
"https://sis.apache.org/epsg.html";;
+ /**
+ * List of operation methods supported by Apache SIS.
+ */
+ public static final String OPERATION_METHODS =
"https://sis.apache.org/tables/CoordinateOperationMethods.html";;
+
/**
* The Well-Known Text (WKT) 2 specification implemented by Apache SIS.
*/
diff --git
a/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/Resources.java
b/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/Resources.java
index 448986964e..8c88cedc8b 100644
---
a/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/Resources.java
+++
b/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/Resources.java
@@ -327,7 +327,8 @@ public final class Resources extends IndexedResourceBundle {
public static final short NoCommonFeatureType = 75;
/**
- * Index {1} in dimension “{0}” maps to {2} slices.
+ * Index {1} in dimension “{0}” maps to {2} slices. This error can be
avoided by specifying a
+ * merge strategy.
*/
public static final short NoSliceMapped_3 = 79;
diff --git
a/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/aggregate/CoverageAggregator.java
b/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/aggregate/CoverageAggregator.java
index 91d4292bbc..100c410a57 100644
---
a/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/aggregate/CoverageAggregator.java
+++
b/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/aggregate/CoverageAggregator.java
@@ -51,6 +51,35 @@ import org.apache.sis.util.ArgumentChecks;
* All source coverages should share the same CRS and have the same ranges
(sample dimensions).
* If this is not the case, then the source coverages will be grouped in
different aggregates
* with an uniform CRS and set of ranges in each sub-aggregates.
+ * More specifically, {@code CoverageAggregator} organizes resources as below,
+ * except that parent nodes having only one child are omitted:
+ *
+ * {@preformat text
+ * Root aggregate
+ * ├─ All coverages with same sample dimensions #1
+ * │ └─ ...
+ * └─ All coverages with same sample dimensions #2
+ * ├─ Coverages with equivalent reference systems #1
+ * │ └─ ...
+ * └─ Coverages with equivalent reference systems #2
+ * ├─ Slices with compatible "grid to CRS" #1
+ * ├─ Slices with compatible "grid to CRS" #2
+ * └─ ...
+ * }
+ *
+ * Where:
+ *
+ * <ul>
+ * <li><dfn>Equivalent reference systems</dfn> means two {@link
org.opengis.referencing.crs.CoordinateReferenceSystem} instances
+ * for which {@link
org.apache.sis.util.Utilities#equalsIgnoreMetadata(Object, Object)} returns
{@code true}.</li>
+ * <li><dfn>Compatible grid to CRS</dfn> means two {@linkplain
org.apache.sis.coverage.grid.GridGeometry#getGridToCRS grid to CRS}
+ * transforms which are identical (with small tolerance for rounding
errors) except for the translation terms,
+ * with the additional condition that the translations, when expressed
in units of grid cell indices,
+ * can differ only by integer amounts of cells.</li>
+ * <li><dfn>Slices</dfn> means source coverages declared to this aggregator
by calls to {@code add(…)} methods,
+ * after they have been incorporated in a data cube by this aggregator.
+ * Above tree does not contain the individual slices, but data cubes
containing all slices that can fit.</li>
+ * </ul>
*
* <h2>Multi-threading and concurrency</h2>
* All {@code add(…)} methods can be invoked concurrently from arbitrary
threads.
@@ -227,12 +256,14 @@ public final class CoverageAggregator extends
Group<GroupBySample> {
* Consequently this method should usually be invoked before to add the
first coverage.
*
* <h4>Effect on previously added coverages</h4>
- * The merge strategy of previously added coverages is not modified by
this method call,
- * except for coverages that become part of the same aggregated {@link
GridCoverageResource}
- * than a coverage added after this method call.
- * In such case, the strategy set by the most recent call to {@code
setMergeStrategy(…)} prevails.
+ * The merge strategy of previously added coverages is not modified by
this method call, except
+ * for coverages (slices) that become part of the same aggregated {@link
GridCoverageResource}
+ * (data cube) than a coverage added after this method call.
+ * In such case, the strategy set by this call to {@code
setMergeStrategy(…)} prevails.
+ * Said otherwise, the merge strategy of a data cube is the strategy which
was active
+ * at the time of the most recently added slice.
*
- * @param strategy new algorithm to apply for merging source coverages at
the same grid index.
+ * @param strategy new algorithm to apply for merging source coverages
at the same grid index.
*/
public void setMergeStrategy(final MergeStrategy strategy) {
ArgumentChecks.ensureNonNull("strategy", strategy);
