Departures from the ISO/OGC specifications

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:

 


 

Departures due to constraints of the Java language

Package org.opengis.referencing.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.

Enum Obligation

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.

Interface CartesianCS

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.

Interface Ellipsoid

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.

Interface Position

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.

 


 

Departures due to historical reasons

Interface AxisDirection

Field FUTURE,
Field PAST

This code was defined in an older specification (2003) and removed in more recent edition (2007), but has been kept in GeoAPI.

Interface CoordinateOperation

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.

Interface Datum

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.

Interface ReferenceSystem

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.

Interface CSAuthorityFactory,
Interface CSFactory

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.

Interface GeocentricCRS,
Interface GeographicCRS

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.

Interface ReferenceSystem

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.

 


 

Departures for harmonization between the different specifications

Package org.opengis.metadata

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")

Package org.opengis.parameter

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.

Interface Factory

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.

Interface IdentifiedObject

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.

Interface ObjectFactory

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.

 


 

Departures for closer integration with the Java environment

Interface CodeList

Method valueOf,
Method valueOf,
Method name,
Method ordinal

Provided by analogy with the methods in the JSE 5 Enum class.

Method family

Provided by analogy with Enum.family(), which was defined in a initial draft of JSE 5 before the final release.

Interface Matrix

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.

Interface VerticalExtent

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.

Interface DerivedCRS

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.

Interface MathTransform2D

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.

 


 

Changes of name without change in functionality

Interface GeneralDerivedCRS

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.

Interface GeographicExtent

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.

Interface ParameterValue

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().

Interface ParameterValueGroup

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.

Interface GeneralParameterDescriptor,
Interface ParameterDescriptor,
Interface ParameterDescriptorGroup

GeoAPI uses a name which contains the "Descriptor" word for consistency with other libraries in Java (e.g. ParameterListDescriptor in Java Advanced Imaging).

 


 

Generalizations due to relaxation of ISO/OGC restrictions

Interface AuthorityFactory

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.

Interface CompoundCRS

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.

Interface CoordinateReferenceSystem

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.

Interface GeneralParameterDescriptor

Method getMaximumOccurs

Moved up (in the interface hierarchy) the maximumOccurs method from ParameterDescriptorGroup into this super-interface, for parallelism with the minimumOccurs method.

Interface GenericName

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.

Interface Record

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.

 


 

Addition of elements not in the ISO/OGC specifications

Interface AuthorityFactory

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.

Interface CodeList

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.

Interface CoordinateOperationAuthorityFactory

Method createOperationMethod

This method has been added because OGC 01-009 does not define a factory method for creating such object.

Interface CoordinateOperationFactory

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.

Interface GeneralParameterDescriptor

Method createValue

This method is not part of the ISO specification. It is provided in GeoAPI as a kind of factory method.

Interface GenericName

Method toInternationalString

This method is not part of the ISO specification. It has been added to provide a way to localize the name.

Interface IdentifiedObject

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.

Interface MathTransformFactory

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.

Interface ParameterDescriptor

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.

Interface ParameterDescriptorGroup

Method createValue

This method is not part of the ISO specification. It is provided in GeoAPI as a kind of factory method.

Interface RecordType

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().

Interface CodeList

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.

Interface ConicProjection,
Interface CylindricalProjection,
Interface PlanarProjection,
Interface Projection

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.

Class FactoryException,
Class InvalidParameterCardinalityException,
Class InvalidParameterTypeException,
Class MismatchedDimensionException,
Class NoSuchAuthorityCodeException,
Class NoSuchIdentifierException,
Class NoninvertibleTransformException,
Class OperationNotFoundException,
Class TransformException

This exception is not part of the OGC specification.

Interface InternationalString

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.

Interface MathTransform1D

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.

Interface NameFactory

Added in order to provide constructors for GenericName and related interfaces.

Class ParameterNotFoundException

This exception is not part of OGC specification.

 


 

Extensions for convenience, without introduction of new functionality

Interface Envelope

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.

Interface GenericName

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.

Interface Matrix

Method isIdentity

Added as a convenience for a frequently requested operation.

Interface ParameterDescriptorGroup

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.

Interface ParameterValueGroup

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.

Interface Record

Method set

This method provides no additional functionality compared to the ISO standard methods, but is declared in GeoAPI as a convenient shortcut.

Interface RecordType

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.

Interface ScopedName

Method path

This method is not part of ISO specification. It has been added in GeoAPI as a complement of the ISO tail() method.

Interface DirectPosition,
Interface Envelope

This interface was moved into the org.opengis.geometry package for convenience.