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.identification;
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 * High-level geographic data thematic classification to assist in the grouping and
030 * search of available geographic data sets. Can be used to group keywords as well.
031 * Listed examples are not exhaustive.
032 *
033 * <div class="note"><b>Note:</b>
034 * it is understood there are overlaps between general categories and the user
035 * is encouraged to select the one most appropriate.</div>
036 *
037 * <div class="warning"><b>Upcoming API change — enumeration</b><br>
038 * According ISO 19115, {@code TopicCategory} shall be an enumeration, not a code list.
039 * This class may be changed to a Java {@code enum} in GeoAPI 4.0.
040 * See <a href="http://jira.codehaus.org/browse/GEO-199">GEO-199</a> for more information.
041 * </div>
042 *
043 * @author  Martin Desruisseaux (IRD)
044 * @author  Rémi Maréchal (Geomatys)
045 * @version 3.1
046 * @since   2.0
047 */
048@Vocabulary(capacity=21)
049@UML(identifier="MD_TopicCategoryCode", specification=ISO_19115)
050public final class TopicCategory extends CodeList<TopicCategory> {
051    /**
052     * Serial number for compatibility with different versions.
053     */
054    private static final long serialVersionUID = -4987523565852255081L;
055
056    /**
057     * Rearing of animals and/or cultivation of plants.
058     *
059     * <p><b>Examples:</b>
060     * agriculture, irrigation, aquaculture, plantations, herding, pests and
061     * diseases affecting crops and livestock.
062     * </p>
063     */
064    @UML(identifier="farming", obligation=CONDITIONAL, specification=ISO_19115)
065    public static final TopicCategory FARMING = new TopicCategory("FARMING");
066
067    /**
068     * Flora and/or fauna in natural environment.
069     *
070     * <p><b>Examples:</b>
071     * wildlife, vegetation, biological sciences, ecology, wilderness, sealife, wetlands, habitat
072     * </p>
073     */
074    @UML(identifier="biota", obligation=CONDITIONAL, specification=ISO_19115)
075    public static final TopicCategory BIOTA = new TopicCategory("BIOTA");
076
077    /**
078     * Legal land descriptions.
079     *
080     * <p><b>Examples:</b>
081     * political and administrative boundaries.
082     * </p>
083     */
084    @UML(identifier="boundaries", obligation=CONDITIONAL, specification=ISO_19115)
085    public static final TopicCategory BOUNDARIES = new TopicCategory("BOUNDARIES");
086
087    /**
088     * Processes and phenomena of the atmosphere.
089     *
090     * <p><b>Examples:</b>
091     * cloud cover, weather, climate, atmospheric conditions, climate change, precipitation.
092     * </p>
093     */
094    @UML(identifier="climatologyMeteorologyAtmosphere", obligation=CONDITIONAL, specification=ISO_19115)
095    public static final TopicCategory CLIMATOLOGY_METEOROLOGY_ATMOSPHERE = new TopicCategory("CLIMATOLOGY_METEOROLOGY_ATMOSPHERE");
096
097    /**
098     * Economic activities, conditions and employment.
099     *
100     * <p><b>Examples:</b>
101     * production, labour, revenue, commerce, industry, tourism and ecotourism,
102     * forestry, fisheries, commercial or subsistence hunting,
103     * exploration and exploitation of resources such as minerals, oil and gas.
104     * </p>
105     */
106    @UML(identifier="economy", obligation=CONDITIONAL, specification=ISO_19115)
107    public static final TopicCategory ECONOMY = new TopicCategory("ECONOMY");
108
109    /**
110     * Height above or below sea level.
111     *
112     * <p><b>Examples:</b>
113     * altitude, bathymetry, digital elevation models, slope, derived products.
114     * </p>
115     */
116    @UML(identifier="elevation", obligation=CONDITIONAL, specification=ISO_19115)
117    public static final TopicCategory ELEVATION = new TopicCategory("ELEVATION");
118
119    /**
120     * Environmental resources, protection and conservation.
121     *
122     * <p><b>Examples:</b>
123     * environmental pollution, waste storage and treatment, environmental impact assessment,
124     * monitoring environmental risk, nature reserves, landscape.
125     * </p>
126     */
127    @UML(identifier="environment", obligation=CONDITIONAL, specification=ISO_19115)
128    public static final TopicCategory ENVIRONMENT = new TopicCategory("ENVIRONMENT");
129
130    /**
131     * Information pertaining to earth sciences.
132     *
133     * <p><b>Examples:</b>
134     * geophysical features and processes, geology, minerals, sciences dealing with the composition,
135     * structure and origin of the earth's rocks, risks of earthquakes, volcanic activity, landslides,
136     * gravity information, soils, permafrost, hydrogeology, erosion.
137     * </p>
138     */
139    @UML(identifier="geoscientificInformation", obligation=CONDITIONAL, specification=ISO_19115)
140    public static final TopicCategory GEOSCIENTIFIC_INFORMATION = new TopicCategory("GEOSCIENTIFIC_INFORMATION");
141
142    /**
143     * Health, health services, human ecology, and safety.
144     *
145     * <p><b>Examples:</b>
146     * disease and illness, factors affecting health, hygiene, substance abuse,
147     * mental and physical health, health services.
148     * </p>
149     */
150    @UML(identifier="health", obligation=CONDITIONAL, specification=ISO_19115)
151    public static final TopicCategory HEALTH = new TopicCategory("HEALTH");
152
153    /**
154     * Base maps.
155     *
156     * <p><b>Examples:</b>
157     * land cover, topographic maps, imagery, unclassified images, annotations.
158     * </p>
159     */
160    @UML(identifier="imageryBaseMapsEarthCover", obligation=CONDITIONAL, specification=ISO_19115)
161    public static final TopicCategory IMAGERY_BASE_MAPS_EARTH_COVER = new TopicCategory("IMAGERY_BASE_MAPS_EARTH_COVER");
162
163    /**
164     * Military bases, structures, activities.
165     *
166     * <p><b>Examples:</b>
167     * barracks, training grounds, military transportation, information collection.
168     * </p>
169     */
170    @UML(identifier="intelligenceMilitary", obligation=CONDITIONAL, specification=ISO_19115)
171    public static final TopicCategory INTELLIGENCE_MILITARY = new TopicCategory("INTELLIGENCE_MILITARY");
172
173    /**
174     * Inland water features, drainage systems and their characteristics.
175     *
176     * <p><b>Examples:</b>
177     * rivers and glaciers, salt lakes, water utilization plans, dams, currents,
178     * floods, water quality, hydrographic charts.
179     * </p>
180     */
181    @UML(identifier="inlandWaters", obligation=CONDITIONAL, specification=ISO_19115)
182    public static final TopicCategory INLAND_WATERS = new TopicCategory("INLAND_WATERS");
183
184    /**
185     * Positional information and services.
186     *
187     * <p><b>Examples:</b>
188     * addresses, geodetic networks, control points, postal zones and services, place names.
189     * </p>
190     */
191    @UML(identifier="location", obligation=CONDITIONAL, specification=ISO_19115)
192    public static final TopicCategory LOCATION = new TopicCategory("LOCATION");
193
194    /**
195     * Features and characteristics of salt water bodies (excluding inland waters).
196     *
197     * <p><b>Examples:</b>
198     * tides, tidal waves, coastal information, reefs.
199     * </p>
200     */
201    @UML(identifier="oceans", obligation=CONDITIONAL, specification=ISO_19115)
202    public static final TopicCategory OCEANS = new TopicCategory("OCEANS");
203
204    /**
205     * Information used for appropriate actions for future use of the land.
206     *
207     * <p><b>Examples:</b>
208     * land use maps, zoning maps, cadastral surveys, land ownership.
209     * </p>
210     */
211    @UML(identifier="planningCadastre", obligation=CONDITIONAL, specification=ISO_19115)
212    public static final TopicCategory PLANNING_CADASTRE = new TopicCategory("PLANNING_CADASTRE");
213
214    /**
215     * Characteristics of society and cultures.
216     *
217     * <p><b>Examples:</b>
218     * settlements, anthropology, archaeology, education, traditional beliefs, manners and customs,
219     * demographic data, recreational areas and activities, social impact assessments,
220     * crime and justice, census information
221     * </p>
222     */
223    @UML(identifier="society", obligation=CONDITIONAL, specification=ISO_19115)
224    public static final TopicCategory SOCIETY = new TopicCategory("SOCIETY");
225
226    /**
227     * Man-made construction.
228     *
229     * <p><b>Examples:</b>
230     * buildings, museums, churches, factories, housing, monuments, shops, towers.
231     * </p>
232     */
233    @UML(identifier="structure", obligation=CONDITIONAL, specification=ISO_19115)
234    public static final TopicCategory STRUCTURE = new TopicCategory("STRUCTURE");
235
236    /**
237     * Means and aids for conveying persons and/or goods.
238     *
239     * <p><b>Examples:</b>
240     * roads, airports/airstrips, shipping routes, tunnels, nautical charts,
241     * vehicle or vessel location, aeronautical charts, railways.
242     * </p>
243     */
244    @UML(identifier="transportation", obligation=CONDITIONAL, specification=ISO_19115)
245    public static final TopicCategory TRANSPORTATION = new TopicCategory("TRANSPORTATION");
246
247    /**
248     * Energy, water and waste systems and communications infrastructure and services.
249     *
250     * <p><b>Examples:</b>
251     * hydroelectricity, geothermal, solar and nuclear sources of energy, water purification and
252     * distribution, sewage collection and disposal, electricity and gas distribution,
253     * data communication, telecommunication, radio, communication networks.
254     * </p>
255     */
256    @UML(identifier="utilitiesCommunication", obligation=CONDITIONAL, specification=ISO_19115)
257    public static final TopicCategory UTILITIES_COMMUNICATION = new TopicCategory("UTILITIES_COMMUNICATION");
258
259    /**
260     * Region more than 100 Km above the surface of the Earth.
261     *
262     * @since 3.1
263     */
264    @UML(identifier="extraTerrestrial", obligation=CONDITIONAL, specification=ISO_19115)
265    public static final TopicCategory EXTRA_TERRESTRIAL = new TopicCategory("EXTRA_TERRESTRIAL");
266
267    /**
268     * Information related to disaster.
269     *
270     * <p><b>Examples:</b>
271     * site of the disaster, evacuation zone, disaster prevention facility,
272     * disaster relief activity.</p>
273     *
274     * @since 3.1
275     */
276    @UML(identifier="disaster", obligation=CONDITIONAL, specification=ISO_19115)
277    public static final TopicCategory DISASTER = new TopicCategory("DISASTER");
278
279    /**
280     * Constructs an element of the given name.
281     *
282     * @param name  the name of the new element. This name shall not be in use by an other element of this type.
283     */
284    private TopicCategory(final String name) {
285        super(name);
286    }
287
288    /**
289     * Returns the list of {@code TopicCategory}s.
290     *
291     * @return the list of codes declared in the current JVM.
292     */
293    public static TopicCategory[] values() {
294        return values(TopicCategory.class);
295    }
296
297    /**
298     * Returns the list of codes of the same kind than this code list element.
299     * Invoking this method is equivalent to invoking {@link #values()}, except that
300     * this method can be invoked on an instance of the parent {@code CodeList} class.
301     *
302     * @return all code {@linkplain #values() values} for this code list.
303     */
304    @Override
305    public TopicCategory[] family() {
306        return values();
307    }
308
309    /**
310     * Returns the topic category that matches the given string, or returns a new one if none match it.
311     * This methods returns the first instance (in declaration order) for which the {@linkplain #name() name}
312     * is {@linkplain String#equalsIgnoreCase(String) equals, ignoring case}, to the given name.
313     * If no existing instance is found, then a new one is created for the given name.
314     *
315     * @param  code  the name of the code to fetch or to create.
316     * @return a code matching the given name.
317     */
318    public static TopicCategory valueOf(String code) {
319        return valueOf(TopicCategory.class, code, TopicCategory::new).get();
320    }
321}