Package org.apache.sis.referencing.cs

## Class AbstractCS

- Object
- - FormattableObject
  - - AbstractIdentifiedObject
    - - AbstractCS

- All Implemented Interfaces:
    `Serializable`, `Deprecable`, `LenientComparable`, `CoordinateSystem`, `IdentifiedObject`
  Direct Known Subclasses:
    `DefaultAffineCS`, `DefaultCompoundCS`, `DefaultCylindricalCS`, `DefaultEllipsoidalCS`, `DefaultLinearCS`, `DefaultParametricCS`, `DefaultPolarCS`, `DefaultSphericalCS`, `DefaultTimeCS`, `DefaultUserDefinedCS`, `DefaultVerticalCS`

      public class AbstractCS
      extends AbstractIdentifiedObject
      implements CoordinateSystem

  The set of coordinate system axes that spans a given coordinate space. The type of the coordinate system implies the set of mathematical rules for calculating geometric properties like angles, distances and surfaces.

  This class is conceptually abstract, even if it is technically possible to instantiate it. Typical applications should create instances of the most specific subclass with `Default` prefix instead. An exception to this rule may occurs when it is not possible to identify the exact type. For example it is not possible to infer the exact coordinate system from Well Known Text (WKT) version 1 in some cases (e.g. in a `LOCAL_CS` element). In such exceptional situation, a plain `AbstractCS` object may be instantiated.

  Immutability and thread safety
  This base class is immutable and thus thread-safe if the property values (not necessarily the map itself) and the `CoordinateSystemAxis` instances given to the constructor are also immutable. Most SIS subclasses and related classes are immutable under similar conditions. This means that unless otherwise noted in the javadoc, `CoordinateSystem` instances created using only SIS factories and static constants can be shared by many objects and passed between threads without synchronization.
  Since:
    0.4
  See Also:
    `DefaultCoordinateSystemAxis`, `AbstractCRS`, 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`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor | Description
    --- | --- | ---
    `` | `AbstractCS​(Map<String,​?> properties, CoordinateSystemAxis... axes)` | Constructs a coordinate system from a set of properties and a sequence of axes.
    `protected` | `AbstractCS​(CoordinateSystem cs)` | Creates a new coordinate system with the same values than the specified one.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static AbstractCS` | `castOrCopy​(CoordinateSystem object)` | Returns a SIS coordinate system implementation with the values of the given arbitrary implementation.
    `protected long` | `computeHashCode()` | Invoked by `hashCode()` for computing the hash code when first needed.
    `boolean` | `equals​(Object object, ComparisonMode mode)` | Compares the specified object with this coordinate system for equality.
    `AbstractCS` | `forConvention​(AxesConvention convention)` | Returns a coordinate system equivalent to this one but with axes rearranged according the given convention.
    `protected String` | `formatTo​(Formatter formatter)` | Formats the inner part of the Well Known Text (WKT) representation of this coordinate system.
    `CoordinateSystemAxis` | `getAxis​(int dimension)` | Returns the axis for this coordinate system at the specified dimension.
    `int` | `getDimension()` | Returns the number of dimensions of this coordinate system.
    `Class<? extends CoordinateSystem>` | `getInterface()` | Returns the GeoAPI interface implemented by this class.

    - ### Methods inherited from class AbstractIdentifiedObject

      `castOrCopy, equals, 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`

- - ### Constructor Detail

    - #### AbstractCS

          public AbstractCS​(Map<String,​?> properties,
                            CoordinateSystemAxis... axes)

      Constructs a coordinate system from a set of properties and a sequence of axes. The properties map is given unchanged to 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()`

      Parameters:
        `properties` - the properties to be given to the identified object.
        `axes` - the sequence of axes.

    - #### AbstractCS

          protected AbstractCS​(CoordinateSystem cs)

      Creates a new coordinate 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:
        `cs` - the coordinate system to copy.
      See Also:
        `castOrCopy(CoordinateSystem)`

  - ### Method Detail

    - #### castOrCopy

          public static AbstractCS castOrCopy​(CoordinateSystem object)

      Returns a SIS coordinate system implementation with the values of the given arbitrary implementation. This method performs the first applicable action in the following choices:
      - If the given object is `null`, then this method returns `null`.
      - Otherwise if the given object is an instance of `AffineCS`, `CartesianCS`, `SphericalCS`, `EllipsoidalCS`, `CylindricalCS`, `PolarCS`, `LinearCS`, `VerticalCS`, `TimeCS` or `UserDefinedCS`, then this method delegates to the `castOrCopy(…)` method of the corresponding SIS subclass. Note that if the given object implements more than one of the above-cited interfaces, then the `castOrCopy(…)` method to be used is unspecified.
      - Otherwise if the given object is already an instance of `AbstractCS`, then it is returned unchanged.
      - Otherwise a new `AbstractCS` instance is created using the copy constructor and returned. Note that this is a shallow copy operation, since the other properties contained in the given object are not recursively copied.
      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 CoordinateSystem> getInterface()

      Returns the GeoAPI interface implemented by this class. The default implementation returns `CoordinateSystem​.class`. Subclasses implementing a more specific GeoAPI interface shall override this method.
      Overrides:
        `getInterface` in class `AbstractIdentifiedObject`
      Returns:
        the coordinate system interface implemented by this class.

    - #### getDimension

          public final int getDimension()

      Returns the number of dimensions of this coordinate system. This is the number of axes given at construction time.
      Specified by:
        `getDimension` in interface `CoordinateSystem`
      Returns:
        the number of dimensions of this coordinate system.

    - #### getAxis

          public final CoordinateSystemAxis getAxis​(int dimension)
                                             throws IndexOutOfBoundsException

      Returns the axis for this coordinate system at the specified dimension.
      Specified by:
        `getAxis` in interface `CoordinateSystem`
      Parameters:
        `dimension` - the zero based index of axis.
      Returns:
        the axis at the specified dimension.
      Throws:
        `IndexOutOfBoundsException` - if `dimension` is out of bounds.

    - #### forConvention

          public AbstractCS forConvention​(AxesConvention convention)

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

    - #### equals

          public boolean equals​(Object object,
                                ComparisonMode mode)

      Compares the specified object with this coordinate system for equality.
      Specified by:
        `equals` in interface `LenientComparable`
      Overrides:
        `equals` in class `AbstractIdentifiedObject`
      Parameters:
        `object` - the object to compare to `this`.
        `mode` - `STRICT` for performing a strict comparison, or `IGNORE_METADATA` for comparing only properties relevant to coordinate transformations.
      Returns:
        `true` if both objects are equal.
      See Also:
        `AbstractIdentifiedObject​.computeHashCode()`, `Utilities​.deepEquals(Object, Object, ComparisonMode)`

    - #### computeHashCode

          protected long computeHashCode()

      Invoked by `hashCode()` for computing the hash code when first needed. See `AbstractIdentifiedObject​.computeHashCode()` for more information.
      Overrides:
        `computeHashCode` in class `AbstractIdentifiedObject`
      Returns:
        the hash code value. This value may change in any future Apache SIS version.

    - #### formatTo

          protected String formatTo​(Formatter formatter)

      Formats the inner part of the Well Known Text (WKT) representation of this coordinate system. This method does not format the axes, because they shall appear outside the `CS[…]` element for historical reasons. Axes shall be formatted by the enclosing element (usually an `AbstractCRS`).
      Example: Well-Known Text of a two-dimensional `EllipsoidalCS` having (φ,λ) axes in a unit defined by the enclosing CRS (usually degrees).

      >     CS[ellipsoidal, 2],
      >     Axis["latitude", north],
      >     Axis["longitude", east]

      Compatibility note: `CS` is defined in the WKT 2 specification only.
      Overrides:
        `formatTo` in class `AbstractIdentifiedObject`
      Parameters:
        `formatter` - the formatter where to format the inner content of this WKT element.
      Returns:
        `"CS"`.
      See Also:
        WKT 2 specification §7.5