Module org.apache.sis.referencing.gazetteer

Package org.apache.sis.referencing.gazetteer

Class GeohashReferenceSystem.Coder

Object

ReferencingByIdentifiers.Coder

Coder

Enclosing class:

Geohash­Reference­System

public class GeohashReferenceSystem.Coder
extends ReferencingByIdentifiers.Coder

Conversions between direct positions and geohashes. Each Coder instance can read codes at arbitrary precision, but formats at the specified precision. The same Coder instance can be reused for reading or writing many geohashes.

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:

0.8

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	Coder()	Creates a new geohash coder/decoder initialized to the default precision.

Method Summary

Modifier and Type	Method	Description
Abstract­Location	decode(Char­Sequence geohash)	Decodes the given geohash into a latitude and a longitude.
String	encode(double φ, double λ)	Encodes the given latitude and longitude into a geohash.
String	encode(Direct­Position position)	Encodes the given position into a geohash.
String	encode(Direct­Position position, Quantity<?> precision)	Encodes the given position into a geohash with the given precision.
int	get­Hash­Length()	Returns the length of geohashes strings to be encoded by the encode(Direct­Position) method.
Quantity<Length>	get­Precision(Direct­Position position)	Returns an approximate precision of the geohashes formatted by this coder.
final Geohash­Reference­System	get­Reference­System()	Returns the reference system for which GeoHash identifiers will be encoded or decoded.
void	set­Hash­Length(int length)	Sets the length of geohashes strings to be encoded by the encode(Direct­Position) method.
void	set­Precision(Quantity<?> precision, Direct­Position position)	Sets the desired precision of the identifiers formatted by this coder.

Methods inherited from class Object

clone, equals, finalize, get­Class, hash­Code, notify, notify­All, to­String, wait, wait, wait

Constructor Details

Coder

protected Coder()

Creates a new geohash coder/decoder initialized to the default precision.

Method Details

getReferenceSystem

public final GeohashReferenceSystem getReferenceSystem()

Returns the reference system for which GeoHash identifiers will be encoded or decoded.

Specified by:

get­Reference­System in class Referencing­By­Identifiers.Coder

Returns:

the enclosing reference system.

Since:

1.3

getHashLength

public int getHashLength()

Returns the length of geohashes strings to be encoded by the encode(Direct­Position) method. The default value for Geohash­Reference­System.Format.BASE32 is 12.

Returns:

the length of geohashes strings.

setHashLength

public void setHashLength(int length)

Sets the length of geohashes strings to be encoded by the encode(Direct­Position) method.

Parameters:

length - the new length of geohashes strings.

getPrecision

public Quantity<Length> getPrecision(DirectPosition position)

Returns an approximate precision of the geohashes formatted by this coder. Values are in units of ellipsoid axis length (typically metres). If the location is unspecified, then this method returns a value for the "worst case" scenario, which is at equator. The actual precision is sometimes (but not always) better for coordinates closer to a pole.

Specified by:

get­Precision in class Referencing­By­Identifiers.Coder

Parameters:

position - where to evaluate the precision, or null for equator.

Returns:

approximate precision of formatted geohashes.

Since:

1.3

setPrecision

public 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 a string length.

Specified by:

set­Precision in class Referencing­By­Identifiers.Coder

Parameters:

precision - the desired precision in a linear or angular unit.

position - location where the specified precision is desired, or null for the equator.

Throws:

Incommensurable­Exception - if the given precision does not use linear or angular units.

Since:

1.3

encode

public String encode(double φ,
 double λ)
              throws TransformException

Encodes the given latitude and longitude into a geohash. This method does not take in account the axis order and units of the coordinate reference system (CRS) given to the Geohash­Reference­System constructor. For geohashing of coordinates in different CRS, use encode(Direct­Position) instead.

Parameters:

φ - latitude to encode, as decimal degrees in the [-90 … 90]° range.

λ - longitude to encode, as decimal degrees in the [-180 … 180]° range.

Returns:

geohash encoding of the given longitude and latitude.

Throws:

Transform­Exception - if an error occurred while formatting the given coordinate.

encode

public String encode(DirectPosition position)
              throws TransformException

Encodes the given position into a geohash. The default implementation transforms the given position to the coordinate reference system expected by the enclosing Geohash­Reference­System, then delegates to encode(double, double).

Specified by:

encode in class Referencing­By­Identifiers.Coder

Parameters:

position - the coordinate to encode.

Returns:

geohash encoding of the given position.

Throws:

Transform­Exception - if an error occurred while transforming the given coordinate to a geohash reference.

encode

public String encode(DirectPosition position,
 Quantity<?> precision)
              throws IncommensurableException,
TransformException

Encodes the given position into a geohash with the given precision. This is equivalent to invoking set­Precision(Quantity, Direct­Position) before encode(Direct­Position), except that it is potentially more efficient.

Overrides:

encode in class Referencing­By­Identifiers.Coder

Parameters:

position - the coordinate to encode.

precision - the desired precision in a linear or angular unit.

Returns:

geohash encoding of the given position.

Throws:

Incommensurable­Exception - if the given precision does not use linear or angular units.

Transform­Exception - if an error occurred while transforming the given coordinate to a geohash reference.

Since:

1.3

decode

public AbstractLocation decode(CharSequence geohash)
                        throws TransformException

Decodes the given geohash into a latitude and a longitude. The axis order depends on the coordinate reference system of the enclosing Geohash­Reference­System.

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.

Specified by:

decode in class Referencing­By­Identifiers.Coder

Parameters:

geohash - geohash string to decode.

Returns:

a new geographic coordinate for the given geohash.

Throws:

Transform­Exception - if an error occurred while parsing the given string.