001/*
002 *    GeoAPI - Java interfaces for OGC/ISO standards
003 *    Copyright © 2003-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.referencing;
019
020import org.opengis.metadata.extent.Extent;
021import org.opengis.util.InternationalString;
022import org.opengis.geoapi.internal.Legacy;
023import org.opengis.annotation.UML;
024
025import static org.opengis.annotation.Obligation.*;
026import static org.opengis.annotation.Specification.*;
027
028
029/**
030 * Base interface of reference systems by coordinates or by identifiers.
031 * A reference system contains the metadata required to interpret spatial location information unambiguously.
032 * Two methods to describe spatial location are distinguished:
033 *
034 * <ul>
035 *   <li>Spatial referencing by geographic identifier.
036 *       Geographic identifiers are location descriptors such as addresses and grid indexes.</li>
037 *   <li>Spatial referencing by coordinates. This specialized case is handled by the
038 *       {@link org.opengis.referencing.crs.CoordinateReferenceSystem} subtype.</li>
039 * </ul>
040 *
041 * Reference systems contain the following properties
042 * (including those inherited from the {@link IdentifiedObject} parent interface):
043 *
044 * <ul>
045 *   <li>A {@linkplain #getName() name} (e.g. <q>WGS 84 / World Mercator</q>).</li>
046 *   <li>Alternative names or {@linkplain #getAlias() aliases}, sometimes used for abbreviations.</li>
047 *   <li>{@linkplain #getIdentifiers() Identifiers} allocated by authorities (e.g. “EPSG:3395”).</li>
048 *   <li>The {@linkplain ObjectDomain#getDomainOfValidity() domain of validity} in which this reference system is valid
049 *       (e.g. <q>World - between 80°S and 84°N</q>).</li>
050 *   <li>The {@linkplain ObjectDomain#getScope() scope} or intended usage for this reference system
051 *       (e.g. <q>Very small scale mapping</q>).</li>
052 *   <li>{@linkplain #getRemarks() Remarks} about this object, including data source information
053 *       (e.g. <q>Euro-centric view of world excluding polar areas</q>).</li>
054 * </ul>
055 *
056 * @departure harmonization
057 *    The type defined in ISO 19115 has no relationship with ISO 19111.
058 *    GeoAPI redefines this type as a subtype of {@link IdentifiedObject}
059 *    and the common parent for
060 *    {@link org.opengis.referencing.crs.CoordinateReferenceSystem} and
061 *    {@link org.opengis.referencing.gazetteer.ReferenceSystemUsingIdentifiers}.
062 *    This change makes this interface closer to the legacy
063 *    ISO 19115:2003 {@code RS_ReferenceSystem} than to
064 *    ISO 19115:2015 {@code MD_ReferenceSystem}.
065 *
066 * @author  ISO 19115 (for abstract model and documentation)
067 * @author  Martin Desruisseaux (IRD, Geomatys)
068 * @version 3.1
069 * @since   1.0
070 *
071 * @see org.opengis.referencing.crs.CoordinateReferenceSystem
072 */
073@UML(identifier="RS_ReferenceSystem", specification=ISO_19115, version=2003)
074public interface ReferenceSystem extends IdentifiedObject {
075    /**
076     * Key for the <code>{@value}</code> property to be given to the
077     * {@code ObjectFactory.createFoo(Map, ...)} methods.
078     *
079     * @see ObjectFactory
080     * @see ObjectDomain#getDomainOfValidity()
081     *
082     * @deprecated Moved to {@link ObjectDomain} as of ISO 19111:2019.
083     */
084    @Deprecated(since="3.1")
085    String DOMAIN_OF_VALIDITY_KEY = "domainOfValidity";
086
087    /**
088     * Key for the <code>{@value}</code> property to be given to the
089     * {@code ObjectFactory.createFoo(Map, ...)} methods.
090     *
091     * @see ObjectFactory
092     * @see ObjectDomain#getScope()
093     *
094     * @deprecated Moved to {@link ObjectDomain} as of ISO 19111:2019.
095     */
096    @Deprecated(since="3.1")
097    String SCOPE_KEY = "scope";
098
099    /**
100     * Area or region or timeframe in which this (coordinate) reference system is valid.
101     *
102     * @return the reference system valid domain, or {@code null} if not available.
103     *
104     * @deprecated Replaced by {@link #getDomains()} as of ISO 19111:2019.
105     */
106    @Deprecated(since="3.1")
107    @UML(identifier="SC_CRS.domainOfValidity", obligation=OPTIONAL, specification=ISO_19111, version=2007)
108    default Extent getDomainOfValidity() {
109        return Legacy.getDomainOfValidity(getDomains());
110    }
111
112    /**
113     * Description of domain of usage, or limitations of usage, for which this
114     * Reference System object is valid.
115     *
116     * @return the domain of usage, or {@code null} if none.
117     *
118     * @deprecated Replaced by {@link #getDomains()} as of ISO 19111:2019.
119     */
120    @Deprecated(since="3.1")
121    @UML(identifier="SC_CRS.scope", obligation=OPTIONAL, specification=ISO_19111, version=2007)
122    default InternationalString getScope() {
123        return Legacy.getScope(getDomains());
124    }
125}