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}