# Class DefaultTemporalCRS

Object
FormattableObject
AbstractIdentifiedObject
AbstractReferenceSystem
AbstractCRS
DefaultTemporalCRS

All Implemented Interfaces:
  `Serializable`, `Formattable`, `Deprecable`, `LenientComparable`, `Printable`, `CoordinateReferenceSystem`, `SingleCRS`, `TemporalCRS`, `IdentifiedObject`, `ReferenceSystem`

public class DefaultTemporalCRS extends AbstractCRS implements TemporalCRS
A 1-dimensional coordinate reference system used for the recording of time. The Apache SIS implementation provides the following methods in addition to the OGC/ISO properties:

- `toInstant(double)` for converting a temporal position to a `Date`.
- `toValue(Instant)` for converting a `Instant` to a temporal position.

Used with datum type: Temporal.
Used with coordinate system type: Time.

## Immutability and thread safety

This class is immutable and thus thread-safe if the property values (not necessarily the map itself), the coordinate system and the datum instances given to the constructor are also immutable. Unless otherwise noted in the javadoc, this condition holds if all components were created using only SIS factories and static constants.

Since:
  0.4
See Also:
  - `DefaultTemporalDatum`
  - `DefaultTimeCS`
  - `GeodeticAuthorityFactory​.createTemporalCRS(String)`
  - Serialized Form

- ## Field Summary

  ### Fields inherited from class AbstractIdentifiedObject

  `DEPRECATED_KEY, DOMAINS_KEY, LOCALE_KEY`

  ### Fields inherited from interface IdentifiedObject

  `ALIAS_KEY, IDENTIFIERS_KEY, NAME_KEY, REMARKS_KEY`

  ### Fields inherited from interface ReferenceSystem

  `DOMAIN_OF_VALIDITY_KEY, SCOPE_KEY`

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  ``
  `DefaultTemporalCRS(Map<String,?> properties, TemporalDatum datum, DefaultDatumEnsemble<TemporalDatum> ensemble, TimeCS cs)`
  Creates a coordinate reference system from the given properties, datum and coordinate system.
  ``
  `DefaultTemporalCRS(Map<String,?> properties, TemporalDatum datum, TimeCS cs)`
  Deprecated, for removal: This API element is subject to removal in a future version.
  A `DefaultDatumEnsemble` argument has been added.
  `protected`
  `DefaultTemporalCRS(TemporalCRS crs)`
  Constructs a new coordinate reference system with the same values as the specified one.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static DefaultTemporalCRS`
  `castOrCopy(TemporalCRS object)`
  Returns a SIS coordinate reference system implementation with the same values as the given arbitrary implementation.
  `DefaultTemporalCRS`
  `forConvention(AxesConvention convention)`
  Returns a CRS equivalent to this one but with axes rearranged according the given convention.
  `protected String`
  `formatTo(Formatter formatter)`
  Formats this CRS as a Well Known Text `TimeCRS[…]` element.
  `TimeCS`
  `getCoordinateSystem()`
  Returns the coordinate system.
  `TemporalDatum`
  `getDatum()`
  Returns the definition of the relationship of a temporal CRS to a time.
  `DefaultDatumEnsemble<TemporalDatum>`
  `getDatumEnsemble()`
  Returns a collection of datums which, for low accuracy requirements, may be considered to be insignificantly different from each other.
  `Class<? extends TemporalCRS>`
  `getInterface()`
  Returns the GeoAPI interface implemented by this class.
  `final Temporal`
  `getOrigin()`
  Returns the temporal origin which is indirectly (through a datum) associated to this CRS.
  `final Unit<Time>`
  `getUnit()`
  Returns the unit of measurement of temporal measurement in the coordinate reference system.
  `Date`
  `toDate(double value)`
  Converts the given value into a `Date` object.
  `Duration`
  `toDuration(double delta)`
  Converts the given value difference into a duration object.
  `Instant`
  `toInstant(double value)`
  Converts the given value into an instant object.
  `double`
  `toValue(Duration delta)`
  Converts the given duration into a difference of values in this axis unit.
  `double`
  `toValue(Instant time)`
  Converts the given instant into a value in this axis unit.
  `double`
  `toValue(Date time)`
  Converts the given date into a value in this axis unit.

  ### Methods inherited from class AbstractCRS

  `castOrCopy`

  ### Methods inherited from class AbstractReferenceSystem

  `getDomainOfValidity, getScope`

  ### Methods inherited from class AbstractIdentifiedObject

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

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

  ### Methods inherited from interface ReferenceSystem

  `getDomainOfValidity, getScope`

- ## Constructor Details

  - ### DefaultTemporalCRS

    public DefaultTemporalCRS(Map<String,?> properties, TemporalDatum datum, DefaultDatumEnsemble<TemporalDatum> ensemble, TimeCS cs)
    Creates a coordinate reference system from the given properties, datum and coordinate system. At least one of the `datum` and `ensemble` arguments shall be non-null. The properties given in argument follow the same rules as for the super-class constructor. The following table is a reminder of main (not all) properties:

    Recognized properties (non exhaustive list)
    Property name | Value type | Returned by
    --- | --- | ---
    "name" | `ReferenceIdentifier` or `String` | `AbstractIdentifiedObject.getName()`
    "alias" | `GenericName` or `CharSequence` (optionally as array) | `AbstractIdentifiedObject.getAlias()`
    "identifiers" | `ReferenceIdentifier` (optionally as array) | `AbstractIdentifiedObject.getIdentifiers()`
    "domains" | `DefaultObjectDomain` (optionally as array) | `AbstractIdentifiedObject.getDomains()`
    "remarks" | `InternationalString` or `String` | `AbstractIdentifiedObject.getRemarks()`

    Parameters:
      `properties` - the properties to be given to the coordinate reference system.
      `datum` - the datum, or `null` if the CRS is associated only to a datum ensemble.
      `ensemble` - collection of reference frames which for low accuracy requirements may be considered to be insignificantly different from each other, or `null` if there is no such ensemble.
      `cs` - the coordinate system.
    Since:
      1.5
    See Also:
      - `GeodeticObjectFactory​.createTemporalCRS(Map, TemporalDatum, DefaultDatumEnsemble, TimeCS)`

  - ### DefaultTemporalCRS

    @Deprecated(since="1.5", forRemoval=true) public DefaultTemporalCRS(Map<String,?> properties, TemporalDatum datum, TimeCS cs)
    Deprecated, for removal: This API element is subject to removal in a future version.
    A `DefaultDatumEnsemble` argument has been added.

  - ### DefaultTemporalCRS

    protected DefaultTemporalCRS(TemporalCRS crs)
    Constructs a new coordinate reference system 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:
      `crs` - the coordinate reference system to copy.
    See Also:
      - `castOrCopy(TemporalCRS)`

- ## Method Details

  - ### castOrCopy

    public static DefaultTemporalCRS castOrCopy(TemporalCRS object)
    Returns a SIS coordinate reference system implementation with the same values as the given arbitrary implementation. If the given object is `null`, then this method returns `null`. Otherwise if the given object is already a SIS implementation, then the given object is returned unchanged. Otherwise a new SIS implementation is created and initialized to the attribute values of the given object.
    Parameters:
      `object` - the object to get as a SIS implementation, or `null` if none.
    Returns:
      a SIS implementation containing the values of the given object (may be the given object itself), or `null` if the argument was null.

  - ### getInterface

    public Class<? extends TemporalCRS> getInterface()
    Returns the GeoAPI interface implemented by this class. The SIS implementation returns `TemporalCRS​.class`.

    #### Note for implementers

    Subclasses usually do not need to override this method since GeoAPI does not define `TemporalCRS` sub-interface. Overriding possibility is left mostly for implementers who wish to extend GeoAPI with their own set of interfaces.
    Returns:
      `TemporalCRS​.class` or a user-defined sub-interface.

  - ### getDatum

    public TemporalDatum getDatum()
    Returns the definition of the relationship of a temporal CRS to a time. This property may be null if this CRS is related to an object identified only by a datum ensemble.
    Specified by:
      `getDatum` in interface `SingleCRS`
    Specified by:
      `getDatum` in interface `TemporalCRS`
    Returns:
      the temporal datum, or `null` if this CRS is related to an object identified only by a datum ensemble.

  - ### getDatumEnsemble

    public DefaultDatumEnsemble<TemporalDatum> getDatumEnsemble()
    Returns a collection of datums which, for low accuracy requirements, may be considered to be insignificantly different from each other. This property may be null if this CRS is related to an object identified only by a single datum.
    Warning: in a future SIS version, the return type may be changed to the `org​.opengis​.referencing​.datum​.DatumEnsemble` interface. This change is pending GeoAPI revision.
    Returns:
      the datum ensemble, or `null` if this CRS is related to an object identified only by a single datum.
    Since:
      1.5

  - ### getCoordinateSystem

    public TimeCS getCoordinateSystem()
    Returns the coordinate system.
    Specified by:
      `getCoordinateSystem` in interface `CoordinateReferenceSystem`
    Specified by:
      `getCoordinateSystem` in interface `SingleCRS`
    Specified by:
      `getCoordinateSystem` in interface `TemporalCRS`
    Overrides:
      `getCoordinateSystem` in class `AbstractCRS`
    Returns:
      the coordinate system.

  - ### getUnit

    public final Unit<Time> getUnit()
    Returns the unit of measurement of temporal measurement in the coordinate reference system. This is a convenience method for `CoordinateSystemAxis​.getUnit()` on the unique axis of this coordinate reference system. The unit of measurement returned by this method is the unit of the value expected in argument by `toInstant(double)` and `toDate(double)`, and the unit of the value returned by `toValue(…)` methods.

    #### Implementation note

    This method is declared final and does not invoke overridden `getCoordinateSystem()` method because this `getUnit()` method is invoked indirectly by constructors. Another reason is that the overriding point is the `CoordinateSystemAxis​.getUnit()` method and we want to avoid introducing another overriding point that could be inconsistent with above method.
    Returns:
      the temporal unit of measurement of coordinates in this CRS.
    Since:
      1.0

  - ### getOrigin

    public final Temporal getOrigin()
    Returns the temporal origin which is indirectly (through a datum) associated to this CRS. If the datum is non-null, then this method returns the datum origin. Otherwise, if all members of the datum ensemble use the same origin, then this method returns that origin.
    Returns:
      the origin indirectly associated to this CRS.
    Throws:
      `NullPointerException` - if an origin, which are mandatory, is null.
      `GeodeticException` - if the origin is not the same for all members of the datum ensemble.
    Since:
      1.5

  - ### forConvention

    public DefaultTemporalCRS forConvention(AxesConvention convention)
    Returns a CRS equivalent to this one but with axes rearranged according the given convention. If this CRS is already compatible with the given convention, then this method returns `this`.
    Overrides:
      `forConvention` in class `AbstractCRS`
    Parameters:
      `convention` - the axes convention for which a coordinate reference system is desired.
    Returns:
      a coordinate reference system compatible with the given convention (may be `this`).
    See Also:
      - `AbstractCS​.forConvention(AxesConvention)`

  - ### toInstant

    public Instant toInstant(double value)
    Converts the given value into an instant object. If the given value is NaN or infinite, then this method returns `null`. This method is the converse of `toValue(Instant)`.
    Parameters:
      `value` - a value in this axis. Unit of measurement is given by `getUnit()`.
    Returns:
      the value as an instant, or `null` if the given value is NaN or infinite.
    Since:
      1.0

  - ### toDate

    public Date toDate(double value)
    Converts the given value into a `Date` object. If the given value is is NaN or infinite, then this method returns `null`. This method is the converse of `toValue(Date)`.

    This method is provided for interoperability with legacy `java​.util​.Date` object. New code should use `toInstant(double)` instead.

    Parameters:
      `value` - a value in this axis unit. Unit of measurement is given by `getUnit()`.
    Returns:
      the value as a date, or `null` if the given value is NaN or infinite.

  - ### toDuration

    public Duration toDuration(double delta)
    Converts the given value difference into a duration object. If the given value is NaN or infinite, or if the conversion is non-linear, then this method returns `null`. This method is the converse of `toValue(Duration)`.
    Parameters:
      `delta` - a difference of values in this axis. Unit of measurement is given by `getUnit()`.
    Returns:
      the value difference as a duration, or `null` if the duration cannot be computed.
    Since:
      1.3

  - ### toValue

    public double toValue(Instant time)
    Converts the given instant into a value in this axis unit. If the given instant is `null`, then this method returns `Double​.NaN`. This method is the converse of `toInstant(double)`.
    Parameters:
      `time` - the value as an instant, or `null`.
    Returns:
      the value in this axis unit, or `Double​.NaN` if the given instant is `null`. Unit of measurement is given by `getUnit()`.
    Since:
      1.0

  - ### toValue

    public double toValue(Date time)
    Converts the given date into a value in this axis unit. If the given time is `null`, then this method returns `Double​.NaN`. This method is the converse of `toDate(double)`.

    This method is provided for interoperability with legacy `java​.util​.Date` object. New code should use `toValue(Instant)` instead.

    Parameters:
      `time` - the value as a date, or `null`.
    Returns:
      the value in this axis unit, or `Double​.NaN` if the given time is `null`. Unit of measurement is given by `getUnit()`.

  - ### toValue

    public double toValue(Duration delta)
    Converts the given duration into a difference of values in this axis unit. If the given duration is `null`, or if the conversion is non-linear, then this method returns `Double​.NaN`. This method is the converse of `toDuration(double)`.
    Parameters:
      `delta` - the difference of values as a duration, or `null`.
    Returns:
      the value difference in this axis unit, or `Double​.NaN` if it cannot be computed. Unit of measurement is given by `getUnit()`.
    Since:
      1.3

  - ### formatTo

    protected String formatTo(Formatter formatter)
    Formats this CRS as a Well Known Text `TimeCRS[…]` element.

    #### Compatibility note

    `TimeCRS` is defined in the WKT 2 specification only.
    Overrides:
      `formatTo` in class `AbstractCRS`
    Parameters:
      `formatter` - the formatter where to format the inner content of this WKT element.
    Returns:
      `"TimeCRS"`.
    See Also:
      - `FormattableObject​.toWKT()`
      - `FormattableObject​.toString()`