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:
coordinate sub-package.
GeoAPI moved this interface into the org.opengis.geometry root package for
convenience, because it is extensively used.Filter contains a "filter" property of type Operator.
Then various Operator subclasses are provided such as SpatialOperator, etc.
GeoAPI removes this indirection level and extends Filter directly instead.CoordinateOperationAuthorityFactory, or from
MathTransformFactory, or creating it himself.MeasureReference
that clients can use for finding the full measure description in a measure register or catalogue.
Because Java interfaces can execute code (as opposed to static data encoded in XML or JSON documents),
implementers are free to do themselves the work of fetching this information from an external source
when getMeasure() is invoked. This method is added in the Element interface for making
that feature possible. This is an optional feature; implementers can ignore this method and implement
only the #getMeasureReference() method.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).Envelope itself rather than in a contained DirectPosition corner.Envelope itself rather
than calculating it from the corners.tail() method.SpatialOperatorDescription type by Map.Entry.
It reduces the number of interfaces and makes easy to query the operands for a specific operator.TemporalOperatorDescription type by Map.Entry.
It reduces the number of interfaces and makes easy to query the operands for a specific operator.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.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.IdentifiedObject instances.IdentifiedObject
and the common parent for
org.opengis.referencing.crs.CoordinateReferenceSystem and
org.opengis.referencing.gazetteer.ReferenceSystemUsingIdentifiers.
This change makes this interface closer to the legacy
ISO 19115:2003 RS_ReferenceSystem than to
ISO 19115:2015 MD_ReferenceSystem.valueReference)
completed by 2 parameters (geometry and distance).
GeoAPI puts the expression and the 2 parameters in a single list for enabling access
to all parameters in a more generic wayFilter#getExpressions().DQM_Parameter type has been replaced by usage of the ISO 19111
CC_OperationParameter type, completed with some new DQM_Parameter properties,
in order to provide a unified parameter API. Note that CC_OperationParameter is named
ParameterDescriptor in GeoAPI to reflect its extended scope.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.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.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.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.MathTransform2D and because the 1D case provides opportunities for optimization
through a transform method accepting a single double primitive type.GenericName and related interfaces.CodeList has at least two names, the Java programmatic
name and the UML identifier, while some subclasses have additional names.CodeList has a UML identifier in addition of the Java
programmatic name.ProjectedCRS instances.CRSFactory.createFromWKT(String) method, which is defined in OGC 01-009.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).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.anchorDefinition."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.greenwichLongitude is a property of type Angle
rather than double, and the unit of measure is part of the Angle value."valueRecordType" to "valueType" for compatibility with ISO 19115:2003
and because the return object type does not need to be repeated in Java method name.Extent attributes already allow collections.SC_CRS subtype.
GeoAPI keeps this property here for historical reasons.null value for unknown scope.DCPList" to "DistributedComputingPlatform" for the following reasons:
List" suffix because instances of this class are not list.
The concept of list rather applies to the list of predefined static constants in this class.DCP" is an abbreviation, and Java usage is to avoid abbreviations unless they are well known.Descriptor" word for consistency with other
libraries in Java (e.g. ParameterListDescriptor in Java Advanced Imaging).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 Internationalization Service for J2EE.measure.
This is renamed measureReference in GeoAPI for reflecting the return type
and for making room for a measure property for the full Measure description."referenceDoc" to "referenceDocument"
for avoiding abbreviation (a Java usage).featureTypes" to "featureTypeInfo" for the following reasons:
featureTypes".FeatureTypeInfo and org.opengis.feature.FeatureType.
A getFeatureTypes() method name would suggest that the collection contains the latter.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."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.value" to "doubleValue" for consistency
with Number.doubleValue() and the other "*Value" methods defined
in this interface.integerValue" to "intValue" for
consistency with Number.intValue() and the int Java primitive type.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.integerValueList" to "intValueList"
for consistency with intValue().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.partyIdentifier" to "identifier"
for providing a unified method signature for identifiers.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.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.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, implementers 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.SC_GeographicCRS and SC_GeocentricCRS types,
handling both using the SC_GeodeticCRS parent type. GeoAPI keeps them for two reasons:
EllipsoidalCS.
ISO 19111 uses a union for expressing this restriction at the SC_GeodeticCRS level, but
the Java language does not provide such construct. A distinct geographic type is one way to achieve the
same goal.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.SpatialDescription, which is a union between
Geometry, Envelope and ValueReference.
Union has no direct equivalence in Java and is replaced by documentation in this method.FORBIDDEN obligation
(not in original ISO specifications) to be used with the @UML annotation and
which adds a flag in the Java documentation.operand1 and operand2,
of type ValueReference and TemporalOperand respectively.
The later is an union of TM_Object and ValueReference,
which has no direct equivalence in Java.
The union purpose is replaced by documentation in this method.
The two values are put in a list for retrofitting in Filter#getExpressions().ValueReference.
GeoAPI relaxes this restriction by allowing arbitrary expressions.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.operatorType property in UnaryLogicOperator,
BinaryLogicOperator, BinaryComparisonOperator, BinarySpatialOperator
and DistanceOperator. This method has been added for providing a single access point
for that information without the need to check for each sub-type.expression (with a cardinality of 1, 2 or unlimited), operand1, operand2, or
valueReference. This method provides a way to access those expressions without the need to
make special cases for each sub-type.maximumOccurs method from
ParameterDescriptorGroup into this super-interface, for parallelism
with the minimumOccurs method.ScopedName only. GeoAPI defines it in the base
class since LocalName can return a sensible value for it. This reduces the
need for casts.Enum and CodeList
in the same way for some common tasks.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.java.awt.geom.AffineTransform API.verticalCRS of type SC_VerticalCRS (from ISO 19111),verticalCRSId of type MD_ReferenceSystem (from ISO 19115).MD_ReferenceSystem type
has been intentionally omitted in order to have a single CRS framework (the ISO 19111 one).CharacterString. Since the specification clearly states that the
string shall be a filename, a more specific Java type like URI seem appropriate.Enum class.Enum.family(), which was defined in a initial
draft of Java 5 before the final release.<gcx:FileName>, which we map to a URI in Java.<gcx:MimeFileType>.LanguageCode, CountryCode and MD_CharacterSetCode
code lists by equivalent objects from the standard Java library.
See org.opengis.metadata.Metadata#getLocalesAndCharsets() for more information.LanguageCode, CountryCode and MD_CharacterSetCode
code lists by equivalent objects from the standard Java library.
See org.opengis.metadata.Metadata#getLocalesAndCharsets() for more information.GMatrix in the vecmath package, for straightforward
implementation.LanguageCode, CountryCode and MD_CharacterSetCode
code lists by equivalent objects from the standard Java library. The PT_Locale class, which is a
container for above code-lists, is replaced by Map entries in order to avoid to introduce a new class
and because the character set information is not as relevant in Java than in XML documents.
For example, the character encoding information is irrelevant to InternationalString
because the Java language fixes the encoding of all String instances to UTF-16.
In addition ISO 19115:2014 defines defaultLocale and otherLocale(s) as separated attributes,
but GeoAPI groups them in a single collection for compatibility with standard Java methods like
Locale.lookup(…, Collection<Locale>)Locale#lookup(List, Collection)Locale objects with
getLocalesAndCharsets().keySet()Map#keySet().