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 6680d98683cdb3bcac1967601d22af095c2ec1b8
Author: Martin Desruisseaux <martin.desruisse...@geomatys.com>
AuthorDate: Thu Aug 18 16:28:41 2022 +0200
Add an annotation for methods which may return `java.util.Optional` in a
future SIS version.
This is for documentation purpose only and a reminder for future
development.
We do not annotate all possible methods yet; annotations will be added
progressively.
---
.../apache/sis/metadata/iso/extent/Extents.java | 9 ++++-
.../main/java/org/apache/sis/util/iso/Types.java | 5 +++
.../main/java/org/apache/sis/referencing/CRS.java | 10 +++++
.../operation/transform/MathTransforms.java | 2 +
.../main/java/org/apache/sis/measure/Units.java | 3 ++
.../org/apache/sis/util/OptionalCandidate.java | 44 ++++++++++++++++++++++
6 files changed, 72 insertions(+), 1 deletion(-)
diff --git
a/core/sis-metadata/src/main/java/org/apache/sis/metadata/iso/extent/Extents.java
b/core/sis-metadata/src/main/java/org/apache/sis/metadata/iso/extent/Extents.java
index 4ab70007e1..ae145b88cc 100644
---
a/core/sis-metadata/src/main/java/org/apache/sis/metadata/iso/extent/Extents.java
+++
b/core/sis-metadata/src/main/java/org/apache/sis/metadata/iso/extent/Extents.java
@@ -51,6 +51,7 @@ import org.apache.sis.measure.Longitude;
import org.apache.sis.measure.MeasurementRange;
import org.apache.sis.measure.Range;
import org.apache.sis.util.iso.Types;
+import org.apache.sis.util.OptionalCandidate;
import org.apache.sis.util.resources.Vocabulary;
import org.apache.sis.util.resources.Errors;
import org.apache.sis.util.ArgumentChecks;
@@ -130,10 +131,11 @@ public final class Extents extends Static {
* using {@link #getGeographicBoundingBox(Extent)}.</div>
*
* @param metadata the metadata from which to get a global bounding box,
or {@code null} if none.
- * @return a global bounding box for all extents found in the given
metadata.
+ * @return a global bounding box for all extents found in the given
metadata, or {@code null} if none.
*
* @since 1.1
*/
+ @OptionalCandidate
public static GeographicBoundingBox getGeographicBoundingBox(final
Metadata metadata) {
if (metadata == null) {
return null;
@@ -179,6 +181,7 @@ public final class Extents extends Static {
*
* @see
org.apache.sis.referencing.CRS#getDomainOfValidity(CoordinateReferenceSystem)
*/
+ @OptionalCandidate
public static GeographicBoundingBox getGeographicBoundingBox(final Extent
extent) {
if (extent == null) {
return null;
@@ -328,6 +331,7 @@ public final class Extents extends Static {
*
* @since 0.4
*/
+ @OptionalCandidate
public static MeasurementRange<Double> getVerticalRange(final Extent
extent) {
MeasurementRange<Double> range = null;
VerticalDatumType selectedType = null;
@@ -402,6 +406,7 @@ public final class Extents extends Static {
*
* @since 0.4
*/
+ @OptionalCandidate
public static Range<Date> getTimeRange(final Extent extent) {
Date min = null;
Date max = null;
@@ -451,6 +456,7 @@ public final class Extents extends Static {
*
* @since 0.4
*/
+ @OptionalCandidate
public static Date getDate(final Extent extent, final double location) {
ArgumentChecks.ensureFinite("location", location);
Date min = null;
@@ -487,6 +493,7 @@ public final class Extents extends Static {
*
* @since 1.1
*/
+ @OptionalCandidate
public static String getDescription(final Extent extent, final Locale
locale) {
return (extent != null) ? Types.toString(extent.getDescription(),
locale) : null;
}
diff --git a/core/sis-metadata/src/main/java/org/apache/sis/util/iso/Types.java
b/core/sis-metadata/src/main/java/org/apache/sis/util/iso/Types.java
index 7fa0879c9f..b88c3f3adb 100644
--- a/core/sis-metadata/src/main/java/org/apache/sis/util/iso/Types.java
+++ b/core/sis-metadata/src/main/java/org/apache/sis/util/iso/Types.java
@@ -39,6 +39,7 @@ import org.apache.sis.util.Static;
import org.apache.sis.util.Locales;
import org.apache.sis.util.CharSequences;
import org.apache.sis.util.ArgumentChecks;
+import org.apache.sis.util.OptionalCandidate;
import org.apache.sis.util.logging.Logging;
import org.apache.sis.util.resources.Errors;
import org.apache.sis.util.resources.Messages;
@@ -149,6 +150,7 @@ public final class Types extends Static {
*
* @see #forStandardName(String)
*/
+ @OptionalCandidate
public static String getStandardName(final Class<?> type) {
if (type != null) {
final UML uml = type.getAnnotation(UML.class);
@@ -294,6 +296,7 @@ public final class Types extends Static {
* @see #getCodeTitle(ControlledVocabulary)
* @see #getDescription(Class)
*/
+ @OptionalCandidate
public static InternationalString getDescription(final
ControlledVocabulary code) {
if (code != null) {
final String resources = getResources(code.getClass().getName());
@@ -313,6 +316,7 @@ public final class Types extends Static {
*
* @see #getDescription(ControlledVocabulary)
*/
+ @OptionalCandidate
public static InternationalString getDescription(final Class<?> type) {
final String name = getStandardName(type);
if (name != null) {
@@ -690,6 +694,7 @@ public final class Types extends Static {
*
* @since 0.4
*/
+ @OptionalCandidate
public static InternationalString toInternationalString(Map<String,?>
properties, final String prefix)
throws IllegalArgumentException
{
diff --git
a/core/sis-referencing/src/main/java/org/apache/sis/referencing/CRS.java
b/core/sis-referencing/src/main/java/org/apache/sis/referencing/CRS.java
index 18e19dad8a..265f31a557 100644
--- a/core/sis-referencing/src/main/java/org/apache/sis/referencing/CRS.java
+++ b/core/sis-referencing/src/main/java/org/apache/sis/referencing/CRS.java
@@ -86,6 +86,7 @@ import
org.apache.sis.metadata.iso.extent.DefaultGeographicBoundingBox;
import org.apache.sis.metadata.iso.extent.Extents;
import org.apache.sis.util.resources.Errors;
import org.apache.sis.util.logging.Logging;
+import org.apache.sis.util.OptionalCandidate;
import org.apache.sis.util.ArgumentChecks;
import org.apache.sis.util.Utilities;
import org.apache.sis.util.Static;
@@ -461,6 +462,7 @@ public final class CRS extends Static {
*
* @since 0.8
*/
+ @OptionalCandidate
public static CoordinateReferenceSystem
suggestCommonTarget(GeographicBoundingBox regionOfInterest,
CoordinateReferenceSystem... sourceCRS)
{
@@ -728,6 +730,7 @@ public final class CRS extends Static {
*
* @since 0.7
*/
+ @OptionalCandidate
public static double getLinearAccuracy(final CoordinateOperation
operation) {
if (operation == null) {
return Double.NaN;
@@ -758,6 +761,7 @@ public final class CRS extends Static {
*
* @since 0.7
*/
+ @OptionalCandidate
public static GeographicBoundingBox getGeographicBoundingBox(final
CoordinateOperation operation) {
if (operation == null) {
return null;
@@ -785,6 +789,7 @@ public final class CRS extends Static {
*
* @category information
*/
+ @OptionalCandidate
public static GeographicBoundingBox getGeographicBoundingBox(final
CoordinateReferenceSystem crs) {
return (crs != null) ?
Extents.getGeographicBoundingBox(crs.getDomainOfValidity()) : null;
}
@@ -812,6 +817,7 @@ public final class CRS extends Static {
* @category information
* @since 0.8
*/
+ @OptionalCandidate
public static Envelope getDomainOfValidity(final CoordinateReferenceSystem
crs) {
Envelope envelope = null;
GeneralEnvelope merged = null;
@@ -1096,6 +1102,7 @@ public final class CRS extends Static {
*
* @see org.apache.sis.geometry.GeneralEnvelope#horizontal()
*/
+ @OptionalCandidate
public static SingleCRS getHorizontalComponent(final
CoordinateReferenceSystem crs) {
switch (horizontalCode(crs)) {
/*
@@ -1190,6 +1197,7 @@ public final class CRS extends Static {
*
* @category information
*/
+ @OptionalCandidate
public static VerticalCRS getVerticalComponent(final
CoordinateReferenceSystem crs, final boolean allowCreateEllipsoidal) {
if (crs instanceof VerticalCRS) {
return (VerticalCRS) crs;
@@ -1233,6 +1241,7 @@ public final class CRS extends Static {
*
* @category information
*/
+ @OptionalCandidate
public static TemporalCRS getTemporalComponent(final
CoordinateReferenceSystem crs) {
if (crs instanceof TemporalCRS) {
return (TemporalCRS) crs;
@@ -1348,6 +1357,7 @@ public final class CRS extends Static {
*
* @since 0.5
*/
+ @OptionalCandidate
public static CoordinateReferenceSystem
getComponentAt(CoordinateReferenceSystem crs, int lower, int upper) {
if (crs == null) return null; // Skip bounds check.
int dimension = ReferencingUtilities.getDimension(crs);
diff --git
a/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/MathTransforms.java
b/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/MathTransforms.java
index 73e125f7a9..13452be39c 100644
---
a/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/MathTransforms.java
+++
b/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/MathTransforms.java
@@ -37,6 +37,7 @@ import
org.apache.sis.internal.referencing.j2d.AffineTransform2D;
import org.apache.sis.referencing.operation.matrix.AffineTransforms2D;
import org.apache.sis.referencing.operation.matrix.MatrixSIS;
import org.apache.sis.referencing.operation.matrix.Matrices;
+import org.apache.sis.util.OptionalCandidate;
import org.apache.sis.util.ArgumentChecks;
import org.apache.sis.util.ArraysExt;
import org.apache.sis.util.Static;
@@ -614,6 +615,7 @@ public final class MathTransforms extends Static {
* @see #linear(Matrix)
* @see LinearTransform#getMatrix()
*/
+ @OptionalCandidate
public static Matrix getMatrix(final MathTransform transform) {
if (transform instanceof LinearTransform) {
return ((LinearTransform) transform).getMatrix();
diff --git a/core/sis-utility/src/main/java/org/apache/sis/measure/Units.java
b/core/sis-utility/src/main/java/org/apache/sis/measure/Units.java
index 090d7a8007..0bd4832301 100644
--- a/core/sis-utility/src/main/java/org/apache/sis/measure/Units.java
+++ b/core/sis-utility/src/main/java/org/apache/sis/measure/Units.java
@@ -27,6 +27,7 @@ import org.opengis.geometry.DirectPosition; // For
javadoc
import org.opengis.referencing.cs.AxisDirection; // For javadoc
import org.apache.sis.util.Static;
+import org.apache.sis.util.OptionalCandidate;
import org.apache.sis.util.resources.Errors;
import org.apache.sis.internal.util.Constants;
@@ -1793,6 +1794,7 @@ public final class Units extends Static {
*
* @see
org.apache.sis.referencing.factory.GeodeticAuthorityFactory#createUnit(String)
*/
+ @OptionalCandidate
public static Unit<?> valueOfEPSG(final int code) {
/*
* The switch for the SexagesimalConverter cases are needed since we
did not put those units
@@ -1838,6 +1840,7 @@ public final class Units extends Static {
*
* @since 0.4
*/
+ @OptionalCandidate
public static Integer getEpsgCode(Unit<?> unit, final boolean inAxis) {
if (unit != null) {
if (!(unit instanceof AbstractUnit<?>)) {
diff --git
a/core/sis-utility/src/main/java/org/apache/sis/util/OptionalCandidate.java
b/core/sis-utility/src/main/java/org/apache/sis/util/OptionalCandidate.java
new file mode 100644
index 0000000000..1eb9949eda
--- /dev/null
+++ b/core/sis-utility/src/main/java/org/apache/sis/util/OptionalCandidate.java
@@ -0,0 +1,44 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.sis.util;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.Target;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+
+
+/**
+ * Marker annotation for methods which may return {@code java.util.Optional}
in a future version.
+ * This is applied on some methods introduced at a time when Apache SIS was
targeting Java 6 or 7.
+ * Replacing the return value by an {@link java.util.Optional} would be an
incompatible change,
+ * so this change will not be applied in SIS 1.x. But it may be applied in SIS
2.0.
+ *
+ * <p><b>Note:</b> the use of this annotation is not a guarantee that the
annotated method will return
+ * {@link java.util.Optional} in SIS 2. It only means that this possibility is
under consideration.</p>
+ *
+ * @author Martin Desruisseaux (Geomatys)
+ * @version 1.3
+ * @since 1.3
+ * @module
+ */
+@Documented
+@Target(ElementType.METHOD)
+@Retention(RetentionPolicy.SOURCE)
+public @interface OptionalCandidate {
+}
