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 org.opengis.util.CodeList;
021import org.opengis.annotation.UML;
022import org.opengis.geoapi.internal.Vocabulary;
023
024import static org.opengis.annotation.Obligation.*;
025import static org.opengis.annotation.Specification.*;
026
027
028/**
029 * Class of information to which the referencing entity applies.
030 *
031 * @author  Martin Desruisseaux (IRD)
032 * @author  Cory Horner (Refractions Research)
033 * @author  Rémi Maréchal (Geomatys)
034 * @version 3.1
035 * @since   2.0
036 *
037 * @see Scope
038 */
039@Vocabulary(capacity=26)
040@UML(identifier="MD_ScopeCode", specification=ISO_19115)
041public final class ScopeCode extends CodeList<ScopeCode> {
042    /**
043     * Serial number for compatibility with different versions.
044     */
045    private static final long serialVersionUID = -4542429199783894255L;
046
047    /**
048     * Information applies to the collection hardware class.
049     */
050    @UML(identifier="collectionHardware", obligation=CONDITIONAL, specification=ISO_19115)
051    public static final ScopeCode COLLECTION_HARDWARE = new ScopeCode("COLLECTION_HARDWARE");
052
053    /**
054     * Information applies to the collection session.
055     */
056    @UML(identifier="collectionSession", obligation=CONDITIONAL, specification=ISO_19115)
057    public static final ScopeCode COLLECTION_SESSION = new ScopeCode("COLLECTION_SESSION");
058
059    /**
060     * Information applies to a collection of spatial data which share similar characteristics of theme,
061     * source date, resolution, and methodology. The exact definition of what constitutes a series
062     * is determined by the data provider. Examples of data series metadata entries may include:
063     *
064     * <ul>
065     *   <li>A flight line of digital aerial photographs collected during a single flight with one camera and film type.</li>
066     *   <li>A continuous scan swathe collected from a satellite using the same sensors on a single orbital pass.</li>
067     *   <li>A collection of raster map data captured from a common series of paper maps.</li>
068     *   <li>A collection of vector datasets depicting surface hydrography with associated attribution
069     *        for multiple administrative areas within a country.</li>
070     * </ul>
071     */
072    @UML(identifier="series", obligation=CONDITIONAL, specification=ISO_19115)
073    public static final ScopeCode SERIES = new ScopeCode("SERIES");
074
075    /**
076     * Information applies to a consistent spatial data product that can be provided by a
077     * data distributor. A dataset may be a member of a data {@linkplain #SERIES series}.
078     * A dataset may be composed of a set of feature {@linkplain #FEATURE_TYPE types} and
079     * {@linkplain #FEATURE instances}, and attribute {@linkplain #ATTRIBUTE_TYPE types} and
080     * {@linkplain #ATTRIBUTE instances}.
081     *
082     * @see ScopeDescription#getDataset()
083     */
084    @UML(identifier="dataset", obligation=CONDITIONAL, specification=ISO_19115)
085    public static final ScopeCode DATASET = new ScopeCode("DATASET");
086
087    /**
088     * Information applies to non-geographic data.
089     */
090    @UML(identifier="nonGeographicDataset", obligation=CONDITIONAL, specification=ISO_19115)
091    public static final ScopeCode NON_GEOGRAPHIC_DATASET = new ScopeCode("NON_GEOGRAPHIC_DATASET");
092
093    /**
094     * Information applies to a dimension group.
095     */
096    @UML(identifier="dimensionGroup", obligation=CONDITIONAL, specification=ISO_19115)
097    public static final ScopeCode DIMENSION_GROUP = new ScopeCode("DIMENSION_GROUP");
098
099    /**
100     * Information applies to a group of spatial primitives (geometric objects) that have a
101     * common type. Example (compare with {@linkplain #FEATURE}):
102     *
103     * <ul>
104     *   <li>All bridges within a dataset.</li>
105     * </ul>
106     *
107     * Feature type metadata are grouped in {@linkplain #DATASET dataset}s.
108     *
109     * @see ScopeDescription#getFeatures()
110     */
111    @UML(identifier="featureType", obligation=CONDITIONAL, specification=ISO_19115)
112    public static final ScopeCode FEATURE_TYPE = new ScopeCode("FEATURE_TYPE");
113
114    /**
115     * Information applies to spatial constructs (features) that have a direct correspondence
116     * with a real world object. Examples (compare with {@linkplain #FEATURE_TYPE}):
117     *
118     * <ul>
119     *   <li>The Sydney harbour bridge.</li>
120     *   <li>The Golden Gate bridge, in San Francisco.</li>
121     * </ul>
122     *
123     * Feature instance metadata are grouped in {@linkplain #DATASET dataset}s.
124     *
125     * @see ScopeDescription#getFeatureInstances()
126     */
127    @UML(identifier="feature", obligation=CONDITIONAL, specification=ISO_19115)
128    public static final ScopeCode FEATURE = new ScopeCode("FEATURE");
129
130    /**
131     * Information applies to the characteristic of a feature.
132     * Attribute types are the digital parameters that describe a common aspect of grouped spatial
133     * primitives (geometric objects). Example (compare with {@linkplain #ATTRIBUTE}):
134     *
135     * <ul>
136     *   <li>Overhead clearance associated with a bridge.</li>
137     * </ul>
138     *
139     * Attribute type metadata are grouped in {@linkplain #DATASET dataset}s.
140     *
141     * @see ScopeDescription#getAttributes()
142     */
143    @UML(identifier="attributeType", obligation=CONDITIONAL, specification=ISO_19115)
144    public static final ScopeCode ATTRIBUTE_TYPE = new ScopeCode("ATTRIBUTE_TYPE");
145
146    /**
147     * Information applies to the attribute value.
148     * Attribute instances are the digital parameters that describe an aspect of a feature instance.
149     * Example (compare with {@linkplain #ATTRIBUTE_TYPE}):
150     *
151     * <ul>
152     *   <li>The overhead clearance associated with a specific bridge across a road.</li>
153     * </ul>
154     *
155     * Attribute instance metadata are grouped in {@linkplain #DATASET dataset}s.
156     *
157     * @see ScopeDescription#getAttributeInstances()
158     */
159    @UML(identifier="attribute", obligation=CONDITIONAL, specification=ISO_19115)
160    public static final ScopeCode ATTRIBUTE = new ScopeCode("ATTRIBUTE");
161
162    /**
163     * Information applies to a property type.
164     */
165    @UML(identifier="propertyType", obligation=CONDITIONAL, specification=ISO_19115)
166    public static final ScopeCode PROPERTY_TYPE = new ScopeCode("PROPERTY_TYPE");
167
168    /**
169     * Information applies to a field session.
170     */
171    @UML(identifier="fieldSession", obligation=CONDITIONAL, specification=ISO_19115)
172    public static final ScopeCode FIELD_SESSION = new ScopeCode("FIELD_SESSION");
173
174    /**
175     * Information applies to a computer program or routine.
176     */
177    @UML(identifier="software", obligation=CONDITIONAL, specification=ISO_19115)
178    public static final ScopeCode SOFTWARE = new ScopeCode("SOFTWARE");
179
180    /**
181     * Information applies to a capability which a service provider entity makes available
182     * to a service user entity through a set of interfaces that define a behaviour, such as
183     * a use case.
184     */
185    @UML(identifier="service", obligation=CONDITIONAL, specification=ISO_19115)
186    public static final ScopeCode SERVICE = new ScopeCode("SERVICE");
187
188    /**
189     * Information applies to a copy or imitation of an existing or hypothetical object.
190     */
191    @UML(identifier="model", obligation=CONDITIONAL, specification=ISO_19115)
192    public static final ScopeCode MODEL = new ScopeCode("MODEL");
193
194    /**
195     * Information applies to a tile, a spatial subset of geographic data.
196     */
197    @UML(identifier="tile", obligation=CONDITIONAL, specification=ISO_19115)
198    public static final ScopeCode TILE = new ScopeCode("TILE");
199
200    /**
201     * Information applies to metadata.
202     *
203     * @since 3.1
204     */
205    @UML(identifier="metadata", obligation=CONDITIONAL, specification=ISO_19115)
206    public static final ScopeCode METADATA = new ScopeCode("METADATA");
207
208    /**
209     * Information applies to an initiative.
210     *
211     * @since 3.1
212     */
213    @UML(identifier="initiative", obligation=CONDITIONAL, specification=ISO_19115)
214    public static final ScopeCode INITIATIVE = new ScopeCode("INITIATIVE");
215
216    /**
217     * Information applies to a sample.
218     *
219     * @since 3.1
220     */
221    @UML(identifier="sample", obligation=CONDITIONAL, specification=ISO_19115)
222    public static final ScopeCode SAMPLE = new ScopeCode("SAMPLE");
223
224    /**
225     * Information applies to a document.
226     *
227     * @since 3.1
228     */
229    @UML(identifier="document", obligation=CONDITIONAL, specification=ISO_19115)
230    public static final ScopeCode DOCUMENT = new ScopeCode("DOCUMENT");
231
232    /**
233     * Information applies to a repository.
234     *
235     * @since 3.1
236     */
237    @UML(identifier="repository", obligation=CONDITIONAL, specification=ISO_19115)
238    public static final ScopeCode REPOSITORY = new ScopeCode("REPOSITORY");
239
240    /**
241     * Information applies to an aggregate resource.
242     *
243     * @since 3.1
244     */
245    @UML(identifier="aggregate", obligation=CONDITIONAL, specification=ISO_19115)
246    public static final ScopeCode AGGREGATE = new ScopeCode("AGGREGATE");
247
248    /**
249     * Metadata describing an ISO 19131 data product specification.
250     *
251     * @since 3.1
252     */
253    @UML(identifier="product", obligation=CONDITIONAL, specification=ISO_19115)
254    public static final ScopeCode PRODUCT = new ScopeCode("PRODUCT");
255
256    /**
257     * Information applies to an unstructured set.
258     *
259     * @since 3.1
260     */
261    @UML(identifier="collection", obligation=CONDITIONAL, specification=ISO_19115)
262    public static final ScopeCode COLLECTION = new ScopeCode("COLLECTION");
263
264    /**
265     * Information applies to a coverage.
266     *
267     * @since 3.1
268     */
269    @UML(identifier="coverage", obligation=CONDITIONAL, specification=ISO_19115)
270    public static final ScopeCode COVERAGE = new ScopeCode("COVERAGE");
271
272    /**
273     * Information resource hosted on a specific set of hardware and accessible over network.
274     *
275     * @since 3.1
276     */
277    @UML(identifier="application", obligation=CONDITIONAL, specification=ISO_19115)
278    public static final ScopeCode APPLICATION = new ScopeCode("APPLICATION");
279
280    /**
281     * Constructs an element of the given name.
282     *
283     * @param name  the name of the new element. This name shall not be in use by another element of this type.
284     */
285    private ScopeCode(final String name) {
286        super(name);
287    }
288
289    /**
290     * Returns the list of {@code ScopeCode}s.
291     *
292     * @return the list of codes declared in the current JVM.
293     */
294    public static ScopeCode[] values() {
295        return values(ScopeCode.class);
296    }
297
298    /**
299     * Returns the list of codes of the same kind as this code list element.
300     * Invoking this method is equivalent to invoking {@link #values()}, except that
301     * this method can be invoked on an instance of the parent {@code CodeList} class.
302     *
303     * @return all code {@linkplain #values() values} for this code list.
304     */
305    @Override
306    public ScopeCode[] family() {
307        return values();
308    }
309
310    /**
311     * Returns the scope code that matches the given string, or returns a new one if none match it.
312     * This methods returns the first instance (in declaration order) for which the {@linkplain #name() name}
313     * is {@linkplain String#equalsIgnoreCase(String) equals, ignoring case}, to the given name.
314     * If no existing instance is found, then a new one is created for the given name.
315     *
316     * @param  code  the name of the code to fetch or to create.
317     * @return a code matching the given name.
318     */
319    public static ScopeCode valueOf(String code) {
320        return valueOf(ScopeCode.class, code, ScopeCode::new).get();
321    }
322}