net.rim.device.api.lbs.maps.server
Class Geocoder

java.lang.Object
  extended by net.rim.device.api.lbs.maps.server.Geocoder

public final class Geocoder
extends Object

Provides geocoding capabilities, so you can request the geographic coordinates for a specified location address. You can specify one of the following types of address search terms:

Free-form and structured are the types of geocoding requests. However, you can define how the call is executed. Geocoder supports both asynchronous and synchronous calls.

To make an asynchronous call, you must provide a ServerExchangeCallback.

Asynchronous example:
Geocoder.getInstance().geocode(myServerExchangeCallback, "New York", new MapDimensions(...), 0);

To make a synchronous (or blocking) call, you must pass null in as the ServerExchangeCallback. This forces the method to return the results of the query when it's complete.

Synchronous example:
Geocoder.getInstance().geocode(null, "New York", new MapDimensions(...), 0);

Since:
BlackBerry API 7.0.0

Method Summary
 GeocodeExchange geocode(ServerExchangeCallback callback, String address, MapDimensions visibleArea, long timeout)
          Geocodes a free-form address to latitude and longitude coordinates (if possible).
 GeocodeExchange geocode(ServerExchangeCallback callback, MapLocation address, MapDimensions visibleArea, long timeout)
          Geocodes a structured address to latitude and longitude coordinates.
static Geocoder getInstance()
          Retrieves the singleton instance of the Geocoder.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 



Method Detail

getInstance

public static final Geocoder getInstance()
Retrieves the singleton instance of the Geocoder.

Returns:
The singleton instance of the Geocoder.
Since:
BlackBerry API 7.0.0

geocode

public final GeocodeExchange geocode(ServerExchangeCallback callback,
                                     String address,
                                     MapDimensions visibleArea,
                                     long timeout)
Geocodes a free-form address to latitude and longitude coordinates (if possible).

Parameters:
callback - If provided, this will be an asynchronous call. If null the call will be blocking (synchronous).
address - A free-form string representing the address to look up. Depending on how this parameter is formatted, the result may not be the same as if it were a structured search.
visibleArea - This is the latitude/longitude bounding box that is used to provide context for the search. This allows users to enter a street name instead of the entire address.
timeout - The amount of time that should elapse before the either the connection attempt should give up and (if using the synchronous method) how long before the method should return.
Returns:
The GeocodeExchange that was created, which contains the results and any errors.
Since:
BlackBerry API 7.0.0

geocode

public final GeocodeExchange geocode(ServerExchangeCallback callback,
                                     MapLocation address,
                                     MapDimensions visibleArea,
                                     long timeout)
                              throws GeocodeException
Geocodes a structured address to latitude and longitude coordinates.

Parameters:
callback - If provided, this will be an asynchronous call. If null the call will be blocking (synchronous).
address - A structured model representing the address. Each field of the address is defined.
visibleArea - This is the latitude/longitude bounding box that is used to provide context for the search. This allows users to enter a street name instead of the entire address.
timeout - The amount of time that should elapse before the either the connection attempt should give up and (if using the synchronous method) how long before the method should return.
Returns:
The GeocodeExchange that was created, which contains the results and any errors.
Throws:
GeocodeException - if address is null.
Since:
BlackBerry API 7.0.0





Copyright 1999-2011 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Java is a trademark of Oracle America Inc. in the US and other countries.
Legal