001/*
002 *    GeoAPI - Java interfaces for OGC/ISO standards
003 *    Copyright © 2004-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.lineage;
019
020import java.util.Collection;
021import java.util.Collections;
022import java.util.Date;
023import org.opengis.util.InternationalString;
024import org.opengis.metadata.citation.Citation;
025import org.opengis.metadata.citation.Responsibility;
026import org.opengis.metadata.citation.ResponsibleParty;
027import org.opengis.metadata.maintenance.Scope;
028import org.opengis.temporal.TemporalPrimitive;
029import org.opengis.geoapi.internal.Legacy;
030import org.opengis.annotation.UML;
031
032import static org.opengis.annotation.Obligation.*;
033import static org.opengis.annotation.Specification.*;
034
035
036/**
037 * Information about an event or transformation in the life of resource.
038 * This includes the process used to maintain the resource.
039 *
040 * @author  Martin Desruisseaux (IRD)
041 * @author  Cédric Briançon (Geomatys)
042 * @author  Rémi Maréchal (Geomatys)
043 * @version 3.1
044 * @since   2.0
045 */
046@UML(identifier="LI_ProcessStep", specification=ISO_19115)
047public interface ProcessStep {
048    /**
049     * Description of the event, including related parameters or tolerances.
050     *
051     * @return description of the event.
052     */
053    @UML(identifier="description", obligation=MANDATORY, specification=ISO_19115)
054    InternationalString getDescription();
055
056    /**
057     * Requirement or purpose for the process step.
058     *
059     * @return requirement or purpose for the process step, or {@code null} if none.
060     */
061    @UML(identifier="rationale", obligation=OPTIONAL, specification=ISO_19115)
062    default InternationalString getRationale() {
063        return null;
064    }
065
066    /**
067     * Date and time on which the process step occurred.
068     *
069     * @return date on which the process step occurred, or {@code null} if none.
070     *
071     * @deprecated Replaced by {@link #getStepDateTime()} as of ISO 19115:2014.
072     */
073    @Deprecated(since="3.1")
074    @UML(identifier="dateTime", obligation=OPTIONAL, specification=ISO_19115, version=2003)
075    default Date getDate() {
076        return Legacy.toDate(getStepDateTime());
077    }
078
079    /**
080     * Date and time or range of date and time on or over which the process step occurred.
081     *
082     * @return date on or over which the process step occurred, or {@code null} if none.
083     *
084     * @since 3.1
085     */
086    @UML(identifier="stepDateTime", obligation=OPTIONAL, specification=ISO_19115)
087    default TemporalPrimitive getStepDateTime() {
088        return null;
089    }
090
091    /**
092     * Identification of, and means of communication with, person(s) and
093     * organization(s) associated with the process step.
094     *
095     * <div class="warning"><b>Upcoming API change — generalization</b><br>
096     * As of ISO 19115:2014, {@code ResponsibleParty} is replaced by the {@link Responsibility} parent interface.
097     * This change may be applied in GeoAPI 4.0.
098     * </div>
099     *
100     * @return means of communication with person(s) and organization(s) associated with the process step.
101     */
102    @UML(identifier="processor", obligation=OPTIONAL, specification=ISO_19115, version=2003)
103    default Collection<? extends ResponsibleParty> getProcessors() {
104        return Collections.emptyList();
105    }
106
107    /**
108     * Process step documentation.
109     * Returns an empty collection if none.
110     *
111     * @return process step documentation.
112     *
113     * @since 3.1
114     */
115    @UML(identifier="reference", obligation=OPTIONAL, specification=ISO_19115)
116    default Collection<? extends Citation> getReferences() {
117        return Collections.emptyList();
118    }
119
120    /**
121     * Type of resource and / or extent to which the process step applies.
122     *
123     * @return type of resource and / or extent to which the process step applies, or {@code null} if none.
124     *
125     * @since 3.1
126     */
127    @UML(identifier="scope", obligation=OPTIONAL, specification=ISO_19115)
128    default Scope getScope() {
129        return null;
130    }
131
132    /**
133     * Information about the source data used in creating the data specified by the scope.
134     * Returns an empty collection if none.
135     *
136     * @return information about the source data used in creating the data.
137     */
138    @UML(identifier="source", obligation=OPTIONAL, specification=ISO_19115)
139    default Collection<? extends Source> getSources() {
140        return Collections.emptyList();
141    }
142
143    /**
144     * Description of the product generated as a result of the process step.
145     *
146     * @return product generated as a result of the process step.
147     */
148    @UML(identifier="output", obligation=OPTIONAL, specification=ISO_19115_2)
149    default Collection<? extends Source> getOutputs() {
150        return Collections.emptyList();
151    }
152
153    /**
154     * Comprehensive information about the procedure by which the algorithm was applied
155     * to derive geographic data from the raw instrument measurements, such as datasets,
156     * software used, and the processing environment.
157     *
158     * @return procedure by which the algorithm was applied to derive geographic data,
159     *         or {@code null}.
160     */
161    @UML(identifier="processingInformation", obligation=OPTIONAL, specification=ISO_19115_2)
162    default Processing getProcessingInformation() {
163        return null;
164    }
165
166    /**
167     * Report generated by the process step.
168     *
169     * @return report generated by the process step.
170     */
171    @UML(identifier="report", obligation=OPTIONAL, specification=ISO_19115_2)
172    default Collection<? extends ProcessStepReport> getReports() {
173        return Collections.emptyList();
174    }
175}