# Class DefaultDatumEnsemble<D extends Datum>

Object
FormattableObject
AbstractIdentifiedObject
DefaultDatumEnsemble<D>

Type Parameters:
  `D` - the type of datum members contained in this ensemble.

All Implemented Interfaces:
  `Serializable, Formattable, Deprecable, LenientComparable, Printable, Datum, IdentifiedObject`

public class DefaultDatumEnsemble<D extends Datum> extends AbstractIdentifiedObject implements Datum
Collection of datums which for low accuracy requirements may be considered to be insignificantly different from each other. Coordinate transformations between different members of an ensemble can be omitted if the ensemble accuracy is sufficient.

## Ensemble viewed as a datum

While a `DatumEnsemble` is theoretically not a `Datum`, it is sometime convenient to handle the ensemble as if it was a datum. Therefore, Apache SIS implementation of `DatumEnsemble` implements also the `Datum` interface. This is a non-standard approach for making easier to handle `Datum` and `DatumEnsemble` with the same code. A similar approach is used in the EPSG database, which stores ensembles in the same table as the datums.

It is illegal to use this double inheritance for returning a `DatumEnsemble` from `SingleCRS​.getDatum()`, or for creating a `DatumEnsemble` containing a nested `DatumEnsemble`. The Apache SIS constructors verify these constraints. For getting a single object which may be a datum or an ensemble, see the `DatumOrEnsemble` static methods.

Since:
  1.5
See Also:
  - Serialized Form

- ## Field Summary

  ### Fields inherited from class AbstractIdentifiedObject

  `DEPRECATED_KEY, DOMAINS_KEY, LOCALE_KEY`

  ### Fields inherited from interface Datum

  `ANCHOR_POINT_KEY, DOMAIN_OF_VALIDITY_KEY, REALIZATION_EPOCH_KEY, SCOPE_KEY`

  ### Fields inherited from interface IdentifiedObject

  `ALIAS_KEY, IDENTIFIERS_KEY, NAME_KEY, REMARKS_KEY`

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `DefaultDatumEnsemble(Map<String,?> properties, Collection<? extends D> members, PositionalAccuracy accuracy, Class<D> memberType)`
  Creates a datum ensemble from the given properties.
  `protected`
  `DefaultDatumEnsemble(DefaultDatumEnsemble<? extends D> ensemble, Class<D> memberType)`
  Creates a new ensemble with the same values as the specified one.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `<N extends Datum>
  DefaultDatumEnsemble<N>`
  `cast(Class<N> memberType)`
  Returns this datum ensemble as a collection of datum of the given type.
  `static <D extends Datum>
  DefaultDatumEnsemble<D>`
  `create(Map<String,?> properties, Class<D> memberType, Collection<? extends D> members, PositionalAccuracy accuracy)`
  Creates a datum ensemble from the given properties.
  `InternationalString`
  `getAnchorPoint()`
  Returns an anchor point which is common to all members of the datum ensemble.
  `Extent`
  `getDomainOfValidity()`
  Returns a domain of validity which is common to all members of the datum ensemble.
  `PositionalAccuracy`
  `getEnsembleAccuracy()`
  Returns the inaccuracy introduced through use of this ensemble.
  `double`
  `getLinearAccuracy()`
  Returns an estimation of positional accuracy in metres, or `NaN` if unknown.
  `final Collection<D>`
  `getMembers()`
  Returns the datum or reference frames which are members of this ensemble.
  `Date`
  `getRealizationEpoch()`
  Returns a realization epoch which is common to all members of the datum ensemble.
  `InternationalString`
  `getScope()`
  Returns a scope which is common to all members of the datum ensemble.
  `boolean`
  `isHeuristicMatchForName(String name)`
  Returns `true` if either the primary name or at least one alias matches the given string according heuristic rules.

  ### Methods inherited from class AbstractIdentifiedObject

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

  ### 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

  - ### DefaultDatumEnsemble

    protected DefaultDatumEnsemble(Map<String,?> properties, Collection<? extends D> members, PositionalAccuracy accuracy, Class<D> memberType)
    Creates a datum ensemble from the given properties. The properties given in argument follow the same rules as for the super-class constructor.

    Recognized properties (non exhaustive list)
    Property name | Value type | Returned by
    --- | --- | ---
    "name" | invalid reference
        Identifier
    or `String` | `AbstractIdentifiedObject.getName()`
    "alias" | invalid reference
        GenericName
    or `CharSequence` (optionally as array) | `AbstractIdentifiedObject.getAlias()`
    "identifiers" | invalid reference
        Identifier
    (optionally as array) | `AbstractIdentifiedObject.getIdentifiers()`
    `"domains"` | invalid reference
        org​.opengis​.referencing​.ObjectDomain
    (optionally as array) | `AbstractIdentifiedObject.getDomains()`
    "remarks" | `InternationalString` or `String` | `AbstractIdentifiedObject.getRemarks()`

    Parameters:
      `properties` - the properties to be given to the identified object.
      `members` - datum or reference frames which are members of this ensemble.
      `accuracy` - inaccuracy introduced through use of this ensemble (mandatory).
      `memberType` - the base type of datum members contained in this ensemble.
    Throws:
      `ClassCastException` - if a member is not an instance of `memberType`.
      `IllegalArgumentException` - if a member is an instance of `DatumEnsemble`, of if at least two different conventional reference systems are found.
    See Also:
      - `create(Map, Class, Collection, PositionalAccuracy)`

  - ### DefaultDatumEnsemble

    protected DefaultDatumEnsemble(DefaultDatumEnsemble<? extends D> ensemble, Class<D> memberType)
    Creates a new ensemble with the same values as 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:
      `ensemble` - the ensemble to copy.
      `memberType` - the base type of datum members contained in this ensemble.
    Throws:
      `ClassCastException` - if a member is not an instance of `memberType`.
      `IllegalArgumentException` - if a member is an instance of `DatumEnsemble`, of if at least two different conventional reference systems are found.

- ## Method Details

  - ### create

    public static <D extends Datum> DefaultDatumEnsemble<D> create(Map<String,?> properties, Class<D> memberType, Collection<? extends D> members, PositionalAccuracy accuracy)
    Creates a datum ensemble from the given properties. The content of the `properties` map is described in the constructor. The returned ensemble may implement the `GeodeticDatum`, `VerticalDatum`, `TemporalDatum`, or `EngineeringDatum` interface if all members are instances of the same interface.
    Type Parameters:
      `D` - the type of datum members contained in the ensemble to create.
    Parameters:
      `properties` - the properties to be given to the identified object.
      `memberType` - type of members, or `null` for automatic.
      `members` - datum or reference frames which are members of this ensemble.
      `accuracy` - inaccuracy introduced through use of this ensemble (mandatory).
    Returns:
      the datum ensemble.
    Throws:
      `IllegalArgumentException` - if a member is an instance of `DatumEnsemble`, of if at least two different conventional reference systems are found.

  - ### cast

    public <N extends Datum> DefaultDatumEnsemble<N> cast(Class<N> memberType)
    Returns this datum ensemble as a collection of datum of the given type. This method casts the datum members, it does not copy or rewrite them. However, the returned `DatumEnsemble` may be a different instance.
    Type Parameters:
      `N` - compile-time value of `memberType`.
    Parameters:
      `memberType` - the new desired type of datum members.
    Returns:
      an ensemble of datum of the given type.
    Throws:
      `ClassCastException` - if at least one member is not an instance of the specified type.

  - ### getMembers

    public final Collection<D> getMembers()
    Returns the datum or reference frames which are members of this ensemble. The returned list is immutable.
    Returns:
      datum or reference frames which are members of this ensemble.

  - ### getEnsembleAccuracy

    public PositionalAccuracy getEnsembleAccuracy()
    Returns the inaccuracy introduced through use of this ensemble.
    Returns:
      inaccuracy introduced through use of this ensemble.

  - ### getLinearAccuracy

    public double getLinearAccuracy()
    Returns an estimation of positional accuracy in metres, or `NaN` if unknown. If at least one quantitative result is found with a linear unit, then returns the largest result value converted to metres.
    Returns:
      the accuracy estimation (always in meters), or NaN if unknown.
    See Also:
      - `CRS​.getLinearAccuracy(CoordinateOperation)`

  - ### getAnchorPoint

    public InternationalString getAnchorPoint()
    Returns an anchor point which is common to all members of the datum ensemble. If the value is not the same for all members, or if at least one member returned null, then this method returns null.
    Specified by:
      `getAnchorPoint` in interface `Datum`
    Returns:
      the common anchor point, or null if there is no common value.

  - ### getRealizationEpoch

    public Date getRealizationEpoch()
    Returns a realization epoch which is common to all members of the datum ensemble. If the value is not the same for all members, or if at least one member returned null, then this method returns null.
    Specified by:
      `getRealizationEpoch` in interface `Datum`
    Returns:
      the common realization epoch, null if there is no common value.

  - ### getDomainOfValidity

    public Extent getDomainOfValidity()
    Returns a domain of validity which is common to all members of the datum ensemble. If the value is not the same for all members, or if at least one member returned null, then this method returns null.
    Specified by:
      `getDomainOfValidity` in interface `Datum`
    Returns:
      the common domain of validity, or null if there is no common value.

  - ### getScope

    public InternationalString getScope()
    Returns a scope which is common to all members of the datum ensemble. If the value is not the same for all members, or if at least one member returned null, then this method returns null.
    Specified by:
      `getScope` in interface `Datum`
    Returns:
      the common scope, or null if there is no common value.

  - ### isHeuristicMatchForName

    public boolean isHeuristicMatchForName(String name)
    Returns `true` if either the primary name or at least one alias matches the given string according heuristic rules. This method performs the comparison documented in the datum-class.
    Overrides:
      `isHeuristicMatchForName` in class `AbstractIdentifiedObject`
    Parameters:
      `name` - the name to compare.
    Returns:
      `true` if the primary name or at least one alias matches the specified `name`.
    See Also:
      - `IdentifiedObjects​.isHeuristicMatchForName(IdentifiedObject, String)`
      - `Characters​.Filter​.LETTERS_AND_DIGITS`