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.Date;
021import java.util.Collection;
022import java.util.Collections;
023
024import org.opengis.annotation.UML;
025import org.opengis.metadata.Identifier;
026import org.opengis.metadata.citation.Citation;
027import org.opengis.metadata.citation.ResponsibleParty;
028
029import static org.opengis.annotation.Obligation.*;
030import static org.opengis.annotation.Specification.*;
031
032
033/**
034 * Requirement to be satisfied by the planned data acquisition.
035 *
036 * @author  Cédric Briançon (Geomatys)
037 * @version 3.1
038 * @since   2.3
039 */
040@UML(identifier="MI_Requirement", specification=ISO_19115_2)
041public interface Requirement {
042    /**
043     * Identification of reference or guidance material for the requirement.
044     *
045     * @return identification of reference or guidance material, or {@code null}.
046     */
047    @UML(identifier="citation", obligation=OPTIONAL, specification=ISO_19115_2)
048    default Citation getCitation() {
049        return null;
050    }
051
052    /**
053     * Unique name, or code, for the requirement.
054     *
055     * @return unique name or code.
056     */
057    @UML(identifier="identifier", obligation=MANDATORY, specification=ISO_19115_2)
058    Identifier getIdentifier();
059
060    /**
061     * Origin of requirement.
062     *
063     * <div class="warning"><b>Upcoming API change — generalization</b><br>
064     * As of ISO 19115:2014, {@code ResponsibleParty} is replaced by the {@link Responsibility} parent interface.
065     * This change may be applied in GeoAPI 4.0.
066     * </div>
067     *
068     * @return origin of requirement.
069     */
070    @UML(identifier="requestor", obligation=MANDATORY, specification=ISO_19115_2, version=2003)
071    Collection<? extends ResponsibleParty> getRequestors();
072
073    /**
074     * Person(s), or body(ies), to receive results of requirement.
075     *
076     * <div class="warning"><b>Upcoming API change — generalization</b><br>
077     * As of ISO 19115:2014, {@code ResponsibleParty} is replaced by the {@link Responsibility} parent interface.
078     * This change may be applied in GeoAPI 4.0.
079     * </div>
080     *
081     * @return person(s), or body(ies), to receive results.
082     */
083    @UML(identifier="recipient", obligation=MANDATORY, specification=ISO_19115_2, version=2003)
084    Collection<? extends ResponsibleParty> getRecipients();
085
086    /**
087     * Relative ordered importance, or urgency, of the requirement.
088     *
089     * @return relative ordered importance, or urgency.
090     */
091    @UML(identifier="priority", obligation=MANDATORY, specification=ISO_19115_2)
092    Priority getPriority();
093
094    /**
095     * Required or preferred acquisition date and time.
096     *
097     * @return required or preferred acquisition date and time.
098     */
099    @UML(identifier="requestedDate", obligation=MANDATORY, specification=ISO_19115_2)
100    RequestedDate getRequestedDate();
101
102    /**
103     * Date and time after which collection is no longer valid.
104     *
105     * <div class="warning"><b>Upcoming API change — temporal schema</b><br>
106     * As of Java 8, the {@code java.time} package is a better match for the different
107     * types of date defined by ISO 19108 (<cite>Temporal Schema</cite>) or ISO 19103.
108     * The return value of this method may be changed to {@link java.time.temporal.Temporal} in GeoAPI 4.0.
109     * </div>
110     *
111     * @return date and time after which collection is no longer valid.
112     */
113    @UML(identifier="expiryDate", obligation=MANDATORY, specification=ISO_19115_2)
114    Date getExpiryDate();
115
116    /**
117     * Plan that identifies solution to satisfy the requirement.
118     *
119     * @return plan that identifies solution to satisfy the requirement.
120     */
121    @UML(identifier="satisfiedPlan", obligation=OPTIONAL, specification=ISO_19115_2)
122    default Collection<? extends Plan> getSatisfiedPlans() {
123        return Collections.emptyList();
124    }
125}