Navigation fixes (#367)

* changed start and end navigation positions to origin and destination

* allow user to disable traffic when getting route

* added exceptions to getRoute method and javadoc

* added javadoc to direction methods in MapboxNavigation

* fixed issue if alert listener wasn't set application would crash

* fixed some navigation issues

* fixed a memory leak with navigation service

* fixed checkstyle issue

* added offroute listener

* checkstyle fixes

* added test to PR

Author: Cameron Mace

.gitignore

@@ -23,3 +23,6 @@ libandroid/app/src/main/res/values/developer-config.xml
 
 # Do not track signing file
 secring.gpg
+
+# Documentation files
+node_modules/

mapbox/dependencies.gradle

@@ -53,6 +53,7 @@ ext {
 
             // testing
             junit                : 'junit:junit:4.12',
+            mockito              : 'org.mockito:mockito-core:2.7.13',
             hamcrestJunit        : 'org.hamcrest:hamcrest-junit:2.0.0.0',
             supportEspresso      : 'com.android.support.test.espresso:espresso-core:2.2.2'
     ]

mapbox/libandroid-services/build.gradle

@@ -24,6 +24,10 @@ android {
             consumerProguardFiles 'proguard-rules.pro'
         }
     }
+
+    testOptions {
+        unitTests.returnDefaultValues = true
+    }
 }
 
 dependencies {
@@ -42,7 +46,11 @@ dependencies {
     compile rootProject.ext.dep.lost
 
     // Testing
+    testCompile rootProject.ext.dep.mockito
+    testCompile rootProject.ext.dep.okhttp3Mockwebserver
+    testCompile rootProject.ext.dep.hamcrestJunit
     testCompile rootProject.ext.dep.junit
+
     androidTestCompile(rootProject.ext.dep.supportEspresso, {
         exclude group: 'com.android.support', module: 'support-annotations'
     })

mapbox/libandroid-services/src/androidTest/java/com/mapbox/services/android/ExampleInstrumentedTest.java

@@ -1,11 +1,16 @@
+<?xml version="1.0" encoding="utf-8"?>
 <manifest xmlns:android="http://schemas.android.com/apk/res/android"
           package="com.mapbox.services.android">
 
-    <application android:allowBackup="true"
-                 android:label="@string/app_name"
-                 android:supportsRtl="true"
-    >
+    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
+    <uses-permission android:name="android.permission.INTERNET"/>
 
+    <application
+        android:allowBackup="true"
+        android:label="@string/app_name"
+        android:supportsRtl="true">
+
+        <service android:name="com.mapbox.services.android.navigation.v5.NavigationService"/>
     </application>
 
-</manifest>
+</manifest>

mapbox/libandroid-services/src/main/AndroidManifest.xml

@@ -4,10 +4,27 @@
 import com.mapbox.services.api.navigation.v5.RouteProgress;
 
 /**
- * This is an experimental API. Experimental APIs are quickly evolving and
- * might change or be removed in minor versions.
+ * Listening in to the alertLevelChange is useful for correctly getting the timing of user notifications while the user
+ * is traversing along the route. The listener's invoked only when the user's reached a specific point along the
+ * current step they are on. The alert thresholds can be adjusted within the constants file while developing and are
+ * based on time (in seconds) till the user reaches the next maneuver.
+ * <p>
+ * This is an experimental API. Experimental APIs are quickly evolving and might change or be removed in minor versions.
+ *
+ * @see <a href="https://www.mapbox.com/mapbox-java/#alertlevelchange">AlertLevelChange documentation</a>
+ * @since 2.0.0
  */
 @Experimental
 public interface AlertLevelChangeListener {
+
+  /**
+   * Method's invoked when the alert level has changed during the current navigation session.
+   *
+   * @param alertLevel    One of the alert level constants found in {@link com.mapbox.services.android.Constants}.
+   * @param routeProgress Provides a {@link RouteProgress} object which will contain information about the users
+   *                      current position along the route.
+   * @see <a href="https://www.mapbox.com/mapbox-java/#alertlevelchange">AlertLevelChange documentation</a>
+   * @since 2.0.0
+   */
   void onAlertLevelChange(int alertLevel, RouteProgress routeProgress);
 }

mapbox/libandroid-services/src/main/java/com/mapbox/services/android/navigation/v5/AlertLevelChangeListener.java

@@ -4,6 +4,7 @@
 import android.os.Handler;
 import android.os.HandlerThread;
 import android.os.Message;
+import android.support.annotation.VisibleForTesting;
 
 import com.mapbox.services.Experimental;
 import com.mapbox.services.android.Constants;
@@ -28,7 +29,7 @@
  * might change or be removed in minor versions.
  */
 @Experimental
-public class LocationUpdatedThread extends HandlerThread {
+class LocationUpdatedThread extends HandlerThread {
 
   private static final String TAG = "LocationUpdatedThread";
   private static final int MESSAGE_LOCATION_UPDATED = 0;
@@ -41,6 +42,8 @@ public class LocationUpdatedThread extends HandlerThread {
   private AlertLevelChangeListener alertLevelChangeListener;
   private ProgressChangeListener progressChangeListener;
   private double userDistanceToManeuverLocation;
+  private OffRouteListener offRouteListener;
+  private boolean userStillOnRoute = true;
   private boolean snapToRoute;
   private Location location;
 
@@ -64,7 +67,7 @@ void updateLocation(RouteProgress target, Location location) {
     requestHandler.obtainMessage(MESSAGE_LOCATION_UPDATED, target).sendToTarget();
   }
 
-  private void handleRequest(final RouteProgress target, Location location) {
+  private void handleRequest(final RouteProgress target, final Location location) {
     if (location == null) {
       return;
     }
@@ -85,7 +88,6 @@ private void handleRequest(final RouteProgress target, Location location) {
       List<StepIntersection> intersections = getNextIntersections(target, snappedPosition);
 
       // Test the closest intersection to the user only.
-      boolean userStillOnRoute = true;
       if (intersections.size() > 0) {
         userStillOnRoute = isUserStillOnRoute(intersections.get(0), location.getBearing());
       }
@@ -100,11 +102,19 @@ private void handleRequest(final RouteProgress target, Location location) {
       // Post back to the UI Thread.
       responseHandler.post(new Runnable() {
         public void run() {
+          if (offRouteListener != null && !userStillOnRoute) {
+            offRouteListener.userOffRoute(location);
+          }
+
           if (target.getPreviousAlertLevel() != alertLevel) {
-            target.setAlertUserLevel(alertLevel);
-            alertLevelChangeListener.onAlertLevelChange(alertLevel, target);
+            if (alertLevelChangeListener != null) {
+              target.setAlertUserLevel(alertLevel);
+              alertLevelChangeListener.onAlertLevelChange(alertLevel, target);
+            }
+          }
+          if (progressChangeListener != null) {
+            progressChangeListener.onProgressChange(LocationUpdatedThread.this.location, target);
           }
-          progressChangeListener.onProgressChange(LocationUpdatedThread.this.location, target);
         }
       });
 
@@ -121,6 +131,10 @@ void setProgressChangeListener(ProgressChangeListener progressChangeListener) {
     this.progressChangeListener = progressChangeListener;
   }
 
+  void setOffRouteListener(OffRouteListener offRouteListener) {
+    this.offRouteListener = offRouteListener;
+  }
+
   void setSnapToRoute(boolean snapToRoute) {
     this.snapToRoute = snapToRoute;
   }
@@ -209,7 +223,8 @@ private int monitorStepProgress(final RouteProgress routeProgress, Location loca
    * @throws TurfException Thrown if turf calculation error occurs.
    * @since 2.0.0
    */
-  private List<StepIntersection> getNextIntersections(RouteProgress routeProgress, Position userPosition)
+  @VisibleForTesting
+  public List<StepIntersection> getNextIntersections(RouteProgress routeProgress, Position userPosition)
     throws TurfException {
     List<StepIntersection> intersectionsWithinRange = new ArrayList<>();
     List<StepIntersection> stepIntersections = new ArrayList<>();
@@ -263,6 +278,7 @@ private List<StepIntersection> getNextIntersections(RouteProgress routeProgress,
    * @return boolean true if the user remains on the route through the intersection, else false.
    * @since 2.0.0
    */
+  @VisibleForTesting
   private boolean isUserStillOnRoute(StepIntersection intersection, double userHeading) {
     // We start off assuming the user is on route.
     boolean isOnRoute = true;