Class ReferencingByIdentifiers.Coder

java.lang.Object
org.apache.sis.referencing.gazetteer.ReferencingByIdentifiers.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
Version:
1.3
  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    Creates a new instance.
  • Method Summary

    Modifier and Type
    Method
    Description
    decode(CharSequence identifier)
    Decodes the given identifier into a latitude and a longitude.
    abstract String
    encode(org.opengis.geometry.DirectPosition position)
    Encodes the given position into an identifier.
    encode(org.opengis.geometry.DirectPosition position, javax.measure.Quantity<?> precision)
    A combined method which sets the encoder precision to the given value, then formats the given position.
    abstract javax.measure.Quantity<?>
    getPrecision(org.opengis.geometry.DirectPosition position)
    Returns approximate precision of the identifiers formatted by this coder at the given location.
    Returns the reference system for which this coder is reading or writing identifiers.
    (package private) static void
    recoverableException(Class<?> caller, String method, Exception e)
    Logs a warning for a recoverable error while transforming a position.
    abstract void
    setPrecision(javax.measure.Quantity<?> precision, org.opengis.geometry.DirectPosition position)
    Sets the desired precision of the identifiers formatted by this coder.

    Methods inherited from class java.lang.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 javax.measure.Quantity<?> getPrecision(org.opengis.geometry.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(javax.measure.Quantity<?> precision, org.opengis.geometry.DirectPosition position) throws javax.measure.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:
      javax.measure.IncommensurableException - if the given precision uses incompatible units of measurement.
    • encode

      public String encode(org.opengis.geometry.DirectPosition position, javax.measure.Quantity<?> precision) throws javax.measure.IncommensurableException, org.opengis.referencing.operation.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: 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:
      javax.measure.IncommensurableException - if the given precision uses incompatible units of measurement.
      org.opengis.referencing.operation.TransformException - if an error occurred while transforming the given coordinate to an identifier.
    • encode

      public abstract String encode(org.opengis.geometry.DirectPosition position) throws org.opengis.referencing.operation.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:
      org.opengis.referencing.operation.TransformException - if an error occurred while transforming the given coordinate to an identifier.
    • decode

      public abstract AbstractLocation decode(CharSequence identifier) throws org.opengis.referencing.operation.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:
      org.opengis.referencing.operation.TransformException - if an error occurred while parsing the given string.
    • recoverableException

      static void recoverableException(Class<?> caller, String method, Exception e)
      Logs a warning for a recoverable error while transforming a position. This is used for implementations of method such as getPrecision(DirectPosition), which can fallback on "worst case" scenario.
      Parameters:
      caller - the class that wanted to transform a position.
      method - the method that wanted to transform a position.
      e - the transformation error.