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 * Limitation(s) placed upon the access or use of the data.
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=17)
037@UML(identifier="MD_RestrictionCode", specification=ISO_19115)
038public final class Restriction extends CodeList<Restriction> {
039    /**
040     * Serial number for compatibility with different versions.
041     */
042    private static final long serialVersionUID = 7949159742645339894L;
043
044    /**
045     * Exclusive right to the publication, production, or sale of the rights to a literary,
046     * dramatic, musical, or artistic work, or to the use of a commercial print or label,
047     * granted by law for a specified period of time to an author, composer, artist, distributor.
048     */
049    @UML(identifier="copyright", obligation=CONDITIONAL, specification=ISO_19115)
050    public static final Restriction COPYRIGHT = new Restriction("COPYRIGHT");
051
052    /**
053     * Government has granted exclusive right to make, sell, use or license an invention
054     * or discovery.
055     */
056    @UML(identifier="patent", obligation=CONDITIONAL, specification=ISO_19115)
057    public static final Restriction PATENT = new Restriction("PATENT");
058
059    /**
060     * Produced or sold information awaiting a patent.
061     */
062    @UML(identifier="patentPending", obligation=CONDITIONAL, specification=ISO_19115)
063    public static final Restriction PATENT_PENDING = new Restriction("PATENT_PENDING");
064
065    /**
066     * A name, symbol, or other device identifying a product, officially registered and
067     * legally restricted to the use of the owner or manufacturer.
068     */
069    @UML(identifier="trademark", obligation=CONDITIONAL, specification=ISO_19115)
070    public static final Restriction TRADEMARK = new Restriction("TRADEMARK");
071
072    /**
073     * Formal permission to do something.
074     * Note: it was spelled "license" in ISO 19115:2003.
075     *
076     * @since 3.1
077     */
078    @UML(identifier="licence", obligation=CONDITIONAL, specification=ISO_19115)
079    public static final Restriction LICENCE = new Restriction("LICENCE");
080
081    /**
082     * Formal permission to do something (ISO 19115:2003 spelling).
083     *
084     * @deprecated As of ISO 19115:2014, renamed {@link #LICENCE}.
085     */
086    @Deprecated(since="3.1")
087    @UML(identifier="license", obligation=CONDITIONAL, specification=ISO_19115, version=2003)
088    public static final Restriction LICENSE = LICENCE;
089
090    /**
091     * Rights to financial benefit from and control of distribution of non-tangible property
092     * that is a result of creativity.
093     */
094    @UML(identifier="intellectualPropertyRights", obligation=CONDITIONAL, specification=ISO_19115)
095    public static final Restriction INTELLECTUAL_PROPERTY_RIGHTS = new Restriction("INTELLECTUAL_PROPERTY_RIGHTS");
096
097    /**
098     * Withheld from general circulation or disclosure.
099     */
100    @UML(identifier="restricted", obligation=CONDITIONAL, specification=ISO_19115)
101    public static final Restriction RESTRICTED = new Restriction("RESTRICTED");
102
103    /**
104     * Limitation not listed.
105     */
106    @UML(identifier="otherRestrictions", obligation=CONDITIONAL, specification=ISO_19115)
107    public static final Restriction OTHER_RESTRICTIONS = new Restriction("OTHER_RESTRICTIONS");
108
109    /**
110     * No constraints exist.
111     *
112     * @since 3.1
113     */
114    @UML(identifier="unrestricted", obligation=CONDITIONAL, specification=ISO_19115)
115    public static final Restriction UNRESTRICTED = new Restriction("UNRESTRICTED");
116
117    /**
118     * Formal permission not required to use the resource.
119     *
120     * @since 3.1
121     */
122    @UML(identifier="licenceUnrestricted", obligation=CONDITIONAL, specification=ISO_19115)
123    public static final Restriction LICENCE_UNRESTRICTED = new Restriction("LICENCE_UNRESTRICTED");
124
125    /**
126     * Formal permission required for a person or an entity to use the resource
127     * and that may differ from the person that orders or purchases it.
128     *
129     * @since 3.1
130     */
131    @UML(identifier="licenceEndUser", obligation=CONDITIONAL, specification=ISO_19115)
132    public static final Restriction LICENCE_END_USER = new Restriction("LICENCE_END_USER");
133
134    /**
135     * Formal permission required for a person or an entity to commercialize or
136     * distribute the resource.
137     *
138     * @since 3.1
139     */
140    @UML(identifier="licenceDistributor", obligation=CONDITIONAL, specification=ISO_19115)
141    public static final Restriction LICENCE_DISTRIBUTOR = new Restriction("LICENCE_DISTRIBUTOR");
142
143    /**
144     * Protects rights of individual or organisations from observation, intrusion,
145     * or attention of others.
146     *
147     * @since 3.1
148     */
149    @UML(identifier="private", obligation=CONDITIONAL, specification=ISO_19115)
150    public static final Restriction PRIVATE = new Restriction("PRIVATE");
151
152    /**
153     * Prescribed by law.
154     *
155     * @since 3.1
156     */
157    @UML(identifier="statutory", obligation=CONDITIONAL, specification=ISO_19115)
158    public static final Restriction STATUTORY = new Restriction("STATUTORY");
159
160    /**
161     * Not available to the public contains information that could be prejudicial
162     * to a commercial, industrial, or national interest.
163     *
164     * @since 3.1
165     */
166    @UML(identifier="confidential", obligation=CONDITIONAL, specification=ISO_19115)
167    public static final Restriction CONFIDENTIAL = new Restriction("CONFIDENTIAL");
168
169    /**
170     * Although unclassified, requires strict controls over its distribution.
171     *
172     * @since 3.1
173     */
174    @UML(identifier="sensitiveButUnclassified", obligation=CONDITIONAL, specification=ISO_19115)
175    public static final Restriction SENSITIVE_BUT_UNCLASSIFIED = new Restriction("SENSITIVE_BUT_UNCLASSIFIED");
176
177    /**
178     * With trust.
179     *
180     * @since 3.1
181     */
182    @UML(identifier="in-confidence", obligation=CONDITIONAL, specification=ISO_19115)
183    public static final Restriction IN_CONFIDENCE = new Restriction("IN_CONFIDENCE");
184
185    /**
186     * Constructs an element of the given name.
187     *
188     * @param name  the name of the new element. This name shall not be in use by another element of this type.
189     */
190    private Restriction(final String name) {
191        super(name);
192    }
193
194    /**
195     * Returns the programmatic name and the UML identifier of this code, together with legacy UML identifier
196     * if any. In particular, {@link #LICENCE} is known as both {@code "licence"} (from ISO 19115:2014) and
197     * {@code "license"} (from ISO 19115:2003).
198     *
199     * @return Names of this code, including legacy names if any.
200     */
201    @Override
202    public String[] names() {
203        if (this == LICENSE) {
204            return new String[] {"LICENCE", "LICENSE", "licence", "license"};
205        }
206        return super.names();
207    }
208
209    /**
210     * Returns the list of {@code Restriction}s.
211     *
212     * @return the list of codes declared in the current JVM.
213     */
214    public static Restriction[] values() {
215        return values(Restriction.class);
216    }
217
218    /**
219     * Returns the list of codes of the same kind as this code list element.
220     * Invoking this method is equivalent to invoking {@link #values()}, except that
221     * this method can be invoked on an instance of the parent {@code CodeList} class.
222     *
223     * @return all code {@linkplain #values() values} for this code list.
224     */
225    @Override
226    public Restriction[] family() {
227        return values();
228    }
229
230    /**
231     * Returns the restriction that matches the given string, or returns a new one if none match it.
232     * This methods returns the first instance (in declaration order) for which the {@linkplain #name() name}
233     * is {@linkplain String#equalsIgnoreCase(String) equals, ignoring case}, to the given name.
234     * If no existing instance is found, then a new one is created for the given name.
235     *
236     * <p>For compatibility reasons, the {@code "LICENSE"} string (derived from ISO 19115:2003)
237     * is taken as synonymous to {@code "LICENCE"} (derived from ISO 19115:2014).</p>
238     *
239     * @param  code  the name of the code to fetch or to create.
240     * @return a code matching the given name.
241     */
242    public static Restriction valueOf(String code) {
243        if ("LICENSE".equals(code)) {
244            code = "LICENCE";           // For compatibility between ISO 19115:2003 and ISO 19115:2014.
245        }
246        return valueOf(Restriction.class, code, Restriction::new).get();
247    }
248}