# Enum Class Convention

Object
Enum<Convention>
Convention

All Implemented Interfaces:
  `Serializable`, `Comparable<Convention>`, `Constable`

public enum Convention extends Enum<Convention>
The convention to use for WKT formatting. This enumeration specifies whether to use the Well Known Text format defined by ISO 19162 (also known as “WKT 2”), or whether to use the format previously defined in OGC 01-009 (referenced as “WKT 1”).

## WKT 1 variants

The WKT 2 format should be parsed and formatted consistently by all software products. But the WKT 1 format has been interpreted differently by various implementers. Apache SIS can adapt itself to different WKT variants, sometimes automatically. But some aspects cannot be guessed. One noticeable source of confusion is the unit of measurement of `PRIMEM[…]` and `PARAMETER[…]` elements:

- The unit of the Prime Meridian shall be the angular unit of the enclosing Geographic CRS according the OGC 01-009 (Coordinate transformation services) specification.
- An older specification — Simple Features — was unclear on this matter and has been interpreted by many software products as fixing the unit to decimal degrees.
- Some software products support only (longitude, latitude) axis order and ignore completely all `AXIS[…]` elements in the WKT.

Despite the first interpretation being specified by both OGC 01-009 and ISO 19162 standards, the second interpretation appears to be in wide use for WKT 1. Apache SIS uses the standard interpretation by default, but the `WKT1_COMMON_UNITS` enumeration allows parsing and formatting using the older interpretation. The `WKT1_IGNORE_AXES` enumeration mimics the most minimalist WKT 1 parsers, but should be avoided when not imposed by compatibility reasons.

Since:
  0.4
See Also:
  - `WKTFormat​.getConvention()`
  - `WKTFormat​.setConvention(Convention)`

- ## Nested Class Summary

  ### Nested classes/interfaces inherited from class Enum

  `Enum​.EnumDesc<E extends Enum<E>>`

- ## Enum Constant Summary

  Enum Constants
  Enum Constant
  Description
  `INTERNAL`
  A special convention for formatting objects as stored internally by Apache SIS.
  `WKT1`
  The OGC 01-009 format, also known as “WKT 1”.
  `WKT1_COMMON_UNITS`
  The Simple Feature format, also known as “WKT 1”.
  `WKT1_IGNORE_AXES`
  The Simple Feature format without parsing of axis elements.
  `WKT2`
  Latest version of the ISO 19162 format (also known as “WKT 2”) supported by Apache SIS.
  `WKT2_2015`
  The ISO 19162:2015 format, also known as “WKT 2”.
  `WKT2_2019`
  The ISO 19162:2019 format, also known as “WKT 2”.
  `WKT2_SIMPLIFIED`
  The ISO 19162 format with omission of some optional elements.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `isSimplified()`
  Returns `true` if this convention is one of the simplified variants of WKT.
  `int`
  `majorVersion()`
  Returns the major version of the Well Known Text represented by this convention.
  `boolean`
  `supports(Convention base)`
  Returns whether this convention supports the feature of the given convention.
  `static Convention`
  `valueOf(String name)`
  Returns the enum constant of this class with the specified name.
  `static Convention[]`
  `values()`
  Returns an array containing the constants of this enum class, in the order they are declared.

  ### Methods inherited from class Enum

  `clone, compareTo, describeConstable, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf`

  ### Methods inherited from class Object

  `getClass, notify, notifyAll, wait, wait, wait`

- ## Enum Constant Details

  - ### WKT2

    public static final Convention WKT2
    Latest version of the ISO 19162 format (also known as “WKT 2”) supported by Apache SIS. In the current version of Apache SIS, this is synonymous of `WKT2_2019`.

    This is the default convention used by `FormattableObject​.toWKT()` and for new `WKTFormat` instances.

  - ### WKT2_SIMPLIFIED

    public static final Convention WKT2_SIMPLIFIED
    The ISO 19162 format with omission of some optional elements. This convention is identical to the `WKT2` convention except for the following aspects:
    - By default, this convention uses the keywords that are the closest matches to the Java interface names. For example, `"GeodeticCRS"` is preferred to `"GeodCRS"`.
    - The `PrimeMeridian` element is omitted if the meridian is Greenwich.
    - The `Axis` element omits always the `Order` sub-element.
    - The `Axis` element omits the `AxisMinValue`, `AxisMinValue` and `RangeMeaning` sub-elements if their values are the standard values for latitude or longitude axes.
    - The `Unit` elements are less verbose:
      - `Ellipsoid` and `VerticalExtent` elements omit the `LengthUnit` sub-element if that unit is `Units​.METRE`.
      - `Parameter` elements omit the `LengthUnit` sub-element if that unit is the same as the unit of the `ProjectedCRS` axes.
      - `Parameter` and `PrimeMeridian` elements omit the `AngleUnit` sub-element if that unit is the same as the unit of the `GeodeticCRS` axes.
      - Axes unit is declared only once after the axes instead of repeated for each axis if the unit is the same for all axes.
      - `AngleUnit`, `LengthUnit`, `ScaleUnit`, `ParametricUnit` and `TimeUnit` are formatted as plain `Unit` elements.
    - The `Id` element is formatted only for the root element (omit parameters and operation methods `Id`).
    Those modifications are allowed by the ISO 19162 standard, so the WKT is still valid.

    This is the default convention used by `FormattableObject​.toString()`.

  - ### WKT2_2019

    public static final Convention WKT2_2019
    The ISO 19162:2019 format, also known as “WKT 2”. This version replaces ISO 19162:2015.

    Unless otherwise specified by `WKTFormat​.setNameAuthority(Citation)`, projections and parameters formatted with this convention will use the EPSG names when available.

    Since:
      1.5

  - ### WKT2_2015

    public static final Convention WKT2_2015
    The ISO 19162:2015 format, also known as “WKT 2”. This version has been replaced by ISO 19162:2019. This enumeration value can be used when compatibility with this older standard is required.

    This was the default convention used by `FormattableObject​.toWKT()` in Apache SIS versions prior to version 1.5.

    Since:
      1.5

  - ### WKT1

    public static final Convention WKT1
    The OGC 01-009 format, also known as “WKT 1”. A definition for this format is shown in Extended Backus Naur Form (EBNF) in OGC 01-009.

    Unless otherwise specified by `WKTFormat​.setNameAuthority(Citation)`, projections and parameters formatted with this convention will use the OGC names when available.

    #### Differences compared to WKT 2

    WKT 1 and WKT 2 differ in their keywords and syntax, but also in more subtle ways regarding axis names, parameter and code list values. For example, for geocentric CRS, WKT 1 uses a legacy set of Cartesian axes which were defined in OGC 01-009. Those axes use the Other, Easting and Northing axis directions instead of the geocentric ones. For more uniform handling of CRS objects in client code, SIS parser replaces some WKT 1 conventions by the ISO ones when possible.

    Geocentric axis directions
    ISO 19111 | OGC 01-009 | Description
    --- | --- | ---
    Geocentric X | Other | Toward prime meridian
    Geocentric Y | Easting | Toward 90°E longitude
    Geocentric Z | Northing | Toward north pole

    Coordinate system axis names
    CRS type | WKT1 names | ISO abbreviations
    --- | --- | ---
    Geographic | Lon, Lat | λ, φ
    Vertical | H | H or h
    Projected | X, Y | E, N
    Geocentric | X, Y, Z | X, Y, Z

  - ### WKT1_COMMON_UNITS

    public static final Convention WKT1_COMMON_UNITS
    The Simple Feature format, also known as “WKT 1”. OGC Simple Feature is anterior to OGC 01-009 and defines the same format, but was unclear about the unit of measurement for prime meridians and projection parameters. Consequently, many implementations interpreted those angular units as fixed to degrees instead than being context-dependent.

    This convention is identical to `WKT1` except for the following aspects:

    - The angular units of `PRIMEM` and `PARAMETER` elements are always degrees, no matter the units of the enclosing `GEOGCS` element.
    - Unit names use American spelling instead of the international ones (e.g. meter instead of metre).

  - ### WKT1_IGNORE_AXES

    public static final Convention WKT1_IGNORE_AXES
    The Simple Feature format without parsing of axis elements. This convention is identical to `WKT1_COMMON_UNITS` except that all `AXIS[…]` elements are ignored. Since the WKT 1 specification said that the default axis order shall be (x,y) or (longitude, latitude), ignoring `AXIS[…]` elements is equivalent to forcing the coordinate systems to that default order.

    Note that `AXIS[…]` elements still need to be well formed even when parsing a text with this convention. Malformed axis elements will continue to cause a `ParseException` despite their content being ignored.

    This convention may be useful for compatibility with some other software products that do not handle axis order correctly. But except when imposed by such compatibility reasons, this convention should be avoided as much as possible.

    Since:
      0.6

  - ### INTERNAL

    @Debug public static final Convention INTERNAL
    A special convention for formatting objects as stored internally by Apache SIS. The result is similar to the one produced using the `WKT2_SIMPLIFIED` convention, with the following differences:
    - All quoted texts (not only the remarks) preserve non-ASCII characters.
    - Map projections are shown as SIS stores them internally, i.e. with the separation between linear and non-linear steps, rather than as a single operation.
    - `Parameter` elements omit the unit of measurement if that unit is equal to the default unit (as declared in the parameter descriptor).
    - `CompoundCRS` elements show nested compound CRS if any (the structure is not flattened).
    - `Id` elements are formatted for child elements in addition to the root one.
    - `Id` element omits the `URI` sub-element if the latter is derived by Apache SIS from the `Id` properties.
    - `Remarks` element is formatted for all identified objects, not only CRS or coordinate operations.
    - Additional attributes not defined by ISO 19162 may be formatted.
    This convention is used only for debugging purpose.

- ## Method Details

  - ### values

    public static Convention[] values()
    Returns an array containing the constants of this enum class, in the order they are declared.
    Returns:
      an array containing the constants of this enum class, in the order they are declared

  - ### valueOf

    public static Convention valueOf(String name)
    Returns the enum constant of this class with the specified name. The string must match exactly an identifier used to declare an enum constant in this class. (Extraneous whitespace characters are not permitted.)
    Parameters:
      `name` - the name of the enum constant to be returned.
    Returns:
      the enum constant with the specified name
    Throws:
      `IllegalArgumentException` - if this enum class has no constant with the specified name
      `NullPointerException` - if the argument is null

  - ### supports

    public boolean supports(Convention base)
    Returns whether this convention supports the feature of the given convention. For example, `supports(WKT2_2015)` returns `true` if this convention represents either ISO 19162:2015 or a more recent version such as ISO 19162:2019.
    Parameters:
      `base` - the base version which is required.
    Returns:
      whether this convention is the given base version or a more recent version.
    Since:
      1.5

  - ### majorVersion

    public int majorVersion()
    Returns the major version of the Well Known Text represented by this convention. In current Apache SIS implementation, this method can return only 1 or 2.
    Returns:
      1 if this convention is one of the WKT 1 variants, or 2 otherwise.

  - ### isSimplified

    public boolean isSimplified()
    Returns `true` if this convention is one of the simplified variants of WKT. The simplifications are documented in the `WKT2_SIMPLIFIED` javadoc. This method also considers version 1 of WKT as a simplified convention.
    Returns:
      `true` it this convention uses a simplified variant of WKT.