|
|||||||||
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 start time or end 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() { // Arrive two hours from now. long desiredArrivalTime = System.currentTimeMillis() + 2 * 60 * 60 * 1000; TravelTimeEstimator estimator = TravelTimeEstimator.getInstance(); try { TravelTime travelTime = estimator.requestDepartureEstimate(start, end, desiredArrivalTime, 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 starting 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 starting the specified date and time. |
|
TravelTime |
requestDepartureEstimate(Coordinates start,
Coordinates end,
long endTime,
TravelTimeOptions options)
Synchronously provides an estimated travel time between the two specified points ending at the specified date and time. |
|
TravelTimeRequest |
requestDepartureEstimate(Coordinates start,
Coordinates end,
long endTime,
TravelTimeOptions options,
TravelTimeListener listener)
Asynchronously provides an estimated travel time between the two specified points ending 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.public TravelTimeRequest requestDepartureEstimate(Coordinates start, Coordinates end, long endTime, 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.endTime
- Time at which to arrive at the destination. 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. The
value must be greater than zero. Depending on the specified end time
and the trip duration, the estimated departure time may be in the
past.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
endTime
is less than or equal to zero.public TravelTime requestDepartureEstimate(Coordinates start, Coordinates end, long endTime, 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.endTime
- Time at which to arrive at the destination. 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. The
value must be greater than zero. Depending on the specified end time
and the trip duration, the estimated departure time may be in the
past.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 endTime
is less than or equal
to zero.
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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