org.apache.sis.geometry

## Class AbstractDirectPosition

- Object
- - AbstractDirectPosition

- All Implemented Interfaces:
    Position, DirectPosition
  Direct Known Subclasses:
    DirectPosition1D, GeneralDirectPosition

      public abstract class AbstractDirectPosition
      extends Object
      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 and Description
    --- | ---
    `protected` | `AbstractDirectPosition()` Constructs a direct position.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `equals(Object object)` Returns `true` if the specified object is also a `DirectPosition` with equal coordinate and equal CRS.
    `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.
    `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 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

    - #### 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 ordinate 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 ordinate values against the limits of the coordinate system axis for that dimension. If some ordinates are out of range, then there is a choice depending on the axis range meaning:
      - If `RangeMeaning​.EXACT` (typically latitudes ordinates), 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 ordinates), 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()`

    - #### 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 ordinate values at index 0, 1, 2, etc.:

          POINT(x₀ x₁ x₂ …)

      The string returned by this method can be parsed by the `GeneralDirectPosition` constructor.
      Overrides:
        `toString` in class `Object`
      Returns:
        This position as a `POINT` in Well Known Text (WKT) format.

    - #### hashCode

          public int hashCode()

      Returns a hash value for this coordinate. 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 coordinate 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.

Copyright © 2010–2017 The Apache Software Foundation. All rights reserved.