net.rim.device.api.lbs
Class Locator

java.lang.Object
  extended by net.rim.device.api.lbs.Locator

public final class Locator
extends Object

Locator is a geocoding service that allows you to obtain location information for an address. You can use the the Locator class to obtain latitudinal and longitudinal information using either an AddressInfo object for formatted input or a String object for non-formatted input. A successful request for geocode information return an enumeration of Landmarks.

Requests for geocode information are synchronous, but can be interrupted by invoking cancel(). An application can use the Locator class to make only one request at a time. Making more than one request results in a MapServiceException.

An application must request geocode information outside of the event dispatch thread. Requests made on the event dispatch thread will be denied and result in a MapServiceException.

Each request for geocode information is sent to the LBS Locator Server. If a request fails, a LocatorException is thrown with an error code that indicates the reason for the failure. If a request fails or stalls at the transport level, it will be cancelled as specified by the value for REQUEST_TIMEOUT.

If the LBS Map API is not installed on a BlackBerry device, requests for geocode information will throw a MapServiceException.

Request results are not cached on the BlackBerry device.

Usage Scenarios

Scenario 1: Freeform String Geocode Request

Returns to landmarkArray an array of Landmark objects that fit the “Waterloo” search criteria.

     Landmark[] landmarkArray = Locator.geocode(“Waterloo”, null);

Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.6.0

Field Summary
Category: Signed static int ADDRESS
          Use this to request the nearest address or nearest street to the specified latitude/longitude.
Category: Signed static int CITY
          Use this constant for reverse geocoding so that the return value will be focused on the City Level.
Category: Signed static int COUNTRY
          Use this constant for reverse geocoding so that the return value will be focused on Country Level.
Category: Signed static int PROVINCE_STATE
          Use this constant for reverse geocoding so that the return value will be focused on Province/State Level.
Category: Signed static int REQUEST_TIMEOUT
          Deprecated.  
 
Method Summary
Category: Signed static void cancel()
          Cancels the Locator request for the calling application process.
Category: Signed static Landmark[] geocode(String freeformString, Coordinates startCoords)
          Starts a request for geocode information using a non-formatted String as input.
Category: Signed static Landmark[] geocode(AddressInfo address, Coordinates startCoords)
          Starts a request for geocode information using an AddressInfo object as input.
Category: Signed static Landmark[] reverseGeocode(int latitude, int longitude, int searchType)
          Starts a request for reverse GeoCoding using a Latitude & Longitude, Admin Bounding Box.
Category: Signed static Landmark[] reverseGeocode(Coordinates coord, int searchType)
          Starts a request for reverse GeoCoding using a Coordinates object.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 



Field Detail

REQUEST_TIMEOUT

public static final int REQUEST_TIMEOUT
Deprecated. 
The timeout value, in seconds, before the request will be cancelled. This constant will be removed in future releases and should not be relied upon.

See Also:
Constant Field Values
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.6.0

ADDRESS

public static final int ADDRESS
Use this to request the nearest address or nearest street to the specified latitude/longitude.

If the nearest address cannot be found, the nearest administrative region will be returned. This could be a combination of City, State/Province and or Country depending on if the location is inside one of these boundaries.

See Also:
Constant Field Values
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 5.0.0

COUNTRY

public static final int COUNTRY
Use this constant for reverse geocoding so that the return value will be focused on Country Level. This will return the name of the Country.

See Also:
Constant Field Values
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 5.0.0

PROVINCE_STATE

public static final int PROVINCE_STATE
Use this constant for reverse geocoding so that the return value will be focused on Province/State Level. This will return the name of the Province/State & Country.

See Also:
Constant Field Values
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 5.0.0

CITY

public static final int CITY
Use this constant for reverse geocoding so that the return value will be focused on the City Level. This will return the name of the City, Province/State & Country.

See Also:
Constant Field Values
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 5.0.0


Method Detail

geocode

public static Landmark[] geocode(AddressInfo address,
                                 Coordinates startCoords)
                          throws LocatorException
Starts a request for geocode information using an AddressInfo object as input.

Parameters:
address - The AddressInfo object to use in the request for geocode information. Supported fields include: STREET, POSTAL_CODE, CITY, STATE, COUNTRY or COUNTRY_CODE.
startCoords - hint Coordinates for starting the search specified in the request. This is used in refining a request from an initial location starting point. This parameter may be null.
Returns:
array of Landmarks: the first array element contains the most relevant Landmark to the locator request. May be null if geocode request is cancelled or the request fails.
Throws:
LocatorException - if no valid connection exists (i.e. The BlackBerry device is not sufficiently connected to send or receive over any transport.)

One of the following will be true if this is the case:

  • RadioInfo.getActiveWAFs() == 0
  • CoverageInfo.isCoverageSufficient(CoverageInfo.TRANSPORT_ANY, null) == false
  • WLANInfo.getWLANState() != WLANInfo.WLAN_STATE_CONNECTED && DataServices.isDataServicesEnabled() == false

To obtain the reason the request is not fulfilled, invoke LocatorException.getErrorCode().

MapServiceException - if the LBS Map API is not installed on the BlackBerry device or if an application makes more than one request at a time.
IllegalThreadStateException - if a request is made on the event dispatch thread.
IllegalStateException - thrown if there is no valid radio/wi-fi connection to send the request to.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 5.0.0

geocode

public static Landmark[] geocode(String freeformString,
                                 Coordinates startCoords)
                          throws LocatorException
Starts a request for geocode information using a non-formatted String as input.
For example: 'Paris', '10 Downing St London UK', '90210 USA' are valid search requests.

Parameters:
freeformString - the search String used as input into a request for geocode information.
startCoords - hint Coordinates for starting the search specified in a request. This request uses this data to refine the starting point. This parameter can be null.
Returns:
array of Landmarks: the first array element contains the most relevant Landmark to the locator request. May be null if the geocode request is cancelled.
Throws:
LocatorException - if no valid connection exists (i.e. The BlackBerry device is not sufficiently connected to send or receive over any transport.)

One of the following will be true if this is the case:

  • RadioInfo.getActiveWAFs() == 0
  • CoverageInfo.isCoverageSufficient(CoverageInfo.TRANSPORT_ANY, null) == false
  • WLANInfo.getWLANState() != WLANInfo.WLAN_STATE_CONNECTED && DataServices.isDataServicesEnabled() == false

To obtain the reason the request is not fulfilled, invoke LocatorException.getErrorCode().

MapServiceException - if the LBS Map API is not installed on a BlackBerry device or if an application makes more than one request at a time.
IllegalThreadStateException - if a request is made on the event dispatch thread.
IllegalStateException - thrown if there is no valid radio/wi-fi connection to send the request to.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.6.0

reverseGeocode

public static Landmark[] reverseGeocode(Coordinates coord,
                                        int searchType)
                                 throws LocatorException
Starts a request for reverse GeoCoding using a Coordinates object. The request will block till it is finished, cancelled or it times out.

Parameters:
coord - Should contain at least the lat and long
searchType - The type of the search to perform, one of: ADDRESS, COUNTRY, PROVINCE_STATE, or CITY.
Returns:
An array of Landmarks is returned.
Throws:
LocatorException - If the request could not be fulfilled. To obtain the reason the request is not fulfilled, invoke LocatorException.getErrorCode().
IllegalThreadStateException - if a request is made on the event dispatch thread.
IllegalStateException - thrown if there is no valid radio/wi-fi connection to send the request to.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 5.0.0

reverseGeocode

public static Landmark[] reverseGeocode(int latitude,
                                        int longitude,
                                        int searchType)
                                 throws LocatorException
Starts a request for reverse GeoCoding using a Latitude & Longitude, Admin Bounding Box. The request will block till it is finished, cancelled or it times out.

Parameters:
latitude - The latitude of the address to reverse geocode.
longitude - The longitude of the address to reverse geocode.
coord - Should contain at least the latitude and longitude.
searchType - The type of the search to perform, one of: ADDRESS, COUNTRY, PROVINCE_STATE, or CITY.
Returns:
An array of Landmarks is returned.
Throws:
LocatorException - If the request could not be fulfilled. To obtain the reason the request is not fulfilled, invoke LocatorException.getErrorCode().
IllegalThreadStateException - if a request is made on the event dispatch thread.
IllegalStateException - thrown if there is no valid radio/wi-fi connection to send the request to.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 5.0.0

cancel

public static void cancel()
Cancels the Locator request for the calling application process.

Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.6.0





Copyright 1999-2010 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.