NAVAND-960: allow different PredictiveCacheLocationOptions for different zooms

Author: dzinad

changelog/unreleased/features/dd.md

@@ -0,0 +1 @@
+- Introduced `PredictiveCacheOptions.Builder#predictiveCacheMapsOptionsList` as an alternative for deprecated `PredictiveCacheOptions.Builder#predictiveCacheMapsOptions`. This allows to use different `PredictiveCacheLocationOptions` for different zoom level ranges.

libnavigation-base/api/current.txt

@@ -542,17 +542,20 @@ package com.mapbox.navigation.base.options {
   }
 
   public final class PredictiveCacheOptions {
-    method public com.mapbox.navigation.base.options.PredictiveCacheMapsOptions getPredictiveCacheMapsOptions();
+    method @Deprecated public com.mapbox.navigation.base.options.PredictiveCacheMapsOptions getPredictiveCacheMapsOptions();
+    method public java.util.List<com.mapbox.navigation.base.options.PredictiveCacheMapsOptions> getPredictiveCacheMapsOptionsList();
     method public com.mapbox.navigation.base.options.PredictiveCacheNavigationOptions getPredictiveCacheNavigationOptions();
     method public com.mapbox.navigation.base.options.PredictiveCacheOptions.Builder toBuilder();
-    property public final com.mapbox.navigation.base.options.PredictiveCacheMapsOptions predictiveCacheMapsOptions;
+    property @Deprecated public final com.mapbox.navigation.base.options.PredictiveCacheMapsOptions predictiveCacheMapsOptions;
+    property public final java.util.List<com.mapbox.navigation.base.options.PredictiveCacheMapsOptions> predictiveCacheMapsOptionsList;
     property public final com.mapbox.navigation.base.options.PredictiveCacheNavigationOptions predictiveCacheNavigationOptions;
   }
 
   public static final class PredictiveCacheOptions.Builder {
     ctor public PredictiveCacheOptions.Builder();
     method public com.mapbox.navigation.base.options.PredictiveCacheOptions build();
-    method public com.mapbox.navigation.base.options.PredictiveCacheOptions.Builder predictiveCacheMapsOptions(com.mapbox.navigation.base.options.PredictiveCacheMapsOptions predictiveCacheMapsOptions);
+    method @Deprecated public com.mapbox.navigation.base.options.PredictiveCacheOptions.Builder predictiveCacheMapsOptions(com.mapbox.navigation.base.options.PredictiveCacheMapsOptions predictiveCacheMapsOptions);
+    method @kotlin.jvm.Throws(exceptionClasses=IllegalArgumentException::class) public com.mapbox.navigation.base.options.PredictiveCacheOptions.Builder predictiveCacheMapsOptionsList(java.util.List<com.mapbox.navigation.base.options.PredictiveCacheMapsOptions> predictiveCacheMapsOptionsList) throws java.lang.IllegalArgumentException;
     method public com.mapbox.navigation.base.options.PredictiveCacheOptions.Builder predictiveCacheNavigationOptions(com.mapbox.navigation.base.options.PredictiveCacheNavigationOptions predictiveCacheNavigationOptions);
   }
 

libnavigation-base/src/main/java/com/mapbox/navigation/base/options/PredictiveCacheOptions.kt

@@ -4,19 +4,31 @@ package com.mapbox.navigation.base.options
  * PredictiveCacheOptions
  *
  * @param predictiveCacheNavigationOptions [PredictiveCacheNavigationOptions] Predictive cache Navigation related options.
- * @param predictiveCacheMapsOptions [PredictiveCacheMapsOptions] Predictive cache Maps related options.
+ * @param predictiveCacheMapsOptionsList List of predictive cache Maps related options ([PredictiveCacheMapsOptions]).
+ *  Use this instead of [predictiveCacheMapsOptions] so that you can specify different
+ *  [PredictiveCacheLocationOptions]s for different zoom level ranges.
  */
 class PredictiveCacheOptions private constructor(
     val predictiveCacheNavigationOptions: PredictiveCacheNavigationOptions,
-    val predictiveCacheMapsOptions: PredictiveCacheMapsOptions,
+    val predictiveCacheMapsOptionsList: List<PredictiveCacheMapsOptions>
 ) {
 
+    /**
+     * Predictive cache Maps related options. If [Builder.predictiveCacheMapsOptionsList] was used,
+     * returns first element from [predictiveCacheMapsOptionsList].
+     * @deprecated use predictiveCacheMapsOptionsList instead to provide different
+     * [PredictiveCacheLocationOptions]s for different zoom level ranges.
+     */
+    @Deprecated("Use predictiveCacheMapsOptionsList")
+    val predictiveCacheMapsOptions: PredictiveCacheMapsOptions =
+        predictiveCacheMapsOptionsList.first()
+
     /**
      * Get a builder to customize a subset of current options.
      */
     fun toBuilder(): Builder = Builder().apply {
         predictiveCacheNavigationOptions(predictiveCacheNavigationOptions)
-        predictiveCacheMapsOptions(predictiveCacheMapsOptions)
+        predictiveCacheMapsOptionsList(predictiveCacheMapsOptionsList)
     }
 
     /**
@@ -29,7 +41,7 @@ class PredictiveCacheOptions private constructor(
         other as PredictiveCacheOptions
 
         if (predictiveCacheNavigationOptions != other.predictiveCacheNavigationOptions) return false
-        if (predictiveCacheMapsOptions != other.predictiveCacheMapsOptions) return false
+        if (predictiveCacheMapsOptionsList != other.predictiveCacheMapsOptionsList) return false
 
         return true
     }
@@ -39,7 +51,7 @@ class PredictiveCacheOptions private constructor(
      */
     override fun hashCode(): Int {
         var result = predictiveCacheNavigationOptions.hashCode()
-        result = 31 * result + predictiveCacheMapsOptions.hashCode()
+        result = 31 * result + predictiveCacheMapsOptionsList.hashCode()
         return result
     }
 
@@ -49,16 +61,18 @@ class PredictiveCacheOptions private constructor(
     override fun toString(): String {
         return "PredictiveCacheOptions(" +
             "predictiveCacheNavigationOptions=$predictiveCacheNavigationOptions, " +
-            "predictiveCacheMapsOptions=$predictiveCacheMapsOptions" +
+            "predictiveCacheMapsOptionsList=$predictiveCacheMapsOptionsList" +
             ")"
     }
 
     /**
      * Build a new [PredictiveCacheOptions].
      */
     class Builder {
-        private var predictiveCacheNavigationOptions: PredictiveCacheNavigationOptions? = null
-        private var predictiveCacheMapsOptions: PredictiveCacheMapsOptions? = null
+        private var predictiveCacheNavigationOptions =
+            PredictiveCacheNavigationOptions.Builder().build()
+        private var predictiveCacheMapsOptionsList =
+            listOf(PredictiveCacheMapsOptions.Builder().build())
 
         /**
          * Predictive cache Navigation related options.
@@ -71,17 +85,40 @@ class PredictiveCacheOptions private constructor(
 
         /**
          * Predictive cache Maps related options.
+         * @deprecated use predictiveCacheMapsOptionsList instead to provide different
+         * [PredictiveCacheLocationOptions]s for different zoom level ranges.
          */
+        @Deprecated(
+            "Use predictiveCacheMapsOptionsList",
+            ReplaceWith("predictiveCacheMapsOptionsList(listOf(predictiveCacheMapsOptions))")
+        )
         fun predictiveCacheMapsOptions(
             predictiveCacheMapsOptions: PredictiveCacheMapsOptions
-        ): Builder = apply { this.predictiveCacheMapsOptions = predictiveCacheMapsOptions }
+        ): Builder = predictiveCacheMapsOptionsList(listOf(predictiveCacheMapsOptions))
+
+        /**
+         * List of predictive cache Maps related options ([PredictiveCacheMapsOptions]).
+         * Use this instead of [predictiveCacheMapsOptions] so that you can specify different
+         * [PredictiveCacheLocationOptions]s for different zoom level ranges.
+         *
+         * @throws IllegalArgumentException if [predictiveCacheMapsOptionsList] is empty.
+         */
+        @Throws(IllegalArgumentException::class)
+        fun predictiveCacheMapsOptionsList(
+            predictiveCacheMapsOptionsList: List<PredictiveCacheMapsOptions>
+        ): Builder = apply {
+            if (predictiveCacheMapsOptionsList.isEmpty()) {
+                throw IllegalArgumentException("predictiveCacheMapsOptionsList must not be empty")
+            }
+            this.predictiveCacheMapsOptionsList = predictiveCacheMapsOptionsList.toList()
+        }
 
         /**
          * Build [PredictiveCacheOptions].
          */
         fun build(): PredictiveCacheOptions = PredictiveCacheOptions(
-            predictiveCacheNavigationOptions ?: PredictiveCacheNavigationOptions.Builder().build(),
-            predictiveCacheMapsOptions ?: PredictiveCacheMapsOptions.Builder().build(),
+            predictiveCacheNavigationOptions,
+            predictiveCacheMapsOptionsList
         )
     }
 }

libnavigation-base/src/test/java/com/mapbox/navigation/base/options/PredictiveCacheOptionsBuilderTest.kt

@@ -0,0 +1,57 @@
+package com.mapbox.navigation.base.options
+
+import com.mapbox.navigation.testing.BuilderTest
+import org.junit.Test
+import kotlin.reflect.KClass
+
+class PredictiveCacheOptionsBuilderTest :
+    BuilderTest<PredictiveCacheOptions, PredictiveCacheOptions.Builder>() {
+    override fun getImplementationClass(): KClass<PredictiveCacheOptions> =
+        PredictiveCacheOptions::class
+
+    override fun getFilledUpBuilder(): PredictiveCacheOptions.Builder =
+        PredictiveCacheOptions.Builder().apply {
+            predictiveCacheNavigationOptions(
+                PredictiveCacheNavigationOptions.Builder().apply {
+                    predictiveCacheLocationOptions(
+                        PredictiveCacheLocationOptions.Builder().apply {
+                            currentLocationRadiusInMeters(300)
+                            routeBufferRadiusInMeters(50)
+                            destinationLocationRadiusInMeters(20)
+                        }.build()
+                    )
+                }.build()
+            )
+            predictiveCacheMapsOptionsList(
+                listOf(
+                    PredictiveCacheMapsOptions.Builder().apply {
+                        predictiveCacheLocationOptions(
+                            PredictiveCacheLocationOptions.Builder().apply {
+                                currentLocationRadiusInMeters(100)
+                                routeBufferRadiusInMeters(2)
+                                destinationLocationRadiusInMeters(15)
+                            }.build()
+                        )
+                        minZoom(1)
+                        maxZoom(3)
+                    }.build(),
+                    PredictiveCacheMapsOptions.Builder().apply {
+                        predictiveCacheLocationOptions(
+                            PredictiveCacheLocationOptions.Builder().apply {
+                                currentLocationRadiusInMeters(200)
+                                routeBufferRadiusInMeters(3)
+                                destinationLocationRadiusInMeters(18)
+                            }.build()
+                        )
+                        minZoom(7)
+                        maxZoom(9)
+                    }.build(),
+                )
+            )
+        }
+
+    @Test
+    override fun trigger() {
+        // trigger, see KDoc
+    }
+}

libnavigation-base/src/test/java/com/mapbox/navigation/base/options/PredictiveCacheOptionsDeprecatedBuilderTest.kt

@@ -0,0 +1,45 @@
+package com.mapbox.navigation.base.options
+
+import com.mapbox.navigation.testing.BuilderTest
+import org.junit.Test
+import kotlin.reflect.KClass
+
+class PredictiveCacheOptionsDeprecatedBuilderTest :
+    BuilderTest<PredictiveCacheOptions, PredictiveCacheOptions.Builder>() {
+
+    override fun getImplementationClass(): KClass<PredictiveCacheOptions> =
+        PredictiveCacheOptions::class
+
+    override fun getFilledUpBuilder(): PredictiveCacheOptions.Builder =
+        PredictiveCacheOptions.Builder().apply {
+            predictiveCacheNavigationOptions(
+                PredictiveCacheNavigationOptions.Builder().apply {
+                    predictiveCacheLocationOptions(
+                        PredictiveCacheLocationOptions.Builder().apply {
+                            currentLocationRadiusInMeters(300)
+                            routeBufferRadiusInMeters(50)
+                            destinationLocationRadiusInMeters(20)
+                        }.build()
+                    )
+                }.build()
+            )
+            predictiveCacheMapsOptions(
+                PredictiveCacheMapsOptions.Builder().apply {
+                    predictiveCacheLocationOptions(
+                        PredictiveCacheLocationOptions.Builder().apply {
+                            currentLocationRadiusInMeters(100)
+                            routeBufferRadiusInMeters(2)
+                            destinationLocationRadiusInMeters(15)
+                        }.build()
+                    )
+                    minZoom(1)
+                    maxZoom(3)
+                }.build()
+            )
+        }
+
+    @Test
+    override fun trigger() {
+        // trigger, see KDoc
+    }
+}

libnavigation-base/src/test/java/com/mapbox/navigation/base/options/PredictiveCacheOptionsTest.kt

@@ -1,44 +1,80 @@
 package com.mapbox.navigation.base.options
 
-import com.mapbox.navigation.testing.BuilderTest
+import org.junit.Assert.assertEquals
 import org.junit.Test
-import kotlin.reflect.KClass
-
-class PredictiveCacheOptionsTest :
-    BuilderTest<PredictiveCacheOptions, PredictiveCacheOptions.Builder>() {
-    override fun getImplementationClass(): KClass<PredictiveCacheOptions> =
-        PredictiveCacheOptions::class
-
-    override fun getFilledUpBuilder(): PredictiveCacheOptions.Builder =
-        PredictiveCacheOptions.Builder().apply {
-            predictiveCacheNavigationOptions(
-                PredictiveCacheNavigationOptions.Builder().apply {
-                    predictiveCacheLocationOptions(
-                        PredictiveCacheLocationOptions.Builder().apply {
-                            currentLocationRadiusInMeters(300)
-                            routeBufferRadiusInMeters(50)
-                            destinationLocationRadiusInMeters(20)
-                        }.build()
-                    )
-                }.build()
-            )
-            predictiveCacheMapsOptions(
-                PredictiveCacheMapsOptions.Builder().apply {
-                    predictiveCacheLocationOptions(
-                        PredictiveCacheLocationOptions.Builder().apply {
-                            currentLocationRadiusInMeters(100)
-                            routeBufferRadiusInMeters(2)
-                            destinationLocationRadiusInMeters(15)
-                        }.build()
-                    )
-                    minZoom(1)
-                    maxZoom(3)
-                }.build()
-            )
-        }
+
+class PredictiveCacheOptionsTest {
+
+    @Test
+    fun defaultMapsOptionsList() {
+        val expected = PredictiveCacheMapsOptions.Builder().build()
+        val actual = PredictiveCacheOptions.Builder().build()
+
+        assertEquals(expected, actual.predictiveCacheMapsOptions)
+        assertEquals(listOf(expected), actual.predictiveCacheMapsOptionsList)
+    }
+
+    @Test
+    fun deprecatedMapsOptions() {
+        val mapsOptions = PredictiveCacheMapsOptions.Builder().minZoom(12).maxZoom(14).build()
+        val actual = PredictiveCacheOptions.Builder()
+            .predictiveCacheMapsOptions(mapsOptions)
+            .build()
+
+        assertEquals(mapsOptions, actual.predictiveCacheMapsOptions)
+        assertEquals(listOf(mapsOptions), actual.predictiveCacheMapsOptionsList)
+    }
+
+    @Test
+    fun customMapsOptionsList() {
+        val mapsOptions1 = PredictiveCacheMapsOptions.Builder().minZoom(12).maxZoom(14).build()
+        val mapsOptions2 = PredictiveCacheMapsOptions.Builder().minZoom(11).maxZoom(13).build()
+        val actual = PredictiveCacheOptions.Builder()
+            .predictiveCacheMapsOptionsList(listOf(mapsOptions1, mapsOptions2))
+            .build()
+
+        assertEquals(mapsOptions1, actual.predictiveCacheMapsOptions)
+        assertEquals(listOf(mapsOptions1, mapsOptions2), actual.predictiveCacheMapsOptionsList)
+    }
+
+    @Test(expected = IllegalArgumentException::class)
+    fun customEmptyMapsOptionsList() {
+        PredictiveCacheOptions.Builder()
+            .predictiveCacheMapsOptionsList(emptyList())
+            .build()
+    }
 
     @Test
-    override fun trigger() {
-        // trigger, see KDoc
+    fun customMapsOptionsAfterDeprecatedMapsOptions() {
+        val deprecatedMapsOptions = PredictiveCacheMapsOptions.Builder()
+            .minZoom(7)
+            .maxZoom(9)
+            .build()
+        val mapsOptions1 = PredictiveCacheMapsOptions.Builder().minZoom(12).maxZoom(14).build()
+        val mapsOptions2 = PredictiveCacheMapsOptions.Builder().minZoom(11).maxZoom(13).build()
+        val actual = PredictiveCacheOptions.Builder()
+            .predictiveCacheMapsOptions(deprecatedMapsOptions)
+            .predictiveCacheMapsOptionsList(listOf(mapsOptions1, mapsOptions2))
+            .build()
+
+        assertEquals(mapsOptions1, actual.predictiveCacheMapsOptions)
+        assertEquals(listOf(mapsOptions1, mapsOptions2), actual.predictiveCacheMapsOptionsList)
+    }
+
+    @Test
+    fun deprecatedMapsOptionsAfterCustomMapsOptionsList() {
+        val deprecatedMapsOptions = PredictiveCacheMapsOptions.Builder()
+            .minZoom(7)
+            .maxZoom(9)
+            .build()
+        val mapsOptions1 = PredictiveCacheMapsOptions.Builder().minZoom(12).maxZoom(14).build()
+        val mapsOptions2 = PredictiveCacheMapsOptions.Builder().minZoom(11).maxZoom(13).build()
+        val actual = PredictiveCacheOptions.Builder()
+            .predictiveCacheMapsOptionsList(listOf(mapsOptions1, mapsOptions2))
+            .predictiveCacheMapsOptions(deprecatedMapsOptions)
+            .build()
+
+        assertEquals(deprecatedMapsOptions, actual.predictiveCacheMapsOptions)
+        assertEquals(listOf(deprecatedMapsOptions), actual.predictiveCacheMapsOptionsList)
     }
 }