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:
Calendar code list is omitted because the handling of calendar systems
is delegated to the java.time framework.Enum and CodeList
in the same way for some common tasks.java.awt.geom.AffineTransform API.OperationParameterValue interface and ParameterValue union.
The valueFileCitation and geographicObject properties were omitted because those more
complex objects can be specified by setting the <T> parameterized type to
Citation and Geometry respectively.calendar attribute is omitted because the handling of calendar systems
is delegated to the java.time framework.TimeCS to TemporalCS.
GeoAPI has kept the ISO 19111:2007 interface name for historical reasons,
but also to emphasize the relationship with the java.time package.verticalCRS of type 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).org.opengis.util.ScopedName.
However this is at odd with other classes returning type information,
which use TypeName.CharacterString. Since the specification clearly states that the
string shall be a filename, a more specific Java type like URI seem appropriate.<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.TM_PeriodDuration, an interface defined by ISO 19108.
That ISO type should be mapped to java.time.Period from the standard Java library,
or to java.time.Duration if a precision smaller than one day is needed.LanguageCode, CountryCode and MD_CharacterSetCode
code lists by equivalent objects from the standard Java library.
See org.opengis.metadata.Metadata#getLocalesAndCharsets() for more information.TM_Duration, an interface defined by ISO 19108.
That ISO type can be mapped to the java.time.Period or java.time.Duration
classes from the standard Java library.TM_TemporalPosition to TM_Instant because the former is replaced by
the Temporal standard Java interface, and Temporal does not have an association
to the IndeterminateValue code list.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().
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.crsID) or an association
to a CRS object (crs), with the requirement that at least one of them shall be supplied.
GeoAPI retains only the latter for client applications ease of use, therefor making this attribute mandatory.
Implementers shall resolve identifiers, for example using org.opengis.referencing.crs.CRSAuthorityFactory.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.GeneralParameter is replaced by a ParameterGroup
because it provides method for fetching parameters by their names.tail() method.GeneralParameterValue is replaced by a ParameterValueGroup
because it provides method for fetching parameters by their names.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.OrdinalCS and TemporalCountCS interfaces are omitted because they are about a type
of coordinate values (integers) rather than the mathematical rules implied by the coordinate system.
The DateTimeTemporalCS interface is omitted for similar reason.
The TemporalMeasureCS interface is omitted because it behaves like most other axes,
and therefor is adequately covered by the TimeCS parent interface.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.DynamicGeodeticReferenceFrame and DynamicVerticalReferenceFrame.
GeoAPI defines a single interface for all cases, with the requirement that implementers shall combine this interface with
GeodeticReferenceFrame or VerticalReferenceFrame respectively using multi-inheritance of interfaces.
This is a design similar to org.opengis.referencing.crs.DerivedCRS.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.Argument type has been replaced by usage of the ISO 19111
OperationParameter type in order to provide a unified parameter API.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().date8601, time8601, dateTime8601 or
anyOther properties. Unions are not explicitly supported by the Java language, but the same result
is achieved with type hierarchy. The mappings of ISO 19103 Date, Time and DateTime
types are described in above Javadoc. The TM_TemporalPosition type used by the anyOther
property is replaced by a vendor-specific Temporal implementation.DQM_Parameter type has been replaced by usage of the ISO 19111
OperationParameter type, completed with some new DQM_Parameter properties,
in order to provide a unified parameter API. Note that OperationParameter is named
org.opengis.parameter.ParameterDescriptor in GeoAPI to reflect its extended scope.SV_Parameter type has been replaced by usage of the ISO 19111
OperationParameter type, completed with new SV_Parameter properties,
in order to provide a unified parameter API. Note that OperationParameter is named
org.opengis.parameter.ParameterDescriptor in GeoAPI to reflect its extended scope.DefiningParameter class.
GeoAPI retrofits in the org.opengis.parameter framework.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.TM_RelativePosition code list which is identical to the
ISO 19143 TemporalOperatorName code list, except that the latter has one more
value for "any interacts". GeoAPI uses the latter for avoiding duplication.MathTransform2D and because the 1D case provides opportunities for optimization
through a transform method accepting a single double primitive type.GenericName and related interfaces.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).not knownif the scope is unknown. This change is still under review.
not knownif the scope is unknown.
"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.locate in ISO 19103:2005 and removed in ISO 19103:2015.
It has been kept in GeoAPI as a convenience shortcut for a frequently used operation.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.toBase in OGC 01-009, conversion in ISO 19111:2007
and derivingConversion in ISO 19111:2019. By analogy with 01-009,
GeoAPI defines a method name which contains the "FromBase" words
for making clear which CRS is the source or which one is the target.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."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 DerivedProjectedCS unions are omitted because unions
are not directly supported in the Java language (they are supported in some other languages such as C/C++).
Unions could be simulated, for example, by defining GeodeticCS as a parent interface of
org.opengis.referencing.cs.CartesianCS, org.opengis.referencing.cs.SphericalCS and
org.opengis.referencing.cs.EllipsoidalCS (the members of the GeodeticCS union).
However, it would blur the semantics of subtyping as an “is type of” hierarchy.
For example, a CartesianCS can be used in non-geodetic contexts.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.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, and the Java instanceof operation should be used for determining the type.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 a 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.#getSingleComponents() method.SingleCRS only.
GeoAPI declares this method in CompoundCRS as well for user convenience,
because CS dimension and axes are commonly requested information
that are still available (indirectly) for compound CRS.SingleCRS only. GeoAPI declares this method in this parent interface
for user convenience, because CRS dimension and axes are commonly requested information and are
always available, directly or indirectly, even for 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.ObjectUsage subtype so that only the
org.opengis.referencing.datum.Datum,
org.opengis.referencing.crs.CoordinateReferenceSystem and
org.opengis.referencing.operation.CoordinateOperation subtypes inherit this property.
GeoAPI relaxes this restriction for two reasons:
org.opengis.referencing.cs.CoordinateSystem
may want to specify "For objects moving at relativistic speed" scope.ObjectUsage type name is at odd with
the semantics of subclassing as an “is type of” hierarchy.
Qualifying a CRS as “a type of object usage” is restrictive.
Instead, CRS contains a description of object usage.
Omitting the ObjectUsage subtype avoids this semantic oddity.getDate() method defined in GeoAPI 3.0.getTime() method defined in GeoAPI 3.0.