Class DefaultCoordinateOperationFactory

java.lang.Object
org.apache.sis.util.iso.AbstractFactory
org.apache.sis.referencing.operation.DefaultCoordinateOperationFactory
All Implemented Interfaces:
org.opengis.referencing.ObjectFactory, org.opengis.referencing.operation.CoordinateOperationFactory, org.opengis.util.Factory

public class DefaultCoordinateOperationFactory extends AbstractFactory implements org.opengis.referencing.operation.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: The second approach is the most frequently used.
Since:
0.6
Version:
1.3
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    (package private) final Cache<CRSPair,org.opengis.referencing.operation.CoordinateOperation>
    The cache of coordinate operations found for a given pair of source and target CRS.
    private org.opengis.referencing.crs.CRSFactory
    The factory to use if CoordinateOperationFinder needs to create CRS for intermediate steps.
    private org.opengis.referencing.cs.CSFactory
    The factory to use if CoordinateOperationFinder needs to create CS for intermediate steps.
    private final Map<String,?>
    The default properties, or an empty map if none.
    private org.opengis.referencing.operation.MathTransformFactory
    The math transform factory.
    private final WeakHashSet<org.opengis.referencing.IdentifiedObject>
    Weak references to existing objects.
    (package private) static final boolean
    Whether this class is allowed to use the EPSG authority factory for searching coordinate operation paths.
  • Constructor Summary

    Constructors
    Constructor
    Description
    Constructs a factory with no default properties.
    DefaultCoordinateOperationFactory(Map<String,?> properties, org.opengis.referencing.operation.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.
    org.opengis.referencing.operation.CoordinateOperation
    createConcatenatedOperation(Map<String,?> properties, org.opengis.referencing.operation.CoordinateOperation... operations)
    Creates an ordered sequence of two or more single coordinate operations.
    org.opengis.referencing.operation.Conversion
    createDefiningConversion(Map<String,?> properties, org.opengis.referencing.operation.OperationMethod method, org.opengis.parameter.ParameterValueGroup parameters)
    Creates a defining conversion from the given operation parameters.
    org.opengis.referencing.operation.CoordinateOperation
    createOperation(org.opengis.referencing.crs.CoordinateReferenceSystem sourceCRS, org.opengis.referencing.crs.CoordinateReferenceSystem targetCRS)
    Finds or creates an operation for conversion or transformation between two coordinate reference systems.
    org.opengis.referencing.operation.CoordinateOperation
    createOperation(org.opengis.referencing.crs.CoordinateReferenceSystem sourceCRS, org.opengis.referencing.crs.CoordinateReferenceSystem targetCRS, CoordinateOperationContext context)
    Finds or creates an operation for conversion or transformation between two coordinate reference systems.
    org.opengis.referencing.operation.CoordinateOperation
    createOperation(org.opengis.referencing.crs.CoordinateReferenceSystem sourceCRS, org.opengis.referencing.crs.CoordinateReferenceSystem targetCRS, org.opengis.referencing.operation.OperationMethod method)
    createOperationFinder(org.opengis.referencing.operation.CoordinateOperationAuthorityFactory registry, CoordinateOperationContext context)
    Creates the object which will perform the actual task of finding a coordinate operation path between two CRS.
    org.opengis.referencing.operation.OperationMethod
    createOperationMethod(Map<String,?> properties, Integer sourceDimensions, Integer targetDimensions, org.opengis.parameter.ParameterDescriptorGroup parameters)
    Creates an operation method from a set of properties and a descriptor group.
    List<org.opengis.referencing.operation.CoordinateOperation>
    createOperations(org.opengis.referencing.crs.CoordinateReferenceSystem sourceCRS, org.opengis.referencing.crs.CoordinateReferenceSystem targetCRS, CoordinateOperationContext context)
    Finds or creates operations for conversions or transformations between two coordinate reference systems.
    org.opengis.referencing.operation.SingleOperation
    createSingleOperation(Map<String,?> properties, org.opengis.referencing.crs.CoordinateReferenceSystem sourceCRS, org.opengis.referencing.crs.CoordinateReferenceSystem targetCRS, org.opengis.referencing.crs.CoordinateReferenceSystem interpolationCRS, org.opengis.referencing.operation.OperationMethod method, org.opengis.referencing.operation.MathTransform transform)
    Creates a transformation or conversion from the given properties.
    (package private) final org.opengis.referencing.crs.CRSFactory
    Returns the factory to use if CoordinateOperationFinder needs to create CRS for intermediate steps.
    (package private) final org.opengis.referencing.cs.CSFactory
    Returns the factory to use if CoordinateOperationFinder needs to create CS for intermediate steps.
    (package private) final DefaultMathTransformFactory
    Returns the Apache SIS implementation of math transform factory.
    final org.opengis.referencing.operation.MathTransformFactory
    Returns the underlying math transform factory.
    org.opengis.referencing.operation.OperationMethod
    Returns the operation method of the given name.
    private static boolean
    isConversion(org.opengis.referencing.crs.CoordinateReferenceSystem sourceCRS, org.opengis.referencing.crs.CoordinateReferenceSystem targetCRS)
    Returns true if the given CRS are using equivalent (ignoring metadata) datum.

    Methods inherited from class org.apache.sis.util.iso.AbstractFactory

    getVendor

    Methods inherited from class java.lang.Object

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

    Methods inherited from interface org.opengis.util.Factory

    getVendor
  • Field Details

    • USE_EPSG_FACTORY

      static final boolean USE_EPSG_FACTORY
      Whether this class is allowed to use the EPSG authority factory for searching coordinate operation paths. This flag should always be true, except temporarily for testing purposes.
      See Also:
    • defaultProperties

      private final Map<String,?> defaultProperties
      The default properties, or an empty map if none. This map shall not change after construction in order to allow usage without synchronization in multi-thread context. But we do not need to wrap in a unmodifiable map since DefaultCoordinateOperationFactory does not provide public access to it.
    • crsFactory

      private volatile org.opengis.referencing.crs.CRSFactory crsFactory
      The factory to use if CoordinateOperationFinder needs to create CRS for intermediate steps. Will be created only when first needed.
      See Also:
    • csFactory

      private volatile org.opengis.referencing.cs.CSFactory csFactory
      The factory to use if CoordinateOperationFinder needs to create CS for intermediate steps. Will be created only when first needed.
      See Also:
    • mtFactory

      private volatile org.opengis.referencing.operation.MathTransformFactory mtFactory
      The math transform factory. Will be created only when first needed.
      See Also:
    • pool

      private final WeakHashSet<org.opengis.referencing.IdentifiedObject> pool
      Weak references to existing objects. This set is used in order to return a pre-existing object instead of creating a new one. This applies to objects created explicitly, not to coordinate operations inferred by a call to createOperation(CoordinateReferenceSystem, CoordinateReferenceSystem).
    • cache

      final Cache<CRSPair,org.opengis.referencing.operation.CoordinateOperation> cache
      The cache of coordinate operations found for a given pair of source and target CRS. If current implementation, we cache only operations found without context (otherwise we would need to take in account the area of interest and desired accuracy in the key).
      See Also:
  • Constructor Details

    • DefaultCoordinateOperationFactory

      public DefaultCoordinateOperationFactory()
      Constructs a factory with no default properties.
    • DefaultCoordinateOperationFactory

      public DefaultCoordinateOperationFactory(Map<String,?> properties, org.opengis.referencing.operation.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

    • 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.
    • getCRSFactory

      final org.opengis.referencing.crs.CRSFactory getCRSFactory()
      Returns the factory to use if CoordinateOperationFinder needs to create CRS for intermediate steps.
    • getCSFactory

      final org.opengis.referencing.cs.CSFactory getCSFactory()
      Returns the factory to use if CoordinateOperationFinder needs to create CS for intermediate steps.
    • getMathTransformFactory

      public final org.opengis.referencing.operation.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
    • getDefaultMathTransformFactory

      final DefaultMathTransformFactory getDefaultMathTransformFactory()
      Returns the Apache SIS implementation of math transform factory. This method is used only when we need SIS-specific methods.
    • getOperationMethod

      public org.opengis.referencing.operation.OperationMethod getOperationMethod(String name) throws org.opengis.util.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:
      org.opengis.util.FactoryException - if the requested operation method cannot be fetched.
      See Also:
    • createOperationMethod

      public org.opengis.referencing.operation.OperationMethod createOperationMethod(Map<String,?> properties, Integer sourceDimensions, Integer targetDimensions, org.opengis.parameter.ParameterDescriptorGroup parameters) throws org.opengis.util.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".
      sourceDimensions - number of dimensions in the source CRS of this operation method, or null.
      targetDimensions - number of dimensions in the target CRS of this operation method, or null.
      parameters - description of parameters expected by this operation.
      Returns:
      the operation method created from the given arguments.
      Throws:
      org.opengis.util.FactoryException - if the object creation failed.
      See Also:
    • createDefiningConversion

      public org.opengis.referencing.operation.Conversion createDefiningConversion(Map<String,?> properties, org.opengis.referencing.operation.OperationMethod method, org.opengis.parameter.ParameterValueGroup parameters) throws org.opengis.util.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 org.opengis.referencing.operation.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:
      org.opengis.util.FactoryException - if the object creation failed.
      See Also:
    • isConversion

      private static boolean isConversion(org.opengis.referencing.crs.CoordinateReferenceSystem sourceCRS, org.opengis.referencing.crs.CoordinateReferenceSystem targetCRS)
      Returns true if the given CRS are using equivalent (ignoring metadata) datum. If the CRS are CompoundCRS, then this method verifies that all datum in the target CRS exists in the source CRS, but not necessarily in the same order. The target CRS may have less datum than the source CRS.
      Parameters:
      sourceCRS - the target CRS.
      targetCRS - the source CRS.
      Returns:
      true if all datum in the targetCRS exists in the sourceCRS.
    • createSingleOperation

      public org.opengis.referencing.operation.SingleOperation createSingleOperation(Map<String,?> properties, org.opengis.referencing.crs.CoordinateReferenceSystem sourceCRS, org.opengis.referencing.crs.CoordinateReferenceSystem targetCRS, org.opengis.referencing.crs.CoordinateReferenceSystem interpolationCRS, org.opengis.referencing.operation.OperationMethod method, org.opengis.referencing.operation.MathTransform transform) throws org.opengis.util.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:
      org.opengis.util.FactoryException - if the object creation failed.
      See Also:
    • createConcatenatedOperation

      public org.opengis.referencing.operation.CoordinateOperation createConcatenatedOperation(Map<String,?> properties, org.opengis.referencing.operation.CoordinateOperation... operations) throws org.opengis.util.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 org.opengis.referencing.operation.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:
      org.opengis.util.FactoryException - if the object creation failed.
    • createOperation

      public org.opengis.referencing.operation.CoordinateOperation createOperation(org.opengis.referencing.crs.CoordinateReferenceSystem sourceCRS, org.opengis.referencing.crs.CoordinateReferenceSystem targetCRS) throws org.opengis.referencing.operation.OperationNotFoundException, org.opengis.util.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 org.opengis.referencing.operation.CoordinateOperationFactory
      Parameters:
      sourceCRS - input coordinate reference system.
      targetCRS - output coordinate reference system.
      Returns:
      a coordinate operation from sourceCRS to targetCRS.
      Throws:
      org.opengis.referencing.operation.OperationNotFoundException - if no operation path was found from sourceCRS to targetCRS.
      org.opengis.util.FactoryException - if the operation creation failed for some other reason.
    • createOperation

      public org.opengis.referencing.operation.CoordinateOperation createOperation(org.opengis.referencing.crs.CoordinateReferenceSystem sourceCRS, org.opengis.referencing.crs.CoordinateReferenceSystem targetCRS, CoordinateOperationContext context) throws org.opengis.referencing.operation.OperationNotFoundException, org.opengis.util.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:

      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:
      org.opengis.referencing.operation.OperationNotFoundException - if no operation path was found from sourceCRS to targetCRS.
      org.opengis.util.FactoryException - if the operation creation failed for some other reason.
      Since:
      0.7
      See Also:
    • createOperations

      public List<org.opengis.referencing.operation.CoordinateOperation> createOperations(org.opengis.referencing.crs.CoordinateReferenceSystem sourceCRS, org.opengis.referencing.crs.CoordinateReferenceSystem targetCRS, CoordinateOperationContext context) throws org.opengis.referencing.operation.OperationNotFoundException, org.opengis.util.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:

      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:
      org.opengis.referencing.operation.OperationNotFoundException - if no operation path was found from sourceCRS to targetCRS.
      org.opengis.util.FactoryException - if the operation creation failed for some other reason.
      Since:
      1.0
      See Also:
    • createOperationFinder

      protected CoordinateOperationFinder createOperationFinder(org.opengis.referencing.operation.CoordinateOperationAuthorityFactory registry, CoordinateOperationContext context) throws org.opengis.util.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: 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:
      org.opengis.util.FactoryException - if an error occurred while initializing the CoordinateOperationFinder.
      Since:
      0.8
    • createOperation

      @Deprecated public org.opengis.referencing.operation.CoordinateOperation createOperation(org.opengis.referencing.crs.CoordinateReferenceSystem sourceCRS, org.opengis.referencing.crs.CoordinateReferenceSystem targetCRS, org.opengis.referencing.operation.OperationMethod method) throws org.opengis.util.FactoryException
      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 org.opengis.referencing.operation.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:
      org.opengis.referencing.operation.OperationNotFoundException - if no operation path was found from sourceCRS to targetCRS.
      org.opengis.util.FactoryException - if the operation creation failed for some other reason.