javax.microedition.location.services
Class Route

java.lang.Object
  javax.microedition.location.services.Route

public class Route
extends java.lang.Object

This class represents a route. A route consists of one or more route segments combined in the course of travel. A route has a summary, length and estimated traveling time. A Route object also contains an array of RouteSegment objects that form the actual route.

Since:

2.0

Constructor Summary

Route(RouteSegment[] segments, java.lang.String summary)
Constructor that generates a Route object with the given route segments.

Method Summary

boolean	equals(java.lang.Object obj) Overriding the equals method in Object class to compare the equality of values in two Route objects.
Coordinates	getDestinationPoint() Returns the coordinates of the destination point of the route.
RectangleGeographicArea	getGeographicArea() Returns the RectangleGeographicArea of the route.
double	getLength() Returns the length of the route.
RouteSegment[]	getSegments() Returns the segments of the route.
Coordinates	getStartingPoint() Returns the coordinates of the starting point of the route.
java.lang.String	getSummary() Returns the summary of the route.
long	getTravelTime() Returns the estimated time it takes to travel the route.
int	hashCode() Overriding the hashCode method in Object class.
java.lang.Boolean	incursCosts() Method to check if traveling the route incurs cost to the user.
void	setSegments(RouteSegment[] segments) Sets the segments for the route.
void	setSummary(java.lang.String summary) Sets the summary for the route.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Route

public Route(RouteSegment[] segments,
             java.lang.String summary)

Constructor that generates a Route object with the given route segments. A Route must contain at least one segment. The first coordinate in the first segment is the starting point and the last coordinate in the last segment is the destination point of the route. An application may also provide a summary for the route. It may be null.

The API implementation must validate that the provided route segments form a consistent route. This means that the end point of a segment must be the starting point of the next segment. If this is not the case, an IllegalArgumentException is thrown.

Parameters:

segments - the segments of the route

summary - the route summary, may be null

Throws:

java.lang.IllegalArgumentException - if segments is empty or if segments do not form a consistent route

java.lang.NullPointerException - if segments is null or if segments contains null elements

Method Detail

getLength

public double getLength()

Returns the length of the route. This length must be the sum of lengths of the route segments. The length is given in meters. If conversion to some other length unit is needed, the application itself is responsible for that.

Returns:

the route length in meters

getSegments

public RouteSegment[] getSegments()

Returns the segments of the route. The segments must be ordered from the starting point to the destination so that they form a continuous route. The returned RouteSegment objects contain more information about the segment, like geometry of the segment. A route must contain at least one segment. The order of the segments is significant.

Returns:

an array of RouteSegment objects for the route segments

setSegments

public void setSegments(RouteSegment[] segments)

Sets the segments for the route. This method overrides the previously set route segments. The order of the segments is significant.

The API implementation must validate that the provided route segments form a consistent route. This means that the end point of a segment must be the starting point of the next segment. If this is not the case, an IllegalArgumentException is thrown.

Parameters:

segments - the route segments of the route

Throws:

java.lang.IllegalArgumentException - if segments is empty or if segments do not form a consistent route

java.lang.NullPointerException - if segments is null or if segments contains null elements

getSummary

public java.lang.String getSummary()

Returns the summary of the route. This summary describes the route in general. This summary may be shown to the user. If traveling the route creates cost to the user, the navigation service provider may indicate detailed information about the costs in this summary. The RouteSegment objects in the route contain descriptions about the segments.

If this Route object has been generated by a navigation service provider, the summary must be returned in the language set for the service provider.

Returns:

route summary, null if no summary is available

setSummary

public void setSummary(java.lang.String summary)

Sets the summary for the route. The summary describes the route in general and is typically presented to the user by the application. The RouteSegment objects in the route contain descriptions about the segments.

Parameters:

summary - the route summary, may be null

getTravelTime

public long getTravelTime()

Returns the estimated time it takes to travel the route. The return value must be the sum of travel times of the route segments. The time is given is seconds. If this object is created by the application, the API implementation must calculate the travel time from the travel times of the route segments. If the travel time for some of the segments is not available, this method returns -1. In this case the application may query the travel times from each segment.

Returns:

estimated traveling time of the route in seconds, -1 if travel time is not available for all route segments

getGeographicArea

public RectangleGeographicArea getGeographicArea()

Returns the RectangleGeographicArea of the route. The geographic area is the smallest rectangle that can be drawn around the route.

This information can also be used, for example, to request relevant events or locations in the specified area or to request map of the route segment to be drawn.

Returns:

a RectangleGeographicArea objects that represents an area that contains the route

getStartingPoint

public Coordinates getStartingPoint()

Returns the coordinates of the starting point of the route. The starting point is the first coordinate in the first route segment.

Returns:

the starting point coordinates

getDestinationPoint

public Coordinates getDestinationPoint()

Returns the coordinates of the destination point of the route. The destination point is the last coordinate in the last route segment.

Returns:

the destination point coordinates

incursCosts

public java.lang.Boolean incursCosts()

Method to check if traveling the route incurs cost to the user. The cost may be created, for example, from a toll road or bridge. The method must return Boolean.TRUE, if traveling any of the route segments incurs cost. If none of the route segments incurs cost, this method must return Boolean.FALSE. This method must return null, if cost for some segments is not known and the other segments do not incur cost. If the navigation service provider wants to specify more detailed costs, it may include this information to the route summary.

Returns:

Boolean.TRUE if traveling the route incurs cost, Boolean.FALSE if no cost incurs or null if information is not available

equals

public boolean equals(java.lang.Object obj)

Overriding the equals method in Object class to compare the equality of values in two Route objects. Two Route objects re equal, if the fields and route segments of the route are equal.

Overrides:

equals in class java.lang.Object

Parameters:

obj - object to which the comparison is done

Returns:

true if all fields in the objects are equal, else false

hashCode

public int hashCode()

Overriding the hashCode method in Object class. The method returns a hash code value for the route object. Two Route objects that are equal must have the same hash code. For more information see java.lang.Object.hashCode() method.

Overrides:

hashCode in class java.lang.Object

Returns:

the hash code of the coordinates