[android] Adding builder pattern for LocationComponent activation (#13941)

* initial additions of activation builder

* [android] refactoring LocationComponentActivationOptions based on code review

* [android] initial addition of LocationComponentActivationOptionsTest unit tests

* [android] more refactoring based on code review

* [android] refactoring test app location examples

* [android] espresso test refactor with LocationComponentActivationOptions usage

* [android] locationComponent builder instrumentation test tweaks and log removal

* [android] method and docs refactoring based @lukaspaczos 's review

* [android] locationEngine setting logic refactor

* [android] add null locationEngine to stillStaleAfterResuming test

* added .locationEngine(null) to other tests

* [android] javadocs, method, and test adjustments based on @lukaspaczos review

* [android] test tweaks based on Lukasz review

9 files changed, 209 insertions, 22 deletions

diff --git a/platform/android/MapboxGLAndroidSDKTestApp/src/main/AndroidManifest.xml b/platform/android/MapboxGLAndroidSDKTestApp/src/main/AndroidManifest.xml
index 22ae7f9824..a113fe1d6b 100644
--- a/platform/android/MapboxGLAndroidSDKTestApp/src/main/AndroidManifest.xml
+++ b/platform/android/MapboxGLAndroidSDKTestApp/src/main/AndroidManifest.xml
@@ -862,6 +862,17 @@
                 android:value=".activity.FeatureOverviewActivity" />
         </activity>
         <activity
+            android:name=".activity.location.LocationComponentActivationActivity"
+            android:description="@string/description_location_activation_builder"
+            android:label="@string/activity_location_activation_builder">
+            <meta-data
+                android:name="@string/category"
+                android:value="@string/category_location" />
+            <meta-data
+                android:name="android.support.PARENT_ACTIVITY"
+                android:value=".activity.FeatureOverviewActivity" />
+        </activity>
+        <activity
                 android:name=".activity.maplayout.RecyclerViewActivity"
                 android:description="@string/description_recyclerview"
                 android:label="@string/activity_recyclerview">
diff --git a/platform/android/MapboxGLAndroidSDKTestApp/src/main/java/com/mapbox/mapboxsdk/testapp/activity/location/LocationComponentActivationActivity.java b/platform/android/MapboxGLAndroidSDKTestApp/src/main/java/com/mapbox/mapboxsdk/testapp/activity/location/LocationComponentActivationActivity.java
new file mode 100644
index 0000000000..927a624611
--- /dev/null
+++ b/platform/android/MapboxGLAndroidSDKTestApp/src/main/java/com/mapbox/mapboxsdk/testapp/activity/location/LocationComponentActivationActivity.java
@@ -0,0 +1,140 @@
+package com.mapbox.mapboxsdk.testapp.activity.location;
+
+import android.annotation.SuppressLint;
+import android.graphics.Color;
+import android.os.Bundle;
+import android.support.annotation.NonNull;
+import android.support.v7.app.AppCompatActivity;
+import android.widget.Toast;
+
+import com.mapbox.android.core.permissions.PermissionsListener;
+import com.mapbox.android.core.permissions.PermissionsManager;
+import com.mapbox.mapboxsdk.location.LocationComponent;
+import com.mapbox.mapboxsdk.location.LocationComponentActivationOptions;
+import com.mapbox.mapboxsdk.location.LocationComponentOptions;
+import com.mapbox.mapboxsdk.location.modes.CameraMode;
+import com.mapbox.mapboxsdk.location.modes.RenderMode;
+import com.mapbox.mapboxsdk.maps.MapView;
+import com.mapbox.mapboxsdk.maps.MapboxMap;
+import com.mapbox.mapboxsdk.maps.OnMapReadyCallback;
+import com.mapbox.mapboxsdk.maps.Style;
+import com.mapbox.mapboxsdk.testapp.R;
+
+import java.util.List;
+
+public class LocationComponentActivationActivity extends AppCompatActivity implements OnMapReadyCallback {
+
+  private MapView mapView;
+  private MapboxMap mapboxMap;
+  private PermissionsManager permissionsManager;
+
+  @Override
+  protected void onCreate(Bundle savedInstanceState) {
+    super.onCreate(savedInstanceState);
+    setContentView(R.layout.activity_location_layer_activation_builder);
+
+    mapView = findViewById(R.id.mapView);
+
+    mapView.onCreate(savedInstanceState);
+
+    if (PermissionsManager.areLocationPermissionsGranted(this)) {
+      mapView.getMapAsync(this);
+    } else {
+      permissionsManager = new PermissionsManager(new PermissionsListener() {
+        @Override
+        public void onExplanationNeeded(List<String> permissionsToExplain) {
+          Toast.makeText(LocationComponentActivationActivity.this, "You need to accept location permissions.",
+            Toast.LENGTH_SHORT).show();
+        }
+
+        @Override
+        public void onPermissionResult(boolean granted) {
+          if (granted) {
+            mapView.getMapAsync(LocationComponentActivationActivity.this);
+          } else {
+            finish();
+          }
+        }
+      });
+      permissionsManager.requestLocationPermissions(this);
+    }
+  }
+
+  @Override
+  public void onRequestPermissionsResult(int requestCode, @NonNull String[] permissions, @NonNull int[] grantResults) {
+    super.onRequestPermissionsResult(requestCode, permissions, grantResults);
+    permissionsManager.onRequestPermissionsResult(requestCode, permissions, grantResults);
+  }
+
+  @Override
+  public void onMapReady(@NonNull MapboxMap mapboxMap) {
+    this.mapboxMap = mapboxMap;
+    mapboxMap.setStyle(Style.DARK,
+      style -> activateLocationComponent(style));
+  }
+
+  @SuppressLint("MissingPermission")
+  private void activateLocationComponent(@NonNull Style style) {
+    LocationComponent locationComponent = mapboxMap.getLocationComponent();
+
+    LocationComponentOptions locationComponentOptions = LocationComponentOptions.builder(this)
+      .elevation(5)
+      .accuracyAlpha(.6f)
+      .accuracyColor(Color.GREEN)
+      .foregroundDrawable(R.drawable.mapbox_logo_helmet)
+      .build();
+
+    LocationComponentActivationOptions locationComponentActivationOptions = LocationComponentActivationOptions
+      .builder(this, style)
+      .locationComponentOptions(locationComponentOptions)
+      .useDefaultLocationEngine(true)
+      .build();
+
+    locationComponent.activateLocationComponent(locationComponentActivationOptions);
+    locationComponent.setLocationComponentEnabled(true);
+    locationComponent.setRenderMode(RenderMode.NORMAL);
+    locationComponent.setCameraMode(CameraMode.TRACKING);
+  }
+
+  @Override
+  protected void onStart() {
+    super.onStart();
+    mapView.onStart();
+  }
+
+  @Override
+  protected void onResume() {
+    super.onResume();
+    mapView.onResume();
+  }
+
+  @Override
+  protected void onPause() {
+    super.onPause();
+    mapView.onPause();
+  }
+
+  @Override
+  protected void onStop() {
+    super.onStop();
+    mapView.onStop();
+  }
+
+  @Override
+  protected void onSaveInstanceState(Bundle outState) {
+    super.onSaveInstanceState(outState);
+    mapView.onSaveInstanceState(outState);
+  }
+
+  @Override
+  protected void onDestroy() {
+    super.onDestroy();
+    mapView.onDestroy();
+  }
+
+  @Override
+  public void onLowMemory() {
+    super.onLowMemory();
+    mapView.onLowMemory();
+  }
+}
\ No newline at end of file
diff --git a/platform/android/MapboxGLAndroidSDKTestApp/src/main/java/com/mapbox/mapboxsdk/testapp/activity/location/LocationFragmentActivity.kt b/platform/android/MapboxGLAndroidSDKTestApp/src/main/java/com/mapbox/mapboxsdk/testapp/activity/location/LocationFragmentActivity.kt
index d55a4f5fde..6a01d14249 100644
--- a/platform/android/MapboxGLAndroidSDKTestApp/src/main/java/com/mapbox/mapboxsdk/testapp/activity/location/LocationFragmentActivity.kt
+++ b/platform/android/MapboxGLAndroidSDKTestApp/src/main/java/com/mapbox/mapboxsdk/testapp/activity/location/LocationFragmentActivity.kt
@@ -2,7 +2,6 @@ package com.mapbox.mapboxsdk.testapp.activity.location
 
 import android.annotation.SuppressLint
 import android.app.Fragment
-import android.location.Location
 import android.os.Bundle
 import android.support.v7.app.AppCompatActivity
 import android.view.LayoutInflater
@@ -10,21 +9,18 @@ import android.view.View
 import android.view.ViewGroup
 import android.widget.TextView
 import android.widget.Toast
-import com.mapbox.android.core.location.LocationEngine
 import com.mapbox.android.core.location.LocationEngineCallback
-import com.mapbox.android.core.location.LocationEngineProvider
 import com.mapbox.android.core.location.LocationEngineResult
 import com.mapbox.android.core.permissions.PermissionsListener
 import com.mapbox.android.core.permissions.PermissionsManager
 import com.mapbox.mapboxsdk.camera.CameraUpdateFactory
 import com.mapbox.mapboxsdk.geometry.LatLng
+import com.mapbox.mapboxsdk.location.LocationComponentActivationOptions
 import com.mapbox.mapboxsdk.maps.MapView
 import com.mapbox.mapboxsdk.maps.MapboxMap
-import com.mapbox.mapboxsdk.location.LocationComponent
 import com.mapbox.mapboxsdk.maps.Style
 import com.mapbox.mapboxsdk.testapp.R
 import kotlinx.android.synthetic.main.activity_location_layer_fragment.*
-import java.lang.Exception
 
 class LocationFragmentActivity : AppCompatActivity() {
   private lateinit var permissionsManager: PermissionsManager
@@ -105,10 +101,15 @@ class LocationFragmentActivity : AppCompatActivity() {
       mapView.getMapAsync {
         mapboxMap = it
         it.setStyle(Style.MAPBOX_STREETS) { style ->
-            val component = mapboxMap.locationComponent
-            component.activateLocationComponent(activity, style)
-            component.isLocationComponentEnabled = true
-            component.locationEngine?.getLastLocation(this)
+          val component = mapboxMap.locationComponent
+
+          component.activateLocationComponent(LocationComponentActivationOptions
+                  .builder(activity, style)
+                  .useDefaultLocationEngine(true)
+                  .build())
+
+          component.isLocationComponentEnabled = true
+          component.locationEngine?.getLastLocation(this)
         }
       }
     }
diff --git a/platform/android/MapboxGLAndroidSDKTestApp/src/main/java/com/mapbox/mapboxsdk/testapp/activity/location/LocationMapChangeActivity.java b/platform/android/MapboxGLAndroidSDKTestApp/src/main/java/com/mapbox/mapboxsdk/testapp/activity/location/LocationMapChangeActivity.java
index ea827dc4cd..e444c2fcfd 100644
--- a/platform/android/MapboxGLAndroidSDKTestApp/src/main/java/com/mapbox/mapboxsdk/testapp/activity/location/LocationMapChangeActivity.java
+++ b/platform/android/MapboxGLAndroidSDKTestApp/src/main/java/com/mapbox/mapboxsdk/testapp/activity/location/LocationMapChangeActivity.java
@@ -10,6 +10,7 @@ import android.widget.Toast;
 import com.mapbox.android.core.permissions.PermissionsListener;
 import com.mapbox.android.core.permissions.PermissionsManager;
 import com.mapbox.mapboxsdk.location.LocationComponent;
+import com.mapbox.mapboxsdk.location.LocationComponentActivationOptions;
 import com.mapbox.mapboxsdk.location.modes.RenderMode;
 import com.mapbox.mapboxsdk.maps.MapView;
 import com.mapbox.mapboxsdk.maps.MapboxMap;
@@ -80,7 +81,13 @@ public class LocationMapChangeActivity extends AppCompatActivity implements OnMa
   @SuppressLint("MissingPermission")
   private void activateLocationComponent(@NonNull Style style) {
     LocationComponent locationComponent = mapboxMap.getLocationComponent();
-    locationComponent.activateLocationComponent(this, style);
+
+    locationComponent.activateLocationComponent(
+      LocationComponentActivationOptions
+        .builder(this, style)
+        .useDefaultLocationEngine(true)
+        .build());
+
     locationComponent.setLocationComponentEnabled(true);
     locationComponent.setRenderMode(RenderMode.COMPASS);
 
diff --git a/platform/android/MapboxGLAndroidSDKTestApp/src/main/java/com/mapbox/mapboxsdk/testapp/activity/location/LocationModesActivity.java b/platform/android/MapboxGLAndroidSDKTestApp/src/main/java/com/mapbox/mapboxsdk/testapp/activity/location/LocationModesActivity.java
index 11918669cb..28d165428d 100644
--- a/platform/android/MapboxGLAndroidSDKTestApp/src/main/java/com/mapbox/mapboxsdk/testapp/activity/location/LocationModesActivity.java
+++ b/platform/android/MapboxGLAndroidSDKTestApp/src/main/java/com/mapbox/mapboxsdk/testapp/activity/location/LocationModesActivity.java
@@ -18,6 +18,7 @@ import com.mapbox.android.core.permissions.PermissionsListener;
 import com.mapbox.android.core.permissions.PermissionsManager;
 import com.mapbox.mapboxsdk.camera.CameraUpdateFactory;
 import com.mapbox.mapboxsdk.location.LocationComponent;
+import com.mapbox.mapboxsdk.location.LocationComponentActivationOptions;
 import com.mapbox.mapboxsdk.location.LocationComponentOptions;
 import com.mapbox.mapboxsdk.location.OnCameraTrackingChangedListener;
 import com.mapbox.mapboxsdk.location.OnLocationCameraTransitionListener;
@@ -126,12 +127,16 @@ public class LocationModesActivity extends AppCompatActivity implements OnMapRea
 
     mapboxMap.setStyle(Style.MAPBOX_STREETS, style -> {
       locationComponent = mapboxMap.getLocationComponent();
-      locationComponent.activateLocationComponent(this, style, true,
-        new LocationEngineRequest.Builder(750)
-          .setFastestInterval(750)
-          .setPriority(LocationEngineRequest.PRIORITY_HIGH_ACCURACY)
-          .build()
-      );
+      locationComponent.activateLocationComponent(
+        LocationComponentActivationOptions
+          .builder(this, style)
+          .useDefaultLocationEngine(true)
+          .locationEngineRequest(new LocationEngineRequest.Builder(750)
+            .setFastestInterval(750)
+            .setPriority(LocationEngineRequest.PRIORITY_HIGH_ACCURACY)
+            .build())
+          .build());
+
       toggleStyle();
       locationComponent.setLocationComponentEnabled(true);
       locationComponent.addOnLocationClickListener(this);
diff --git a/platform/android/MapboxGLAndroidSDKTestApp/src/main/java/com/mapbox/mapboxsdk/testapp/activity/location/ManualLocationUpdatesActivity.java b/platform/android/MapboxGLAndroidSDKTestApp/src/main/java/com/mapbox/mapboxsdk/testapp/activity/location/ManualLocationUpdatesActivity.java
index dc6bf8a8b7..5ca00e5d0f 100644
--- a/platform/android/MapboxGLAndroidSDKTestApp/src/main/java/com/mapbox/mapboxsdk/testapp/activity/location/ManualLocationUpdatesActivity.java
+++ b/platform/android/MapboxGLAndroidSDKTestApp/src/main/java/com/mapbox/mapboxsdk/testapp/activity/location/ManualLocationUpdatesActivity.java
@@ -6,6 +6,7 @@ import android.support.annotation.NonNull;
 import android.support.design.widget.FloatingActionButton;
 import android.support.v7.app.AppCompatActivity;
 import android.widget.Toast;
+
 import com.mapbox.android.core.location.LocationEngine;
 import com.mapbox.android.core.location.LocationEngineProvider;
 import com.mapbox.android.core.location.LocationEngineRequest;
@@ -13,6 +14,7 @@ import com.mapbox.android.core.permissions.PermissionsListener;
 import com.mapbox.android.core.permissions.PermissionsManager;
 import com.mapbox.mapboxsdk.geometry.LatLngBounds;
 import com.mapbox.mapboxsdk.location.LocationComponent;
+import com.mapbox.mapboxsdk.location.LocationComponentActivationOptions;
 import com.mapbox.mapboxsdk.location.modes.RenderMode;
 import com.mapbox.mapboxsdk.maps.MapView;
 import com.mapbox.mapboxsdk.maps.MapboxMap;
@@ -109,14 +111,16 @@ public class ManualLocationUpdatesActivity extends AppCompatActivity implements
   public void onMapReady(@NonNull MapboxMap mapboxMap) {
     mapboxMap.setStyle(new Style.Builder().fromUrl(Style.MAPBOX_STREETS), style -> {
       locationComponent = mapboxMap.getLocationComponent();
+
       locationComponent.activateLocationComponent(
-        this,
-        style,
-        locationEngine,
-        new LocationEngineRequest.Builder(500)
-          .setFastestInterval(500)
-          .setPriority(LocationEngineRequest.PRIORITY_HIGH_ACCURACY)
+        LocationComponentActivationOptions
+          .builder(this, style)
+          .locationEngine(locationEngine)
+          .locationEngineRequest(new LocationEngineRequest.Builder(500)
+            .setFastestInterval(500)
+            .setPriority(LocationEngineRequest.PRIORITY_HIGH_ACCURACY).build())
           .build());
+
       locationComponent.setLocationComponentEnabled(true);
       locationComponent.setRenderMode(RenderMode.COMPASS);
     });
diff --git a/platform/android/MapboxGLAndroidSDKTestApp/src/main/res/layout/activity_location_layer_activation_builder.xml b/platform/android/MapboxGLAndroidSDKTestApp/src/main/res/layout/activity_location_layer_activation_builder.xml
new file mode 100644
index 0000000000..daae10ad03
--- /dev/null
+++ b/platform/android/MapboxGLAndroidSDKTestApp/src/main/res/layout/activity_location_layer_activation_builder.xml
@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="utf-8"?>
+<android.support.design.widget.CoordinatorLayout
+    xmlns:android="http://schemas.android.com/apk/res/android"
+    xmlns:app="http://schemas.android.com/apk/res-auto"
+    android:id="@+id/coordinator_layout"
+    android:layout_width="match_parent"
+    android:layout_height="match_parent"
+    android:orientation="vertical">
+
+    <com.mapbox.mapboxsdk.maps.MapView
+        android:id="@+id/mapView"
+        android:layout_width="match_parent"
+        android:layout_height="match_parent"
+        android:layout_marginBottom="0dp"
+        app:mapbox_uiAttribution="false"/>
+
+</android.support.design.widget.CoordinatorLayout>
\ No newline at end of file
diff --git a/platform/android/MapboxGLAndroidSDKTestApp/src/main/res/values/descriptions.xml b/platform/android/MapboxGLAndroidSDKTestApp/src/main/res/values/descriptions.xml
index 7fdc4c1bea..14eb678795 100644
--- a/platform/android/MapboxGLAndroidSDKTestApp/src/main/res/values/descriptions.xml
+++ b/platform/android/MapboxGLAndroidSDKTestApp/src/main/res/values/descriptions.xml
@@ -75,6 +75,7 @@
     <string name="description_location_modes">Showcases location render and tracking modes</string>
     <string name="description_location_fragment">Uses LocationComponent in a Fragment</string>
     <string name="description_location_manual">Force location updates and don\'t rely on the engine</string>
+    <string name="description_location_activation_builder">Use LocationComponentActivationOptions to set options</string>
     <string name="description_recyclerview">Show a MapView as a recyclerView item</string>
     <string name="description_nested_viewpager">Show a MapView inside a viewpager inside a recyclerView</string>
 </resources>
diff --git a/platform/android/MapboxGLAndroidSDKTestApp/src/main/res/values/titles.xml b/platform/android/MapboxGLAndroidSDKTestApp/src/main/res/values/titles.xml
index 3345c8db4e..dc4fd89deb 100644
--- a/platform/android/MapboxGLAndroidSDKTestApp/src/main/res/values/titles.xml
+++ b/platform/android/MapboxGLAndroidSDKTestApp/src/main/res/values/titles.xml
@@ -75,6 +75,7 @@
     <string name="activity_location_modes">Location Modes Activity</string>
     <string name="activity_location_fragment">Location Fragment</string>
     <string name="activity_location_manual">Manual Location updates</string>
+    <string name="activity_location_activation_builder">Build Location Activation</string>
     <string name="activity_recyclerview">RecyclerView</string>
     <string name="activity_nested_viewpager">Nested ViewPager</string>
 </resources>
\ No newline at end of file