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.Set;
021import java.util.Collections;
022import org.opengis.annotation.UML;
023import org.opengis.annotation.Classifier;
024import org.opengis.annotation.Stereotype;
025import org.opengis.feature.type.AttributeType;
026import org.opengis.feature.type.FeatureType;
027
028import static org.opengis.annotation.Obligation.*;
029import static org.opengis.annotation.Specification.*;
030
031
032/**
033 * Description of the class of information covered by the information.
034 * Exactly one of the {@code attributes}, {@code features}, {@code featureInstances},
035 * {@code attributeInstances}, {@code dataset} and {@code other} properties shall be provided.
036 *
037 * @author  Martin Desruisseaux (IRD)
038 * @author  Cory Horner (Refractions Research)
039 * @version 3.1
040 * @since   2.0
041 */
042@Classifier(Stereotype.UNION)
043@UML(identifier="MD_ScopeDescription", specification=ISO_19115)
044public interface ScopeDescription {
045    /**
046     * Dataset to which the information applies.
047     *
048     * <div class="note"><b>Example:</b>
049     * if a geographic data provider is generating vector mapping for the administrative areas
050     * and if the data were processed in the same way, then the provider could record the bulk
051     * of initial data at {@link ScopeCode#DATASET} level with a
052     * <q>Administrative area A, B &amp; C</q> description.
053     * </div>
054     *
055     * @return dataset to which the information applies, or {@code null}.
056     *
057     * @condition {@code features}, {@code attributes}, {@code featureInstances},
058     *            {@code attributeInstances} and {@code other} not provided.
059     *
060     * @see ScopeCode#DATASET
061     */
062    @UML(identifier="dataset", obligation=CONDITIONAL, specification=ISO_19115)
063    default String getDataset() {
064        return null;
065    }
066
067    /**
068     * Feature types to which the information applies.
069     *
070     * <div class="note"><b>Example:</b>
071     * if an administrative area performs a complete re-survey of the road network,
072     * the change can be recorded at {@link ScopeCode#FEATURE_TYPE} level with a
073     * <q>Administrative area A — Road network</q> description.
074     * </div>
075     *
076     * <div class="warning"><b>Upcoming API change</b><br>
077     * As of ISO 19115:2014, the type become {@link Set<? extends CharSequence>}.
078     * This change may be applied in GeoAPI 4.0.
079     * </div>
080     *
081     * @return feature types to which the information applies.
082     *
083     * @condition {@code attributes}, {@code featureInstances}, {@code attributeInstances},
084     *            {@code dataset} and {@code other} not provided.
085     *
086     * @see ScopeCode#FEATURE_TYPE
087     */
088    @UML(identifier="features", obligation=CONDITIONAL, specification=ISO_19115, version=2003)
089    default Set<? extends FeatureType> getFeatures() {
090        return Collections.emptySet();
091    }
092
093    /**
094     * Attribute types to which the information applies.
095     *
096     * <div class="note"><b>Example:</b>
097     * if an administrative area detects an anomaly in all overhead clearance of the road survey,
098     * the correction can be recorded at {@link ScopeCode#ATTRIBUTE_TYPE} level with a
099     * <q>Administrative area A — Overhead clearance</q> description.
100     * </div>
101     *
102     * <div class="warning"><b>Upcoming API change</b><br>
103     * As of ISO 19115:2014, the type become {@link Set<? extends CharSequence>}.
104     * This change may be applied in GeoAPI 4.0.
105     * </div>
106     *
107     * @return attribute types to which the information applies.
108     *
109     * @condition {@code features}, {@code featureInstances}, {@code attributeInstances},
110     *            {@code dataset} and {@code other} not provided.
111     *
112     * @see ScopeCode#ATTRIBUTE_TYPE
113     */
114    @UML(identifier="attributes", obligation=CONDITIONAL, specification=ISO_19115, version=2003)
115    default Set<? extends AttributeType> getAttributes() {
116        return Collections.emptySet();
117    }
118
119    /**
120     * Feature instances to which the information applies.
121     *
122     * <div class="note"><b>Example:</b>
123     * if a new bridge is constructed in a road network,
124     * the change can be recorded at {@link ScopeCode#FEATURE} level with a
125     * <q>Administrative area A — New bridge</q> description.
126     * </div>
127     *
128     * <div class="warning"><b>Upcoming API change</b><br>
129     * As of ISO 19115:2014, the type become {@link Set<? extends CharSequence>}.
130     * This change may be applied in GeoAPI 4.0.
131     * </div>
132     *
133     * @return feature instances to which the information applies.
134     *
135     * @condition {@code features}, {@code attributes}, {@code attributeInstances},
136     *            {@code dataset} and {@code other} not provided.
137     *
138     * @see ScopeCode#FEATURE
139     */
140    @UML(identifier="featureInstances", obligation=CONDITIONAL, specification=ISO_19115, version=2003)
141    default Set<? extends FeatureType> getFeatureInstances() {
142        return Collections.emptySet();
143    }
144
145    /**
146     * Attribute instances to which the information applies.
147     *
148     * <div class="note"><b>Example:</b>
149     * if the overhead clearance of a new bridge was wrongly recorded,
150     * the correction can be recorded at {@link ScopeCode#ATTRIBUTE} level with a
151     * <q>Administrative area A — New bridge — Overhead clearance</q> description.
152     * </div>
153     *
154     * <div class="warning"><b>Upcoming API change</b><br>
155     * As of ISO 19115:2014, the type become {@link Set<? extends CharSequence>}.
156     * This change may be applied in GeoAPI 4.0.
157     * </div>
158     *
159     * @return attribute instances to which the information applies.
160     *
161     * @condition {@code features}, {@code attributes}, {@code featureInstances},
162     *            {@code dataset} and {@code other} not provided.
163     *
164     * @see ScopeCode#ATTRIBUTE
165     */
166    @UML(identifier="attributeInstances", obligation=CONDITIONAL, specification=ISO_19115, version=2003)
167    default Set<? extends AttributeType> getAttributeInstances() {
168        return Collections.emptySet();
169    }
170
171    /**
172     * Class of information that does not fall into the other categories to which the information applies.
173     *
174     * <div class="warning"><b>Upcoming API change — internationalization</b><br>
175     * The return type will be changed from {@code String} to {@code InternationalString} in GeoAPI 4.0.
176     * </div>
177     *
178     * @return class of information that does not fall into the other categories, or {@code null}.
179     *
180     * @condition {@code features}, {@code attributes}, {@code featureInstances},
181     *            {@code attributeInstances} and {@code dataset} not provided.
182     */
183    @UML(identifier="other", obligation=CONDITIONAL, specification=ISO_19115)
184    default String getOther() {
185        return null;
186    }
187}