Package org.apache.sis.geometry

# Class AbstractDirectPosition

Object
FormattableObject
AbstractDirectPosition

All Implemented Interfaces:
  `Position`, `DirectPosition`

Direct Known Subclasses:
  `DirectPosition1D`, `GeneralDirectPosition`

public abstract class AbstractDirectPosition extends FormattableObject implements DirectPosition
Default implementations of some `DirectPosition` methods, leaving the data storage to subclasses. A direct position holds the coordinates for a position within some coordinate reference system. This base class provides default implementations for `toString()`, `equals(Object)` and `hashCode()` methods.

This base class does not hold any state and does not implement the `Serializable` or `Cloneable` interfaces. The internal representation, and the choice to be cloneable or serializable, is left to subclasses.

Since:
  0.3

Defined in the `sis-referencing` module

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `AbstractDirectPosition()`
  Constructs a direct position.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static AbstractDirectPosition`
  `castOrCopy(DirectPosition position)`
  Returns the given position as an `AbstractDirectPosition` instance.
  `boolean`
  `equals(Object object)`
  Returns `true` if the specified object is also a `DirectPosition` with equal coordinates and equal CRS.
  `protected String`
  `formatTo(Formatter formatter)`
  Formats this position in the Well Known Text (WKT) format.
  `double[]`
  `getCoordinate()`
  Returns a sequence of numbers that hold the coordinate of this position in its reference system.
  `CoordinateReferenceSystem`
  `getCoordinateReferenceSystem()`
  Returns the coordinate reference system in which the coordinate tuple is given.
  `final DirectPosition`
  `getDirectPosition()`
  Returns always `this`, the direct position for this position.
  `int`
  `hashCode()`
  Returns a hash value for this coordinate tuple.
  `boolean`
  `normalize()`
  Ensures that the position is contained in the coordinate system domain.
  `void`
  `setLocation(DirectPosition position)`
  Sets this direct position to the given position.
  `void`
  `setOrdinate(int dimension, double value)`
  Sets the coordinate value along the specified dimension.
  `String`
  `toString()`
  Formats this position in the Well Known Text (WKT) format.

  ### Methods inherited from class FormattableObject

  `print, toString, toWKT`

  ### Methods inherited from class Object

  `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

  ### Methods inherited from interface DirectPosition

  `getDimension, getOrdinate`

- ## Constructor Details

  - ### AbstractDirectPosition

    protected AbstractDirectPosition()
    Constructs a direct position.

- ## Method Details

  - ### castOrCopy

    public static AbstractDirectPosition castOrCopy(DirectPosition position)
    Returns the given position as an `AbstractDirectPosition` instance. If the given position is already an instance of `AbstractDirectPosition`, then it is returned unchanged. Otherwise the coordinate values and the CRS of the given position are copied in a new position.
    Parameters:
      `position` - the position to cast, or `null`.
    Returns:
      the values of the given position as an `AbstractDirectPosition` instance.
    Since:
      1.0

  - ### getDirectPosition

    public final DirectPosition getDirectPosition()
    Returns always `this`, the direct position for this position.
    Specified by:
      `getDirectPosition` in interface `Position`
    Returns:
      `this`.

  - ### getCoordinateReferenceSystem

    public CoordinateReferenceSystem getCoordinateReferenceSystem()
    Returns the coordinate reference system in which the coordinate tuple is given. May be `null` if this particular `DirectPosition` is included in a larger object with such a reference to a coordinate reference system.

    The default implementation returns `null`. Subclasses should override this method if the CRS can be provided.

    Specified by:
      `getCoordinateReferenceSystem` in interface `DirectPosition`
    Returns:
      the coordinate reference system, or `null`.

  - ### getCoordinate

    public double[] getCoordinate()
    Returns a sequence of numbers that hold the coordinate of this position in its reference system.
    Specified by:
      `getCoordinate` in interface `DirectPosition`
    Returns:
      the coordinates.

  - ### setOrdinate

    public void setOrdinate(int dimension, double value)
    Sets the coordinate value along the specified dimension.

    The default implementation throws `UnsupportedOperationException`. Subclasses need to override this method if this direct position is mutable.

    Specified by:
      `setOrdinate` in interface `DirectPosition`
    Parameters:
      `dimension` - the dimension for the coordinate of interest.
      `value` - the coordinate value of interest.
    Throws:
      `IndexOutOfBoundsException` - if the given index is negative or is equals or greater than the position dimension.
      `UnsupportedOperationException` - if this direct position is immutable.

  - ### setLocation

    public void setLocation(DirectPosition position) throws MismatchedDimensionException, MismatchedReferenceSystemException
    Sets this direct position to the given position. If the given position is `null`, then all coordinate values are set to `NaN`.

    If this position and the given position have a non-null CRS, then the default implementation requires the CRS to be equals (ignoring metadata), otherwise a `MismatchedReferenceSystemException` is thrown. However subclass may choose to assign the CRS of this position to the CRS of the given position.

    Parameters:
      `position` - the new position, or `null`.
    Throws:
      `MismatchedDimensionException` - if the given position doesn't have the expected dimension.
      `MismatchedReferenceSystemException` - if the given position doesn't use the expected CRS.

  - ### normalize

    public boolean normalize()
    Ensures that the position is contained in the coordinate system domain. For each dimension, this method compares the coordinate values against the limits of the coordinate system axis for that dimension. If some coordinates are out of range, then there is a choice depending on the axis range meaning:
    - If `RangeMeaning​.EXACT` (typically latitudes coordinates), then values greater than the axis maximal value are replaced by the axis maximum, and values smaller than the axis minimal value are replaced by the axis minimum.
    - If `RangeMeaning​.WRAPAROUND` (typically longitudes coordinates), then a multiple of the axis range (e.g. 360° for longitudes) is added or subtracted.
    Returns:
      `true` if this position has been modified as a result of this method call, or `false` if no change has been done.
    See Also:
      - `GeneralEnvelope​.normalize()`

  - ### formatTo

    protected String formatTo(Formatter formatter)
    Formats this position in the Well Known Text (WKT) format. The format is like below, where `x₀`, `x₁`, `x₂`, etc. are the coordinate values at index 0, 1, 2, etc.:

    >     POINT[x₀ x₁ x₂ …]

    If the coordinate reference system is geodetic or projected, then coordinate values are formatted with a precision equivalent to one centimetre on Earth (the actual number of fraction digits is adjusted for the axis unit of measurement and the planet size if different than Earth).
    Specified by:
      `formatTo` in class `FormattableObject`
    Parameters:
      `formatter` - the formatter where to format the inner content of this point.
    Returns:
      the WKT keyword, which is `"Point"` for this element.
    Since:
      1.0
    See Also:
      - `FormattableObject​.toWKT()`
      - `FormattableObject​.toString()`

  - ### toString

    public String toString()
    Formats this position in the Well Known Text (WKT) format. The returned string is like below, where `x₀`, `x₁`, `x₂`, etc. are the coordinate values at index 0, 1, 2, etc.:

    >     POINT(x₀ x₁ x₂ …)

    This method formats the numbers as with `Double​.toString(double)` (i.e. without fixed number of fraction digits). The string returned by this method can be parsed by the `GeneralDirectPosition` constructor.
    Overrides:
      `toString` in class `FormattableObject`
    Returns:
      this position as a `POINT` in Well Known Text (WKT) format.

  - ### hashCode

    public int hashCode()
    Returns a hash value for this coordinate tuple. This method returns a value compliant with the contract documented in the `DirectPosition​.hashCode()` javadoc. Consequently, it should be possible to mix different `DirectPosition` implementations in the same hash map.
    Specified by:
      `hashCode` in interface `DirectPosition`
    Overrides:
      `hashCode` in class `Object`
    Returns:
      a hash code value for this position.

  - ### equals

    public boolean equals(Object object)
    Returns `true` if the specified object is also a `DirectPosition` with equal coordinates and equal CRS. This method performs the comparison as documented in the `DirectPosition​.equals(Object)` javadoc. In particular, the given object is not required to be of the same implementation class. Consequently, it should be possible to mix different `DirectPosition` implementations in the same hash map.
    Specified by:
      `equals` in interface `DirectPosition`
    Overrides:
      `equals` in class `Object`
    Parameters:
      `object` - the object to compare with this position.
    Returns:
      `true` if the given object is equal to this position.