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}