javax.microedition.location.services
Class RouteSegment

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

public class RouteSegment
extends java.lang.Object

This class represents a segment of a route. It has a start and an end coordinates. The segment also contains instructions to navigate through the it. The geometry of the segment may be other than a straight line between start and end, and this class provides a method to get the geometry. The segment also contains a description, a length and an estimated travel time.

Since:

2.0

Constructor Summary

RouteSegment(Coordinates[] geometry, NavigationInstruction[] instructions, java.lang.String description)
Constructor to create a route segment.

RouteSegment(Coordinates start, Coordinates end, NavigationInstruction[] instructions, java.lang.String description)
Constructor to create a route segment.

Method Summary

boolean	equals(java.lang.Object obj) Overriding the equals method in Object class to compare the equality of values in two RouteSegment objects.
java.lang.String	getDescription() Returns the description given for the route segment.
RectangleGeographicArea	getGeographicArea() Returns the RectangleGeographicArea of the route segment.
Coordinates[]	getGeometry() Returns the geometry of the route segment.
NavigationInstruction[]	getInstructions() Returns the navigation instructions for this route segment.
double	getLength() Returns the length of the route segment in meters.
java.lang.String	getTransportMode() Returns the transport mode for the route segment.
long	getTravelTime() Returns the estimated time it takes to travel the route segment.
int	hashCode() Overriding the hashCode method in Object class.
java.lang.Boolean	incursCosts() Method to check if traveling the route segment incurs cost to the user.
void	setDescription(java.lang.String description) Sets the description given for the route segment.
void	setGeometry(Coordinates[] geometry) Sets the geometry for the route segment.
void	setIncursCosts(java.lang.Boolean incursCosts) Method to set whether traveling the route segment creates cost to the user.
void	setInstructions(NavigationInstruction[] instructions) Sets the instructions needed to navigate the route segment.
void	setTransportMode(java.lang.String mode) Sets the transport mode for this route segment.
void	setTravelTime(long travelTime) Sets the estimated time it takes to travel the route segment.

Methods inherited from class java.lang.Object

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

Constructor Detail

RouteSegment

public RouteSegment(Coordinates start,
                    Coordinates end,
                    NavigationInstruction[] instructions,
                    java.lang.String description)

Constructor to create a route segment. The segment contains a starting point and an end point. There may also be instructions how to navigate the route segment. The instructions may be null. An application may also include a description for the route segment. The description may be null.

This method sets the travel time to -1, transport mode and incurs cost to null.

Parameters:

start - the coordinates of the starting point

end - the coordinates of the end point

instructions - instructions to navigate the route segment

description - the description of the route segment, may be null

Throws:

java.lang.NullPointerException - if start or end is null or if instructions contains null elements

RouteSegment

public RouteSegment(Coordinates[] geometry,
                    NavigationInstruction[] instructions,
                    java.lang.String description)

Constructor to create a route segment. The geometry parameter contains the geometry of the route segment. The starting point of the segment is the first element in the geometry parameter. The last element in the geometry parameter is the end point of the route segment. So the geometry parameter must contain at least two elements. There may also be instructions how to navigate the route segment. The instructions may be null. An application may also include a description for the route segment. The description may be null.

This method sets the travel time to -1, transport mode and incurs cost to null.

Parameters:

geometry - the geometry of the route segment

instructions - instructions to navigate the route segment

description - the description of the route segment, may be null

Throws:

java.lang.IllegalArgumentException - if geometry has less than 2 elements

java.lang.NullPointerException - if geometry is null or if geometry or instructions contain null elements

Method Detail

getDescription

public java.lang.String getDescription()

Returns the description given for the route segment. This description may contain some characteristics about the segment or other additional information about the route segment. This information may be shown to the user. If traveling this route segment creates cost to the user, the navigation service provider may indicate the amount of cost in this route segment description.

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

Returns:

the description of the segment, null if description has not been set

setDescription

public void setDescription(java.lang.String description)

Sets the description given for the route segment. This description may contain some characteristics about the segment or other additional information about the route segment. This information may be shown to the user.

Parameters:

description - the description of the segment, may be null

getGeometry

public Coordinates[] getGeometry()

Returns the geometry of the route segment. The geometry includes intermediate points needed to describe the geometric shape of the route segment This can be, for example, that a road between two cities is not fairly straight, but has several curves on it. The application or the service provider may add coordinates to the geometry to better depict these curves.

The geometry is formed by connecting the coordinates with the straight lines. The geometry may be a polygon, if the starting and destination points of the route segment are the same.

The API implementation must guarantee that the returned array contains enough Coordinates objects so that the geometry can be presented by connecting the coordinates with straight lines. The first item in the array must be the starting point and the last item the end point of the segment. If start and end point of the segment are the same, the method still returns at least an array of two coordinates.

Returns:

an array of Coordinates objects that form the geometry of the segment

setGeometry

public void setGeometry(Coordinates[] geometry)

Sets the geometry for the route segment. The geometry includes intermediate points needed to describe the geometric shape of the route segment. This can be, for example, that a road between two cities is not fairly straight, but has several curves on it. The given coordinates replace the geometry set for the route segment, including start and end points. The starting point of the segment is the first element in the geometry parameter and the last is the end point of the route segment. So the geometry parameter must contain at least two elements.

Parameters:

geometry - the geometry of the route segment

Throws:

java.lang.IllegalArgumentException - if geometry has less than 2 elements

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

getLength

public double getLength()

Returns the length of the route segment in meters. If conversion to some other length unit is needed, the application itself is responsible for that.

Returns:

the length of the segment in meters

getTravelTime

public long getTravelTime()

Returns the estimated time it takes to travel the route segment. The time is given in seconds.

Returns:

the estimated time of the segment in seconds, -1 if travel time is not available

setTravelTime

public void setTravelTime(long travelTime)

Sets the estimated time it takes to travel the route segment. The time is given in seconds. -1 can be used to indicate that travel time is not available.

Parameters:

travelTime - the estimated time of the segment in seconds

Throws:

java.lang.IllegalArgumentException - if travelTime < -1

getGeographicArea

public RectangleGeographicArea getGeographicArea()

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

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. The direction of the geographic area is always true north.

Returns:

a RectangleGeographicArea objects that represents an area that contains the route

getTransportMode

public java.lang.String getTransportMode()

Returns the transport mode for the route segment. If this RouteSegment object has been created by the navigation service provider, this method returns the the transport mode that the navigation service provider sees the best for this route segment. If this RouteSegment object has been created by the application, this method returns the transport mode that has been set with the setTransportMode method or null if transport mode has not been set. Possible values can be retrieved with ProviderCapabilities.getPropertyValue method using ProviderCapabilities.NAV_SUPPORTED_TRANSPORT_MODES as the key value.

Returns:

the transport that used in the route calculations by the navigation service provider or the transport mode set by the application or null if transport mode has not been set

setTransportMode

public void setTransportMode(java.lang.String mode)

Sets the transport mode for this route segment. Possible values can be retrieved with ProviderCapabilities.getPropertyValue method using ProviderCapabilities.NAV_SUPPORTED_TRANSPORT_MODES as the key value. The value is not validated.

Parameters:

mode - the transport that used in this route segment

getInstructions

public NavigationInstruction[] getInstructions()

Returns the navigation instructions for this route segment. If the instructions have been created by a navigation service provider, the usage of the instructions may be restricted by the service provider. In this case, an empty array is returned from this method.

Returns:

the instructions for navigation of this route segment, an empty array if instructions have not been set

setInstructions

public void setInstructions(NavigationInstruction[] instructions)

Sets the instructions needed to navigate the route segment. Instructions may be null.

Parameters:

instructions - instructions related to the route segment

Throws:

java.lang.NullPointerException - if instructions contains null elements

incursCosts

public java.lang.Boolean incursCosts()

Method to check if traveling the route segment incurs cost to the user. The cost may be created, for example, from a toll road or bridge. If the navigation service provider wants to specify more detailed costs, it may include this information to the route segment description. If the navigation service provider does not have the information about cost, this method must return null.

Returns:

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

setIncursCosts

public void setIncursCosts(java.lang.Boolean incursCosts)

Method to set whether traveling the route segment creates cost to the user.

Parameters:

incursCosts - Boolean.TRUE if traveling the route segment creates cost, Boolean.FALSE if no cost is created 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 RouteSegment objects. Two RouteSegment objects are equal, if the fields 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 RouteSegment 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