ISO 19111 defines GeodeticCS, EngineeringCS and ImageCS
unions for type safety, which ensures, for example, that a GeodeticCRS only be
associated to a CartesianCS, an EllipsoidalCS or a SphericalCS.
However the union construct found in some languages like C/C++ is not available
in Java. In the particular case of ImageCS, the same type-safety objective can
be obtained through a slight change in the interface hierarchy (see the departure documented
in CartesianCS). For the other two unions (GeodeticCS and
EngineeringCS), no workaround is proposed.

Enum FORBIDDEN

ISO specifications sometime override a parent method with a comment saying that the method
is not allowed for a particular class. Since there is no construct in Java for expressing this
constraint in the method signature, GeoAPI defines a FORBIDDEN obligation
(not in original ISO specifications) to be used with the @UML annotation and
which adds a flag in the Java documentation.

ISO 19111 defines CartesianCS as a direct sub-type of CoordinateSystem.
ISO also defines ImageCS as the union of AffineCS and CartesianCS,
for use by ImageCRS. Because the union construct found in some languages like
C/C++ does not exist in Java, GeoAPI defines CartesianCS as a sub-type of AffineCS
in order to achieve the same type safety; also, GeoAPI does not define ImageCS but uses
AffineCS instead. In this hierarchy, CartesianCS is considered
a special case of AffineCS where all axes are perpendicular to each other.

ISO 19111 defines the union named secondDefiningParameter as being either
semiMinorAxis or inverseFlattening. The union
construct (defined in some languages like C/C++) does not exist in Java. GeoAPI changed the
interface to require both ellipsoidal parameters (in addition to the semiMajorAxis
parameter which is mandatory in any case), as was done in OGC 01-009. However, implementors
could readily permit users to only provide one of the two parameters by creating a class which
calculates the second parameter from the first. For precision, GeoAPI imports the
isIvfDefinitive attribute from OGC 01-009 to enable the user to establish which of
the two parameters was used to define the instance.

ISO 19107 defines Position as a union of
DirectPosition and Point but unions are not allowed in Java.
GeoAPI defines Position as the base interface of both types so the two
conditional accessor methods, getPoint() and getDirectPosition(),
can be replaced by an instanceof check. However, the
getDirectPosition() has been retained with different semantics, conceptually
returning a DirectPosition at the same location. The conditionality has also
been changed to mandatory since all three types conceptually have a well defined location.

Field FUTURE,Field PAST

Method getScope

This method has been kept conformant with the specification published in 2003.
The revision published in 2007 replaced the singleton by a collection and changed the
obligation from "optional" to "mandatory", requiring a return value of
"not known" if the scope is unknown. This change is still under review.

Method getScope

This method has been kept conformant with the specification published in 2003. The revision
published in 2007 replaced the singleton by a collection and changed the obligation
from "optional" to "mandatory", requiring a return value of "not known"
if the scope is unknown. This change is still under review.

Method getDomainOfValidity

This method has been kept conformant with the specification published in 2003.
Later revisions changed the multiplicity, so the return type should now be a
collection. The singleton has been preserved in GeoAPI for historical reasons,
and also because the Extent attributes already allow collections.

Method getScope

This method has been kept conformant with the specification published in 2003.
A later revision moved this attribute to subclasses, but GeoAPI keeps this method
here for historical reasons. The obligation is still optional, as opposed to ISO 19111:2007
which makes this attribute mandatory while mandating the text "not known" if
the scope is unknown. In addition, the return value of this method is still a singleton as in
the 2003 version, as opposed to the 2007 version which mandates a collection. The proposed
change is still under review.

Added for consistency with CRS and datum factories. This CS factory was not defined in the
OGC specification because OGC 01-009 was created before ISO 19111 and had no equivalent of
the ISO Coordinate System types.

This interface is kept conformant with the specification published in 2003.
The 2007 revision of ISO 19111 removed the GeographicCRS and
GeocentricCRS types, handling both using the GeodeticCRS parent type.
GeoAPI keeps them since the distinction between those two types is in wide use.

This interface was initially derived from an ISO 19111 specification published in 2003. Later
revisions (in 2005) rely on an interface defined in ISO 19115 instead. The annotations were
updated accordingly, but this interface is still defined in the referencing package instead
of the metadata package for this historical reason.

Moved the GeneralParameterDescriptor, ParameterDescriptor,
ParameterDescriptorGroup, GeneralParameterValue, ParameterValue,
ParameterValueGroup, InvalidParameterNameException,
InvalidParameterTypeException and InvalidParameterValueException
interfaces from org.opengis.referencing.operation to org.opengis.parameter.
With this move, GeoAPI has extended the use of these parameter classes to a more general use rather
than only for referencing operation types.

ISO 19111 defines an IdentifiedObjectBase interface. The later is omitted in
GeoAPI because the split between IdentifiedObject and IdentifiedObjectBase
in the ISO/OGC specification was a workaround for introducing IdentifiedObject
in ISO 19111 without changing the ReferenceSystem definition in ISO 19115 but
GeoAPI does not need this workaround.

Method getNumRow,Method getNumCol,Method getElement,Method setElement

Method getVerticalCRS

ISO 19115 specifies a generic CoordinateReferenceSystem instead than the more
restrictive VerticalCRS. GeoAPI uses the more specific type for type-safety and
consistency with VerticalExtent usage. However this restriction prevents usage
of Height above the ellipsoid when only the constants defined in the
VerticalDatumType code list are used. If such height is wanted, implementors
need to extend the above code list with their own ELLIPSOIDAL constant.

This interface is not part of OGC specification. It has been added in GeoAPI for
close integration with the Java2D library. The API defined in this
interface matches the java.awt.geom.AffineTransform API.

Method getConversionFromBase

"conversion" may be confusing as a method name since it does not indicate
which CRS is the source or which is the target. OGC document 01-009 used the
toBase() method name. By analogy with 01-009, GeoAPI defines a method name
which contains the "FromBase" expression.

Method doubleValue

Renamed the method from "value" to "doubleValue" for consistency
with Number.doubleValue() and the other "*Value" methods defined
in this interface.

Method intValue

Renamed the method from "integerValue" to "intValue" for
consistency with Number.intValue() and the int Java primitive type.

Method doubleValueList

Renamed the method from "valueList" to "doubleValueList" both for
consistency with doubleValue() and also because, like doubleValue(),
this method returns an array of double values rather than a Measure
object.

Method intValueList

Renamed the attribute from "integerValueList" to "intValueList"
for consistency with intValue().

Method getDescriptor

The ISO name was "group". GeoAPI uses "descriptor" instead in
order to override the getDescriptor() generic method provided in the parent
interface. In addition the "descriptor" name makes more apparent that this method returns
an abstract definition of parameters - not their actual values - and is consistent with
usage in other Java libraries like the Java Advanced Imaging library.

Method getComponents

According ISO 19111, "A Compound CRS is a coordinate reference system that combines
two or more coordinate reference systems, none of which can itself be compound".
However this constraint greatly increases the cost of extracting metadata (especially the CRS
identifier) of the three-dimensional part of a spatio-temporal CRS. Note also that in
"Coordinate Transformation Services" (OGC document 01-009), a compound CRS was
specified as a pair of arbitrary CRS ("head" and "tail") where each could be another
compound CRS, allowing the creation of a tree. GeoAPI follows that more general strategy.

Method getCoordinateSystem

ISO 19111 defines this method for SingleCRS only. GeoAPI declares this method
in this parent interface for user convenience, since CS dimension and axes are commonly
requested information and will always be available, directly or indirectly,
even for CompoundCRS.

Method getAvailableMethods

This method is not part of the OGC specification. It has been added as a way to publish
the capabilities of a factory.

Method getLastMethodUsed

This method is not part of the OGC specification. It has been added because this information
appears to be needed in practice. A more object-oriented approach would have been to
return a {MathTransform, OperationMethod} tuple in the
createParameterizedTransform(&hellip) method, but we wanted to keep the
later unchanged for historical reasons (it is inherited from OGC 01-009) and because
only a minority of use cases need the operation method.

Note that the existence of this method does not break thread-safety if the implementor
stores this information in a ThreadLocal variable.

Method getDefaultParameters,Method createBaseToDerived

This method is part of the GeoAPI mechanism for defining the math transform parameters
or deriving other transforms.

The inner CodeList.Filter interface is not part of the OGC specification.
It has been added because CodeList is one of the few concrete classes in
GeoAPI and there is a need to give some user control over the behavior of the
CodeList implementation.

Added this new type in order to distinguish between localizable and non-localizable character
strings. Not all character strings should be localizable; for example Well Know Text
or code names should probably be language neutral. Since the ISO/OGC UML does not say which character
strings are localizable and which ones are not, we have done our own guesses in GeoAPI.

This interface is not part of the OGC specification. It has been added as a complement
of MathTransform2D and because the 1D case provides opportunities for
optimization through a transform method accepting a single double
primitive type.

Method getCoordinateReferenceSystem,Method getDimension

ISO does not define this method - the CRS or the dimension can be obtained only through
one of the corner DirectPosition objects. GeoAPI adds this method for
convenience as a more direct way of obtaining the information and to free the user from
the need to choose an arbitrary corner (very defensive code might feel the need to get
the value from both corners to check they were the same).

Method getMinimum,Method getMaximum,Method getMedian,Method getSpan

This method is not part of ISO specification. GeoAPI adds this method for convenience and
efficiency, since some implementations might store the minimum and maximum ordinate values
directly in the Envelope itself rather than in a contained
DirectPosition corner.

Method tip,Method toFullyQualifiedName,Method toString

This method is not part of ISO specification. It does not provide any additional
information compared to that accessible though the standard methods defined by
ISO, but provides easier to access frequently requested information.