001/*
002 *    GeoAPI - Java interfaces for OGC/ISO standards
003 *    Copyright © 2003-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;
019
020import org.opengis.annotation.UML;
021import org.opengis.annotation.Classifier;
022import org.opengis.annotation.Stereotype;
023import org.opengis.util.InternationalString;
024import org.opengis.metadata.citation.Citation;
025
026import static org.opengis.annotation.Obligation.*;
027import static org.opengis.annotation.Specification.*;
028
029
030/**
031 * Value uniquely identifying an object within a namespace.
032 *
033 * <div class="note"><b>Example:</b>
034 * for the WGS 84 geographic coordinate reference system,
035 * {@code code}        = {@code "4326"},
036 * {@code codeSpace}   = {@code "EPSG"},
037 * {@code description} = {@code "WGS 84"} and
038 * {@code authority}   = OGP geodetic committee.</div>
039 *
040 * @author  Martin Desruisseaux (IRD, Geomatys)
041 * @version 3.1
042 * @since   2.0
043 */
044@Classifier(Stereotype.DATATYPE)
045@UML(identifier="MD_Identifier", specification=ISO_19115)
046public interface Identifier {
047    /**
048     * Key for the <code>{@value}</code> property to be given to the
049     * {@linkplain org.opengis.referencing.ObjectFactory CRS factory} {@code createFoo(Map, ...)} methods.
050     * It can be used as an alternative to {@link org.opengis.referencing.IdentifiedObject#NAME_KEY}
051     * for setting the value to be returned by {@link #getAuthority()}.
052     *
053     * @see org.opengis.referencing.ObjectFactory
054     * @see #getAuthority()
055     */
056    String AUTHORITY_KEY = "authority";
057
058    /**
059     * Key for the <code>{@value}</code> property to be given to the
060     * {@linkplain org.opengis.referencing.ObjectFactory CRS factory} {@code createFoo(Map, ...)} methods.
061     * It can be used as an alternative to {@link org.opengis.referencing.IdentifiedObject#NAME_KEY}
062     * for setting the value to be returned by {@link #getCode()}.
063     *
064     * @see org.opengis.referencing.ObjectFactory
065     * @see #getCode()
066     */
067    String CODE_KEY = "code";
068
069    /**
070     * Key for the <code>{@value}</code> property to be given to the
071     * {@linkplain org.opengis.referencing.ObjectFactory CRS factory} {@code createFoo(Map, ...)} methods.
072     * It can be used as an alternative to {@link org.opengis.referencing.IdentifiedObject#NAME_KEY}
073     * for setting the value to be returned by {@link #getCodeSpace()}.
074     *
075     * @see org.opengis.referencing.ObjectFactory
076     * @see #getCodeSpace()
077     */
078    String CODESPACE_KEY = "codespace";
079
080    /**
081     * Key for the <code>{@value}</code> property to be given to the
082     * {@linkplain org.opengis.referencing.ObjectFactory CRS factory} {@code createFoo(Map, ...)} methods.
083     * It can be used as an alternative to {@link org.opengis.referencing.IdentifiedObject#NAME_KEY}
084     * for setting the value to be returned by {@link #getVersion()}.
085     *
086     * @see org.opengis.referencing.ObjectFactory
087     * @see #getVersion()
088     */
089    String VERSION_KEY = "version";
090
091    /**
092     * Key for the <code>{@value}</code> property to be given to the
093     * {@linkplain org.opengis.referencing.ObjectFactory CRS factory} {@code createFoo(Map, ...)} methods.
094     * It can be used as an alternative to {@link org.opengis.referencing.IdentifiedObject#NAME_KEY}
095     * for setting the value to be returned by {@link #getDescription()}.
096     *
097     * @see org.opengis.referencing.ObjectFactory
098     * @see #getDescription()
099     *
100     * @since 3.1
101     */
102    String DESCRIPTION_KEY = "description";
103
104    /**
105     * Person or party responsible for maintenance of the namespace.
106     *
107     * @return the person or party responsible for maintenance of the namespace, or {@code null} if none.
108     */
109    @UML(identifier="authority", obligation=OPTIONAL, specification=ISO_19115)
110    default Citation getAuthority() {
111        return null;
112    }
113
114    /**
115     * Alphanumeric value identifying an instance in the namespace.
116     * Should avoid characters that are not legal in URLs.
117     *
118     * <div class="note"><b>Example:</b> {@code "4326"}.</div>
119     *
120     * @return value identifying an instance in the namespace.
121     */
122    @UML(identifier="code", obligation=MANDATORY, specification=ISO_19115)
123    String getCode();
124
125    /**
126     * Identifier or namespace in which the code is valid.
127     *
128     * <div class="note"><b>Example:</b> {@code "EPSG"}.</div>
129     *
130     * @return the identifier or namespace in which the code is valid, or {@code null} if none.
131     *
132     * @since 3.1
133     */
134    @UML(identifier="codeSpace", obligation=OPTIONAL, specification=ISO_19115)
135    default String getCodeSpace() {
136        return null;
137    }
138
139    /**
140     * Version identifier for the namespace, as specified by the code authority.
141     * When appropriate, the edition is identified by the effective date, coded
142     * using ISO 8601 date format.
143     *
144     * <div class="note"><b>Example:</b>
145     * the version of the underlying EPSG database.</div>
146     *
147     * @return the version identifier for the namespace, or {@code null} if none.
148     *
149     * @since 3.1
150     */
151    @UML(identifier="version", obligation=OPTIONAL, specification=ISO_19115)
152    default String getVersion() {
153        return null;
154    }
155
156    /**
157     * Natural language description of the meaning of the code value.
158     *
159     * <div class="note"><b>Example:</b> for {@code codeSpace = "EPSG"} and {@code code = "4326"},
160     * the description can be "WGS 84".</div>
161     *
162     * @return the natural language description, or {@code null} if none.
163     *
164     * @since 3.1
165     */
166    @UML(identifier="description", obligation=OPTIONAL, specification=ISO_19115)
167    default InternationalString getDescription() {
168        return null;
169    }
170}