com.askgeo.dbl.base
Class GeneralMap<ResultType extends ResultBase>

java.lang.Object
  com.askgeo.dbl.base.GeneralMap<ResultType>

Type Parameters:

ResultType - is the generic subclass of ResultBase that defines the return type for a number of the methods in GeneralMap, most notably findResult.

Direct Known Subclasses:

CountryMap, TimeZoneMap, UsCensusMap

public abstract class GeneralMap<ResultType extends ResultBase>
extends java.lang.Object

All the map classes in AskGeo derive directly or indirectly from GeneralMap. GeneralMap implements the basic functionality shared among all of the maps.

A GeneralMap contains a representation of a map that covers part or all of the Earth. These are defined by a set of polygonal shapes. Each shape represents a geographic entity that might be of interest to the user of the map.

Subclasses of GeneralMap allow the user to query a given latitude and longitude and to get a result back that contains polygonal data that defines the shape, as well as metadata associated with that shape. In some cases, additional metadata that is external to the map but is associated with the shapes in the map is also returned (such as with maps based on data from the US Census Bureau).

In the event that a query point is not inside any of the shapes in the map, a GeneralMap may also snap to a nearby shape and use that to build the result object. Whether or not this is the case, and the distance from the query point to the shape is also returned in the result object.

Method Summary

void	authorize(java.io.File f) Authorizes the use of the map object by providing a license file.
void	authorize(java.io.InputStream is) Authorizes the use of the map object by providing a license file.
void	authorize(java.lang.String s) Authorizes the use of the map object by providing a license String.
static double[]	conusBbox() Returns a new bounding box roughly containing the continental US, or CONUS (i.e., from -125 to -66 degrees longitude and from 24 to 50 degrees latitude).
abstract ResultType	findResult(double latDeg, double lonDeg) Returns a results map query result.
java.util.Vector<ResultType>	getAllResults() Returns a Vector of results, each result corresponding to a shape in the map.
double[]	getBbox() Returns the bounding box for this map as a double array.
DataFieldInterface	getDataField(int index) Each map contains metadata associated with each shape.
int	getNumDataFields() Returns the number of data fields associated with this map.
abstract java.lang.String	getOracleName() A unique identifier for this map, used in the license file and in the AskGeo Web API.
static double[]	worldBbox() Returns a new bounding box encompassing the entire globe (for example, from -180 to +180 degrees longitude and from -90 to +90 degrees latitude).

Methods inherited from class java.lang.Object

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

Method Detail

findResult

public abstract ResultType findResult(double latDeg,
                                      double lonDeg)

Returns a results map query result. All result classes extend ResultBase but the specific subclass returned depends on what map class is being used. Each map class has a companion result class. If no shape is found at or near the query point, null is returned.

Parameters:

latDeg - the latitude of the query point, expressed in degrees.

lonDeg - the longitude of the query point, expressed in degrees.

Returns:

the result for the given latitude and longitude, or null if none is found.

getAllResults

public java.util.Vector<ResultType> getAllResults()

Returns a Vector of results, each result corresponding to a shape in the map. All result classes extend ResultBase but the specific subclass depends on what map class is being used. Each map class has a companion result class.

Returns:

a Vector of results.

authorize

public void authorize(java.io.File f)
               throws java.io.IOException

Authorizes the use of the map object by providing a license file.

Parameters:

f - the license file.

Throws:

java.io.IOException - if there are problems reading the file.

authorize

public void authorize(java.io.InputStream is)
               throws java.io.IOException

Authorizes the use of the map object by providing a license file.

Parameters:

is - the input stream of the license file.

Throws:

java.io.IOException - if there are problems reading the stream.

authorize

public void authorize(java.lang.String s)

Authorizes the use of the map object by providing a license String.

Parameters:

s - the license String.

getOracleName

public abstract java.lang.String getOracleName()

A unique identifier for this map, used in the license file and in the AskGeo Web API.

Returns:

the unique identifier for this map.

getBbox

public double[] getBbox()

Returns the bounding box for this map as a double array. The order of the array is: min latitude, min longitude, max latitude, max longitude.

Returns:

the bounding box.

getDataField

public DataFieldInterface getDataField(int index)

Each map contains metadata associated with each shape. The metadata is indexed by an enum that is defined within each map subclass. All of the enums implement the DataFieldInterface. Those enums are exposed through this common interface here.

Parameters:

index - the index of the data field to return, ranging from 0 to getNumDataFields inclusive.

Returns:

the requested data field.

getNumDataFields

public int getNumDataFields()

Returns the number of data fields associated with this map.

Returns:

the number of data fields associated with this map.

worldBbox

public static double[] worldBbox()

Returns a new bounding box encompassing the entire globe (for example, from -180 to +180 degrees longitude and from -90 to +90 degrees latitude). Values are stored in radians.

Returns:

the bounding box double array (values stored in radians).

conusBbox

public static double[] conusBbox()

Returns a new bounding box roughly containing the continental US, or CONUS (i.e., from -125 to -66 degrees longitude and from 24 to 50 degrees latitude).

Returns:

the bounding box double array (values stored in radians).