The following sections list all the departures from the ISO standards taken by the GeoAPI interface library. The rationale for these departures fall into the following categories:
Departure for closer integration with the Java environment
ISO 19111 defines a DerivedCRSType code list. The later is omitted in GeoAPI since
Java expressions like (baseCRS instanceof FooCRS) provides the same capability
with more flexibility.
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 valueOf,
Method valueOf,
Method name,
Method ordinal
Provided by analogy with the methods in the Java Enum class.
Method family
Provided by analogy with Enum.family(), which was defined in a initial
draft of Java 5 before the final release.
Method getNumRow,
Method getNumCol,
Method getElement,
Method setElement
Needed for making the matrix usable. The method signature matches the one of
GMatrix in the vecmath package, for straightforward
implementation.
Method getVerticalCRS
ISO 19115 specifies a generic CoordinateReferenceSystem instead of 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.
Extension for convenience without introduction of new functionality
This interface was moved into the org.opengis.geometry package for convenience.
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.
Method isIdentity
Added as a convenience for a frequently requested operation.
Method descriptor
This method is not part of the ISO specification. It has been added in an attempt to make
this interface easier to use.
Method parameter,
Method groups,
Method addGroup
This method is not part of the ISO specification. It has been added in an attempt to make
this interface easier to use.
Method set
This method provides no additional functionality compared to the ISO standard methods,
but is declared in GeoAPI as a convenient shortcut.
Method getMembers,
Method isInstance
This method provides no additional information compared to the ISO standard methods,
but is declared in GeoAPI as a convenient shortcut.
Method path
This method is not part of ISO specification. It has been added in GeoAPI as a
complement of the ISO tail() method.
Departure for harmonization between different specifications
Omitted the reference system package, since it duplicates ISO 19111 / OGC Topic 2.
This follows the lead of ISO 19111, which states:
"Normative reference to ISO 19115 is restricted as follows: in this international
standard, normative reference to ISO 19111 excludes the MD_CRS class and its components
classes." (ISO 19111:2007, section 3 "Normative References")
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.
This interface is not part of the OGC specification. It is added for uniformity,
in order to provide a common base class for all factories.
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.
This interface is not part of any OGC specification. It is added for uniformity,
in order to provide a common base class for all referencing factories producing
IdentifiedObject instances.
Addition of element not in the ISO/OGC specification
This interface is not part of the ISO specification. It has been added in GeoAPI at user
request, in order to provide a way to know the kind of map projection.
This exception is not part of the OGC specification.
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.
Added in order to provide constructors for GenericName and related interfaces.
This exception is not part of OGC specification.
Method getAuthorityCodes
This method is not part of the OGC specification but has been added as a way to publish
the capabilities of a factory.
Method names
Defined because each CodeList has at least two names, the Java programmatic
name and the UML identifier, while some subclasses have additional names.
Method identifier
Defined because each CodeList has a UML identifier in addition of the Java
programmatic name.
Method createOperationMethod
This method has been added because OGC 01-009 does not define a factory
method for creating such object.
Method createOperation
This method has been added at user request, in order to specify the desired
transformation path when many are available.
Method createConcatenatedOperation
This method has been added because OGC 01-009 does not define a factory
method for creating such object.
Method createValue
This method is not part of the ISO specification. It is provided in GeoAPI as a kind of
factory method.
Method toInternationalString
This method is not part of the ISO specification. It has been added to provide
a way to localize the name.
Method toWKT
This method is not part of the OGC specification. It has been added in order to provide
the converse of the CRSFactory.createFromWKT(String) method, which is
defined in OGC 01-009.
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() 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.
Method createValue
This method is not part of the ISO specification. It is provided in GeoAPI as a kind of
factory method.
Method getValidValues,
Method getUnit
This method is not part of ISO specification. It is provided as a complement of information.
Method createValue
This method is not part of the ISO specification. It is provided in GeoAPI as a kind of
factory method.
Method getContainer
This is the TypeList association in figure 15 of ISO 19103:2005,
but navigable in the opposite way. The navigation in the ISO way is represented
by the RecordSchema.getDescription().values().
Departure for historical reason
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.
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.
Change of name without change in functionality
GeoAPI uses a name which contains the "Descriptor" word for consistency with other
libraries in Java (e.g. ParameterListDescriptor in Java Advanced Imaging).
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 getInclusion
The ISO identifier is "extentTypeCode" and defines the value 1 for inclusion,
and 0 for exclusion. GeoAPI uses a name which better expresses the meaning of the return
value.
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.
Departure due to constraint of the Java language
Package cs
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.
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.
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.
Generalization by relaxation of ISO/OGC restriction
Method createObject
This method is not part of the OGC specification. It has been added to leverage the
capability of factories that can automatically determine the type of the requested
object at runtime.
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 getMaximumOccurs
Moved up (in the interface hierarchy) the maximumOccurs method from
ParameterDescriptorGroup into this super-interface, for parallelism
with the minimumOccurs method.
Method head
ISO defines this method in ScopedName only. GeoAPI defines it in the base
class since LocalName can return a sensible value for it. This reduces the
need for casts.
Method getAttributes
Figure 15 in ISO 19103:2005 specifies a cardinality of 1. However, this seems to
contradict the semantics of the locate(name) and
RecordType.getMemberTypes() methods.