net.rim.device.api.lbs.travel
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.

Overview

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.

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.

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.

Requests limit

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.

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.

getInstance

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 6.0.0

requestArrivalEstimate

Asynchronously provides an estimated travel time between the two
specified points at the specified date and time. The call will return
immediately and all results are communicated through the specified
listener.

Parameters:

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.

Returns:

An object which can be used to monitor and manage the travel time request.

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 6.0.0

requestArrivalEstimate

Synchronously provides an estimated travel time between the two specified
points at the specified date and time. This synchronous call
call involves network communication which can block the calling thread
for a significant amount of time. It must not be called on the event
dispatch thread or an IllegalThreadStateException will be thrown.

Parameters:

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.

Returns:

An object providing the estimated elapsed travel time and
distance along the route from the starting point to the ending point.
The returned object also provides access to the
input parameters (for example, start and end coordinates).

Throws:

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.

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.