Package org.apache.sis.referencing.crs

# Class DefaultTemporalCRS

Object
FormattableObject
AbstractIdentifiedObject
AbstractReferenceSystem
AbstractCRS
DefaultTemporalCRS

All Implemented Interfaces:
  `Serializable`, `Formattable`, `Deprecable`, `LenientComparable`, `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

Defined in the `sis-referencing` module

- ## Field Summary

  ### Fields inherited from class AbstractIdentifiedObject

  `DEPRECATED_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, TimeCS cs)`
  Creates a coordinate reference system from the given properties, datum and coordinate system.
  `protected`
  `DefaultTemporalCRS(TemporalCRS crs)`
  Constructs a new coordinate reference system with the same values than 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 than the given arbitrary implementation.
  `DefaultTemporalCRS`
  `forConvention(AxesConvention convention)`
  Returns a coordinate reference system 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 datum.
  `Class<? extends TemporalCRS>`
  `getInterface()`
  Returns the GeoAPI interface implemented by this class.
  `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.
  `Instant`
  `toInstant(double value)`
  Converts the given value into an instant object.
  `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, computeHashCode, equals`

  ### Methods inherited from class AbstractReferenceSystem

  `getDomainOfValidity, getScope`

  ### Methods inherited from class AbstractIdentifiedObject

  `castOrCopy, equals, formatTo, getAlias, getDescription, 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, TimeCS cs)
    Creates a coordinate reference system from the given properties, datum and coordinate system. The properties given in argument follow the same rules than 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()`
    "remarks" | `InternationalString` or `String` | `AbstractIdentifiedObject.getRemarks()`
    "domainOfValidity" | `Extent` | `AbstractReferenceSystem.getDomainOfValidity()`
    "scope" | `InternationalString` or `String` | `AbstractReferenceSystem.getScope()`

    Parameters:
      `properties` - the properties to be given to the coordinate reference system.
      `datum` - the datum.
      `cs` - the coordinate system.
    See Also:
      - `GeodeticObjectFactory​.createTemporalCRS(Map, TemporalDatum, TimeCS)`

  - ### DefaultTemporalCRS

    protected DefaultTemporalCRS(TemporalCRS crs)
    Constructs a new coordinate reference system with the same values than 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 than 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.
    Overrides:
      `getInterface` in class `AbstractCRS`
    Returns:
      `TemporalCRS​.class` or a user-defined sub-interface.

  - ### getDatum

    public TemporalDatum getDatum()
    Returns the datum.
    Specified by:
      `getDatum` in interface `SingleCRS`
    Specified by:
      `getDatum` in interface `TemporalCRS`
    Returns:
      the datum.

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

  - ### forConvention

    public DefaultTemporalCRS forConvention(AxesConvention convention)
    Returns a coordinate reference system 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.

  - ### 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()`.

  - ### 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:
      - WKT 2 specification §14