Module org.apache.sis.referencing
Package org.apache.sis.referencing.operation

# Class DefaultOperationMethod

Object
FormattableObject
AbstractIdentifiedObject
DefaultOperationMethod

All Implemented Interfaces:
  `Serializable`, `Formattable`, `Deprecable`, `LenientComparable`, `IdentifiedObject`, `OperationMethod`

public class DefaultOperationMethod extends AbstractIdentifiedObject implements OperationMethod
Describes the algorithm and parameters used to perform a coordinate operation. An `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.

In Apache SIS implementation, the name is the only mandatory property. However, it is recommended to provide also identifiers (e.g. “EPSG:9804” in the following example) because names can sometimes be ambiguous or be spelled in different ways.

## Example

An operation method named “Mercator (variant A)” (EPSG:9804) expects the following parameters:

- “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 the `MathTransformProvider` implementations to be used with `DefaultMathTransformFactory`.

Since:
  0.5
See Also:
  - `DefaultConversion`
  - `DefaultTransformation`
  - `MathTransformProvider`
  - Serialized Form

- ## Field Summary

  ### Fields inherited from class AbstractIdentifiedObject

  `DEPRECATED_KEY, LOCALE_KEY`

  ### Fields inherited from interface IdentifiedObject

  `ALIAS_KEY, IDENTIFIERS_KEY, NAME_KEY, REMARKS_KEY`

  ### Fields inherited from interface OperationMethod

  `FORMULA_KEY`

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  ``
  `DefaultOperationMethod(Map<String,?> properties, ParameterDescriptorGroup parameters)`
  Constructs an operation method from a set of properties and a descriptor group.
  ``
  `DefaultOperationMethod(MathTransform transform)`
  Convenience constructor that creates an operation method from a math transform.
  `protected`
  `DefaultOperationMethod(OperationMethod method)`
  Creates a new operation method with the same values than the specified one.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static DefaultOperationMethod`
  `castOrCopy(OperationMethod object)`
  Returns a SIS operation method implementation with the same values than the given arbitrary implementation.
  `protected long`
  `computeHashCode()`
  Invoked by `hashCode()` 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`
  `formatTo(Formatter formatter)`
  Formats this operation as a Well Known Text `Method[…]` element.
  `Formula`
  `getFormula()`
  Formula(s) or procedure used by this operation method.
  `Class<? extends OperationMethod>`
  `getInterface()`
  Returns the GeoAPI interface implemented by this class.
  `Class<? extends SingleOperation>`
  `getOperationType()`
  Returns the base interface of the `CoordinateOperation` instances that use this method.
  `ParameterDescriptorGroup`
  `getParameters()`
  Returns the set of parameters.
  `Integer`
  `getSourceDimensions()`
  Deprecated.
  This attribute has been removed from ISO 19111:2019.
  `Integer`
  `getTargetDimensions()`
  Deprecated.
  This attribute has been removed from ISO 19111:2019.

  ### Methods inherited from class AbstractIdentifiedObject

  `castOrCopy, equals, formatTo, getAlias, getDescription, getDomains, getIdentifiers, getName, getRemarks, hashCode, isDeprecated, isHeuristicMatchForName`

  ### Methods inherited from class FormattableObject

  `print, toString, toString, toWKT`

  ### Methods inherited from class Object

  `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

  ### Methods inherited from interface IdentifiedObject

  `getAlias, getIdentifiers, getName, getRemarks, toWKT`

- ## Constructor Details

  - ### DefaultOperationMethod

    public DefaultOperationMethod(Map<String,?> properties, 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` or `CharSequence` | `getFormula()`
    Defined in parent classes (reminder)
    "name" | `Identifier` or `String` | `AbstractIdentifiedObject.getName()`
    "alias" | `GenericName` or `CharSequence` (optionally as array) | `AbstractIdentifiedObject.getAlias()`
    "identifiers" | `Identifier` (optionally as array) | `AbstractIdentifiedObject.getIdentifiers()`
    "remarks" | `InternationalString` or `String` | `AbstractIdentifiedObject.getRemarks()`

    Parameters:
      `properties` - set of properties. Shall contain at least `"name"`.
      `parameters` - description of parameters expected by this operation.
    Since:
      1.1

  - ### DefaultOperationMethod

    public DefaultOperationMethod(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(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:
      - `castOrCopy(OperationMethod)`

- ## Method Details

  - ### castOrCopy

    public static DefaultOperationMethod castOrCopy(OperationMethod object)
    Returns a SIS operation method implementation with the same values than the given arbitrary implementation. If the given object is `null`, then `null` 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, or `null` 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.

  - ### getInterface

    public Class<? extends OperationMethod> getInterface()
    Returns the GeoAPI interface implemented by this class. The SIS implementation returns `OperationMethod​.class`.

    #### Note for implementers

    Subclasses usually do not need to override this information since GeoAPI does not define `OperationMethod` sub-interface. Overriding possibility is left mostly for implementers who wish to extend GeoAPI with their own set of interfaces.
    Overrides:
      `getInterface` in class `AbstractIdentifiedObject`
    Returns:
      `OperationMethod​.class` or a user-defined sub-interface.

  - ### getOperationType

    public Class<? extends SingleOperation> getOperationType()
    Returns the base interface of the `CoordinateOperation` instances that use this method. The base `CoordinateOperation` 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 the `CylindricalProjection`, `ConicProjection` or `PlanarProjection` subtypes.
    In case of doubt, `getOperationType()` can conservatively return the base type. The default implementation returns `SingleOperation​.class`, which is the most conservative return value.
    Returns:
      interface implemented by all coordinate operations that use this method.
    See Also:
      - `DefaultMathTransformFactory​.getAvailableMethods(Class)`

  - ### getFormula

    public 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 interface `OperationMethod`
    Returns:
      the formula used by this method, or `null` if unknown.
    See Also:
      - `DefaultFormula`
      - `MathTransformProvider`

  - ### getSourceDimensions

    @Deprecated(since="1.1") public Integer 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 interface `OperationMethod`
    Returns:
      the dimension of source CRS, or `null` if unknown.
    See Also:
      - `AbstractMathTransform​.getSourceDimensions()`

  - ### getTargetDimensions

    @Deprecated(since="1.1") public Integer 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 interface `OperationMethod`
    Returns:
      the dimension of target CRS, or `null` if unknown.
    See Also:
      - `AbstractMathTransform​.getTargetDimensions()`

  - ### getParameters

    public ParameterDescriptorGroup getParameters()
    Returns the set of parameters.

    #### Departure from the ISO 19111 standard

    This property is mandatory according ISO 19111, but may be `null` in Apache SIS if the `DefaultOperationMethod(MathTransform)` constructor has been unable to infer it.
    Specified by:
      `getParameters` in interface `OperationMethod`
    Returns:
      the parameters, or `null` if unknown.
    See Also:
      - `Parameterized​.getParameterDescriptors()`
      - `SingleOperation​.getParameterValues()`

  - ### equals

    public boolean equals(Object object, ComparisonMode mode)
    Compares this operation method with the specified object for equality. If the `mode` argument value is `STRICT` or `BY_CONTRACT`, then all available properties are compared including the formula.
    Specified by:
      `equals` in interface `LenientComparable`
    Overrides:
      `equals` in class `AbstractIdentifiedObject`
    Parameters:
      `object` - the object to compare to `this`.
      `mode` - `STRICT` for performing a strict comparison, or `IGNORE_METADATA` for comparing only properties relevant to transformations.
    Returns:
      `true` if both objects are equal.
    See Also:
      - `AbstractIdentifiedObject​.computeHashCode()`
      - `Utilities​.deepEquals(Object, Object, ComparisonMode)`

  - ### computeHashCode

    protected long computeHashCode()
    Invoked by `hashCode()` for computing the hash code when first needed. See `AbstractIdentifiedObject​.computeHashCode()` for more information.
    Overrides:
      `computeHashCode` in class `AbstractIdentifiedObject`
    Returns:
      the hash code value. This value may change in any future Apache SIS version.

  - ### formatTo

    protected String formatTo(Formatter formatter)
    Formats this operation as a Well Known Text `Method[…]` element.
    Overrides:
      `formatTo` in class `AbstractIdentifiedObject`
    Parameters:
      `formatter` - the formatter where to format the inner content of this WKT element.
    Returns:
      `"Method"` (WKT 2) or `"Projection"` (WKT 1).
    See Also:
      - WKT 2 specification §17.2.3