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

# Class DefaultCoordinateOperationFactory

Object
AbstractFactory
DefaultCoordinateOperationFactory

All Implemented Interfaces:
  `ObjectFactory`, `CoordinateOperationFactory`, `Factory`

public class DefaultCoordinateOperationFactory extends AbstractFactory implements CoordinateOperationFactory
Creates operations capable to transform coordinates from a given source CRS to a given target CRS. This factory provides two ways to create such operations:

- By fetching or building explicitly each components of the operation:
  - The `operation method`, which can be fetched from a set of predefined methods or built explicitly.
  - A single defining conversion.
  - A concatenation of other operations.
- By giving only the source and target CRS, then let the Apache SIS referencing engine infers by itself the coordinate operation (with the help of an EPSG database if available).

The second approach is the most frequently used.

## Thread safety

This class is safe for multi-thread usage if all referenced factories are thread-safe.

Since:
  0.6

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `DefaultCoordinateOperationFactory()`
  Constructs a factory with no default properties.
  `DefaultCoordinateOperationFactory(Map<String,?> properties, MathTransformFactory factory)`
  Constructs a factory with the given default properties.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected Map<String,?>`
  `complete(Map<String,?> properties)`
  Returns the union of the given `properties` map with the default properties given at construction time.
  `CoordinateOperation`
  `createConcatenatedOperation(Map<String,?> properties, CoordinateOperation... operations)`
  Creates an ordered sequence of two or more single coordinate operations.
  `Conversion`
  `createDefiningConversion(Map<String,?> properties, OperationMethod method, ParameterValueGroup parameters)`
  Creates a defining conversion from the given operation parameters.
  `CoordinateOperation`
  `createOperation(CoordinateReferenceSystem sourceCRS, CoordinateReferenceSystem targetCRS)`
  Finds or creates an operation for conversion or transformation between two coordinate reference systems.
  `CoordinateOperation`
  `createOperation(CoordinateReferenceSystem sourceCRS, CoordinateReferenceSystem targetCRS, CoordinateOperationContext context)`
  Finds or creates an operation for conversion or transformation between two coordinate reference systems.
  `CoordinateOperation`
  `createOperation(CoordinateReferenceSystem sourceCRS, CoordinateReferenceSystem targetCRS, OperationMethod method)`
  Deprecated.
  Replaced by `createOperation(CoordinateReferenceSystem, CoordinateReferenceSystem, CoordinateOperationContext)`.
  `protected CoordinateOperationFinder`
  `createOperationFinder(CoordinateOperationAuthorityFactory registry, CoordinateOperationContext context)`
  Creates the object which will perform the actual task of finding a coordinate operation path between two CRS.
  `OperationMethod`
  `createOperationMethod(Map<String,?> properties, ParameterDescriptorGroup parameters)`
  Creates an operation method from a set of properties and a descriptor group.
  `List<CoordinateOperation>`
  `createOperations(CoordinateReferenceSystem sourceCRS, CoordinateReferenceSystem targetCRS, CoordinateOperationContext context)`
  Finds or creates operations for conversions or transformations between two coordinate reference systems.
  `SingleOperation`
  `createSingleOperation(Map<String,?> properties, CoordinateReferenceSystem sourceCRS, CoordinateReferenceSystem targetCRS, CoordinateReferenceSystem interpolationCRS, OperationMethod method, MathTransform transform)`
  Creates a transformation or conversion from the given properties.
  `final MathTransformFactory`
  `getMathTransformFactory()`
  Returns the underlying math transform factory.
  `OperationMethod`
  `getOperationMethod(String name)`
  Returns the operation method of the given name.
  `static DefaultCoordinateOperationFactory`
  `provider()`
  Returns the default provider of `CoordinateOperation` instances.

  ### Methods inherited from class AbstractFactory

  `getVendor`

  ### Methods inherited from class Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

  ### Methods inherited from interface Factory

  `getVendor`

- ## Constructor Details

  - ### DefaultCoordinateOperationFactory

    public DefaultCoordinateOperationFactory()
    Constructs a factory with no default properties.
    See Also:
      - `provider()`

  - ### DefaultCoordinateOperationFactory

    public DefaultCoordinateOperationFactory(Map<String,?> properties, MathTransformFactory factory)
    Constructs a factory with the given default properties. The new factory will fallback on the map given to this constructor for any property not present in the map given to a `createFoo(Map<String,?>, …)` method.
    Parameters:
      `properties` - the default properties, or `null` if none.
      `factory` - the factory to use for creating math transforms, or `null` for the default factory.

- ## Method Details

  - ### provider

    public static DefaultCoordinateOperationFactory provider()
    Returns the default provider of `CoordinateOperation` instances. This is the factory used by the Apache SIS library when no non-null `CoordinateOperationFactory` has been explicitly specified. This method can be invoked directly, or indirectly through `ServiceLoader​.load(CoordinateOperationFactory​.class)`.
    Returns:
      the default provider of coordinate operations.
    Since:
      1.4
    See Also:
      - `ServiceLoader`

  - ### complete

    protected Map<String,?> complete(Map<String,?> properties)
    Returns the union of the given `properties` map with the default properties given at construction time. Entries in the given properties map have precedence, even if their value is `null` (i.e. a null value "erase" the default property value). Entries with null value after the union will be omitted.

    This method is invoked by all `createFoo(Map<String,?>, …)` methods for determining the properties to give to coordinate operation constructor.

    Parameters:
      `properties` - the user supplied properties.
    Returns:
      the union of the given properties with the default properties.

  - ### getMathTransformFactory

    public final MathTransformFactory getMathTransformFactory()
    Returns the underlying math transform factory. This factory is used for constructing the `MathTransform` instances doing the actual mathematical work of coordinate operations instances.
    Returns:
      the underlying math transform factory.
    Since:
      1.1

  - ### getOperationMethod

    public OperationMethod getOperationMethod(String name) throws FactoryException
    Returns the operation method of the given name. The given argument shall be either a method name (e.g. "Transverse Mercator") or one of its identifiers (e.g. `"EPSG:9807"`). The search is case-insensitive and comparisons against method names can be heuristic.

    If more than one method match the given name, then the first (according iteration order) non-deprecated matching method is returned. If all matching methods are deprecated, the first one is returned.

    Parameters:
      `name` - the name of the operation method to fetch.
    Returns:
      the operation method of the given name.
    Throws:
      `FactoryException` - if the requested operation method cannot be fetched.
    See Also:
      - `DefaultMathTransformFactory​.getOperationMethod(String)`

  - ### createOperationMethod

    public OperationMethod createOperationMethod(Map<String,?> properties, ParameterDescriptorGroup parameters) throws FactoryException
    Creates an operation method from a set of properties and a descriptor group. The source and target dimensions may be `null` if the method can work with any number of dimensions (e.g. Affine Transform).

    The properties given in argument follow the same rules than for the operation method constructor. The following table is a reminder of main (not all) properties:

    Recognized properties (non exhaustive list)
    Property name | Value type | Returned by
    --- | --- | ---
    "name" | `Identifier` or `String` | `AbstractIdentifiedObject.getName()`
    "alias" | `GenericName` or `CharSequence` (optionally as array) | `AbstractIdentifiedObject.getAlias()`
    "identifiers" | `Identifier` (optionally as array) | `AbstractIdentifiedObject.getIdentifiers()`
    "formula" | `Formula`, `Citation` or `CharSequence` | `DefaultOperationMethod.getFormula()`

    Parameters:
      `properties` - set of properties. Shall contain at least `"name"`.
      `parameters` - description of parameters expected by this operation.
    Returns:
      the operation method created from the given arguments.
    Throws:
      `FactoryException` - if the object creation failed.
    Since:
      1.4
    See Also:
      - `DefaultOperationMethod(Map, ParameterDescriptorGroup)`

  - ### createDefiningConversion

    public Conversion createDefiningConversion(Map<String,?> properties, OperationMethod method, ParameterValueGroup parameters) throws FactoryException
    Creates a defining conversion from the given operation parameters. This conversion has no source and target CRS since those elements are usually unknown at this stage. The source and target CRS will become known later, at the Derived CRS or Projected CRS construction time.

    The properties given in argument follow the same rules than for the coordinate conversion constructor. The following table is a reminder of main (not all) properties:

    Recognized properties (non exhaustive list)
    Property name | Value type | Returned by
    --- | --- | ---
    "name" | `Identifier` or `String` | `AbstractIdentifiedObject.getName()`
    "identifiers" | `Identifier` (optionally as array) | `AbstractIdentifiedObject.getIdentifiers()`
    "domainOfValidity" | `Extent` | `AbstractCoordinateOperation.getDomainOfValidity()`

    Specified by:
      `createDefiningConversion` in interface `CoordinateOperationFactory`
    Parameters:
      `properties` - the properties to be given to the identified object.
      `method` - the operation method.
      `parameters` - the parameter values.
    Returns:
      the defining conversion created from the given arguments.
    Throws:
      `FactoryException` - if the object creation failed.
    See Also:
      - `DefaultConversion(Map, OperationMethod, MathTransform, ParameterValueGroup)`

  - ### createSingleOperation

    public SingleOperation createSingleOperation(Map<String,?> properties, CoordinateReferenceSystem sourceCRS, CoordinateReferenceSystem targetCRS, CoordinateReferenceSystem interpolationCRS, OperationMethod method, MathTransform transform) throws FactoryException
    Creates a transformation or conversion from the given properties. This method infers by itself if the operation to create is a `Transformation`, a `Conversion` or a `Projection` sub-type (`CylindricalProjection`, `ConicProjection` or `PlanarProjection`) using the information provided by the given method.

    The properties given in argument follow the same rules than for the coordinate operation constructor. The following table is a reminder of main (not all) properties:

    Recognized properties (non exhaustive list)
    Property name | Value type | Returned by
    --- | --- | ---
    "name" | `Identifier` or `String` | `AbstractIdentifiedObject.getName()`
    "identifiers" | `Identifier` (optionally as array) | `AbstractIdentifiedObject.getIdentifiers()`
    "domainOfValidity" | `Extent` | `AbstractCoordinateOperation.getDomainOfValidity()`

    Parameters:
      `properties` - the properties to be given to the identified object.
      `sourceCRS` - the source CRS.
      `targetCRS` - the target CRS.
      `interpolationCRS` - the CRS of additional coordinates needed for the operation, or `null` if none.
      `method` - the coordinate operation method (mandatory in all cases).
      `transform` - transform from positions in the source CRS to positions in the target CRS.
    Returns:
      the coordinate operation created from the given arguments.
    Throws:
      `FactoryException` - if the object creation failed.
    See Also:
      - `DefaultOperationMethod​.getOperationType()`
      - `DefaultTransformation`
      - `DefaultConversion`

  - ### createConcatenatedOperation

    public CoordinateOperation createConcatenatedOperation(Map<String,?> properties, CoordinateOperation... operations) throws FactoryException
    Creates an ordered sequence of two or more single coordinate operations. The sequence of operations is constrained by the requirement that the source coordinate reference system of step (n+1) must be the same as the target coordinate reference system of step (n). The source coordinate reference system of the first step and the target coordinate reference system of the last step are the source and target coordinate reference system associated with the concatenated operation.

    The properties given in argument follow the same rules than for any other coordinate operation constructor. The following table is a reminder of main (not all) properties:

    Recognized properties (non exhaustive list)
    Property name | Value type | Returned by
    --- | --- | ---
    "name" | `Identifier` or `String` | `AbstractIdentifiedObject.getName()`
    "identifiers" | `Identifier` (optionally as array) | `AbstractIdentifiedObject.getIdentifiers()`

    Specified by:
      `createConcatenatedOperation` in interface `CoordinateOperationFactory`
    Parameters:
      `properties` - the properties to be given to the identified object.
      `operations` - the sequence of operations. Shall contain at least two operations.
    Returns:
      the concatenated operation created from the given arguments.
    Throws:
      `FactoryException` - if the object creation failed.

  - ### createOperation

    public CoordinateOperation createOperation(CoordinateReferenceSystem sourceCRS, CoordinateReferenceSystem targetCRS) throws OperationNotFoundException, FactoryException
    Finds or creates an operation for conversion or transformation between two coordinate reference systems. If an operation exists, it is returned. If more than one operation exists, the operation having the widest domain of validity is returned. If no operation exists, then an exception is thrown.

    The default implementation delegates to `createOperation(sourceCRS, targetCRS, null)}`.

    Specified by:
      `createOperation` in interface `CoordinateOperationFactory`
    Parameters:
      `sourceCRS` - input coordinate reference system.
      `targetCRS` - output coordinate reference system.
    Returns:
      a coordinate operation from `sourceCRS` to `targetCRS`.
    Throws:
      `OperationNotFoundException` - if no operation path was found from `sourceCRS` to `targetCRS`.
      `FactoryException` - if the operation creation failed for some other reason.

  - ### createOperation

    public CoordinateOperation createOperation(CoordinateReferenceSystem sourceCRS, CoordinateReferenceSystem targetCRS, CoordinateOperationContext context) throws OperationNotFoundException, FactoryException
    Finds or creates an operation for conversion or transformation between two coordinate reference systems. If an operation exists, it is returned. If more than one operation exists, then the operation having the widest intersection between its domain of validity and the area of interest is returned.

    The default implementation performs the following steps:

    - If a coordinate operation has been previously cached for the given CRS and context, return it.
    - Otherwise:
      1. Invoke `createOperationFinder(CoordinateOperationAuthorityFactory, CoordinateOperationContext)`.
      2. Invoke `CoordinateOperationFinder​.createOperation(CoordinateReferenceSystem, CoordinateReferenceSystem)` on the object returned by the previous step.
      3. Cache the result, then return it.
    Subclasses can override `createOperationFinder(…)` if they need more control on the way coordinate operations are inferred.
    Parameters:
      `sourceCRS` - input coordinate reference system.
      `targetCRS` - output coordinate reference system.
      `context` - area of interest and desired accuracy, or `null`.
    Returns:
      a coordinate operation from `sourceCRS` to `targetCRS`.
    Throws:
      `OperationNotFoundException` - if no operation path was found from `sourceCRS` to `targetCRS`.
      `FactoryException` - if the operation creation failed for some other reason.
    Since:
      0.7
    See Also:
      - `CoordinateOperationFinder`

  - ### createOperations

    public List<CoordinateOperation> createOperations(CoordinateReferenceSystem sourceCRS, CoordinateReferenceSystem targetCRS, CoordinateOperationContext context) throws OperationNotFoundException, FactoryException
    Finds or creates operations for conversions or transformations between two coordinate reference systems. If at least one operation exists, they are returned in preference order: the operation having the widest intersection between its domain of validity and the area of interest is returned.

    The default implementation performs the following steps:

    - Invoke `createOperationFinder(CoordinateOperationAuthorityFactory, CoordinateOperationContext)`.
    - Invoke `CoordinateOperationFinder​.createOperations(CoordinateReferenceSystem, CoordinateReferenceSystem)` on the object returned by the previous step.
    Subclasses can override `createOperationFinder(…)` if they need more control on the way coordinate operations are inferred.
    Parameters:
      `sourceCRS` - input coordinate reference system.
      `targetCRS` - output coordinate reference system.
      `context` - area of interest and desired accuracy, or `null`.
    Returns:
      coordinate operations from `sourceCRS` to `targetCRS`.
    Throws:
      `OperationNotFoundException` - if no operation path was found from `sourceCRS` to `targetCRS`.
      `FactoryException` - if the operation creation failed for some other reason.
    Since:
      1.0
    See Also:
      - `CoordinateOperationFinder`

  - ### createOperationFinder

    protected CoordinateOperationFinder createOperationFinder(CoordinateOperationAuthorityFactory registry, CoordinateOperationContext context) throws FactoryException
    Creates the object which will perform the actual task of finding a coordinate operation path between two CRS. This method is invoked by `createOperation(…)` when no operation was found in the cache. The default implementation is straightforward:

        return new CoordinateOperationFinder(registry, this, context);

    Subclasses can override this method is they want to modify the way coordinate operations are inferred.
    Parameters:
      `registry` - the factory to use for creating operations as defined by authority, or `null` if none.
      `context` - the area of interest and desired accuracy, or `null` if none.
    Returns:
      a finder of conversion or transformation path from a source CRS to a target CRS.
    Throws:
      `FactoryException` - if an error occurred while initializing the `CoordinateOperationFinder`.
    Since:
      0.8

  - ### createOperation

    @Deprecated(since="0.7") public CoordinateOperation createOperation(CoordinateReferenceSystem sourceCRS, CoordinateReferenceSystem targetCRS, OperationMethod method) throws FactoryException
    Deprecated.
    Replaced by `createOperation(CoordinateReferenceSystem, CoordinateReferenceSystem, CoordinateOperationContext)`.
    Returns an operation using a particular method for conversion or transformation between two coordinate reference systems. If an operation exists using the given method, then it is returned. If no operation using the given method is found, then the implementation has the option of inferring the operation from the argument objects.

    Current implementation ignores the `method` argument. This behavior may change in a future Apache SIS version.

    Specified by:
      `createOperation` in interface `CoordinateOperationFactory`
    Parameters:
      `sourceCRS` - input coordinate reference system.
      `targetCRS` - output coordinate reference system.
      `method` - the algorithmic method for conversion or transformation.
    Returns:
      a coordinate operation from `sourceCRS` to `targetCRS`.
    Throws:
      `OperationNotFoundException` - if no operation path was found from `sourceCRS` to `targetCRS`.
      `FactoryException` - if the operation creation failed for some other reason.