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.constraint;
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 * Name of the handling restrictions on the dataset.
030 *
031 * @author  Martin Desruisseaux (IRD)
032 * @author  Rémi Maréchal (Geomatys)
033 * @version 3.1
034 * @since   2.0
035 */
036@Vocabulary(capacity=9)
037@UML(identifier="MD_ClassificationCode", specification=ISO_19115)
038public final class Classification extends CodeList<Classification> {
039    /**
040     * Serial number for compatibility with different versions.
041     */
042    private static final long serialVersionUID = -549174931332214797L;
043
044    /**
045     * Available for general disclosure.
046     */
047    @UML(identifier="unclassified", obligation=CONDITIONAL, specification=ISO_19115)
048    public static final Classification UNCLASSIFIED = new Classification("UNCLASSIFIED");
049
050    /**
051     * Not for general disclosure.
052     */
053    @UML(identifier="restricted", obligation=CONDITIONAL, specification=ISO_19115)
054    public static final Classification RESTRICTED = new Classification("RESTRICTED");
055
056    /**
057     * Available for someone who can be entrusted with information.
058     */
059    @UML(identifier="confidential", obligation=CONDITIONAL, specification=ISO_19115)
060    public static final Classification CONFIDENTIAL = new Classification("CONFIDENTIAL");
061
062    /**
063     * Kept or meant to be kept private, unknown, or hidden from all but a select group of people.
064     */
065    @UML(identifier="secret", obligation=CONDITIONAL, specification=ISO_19115)
066    public static final Classification SECRET = new Classification("SECRET");
067
068    /**
069     * Of the highest secrecy.
070     */
071    @UML(identifier="topSecret", obligation=CONDITIONAL, specification=ISO_19115)
072    public static final Classification TOP_SECRET = new Classification("TOP_SECRET");
073
074    /**
075     * Although unclassified, requires strict controls over its distribution.
076     *
077     * @since 3.1
078     */
079    @UML(identifier="sensitiveButUnclassified", obligation=CONDITIONAL, specification=ISO_19115)
080    public static final Classification SENSITIVE_BUT_UNCLASSIFIED = new Classification("SENSITIVE_BUT_UNCLASSIFIED");
081
082    /**
083     * Unclassified information that is to be used only for official purposes
084     * determinate by the designating body.
085     *
086     * @since 3.1
087     */
088    @UML(identifier="forOfficialUseOnly", obligation=CONDITIONAL, specification=ISO_19115)
089    public static final Classification FOR_OFFICIAL_USE_ONLY = new Classification("FOR_OFFICIAL_USE_ONLY");
090
091    /**
092     * Compromise of the information could cause damage.
093     *
094     * @since 3.1
095     */
096    @UML(identifier="protected", obligation=CONDITIONAL, specification=ISO_19115)
097    public static final Classification PROTECTED = new Classification("PROTECTED");
098
099    /**
100     * Dissemination limited by designating body.
101     *
102     * @since 3.1
103     */
104    @UML(identifier="limitedDistribution", obligation=CONDITIONAL, specification=ISO_19115)
105    public static final Classification LIMITED_DISTRIBUTION = new Classification("LIMITED_DISTRIBUTION");
106
107    /**
108     * Constructs an element of the given name.
109     *
110     * @param name  the name of the new element. This name shall not be in use by another element of this type.
111     */
112    private Classification(final String name) {
113        super(name);
114    }
115
116    /**
117     * Returns the list of {@code Classification}s.
118     *
119     * @return the list of codes declared in the current JVM.
120     */
121    public static Classification[] values() {
122        return values(Classification.class);
123    }
124
125    /**
126     * Returns the list of codes of the same kind as this code list element.
127     * Invoking this method is equivalent to invoking {@link #values()}, except that
128     * this method can be invoked on an instance of the parent {@code CodeList} class.
129     *
130     * @return all code {@linkplain #values() values} for this code list.
131     */
132    @Override
133    public Classification[] family() {
134        return values();
135    }
136
137    /**
138     * Returns the classification that matches the given string, or returns a new one if none match it.
139     * This methods returns the first instance (in declaration order) for which the {@linkplain #name() name}
140     * is {@linkplain String#equalsIgnoreCase(String) equals, ignoring case}, to the given name.
141     * If no existing instance is found, then a new one is created for the given name.
142     *
143     * @param  code  the name of the code to fetch or to create.
144     * @return a code matching the given name.
145     */
146    public static Classification valueOf(String code) {
147        return valueOf(Classification.class, code, Classification::new).get();
148    }
149}