# Class DatumOrEnsemble

Object
DatumOrEnsemble

public final class DatumOrEnsemble extends Object
Utility methods for working on objects that may be `Datum` or `DatumEnsemble`. The methods in this class view an ensemble as if it was a datum for the sake of simplicity. For example, `DatumOrEnsemble​.of(crs)` allows to compare the datum name without the need to check which one of the `getDatum()` or `getDatumEnsemble()` methods returns a non-null value.

Since:
  1.5

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static EngineeringDatum`
  `asDatum(EngineeringCRS crs)`
  Returns the datum (preferred) or ensemble (fallback) of the given engineering CRS.
  `static GeodeticDatum`
  `asDatum(GeodeticCRS crs)`
  Returns the datum (preferred) or ensemble (fallback) of the given geodetic CRS.
  `static TemporalDatum`
  `asDatum(TemporalCRS crs)`
  Returns the datum (preferred) or ensemble (fallback) of the given temporal CRS.
  `static VerticalDatum`
  `asDatum(VerticalCRS crs)`
  Returns the datum (preferred) or ensemble (fallback) of the given vertical CRS.
  `static Optional<DefaultDatumEnsemble<EngineeringDatum>>`
  `asEnsemble(EngineeringDatum datum)`
  If the given object is a pseudo-datum for a engineering ensemble, returns that ensemble.
  `static Optional<DefaultDatumEnsemble<GeodeticDatum>>`
  `asEnsemble(GeodeticDatum datum)`
  If the given object is a pseudo-datum for a geodetic ensemble, returns that ensemble.
  `static Optional<DefaultDatumEnsemble<TemporalDatum>>`
  `asEnsemble(TemporalDatum datum)`
  If the given object is a pseudo-datum for a temporal ensemble, returns that ensemble.
  `static Optional<DefaultDatumEnsemble<VerticalDatum>>`
  `asEnsemble(VerticalDatum datum)`
  If the given object is a pseudo-datum for a vertical ensemble, returns that ensemble.
  `static Optional<EngineeringDatum>`
  `asTargetDatum(EngineeringCRS source, EngineeringCRS target)`
  Returns the datum or pseudo-datum of the result of an operation between the given engineering CRSs.
  `static Optional<GeodeticDatum>`
  `asTargetDatum(GeodeticCRS source, GeodeticCRS target)`
  Returns the datum or pseudo-datum of the result of an operation between the given geodetic CRSs.
  `static Optional<TemporalDatum>`
  `asTargetDatum(TemporalCRS source, TemporalCRS target)`
  Returns the datum or pseudo-datum of the result of an operation between the given temporal CRSs.
  `static Optional<VerticalDatum>`
  `asTargetDatum(VerticalCRS source, VerticalCRS target)`
  Returns the datum or pseudo-datum of the result of an operation between the given vertical CRSs.
  `static Optional<PositionalAccuracy>`
  `getAccuracy(IdentifiedObject object)`
  If the given object is a datum ensemble or a CRS associated to a datum ensemble, returns its accuracy.
  `static Optional<Ellipsoid>`
  `getEllipsoid(CoordinateReferenceSystem crs)`
  Returns the ellipsoid used by the given coordinate reference system.
  `static Optional<PrimeMeridian>`
  `getPrimeMeridian(CoordinateReferenceSystem crs)`
  Returns the prime meridian used by the given coordinate reference system.
  `static boolean`
  `isLegacyDatum(DefaultDatumEnsemble<?> ensemble, Datum datum, ComparisonMode mode)`
  Returns whether a legacy definition of a datum may be considered as equivalent to the given datum ensemble.
  `static IdentifiedObject`
  `of(SingleCRS crs)`
  Returns the datum of the given CRS if presents, or the datum ensemble otherwise.
  `static Optional<IdentifiedObject>`
  `ofTarget(SingleCRS source, SingleCRS target)`
  Returns the datum or ensemble of a coordinate operation from source to target.

  ### Methods inherited from class Object

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

- ## Method Details

  - ### of

    public static IdentifiedObject of(SingleCRS crs)
    Returns the datum of the given CRS if presents, or the datum ensemble otherwise. This is an alternative to the `asDatum(…)` methods when the caller does not need to view the returned object as a datum.
    Parameters:
      `crs` - the CRS from which to get the datum or ensemble, or `null`.
    Returns:
      the datum if present, or the datum ensemble otherwise, or `null`.

  - ### ofTarget

    public static Optional<IdentifiedObject> ofTarget(SingleCRS source, SingleCRS target)
    Returns the datum or ensemble of a coordinate operation from source to target. If the two given coordinate reference systems are associated to equal datum (ignoring metadata), then this method returns the target datum. Otherwise, this method returns the largest ensemble which fully contains the datum or datum ensemble of the other CRS. That largest common ensemble is interpreted as the new target of the operation result. If none of the source or target datum ensembles met the above criteria, then this method returns an empty value. A non-empty value means that it is okay, for low accuracy requirements, to ignore the datum shift.

    This is an alternative to the `asTargetDatum(…)` methods when the caller does not need to view the returned object as a datum.

    Parameters:
      `source` - the source CRS of a coordinate operation.
      `target` - the target CRS of a coordinate operation.
    Returns:
      datum or datum ensemble of the coordinate operation result if it is okay to ignore datum shift.
    Throws:
      `NullPointerException` - if any argument is null.

  - ### asDatum

    public static GeodeticDatum asDatum(GeodeticCRS crs)
    Returns the datum (preferred) or ensemble (fallback) of the given geodetic CRS. If the given CRS is associated to a non-null datum, then this method returns that datum. Otherwise, this method returns the CRS datum ensemble as a pseudo-datum.

    #### Common properties

    If an ensemble is viewed as a pseudo-datum, then the implementation of the `GeodeticDatum​.getEllipsoid()` and `GeodeticDatum​.getPrimeMeridian()` methods will verify that all members have the same ellipsoid or prime meridian respectively. If this condition does not hold, then a `GeodeticException` will be thrown. Note that this verification is done when the above-cited methods are invoked, not when this `asDatum(…)` method is invoked.
    Parameters:
      `crs` - the coordinate reference system for which to get the datum or datum ensemble, or `null`.
    Returns:
      the datum or pseudo-datum of the given CRS, or `null`.

  - ### asDatum

    public static VerticalDatum asDatum(VerticalCRS crs)
    Returns the datum (preferred) or ensemble (fallback) of the given vertical CRS. If the given CRS is associated to a non-null datum, then this method returns that datum. Otherwise, this method returns the CRS datum ensemble as a pseudo-datum.
    Parameters:
      `crs` - the coordinate reference system for which to get the datum or datum ensemble, or `null`.
    Returns:
      the datum or pseudo-datum of the given CRS, or `null`.

  - ### asDatum

    public static TemporalDatum asDatum(TemporalCRS crs)
    Returns the datum (preferred) or ensemble (fallback) of the given temporal CRS. If the given CRS is associated to a non-null datum, then this method returns that datum. Otherwise, this method returns the CRS datum ensemble as a pseudo-datum.

    #### Common property

    If an ensemble is viewed as a pseudo-datum, then the implementation of the `TemporalDatum​.getOrigin()` method will verify that all members have the same origin. If this condition does not hold, then a `GeodeticException` will be thrown. Note that this verification is done when the above-cited method is invoked, not when this `asDatum(…)` method is invoked.
    Parameters:
      `crs` - the coordinate reference system for which to get the datum or datum ensemble, or `null`.
    Returns:
      the datum or pseudo-datum of the given CRS, or `null`.

  - ### asDatum

    public static EngineeringDatum asDatum(EngineeringCRS crs)
    Returns the datum (preferred) or ensemble (fallback) of the given engineering CRS. If the given CRS is associated to a non-null datum, then this method returns that datum. Otherwise, this method returns the CRS datum ensemble as a pseudo-datum.
    Parameters:
      `crs` - the coordinate reference system for which to get the datum or datum ensemble, or `null`.
    Returns:
      the datum or pseudo-datum of the given CRS, or `null`.

  - ### asTargetDatum

    public static Optional<GeodeticDatum> asTargetDatum(GeodeticCRS source, GeodeticCRS target)
    Returns the datum or pseudo-datum of the result of an operation between the given geodetic CRSs. If the two given coordinate reference systems are associated to equal (ignoring metadata) datum, then this method returns the target datum. Otherwise, this method returns a pseudo-datum for the largest ensemble which fully contains the datum or datum ensemble of the other CRS. That largest common ensemble is interpreted as the new target of the operation result. If none of the source or target datum ensembles met the above criteria, then this method returns an empty value. A non-empty value means that it is okay, for low accuracy requirements, to ignore the datum shift.
    Parameters:
      `source` - the source CRS of a coordinate operation.
      `target` - the target CRS of a coordinate operation.
    Returns:
      datum or pseudo-datum of the coordinate operation result if it is okay to ignore datum shift.
    Throws:
      `NullPointerException` - if any argument is null.

  - ### asTargetDatum

    public static Optional<VerticalDatum> asTargetDatum(VerticalCRS source, VerticalCRS target)
    Returns the datum or pseudo-datum of the result of an operation between the given vertical CRSs. See `asTargetDatum(GeodeticCRS, GeodeticCRS)` for more information.
    Parameters:
      `source` - the source CRS of a coordinate operation.
      `target` - the target CRS of a coordinate operation.
    Returns:
      datum or pseudo-datum of the coordinate operation result if it is okay to ignore datum shift.
    Throws:
      `NullPointerException` - if any argument is null.

  - ### asTargetDatum

    public static Optional<TemporalDatum> asTargetDatum(TemporalCRS source, TemporalCRS target)
    Returns the datum or pseudo-datum of the result of an operation between the given temporal CRSs. See `asTargetDatum(GeodeticCRS, GeodeticCRS)` for more information.
    Parameters:
      `source` - the source CRS of a coordinate operation.
      `target` - the target CRS of a coordinate operation.
    Returns:
      datum or pseudo-datum of the coordinate operation result if it is okay to ignore datum shift.
    Throws:
      `NullPointerException` - if any argument is null.

  - ### asTargetDatum

    public static Optional<EngineeringDatum> asTargetDatum(EngineeringCRS source, EngineeringCRS target)
    Returns the datum or pseudo-datum of the result of an operation between the given engineering CRSs. See `asTargetDatum(GeodeticCRS, GeodeticCRS)` for more information.
    Parameters:
      `source` - the source CRS of a coordinate operation.
      `target` - the target CRS of a coordinate operation.
    Returns:
      datum or pseudo-datum of the coordinate operation result if it is okay to ignore datum shift.
    Throws:
      `NullPointerException` - if any argument is null.

  - ### asEnsemble

    public static Optional<DefaultDatumEnsemble<GeodeticDatum>> asEnsemble(GeodeticDatum datum)
    If the given object is a pseudo-datum for a geodetic ensemble, returns that ensemble. This method is the converse of `asDatum(GeodeticCRS)` and recognizes only the pseudo-datum created by this class of by `DefaultDatumEnsemble` static methods.
    Parameters:
      `datum` - the object which may be a pseudo-datum for an ensemble, or `null`.
    Returns:
      the given object cast to a datum ensemble if the cast is valid.

  - ### asEnsemble

    public static Optional<DefaultDatumEnsemble<VerticalDatum>> asEnsemble(VerticalDatum datum)
    If the given object is a pseudo-datum for a vertical ensemble, returns that ensemble. This method is the converse of `asDatum(VerticalCRS)` and recognizes only the pseudo-datum created by this class of by `DefaultDatumEnsemble` static methods.
    Parameters:
      `datum` - the object which may be a pseudo-datum for an ensemble, or `null`.
    Returns:
      the given object cast to a datum ensemble if the cast is valid.

  - ### asEnsemble

    public static Optional<DefaultDatumEnsemble<TemporalDatum>> asEnsemble(TemporalDatum datum)
    If the given object is a pseudo-datum for a temporal ensemble, returns that ensemble. This method is the converse of `asDatum(TemporalCRS)` and recognizes only the pseudo-datum created by this class of by `DefaultDatumEnsemble` static methods.
    Parameters:
      `datum` - the object which may be a pseudo-datum for an ensemble, or `null`.
    Returns:
      the given object cast to a datum ensemble if the cast is valid.

  - ### asEnsemble

    public static Optional<DefaultDatumEnsemble<EngineeringDatum>> asEnsemble(EngineeringDatum datum)
    If the given object is a pseudo-datum for a engineering ensemble, returns that ensemble. This method is the converse of `asDatum(EngineeringCRS)` and recognizes only the pseudo-datum created by this class of by `DefaultDatumEnsemble` static methods.
    Parameters:
      `datum` - the object which may be a pseudo-datum for an ensemble, or `null`.
    Returns:
      the given object cast to a datum ensemble if the cast is valid.

  - ### isLegacyDatum

    public static boolean isLegacyDatum(DefaultDatumEnsemble<?> ensemble, Datum datum, ComparisonMode mode)
    Returns whether a legacy definition of a datum may be considered as equivalent to the given datum ensemble. This is `true` if all reference frames (both the specified datum and the ensemble members) have the same properties (ellipsoid and prime meridians in the geodetic case), and the datum and datum ensemble either have a common identifier or an heuristic match of name.

    This method does not verify if the given datum is a member of the given ensemble. If the datum was a member, then the two objects would not be conceptually equal. We would rather have one object clearly identified as more accurate than the other.

    #### Use case

    This method is for interoperability between the old and new definitions of WGS 1984 (EPSG:4326). Before ISO 19111:2019, the datum ensemble concept did not existed in the OGC/ISO standards and WGS 1984 was defined as a `Datum`. In recent standards, WGS 1984 is defined as a `DatumEnsemble`, but the old definition is still encountered. For example, a CRS may have been parsed from a GML document, or from a WKT 1 string, or from a ISO 19162:2015 string, etc. This method can be used for detecting such situations. While WGS 1984 is the main use case, this method can be used for any datum in the same situation.
    Parameters:
      `ensemble` - the datum ensemble, or `null`.
      `datum` - the datum, or `null`.
      `mode` - the criterion for comparing ellipsoids and prime meridians.
    Returns:
      whether the two objects could be considered as equal if the concept of datum ensemble did not existed.

  - ### getEllipsoid

    public static Optional<Ellipsoid> getEllipsoid(CoordinateReferenceSystem crs)
    Returns the ellipsoid used by the given coordinate reference system. This method searches in the following locations:
    - If the given CRS is an instance of `SingleCRS` and its datum is a `GeodeticDatum`, then this method returns the datum ellipsoid.
    - Otherwise, if the given CRS is an instance of `SingleCRS`, is associated to a `DatumEnsemble`, and all members of the ensemble have equal (ignoring metadata) ellipsoid, then returns that ellipsoid.
    - Otherwise, if the given CRS is an instance of `CompoundCRS`, then this method searches recursively in each component until a geodetic reference frame is found.
    - Otherwise, this method returns an empty value.
    This method may return an empty value if the ellipsoid is not equal (ignoring metadata) for all members of the ensemble.
    Parameters:
      `crs` - the coordinate reference system for which to get the ellipsoid.
    Returns:
      the ellipsoid, or an empty value if none or not equivalent for all members of the ensemble.
    See Also:
      - `CRS​.getGeodeticReferenceFrame(CoordinateReferenceSystem)`

  - ### getPrimeMeridian

    public static Optional<PrimeMeridian> getPrimeMeridian(CoordinateReferenceSystem crs)
    Returns the prime meridian used by the given coordinate reference system. This method applies the same rules as `getEllipsoid(CoordinateReferenceSystem)`.
    Parameters:
      `crs` - the coordinate reference system for which to get the prime meridian.
    Returns:
      the prime meridian, or an empty value if none or not equivalent for all members of the ensemble.
    See Also:
      - `CRS​.getGeodeticReferenceFrame(CoordinateReferenceSystem)`
      - `CRS​.getGreenwichLongitude(GeodeticCRS)`

  - ### getAccuracy

    public static Optional<PositionalAccuracy> getAccuracy(IdentifiedObject object)
    If the given object is a datum ensemble or a CRS associated to a datum ensemble, returns its accuracy.
    Parameters:
      `object` - the object from which to get the ensemble accuracy, or `null`.
    Returns:
      the datum ensemble accuracy if the given object is a datum ensemble.
    Throws:
      `NullPointerException` - if the given object should provide an accuracy but didn't.
    See Also:
      - `CRS​.getLinearAccuracy(CoordinateOperation)`