# Class MultiRegisterOperations

Object
AbstractFactory
MultiRegisterOperations

All Implemented Interfaces:
  `Factory`

public class MultiRegisterOperations extends AbstractFactory
Finds CRSs or coordinate operations in one or many geodetic registries. Each `MultiRegisterOperations` instance can narrow the search to a single registry, a specific version of that registry, or to a domain of validity. Each instance is immutable and thread-safe.

This class delegates its work to static methods or to `MultiAuthoritiesFactory`. It does not provide new services compared to the above, but provides a more high-level API with the most important registry-based services in a single place. `RegisterOperations` can also be used as en entry point, with accesses to the low-level API granted by `getFactory(Class)`.

## User-defined geodetic registries

User-defined authorities can be added to the SIS environment by creating `CRSAuthorityFactory` implementations with a public no-argument constructor or a public static `provider()` method, and declaring the name of those classes in the `module-info​.java` file as a provider of the `org​.opengis​.referencing​.crs​.CRSAuthorityFactory` service.

Since:
  1.5

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `MultiRegisterOperations(MultiRegisterOperations source, String authority, String version)`
  Creates an instance which will use the registry of the specified authority, optionally at a specified version.
  `protected`
  `MultiRegisterOperations(MultiRegisterOperations source, GeographicBoundingBox areaOfInterest)`
  Creates an instance with the same register than the given instance, but a different AOI.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `CoordinateOperation`
  `findCoordinateOperation(String code)`
  Extracts coordinate operation details from the registry.
  `Set<CoordinateOperation>`
  `findCoordinateOperations(CoordinateReferenceSystem source, CoordinateReferenceSystem target)`
  Finds or infers any coordinate operations for which the given CRSs are the source and target, in that order.
  `CoordinateReferenceSystem`
  `findCoordinateReferenceSystem(String code)`
  Extracts CRS details from the registry.
  `<T extends Factory>
  Optional<T>`
  `getFactory(Class<? extends T> type)`
  Returns a factory used for building components of CRS or coordinate operations.
  `static MultiRegisterOperations`
  `provider()`
  Returns an instance which will search CRS definitions in all registries that are known to SIS.
  `MultiRegisterOperations`
  `withAreaOfInterest(GeographicBoundingBox newValue)`
  Returns an instance for the specified area of interest (AOI).
  `MultiRegisterOperations`
  `withAuthority(String newValue)`
  Returns an instance for a geodetic registry of the specified authority, such as "EPSG".
  `MultiRegisterOperations`
  `withVersion(String newValue)`
  Returns an instance for the specified version of the geodetic registry.

  ### Methods inherited from class AbstractFactory

  `getVendor, toString`

  ### Methods inherited from class Object

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

- ## Constructor Details

  - ### MultiRegisterOperations

    protected MultiRegisterOperations(MultiRegisterOperations source, GeographicBoundingBox areaOfInterest)
    Creates an instance with the same register than the given instance, but a different AOI.
    Parameters:
      `source` - the register from which to copy the authority and version.
      `areaOfInterest` - the new area of interest (AOI), or `null` if none.
    See Also:
      - `withAreaOfInterest(GeographicBoundingBox)`

  - ### MultiRegisterOperations

    protected MultiRegisterOperations(MultiRegisterOperations source, String authority, String version) throws FactoryException
    Creates an instance which will use the registry of the specified authority, optionally at a specified version.
    Parameters:
      `source` - the register from which to copy the area of interest.
      `authority` - identification of the registry to use (e.g., "EPSG").
      `version` - the registry version to use, or `null` for the default version.
    Throws:
      `NoSuchAuthorityFactoryException` - if the specified registry has not been found.
      `FactoryException` - if an error occurred while initializing this factory.
    See Also:
      - `withAuthority(String)`
      - `withVersion(String)`

- ## Method Details

  - ### provider

    public static MultiRegisterOperations provider()
    Returns an instance which will search CRS definitions in all registries that are known to SIS. Because this instance is not for a specific registry, the authority will need to be part of the `code` argument given to `create(String)` methods. For example, `"EPSG:4326"` instead of `"4326"`. The registry can be made implicit by a call to `withAuthority(String)`.
    Returns:
      the default instance for all registries known to SIS.

  - ### withAuthority

    public MultiRegisterOperations withAuthority(String newValue) throws FactoryException
    Returns an instance for a geodetic registry of the specified authority, such as "EPSG". If a version number was specified previously, that version is cleared. If an area of interest was specified, the same area of interest is reused.

    ## User-defined geodetic registries

    A user-defined authority can be specified if the implementation is declared in a `module-info` file as a `CRSAuthorityFactory` service. See class javadoc for more information.
    Parameters:
      `newValue` - the desired authority, or `null` for all of them.
    Returns:
      register operations for the specified authority.
    Throws:
      `NoSuchAuthorityFactoryException` - if the given authority is unknown to SIS.
      `FactoryException` - if the factory cannot be created for another reason.
    See Also:
      - `CRS​.getAuthorityFactory(String)`

  - ### withVersion

    public MultiRegisterOperations withVersion(String newValue) throws FactoryException
    Returns an instance for the specified version of the geodetic registry. A non-null authority must have been specified before to invoke this method. If an area of interest was specified, the same area of interest is reused.
    Parameters:
      `newValue` - the desired version, or `null` for the default version.
    Returns:
      register operations for the specified version of the geodetic registry.
    Throws:
      `IllegalStateException` - if the version is non-null and no authority has been specified previously.
      `NoSuchAuthorityFactoryException` - if the given version is unknown to SIS.
      `FactoryException` - if the factory cannot be created for another reason.

  - ### withAreaOfInterest

    public MultiRegisterOperations withAreaOfInterest(GeographicBoundingBox newValue)
    Returns an instance for the specified area of interest (AOI). The area of interest is used for filtering coordinate operations between a between a pair of CRSs.
    Parameters:
      `newValue` - the desired area of interest, or `null` for the world.
    Returns:
      register operations for the specified area of interest.

  - ### findCoordinateReferenceSystem

    public CoordinateReferenceSystem findCoordinateReferenceSystem(String code) throws FactoryException
    Extracts CRS details from the registry. If this `RegisterOperations` has not been restricted to a specific authority by a call to `withAuthority(String)`, then the given code must contain the authority (e.g., `"EPSG:4326"` instead of `"4326"`. Otherwise, this method delegates to `CRS​.forCode(jString)`.

    By default, this method recognizes the `"EPSG"` and `"OGC"` authorities. In the `"EPSG"` case, whether the full set of EPSG codes is supported or not depends on whether a connection to the database can be established. If no connection can be established, then this method uses a small embedded EPSG factory containing at least the CRS defined in the

    invalid reference

        #forCode(String)

    method javadoc.
    Parameters:
      `code` - CRS identifier allocated by the authority.
    Returns:
      the CRS for the given authority code.
    Throws:
      `NoSuchAuthorityCodeException` - if the specified `code` was not found.
      `FactoryException` - if the search failed for some other reason.
    See Also:
      - `CRS​.forCode(String)`

  - ### findCoordinateOperation

    public CoordinateOperation findCoordinateOperation(String code) throws FactoryException
    Extracts coordinate operation details from the registry. If this `RegisterOperations` has not been restricted to a specific authority by a call to `withAuthority(String)`, then the given code must contain the authority.
    Parameters:
      `code` - operation identifier allocated by the authority.
    Returns:
      the operation for the given authority code.
    Throws:
      `NoSuchAuthorityCodeException` - if the specified `code` was not found.
      `FactoryException` - if the search failed for some other reason.

  - ### findCoordinateOperations

    public Set<CoordinateOperation> findCoordinateOperations(CoordinateReferenceSystem source, CoordinateReferenceSystem target) throws FactoryException
    Finds or infers any coordinate operations for which the given CRSs are the source and target, in that order. This method searches for operation paths defined in the registry. If none are found, this method tries to infer a path itself.
    Parameters:
      `source` - the source CRS.
      `target` - the target CRS.
    Returns:
      coordinate operations found or inferred between the given pair CRSs. May be an empty set.
    Throws:
      `FactoryException` - if an error occurred while searching for coordinate operations.

  - ### getFactory

    public <T extends Factory> Optional<T> getFactory(Class<? extends T> type) throws FactoryException
    Returns a factory used for building components of CRS or coordinate operations. The factories returned by this method provide accesses to the low-level services used by this `RegisterOperations` instance for implementing its high-level services.
    Type Parameters:
      `T` - compile-time value of the `type` argument.
    Parameters:
      `type` - the desired type of factory.
    Returns:
      factory of the specified type.
    Throws:
      `NullPointerException` - if the specified type is null.
      `IllegalArgumentException` - if the specified type is not one of the above-cited values.
      `FactoryException` - if an error occurred while searching or preparing the requested factory.