|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectnet.rim.device.api.lbs.Locator
public final class Locator
Locator
is a geocoding service that allows you to obtain location information for an address. You can use
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 Landmark
objects.
Requests for geocode information are synchronous, but can be interrupted by invoking
Locator.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 the LBS Map API module is not installed on the BlackBerry device, requests for geocode information will throw
a MapServiceException
.
Request results are not cached on the BlackBerry device.
Freeform String geocode request
Returns to landmarkArray
an array of Landmark
objects that fit the “Waterloo” search criteria.
Landmark[] landmarkArray = Locator.geocode(“Waterloo”, null);
Field Summary | ||
---|---|---|
|
static int |
ADDRESS
Use this to request the nearest address or nearest street to the specified latitude/longitude. |
|
static int |
CITY
Use this constant for reverse geocoding so that the return value focuses on the city level. |
|
static int |
COUNTRY
Use this constant for reverse geocoding so that the return value focuses on the country level. |
|
static int |
POSTAL_ZIP_CODE
Use this to reverse geocode a latitude/longitude to a postal/zip code. |
|
static int |
PROVINCE_STATE
Use this constant for reverse geocoding so that the return value focuses on the province/state level. |
|
static int |
REQUEST_TIMEOUT
Deprecated. |
Method Summary | ||
---|---|---|
|
static void |
cancel()
Cancels the Locator request for the calling application process. |
|
static Landmark[] |
geocode(String freeformString,
Coordinates startCoords)
Starts a request for geocode information using a non-formatted String as input. |
|
static Landmark[] |
geocode(AddressInfo address,
Coordinates startCoords)
Starts a request for geocode information using an AddressInfo object as input. |
|
static Landmark[] |
reverseGeocode(int latitude,
int longitude,
int searchType)
Starts a request for reverse geocoding using the latitude, longitude, and search type. |
|
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 |
---|
public static final int REQUEST_TIMEOUT
public static final int ADDRESS
If the nearest address cannot be found, the nearest administrative region is returned. This could be a combination of city, state/province and/or country depending on if the location is inside one of these boundaries.
public static final int COUNTRY
public static final int PROVINCE_STATE
public static final int CITY
public static final int POSTAL_ZIP_CODE
Method Detail |
---|
public static Landmark[] geocode(AddressInfo address, Coordinates startCoords) throws LocatorException
AddressInfo
object as input.
address
- The AddressInfo
object to use for requesting geocoding information.
Supported fields include: STREET
, POSTAL_CODE
,
CITY
, STATE
, COUNTRY
or COUNTRY_CODE
.startCoords
- The Coordinates
for starting the search specified in the request. This is used to refine a request
from an initial location starting point. This parameter may be null
.
Landmarks
. The first array element contains the most relevant Landmark to the locator request.
LocatorException
- if the request could not be fulfilled.
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 connectivity to send the request upon.public static Landmark[] geocode(String freeformString, Coordinates startCoords) throws LocatorException
String
as input.
freeformString
- The search String
used as input to request geocode information.startCoords
- The Coordinates
for starting the search specified in a request. This request uses this data to
refine the starting point. This parameter can be null
.
Landmarks
. The first array element contains the most relevant Landmark to the locator request.
LocatorException
- if the request could not be fulfilled.
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.public static Landmark[] reverseGeocode(Coordinates coord, int searchType) throws LocatorException
Coordinates
object.
The reverse geocoding request blocks until it completes, cancels, or times out.
coord
- A Coordinates
object that contains at least the latitude and longitude.searchType
- The type of the search to perform, which can be one of the following:
ADDRESS
, COUNTRY
, PROVINCE_STATE
, POSTAL_CODE
, or CITY
.
Landmarks
.
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.public static Landmark[] reverseGeocode(int latitude, int longitude, int searchType) throws LocatorException
latitude
- The latitude of the address, specified as decimal degrees
to five decimal places, multiplied by 100000.longitude
- The longitude of the address, specified as decimal degrees
to five decimal places, multiplied by 100000.searchType
- The type of the search to perform, which can be one of the following:
ADDRESS
, COUNTRY
, PROVINCE_STATE
, POSTAL_CODE
, or CITY
.
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.public static void cancel()
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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.