001/*
002 *    GeoAPI - Java interfaces for OGC/ISO standards
003 *    Copyright © 2004-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.metadata.maintenance;
019
020import java.util.Date;
021import java.util.Collection;
022import java.util.Collections;
023import java.util.LinkedHashSet;
024import org.opengis.metadata.citation.DateType;
025import org.opengis.metadata.citation.CitationDate;
026import org.opengis.metadata.citation.Responsibility;
027import org.opengis.metadata.citation.ResponsibleParty;
028import org.opengis.temporal.PeriodDuration;
029import org.opengis.util.InternationalString;
030import org.opengis.geoapi.internal.Legacy;
031import org.opengis.annotation.UML;
032
033import static org.opengis.annotation.Obligation.*;
034import static org.opengis.annotation.Specification.*;
035
036
037/**
038 * Information about the scope and frequency of updating.
039 *
040 * @author  Martin Desruisseaux (IRD)
041 * @author  Cory Horner (Refractions Research)
042 * @author  Rémi Maréchal (Geomatys)
043 * @version 3.1
044 * @since   2.0
045 */
046@UML(identifier="MD_MaintenanceInformation", specification=ISO_19115)
047public interface MaintenanceInformation {
048    /**
049     * Frequency with which changes and additions are made to the resource after the
050     * initial resource is completed.
051     *
052     * @return frequency with which changes and additions are made to the resource.
053     */
054    @UML(identifier="maintenanceAndUpdateFrequency", obligation=OPTIONAL, specification=ISO_19115)
055    default MaintenanceFrequency getMaintenanceAndUpdateFrequency() {
056        return null;
057    }
058
059    /**
060     * Date information associated with maintenance of resource.
061     * Returns an empty collection if none.
062     *
063     * @return date information associated with maintenance of resource.
064     *
065     * @since 3.1
066     */
067    @UML(identifier="maintenanceDate", obligation=OPTIONAL, specification=ISO_19115)
068    default Collection<? extends CitationDate> getMaintenanceDates() {
069        return Collections.emptyList();
070    }
071
072    /**
073     * Scheduled revision date for resource.
074     *
075     * @return scheduled revision date, or {@code null}.
076     *
077     * @deprecated As of ISO 19115:2014, replaced by {@link #getMaintenanceDates()} in order to enable inclusion
078     *             of a {@link org.opengis.metadata.citation.DateType} to describe the type of the date.
079     *             Note that {@link org.opengis.metadata.citation.DateType#NEXT_UPDATE} was added to that code list.
080     */
081    @Deprecated(since="3.1")
082    @UML(identifier="dateOfNextUpdate", obligation=OPTIONAL, specification=ISO_19115, version=2003)
083    default Date getDateOfNextUpdate() {
084        return Legacy.getDate(getMaintenanceDates(), DateType.NEXT_UPDATE);
085    }
086
087    /**
088     * Maintenance period other than those defined.
089     *
090     * <div class="warning"><b>Upcoming API change — standard time API</b><br>
091     * The return type of this method may change in GeoAPI 4.0. It may be replaced by
092     * the {@link java.time.temporal.TemporalAmount} from the standard time Java API.
093     * In order to anticipate that change, callers should assign the returned value
094     * to a {@code TemporalAmount} type instead of {@code PeriodDuration}.
095     * </div>
096     *
097     * @return the maintenance period, or {@code null}.
098     */
099    @UML(identifier="userDefinedMaintenanceFrequency", obligation=OPTIONAL, specification=ISO_19115)
100    default PeriodDuration getUserDefinedMaintenanceFrequency() {
101        return null;
102    }
103
104    /**
105     * Type of resource and / or extent to which the maintenance information applies.
106     *
107     * @return type of resource and / or extent to which the maintenance information applies, or {@code null} if none.
108     *
109     * @since 3.1
110     */
111    @UML(identifier="maintenanceScope", obligation=OPTIONAL, specification=ISO_19115)
112    default Collection<? extends Scope> getMaintenanceScopes() {
113        return Collections.emptyList();
114    }
115
116    /**
117     * Scope of data to which maintenance is applied.
118     *
119     * @return scope of data to which maintenance is applied.
120     *
121     * @deprecated As of ISO 19115:2014, {@code getUpdateScopes()} and {@link #getUpdateScopeDescriptions()}
122     *             were combined into {@link #getMaintenanceScopes()} in order to allow specifying a scope
123     *             that includes a spatial and temporal extent.
124     */
125    @Deprecated(since="3.1")
126    @UML(identifier="updateScope", obligation=OPTIONAL, specification=ISO_19115, version=2003)
127    default Collection<ScopeCode> getUpdateScopes() {
128        LinkedHashSet<ScopeCode> codes = new LinkedHashSet<>();
129        getMaintenanceScopes().forEach((scope) -> {
130            codes.add(scope.getLevel());
131        });
132        return codes;
133    }
134
135    /**
136     * Additional information about the range or extent of the resource.
137     *
138     * @return additional information about the range or extent of the resource.
139     *
140     * @deprecated As of ISO 19115:2014, {@link #getUpdateScopes()} and {@code getUpdateScopeDescriptions()}
141     *             were combined into {@link #getMaintenanceScopes()} in order to allow specifying a scope
142     *             that includes a spatial and temporal extent.
143     */
144    @Deprecated(since="3.1")
145    @UML(identifier="updateScopeDescription", obligation=OPTIONAL, specification=ISO_19115, version=2003)
146    default Collection<? extends ScopeDescription> getUpdateScopeDescriptions() {
147        for (Scope scope : getMaintenanceScopes()) {
148            Collection<? extends ScopeDescription> desc = scope.getLevelDescription();
149            if (desc != null) return desc;
150        }
151        return Collections.emptyList();
152    }
153
154    /**
155     * Information regarding specific requirements for maintaining the resource.
156     *
157     * @return information regarding specific requirements for maintaining the resource.
158     */
159    @UML(identifier="maintenanceNote", obligation=OPTIONAL, specification=ISO_19115)
160    default Collection<? extends InternationalString> getMaintenanceNotes() {
161        return Collections.emptyList();
162    }
163
164    /**
165     * Identification of, and means of communicating with,
166     * person(s) and organization(s) with responsibility for maintaining the resource.
167     *
168     * <div class="warning"><b>Upcoming API change — generalization</b><br>
169     * As of ISO 19115:2014, {@code ResponsibleParty} is replaced by the {@link Responsibility} parent interface.
170     * This change may be applied in GeoAPI 4.0.
171     * </div>
172     *
173     * @return means of communicating with person(s) and organization(s) with responsibility
174     *         for maintaining the resource.
175     */
176    @UML(identifier="contact", obligation=OPTIONAL, specification=ISO_19115, version=2003)
177    default Collection<? extends ResponsibleParty> getContacts() {
178        return Collections.emptyList();
179    }
180}