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:
Package org.opengis.referencing.cs
ISO 19111 definesGeodeticCS
,EngineeringCS
andImageCS
unions for type safety, which ensures, for example, that aGeodeticCRS
only be associated to aCartesianCS
, anEllipsoidalCS
or aSphericalCS
. However theunion
construct found in some languages like C/C++ is not available in Java. In the particular case ofImageCS
, the same type-safety objective can be obtained through a slight change in the interface hierarchy (see the departure documented inCartesianCS
). For the other two unions (GeodeticCS
andEngineeringCS
), 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 aFORBIDDEN
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 definesCartesianCS
as a direct sub-type ofCoordinateSystem
. ISO also definesImageCS
as the union ofAffineCS
andCartesianCS
, for use byImageCRS
. Because theunion
construct found in some languages like C/C++ does not exist in Java, GeoAPI definesCartesianCS
as a sub-type ofAffineCS
in order to achieve the same type safety; also, GeoAPI does not defineImageCS
but usesAffineCS
instead. In this hierarchy,CartesianCS
is considered a special case ofAffineCS
where all axes are perpendicular to each other.Interface Ellipsoid
ISO 19111 defines the union namedsecondDefiningParameter
as being eithersemiMinorAxis
orinverseFlattening
. Theunion
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 thesemiMajorAxis
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 theisIvfDefinitive
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 definesPosition
as aunion
ofDirectPosition
andPoint
but unions are not allowed in Java. GeoAPI definesPosition
as the base interface of both types so the two conditional accessor methods,getPoint()
andgetDirectPosition()
, can be replaced by aninstanceof
check. However, thegetDirectPosition()
has been retained with different semantics, conceptually returning aDirectPosition
at the same location. The conditionality has also been changed to mandatory since all three types conceptually have a well defined location.
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 theExtent
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 CSFactoryAdded 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 GeographicCRSThis interface is kept conformant with the specification published in 2003. The 2007 revision of ISO 19111 removed theGeographicCRS
andGeocentricCRS
types, handling both using theGeodeticCRS
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.
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 theMD_CRS
class and its components classes." (ISO 19111:2007, section 3 "Normative References")Package org.opengis.parameter
Moved theGeneralParameterDescriptor
,ParameterDescriptor
,ParameterDescriptorGroup
,GeneralParameterValue
,ParameterValue
,ParameterValueGroup
,InvalidParameterNameException
,InvalidParameterTypeException
andInvalidParameterValueException
interfaces fromorg.opengis.referencing.operation
toorg.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 anIdentifiedObjectBase
interface. The later is omitted in GeoAPI because the split betweenIdentifiedObject
andIdentifiedObjectBase
in the ISO/OGC specification was a workaround for introducingIdentifiedObject
in ISO 19111 without changing theReferenceSystem
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 producingIdentifiedObject
instances.
Interface CodeList
Method valueOf,
Method valueOf,
Method name,
Method ordinalProvided by analogy with the methods in the JavaEnum
class.Method family
Provided by analogy withEnum.family()
, which was defined in a initial draft of Java 5 before the final release.Interface Matrix
Method getNumRow,
Method getNumCol,
Method getElement,
Method setElementNeeded for making the matrix usable. The method signature matches the one ofGMatrix
in the vecmath package, for straightforward implementation.Interface VerticalExtent
Method getVerticalCRS
ISO 19115 specifies a genericCoordinateReferenceSystem
instead than the more restrictiveVerticalCRS
. GeoAPI uses the more specific type for type-safety and consistency withVerticalExtent
usage. However this restriction prevents usage of Height above the ellipsoid when only the constants defined in theVerticalDatumType
code list are used. If such height is wanted, implementors need to extend the above code list with their ownELLIPSOIDAL
constant.Interface DerivedCRS
ISO 19111 defines aDerivedCRSType
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 thejava.awt.geom.AffineTransform
API.
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 thetoBase()
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 withNumber.doubleValue()
and the other "*Value
" methods defined in this interface.Method intValue
Renamed the method from "integerValue
" to "intValue
" for consistency withNumber.intValue()
and theint
Java primitive type.Method doubleValueList
Renamed the method from "valueList
" to "doubleValueList
" both for consistency withdoubleValue()
and also because, likedoubleValue()
, this method returns an array ofdouble
values rather than aMeasure
object.Method intValueList
Renamed the attribute from "integerValueList
" to "intValueList
" for consistency withintValue()
.Interface ParameterValueGroup
Method getDescriptor
The ISO name was "group
". GeoAPI uses "descriptor
" instead in order to override thegetDescriptor()
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 ParameterDescriptorGroupGeoAPI uses a name which contains the "Descriptor
" word for consistency with other libraries in Java (e.g.ParameterListDescriptor
in Java Advanced Imaging).
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 forSingleCRS
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 forCompoundCRS
.Interface GeneralParameterDescriptor
Method getMaximumOccurs
Moved up (in the interface hierarchy) themaximumOccurs
method fromParameterDescriptorGroup
into this super-interface, for parallelism with theminimumOccurs
method.Interface GenericName
Method head
ISO defines this method inScopedName
only. GeoAPI defines it in the base class sinceLocalName
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 thelocate(name)
andRecordType.getMemberTypes()
methods.
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 eachCodeList
has at least two names, the Java programmatic name and the UML identifier, while some subclasses have additional names.Method identifier
Defined because eachCodeList
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 theCRSFactory.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 thecreateParameterizedTransform(&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 createBaseToDerivedThis 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 getUnitThis 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 theTypeList
association in figure 15 of ISO 19103:2005, but navigable in the opposite way. The navigation in the ISO way is represented by theRecordSchema.getDescription().values()
.Interface CodeList
The innerCodeList.Filter
interface is not part of the OGC specification. It has been added becauseCodeList
is one of the few concrete classes in GeoAPI and there is a need to give some user control over the behavior of theCodeList
implementation.Interface ConicProjection,
Interface CylindricalProjection,
Interface PlanarProjection,
Interface ProjectionThis 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 TransformExceptionThis 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 ofMathTransform2D
and because the 1D case provides opportunities for optimization through atransform
method accepting a singledouble
primitive type.Interface NameFactory
Added in order to provide constructors forGenericName
and related interfaces.Class ParameterNotFoundException
This exception is not part of OGC specification.
Interface Envelope
Method getCoordinateReferenceSystem,
Method getDimensionISO does not define this method - the CRS or the dimension can be obtained only through one of the cornerDirectPosition
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 getSpanThis 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 theEnvelope
itself rather than in a containedDirectPosition
corner.Interface GenericName
Method tip,
Method toFullyQualifiedName,
Method toStringThis 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 addGroupThis 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 isInstanceThis 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 ISOtail()
method.Interface DirectPosition,
Interface EnvelopeThis interface was moved into theorg.opengis.geometry
package for convenience.