Class AbstractCS

All Implemented Interfaces:
Serializable, Formattable, Deprecable, LenientComparable, org.opengis.referencing.cs.CoordinateSystem, org.opengis.referencing.IdentifiedObject
Direct Known Subclasses:
DefaultAffineCS, DefaultCompoundCS, DefaultCylindricalCS, DefaultEllipsoidalCS, DefaultLinearCS, DefaultParametricCS, DefaultPolarCS, DefaultSphericalCS, DefaultTimeCS, DefaultUserDefinedCS, DefaultVerticalCS

public class AbstractCS extends AbstractIdentifiedObject implements org.opengis.referencing.cs.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
Version:
1.0
See Also:
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private org.opengis.referencing.cs.CoordinateSystemAxis[]
    The sequence of axes for this coordinate system.
    Other coordinate systems derived from this coordinate systems for other axes conventions.
    private static final org.opengis.referencing.cs.CoordinateSystemAxis[]
    An empty array of axes, used only for JAXB.
    (package private) static final int
    (package private) static final int
    private static final long
    Serial number for inter-operability with different versions.
    (package private) static final int

    Fields inherited from class org.apache.sis.referencing.AbstractIdentifiedObject

    DEPRECATED_KEY, LOCALE_KEY

    Fields inherited from interface org.opengis.referencing.IdentifiedObject

    ALIAS_KEY, IDENTIFIERS_KEY, NAME_KEY, REMARKS_KEY
  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    (package private)
    Constructs a new object in which every attributes are set to a null or empty value.
     
    AbstractCS(Map<String,?> properties, org.opengis.referencing.cs.CoordinateSystemAxis... axes)
    Constructs a coordinate system from a set of properties and a sequence of axes.
    protected
    AbstractCS(org.opengis.referencing.cs.CoordinateSystem cs)
    Creates a new coordinate system with the same values than the specified one.
  • Method Summary

    Modifier and Type
    Method
    Description
    static AbstractCS
    castOrCopy(org.opengis.referencing.cs.CoordinateSystem object)
    Returns a SIS coordinate system implementation with the values of the given arbitrary implementation.
    protected long
    Invoked by hashCode() for computing the hash code when first needed.
    (package private) AbstractCS
    createForAxes(Map<String,?> properties, org.opengis.referencing.cs.CoordinateSystemAxis[] axes)
    Returns a coordinate system usually of the same type than this CS but with different axes.
    boolean
    equals(Object object, ComparisonMode mode)
    Compares the specified object with this coordinate system for equality.
    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.
    private static org.opengis.referencing.cs.CoordinateSystemAxis[]
    getAxes(org.opengis.referencing.cs.CoordinateSystem cs)
    Returns the axes of the given coordinate system.
    private org.opengis.referencing.cs.CoordinateSystemAxis[]
    Invoked by JAXB at marshalling time.
    final org.opengis.referencing.cs.CoordinateSystemAxis
    getAxis(int dimension)
    Returns the axis for this coordinate system at the specified dimension.
    final int
    Returns the number of dimensions of this coordinate system.
    Class<? extends org.opengis.referencing.cs.CoordinateSystem>
    Returns the GeoAPI interface implemented by this class.
    private AbstractCS
    Verify if we can get a coordinate system from the EPSG database with the same axes.
    private void
    setAxis(org.opengis.referencing.cs.CoordinateSystemAxis[] values)
    Invoked by JAXB at unmarshalling time.
    (package private) static IllegalArgumentException
    unexpectedDimension(Map<String,?> properties, org.opengis.referencing.cs.CoordinateSystemAxis[] axes, int expected)
    Convenience method for implementations of createForAxes(Map, CoordinateSystemAxis[]) when the resulting coordinate system would have an unexpected number of dimensions.
    (package private) int
    validateAxis(org.opengis.referencing.cs.AxisDirection direction, javax.measure.Unit<?> unit)
    Returns VALID if the given argument values are allowed for an axis in this coordinate system, or an INVALID_* error code otherwise.

    Methods inherited from class org.apache.sis.io.wkt.FormattableObject

    print, toString, toString, toWKT

    Methods inherited from class java.lang.Object

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

    Methods inherited from interface org.opengis.referencing.IdentifiedObject

    getAlias, getIdentifiers, getName, getRemarks, toWKT
  • Field Details

  • Constructor Details

    • AbstractCS

      public AbstractCS(Map<String,?> properties, org.opengis.referencing.cs.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(org.opengis.referencing.cs.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:
    • AbstractCS

      AbstractCS()
      Constructs a new object in which every attributes are set to a null or empty value. This is not a valid object. This constructor is strictly reserved to JAXB, which will assign values to the fields using reflection.
  • Method Details

    • getAxes

      private static org.opengis.referencing.cs.CoordinateSystemAxis[] getAxes(org.opengis.referencing.cs.CoordinateSystem cs)
      Returns the axes of the given coordinate system.
    • castOrCopy

      public static AbstractCS castOrCopy(org.opengis.referencing.cs.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, because 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.
    • validateAxis

      int validateAxis(org.opengis.referencing.cs.AxisDirection direction, javax.measure.Unit<?> unit)
      Returns VALID if the given argument values are allowed for an axis in this coordinate system, or an INVALID_* error code otherwise. This method is invoked at construction time for checking argument validity. The default implementation returns VALID in all cases. Subclasses override this method in order to put more restrictions on allowed axis directions and check for compatibility with metre or degree units.

      Note for implementers: since this method is invoked at construction time, it shall not depend on this object's state. This method is not in public API for that reason.

      Parameters:
      direction - the direction to test for compatibility (never null).
      unit - the unit to test for compatibility (never null).
      Returns:
      VALID if the given direction and unit are compatible with this coordinate system, INVALID_DIRECTION if the direction is invalid or INVALID_UNIT if the unit is invalid.
    • getInterface

      public Class<? extends org.opengis.referencing.cs.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 org.opengis.referencing.cs.CoordinateSystem
      Returns:
      the number of dimensions of this coordinate system.
    • getAxis

      public final org.opengis.referencing.cs.CoordinateSystemAxis getAxis(int dimension) throws IndexOutOfBoundsException
      Returns the axis for this coordinate system at the specified dimension.
      Specified by:
      getAxis in interface org.opengis.referencing.cs.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:
    • createForAxes

      AbstractCS createForAxes(Map<String,?> properties, org.opengis.referencing.cs.CoordinateSystemAxis[] axes)
      Returns a coordinate system usually of the same type than this CS but with different axes. This method shall be overridden by all AbstractCS subclasses in this package.

      This method returns a coordinate system of the same type if the number of axes is unchanged. But if the given axes array has less elements than this coordinate system dimension, then this method may return another kind of coordinate system. See AxisFilter for an example.

      Parameters:
      axes - the set of axes to give to the new coordinate system.
      Returns:
      a new coordinate system of the same type than this, but using the given axes.
      Throws:
      IllegalArgumentException - if axes contains an unexpected number of axes, or if an axis has an unexpected direction or unexpected unit of measurement.
    • resolveEPSG

      private AbstractCS resolveEPSG(AbstractCS original)
      Verify if we can get a coordinate system from the EPSG database with the same axes. Such CS gives more information (better name and remarks). This is a "would be nice" feature; if we fail, we keep the CS built by Normalizer.
      Parameters:
      original - the coordinate system from which this CS is derived.
      Returns:
      the resolved CS, or this if none.
    • unexpectedDimension

      static IllegalArgumentException unexpectedDimension(Map<String,?> properties, org.opengis.referencing.cs.CoordinateSystemAxis[] axes, int expected)
      Convenience method for implementations of createForAxes(Map, CoordinateSystemAxis[]) when the resulting coordinate system would have an unexpected number of dimensions.
      Parameters:
      properties - the properties which was supposed to be given to the constructor.
      axes - the axes which was supposed to be given to the constructor.
      expected - the minimal expected number of dimensions (may be less than getDimension()).
    • 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:
    • 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).
      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:
    • getAxis

      private org.opengis.referencing.cs.CoordinateSystemAxis[] getAxis()
      Invoked by JAXB at marshalling time.
    • setAxis

      private void setAxis(org.opengis.referencing.cs.CoordinateSystemAxis[] values)
      Invoked by JAXB at unmarshalling time.