Support in-progress download restoration

toolkit/offline/src/main/java/com/arcgismaps/toolkit/offline/OfflineMapAreaMetadata.kt

@@ -0,0 +1,133 @@
+/*
+ *
+ *  Copyright 2025 Esri
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ *
+ */
+
+package com.arcgismaps.toolkit.offline
+
+import android.graphics.Bitmap
+import android.graphics.BitmapFactory
+import com.arcgismaps.tasks.offlinemaptask.PreplannedMapArea
+import com.arcgismaps.toolkit.offline.ondemand.OnDemandMapAreaConfiguration
+import com.arcgismaps.toolkit.offline.workmanager.offlineAreaMetadataJsonFile
+import com.arcgismaps.toolkit.offline.workmanager.offlineMapInfoThumbnailFile
+import kotlinx.serialization.Serializable
+import kotlinx.serialization.Transient
+import kotlinx.serialization.json.Json
+import java.io.File
+import java.io.FileOutputStream
+
+/**
+ * Represents the metadata for an area of an offline map.
+ *
+ * @since 200.8.0
+ */
+@Serializable
+internal data class OfflineMapAreaMetadata(
+    val itemId: String,
+    val title: String,
+    val description: String,
+    @Transient val thumbnailImage: Bitmap? = null
+) {
+
+    companion object {
+        /**
+         * Creates an [OfflineMapAreaMetadata] from a [PreplannedMapArea].
+         *
+         * @since 200.8.0
+         */
+        internal fun createPreplannedMetadata(preplannedMapArea: PreplannedMapArea): OfflineMapAreaMetadata {
+            return OfflineMapAreaMetadata(
+                itemId = preplannedMapArea.portalItem.itemId,
+                title = preplannedMapArea.portalItem.title,
+                thumbnailImage = preplannedMapArea.portalItem.thumbnail?.image?.bitmap,
+                description = preplannedMapArea.portalItem.description
+            )
+        }
+
+        /**
+         * Creates an [OfflineMapAreaMetadata] from an [OnDemandMapAreaConfiguration].
+         *
+         * @since 200.8.0
+         */
+        internal fun createOnDemandMetadata(onDemandMapAreaConfiguration: OnDemandMapAreaConfiguration): OfflineMapAreaMetadata {
+            return OfflineMapAreaMetadata(
+                itemId = onDemandMapAreaConfiguration.itemId,
+                title = onDemandMapAreaConfiguration.title,
+                thumbnailImage = onDemandMapAreaConfiguration.thumbnail,
+                description = ""
+            )
+        }
+
+        /**
+         * Creates an [OfflineMapAreaMetadata] from a [directory] on disk, if “metadata.json” exists.
+         *
+         * @since 200.8.0
+         */
+        internal fun createFromDirectory(directory: File): OfflineMapAreaMetadata? {
+            val metadataFile = File(directory, offlineAreaMetadataJsonFile)
+            if (!metadataFile.exists()) {
+                return null
+            }
+            val jsonString = runCatching { metadataFile.readText(Charsets.UTF_8) }.getOrNull()
+                ?: return null
+            val baseMetadata = runCatching {
+                Json.decodeFromString(serializer(), jsonString)
+            }.getOrNull() ?: return null
+            val thumbnailFile = File(directory, offlineMapInfoThumbnailFile)
+            val thumbnail: Bitmap? = if (thumbnailFile.exists()) {
+                BitmapFactory.decodeFile(thumbnailFile.absolutePath)
+            } else {
+                null
+            }
+            return OfflineMapAreaMetadata(
+                itemId = baseMetadata.itemId,
+                thumbnailImage = thumbnail,
+                title = baseMetadata.title,
+                description = baseMetadata.description
+            )
+        }
+
+        /**
+         * Returns true if metadata.json is found in the [directory].
+         */
+        internal fun isSerializedFilePresent(directory: File): Boolean {
+            return File(directory, offlineAreaMetadataJsonFile).exists()
+        }
+    }
+
+    /**
+     * Save this OfflineMapAreaMetadata into a [directory] on disk.
+     *
+     * @since 200.8.0
+     */
+    internal fun saveToDirectory(directory: File) {
+        if (!directory.exists()) {
+            directory.mkdirs()
+        }
+        val metadataFile = File(directory, offlineAreaMetadataJsonFile)
+        val jsonString = Json.encodeToString(serializer(), this)
+        runCatching { metadataFile.writeText(jsonString, Charsets.UTF_8) }
+        thumbnailImage?.let { bmp ->
+            val thumbFile = File(directory, offlineMapInfoThumbnailFile)
+            runCatching {
+                FileOutputStream(thumbFile).use { out ->
+                    bmp.compress(Bitmap.CompressFormat.PNG, 100, out)
+                }
+            }
+        }
+    }
+}

toolkit/offline/src/main/java/com/arcgismaps/toolkit/offline/OfflineMapState.kt

@@ -65,7 +65,7 @@ public class OfflineMapState(
         onSelectionChanged = onSelectionChanged
     )
 
-    private var _mode: OfflineMapMode = OfflineMapMode.Unknown
+    private var _mode: OfflineMapMode by mutableStateOf(OfflineMapMode.Unknown)
     internal val mode: OfflineMapMode
         get() = _mode
 
@@ -216,6 +216,8 @@ public class OfflineMapState(
                         }
                         _preplannedMapAreaStates.add(preplannedMapAreaState)
                     }
+                // restore any running download job state
+                restoreActiveJobsAndUpdateStates(context)
             }
         }
     }
@@ -263,6 +265,8 @@ public class OfflineMapState(
                 _onDemandMapAreaStates.add(it)
             }
         }
+        // restore any running download job state
+        restoreActiveJobsAndUpdateStates(context)
     }
 
     /**
@@ -305,8 +309,9 @@ public class OfflineMapState(
                 mobileMapPackagePath = preplannedPath
             )
             return preplannedMapAreaState
-        } else
+        } else {
             return null
+        }
     }
 
     /**
@@ -395,6 +400,8 @@ public class OfflineMapState(
 
     /**
      * Removes a specific [PreplannedMapAreaState] from the list of preplanned map areas.
+     *
+     * @since 200.8.0
      */
     internal fun removePreplannedMapArea(state: PreplannedMapAreaState) {
         if (state.isSelectedToOpen) {
@@ -405,6 +412,7 @@ public class OfflineMapState(
 
     /**
      * Removes a specific [OnDemandMapAreasState] from the list of on-demand map areas.
+     *
      * @since 200.8.0
      */
     internal fun removeOnDemandMapArea(state: OnDemandMapAreasState) {
@@ -413,6 +421,36 @@ public class OfflineMapState(
         }
         _onDemandMapAreaStates.remove(state)
     }
+
+    /**
+     * Restores the current preplanned & on-demand job state from cached metadata.
+     *
+     * @since 200.8.0
+     */
+    private suspend fun restoreActiveJobsAndUpdateStates(context: Context) {
+        OfflineRepository.getActiveOfflineJobs(context, portalItem.itemId)
+            .forEach { workerUuid ->
+                val mapAreaMetadata = OfflineRepository.getMapAreaMetadataForOfflineJob(
+                    context = context,
+                    uuid = workerUuid,
+                    portalItemId = portalItem.itemId
+                ) ?: return@forEach
+                if (mode == OfflineMapMode.Preplanned) {
+                    // update the loaded preplanned area, to restore with the in-progress job state
+                    _preplannedMapAreaStates.first {
+                        it.preplannedMapArea?.portalItem?.itemId.equals(mapAreaMetadata.itemId)
+                    }.apply { restoreOfflineMapJobState(workerUuid, mapAreaMetadata) }
+                } else {
+                    val restoredState = OnDemandMapAreasState(
+                        context = context,
+                        item = portalItem,
+                        onSelectionChanged = onSelectionChanged
+                    ).apply { restoreOfflineMapJobState(workerUuid, mapAreaMetadata) }
+                    // add the in-progress job states after loading on-demand map areas
+                    _onDemandMapAreaStates.add(restoredState)
+                }
+            }
+    }
 }
 
 /**