Module org.apache.sis.referencing.gazetteer
Package org.apache.sis.referencing.gazetteer

# Class ReferencingByIdentifiers.Coder

Object
Coder

Direct Known Subclasses:
  `GeohashReferenceSystem​.Coder`, `MilitaryGridReferenceSystem​.Coder`

Enclosing class:
  `ReferencingByIdentifiers`

public abstract static class ReferencingByIdentifiers.Coder extends Object
Conversions between direct positions and identifiers. Each `Coder` instance can read references at arbitrary precision, but formats at the specified approximate precision. The same `Coder` instance can be reused for reading or writing many identifiers.

## Immutability and thread safety

This class is not thread-safe. A new instance must be created for each thread, or synchronization must be applied by the caller.

Since:
  1.3

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `Coder()`
  Creates a new instance.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `abstract AbstractLocation`
  `decode(CharSequence identifier)`
  Decodes the given identifier into a latitude and a longitude.
  `abstract String`
  `encode(DirectPosition position)`
  Encodes the given position into an identifier.
  `String`
  `encode(DirectPosition position, Quantity<?> precision)`
  A combined method which sets the encoder precision to the given value, then formats the given position.
  `abstract Quantity<?>`
  `getPrecision(DirectPosition position)`
  Returns approximate precision of the identifiers formatted by this coder at the given location.
  `abstract ReferencingByIdentifiers`
  `getReferenceSystem()`
  Returns the reference system for which this coder is reading or writing identifiers.
  `abstract void`
  `setPrecision(Quantity<?> precision, DirectPosition position)`
  Sets the desired precision of the identifiers formatted by this coder.

  ### Methods inherited from class Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### Coder

    protected Coder()
    Creates a new instance.

- ## Method Details

  - ### getReferenceSystem

    public abstract ReferencingByIdentifiers getReferenceSystem()
    Returns the reference system for which this coder is reading or writing identifiers.
    Returns:
      the enclosing reference system.

  - ### getPrecision

    public abstract Quantity<?> getPrecision(DirectPosition position)
    Returns approximate precision of the identifiers formatted by this coder at the given location. The returned value is typically a length in linear unit (e.g. metres). Precisions in angular units should be converted to linear units at the specified location. If the location is `null`, then this method should return a precision for the worst case scenario.
    Parameters:
      `position` - where to evaluate the precision, or `null` for the worst case scenario.
    Returns:
      approximate precision in metres of formatted identifiers.

  - ### setPrecision

    public abstract void setPrecision(Quantity<?> precision, DirectPosition position) throws IncommensurableException
    Sets the desired precision of the identifiers formatted by this coder. The given value is converted to coder-specific representation (e.g. number of digits). The value returned by `getPrecision(DirectPosition)` may be different than the value specified to this method.
    Parameters:
      `precision` - the desired precision.
      `position` - location where the specified precision is desired, or `null` for the worst case scenario.
    Throws:
      `IncommensurableException` - if the given precision uses incompatible units of measurement.

  - ### encode

    public String encode(DirectPosition position, Quantity<?> precision) throws IncommensurableException, TransformException
    A combined method which sets the encoder precision to the given value, then formats the given position. The default implementation is equivalent to the following code:

        setPrecision(precision, position);
        return encode(position);

    Subclasses should override with more efficient implementation, for example by transforming the given position only once.
    Parameters:
      `position` - the coordinate to encode.
      `precision` - the desired precision.
    Returns:
      identifier of the given position.
    Throws:
      `IncommensurableException` - if the given precision uses incompatible units of measurement.
      `TransformException` - if an error occurred while transforming the given coordinate to an identifier.

  - ### encode

    public abstract String encode(DirectPosition position) throws TransformException
    Encodes the given position into an identifier. The given position must have a Coordinate Reference System (CRS) associated to it.
    Parameters:
      `position` - the coordinate to encode.
    Returns:
      identifier of the given position.
    Throws:
      `TransformException` - if an error occurred while transforming the given coordinate to an identifier.

  - ### decode

    public abstract AbstractLocation decode(CharSequence identifier) throws TransformException
    Decodes the given identifier into a latitude and a longitude. The axis order depends on the coordinate reference system of the enclosing `ReferencingByIdentifiers`.
    Upcoming API change — generalization
    in a future SIS version, the type of returned element may be generalized to the `org​.opengis​.referencing​.gazetteer​.Location` interface. This change is pending GeoAPI revision.
    Parameters:
      `identifier` - identifier string to decode.
    Returns:
      a new geographic coordinate for the given identifier.
    Throws:
      `TransformException` - if an error occurred while parsing the given string.