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. However the union construct found in some languages like C/C++ is not available in Java. For each union, a different approach has been applied and documented in the org.opengis.referencing.cs package. In the particular case of ImageCS, the same type-safety objective can be obtained through a slight change in the interface hierarchy.

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 {@code 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. With this change, GeoAPI can use AffineCS directly without the need to define ImageCS. 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 GeographicCRS

This interface is kept conformant with the specification published in 2003. The 2007 revision of ISO 19111 removed the SC_GeographicCRS and SC_GeocentricCRS types, handling both using the SC_GeodeticCRS parent type. GeoAPI keeps them for two reasons:

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 DataIdentification

Method getLanguages

ISO 19115:2014 defines defaultLocale and otherLocale(s) attributes, who's data type (PT_Locale) combines the language and character encoding information into a single class. However this design does not fit well with the Java model. For example the character encoding information is irrelevant to InternationalString since the Java language fixes the encoding of all String instances to UTF-16. Consequently GeoAPI keeps the language(s) and characterSet(s) attributes as separated entities, as defined in ISO 19115:2003. GeoAPI also keeps default and other locales in a single collection for compatibility with standard Java methods like Locale.lookup(List<Locale.LanguageRange>, Collection<Locale>), which provides elaborated mechanism for choosing the best suited locale for a user.

Method getCharacterSets

GeoAPI has kept the language and characterSet properties as defined in ISO 19115:2003. See getLanguages() for more information.

Interface Datum

Method getAnchorPoint

This method has been kept conformant with the specification published in 2003 for compatibility reasons. The revision published in 2007 renamed this property as anchorDefinition.

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.

Interface ExtendedElementInformation

Method getName

This property has been kept conform to ISO 19115:2003 for simplicity. The 2014 revision defines two mutually exclusive names depending on the data type: "conceptName" for ENUMERATION, CODE_LIST or CODE_LIST_ELEMENT, and "name" for all other data types. GeoAPI keeps the "name" property for all data types and let developers inspect the "dataType" property if needed.

Interface FeatureCatalogueDescription

Method getLanguages

GeoAPI keeps the getLanguages() method name for compliance with the ISO 19115:2003 model See DataIdentification.getLanguages() for information about why the legacy model is more suitable to Java than the new ISO 19115:2014 model. In addition, the language name help to emphases the difference with the ISO 19115:2014 definition of PT_Locale.

Interface Metadata

Method getLanguages

ISO 19115:2014 defines defaultLocale and otherLocale(s) attributes, who's data type (PT_Locale) combines the language and character encoding information into a single class. However this design does not fit well with the Java model. For example the character encoding information is irrelevant to InternationalString since the Java language fixes the encoding of all String instances to UTF-16. Consequently GeoAPI keeps the language(s) and characterSet(s) attributes as separated entities, as defined in ISO 19115:2003. GeoAPI also keeps default and other locales in a single collection for compatibility with standard Java methods like Locale.lookup(List<Locale.LanguageRange>, Collection<Locale>), which provides elaborated mechanism for choosing the best suited locale for a user.

Method getCharacterSets

GeoAPI has kept the language and characterSet properties as defined in ISO 19115:2003. See getLanguages() for more information.

Interface PrimeMeridian

Method getAngularUnit

This attribute is inherited from an older OGC specification. In ISO 19111, greenwichLongitude is a property of type Angle rather than double, and the unit of measure is part of the Angle value.

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 was initially derived from the ISO 19111 specification published in 2003. Later revision (ISO 19111:2007) differs in 3 aspects:
  • ISO 19111:2007 moved this property from this type to the {@code SC_CRS} subtype. GeoAPI keeps this property here for historical reasons.
  • ISO 19111:2007 changed the obligation from optional to mandatory and requires the value to be "not known" if the scope is unknown. GeoAPI lefts the obligation unchanged: optional with {@code null} value for unknown scope.
  • ISO 19111:2007 changed the multiplicity from singleton to a collection. GeoAPI keeps the singleton type for historical reasons.

Interface VerticalDatum

Method getVerticalDatumType

This attribute is kept conformant with the specification published in 2003. The 2007 revision of ISO 19111 removed this attribute, since this information can be encoded in the anchor definition. However GeoAPI keep this attribute for historical reasons, and because it provides some of the anchor definition information in a programmatic way more suitable to coordinate transformation engines.

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

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

Class VerticalDatumType

This code list was defined in the specification published in 2003, but removed from the 2007 revision of ISO 19111. However GeoAPI keep this code list for historical reasons, and because it provides some of the anchor definition information in a programmatic way more suitable to coordinate transformation engines.

 


 

Departures for harmonization between the different specifications

Package org.opengis.parameter

ISO 19111 defines parameters in the Coordinate Operation package, while ISO 19115 defines parameters in the Services package. GeoAPI moves those classes in this parameter independent package and tries to provide a single model for the two standards when possible. 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 OperationMetadata

Method getParameters

Usage of the ISO 19115 SV_Parameter type has been replaced by usage of the ISO 19111 CC_OperationParameter type, completed with new SV_Parameter properties, in order to provide a unified parameter API. Note that CC_OperationParameter is named ParameterDescriptor in GeoAPI to reflect its extended scope.

Interface SampleDimension

Method getTransferFunctionType

ISO 19115-2 defines this property in the MI_Band type (a MD_Band subtype) for historical reasons. GeoAPI moves this property up in the hierarchy to a more natural place when not constrained by historical reasons, which is together with the offset and scale factor.

Method getNominalSpatialResolution

ISO 19115-2 defines this property in the MI_Band type (a MD_Band subtype) for historical reasons. GeoAPI moves this property up in the hierarchy since this property can apply to any sample dimension, not only the measurements in the electromagnetic spectrum.

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 two types, IO_IdentifiedObjectBase and IO_IdentifiedObject, as a workaround for introducing a base type for the name, identifier, alias and remarks properties without changing the RS_ReferenceSystem definition inherited from ISO 19115. Since GeoAPI replaces ISO 19115 CRS definitions by the ISO 19111 ones for providing a unified model, it does not need this workaround. Consequently GeoAPI merges IO_IdentifiedObjectBase and IO_IdentifiedObject into this single interface.

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 BrowseGraphic

Method getFileName

ISO 19115 type is CharacterString. Since the specification clearly state that the string shall be a filename, a more specific Java type like URI seem appropriate.

Interface CodeList

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.

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 StandardOrderProcess

Method getCurrency

This method is not part of ISO specification. It has been added in GeoAPI for integration with the standard JDK library.

Interface ControlledVocabulary

Provided for allowing developers to handles Enum and CodeList in the same way for some common tasks.

Interface DerivedCRS

ISO 19111 defines a SC_DerivedCRSType code list with the following values: geodetic, vertical, engineering and image. But ISO 19162 takes a slightly different approach without such code list. Instead, ISO 19162 writes the derived CRS using the WKT keyword of the corresponding CRS type (“GeodCRS”, “VertCRS”, “TimeCRS” or “EngCRS”). GeoAPI follows a similar path by not providing a DerivedCRSType code list. Instead, we recommend to implement the corresponding interface as documented in the above table. Then, Java expressions like (baseCRS instanceof FooCRS) provides the same capability than the code list with more flexibility. For example it allows to use a derived CRS of type “vertical” with API expecting an instance of VerticalCRS.

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.

Interface VerticalExtent

ISO 19115 provides two ways to define a coordinate reference system, with the restriction that only one of those two ways can be used:
  1. verticalCRS of type SC_VerticalCRS (from ISO 19111),
  2. verticalCRSId of type MD_ReferenceSystem (from ISO 19115).
GeoAPI provides only the first way, because the MD_ReferenceSystem type has been intentionally omitted in order to have a single CRS framework (the ISO 19111 one).

 


 

Changes of name without change in functionality

Interface FeatureCatalogueDescription

Method getFeatureTypeInfo

Renamed from "featureTypes" to "featureTypeInfo" for the following reasons:
  1. Avoid name collision with the ISO 19115:2003 definition of "featureTypes".
  2. Avoid confusion between FeatureTypeInfo and org.opengis.feature.FeatureType. A getFeatureTypes() method name would suggest that the collection contains the later.

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. The OGC 01-009 specification 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.

Class DistributedComputingPlatform

Renamed from "DCPList" to "DistributedComputingPlatform" for the following reasons:
  1. GeoAPI avoids the "List" suffix because instances of this class are not list. The concept of list rather applies to the list of pre-defined static constants in this class.
  2. "DCP" is an abbreviation, and Java usage is to avoid abbreviations unless they are well known.

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

ISO 19111 said "nesting of compound CRSs shall not be permitted; the individual single systems shall be aggregated together". However this approach causes data lost: it is difficult to add a temporal CRS to an existing three-dimensional compound CRS without loosing the name and identifiers of the 3D CRS, unless nesting is permitted. It is programmatically easier to convert nested CRSs to a flat list of single CRSs when needed than to reconstruct the 3D CRS from the single components. Consequently GeoAPI has been keep conformant with the legacy OGC 01-009 specification in this aspect, which were allowing nested compound CRS.

Interface CoordinateReferenceSystem

Method getCoordinateSystem

ISO 19111 defines this method for SC_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 SC_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,
Method createOperationMethod

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

Method createDefiningConversion

Defining conversions is a concept that appears in ISO 19111 textual specification without formalization in UML diagrams. This concept has been formalized in GeoAPI in order to allow the creation of ProjectedCRS instances.

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 important in some situations. We did not defined a {MathTransform, OperationMethod} tuple in order to keep create(…) simpler in the common case where the operation method is not needed, and for historical reasons (conformance to OGC 01-009).

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

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

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.

 


 

Extensions for convenience, without introduction of new functionality

Interface CoordinateOperationFactory

Method getOperationMethod

This method has been added in order to free the user from choosing whether he should get the operation method from CoordinateOperationAuthorityFactory, or from MathTransformFactory, or creating it himself.

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

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 getSpan

This method is not part of ISO specification. GeoAPI adds this method for convenience and efficiency, since some implementations might store the span values directly in the Envelope itself rather than calculating it from the corners.

Interface GenericName

Method tip,
Method toFullyQualifiedName

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 SingleCRS

Method getDatum

The ISO specification declares the datum as absent when the association is indirect. GeoAPI recommends to follow the link to the base CRS for users convenience.

Interface DirectPosition,
Interface Envelope

The ISO specification defines this interface in the coordinate sub-package. GeoAPI moved this interface into the org.opengis.geometry root package for convenience, because it is extensively used.

 


 

renaming

Interface InternationalString

This is called PT_FreeText in ISO 19115 standard, and can be applied to all metadata elements who's data type is CharacterString and domain is “free text”. GeoAPI uses the InternationalString name for historical reasons and for consistency with similar object in JSR-150 (Internationalization Service for J2EE).