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

Class ReferencingByIdentifiers.Coder

Object
Coder
Direct Known Subclasses:
Geohash­Reference­System​.Coder, Military­Grid­Reference­System​.Coder
Enclosing class:
Referencing­By­Identifiers
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 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 get­Precision(Direct­Position) 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:
      Incommensurable­Exception - 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:
      Incommensurable­Exception - if the given precision uses incompatible units of measurement.
      Transform­Exception - 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:
      Transform­Exception - 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 Referencing­By­Identifiers.
      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:
      Transform­Exception - if an error occurred while parsing the given string.