Routing (v2.1.x - Android)

1 CREATING ROUTING MANAGER
2 ROUTING MANAGER BASICS
- 2.1 Sample: routing manager request handling
3 CALCULATING ROUTES
- 3.1 CALCULATING A ROUTE USING ROUTE PLAN
  - 3.1.1 Sample: creating route plan from map coordinates and current position
4 ROUTING SERVICE SETTINGS
- 4.1 Enabling calculation of navigation directions

The core component of Navmii SDK responsible for route calculation is RoutingManager. This class provides the API for calculating new routes and snapping external routes to the map.

CREATING ROUTING MANAGER

Sdk class contains getRoutingManager method which allows Navmii SDK user to access routing manager instance. The routing manager instance can only be created after the SDK was started.

ROUTING MANAGER BASICS

Routing manager can be used to calculate new routes or to snap external routes to the map. Routing manager handles both processes in the same way.

Successful route calculation or snapping result is the route or the list of routes each of which is represented by Route class instance. Those routes can be used by other SDK modules: they can be rendered on map or used for navigation.

Once routing service is requested to calculate or snap a route, it returns a route calculation session represented by RouteCalculationSession class instance. Route calculation session is the routing manager request handler which is used to control the request.

Since session is the only way to control the associated calculation request, the user of the routing service should NOT release the session object until the request finishes.

RouteCalculationSession class instances are passive objects which you can use to request the current status and successful or failure info. You can also use it to cancel the request. In order to get the request status change notifications you can specify an object conforming to the RouteCalculationListener withing the request to the routing manager.

Basically the route calculation request can be in two states: in progress or finished. Route calculation session's hasFinished method indicates the state.

Once you requested a new route calculation or snapping by calling the corresponding routing manager method and got the session instance back, route calculation starts. At this moment session's hasFinished method, as well as wasCanceled, hasSucceeded and hasFailed, returns false.

The request can become finished due to the following reasons:

route calculation has succeeded. Session's hasFinished method, as well as hasSucceeded, returns true. wasCanceled and hasFailed methods return false. getResult returns valid non-null request result. Route calculation listener's onRouteCalculationSucceeded is called while session transits to this state.
route calculation has failed. Session's hasFinished method, as well as hasFailed, returns true wasCanceled and hasSucceeded methods return false. failureInfo returns valid non-null request failure info. Route calculation listener's onRouteCalculationFailed is called while session transits to this state.
route calculation was canceled by user by calling session's cancel method. Session's hasFinished method, as well as wasCanceled, returns true. hasSucceeded and hasFailed methods return false. Please note that request can only be canceled if it hasn't finished by the moment cancel method is called. Canceling the finished session doesn't affect the request state.

As mentioned before, routing manager uses RouteCalculationListener to notify user about route calculation status changes. RouteCalculationListener contains three methods:

onRouteCalculationSucceeded is called once route calculation succeeded. result parameter contains valid non-null route calculation results. The fact that the method was called means the route calculation process had completely finished, therefore user won't receive any other notifications on its status changes.
onRouteCalculationFailed is called once route calculation failed. info parameter contains valid non-null route failure info. The fact that the method was called means the route calculation process had completely finished, therefore user won't receive any other notifications on its status changes.
onNonFatalRouteCalculationErrorOccurred is called once a non-fatal route error occurs during the route calculation. A non-fatal error is an error which does not result in route calculation process interruption. An example of such an error is a network error during an attempt to access routing or map tile server. error parameter contains an error code describing the reason the method was called. The call is just a notification to the SDK user that something went wrong during the route calculation process. Since the fact that the method was called does NOT mean the route calculation process had completely finished, user should expect to see other notifications on route calculation status update.

Here is an example of route calculation request handling.

Sample: routing manager request handling

public class RouteCalculationExample {

    private final RoutingManager routingManager;

    private RouteCalculationSession routeCalculationSession;

    private final RouteCalculationListener routeCalculationListener = new RouteCalculationListener() {
        @Override
        public void onRouteCalculationSucceeded(RouteCalculationResult routeCalculationResult) {
            routeCalculationSession = null;
            // Route calculation succeeded: handling result.
        }

        @Override
        public void onRouteCalculationFailed(RouteCalculationFailureInfo routeCalculationFailureInfo) {
            routeCalculationSession = null;
            // Route calculation failed: handling failure info.
        }

        @Override
        public void onNonFatalRouteCalculationErrorOccurred(RouteCalculationError routeCalculationError) {
            // Non-fatal route calculation error occurred: handling it. Route calculation continues.
        }
    };

    public RouteCalculationExample(Sdk sdk) {
        routingManager = sdk.getRoutingManager();
    }

    public void calculateRouteUsingRoutePlan(ArrayList<RoutePlanPoint> routePlan,
                                             RouteCalculationOptions routeCalculationOptions) {
        routeCalculationSession = routingManager.calculateRoute(
                routePlan, routeCalculationOptions, routeCalculationListener);
    }

    public void cancelRouteCalculation() {
        if (routeCalculationSession != null) {
            routeCalculationSession.cancel();
            routeCalculationSession = null;
        }
    }
}

CALCULATING ROUTES

CALCULATING A ROUTE USING ROUTE PLAN

Routing manager allows to calculate new routes using the specified route plan. A route plan is a list of waypoints represented by instances of RoutePlanPoint class. A route plan should contain at least two points.

A route plan point contains geo coordinates and optional course. Course is used by the routing engine as a hint to calculate direction to move from the point. Usually SDK users don't have such information so you don't have to specify it.

Another route plan point method is called snapped. It indicates whether the route plan point was snapped to the map by Navmii SDK. SDK users do NOT have a way to construct the snapped route plan point other then to construct it from a snapped position returned by another SDK module. The SDK returns positions as Position class instances. The class has the isSnapped method as well. A route plan point will be considered as snapped if only constructed from a snapped position. In this case snapped route plan point will have course set as well.

All that means that it's enough to have geo coordinates for the second and further route plan points. Nevertheless there are options for the first point. If you need to calculate a route from the current position, the preferred way to do this is to use the snapped current position to construct the first route plan point. If however you need to calculate a route starting from some random geo location, geo coordinates would be enough to construct the first route plan point.

Use snapped current position provided by Navmii SDK to construct the first route plan point if you need to calculate a route from current position. Use just coordinates to construct the first route plan point if you need to calculate route starting from some random location.

Here are example methods for both cases.

Sample: creating route plan from map coordinates and current position

    public static ArrayList<RoutePlanPoint> createRoutePlanFromCoordinates(
            List<MapCoordinates> routePlanCoordinates) {

        final ArrayList<RoutePlanPoint> routePlan = new ArrayList<>();

        for (MapCoordinates coordinates : routePlanCoordinates) {
            routePlan.add(RoutePlanPoint.createWithCoordinates(coordinates));
        }

        return routePlan;
    }

    public static ArrayList<RoutePlanPoint> createRoutePlanFromCurrentPositionAndCoordinates(
            Position currentPosition,
            List<MapCoordinates> routePlanCoordinates) {

        final ArrayList<RoutePlanPoint> routePlan = new ArrayList<>();

        routePlan.add(RoutePlanPoint.createWithPosition(currentPosition));

        for (MapCoordinates coordinates : routePlanCoordinates) {
            routePlan.add(RoutePlanPoint.createWithCoordinates(coordinates));
        }

        return routePlan;
    }

ROUTING SERVICE SETTINGS

As you can see in the examples above user is able to pass route calculation options within each routing service request. The specified options are used during request handling. If no options were passed default options are used. RouteCalculationOptions class instances represent available route calculation options.

These options make it possible to fine-tune route calculation process, making it possible to:

switch before walking/driving mode (RouteCalculationOptions.setIsWalkingMode);
choose one of route optimization methods (RouteCalculationOptions.setOptimization):
- fastest;
- easiest (with the least amount of turns, crossroads and ramps);
- most economical with regard to fuel consumption;
- shortest;
choose vehicle type;
choose whether toll roads should be avoided;
choose whether traffic should be taken into account.

RouteCalculationOptions class also contains a method called setBuildAllDirections(bool), which can be used to enable calculation of navigation directions for the entire route during the routing process. When this feature is enabled, directions can be accessed using Route.getDirections() method.