uk.ac.starlink.table

## Interface Domain<M extends DomainMapper>

- All Known Implementing Classes:
    TimeDomain

      public interface Domain<M extends DomainMapper>

  Common value domain. An instance of this class represents some class of externally representable values that can in some sense be treated internally in the same way, but which may have various different external representations. It is used in conjunction with instances of the `DomainMapper` interface, provided by the table input handler or the user, to untangle different possible representations of physical values in input data.

  See the available instances of this interface such as `TimeDomain` for better understanding of how it works.

  Since:
    14 Apr 2020
  See Also:
    `DomainMapper`

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.lang.String` | `getDomainName()` Returns the name of this domain.
    `M[]` | `getMappers()` Returns a list of all mappers known to map values to this domain.
    `M` | `getPossibleMapper(ValueInfo info)` Returns a typed DomainMapper that can be used for data described by the given metadata object.
    `M` | `getProbableMapper(ValueInfo info)` Returns a typed DomainMapper that is likely to be appropriate for data described by the given metadata object.

- - ### Method Detail

    - #### getDomainName

          java.lang.String getDomainName()

      Returns the name of this domain.
      Returns:
        domain name

    - #### getMappers

          M[] getMappers()

      Returns a list of all mappers known to map values to this domain. This is not necessarily exhaustive, and may in particular not include mappers specific to certain input file formats, but it can be offered to users as a list of options for mapping to this domain where no other option is obvious.
      Returns:
        list of generic mappers to this domain

    - #### getProbableMapper

          M getProbableMapper(ValueInfo info)

      Returns a typed DomainMapper that is likely to be appropriate for data described by the given metadata object.

      In general, implementations of this method will first check the `ValueInfo.getDomainMappers()` method. If it is doubtful how to map from the given info to this domain, null should be returned.

      Parameters:
        `info` - metadata describing data to be mapped
      Returns:
        reliable guess at a suitable mapper

    - #### getPossibleMapper

          M getPossibleMapper(ValueInfo info)

      Returns a typed DomainMapper that can be used for data described by the given metadata object. If some reasonable way to make the conversion exists, an appropriate value should be returned, but it's quite possible the conversion will be incorrect. If there is no known possible or plausible mapper, null should be returned.

      If the result of `getProbableMapper(uk.ac.starlink.table.ValueInfo)` is non-null, then this method must also return non-null, but this method is not required to return the same value as `getProbableMapper`.

      Parameters:
        `info` - metadata describing data to be mapped
      Returns:
        best-efforts guess at a suitable mapper