001/*
002 *    GeoAPI - Java interfaces for OGC/ISO standards
003 *    Copyright © 2024 Open Geospatial Consortium, Inc.
004 *    http://www.geoapi.org
005 *
006 *    Licensed under the Apache License, Version 2.0 (the "License");
007 *    you may not use this file except in compliance with the License.
008 *    You may obtain a copy of the License at
009 *
010 *        http://www.apache.org/licenses/LICENSE-2.0
011 *
012 *    Unless required by applicable law or agreed to in writing, software
013 *    distributed under the License is distributed on an "AS IS" BASIS,
014 *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 *    See the License for the specific language governing permissions and
016 *    limitations under the License.
017 */
018package org.opengis.referencing.datum;
019
020import java.time.temporal.Temporal;
021import org.opengis.annotation.Classifier;
022import org.opengis.annotation.Stereotype;
023import org.opengis.annotation.UML;
024
025import static org.opengis.annotation.Obligation.*;
026import static org.opengis.annotation.Specification.*;
027
028
029/**
030 * Reference frame in which some of the defining parameters have time dependency.
031 * The time-varying parameters can describe time evolution of defining station coordinates.
032 * Examples:
033 * <ul>
034 *   <li>Horizontally: defining station coordinates having linear velocities to account for crustal motion.</li>
035 *   <li>Vertically: defining station heights having velocity to account for post-glacial isostatic rebound motion.</li>
036 * </ul>
037 *
038 * This interface should not be implemented alone, but combined with the {@link GeodeticDatum}
039 * or {@link VerticalDatum} interface using multi-inheritance of interfaces.
040 *
041 * @author  OGC Topic 2 (for abstract model and documentation)
042 * @author  Martin Desruisseaux (Geomatys)
043 * @version 3.1
044 * @since   3.1
045 *
046 * @departure harmonization
047 *   ISO 19111 defines two distinct interfaces, {@code DynamicGeodeticReferenceFrame} and {@code DynamicVerticalReferenceFrame}.
048 *   GeoAPI defines a single interface for all cases, with the requirement that implementers shall combine this interface with
049 *   {@code GeodeticReferenceFrame} or {@code VerticalReferenceFrame} respectively using multi-inheritance of interfaces.
050 *   This is a design similar to {@link org.opengis.referencing.crs.DerivedCRS}.
051 */
052@Classifier(Stereotype.ABSTRACT)
053public interface DynamicReferenceFrame extends Datum {
054    /**
055     * Returns the epoch to which the coordinates of stations defining the dynamic geodetic reference frame are referenced.
056     *
057     * <h4>Temporal object type</h4>
058     * The type of the returned object depends on the epoch accuracy and the calendar in use.
059     * For reference frames relative to the Earth, the temporal type should be {@link java.time.Year} if the epoch is
060     * merely a year, {@link java.time.YearMonth} or {@link java.time.LocalDate} if a better precision is available,
061     * up to {@link java.time.OffsetDateTime} or {@link java.time.Instant} for maximal precision.
062     * For reference frames relative to another planet, the time measurement may use a non-Gregorian calendar.
063     * In the latter case, the type of the returned temporal object is currently implementation dependent.
064     *
065     * @return epoch to which the coordinates of stations defining the dynamic geodetic reference frame are referenced.
066     *
067     * @see org.opengis.coordinate.CoordinateMetadata#getCoordinateEpoch()
068     * @see org.opengis.referencing.operation.CoordinateOperation#getSourceEpoch()
069     * @see org.opengis.referencing.operation.CoordinateOperation#getTargetEpoch()
070     */
071    @UML(identifier="frameReferenceEpoch", obligation=MANDATORY, specification=ISO_19111)
072    Temporal getFrameReferenceEpoch();
073}