001/*
002 *    GeoAPI - Java interfaces for OGC/ISO standards
003 *    Copyright © 2009-2023 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.metadata.acquisition;
019
020import java.util.Collection;
021import java.util.Collections;
022import java.util.Date;
023import java.time.temporal.Temporal;
024import org.opengis.metadata.Identifier;
025import org.opengis.geoapi.internal.Legacy;
026import org.opengis.annotation.UML;
027
028import static org.opengis.annotation.Obligation.*;
029import static org.opengis.annotation.Specification.*;
030
031
032/**
033 * Identification of a significant collection point within an operation.
034 *
035 * @author  Cédric Briançon (Geomatys)
036 * @version 3.1
037 * @since   2.3
038 */
039@UML(identifier="MI_Event", specification=ISO_19115_2)
040public interface Event {
041    /**
042     * Event name or number.
043     *
044     * @return event name or number.
045     */
046    @UML(identifier="identifier", obligation=MANDATORY, specification=ISO_19115_2)
047    Identifier getIdentifier();
048
049    /**
050     * Initiator of the event.
051     *
052     * @return initiator of the event.
053     */
054    @UML(identifier="trigger", obligation=MANDATORY, specification=ISO_19115_2)
055    Trigger getTrigger();
056
057    /**
058     * Meaning of the event.
059     *
060     * @return meaning of the event.
061     */
062    @UML(identifier="context", obligation=MANDATORY, specification=ISO_19115_2)
063    Context getContext();
064
065    /**
066     * Relative time ordering of the event.
067     *
068     * @return relative time ordering.
069     */
070    @UML(identifier="sequence", obligation=MANDATORY, specification=ISO_19115_2)
071    Sequence getSequence();
072
073    /**
074     * Time the event occurred.
075     *
076     * @return time the event occurred.
077     *
078     * @deprecated Replaced by {@link #getDateOfOccurrence()}.
079     */
080    @Deprecated(since="3.1")
081    default Date getTime() {
082        return Legacy.toDate(getDateOfOccurrence());
083    }
084
085    /**
086     * Date and time the event occurred.
087     * The returned value should be an instance of {@link java.time.LocalDate}, {@link java.time.LocalDateTime},
088     * {@link java.time.OffsetDateTime} or {@link java.time.ZonedDateTime}, depending whether hours are defined
089     * and how the timezone (if any) is defined. But other types are also allowed.
090     *
091     * @return time the event occurred.
092     *
093     * @departure historical
094     *   Renamed for avoiding a conflict with the {@code getTime()} method defined in GeoAPI 3.0.
095     *
096     * @since 3.1
097     */
098    @UML(identifier="time", obligation=MANDATORY, specification=ISO_19115_2)
099    Temporal getDateOfOccurrence();
100
101    /**
102     * Objective or objectives satisfied by an event.
103     *
104     * @return objectives satisfied by an event.
105     */
106    @UML(identifier="expectedObjective", obligation=OPTIONAL, specification=ISO_19115_2)
107    default Collection<? extends Objective> getExpectedObjectives() {
108        return Collections.emptyList();
109    }
110
111    /**
112     * Pass during which an event occurs.
113     *
114     * @return pass during which an event occurs, or {@code null}.
115     */
116    @UML(identifier="relatedPass", obligation=OPTIONAL, specification=ISO_19115_2)
117    default PlatformPass getRelatedPass() {
118        return null;
119    }
120
121    /**
122     * Instrument or instruments for which the event is meaningful.
123     *
124     * @return instruments for which the event is meaningful.
125     */
126    @UML(identifier="relatedSensor", obligation=OPTIONAL, specification=ISO_19115_2)
127    default Collection<? extends Instrument> getRelatedSensors() {
128        return Collections.emptyList();
129    }
130}