[#1292] Expose Data database file path

- Implemented as part of synchronizer API
- Closes #1292
- Documentation updated

CHANGELOG.md

@@ -6,6 +6,14 @@ and this library adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- `Synchronizer.getExistingDataDbFilePath` public API to check and provide file path to the existing data database 
+  file or throws [InitializeException.MissingDatabaseException] if the database doesn't exist yet. See #1292.
+
+### Changed
+- `CompactBlockProcessor` switched internally from balance and progress FFIs to wallet summary FFI APIs. This change 
+  brings a block synchronization speed up. No action is required on the client side. See #1282.
+
 ## [2.0.2] - 2023-10-20
 
 ### Fixed

sdk-lib/src/main/java/cash/z/ecc/android/sdk/SdkSynchronizer.kt

@@ -11,6 +11,7 @@ import cash.z.ecc.android.sdk.block.processor.CompactBlockProcessor.State.Initia
 import cash.z.ecc.android.sdk.block.processor.CompactBlockProcessor.State.Stopped
 import cash.z.ecc.android.sdk.block.processor.CompactBlockProcessor.State.Synced
 import cash.z.ecc.android.sdk.block.processor.CompactBlockProcessor.State.Syncing
+import cash.z.ecc.android.sdk.exception.InitializeException
 import cash.z.ecc.android.sdk.exception.TransactionEncoderException
 import cash.z.ecc.android.sdk.exception.TransactionSubmitException
 import cash.z.ecc.android.sdk.ext.ConsensusBranchId
@@ -23,6 +24,7 @@ import cash.z.ecc.android.sdk.internal.block.CompactBlockDownloader
 import cash.z.ecc.android.sdk.internal.db.DatabaseCoordinator
 import cash.z.ecc.android.sdk.internal.db.derived.DbDerivedDataRepository
 import cash.z.ecc.android.sdk.internal.db.derived.DerivedDataDb
+import cash.z.ecc.android.sdk.internal.ext.existsSuspend
 import cash.z.ecc.android.sdk.internal.ext.isNullOrEmpty
 import cash.z.ecc.android.sdk.internal.ext.tryNull
 import cash.z.ecc.android.sdk.internal.jni.RustBackend
@@ -655,6 +657,23 @@ class SdkSynchronizer private constructor(
             serverBranchId?.let { ConsensusBranchId.fromHex(it) }
         )
     }
+
+    @Throws(InitializeException.MissingDatabaseException::class)
+    override suspend fun getExistingDataDbFilePath(
+        context: Context,
+        network: ZcashNetwork,
+        alias: String
+    ): String {
+        return DatabaseCoordinator.getInstance(context).dataDbFile(
+            network = network,
+            alias = alias
+        ).run {
+            if (!existsSuspend()) {
+                throw InitializeException.MissingDatabaseException(network, alias)
+            }
+            absolutePath
+        }
+    }
 }
 
 /**

sdk-lib/src/main/java/cash/z/ecc/android/sdk/Synchronizer.kt

@@ -2,6 +2,7 @@ package cash.z.ecc.android.sdk
 
 import android.content.Context
 import cash.z.ecc.android.sdk.block.processor.CompactBlockProcessor
+import cash.z.ecc.android.sdk.exception.InitializeException
 import cash.z.ecc.android.sdk.ext.ZcashSdk
 import cash.z.ecc.android.sdk.internal.Derivation
 import cash.z.ecc.android.sdk.internal.SaplingParamTool
@@ -309,6 +310,24 @@ interface Synchronizer {
      */
     fun getRecipients(transactionOverview: TransactionOverview): Flow<TransactionRecipient>
 
+    /**
+     * Checks and provides file path to the existing data database file for the given input parameters or throws
+     * [InitializeException.MissingDatabaseException] if the database does not exist yet.
+     *
+     * Note that it's the caller's responsibility to provide a [network] and [alias] to an existing database. Otherwise
+     * [InitializeException.MissingDatabaseException] is thrown.
+     *
+     * @return Path to the already created data database file, or null in case none exists yet
+     * @throws [InitializeException.MissingDatabaseException] When the requested database for the given inputs
+     * does not exist yet.
+     */
+    @Throws(InitializeException.MissingDatabaseException::class)
+    suspend fun getExistingDataDbFilePath(
+        context: Context,
+        network: ZcashNetwork,
+        alias: String = ZcashSdk.DEFAULT_ALIAS
+    ): String
+
     //
     // Error Handling
     //

sdk-lib/src/main/java/cash/z/ecc/android/sdk/exception/Exceptions.kt

@@ -1,6 +1,7 @@
 package cash.z.ecc.android.sdk.exception
 
 import cash.z.ecc.android.sdk.internal.SaplingParameters
+import cash.z.ecc.android.sdk.internal.db.DatabaseCoordinator
 import cash.z.ecc.android.sdk.internal.model.Checkpoint
 import cash.z.ecc.android.sdk.model.BlockHeight
 import cash.z.ecc.android.sdk.model.FirstClassByteArray
@@ -224,6 +225,14 @@ sealed class InitializeException(message: String, cause: Throwable? = null) : Sd
                 " data."
         )
 
+    data class MissingDatabaseException(
+        val network: ZcashNetwork,
+        val alias: String
+    ) : InitializeException(
+        "The requested database file with network: $network and alias: $alias does not exist yet. Create and " +
+            "initialize it using functions from ${DatabaseCoordinator::class.simpleName} first."
+    )
+
     class InvalidBirthdayHeightException(birthday: BlockHeight?, network: ZcashNetwork) : InitializeException(
         "Invalid birthday height of ${birthday?.value}. The birthday height must be at least the height of" +
             " Sapling activation on ${network.networkName} (${network.saplingActivationHeight})."