001/*
002 *    GeoAPI - Java interfaces for OGC/ISO standards
003 *    Copyright © 2005-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.annotation;
019
020import java.lang.annotation.Target;
021import java.lang.annotation.Retention;
022import java.lang.annotation.Documented;
023import static java.lang.annotation.ElementType.*;
024import static java.lang.annotation.RetentionPolicy.*;
025
026
027/**
028 * An annotation mapping each interface, methods or fields to the UML identifier where they come from.
029 *
030 * @author  Martin Desruisseaux (IRD, Geomatys)
031 * @version 3.1
032 * @since   2.0
033 */
034@Documented
035@Retention(RUNTIME)
036@Target({TYPE, FIELD, METHOD})
037public @interface UML {
038    /**
039     * The UML identifier for the annotated interface, method or code list element.
040     * Scripts can use this identifier in order to maps a GeoAPI method to the UML
041     * entity where it come from.
042     *
043     * @return the UML identifier used in the standard.
044     *
045     * @see ResourceBundles#classIndex()
046     */
047    String identifier();
048
049    /**
050     * The obligation declared in the UML. This metadata can be queried in order to
051     * determine if a null value is allowed for the annotated method or not. If the
052     * obligation is {@link Obligation#MANDATORY}, then null value are not allowed.
053     *
054     * @return the obligation declared in the standard.
055     */
056    Obligation obligation() default Obligation.MANDATORY;
057
058    /**
059     * The specification where this UML come from.
060     *
061     * @return the originating specification.
062     */
063    Specification specification();
064
065    /**
066     * The version of the specification where this UML come from,
067     * or 0 for the {@linkplain Specification#defaultVersion() default version}.
068     * The valid version numbers are listed in {@link Specification} enumeration constants.
069     *
070     * <p><b>When older standard versions are used:</b></p>
071     * The vast majority of non-deprecated GeoAPI methods leave {@code UML.version()} to its default value,
072     * meaning that the {@code Specification} default version (usually latest OGC/ISO version) is used.
073     * However, there is a few exceptions when an older version of an OGC or ISO standard is preferred.
074     * Examples:
075     *
076     * <ul>
077     *   <li>{@linkplain Specification#ISO_19115 ISO 19115}:2003 defined {@code PT_Locale} in a way closer
078     *       to the {@link java.util.Locale java.util.Locale} model than the newer ISO 19115:2014.</li>
079     * </ul>
080     *
081     * @return the specification version, or 0 for the default (usually latest) specification.
082     *
083     * @see Specification#defaultVersion()
084     *
085     * @since 3.1
086     */
087    short version() default 0;
088}