Replace java.util.Date (from Java 1) by `java.time.temporal.Tempora…

…l` (from Java 8)

in two properties that were introduced by the ISO 19157 upgrade (GitHub issue #44).
This change should be done on all properties, but this commit starts with properties
that did not existed before #44 for making the transition smother in implementations.

#79
#44

geoapi/src/main/java/org/opengis/metadata/quality/Element.java

@@ -32,8 +32,13 @@
 package org.opengis.metadata.quality;
 
 import java.util.Date;
+import java.util.Iterator;
 import java.util.Collection;
 import java.util.Collections;
+import java.util.AbstractCollection;
+import java.time.Instant;
+import java.time.temporal.ChronoField;
+import java.time.temporal.Temporal;
 import org.opengis.metadata.Identifier;
 import org.opengis.metadata.citation.Citation;
 import org.opengis.util.InternationalString;
@@ -230,15 +235,44 @@ default Citation getEvaluationProcedure() {
      * The collection size is 1 for a single date, or 2 for a range.
      * Returns an empty collection if this information is not available.
      *
+     * <p>The default implementation returns a wrapper around @link EvaluationMethod#getDates()} collection.
+     * Calls to {@link Iterator#next()} may throw {@link java.time.DateTimeException} if the temporal object
+     * can not be converted to a date.</p>
+     *
      * @return date or range of dates on which a data quality measure was applied.
      *
      * @deprecated Replaced by {@link EvaluationMethod#getDates()}.
      */
     @Deprecated
     @UML(identifier="dateTime", obligation=OPTIONAL, specification=ISO_19115, version=2003)
     default Collection<? extends Date> getDates() {
-        final EvaluationMethod ref = getEvaluationMethod();
-        return (ref != Collections.emptyList()) ? ref.getDates() : Collections.emptyList();
+        return new AbstractCollection<Date>() {
+            @Override public int size() {
+                final EvaluationMethod ref = getEvaluationMethod();
+                return (ref != null) ? ref.getDates().size() : 0;
+            }
+
+            @Override public Iterator<Date> iterator() {
+                final EvaluationMethod ref = getEvaluationMethod();
+                if (ref == null) {
+                    return Collections.emptyIterator();
+                }
+                final Iterator<? extends Temporal> it = ref.getDates().iterator();
+                return new Iterator<Date>() {
+                    @Override public void    remove()  {it.remove();}
+                    @Override public boolean hasNext() {return it.hasNext();}
+                    @Override public Date next() {
+                        final Temporal t = it.next();
+                        if (t == null) return null;
+                        if (t instanceof Instant) {
+                            return Date.from((Instant) t);
+                        }
+                        // Following may throw `DateTimeException` if the temporal does not support the field.
+                        return new Date(Math.multiplyExact(t.getLong(ChronoField.INSTANT_SECONDS), 1000));
+                    }
+                };
+            }
+        };
     }
 
     /**

geoapi/src/main/java/org/opengis/metadata/quality/EvaluationMethod.java

@@ -33,7 +33,7 @@
 
 import java.util.Collection;
 import java.util.Collections;
-import java.util.Date;
+import java.time.temporal.Temporal;
 import org.opengis.util.InternationalString;
 import org.opengis.annotation.UML;
 import org.opengis.metadata.citation.Citation;
@@ -108,15 +108,10 @@ default Collection <? extends Citation> getReferenceDocuments() {
      * The collection size is 1 for a single date, or 2 for a range.
      * Returns an empty collection if this information is not available.
      *
-     * <div class="warning"><b>Upcoming API change — temporal schema</b><br>
-     * The element type of this method may change in GeoAPI 4.0 release. It may be replaced by a
-     * type matching more closely either ISO 19108 (<cite>Temporal Schema</cite>) or ISO 19103.
-     * </div>
-     *
      * @return date or range of dates on which a data quality measure was applied.
      */
     @UML(identifier="dateTime", obligation=OPTIONAL, specification=ISO_19157)
-    default Collection<? extends Date> getDates() {
+    default Collection<? extends Temporal> getDates() {
         return Collections.emptyList();
     }
 }

geoapi/src/main/java/org/opengis/metadata/quality/Result.java

@@ -31,7 +31,7 @@
  */
 package org.opengis.metadata.quality;
 
-import java.util.Date;
+import java.time.temporal.Temporal;
 import org.opengis.annotation.UML;
 import org.opengis.annotation.Classifier;
 import org.opengis.annotation.Stereotype;
@@ -81,13 +81,16 @@ default Scope getResultScope() {
 
     /**
      * Date when the result was generated.
+     * This is typically a {@link java.time.LocalDate}, {@link java.time.LocalDateTime}
+     * or {@link java.time.ZonedDateTime} depending on whether the hour of the day and
+     * the time zone are provided.
      *
      * @return date of the result, or {@code null} if none.
      *
      * @since 3.1
      */
     @UML(identifier="dateTime", obligation=OPTIONAL, specification=ISO_19157)
-    default Date getDateTime() {
+    default Temporal getDateTime() {
         return null;
     }
 }

geoapi/src/test/java/org/opengis/metadata/quality/ElementImpl.java

@@ -0,0 +1,75 @@
+/*
+ *    GeoAPI - Java interfaces for OGC/ISO standards
+ *    http://www.geoapi.org
+ *
+ *    Copyright (C) 2022 Open Geospatial Consortium, Inc.
+ *    All Rights Reserved. http://www.opengeospatial.org/ogc/legal
+ *
+ *    Permission to use, copy, and modify this software and its documentation, with
+ *    or without modification, for any purpose and without fee or royalty is hereby
+ *    granted, provided that you include the following on ALL copies of the software
+ *    and documentation or portions thereof, including modifications, that you make:
+ *
+ *    1. The full text of this NOTICE in a location viewable to users of the
+ *       redistributed or derivative work.
+ *    2. Notice of any changes or modifications to the OGC files, including the
+ *       date changes were made.
+ *
+ *    THIS SOFTWARE AND DOCUMENTATION IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE
+ *    NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
+ *    TO, WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT
+ *    THE USE OF THE SOFTWARE OR DOCUMENTATION WILL NOT INFRINGE ANY THIRD PARTY
+ *    PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.
+ *
+ *    COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR
+ *    CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE SOFTWARE OR DOCUMENTATION.
+ *
+ *    The name and trademarks of copyright holders may NOT be used in advertising or
+ *    publicity pertaining to the software without specific, written prior permission.
+ *    Title to copyright in this software and any associated documentation will at all
+ *    times remain with copyright holders.
+ */
+package org.opengis.metadata.quality;
+
+import java.util.Collection;
+import java.util.Collections;
+
+
+/**
+ * A simple implementation of {@link Element} for testing purposes.
+ *
+ * @author  Martin Desruisseaux (Geomatys)
+ * @version 3.1
+ * @since   3.1
+ */
+final class ElementImpl implements Element {
+    /**
+     * Information about the evaluation method, or {@code null} if none.
+     */
+    private final EvaluationMethod method;
+
+    /**
+     * Creates a new element.
+     *
+     * @param  method  information about the evaluation method, or {@code null} if none.
+     */
+    ElementImpl(final EvaluationMethod method) {
+        this.method = method;
+    }
+
+    /**
+     * Returns the evaluation information.
+     */
+    @Override
+    public EvaluationMethod getEvaluationMethod() {
+        return method;
+    }
+
+    /**
+     * No yet implemented.
+     */
+    @Override
+    public Collection<? extends Result> getResults() {
+        return Collections.emptyList();
+    }
+}

geoapi/src/test/java/org/opengis/metadata/quality/ElementTest.java

@@ -0,0 +1,68 @@
+/*
+ *    GeoAPI - Java interfaces for OGC/ISO standards
+ *    http://www.geoapi.org
+ *
+ *    Copyright (C) 2022 Open Geospatial Consortium, Inc.
+ *    All Rights Reserved. http://www.opengeospatial.org/ogc/legal
+ *
+ *    Permission to use, copy, and modify this software and its documentation, with
+ *    or without modification, for any purpose and without fee or royalty is hereby
+ *    granted, provided that you include the following on ALL copies of the software
+ *    and documentation or portions thereof, including modifications, that you make:
+ *
+ *    1. The full text of this NOTICE in a location viewable to users of the
+ *       redistributed or derivative work.
+ *    2. Notice of any changes or modifications to the OGC files, including the
+ *       date changes were made.
+ *
+ *    THIS SOFTWARE AND DOCUMENTATION IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE
+ *    NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
+ *    TO, WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT
+ *    THE USE OF THE SOFTWARE OR DOCUMENTATION WILL NOT INFRINGE ANY THIRD PARTY
+ *    PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.
+ *
+ *    COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR
+ *    CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE SOFTWARE OR DOCUMENTATION.
+ *
+ *    The name and trademarks of copyright holders may NOT be used in advertising or
+ *    publicity pertaining to the software without specific, written prior permission.
+ *    Title to copyright in this software and any associated documentation will at all
+ *    times remain with copyright holders.
+ */
+package org.opengis.metadata.quality;
+
+import java.time.Instant;
+import java.util.Collection;
+import java.util.Iterator;
+import java.util.Date;
+import org.junit.Test;
+
+import static org.junit.Assert.*;
+
+
+/**
+ * Tests {@link Element}.
+ *
+ * @author  Martin Desruisseaux (Geomatys)
+ * @version 3.1
+ * @since   3.1
+ */
+public final class ElementTest {
+    /**
+     * Tests {@link Element#getDates()}.
+     */
+    @Test
+    public void testGetDates() {
+        final Instant   startTime = Instant.parse("2009-05-08T14:10:00Z");
+        final Instant     endTime = Instant.parse("2009-05-12T21:45:00Z");
+        final ElementImpl element = new ElementImpl(new EvaluationMethodImpl(startTime, endTime));
+
+        @SuppressWarnings("deprecation")
+        final Collection<? extends Date> dates = element.getDates();
+        assertEquals(2, dates.size());
+        final Iterator<? extends Date> it = dates.iterator();
+        assertEquals(startTime, it.next().toInstant());
+        assertEquals(endTime,   it.next().toInstant());
+        assertFalse (it.hasNext());
+    }
+}

geoapi/src/test/java/org/opengis/metadata/quality/EvaluationMethodImpl.java

@@ -0,0 +1,70 @@
+/*
+ *    GeoAPI - Java interfaces for OGC/ISO standards
+ *    http://www.geoapi.org
+ *
+ *    Copyright (C) 2022 Open Geospatial Consortium, Inc.
+ *    All Rights Reserved. http://www.opengeospatial.org/ogc/legal
+ *
+ *    Permission to use, copy, and modify this software and its documentation, with
+ *    or without modification, for any purpose and without fee or royalty is hereby
+ *    granted, provided that you include the following on ALL copies of the software
+ *    and documentation or portions thereof, including modifications, that you make:
+ *
+ *    1. The full text of this NOTICE in a location viewable to users of the
+ *       redistributed or derivative work.
+ *    2. Notice of any changes or modifications to the OGC files, including the
+ *       date changes were made.
+ *
+ *    THIS SOFTWARE AND DOCUMENTATION IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE
+ *    NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
+ *    TO, WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT
+ *    THE USE OF THE SOFTWARE OR DOCUMENTATION WILL NOT INFRINGE ANY THIRD PARTY
+ *    PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.
+ *
+ *    COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR
+ *    CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE SOFTWARE OR DOCUMENTATION.
+ *
+ *    The name and trademarks of copyright holders may NOT be used in advertising or
+ *    publicity pertaining to the software without specific, written prior permission.
+ *    Title to copyright in this software and any associated documentation will at all
+ *    times remain with copyright holders.
+ */
+package org.opengis.metadata.quality;
+
+import java.util.Arrays;
+import java.util.Collection;
+import java.time.temporal.Temporal;
+
+
+/**
+ * A simple implementation of {@link EvaluationMethod} for testing purposes.
+ *
+ * @author  Martin Desruisseaux (Geomatys)
+ * @version 3.1
+ * @since   3.1
+ */
+final class EvaluationMethodImpl implements EvaluationMethod {
+    /**
+     * Range of dates on which a data quality measure was applied.
+     */
+    private final Temporal startTime, endTime;
+
+    /**
+     * Creates a new evaluation method.
+     *
+     * @param  startTime  start time on which a data quality measure was applied.
+     * @param  endTime    end time on which a data quality measure was applied.
+     */
+    EvaluationMethodImpl(final Temporal startTime, final Temporal endTime) {
+        this.startTime = startTime;
+        this.endTime   = endTime;
+    }
+
+    /**
+     * Returns the range of dates on which a data quality measure was applied.
+     */
+    @Override
+    public Collection<Temporal> getDates() {
+        return Arrays.asList(startTime, endTime);
+    }
+}