prajna.geo

Class GeoNamesLocator

java.lang.Object

prajna.geo.GeoLocator

prajna.geo.GeoNamesLocator

Direct Known Subclasses:

GeoNamesVerifier

public class GeoNamesLocator
extends GeoLocator

Geographic entity location class using the geographic locator at GeoNames. Alternately, the locator can read a local file, avoiding the connectivity problems that geonames.org has by using a single local file. When reading a single file, it generally only works with a single location type. It uses an internal cache to improve performance.

Author:

Edward Swing

Constructor Summary

Constructors

Constructor and Description
GeoNamesLocator() Create the GeoNamesLocator
GeoNamesLocator(java.lang.String path) Create the GeoNamesLocator with the specified path

Method Summary

Methods

Modifier and Type	Method and Description
protected static java.util.Map<java.lang.String,GeoObject>	getCache() Get the cache.
GeoCoord	getCoordinate(java.lang.String locName) Request the geographic coordinate from the GeoNames Map server.
java.lang.String	getCountry(java.lang.String locName) Get the country containing the named location.
GeoFeatureType	getFeatureType(java.lang.String locName) Get the feature type for the location name.
GeoObject	getGeoObject(java.lang.String locName) Get the geographic object for the given location name.
java.lang.String	getGeoPath() Get the geonames path.
java.lang.String	getRealName(java.lang.String locName) Get the real name known by GeoNames for the location name.
boolean	isEstimateFlag() Return whether the locator allows estimation
boolean	isLoaded() Return whether the cache has been fully loaded
boolean	isRetryFlag() Return whether the locator allows retrying if the servers are busy
void	loadCache() Loads the entire file into the cache.
GeoShape	lookup(Location loc) Look up the shape associated with the specified Location
GeoShape	lookup(java.lang.String locName) Look up the shape associated with the specified Location by name
GeoShape	lookup(java.lang.String locName, java.lang.String type) Look up the shape associated with the specified Location by name and type
void	setEstimateFlag(boolean estimateFlag) Set the flag indicating whether to allow estimation within the locator.
void	setFeatureClass(java.lang.String featureClasses) Set the feature classes this locator will use.
void	setGeoPath(java.lang.String path) Set the base GeoNames path.
void	setRetryFlag(boolean retryFlag) Set the flag indicating whether to allow retrying when the servers are too busy.

Methods inherited from class java.lang.Object

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

Constructor Detail

GeoNamesLocator

public GeoNamesLocator()

Create the GeoNamesLocator

GeoNamesLocator

public GeoNamesLocator(java.lang.String path)

Create the GeoNamesLocator with the specified path

Parameters:

path - the path to the GeoNames file or URL

Method Detail

getCoordinate

public GeoCoord getCoordinate(java.lang.String locName)

Request the geographic coordinate from the GeoNames Map server.

Specified by:

getCoordinate in class GeoLocator

Parameters:

locName - Location name.

Returns:

the coordinate for the given location

getCountry

public java.lang.String getCountry(java.lang.String locName)

Get the country containing the named location.

Parameters:

locName - the location name

Returns:

the country name containing the location.

getFeatureType

public GeoFeatureType getFeatureType(java.lang.String locName)

Get the feature type for the location name.

Overrides:

getFeatureType in class GeoLocator

Parameters:

locName - the location name

Returns:

the GeoFeatureType for the geographic feature, or null if no location matches the specified name

getGeoObject

public GeoObject getGeoObject(java.lang.String locName)

Get the geographic object for the given location name. This method first checks the cache for the location name. If it is not found, the location name is looked up using the Geonames web service

Parameters:

locName - the location name

Returns:

the geographic object representing the information about this location name

getGeoPath

public java.lang.String getGeoPath()

Get the geonames path. This will either return the file being read by this locator, or the URL that it is reading from.

Returns:

the geonames path

getRealName

public java.lang.String getRealName(java.lang.String locName)

Get the real name known by GeoNames for the location name.

Parameters:

locName - the location name

Returns:

the name GeoNames uses for the specified name, or null if no location matches the specified name

isEstimateFlag

public boolean isEstimateFlag()

Return whether the locator allows estimation

Specified by:

isEstimateFlag in class GeoLocator

Returns:

whether the locator allows estimation

isLoaded

public boolean isLoaded()

Return whether the cache has been fully loaded

Returns:

whether the cache has been loaded

isRetryFlag

public boolean isRetryFlag()

Return whether the locator allows retrying if the servers are busy

Returns:

whether the locator allows retrying

loadCache

public void loadCache()

Loads the entire file into the cache. This has no effect if the GeoPath points to a URL.

lookup

public GeoShape lookup(Location loc)

Look up the shape associated with the specified Location

Specified by:

lookup in class GeoLocator

Parameters:

loc - the specified location object

Returns:

The geographic shape representing the specified location

lookup

public GeoShape lookup(java.lang.String locName)

Look up the shape associated with the specified Location by name

Specified by:

lookup in class GeoLocator

Parameters:

locName - the specified location name

Returns:

The geographic shape representing the specified location

lookup

public GeoShape lookup(java.lang.String locName,
              java.lang.String type)

Look up the shape associated with the specified Location by name and type

Specified by:

lookup in class GeoLocator

Parameters:

locName - the specified location name

type - the type of location the name represents

Returns:

The geographic shape representing the specified location

setEstimateFlag

public void setEstimateFlag(boolean estimateFlag)

Set the flag indicating whether to allow estimation within the locator.

Specified by:

setEstimateFlag in class GeoLocator

Parameters:

estimateFlag - whether the locator allows estimation

setFeatureClass

public void setFeatureClass(java.lang.String featureClasses)

Set the feature classes this locator will use. The argument should be composed of letters indicating which feature classes this locator will use. Each code is a single letter, and the codes are concatenated together. Letters correspond to those described in the geonames web service, at http://www.geonames.org/export/codes.html. By default, the feature classes are AHP, indicating Countries and Regions (A), Bodies of Water (H), and Population Centers (P).

Parameters:

featureClasses - A string containing single letter codes.

setGeoPath

public void setGeoPath(java.lang.String path)

Set the base GeoNames path. If not set, the default is http://ws.geonames.org. If the path is set to a local file, then the data is read from the local file instead of checking the URL.

Parameters:

path - the new base for the geonames URL, or the local geoFile.

setRetryFlag

public void setRetryFlag(boolean retryFlag)

Set the flag indicating whether to allow retrying when the servers are too busy.

Parameters:

retryFlag - whether the locator allows retrying

getCache

protected static java.util.Map<java.lang.String,GeoObject> getCache()

Get the cache. This method returns the current cache. This method is available for developers who want to subclass this locator.

Returns:

the cache