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

    All Methods Static Methods Instance Methods Concrete Methods
    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.
    `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.
    `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

      `getCoordinateReferenceSystem, getDimension, getOrdinate, setOrdinate`

- - ### Constructor Detail

    - #### AbstractDirectPosition

          protected AbstractDirectPosition()

      Constructs a direct position.

  - ### Method Detail

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

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

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