|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
java.lang.Objectnet.rim.device.api.lbs.travel.TravelTimeEstimator
public final class TravelTimeEstimator
Provides the capability to obtain an estimate of the time it will take to travel between two points on a given date and time. Currently, the Travel Time API only provides estimates for automobile travel in the United States and Canada.
A request for a travel time estimate is forwarded to a remote Travel Time server, which determines a route between the starting and ending points and then uses live and historical traffic information to compute a travel time estimate. The travel starting time is used to ensure that the estimate reflects the conditions on the specified date and time.
All starting and ending points are expressed as
Coordinates objects. To obtain
Coordinates from a Locator service
Landmark object, call the Landmark.getQualifiedCoordinates()
method. To obtain Coordinates from a Location object,
call the Location.getQualifiedCoordinates() method.
The TravelTimeEstimator is a singleton that provides a travel time estimate
in either a synchronous or asynchronous manner. The synchronous method blocks
execution on the current thread until it either returns the travel time
estimate or throws an exception. Because it blocks the caller, the
synchronous method must not be called from the event dispatch thread. The
asynchronous method can be called from any thread because it returns
immediately after sending off a request for an estimate. The results are
returned asynchronously to a listener object that is provided by the caller.
In all cases, the travel time estimate is delivered using an instance of the
TravelTime class. The methods of the TravelTimeEstimator class are thread
safe.
A typical asynchronous call would use the following pattern:
public class MyClass {
...
public void findTravelTime() {
...
TravelTimeEstimator estimator = TravelTimeEstimator.getInstance();
try {
estimator.requestArrivalEstimate(start, end, TravelTime.START_NOW,
null, new TravelTimeListener() {
public onSuccess(TravelTime travelTime) {
// If you need to interact with the event thread
// (e.g. updating a LabelField), use invokeLater or
// invokeAndWait.
Application.getApplication().invokeLater(new Runnable() {
public void run() {
// Do something with the travel time estimate.
...
}
});
}
public onFailure(TravelTimeException e) {
// If you need to interact with the event thread
// (e.g. displaying an error dialog), use invokeLater
// or invokeAndWait.
Application.getApplication().invokeLater(new Runnable() {
public void run() {
// Handle the error.
...
}
});
}
});
} catch (TravelTimeException e) {
// Handle the error.
...
}
}
...
}
Note: The methods in the TravelTimeListener are called from a separate
worker thread. Any communication with the event thread (for example, calling a method
on a UI field) must be done using the Application.invokeLater or
Application.invokeAndWait method.
A typical synchronous call would use the following pattern:
public class MyClass extends Thread {
...
// Call the synchronous method from a separate thread since it blocks.
public void run() {
TravelTimeEstimator estimator = TravelTimeEstimator.getInstance();
try {
TravelTime travelTime =
estimator.requestArrivalEstimate(start, end,
TravelTime.START_NOW, null);
// Do something with the travel time estimate.
...
} catch (TravelTimeException e) {
// Handle the error.
...
}
}
...
}
There is a system limit on the number of travel time estimate requests that
can be pending at one time. If that limit is exceeded, a
TravelTimeException is thrown with the error code
TravelTimeException.REQUEST_MAX_PENDING_EXCEEDED. In addition,
multiple estimate requests made within a two-minute period using the same
set of parameter values (for example, starting and ending positions, start time) will return
the same cached estimate.
TravelTime| Method Summary | ||
|---|---|---|
|
static TravelTimeEstimator |
getInstance()
Retrieves the singleton instance of the TravelTimeEstimator. |
|
TravelTime |
requestArrivalEstimate(Coordinates start,
Coordinates end,
long startTime,
TravelTimeOptions options)
Synchronously provides an estimated travel time between the two specified points at the specified date and time. |
|
TravelTimeRequest |
requestArrivalEstimate(Coordinates start,
Coordinates end,
long startTime,
TravelTimeOptions options,
TravelTimeListener listener)
Asynchronously provides an estimated travel time between the two specified points at the specified date and time. |
| Methods inherited from class java.lang.Object |
|---|
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
| Method Detail |
|---|
public static TravelTimeEstimator getInstance()
public TravelTimeRequest requestArrivalEstimate(Coordinates start,
Coordinates end,
long startTime,
TravelTimeOptions options,
TravelTimeListener listener)
throws TravelTimeException
start - The starting point. Once this method has been called,
subsequent changes to this object will not affect the results.end - The destination point. Once this method has been called,
subsequent changes to this object will not affect the results.startTime - Time at which travel is to start. The value is the
number of milliseconds since January 1, 1970, 00:00:00 GMT, which is
the value returned by the java.util.Date.getTime() method.
To indicate that travel will start immediately, pass TravelTime.START_NOW.options - Optional settings for the travel time request or null
if there are no optional settings. Once this method has been
called, subsequent changes to this object will not effect the results.listener - The object that will receive either the estimated travel
time information or an error notification. The methods
of this listener are called on a worker thread, so any communication
from this thread to the event thread must be done using either
Application.invokeLater
or Application.invokeAndWait.
TravelTimeException - If there was a problem creating the travel time
request.
IllegalArgumentException - If start, end
or listener is null, or if
startTime is negative.
public TravelTime requestArrivalEstimate(Coordinates start,
Coordinates end,
long startTime,
TravelTimeOptions options)
throws TravelTimeException
IllegalThreadStateException will be thrown.
start - The starting point. Once this method has been called,
subsequent changes to this object will not effect the results.end - The destination point. Once this method has been called,
subsequent changes to this object will not effect the results.startTime - Time at which travel is to start. The value is the
number of milliseconds since January 1, 1970, 00:00:00 GMT, which is
the value returned by the java.util.Date.getTime() method.
To indicate that travel will start immediately, pass TravelTime.START_NOW.options - Optional settings for the travel time request or null
if there are no optional settings. Once this method has been
called, subsequent changes to this object will not effect the results.
TravelTimeException - If the estimate request could not be
completed due to a network communication issue or due to incorrect usage
of the Travel Time API.
IllegalThreadStateException - If the estimate request is made on
the event dispatch thread.
IllegalArgumentException - If start or
end is null, or startTime
is negative.
|
|||||||||
| 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.