Class DefaultOperationMethod
- All Implemented Interfaces:
Serializable
,Formattable
,Deprecable
,LenientComparable
,org.opengis.referencing.IdentifiedObject
,org.opengis.referencing.operation.OperationMethod
- Direct Known Subclasses:
AbstractProvider
,InverseOperationMethod
OperationMethod
is a kind of metadata: it does not perform any coordinate operation (e.g. map projection) by itself, but
tells us what is needed in order to perform such operation.
The most important parts of an OperationMethod
are its name and its
group of parameter descriptors. The parameter descriptors do not contain
any value, but tell us what are the expected parameters, together with their units of measurement.
- “Latitude of natural origin” in degrees. Default value is 0°.
- “Longitude of natural origin” in degrees. Default value is 0°.
- “Scale factor at natural origin” as a dimensionless number. Default value is 1.
- “False easting” in metres. Default value is 0 m.
- “False northing” in metres. Default value is 0 m.
Departure from the ISO 19111 standard
The following properties are mandatory according ISO 19111, but may be missing under some conditions in Apache SIS:- The formula if it has not been provided to the constructor, or if it cannot be inferred from the given math transform.
- The parameters if the
DefaultOperationMethod(MathTransform)
constructor cannot infer them.
Relationship with other classes or interfaces
OperationMethod
describes parameters without providing any value (except sometimes default values).
When values have been assigned to parameters, the result is a SingleOperation
.
Note that there is different kinds of SingleOperation
depending on the nature and accuracy of the
coordinate operation. See getOperationType()
for more information.
The interface performing the actual work of taking coordinates in the
source CRS and calculating the new coordinates in the
target CRS is MathTransform
.
In order to allow Apache SIS to instantiate those MathTransform
s from given parameter values,
DefaultOperationMethod
subclasses should implement the
MathTransformProvider
interface.
Immutability and thread safety
This class is immutable and thread-safe if all properties given to the constructor are also immutable and thread-safe. It is strongly recommended for all subclasses to be thread-safe, especially theMathTransformProvider
implementations to be used with
DefaultMathTransformFactory
.- Since:
- 0.5
- Version:
- 1.3
- See Also:
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate org.opengis.referencing.operation.Formula
Formula(s) or procedure used by this operation method.private org.opengis.parameter.ParameterDescriptorGroup
The set of parameters, ornull
if none.private static final long
Serial number for inter-operability with different versions.private Integer
Deprecated.ISO 19111:2019 removed source/target dimensions attributes.private Integer
Deprecated.ISO 19111:2019 removed source/target dimensions attributes.Fields inherited from class org.apache.sis.referencing.AbstractIdentifiedObject
DEPRECATED_KEY, LOCALE_KEY
Fields inherited from interface org.opengis.referencing.IdentifiedObject
ALIAS_KEY, IDENTIFIERS_KEY, NAME_KEY, REMARKS_KEY
Fields inherited from interface org.opengis.referencing.operation.OperationMethod
FORMULA_KEY
-
Constructor Summary
ConstructorsModifierConstructorDescriptionprivate
Creates a new object in which every attributes are set to a null value.DefaultOperationMethod
(Map<String, ?> properties, Integer sourceDimensions, Integer targetDimensions, org.opengis.parameter.ParameterDescriptorGroup parameters) Deprecated.ISO 19111:2019 removed "source dimensions" and "target dimensions" attributes.DefaultOperationMethod
(Map<String, ?> properties, org.opengis.parameter.ParameterDescriptorGroup parameters) Constructs an operation method from a set of properties and a descriptor group.DefaultOperationMethod
(org.opengis.referencing.operation.MathTransform transform) Convenience constructor that creates an operation method from a math transform.protected
DefaultOperationMethod
(org.opengis.referencing.operation.OperationMethod method) Creates a new operation method with the same values than the specified one.private
DefaultOperationMethod
(org.opengis.referencing.operation.OperationMethod method, Integer sourceDimensions, Integer targetDimensions) Constructs a new operation method with the same values than the specified one except the dimensions. -
Method Summary
Modifier and TypeMethodDescriptionprivate void
afterUnmarshal
(Unmarshaller unmarshaller, Object parent) Invoked by JAXB after unmarshalling.static DefaultOperationMethod
castOrCopy
(org.opengis.referencing.operation.OperationMethod object) Returns a SIS operation method implementation with the same values than the given arbitrary implementation.protected long
Invoked byhashCode()
for computing the hash code when first needed.boolean
equals
(Object object, ComparisonMode mode) Compares this operation method with the specified object for equality.protected String
Formats this operation as a Well Known TextMethod[…]
element.private org.opengis.parameter.GeneralParameterDescriptor[]
Invoked by JAXB for getting the parameters to marshal.org.opengis.referencing.operation.Formula
Formula(s) or procedure used by this operation method.private org.opengis.metadata.citation.Citation
Invoked by JAXB for marshalling a citation to the formula.private String
Invoked by JAXB for marshalling the formula literally.Class<? extends org.opengis.referencing.operation.OperationMethod>
Returns the GeoAPI interface implemented by this class.Class<? extends org.opengis.referencing.operation.SingleOperation>
Returns the base interface of theCoordinateOperation
instances that use this method.org.opengis.parameter.ParameterDescriptorGroup
Returns the set of parameters.getProperties
(org.opengis.referencing.IdentifiedObject info, org.opengis.metadata.citation.Citation authority) Returns the properties to be given to an identified object derived from the specified one.getProperties
(org.opengis.referencing.operation.MathTransform transform) Work around for RFE #4093999 in Sun's bug database ("Relax constraint on placement of this()/super() call in constructors").Deprecated.This attribute has been removed from ISO 19111:2019.Deprecated.This attribute has been removed from ISO 19111:2019.org.opengis.referencing.operation.OperationMethod
redimension
(int sourceDimensions, int targetDimensions) Deprecated.ISO 19111:2019 removed source/target dimensions attributes.static org.opengis.referencing.operation.OperationMethod
redimension
(org.opengis.referencing.operation.OperationMethod method, int sourceDimensions, int targetDimensions) Deprecated.Not needed anymore since ISO 19111:2019 removed the "source dimensions" and "target dimensions" attributes.private static org.opengis.referencing.operation.OperationMethod
redimension
(org.opengis.referencing.operation.OperationMethod method, int sourceDimensions, Integer methodSource, int targetDimensions, Integer methodTarget) Returns an operation method with different dimensions, if we are allowed to change dimensionality.private void
setDescriptors
(org.opengis.parameter.GeneralParameterDescriptor[] descriptors) Invoked by JAXB for setting the unmarshalled parameters.private void
setFormulaCitation
(org.opengis.metadata.citation.Citation citation) Invoked by JAXB for setting the citation to the formula.private void
setFormulaDescription
(String description) Invoked by JAXB for setting the formula description.private void
setSourceDimensions
(Integer value) Invoked by JAXB at unmarshalling time.private void
setTargetDimensions
(Integer value) Invoked by JAXB at unmarshalling time.(package private) final void
updateDescriptors
(org.opengis.parameter.GeneralParameterDescriptor[] descriptors) Invoked byAbstractSingleOperation
for completing the parameter descriptor.Methods inherited from class org.apache.sis.referencing.AbstractIdentifiedObject
castOrCopy, equals, formatTo, getAlias, getDescription, getIdentifiers, getName, getRemarks, hashCode, isDeprecated, isHeuristicMatchForName
Methods inherited from class org.apache.sis.io.wkt.FormattableObject
print, toString, toString, toWKT
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
Methods inherited from interface org.opengis.referencing.IdentifiedObject
getAlias, getIdentifiers, getName, getRemarks, toWKT
-
Field Details
-
serialVersionUID
private static final long serialVersionUIDSerial number for inter-operability with different versions.- See Also:
-
formula
private org.opengis.referencing.operation.Formula formulaFormula(s) or procedure used by this operation method. This may be a reference to a publication. Note that the operation method may not be analytic, in which case this attribute references or contains the procedure, not an analytic formula.Consider this field as final! This field is modified only at unmarshalling time by
setFormulaCitation(Citation)
orsetFormulaDescription(String)
. -
sourceDimensions
Deprecated.ISO 19111:2019 removed source/target dimensions attributes.Number of dimensions in the source CRS of this operation method. May benull
if this method can work with any number of source dimensions (e.g. Affine Transform).Consider this field as final! This field is modified only at unmarshalling time by
setSourceDimensions(Integer)
- See Also:
-
targetDimensions
Deprecated.ISO 19111:2019 removed source/target dimensions attributes.Number of dimensions in the target CRS of this operation method. May benull
if this method can work with any number of target dimensions (e.g. Affine Transform).Consider this field as final! This field is modified only at unmarshalling time by
setTargetDimensions(Integer)
- See Also:
-
parameters
private org.opengis.parameter.ParameterDescriptorGroup parametersThe set of parameters, ornull
if none.Consider this field as final! This field is modified only at unmarshalling time by
setDescriptors(GeneralParameterDescriptor[])
orafterUnmarshal(Unmarshaller, Object)
.
-
-
Constructor Details
-
DefaultOperationMethod
public DefaultOperationMethod(Map<String, ?> properties, org.opengis.parameter.ParameterDescriptorGroup parameters) Constructs an operation method from a set of properties and a descriptor group. The properties map is given unchanged to the super-class constructor. In addition to the properties documented in the parent constructor, the following properties are understood by this constructor:Recognized properties (non exhaustive list) Property name Value type Returned by "formula" Formula
,Citation
orCharSequence
getFormula()
Defined in parent classes (reminder) "name" Identifier
orString
AbstractIdentifiedObject.getName()
"alias" GenericName
orCharSequence
(optionally as array)AbstractIdentifiedObject.getAlias()
"identifiers" Identifier
(optionally as array)AbstractIdentifiedObject.getIdentifiers()
"remarks" InternationalString
orString
AbstractIdentifiedObject.getRemarks()
- Parameters:
properties
- set of properties. Shall contain at least"name"
.parameters
- description of parameters expected by this operation.- Since:
- 1.1
-
DefaultOperationMethod
@Deprecated public DefaultOperationMethod(Map<String, ?> properties, Integer sourceDimensions, Integer targetDimensions, org.opengis.parameter.ParameterDescriptorGroup parameters) Deprecated.ISO 19111:2019 removed "source dimensions" and "target dimensions" attributes.Constructs an operation method for the given number of dimensions. The source and target dimensions may benull
if this method can work with any number of dimensions (e.g. Affine Transform).- Parameters:
properties
- set of properties. Shall contain at least"name"
.sourceDimensions
- number of dimensions in the source CRS of this operation method, ornull
.targetDimensions
- number of dimensions in the target CRS of this operation method, ornull
.parameters
- description of parameters expected by this operation.
-
DefaultOperationMethod
public DefaultOperationMethod(org.opengis.referencing.operation.MathTransform transform) Convenience constructor that creates an operation method from a math transform. The information provided in the newly created object are approximations, and usually acceptable only as a fallback when no other information are available.- Parameters:
transform
- the math transform to describe.
-
DefaultOperationMethod
protected DefaultOperationMethod(org.opengis.referencing.operation.OperationMethod method) Creates a new operation method with the same values than the specified one. This copy constructor provides a way to convert an arbitrary implementation into a SIS one or a user-defined one (as a subclass), usually in order to leverage some implementation-specific API.This constructor performs a shallow copy, i.e. the properties are not cloned.
- Parameters:
method
- the operation method to copy.- See Also:
-
DefaultOperationMethod
private DefaultOperationMethod(org.opengis.referencing.operation.OperationMethod method, Integer sourceDimensions, Integer targetDimensions) Constructs a new operation method with the same values than the specified one except the dimensions. The source and target dimensions may benull
if this method can work with any number of dimensions (e.g. Affine Transform).- Parameters:
method
- the operation method to copy.sourceDimensions
- number of dimensions in the source CRS of this operation method.targetDimensions
- number of dimensions in the target CRS of this operation method.
-
DefaultOperationMethod
private DefaultOperationMethod()Creates a new object in which every attributes are set to a null value. This is not a valid object. This constructor is strictly reserved to JAXB, which will assign values to the fields using reflection.
-
-
Method Details
-
getProperties
@Workaround(library="JDK", version="1.7") private static Map<String,?> getProperties(org.opengis.referencing.operation.MathTransform transform) Work around for RFE #4093999 in Sun's bug database ("Relax constraint on placement of this()/super() call in constructors"). -
getProperties
private static Map<String,Object> getProperties(org.opengis.referencing.IdentifiedObject info, org.opengis.metadata.citation.Citation authority) Returns the properties to be given to an identified object derived from the specified one. This method returns the same properties than the supplied argument (as ofgetProperties(info)
), except for the following:- The name's authority is replaced by the specified one.
- All identifiers are removed, because the new object to be created is probably not endorsed by the original authority.
- Parameters:
info
- the identified object to view as a properties map.authority
- the new authority for the object to be created, ornull
if it is not going to have any declared authority.- Returns:
- the identified object properties in a mutable map.
-
castOrCopy
public static DefaultOperationMethod castOrCopy(org.opengis.referencing.operation.OperationMethod object) Returns a SIS operation method implementation with the same values than the given arbitrary implementation. If the given object isnull
, thennull
is returned. Otherwise if the given object is already a SIS implementation, then the given object is returned unchanged. Otherwise a new SIS implementation is created and initialized to the attribute values of the given object.- Parameters:
object
- the object to get as a SIS implementation, ornull
if none.- Returns:
- a SIS implementation containing the values of the given object (may be the
given object itself), or
null
if the argument was null.
-
redimension
private static org.opengis.referencing.operation.OperationMethod redimension(org.opengis.referencing.operation.OperationMethod method, int sourceDimensions, Integer methodSource, int targetDimensions, Integer methodTarget) Returns an operation method with different dimensions, if we are allowed to change dimensionality. This method accepts to change a dimension only if the value specified by the original method isnull
. Otherwise anIllegalArgumentException
is thrown.- Parameters:
method
- the operation method to redimension.sourceDimensions
- the desired new source dimensions.methodSource
- the current number of source dimensions (may benull
).targetDimensions
- the desired new target dimensions.methodTarget
- the current number of target dimensions (may benull
).- Throws:
IllegalArgumentException
- if the given dimensions are illegal for this operation method.
-
redimension
@Deprecated public static org.opengis.referencing.operation.OperationMethod redimension(org.opengis.referencing.operation.OperationMethod method, int sourceDimensions, int targetDimensions) Deprecated.Not needed anymore since ISO 19111:2019 removed the "source dimensions" and "target dimensions" attributes.Returns an operation method with different dimensions, if we are allowed to change dimensionality. The need to change anOperationMethod
dimensionality may occur in two contexts:- When the original method can work with any number of dimensions. Those methods do not know
in advance the number of dimensions, which is fixed only after the actual
MathTransform
instance has been created. Example: Affine conversion. - When a three-dimensional method can also be used in the two-dimensional case, typically by assuming that the ellipsoidal height is zero everywhere. Example: Molodensky transform.
redimension(…)
implementation performs the following choice:- If the given method is an instance of
DefaultOperationMethod
, then delegate toredimension(int, int)
in order to allow subclasses to defines their own policy. For example, the Molodensky method needs to override. - Otherwise for each dimension (source and target):
- If the corresponding dimension of the given method is
null
, then set that dimension to the given value in a newOperationMethod
. - Otherwise if the given value is not equal to the corresponding dimension
in the given method, throw an
IllegalArgumentException
.
- If the corresponding dimension of the given method is
- Parameters:
method
- the operation method to redimension, ornull
.sourceDimensions
- the desired number of input dimensions.targetDimensions
- the desired number of output dimensions.- Returns:
- the redimensioned operation method, or
null
if the given method was null, ormethod
if no change is needed. - Throws:
IllegalArgumentException
- if the given dimensions are illegal for the given operation method.
- When the original method can work with any number of dimensions. Those methods do not know
in advance the number of dimensions, which is fixed only after the actual
-
redimension
@Deprecated public org.opengis.referencing.operation.OperationMethod redimension(int sourceDimensions, int targetDimensions) Deprecated.ISO 19111:2019 removed source/target dimensions attributes.Returns this operation method with different dimensions, if we are allowed to change dimensionality. Seeredimension(OperationMethod, int, int)
for more information.The default implementation performs the following choice: for each dimension (source and target):
- If the corresponding dimension of the given method is
null
, then set that dimension to the given value in a newOperationMethod
. - Otherwise if the given value is not equal to the corresponding dimension
in the given method, throw an
IllegalArgumentException
.
- Parameters:
sourceDimensions
- the desired number of input dimensions.targetDimensions
- the desired number of output dimensions.- Returns:
- the redimensioned operation method, or
this
if no change is needed. - Throws:
IllegalArgumentException
- if the given dimensions are illegal for this operation method.- Since:
- 0.6
- If the corresponding dimension of the given method is
-
getInterface
Returns the GeoAPI interface implemented by this class. The SIS implementation returnsOperationMethod.class
.Note for implementers: Subclasses usually do not need to override this information since GeoAPI does not defineOperationMethod
sub-interface. Overriding possibility is left mostly for implementers who wish to extend GeoAPI with their own set of interfaces.- Overrides:
getInterface
in classAbstractIdentifiedObject
- Returns:
OperationMethod.class
or a user-defined sub-interface.
-
getOperationType
Returns the base interface of theCoordinateOperation
instances that use this method. The baseCoordinateOperation
interface is usually one of the following subtypes:Transformation
if the coordinate operation has some errors (typically of a few metres) because of the empirical process by which the operation parameters were determined. Those errors do not depend on the floating point precision or the accuracy of the implementation algorithm.Conversion
if the coordinate operation is theoretically of infinite precision, ignoring the limitations of floating point arithmetic (including rounding errors) and the approximations implied by finite series expansions.Projection
if the coordinate operation is a conversion (as defined above) converting geodetic latitudes and longitudes to plane (map) coordinates. This type can optionally be refined with one of theCylindricalProjection
,ConicProjection
orPlanarProjection
subtypes.
getOperationType()
can conservatively return the base type. The default implementation returnsSingleOperation.class
, which is the most conservative return value.- Returns:
- interface implemented by all coordinate operations that use this method.
- See Also:
-
getFormula
public org.opengis.referencing.operation.Formula getFormula()Formula(s) or procedure used by this operation method. This may be a reference to a publication. Note that the operation method may not be analytic, in which case this attribute references or contains the procedure, not an analytic formula.Departure from the ISO 19111 standard: this property is mandatory according ISO 19111, but optional in Apache SIS.- Specified by:
getFormula
in interfaceorg.opengis.referencing.operation.OperationMethod
- Returns:
- the formula used by this method, or
null
if unknown. - See Also:
-
getSourceDimensions
Deprecated.This attribute has been removed from ISO 19111:2019.Number of dimensions in the source CRS of this operation method. May be null if unknown, as in an Affine Transform.- Specified by:
getSourceDimensions
in interfaceorg.opengis.referencing.operation.OperationMethod
- Returns:
- the dimension of source CRS, or
null
if unknown. - See Also:
-
getTargetDimensions
Deprecated.This attribute has been removed from ISO 19111:2019.Number of dimensions in the target CRS of this operation method. May be null if unknown, as in an Affine Transform.- Specified by:
getTargetDimensions
in interfaceorg.opengis.referencing.operation.OperationMethod
- Returns:
- the dimension of target CRS, or
null
if unknown. - See Also:
-
getParameters
public org.opengis.parameter.ParameterDescriptorGroup getParameters()Returns the set of parameters.Departure from the ISO 19111 standard: this property is mandatory according ISO 19111, but may benull
in Apache SIS if theDefaultOperationMethod(MathTransform)
constructor has been unable to infer it.- Specified by:
getParameters
in interfaceorg.opengis.referencing.operation.OperationMethod
- Returns:
- the parameters, or
null
if unknown. - See Also:
-
equals
Compares this operation method with the specified object for equality. If themode
argument value isSTRICT
orBY_CONTRACT
, then all available properties are compared including the formula.- Specified by:
equals
in interfaceLenientComparable
- Overrides:
equals
in classAbstractIdentifiedObject
- Parameters:
object
- the object to compare tothis
.mode
-STRICT
for performing a strict comparison, orIGNORE_METADATA
for comparing only properties relevant to transformations.- Returns:
true
if both objects are equal.- See Also:
-
computeHashCode
protected long computeHashCode()Invoked byhashCode()
for computing the hash code when first needed. SeeAbstractIdentifiedObject.computeHashCode()
for more information.- Overrides:
computeHashCode
in classAbstractIdentifiedObject
- Returns:
- the hash code value. This value may change in any future Apache SIS version.
-
formatTo
Formats this operation as a Well Known TextMethod[…]
element.- Overrides:
formatTo
in classAbstractIdentifiedObject
- Parameters:
formatter
- the formatter where to format the inner content of this WKT element.- Returns:
"Method"
(WKT 2) or"Projection"
(WKT 1).- See Also:
-
setSourceDimensions
Invoked by JAXB at unmarshalling time.- See Also:
-
setTargetDimensions
Invoked by JAXB at unmarshalling time.- See Also:
-
getFormulaCitation
private org.opengis.metadata.citation.Citation getFormulaCitation()Invoked by JAXB for marshalling a citation to the formula. In principle at most one ofgetFormulaCitation()
andgetFormulaDescription()
methods can return a non-null value. However, SIS accepts both coexist (but this is invalid GML). -
getFormulaDescription
Invoked by JAXB for marshalling the formula literally. In principle at most one ofgetFormulaDescription()
andgetFormulaCitation()
methods can return a non-null value. However, SIS accepts both to coexist (but this is invalid GML). -
setFormulaCitation
private void setFormulaCitation(org.opengis.metadata.citation.Citation citation) Invoked by JAXB for setting the citation to the formula. -
setFormulaDescription
Invoked by JAXB for setting the formula description. -
getDescriptors
private org.opengis.parameter.GeneralParameterDescriptor[] getDescriptors()Invoked by JAXB for getting the parameters to marshal. This method usually marshals the sequence of descriptors without theirParameterDescriptorGroup
wrapper, because GML is defined that way. TheParameterDescriptorGroup
wrapper is a GeoAPI addition done for allowing usage of its methods as a convenience (e.g.ParameterDescriptorGroup.descriptor(String)
).However, it could happen that the user really wanted to specify a
ParameterDescriptorGroup
as the sole<gml:parameter>
element. We currently have no easy way to distinguish those cases.Tip: One possible way to distinguish the two cases would be to check that the parameter group does not contain any property that this method does not have: But we would need to make sure thatAbstractSingleOperation.getParameters()
is consistent with the decision taken by this method.Historical note: older, deprecated, names for the parameters were:
includesParameter
generalOperationParameter
- note that this name was used by the EPSG repositoryusesParameter
-
setDescriptors
private void setDescriptors(org.opengis.parameter.GeneralParameterDescriptor[] descriptors) Invoked by JAXB for setting the unmarshalled parameters. This method wraps the given descriptors in aDefaultParameterDescriptorGroup
.The parameter descriptors created by this method are incomplete since we cannot provide a non-null value for
ParameterDescriptor.getValueClass()
. The value class will be provided either by replacing thisOperationMethod
by one of the predefined methods, or by unmarshalling the enclosingAbstractSingleOperation
.Maintenance note: the
"setDescriptors"
method name is also hard-coded inCC_GeneralOperationParameter
for logging purpose. -
updateDescriptors
final void updateDescriptors(org.opengis.parameter.GeneralParameterDescriptor[] descriptors) Invoked byAbstractSingleOperation
for completing the parameter descriptor. -
afterUnmarshal
Invoked by JAXB after unmarshalling. If the<gml:OperationMethod>
element does not contain any<gml:parameter>
, we assume that this is a valid parameterless operation (as opposed to an operation with unknown parameters). We need this assumption because, contrarily to GeoAPI model, the GML schema does not differentiate "no parameters" from "unspecified parameters".
-