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
commit 738fd95772219647445c9e35207353304b1e098d
Author: Martin Desruisseaux <martin.desruisse...@geomatys.com>
AuthorDate: Thu Feb 8 17:49:12 2024 +0100
Move to public API the annotation used for documenting methods that use
assertions for arguments validation.
---
.../sis/coverage/grid/DimensionalityReduction.java | 6 ++++--
.../org/apache/sis/geometry/AbstractEnvelope.java | 10 +++++-----
.../org/apache/sis/geometry/GeneralEnvelope.java | 8 ++++----
.../main/org/apache/sis/referencing/Builder.java | 2 ++
.../operation/transform/AbstractMathTransform.java | 2 ++
.../main/org/apache/sis/measure/Range.java | 2 +-
.../{internal => }/ArgumentCheckByAssertion.java | 21 +++++++++++++++++----
7 files changed, 35 insertions(+), 16 deletions(-)
diff --git
a/endorsed/src/org.apache.sis.feature/main/org/apache/sis/coverage/grid/DimensionalityReduction.java
b/endorsed/src/org.apache.sis.feature/main/org/apache/sis/coverage/grid/DimensionalityReduction.java
index 9b0c7ca751..ae52bd3e01 100644
---
a/endorsed/src/org.apache.sis.feature/main/org/apache/sis/coverage/grid/DimensionalityReduction.java
+++
b/endorsed/src/org.apache.sis.feature/main/org/apache/sis/coverage/grid/DimensionalityReduction.java
@@ -33,9 +33,9 @@ import org.opengis.referencing.datum.PixelInCell;
import org.apache.sis.util.Utilities;
import org.apache.sis.util.ArraysExt;
import org.apache.sis.util.ArgumentChecks;
+import org.apache.sis.util.ArgumentCheckByAssertion;
import org.apache.sis.util.ComparisonMode;
import org.apache.sis.util.internal.Numerics;
-import org.apache.sis.util.internal.ArgumentCheckByAssertion;
import org.apache.sis.feature.internal.Resources;
import org.apache.sis.geometry.ImmutableEnvelope;
import org.apache.sis.geometry.GeneralDirectPosition;
@@ -627,9 +627,11 @@ public class DimensionalityReduction implements
UnaryOperator<GridCoverage>, Ser
/**
* Returns a coordinate tuple on which dimensionality reduction has been
applied.
+ *
+ * <h4>Precondition</h4>
* The coordinate reference system of the given {@code source} should be
either
* null or equal (ignoring metadata) to the CRS of the source grid
geometry.
- * For performance reason, this is not verified unless assertions are
enabled.
+ * For performance reason, this condition is not verified unless Java
assertions are enabled.
*
* @param source the source coordinate tuple, or {@code null}.
* @return the reduced coordinate tuple, or {@code null} if the given
source was null.
diff --git
a/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/geometry/AbstractEnvelope.java
b/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/geometry/AbstractEnvelope.java
index 2e81670ba3..5942cd1631 100644
---
a/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/geometry/AbstractEnvelope.java
+++
b/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/geometry/AbstractEnvelope.java
@@ -37,16 +37,16 @@ import
org.opengis.referencing.crs.CoordinateReferenceSystem;
import org.opengis.referencing.cs.CoordinateSystemAxis;
import org.opengis.referencing.cs.CoordinateSystem;
import org.opengis.referencing.cs.RangeMeaning;
+import org.apache.sis.util.ArgumentCheckByAssertion;
import org.apache.sis.util.Emptiable;
import org.apache.sis.util.Utilities;
import org.apache.sis.util.ComparisonMode;
import org.apache.sis.util.resources.Errors;
import org.apache.sis.io.wkt.Formatter;
import org.apache.sis.io.wkt.FormattableObject;
+import org.apache.sis.referencing.IdentifiedObjects;
import org.apache.sis.referencing.util.WKTUtilities;
import org.apache.sis.referencing.util.TemporalAccessor;
-import org.apache.sis.util.internal.ArgumentCheckByAssertion;
-import org.apache.sis.referencing.IdentifiedObjects;
import org.apache.sis.measure.Range;
import org.apache.sis.math.Vector;
@@ -765,7 +765,7 @@ public abstract class AbstractEnvelope extends
FormattableObject implements Enve
*
* <h4>Preconditions</h4>
* This method assumes that the specified point uses a CRS equivalent to
this envelope CRS.
- * For performance reasons, it will no be verified unless Java assertions
are enabled.
+ * For performance reasons, this condition is not verified unless Java
assertions are enabled.
*
* <h4>Crossing the anti-meridian of a Geographic CRS</h4>
* For any dimension, if <var>upper</var> < <var>lower</var> then this
method uses an
@@ -817,7 +817,7 @@ public abstract class AbstractEnvelope extends
FormattableObject implements Enve
*
* <h4>Preconditions</h4>
* This method assumes that the specified envelope uses the same CRS as
this envelope.
- * For performance reasons, it will no be verified unless Java assertions
are enabled.
+ * For performance reasons, this condition is not verified unless Java
assertions are enabled.
*
* <h4>Crossing the anti-meridian of a Geographic CRS</h4>
* For every cases illustrated below, the yellow box is considered
completely enclosed
@@ -947,7 +947,7 @@ public abstract class AbstractEnvelope extends
FormattableObject implements Enve
*
* <h4>Preconditions</h4>
* This method assumes that the specified envelope uses the same CRS as
this envelope.
- * For performance reasons, it will no be verified unless Java assertions
are enabled.
+ * For performance reasons, this condition is not verified unless Java
assertions are enabled.
*
* <h4>Crossing the anti-meridian of a Geographic CRS</h4>
* This method can handle envelopes crossing the anti-meridian.
diff --git
a/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/geometry/GeneralEnvelope.java
b/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/geometry/GeneralEnvelope.java
index 76eb1d05b3..996a9c6cb6 100644
---
a/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/geometry/GeneralEnvelope.java
+++
b/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/geometry/GeneralEnvelope.java
@@ -39,7 +39,7 @@ import
org.opengis.geometry.MismatchedReferenceSystemException;
import org.opengis.metadata.extent.GeographicBoundingBox;
import org.apache.sis.referencing.util.TemporalAccessor;
import org.apache.sis.referencing.util.AxisDirections;
-import org.apache.sis.util.internal.ArgumentCheckByAssertion;
+import org.apache.sis.util.ArgumentCheckByAssertion;
import org.apache.sis.util.resources.Errors;
import org.apache.sis.referencing.CRS;
import org.apache.sis.referencing.IdentifiedObjects;
@@ -535,7 +535,7 @@ public class GeneralEnvelope extends ArrayEnvelope
implements Cloneable, Seriali
*
* <h4>Preconditions</h4>
* This method assumes that the specified point uses a CRS equivalent to
this envelope CRS.
- * For performance reasons, it will no be verified unless Java assertions
are enabled.
+ * For performance reasons, this condition is not verified unless Java
assertions are enabled.
*
* <h4>Crossing the anti-meridian of a Geographic CRS</h4>
* This method supports envelopes crossing the anti-meridian. In such
cases it is possible to
@@ -613,7 +613,7 @@ public class GeneralEnvelope extends ArrayEnvelope
implements Cloneable, Seriali
*
* <h4>Preconditions</h4>
* This method assumes that the specified envelope uses a CRS equivalent
to this envelope CRS.
- * For performance reasons, it will no be verified unless Java assertions
are enabled.
+ * For performance reasons, this condition is not verified unless Java
assertions are enabled.
*
* <h4>Crossing the anti-meridian of a Geographic CRS</h4>
* This method supports envelopes crossing the anti-meridian. If one or
both envelopes cross
@@ -770,7 +770,7 @@ public class GeneralEnvelope extends ArrayEnvelope
implements Cloneable, Seriali
*
* <h4>Preconditions</h4>
* This method assumes that the specified envelope uses a CRS equivalent
to this envelope CRS.
- * For performance reasons, it will no be verified unless Java assertions
are enabled.
+ * For performance reasons, this condition is not verified unless Java
assertions are enabled.
*
* <h4>Crossing the anti-meridian of a Geographic CRS</h4>
* This method supports envelopes crossing the anti-meridian.
diff --git
a/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/referencing/Builder.java
b/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/referencing/Builder.java
index 7f6078bb49..40642e616b 100644
---
a/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/referencing/Builder.java
+++
b/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/referencing/Builder.java
@@ -36,6 +36,7 @@ import org.apache.sis.referencing.internal.DeprecatedCode;
import org.apache.sis.referencing.internal.DeprecatedName;
import org.apache.sis.util.Deprecable;
import org.apache.sis.util.ArgumentChecks;
+import org.apache.sis.util.ArgumentCheckByAssertion;
import org.apache.sis.util.iso.DefaultNameFactory;
import org.apache.sis.util.iso.Types;
import org.apache.sis.util.resources.Errors;
@@ -219,6 +220,7 @@ public abstract class Builder<B extends Builder<B>> {
*
* @throws AssertionError if assertions are enabled and the {@code <B>}
type is not the type of {@code this}.
*/
+ @ArgumentCheckByAssertion
protected Builder() {
assert verifyParameterizedType(getClass());
properties = new HashMap<>(8);
diff --git
a/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/referencing/operation/transform/AbstractMathTransform.java
b/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/referencing/operation/transform/AbstractMathTransform.java
index ba31250c72..592fd6ba3c 100644
---
a/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/referencing/operation/transform/AbstractMathTransform.java
+++
b/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/referencing/operation/transform/AbstractMathTransform.java
@@ -44,6 +44,7 @@ import org.apache.sis.referencing.util.WKTUtilities;
import org.apache.sis.referencing.util.WKTKeywords;
import org.apache.sis.system.Loggers;
import org.apache.sis.util.ArgumentChecks;
+import org.apache.sis.util.ArgumentCheckByAssertion;
import org.apache.sis.util.Utilities;
import org.apache.sis.util.ComparisonMode;
import org.apache.sis.util.LenientComparable;
@@ -1148,6 +1149,7 @@ public abstract class AbstractMathTransform extends
FormattableObject
* @throws AssertionError if assertions are enabled and the objects are
equal but their hash codes are different.
*/
@Override
+ @ArgumentCheckByAssertion
public final boolean equals(final Object object) {
final boolean eq = equals(object, ComparisonMode.STRICT);
// If objects are equal, then they must have the same hash code value.
diff --git
a/endorsed/src/org.apache.sis.util/main/org/apache/sis/measure/Range.java
b/endorsed/src/org.apache.sis.util/main/org/apache/sis/measure/Range.java
index 5dd5801093..26c06c9da4 100644
--- a/endorsed/src/org.apache.sis.util/main/org/apache/sis/measure/Range.java
+++ b/endorsed/src/org.apache.sis.util/main/org/apache/sis/measure/Range.java
@@ -23,10 +23,10 @@ import java.util.FormattableFlags;
import java.io.Serializable;
import javax.measure.Unit;
import org.apache.sis.util.ArgumentChecks;
+import org.apache.sis.util.ArgumentCheckByAssertion;
import org.apache.sis.util.Emptiable;
import org.apache.sis.util.Numbers;
import org.apache.sis.util.internal.Strings;
-import org.apache.sis.util.internal.ArgumentCheckByAssertion;
import org.apache.sis.util.collection.CheckedContainer;
diff --git
a/endorsed/src/org.apache.sis.util/main/org/apache/sis/util/internal/ArgumentCheckByAssertion.java
b/endorsed/src/org.apache.sis.util/main/org/apache/sis/util/ArgumentCheckByAssertion.java
similarity index 57%
rename from
endorsed/src/org.apache.sis.util/main/org/apache/sis/util/internal/ArgumentCheckByAssertion.java
rename to
endorsed/src/org.apache.sis.util/main/org/apache/sis/util/ArgumentCheckByAssertion.java
index 6367f2abdb..c1ffaf3074 100644
---
a/endorsed/src/org.apache.sis.util/main/org/apache/sis/util/internal/ArgumentCheckByAssertion.java
+++
b/endorsed/src/org.apache.sis.util/main/org/apache/sis/util/ArgumentCheckByAssertion.java
@@ -14,7 +14,7 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
-package org.apache.sis.util.internal;
+package org.apache.sis.util;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
@@ -23,11 +23,24 @@ import java.lang.annotation.Target;
/**
- * Marker annotation for public methods which use assertions for validating
users arguments.
- * This is not recommended for public API, but we do that in a few places
where unconditional
- * argument checks may be too expensive. This annotation is used for tracking
those methods.
+ * Marker annotation for methods which use assertions for validating their
arguments.
+ * Arguments validation with assertions is usually not a recommended practice,
+ * but Apache SIS does that when unconditional argument checks would be too
expensive.
+ * Examples:
+ *
+ * <ul>
+ * <li>Checking wether two Coordinate Reference Systems are equal (ignoring
metadata)
+ * in methods potentially executed millions of times (e.g. adding
points).</li>
+ * <li>Checking the class of argument values when those classes should never
be wrong
+ * if the code has been compiled without Java compiler warnings.</li>
+ * </ul>
+ *
+ * This annotation is used for documenting methods where some preconditions
are checked with assertions.
+ * The Javadoc should document what those preconditions are.
*
* @author Martin Desruisseaux (Geomatys)
+ * @version 1.5
+ * @since 1.5
*/
@Target({
ElementType.METHOD,
