Class RouteTracker
- java.lang.Object
-
- com.esri.arcgisruntime.navigation.RouteTracker
-
public final class RouteTracker extends java.lang.Object
Uses a location to provide status and progress updates as a route is traversed (by a moving vehicle, for example).Instances of this class represent methods for processing navigation. The basic workflow:
- Create a new
RouteTracker
instance. - Enable rerouting with
enableReroutingAsync(ReroutingParameters)
, if supported by the underlying route service. - Use
trackLocationAsync(LocationDataSource.Location)
to track the Location of the device. - Subscribe to
RouteTracker.TrackingStatusChangedListener
to get theTrackingStatus
as the location changes. - Subscribe to
RouteTracker.NewVoiceGuidanceListener
to get theVoiceGuidance
whenever new instructions are available. - If there are multiple stops, call
switchToNextDestinationAsync()
each timeDestinationStatus.REACHED
status is returned. Before callingswitchToNextDestinationAsync()
, make sure thatTrackingStatus.getRemainingDestinationCount()
> 1. A value of 1 means the last destination is being approached and there are no other destinations to switch to.
- Since:
- 100.6.0
- Create a new
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
RouteTracker.NewVoiceGuidanceEvent
The new voice guidance event.static interface
RouteTracker.NewVoiceGuidanceListener
A listener that is notified when a new voice guidance is available.static class
RouteTracker.RerouteCompletedEvent
The reroute completed event.static interface
RouteTracker.RerouteCompletedListener
A listener that is notified when the route tracker completes rerouting.static class
RouteTracker.RerouteStartedEvent
The reroute started event.static interface
RouteTracker.RerouteStartedListener
A listener that is notified when the route tracker starts rerouting.static class
RouteTracker.ReroutingStrategy
The route tracker's rerouting strategy.static class
RouteTracker.SpeechEngineReadyEvent
Called byRouteTracker
before a newRouteTracker.NewVoiceGuidanceEvent
is raised to check if the speech engine is busy.static interface
RouteTracker.SpeechEngineReadyListener
Defines the callback listener to listen to SpeechEngineReadyListener events.static class
RouteTracker.TrackingStatusChangedEvent
Tracking status changed event.static interface
RouteTracker.TrackingStatusChangedListener
A listener that is notified when the tracking status is updated.
-
Constructor Summary
Constructors Constructor Description RouteTracker(android.content.Context context, RouteResult routeResult, int routeIndex)
Deprecated.as of 100.9.0 useRouteTracker(Context, RouteResult, int, boolean)
insteadRouteTracker(android.content.Context context, RouteResult routeResult, int routeIndex, boolean skipCoincidentStops)
Creates a Route Tracker using a specific route from a route result with an option to specify treating coincident stops as a single destination.
-
Method Summary
All Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description void
addNewVoiceGuidanceListener(RouteTracker.NewVoiceGuidanceListener listener)
Adds aRouteTracker.NewVoiceGuidanceListener
to this RouteTracker.void
addRerouteCompletedListener(RouteTracker.RerouteCompletedListener listener)
Adds aRouteTracker.RerouteCompletedListener
to this RouteTracker.void
addRerouteStartedListener(RouteTracker.RerouteStartedListener listener)
Adds aRouteTracker.RerouteStartedListener
to this RouteTracker.void
addSpeechEngineReadyListener(RouteTracker.SpeechEngineReadyListener listener)
Registers the givenRouteTracker.SpeechEngineReadyListener
to be called for the status of the text-to-speech engine.void
addTrackingStatusChangedListener(RouteTracker.TrackingStatusChangedListener listener)
Adds aRouteTracker.TrackingStatusChangedListener
to this RouteTracker.void
cancelRerouting()
Cancels a running reroute task.void
disableRerouting()
Disables automatic rerouting functionality of route tracker.ListenableFuture<java.lang.Void>
enableReroutingAsync(ReroutingParameters parameters)
Enables automatic rerouting when the tracker detects an off-route status.ListenableFuture<java.lang.Void>
enableReroutingAsync(RouteTask routeTask, RouteParameters routeParameters, RouteTracker.ReroutingStrategy reroutingStrategy, boolean visitFirstStopOnStart)
Deprecated.100.11.0.VoiceGuidance
generateVoiceGuidance()
Gets the currentVoiceGuidance
object.boolean
getSkipCoincidentStops()
Indicates if multiple stops in a row at the same location should treated as one stop.TrackingStatus
getTrackingStatus()
Returns tracker status for the current location on the route.UnitSystem
getVoiceGuidanceUnitSystem()
Gets the unit system used in voice guidance commands.boolean
isReroutingEnabled()
Reports if routes are automatically regenerated when tracking status is off-route.boolean
removeNewVoiceGuidanceListener(RouteTracker.NewVoiceGuidanceListener listener)
Removes aRouteTracker.NewVoiceGuidanceListener
from this RouteTracker.boolean
removeRerouteCompletedListener(RouteTracker.RerouteCompletedListener listener)
Removes aRouteTracker.RerouteCompletedListener
from this RouteTracker.boolean
removeRerouteStartedListener(RouteTracker.RerouteStartedListener listener)
Removes aRouteTracker.RerouteStartedListener
from this RouteTracker.boolean
removeSpeechEngineReadyListener(RouteTracker.SpeechEngineReadyListener listener)
Unregisters the given SpeechEngineReadyListener that was previously added usingaddSpeechEngineReadyListener(SpeechEngineReadyListener)
.boolean
removeTrackingStatusChangedListener(RouteTracker.TrackingStatusChangedListener listener)
Removes aRouteTracker.TrackingStatusChangedListener
from this RouteTracker.void
setVoiceGuidanceUnitSystem(UnitSystem voiceGuidanceUnitSystem)
Sets the unit system used for generating voice guidance.ListenableFuture<java.lang.Void>
switchToNextDestinationAsync()
Starts tracking progress to the next destination in theRoute
.ListenableFuture<java.lang.Void>
trackLocationAsync(LocationDataSource.Location location)
Provides route tracking status relative to the provided location.
-
-
-
Constructor Detail
-
RouteTracker
@Deprecated public RouteTracker(android.content.Context context, RouteResult routeResult, int routeIndex)
Deprecated.as of 100.9.0 useRouteTracker(Context, RouteResult, int, boolean)
insteadCreates a Route Tracker. An exception is thrown if theRoute
is not found or if it lacks Stops or Directions.- Parameters:
context
- the Context in which the tracker is runningrouteResult
- the RouteResult obtained by callingRouteTask.solveRouteAsync(RouteParameters)
. The RouteResult must contain at least oneRoute
.routeIndex
- the zero-based index of theRoute
inRouteResult
to track. The Route must contain Stops and Directions.- Throws:
java.lang.IllegalArgumentException
- if context is nulljava.lang.IllegalArgumentException
- if routeResult is nullArcGISRuntimeException
- if route does not exist for given routeIndexArcGISRuntimeException
- if route does not have stopsArcGISRuntimeException
- if route does not have directions- Since:
- 100.6.0
- See Also:
RouteResult.getRoutes()
,Route.getStops()
,Route.getDirectionManeuvers()
-
RouteTracker
public RouteTracker(android.content.Context context, RouteResult routeResult, int routeIndex, boolean skipCoincidentStops)
Creates a Route Tracker using a specific route from a route result with an option to specify treating coincident stops as a single destination. An exception is thrown if theRoute
is not found or if it lacksRoute.getStops()
andRoute.getDirectionManeuvers()
.- Parameters:
context
- the Context in which the tracker is runningrouteResult
- aRouteResult
generated from route task solverouteIndex
- the integer value for which route to use in the array ofRouteResult.getRoutes()
. The array is zero-based.skipCoincidentStops
- determines if coincident stops (multiple stops in a row at the same location) should be treated as a single destination- Throws:
java.lang.IllegalArgumentException
- if context is nulljava.lang.IllegalArgumentException
- if routeResult is null- Since:
- 100.9.0
- See Also:
RouteResult
-
-
Method Detail
-
isReroutingEnabled
public boolean isReroutingEnabled()
Reports if routes are automatically regenerated when tracking status is off-route.- Returns:
true
if rerouting is enabled, otherwisefalse
- Since:
- 100.6.0
- See Also:
enableReroutingAsync(ReroutingParameters)
,disableRerouting()
-
getTrackingStatus
public TrackingStatus getTrackingStatus()
Returns tracker status for the current location on the route.- Returns:
- the tracking status, null if
trackLocationAsync(LocationDataSource.Location)
was never called - Since:
- 100.6.0
-
getVoiceGuidanceUnitSystem
public UnitSystem getVoiceGuidanceUnitSystem()
Gets the unit system used in voice guidance commands.Default value is
UnitSystem.METRIC
. Supported values areUnitSystem.METRIC
andUnitSystem.IMPERIAL
.- Returns:
- the unit system used in voice guidance commands
- Since:
- 100.6.0
- See Also:
setVoiceGuidanceUnitSystem(UnitSystem)
-
setVoiceGuidanceUnitSystem
public void setVoiceGuidanceUnitSystem(UnitSystem voiceGuidanceUnitSystem)
Sets the unit system used for generating voice guidance.Supported values are
UnitSystem.METRIC
andUnitSystem.IMPERIAL
.- Parameters:
voiceGuidanceUnitSystem
- the voice guidance unit system- Throws:
java.lang.IllegalArgumentException
- if voiceGuidanceUnitSystem is null- Since:
- 100.6.0
- See Also:
getVoiceGuidanceUnitSystem()
-
getSkipCoincidentStops
public boolean getSkipCoincidentStops()
Indicates if multiple stops in a row at the same location should treated as one stop. When true, if there are multiple stops, in a row, at the same network location the new voice guidance event will fire a single time and callingRouteTracker
will skip over the other coincident stops, setting the state to the next relevant direction maneuver. If the value is false each stop will be treated as a unique destination. The default value for this property is true. If your route does not have coincident stops the value of this property will have no effect.- Returns:
- true if multiple stops in a row at the same location should treated as one stop, false otherwise
- Since:
- 100.9.0
-
cancelRerouting
public void cancelRerouting()
Cancels a running reroute task.If rerouting is in progress, this method will interrupt the rerouting background route task process.
- Since:
- 100.6.0
-
disableRerouting
public void disableRerouting()
Disables automatic rerouting functionality of route tracker.When disabled, the rerouting tracker will not automatically recalculate a route in the case where tracking status is off-route: that is, where
TrackingStatus.isOnRoute() = false
.- Since:
- 100.6.0
- See Also:
enableReroutingAsync(ReroutingParameters)
,TrackingStatus.isOnRoute()
,isReroutingEnabled()
-
enableReroutingAsync
public ListenableFuture<java.lang.Void> enableReroutingAsync(ReroutingParameters parameters)
Enables automatic rerouting when the tracker detects an off-route status.Re-routing only occurs when the current location is off-route, but on or near the transportation network edges. For example if an off-route state is detected but the tracked location is in a parking lot, away from any transportation network edges, re-routing will not occur, and will occur only once a subsequent tracked location is on or near the transportation network edges.
- Parameters:
parameters
- aReroutingParameters
allow customizing background rerouting- Returns:
- a
ListenableFuture
that has no return value - Throws:
java.lang.IllegalArgumentException
- if parameters is null- Since:
- 100.11.0
-
enableReroutingAsync
@Deprecated public ListenableFuture<java.lang.Void> enableReroutingAsync(RouteTask routeTask, RouteParameters routeParameters, RouteTracker.ReroutingStrategy reroutingStrategy, boolean visitFirstStopOnStart)
Deprecated.100.11.0. Replaced withenableReroutingAsync(ReroutingParameters)
Enables automatic rerouting when the tracker detects an off-route status.Rerouting is initiated automatically when the tracking status is off-route (In general, when vehicle
TrackingStatus.isOnRoute()
= false). In order to be considered off-route, the location must be on the transportation network as well as off the current route. If a tracked location is in a parking lot, for example, it is not considered off-route and rerouting will not occur. If the next location is on the network but not on the route, automatic rerouting will begin.These properties in routeParameters will be ignored:
RouteParameters.setStops(Iterable)
,RouteParameters.setStops(ArcGISFeatureTable, QueryParameters)
RouteParameters.setFindBestSequence(boolean)
RouteParameters.setOutputSpatialReference(SpatialReference)
RouteParameters.setPreserveFirstStop(boolean)
RouteParameters.setStartTime(Calendar)
RouteParameters.setReturnDirections(boolean)
RouteParameters.setReturnStops(boolean)
RouteParameters.setReturnRoutes(boolean)
- Parameters:
routeTask
- ARouteTask
capable of solving routes on the same network used by the original route. This is usually the same RouteTask that was used to create the route being tracked. The RouteTask will be used for rerouting in background thread.routeParameters
- a RouteParameters object that defines parameters for the rerouting RouteTask.reroutingStrategy
- a rerouting strategy that determines how new routes are created (to the next waypoint by default)*visitFirstStopOnStart
- iftrue
, vehicle must visit first stop of the route when rerouted; iffalse
, vehicle will be tracked to second stop. False by default.- Returns:
- empty future, which shows when enabling is finished
- Throws:
java.lang.IllegalArgumentException
- if routeTask is nulljava.lang.IllegalArgumentException
- if routeParameters is nulljava.lang.IllegalArgumentException
- if reroutingStrategy is nullArcGISRuntimeException
- if travelMode in routeParameters has invalid values for time, distance and impedance attributes- Since:
- 100.6.0
- See Also:
TravelMode.setDistanceAttributeName(String)
,TravelMode.setTimeAttributeName(String)
,TravelMode.setImpedanceAttributeName(String)
-
generateVoiceGuidance
public VoiceGuidance generateVoiceGuidance()
Gets the currentVoiceGuidance
object.The most recent voice guidance based on last
Location
that was passed totrackLocationAsync(LocationDataSource.Location)
. Can be used to repeat last/latest voice guidance, where distances will be based on current location.- Returns:
- the voice guidance
- Since:
- 100.6.0
-
switchToNextDestinationAsync
public ListenableFuture<java.lang.Void> switchToNextDestinationAsync()
Starts tracking progress to the next destination in theRoute
.Use
switchToNextDestinationAsync()
when the tracker reportsDestinationStatus.REACHED
status. Before callingswitchToNextDestinationAsync()
, make sure thatTrackingStatus.getRemainingDestinationCount()
> 1. A value of 1 means navigation is proceeding to last destination. This method can also be called afterDestinationStatus.APPROACHING
is raised in cases where the Location cannot get near enough to the destination point forDestinationStatus.REACHED
to be raised (such as the center of a park or shopping center).- Returns:
- future that has no return value
- Throws:
ArcGISRuntimeException
- if next destination does not exist- Since:
- 100.6.0
-
trackLocationAsync
public ListenableFuture<java.lang.Void> trackLocationAsync(LocationDataSource.Location location)
Provides route tracking status relative to the provided location.The location generally comes from a GPS but may also be a simulated or manually entered location. It must have valid values for X and Y coordinates, speed (in meters per second), course (in degrees), and a timestamp.
Events fired for
RouteTracker
when completed.- Parameters:
location
- A location used to evaluate status and progress along the route- Returns:
- future that has no return value
- Throws:
java.lang.IllegalArgumentException
- if location is null- Since:
- 100.6.0
-
addNewVoiceGuidanceListener
public void addNewVoiceGuidanceListener(RouteTracker.NewVoiceGuidanceListener listener)
Adds aRouteTracker.NewVoiceGuidanceListener
to this RouteTracker.- Parameters:
listener
- aRouteTracker.NewVoiceGuidanceListener
that gets called when a new voice guidance is available- Throws:
java.lang.IllegalArgumentException
- if the listener is null- Since:
- 100.6.0
-
removeNewVoiceGuidanceListener
public boolean removeNewVoiceGuidanceListener(RouteTracker.NewVoiceGuidanceListener listener)
Removes aRouteTracker.NewVoiceGuidanceListener
from this RouteTracker.- Parameters:
listener
- theRouteTracker.NewVoiceGuidanceListener
to remove- Returns:
true
if theRouteTracker.NewVoiceGuidanceListener
has been removed, otherwisefalse
- Throws:
java.lang.IllegalArgumentException
- if the listener is null- Since:
- 100.6.0
-
addRerouteCompletedListener
public void addRerouteCompletedListener(RouteTracker.RerouteCompletedListener listener)
Adds aRouteTracker.RerouteCompletedListener
to this RouteTracker.- Parameters:
listener
- aRouteTracker.RerouteCompletedListener
that gets called when a reroute finishes- Throws:
java.lang.IllegalArgumentException
- if the listener is null- Since:
- 100.6.0
-
removeRerouteCompletedListener
public boolean removeRerouteCompletedListener(RouteTracker.RerouteCompletedListener listener)
Removes aRouteTracker.RerouteCompletedListener
from this RouteTracker.- Parameters:
listener
- theRouteTracker.RerouteCompletedListener
to remove- Returns:
true
if theRouteTracker.RerouteCompletedListener
has been removed, otherwisefalse
- Throws:
java.lang.IllegalArgumentException
- if the listener is null- Since:
- 100.6.0
-
addRerouteStartedListener
public void addRerouteStartedListener(RouteTracker.RerouteStartedListener listener)
Adds aRouteTracker.RerouteStartedListener
to this RouteTracker.- Parameters:
listener
- aRouteTracker.RerouteStartedListener
that gets called when a reroute starts- Throws:
java.lang.IllegalArgumentException
- if the listener is null- Since:
- 100.6.0
-
removeRerouteStartedListener
public boolean removeRerouteStartedListener(RouteTracker.RerouteStartedListener listener)
Removes aRouteTracker.RerouteStartedListener
from this RouteTracker.- Parameters:
listener
- theRouteTracker.RerouteStartedListener
to remove- Returns:
true
if theRouteTracker.RerouteStartedListener
has been removed, otherwisefalse
- Throws:
java.lang.IllegalArgumentException
- if the listener is null- Since:
- 100.6.0
-
addTrackingStatusChangedListener
public void addTrackingStatusChangedListener(RouteTracker.TrackingStatusChangedListener listener)
Adds aRouteTracker.TrackingStatusChangedListener
to this RouteTracker.- Parameters:
listener
- aRouteTracker.TrackingStatusChangedListener
that gets called when the route tracking status changes- Throws:
java.lang.IllegalArgumentException
- if the listener is null- Since:
- 100.6.0
-
removeTrackingStatusChangedListener
public boolean removeTrackingStatusChangedListener(RouteTracker.TrackingStatusChangedListener listener)
Removes aRouteTracker.TrackingStatusChangedListener
from this RouteTracker.- Parameters:
listener
- theRouteTracker.TrackingStatusChangedListener
to remove- Returns:
true
if theRouteTracker.TrackingStatusChangedListener
has been removed, otherwisefalse
- Throws:
java.lang.IllegalArgumentException
- if the listener is null- Since:
- 100.6.0
-
addSpeechEngineReadyListener
public void addSpeechEngineReadyListener(RouteTracker.SpeechEngineReadyListener listener)
Registers the givenRouteTracker.SpeechEngineReadyListener
to be called for the status of the text-to-speech engine.If the the Android
TextToSpeech
engine is used, use:setSpeechEngineReady(!textToSpeech.isSpeaking())
because the TTS engine is ready until it is done speaking.
Adding this listener on the UI thread will cause it to be invoked on the UI thread, otherwise it is not guaranteed on which thread the listener is invoked.
- Parameters:
listener
- the listener to register- Throws:
java.lang.IllegalArgumentException
- if the listener is null- Since:
- 100.12.0
- See Also:
removeSpeechEngineReadyListener(SpeechEngineReadyListener)
-
removeSpeechEngineReadyListener
public boolean removeSpeechEngineReadyListener(RouteTracker.SpeechEngineReadyListener listener)
Unregisters the given SpeechEngineReadyListener that was previously added usingaddSpeechEngineReadyListener(SpeechEngineReadyListener)
.- Parameters:
listener
- the listener to unregister- Returns:
- true if the listener was successfully removed; false otherwise
- Since:
- 100.12.0
-
-