001/*
002 *    GeoAPI - Java interfaces for OGC/ISO standards
003 *    Copyright © 2005-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.temporal;
019
020import java.time.DateTimeException;
021import org.opengis.filter.TemporalOperatorName;
022import org.opengis.annotation.UML;
023
024import static org.opengis.annotation.Obligation.OPTIONAL;
025import static org.opengis.annotation.Specification.ISO_19108;
026
027
028/**
029 * A non-decomposed element of temporal object or topology of time.
030 * The two primitives in the temporal dimension are the instant and the period.
031 *
032 * @author  ISO 19108 (for abstract model and documentation)
033 * @author  Stephane Fellah (Image Matters)
034 * @author  Alexander Petkov
035 * @author  Martin Desruisseaux (Geomatys)
036 * @author  Remi Marechal (Geomatys).
037 * @version 3.1
038 * @since   2.3
039 */
040@UML(identifier="TM_Primitive", specification=ISO_19108)
041public interface TemporalPrimitive {
042    /**
043     * Determines the position of this primitive relative to another temporal primitive.
044     * The relative position is identified by an operator which evaluates to {@code true}
045     * when the two operands are {@code this} and {@code other}.
046     *
047     * <h4>Valid return values</h4>
048     * <p>If the two primitives are {@link Instant} instances,
049     * then this method can return one of the following values:
050     * {@link TemporalOperatorName#BEFORE before},
051     * {@link TemporalOperatorName#EQUALS equals} or
052     * {@link TemporalOperatorName#AFTER  after}.</p>
053     *
054     * <p>If the first primitive is a {@link Period} and the second primitive is an {@link Instant},
055     * then this method can return one of the following values:
056     * {@link TemporalOperatorName#BEFORE   before},
057     * {@link TemporalOperatorName#ENDED_BY ended by},
058     * {@link TemporalOperatorName#CONTAINS contains},
059     * {@link TemporalOperatorName#BEGUN_BY begun by} or
060     * {@link TemporalOperatorName#AFTER    after}.</p>
061     *
062     * <p>If the first primitive is an {@link Instant} and the second primitive is a {@link Period},
063     * then this method can return one of the following values:
064     * {@link TemporalOperatorName#BEFORE before},
065     * {@link TemporalOperatorName#BEGINS begins},
066     * {@link TemporalOperatorName#DURING during},
067     * {@link TemporalOperatorName#ENDS   ends} or
068     * {@link TemporalOperatorName#AFTER  after}.</p>
069     *
070     * <p>If the two primitives are {@link Period} instances, then this method can return
071     * any of the 13 values except {@link TemporalOperatorName#ANY_INTERACTS any interacts}.</p>
072     *
073     * <h4>Exceptions</h4>
074     * This method may throw an {@link IndeterminatePositionException} if an input value is indeterminate.
075     * A {@link DateTimeException} can also be thrown if the temporal objects used by the primitives do not
076     * support the {@linkplain java.time.temporal.TemporalField temporal fields} that this method can compare.
077     *
078     * @departure harmonization
079     *   ISO 19108 defines a {@code TM_RelativePosition} code list which is identical to the
080     *   ISO 19143 {@code TemporalOperatorName} code list, except that the latter has one more
081     *   value for "any interacts". GeoAPI uses the latter for avoiding duplication.
082     *
083     * @param  other the other primitive for which to determine the relative position.
084     * @return a temporal operator which is true when evaluated between this primitive and the other primitive.
085     * @throws UnsupportedOperationException if this operation is not supported.
086     * @throws IndeterminatePositionException if a temporal position is indeterminate.
087     * @throws DateTimeException if the two temporal primitives cannot be compared.
088     *
089     * @since 3.1
090     */
091    @UML(identifier="TM_Order.relativePosition", obligation=OPTIONAL, specification=ISO_19108)
092    default TemporalOperatorName findRelativePosition(TemporalPrimitive other) {
093        throw new UnsupportedOperationException();
094    }
095}