001/*
002 *    GeoAPI - Java interfaces for OGC/ISO standards
003 *    Copyright © 2004-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.referencing.crs;
019
020import org.opengis.referencing.datum.Datum;
021import org.opengis.referencing.datum.DatumEnsemble;
022import org.opengis.referencing.cs.CoordinateSystem;
023import org.opengis.annotation.UML;
024import org.opengis.annotation.Classifier;
025import org.opengis.annotation.Stereotype;
026
027import static org.opengis.annotation.Obligation.*;
028import static org.opengis.annotation.Specification.*;
029
030
031/**
032 * Base type of <abbr>CRS</abbr> related to an object by a datum or datum ensemble.
033 * The object will generally, but not necessarily, be the Earth. It can be identified either
034 * by a {@linkplain #getDatum() datum} or a {@linkplain #getDatumEnsemble() datum ensemble}.
035 * At least one of those two properties shall be present.
036 *
037 * <p>The valid coordinate system type and the datum type are constrained by the <abbr>CRS</abbr> type.
038 * For example, {@link GeographicCRS} can be associated only to {@code GeodeticReferenceFrame}
039 * (a specialization of {@code Datum}) and {@code EllipsoidalCS}.
040 * The constraints are documented in the Javadoc of sub-interfaces.</p>
041 *
042 * @author  OGC Topic 2 (for abstract model and documentation)
043 * @author  Martin Desruisseaux (IRD, Geomatys)
044 * @version 3.1
045 * @since   2.0
046 *
047 * @see CoordinateSystem
048 * @see Datum
049 */
050@Classifier(Stereotype.ABSTRACT)
051@UML(identifier="SingleCRS", specification=ISO_19111)
052public interface SingleCRS extends CoordinateReferenceSystem {
053    /**
054     * Returns the coordinate system associated to this <abbr>CRS</abbr>.
055     * The coordinate system (<abbr>CS</abbr>) is composed of a set of coordinate axes with specified units of measure.
056     * The <abbr>CS</abbr> subtype implies the mathematical rules that define how coordinate values are calculated
057     * from distances, angles and other geometric elements and vice versa.
058     *
059     * @return the coordinate system associated to this <abbr>CRS</abbr>.
060     */
061    @Override
062    @UML(identifier="coordinateSystem", obligation=MANDATORY, specification=ISO_19111)
063    CoordinateSystem getCoordinateSystem();
064
065    /**
066     * Returns the datum associated directly or indirectly to this <abbr>CRS</abbr>.
067     * In the case of {@link DerivedCRS}, this method returns the
068     * datum of the {@linkplain DerivedCRS#getBaseCRS() base CRS}.
069     * This property may be null if this <abbr>CRS</abbr> is related to an object
070     * identified only by a {@linkplain #getDatumEnsemble() datum ensemble}.
071     *
072     * <p>A datum specifies the relationship of a coordinate system to the object, thus ensuring that the abstract
073     * mathematical concept “coordinate system” can be applied to the practical problem of describing positions of
074     * features on or near the planet's surface by means of coordinates.
075     * The object will generally, but not necessarily, be the Earth.
076     * For certain <abbr>CRS</abbr>s, the object may be a moving platform.</p>
077     *
078     * @return the datum, or {@code null} if this <abbr>CRS</abbr> is related to an object
079     *         identified only by a {@linkplain #getDatumEnsemble() datum ensemble}.
080     *
081     * @departure easeOfUse
082     *   The ISO specification declares the datum as absent when the association is indirect.
083     *   GeoAPI recommends to follow the link to the base CRS for users convenience.
084     *
085     * @condition Mandatory if the {@linkplain #getDatumEnsemble() datum ensemble} is not documented.
086     */
087    @UML(identifier="datum", obligation=CONDITIONAL, specification=ISO_19111)
088    Datum getDatum();
089
090    /**
091     * Returns the datum ensemble associated directly or indirectly to this <abbr>CRS</abbr>.
092     * In the case of {@link DerivedCRS}, this method returns the datum ensemble
093     * of the {@linkplain DerivedCRS#getBaseCRS() base CRS}.
094     * This property may be null if this <abbr>CRS</abbr> is related to an object
095     * identified only by a single {@linkplain #getDatum() datum}.
096     *
097     * <p>The default implementation returns {@code null}.</p>
098     *
099     * @return the datum ensemble, or {@code null} if this <abbr>CRS</abbr> is related
100     *         to an object identified only by a single {@linkplain #getDatum() datum}.
101     *
102     * @condition Mandatory if the {@linkplain #getDatum() datum} is not documented.
103     * @since 3.1
104     */
105    @UML(identifier="datumEnsemble", obligation=CONDITIONAL, specification=ISO_19111)
106    default DatumEnsemble<?> getDatumEnsemble() {
107        /*
108         * API design note: we cannot use `Optional.empty()` because the use of `Optional<DatumEnsemble<?>>`
109         * as the return type prevents sub-interfaces to specialize the `<?>` part with a more specific type.
110         * Anyway, this attribute is not exactly optional but conditional.
111         */
112        return null;
113    }
114}