net.rim.device.api.lbs.travel
Class TravelTimeEstimator

java.lang.Object
  net.rim.device.api.lbs.travel.TravelTimeEstimator

public final class TravelTimeEstimator
extends Object

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 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.

Code sample: Using an asynchronous call to retrieve an arrival estimate

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.

Code sample: Using a synchronous call to retrieve a departure estimate

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.
             ...
         }
     }
     ...
 }
 

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.

See Also:

TravelTime

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 6.0.0

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

getInstance

public static TravelTimeEstimator getInstance()

Retrieves the singleton instance of the TravelTimeEstimator.

Returns:

The singleton instance of the TravelTimeEstimator.

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 6.0.0

requestArrivalEstimate

public TravelTimeRequest requestArrivalEstimate(Coordinates start,
                                                Coordinates end,
                                                long startTime,
                                                TravelTimeOptions options,
                                                TravelTimeListener listener)
                                         throws TravelTimeException

Asynchronously provides an estimated travel time between the two specified points starting 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.

Throws:

TravelTimeException - If there was a problem creating the travel time request.

IllegalArgumentException - If start, end or listener is null, or if startTime is negative.

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 6.0.0

requestArrivalEstimate

public TravelTime requestArrivalEstimate(Coordinates start,
                                         Coordinates end,
                                         long startTime,
                                         TravelTimeOptions options)
                                  throws TravelTimeException

Synchronously provides an estimated travel time between the two specified points starting 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.

IllegalThreadStateException - If the estimate request is made on the event dispatch thread.

IllegalArgumentException - If start or end is null, or startTime is negative.

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 6.0.0

requestDepartureEstimate

public TravelTimeRequest requestDepartureEstimate(Coordinates start,
                                                  Coordinates end,
                                                  long endTime,
                                                  TravelTimeOptions options,
                                                  TravelTimeListener listener)
                                           throws TravelTimeException

Asynchronously provides an estimated travel time between the two specified points ending 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.

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.

Returns:

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

Throws:

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.

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 7.0.0

requestDepartureEstimate

public TravelTime requestDepartureEstimate(Coordinates start,
                                           Coordinates end,
                                           long endTime,
                                           TravelTimeOptions options)
                                    throws TravelTimeException

Synchronously provides an estimated travel time between the two specified points ending 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.

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.

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.

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.

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 7.0.0