Update DataStore.kt

Author: daymxn

firebase-common/src/main/java/com/google/firebase/datastore/DataStore.kt

@@ -27,11 +27,28 @@ import kotlinx.coroutines.flow.firstOrNull
 import kotlinx.coroutines.runBlocking
 
 /**
- * Don't use this unless you're bridging Java code Use your own [dataStore] directly in Kotlin code,
- * or if you're writing new code.
+ * Wrapper around [DataStore] for easier migration from `SharedPreferences` in Java code.
+ *
+ * Automatically migrates data from any `SharedPreferences` that share the same context and name.
+ *
+ * There should only ever be _one_ instance of this class per context and name variant.
+ *
+ * > Do **NOT** use this _unless_ you're bridging Java code. If you're writing new code, or your >
+ * code is in Kotlin, then you should create your own singleton that uses [DataStore] directly.
+ *
+ * Example:
+ * ```java
+ * DataStorage heartBeatStorage = new DataStorage(applicationContext, "FirebaseHeartBeat");
+ * ```
+ *
+ * @property context The [Context] that this data will be saved under.
+ * @property name What the storage file should be named.
  */
 class DataStorage(val context: Context, val name: String) {
-  private val transforming = ThreadLocal<Boolean>()
+  /**
+   * Used to ensure that there's only ever one call to [editSync] per thread; as to avoid deadlocks.
+   */
+  private val editLock = ThreadLocal<Boolean>()
 
   private val Context.dataStore: DataStore<Preferences> by
     preferencesDataStore(
@@ -41,26 +58,134 @@ class DataStorage(val context: Context, val name: String) {
 
   private val dataStore = context.dataStore
 
+  /**
+   * Get data from the datastore _synchronously_.
+   *
+   * Note that if the key is _not_ in the datastore, while the [defaultValue] will be returned
+   * instead- it will **not** be saved to the datastore; you'll have to manually do that.
+   *
+   * Blocks on the currently running thread.
+   *
+   * Example:
+   * ```java
+   * Preferences.Key<Long> fireCountKey = PreferencesKeys.longKey("fire-count");
+   * assert dataStore.get(fireCountKey, 0L) == 0L;
+   *
+   * dataStore.putSync(fireCountKey, 102L);
+   * assert dataStore.get(fireCountKey, 0L) == 102L;
+   * ```
+   *
+   * @param key The typed key of the entry to get data for.
+   * @param defaultValue A value to default to, if the key isn't found.
+   *
+   * @see Preferences.getOrDefault
+   */
   fun <T> getSync(key: Preferences.Key<T>, defaultValue: T): T = runBlocking {
     dataStore.data.firstOrNull()?.get(key) ?: defaultValue
   }
 
+  /**
+   * Checks if a key is present in the datastore _synchronously_.
+   *
+   * Blocks on the currently running thread.
+   *
+   * Example:
+   * ```java
+   * Preferences.Key<Long> fireCountKey = PreferencesKeys.longKey("fire-count");
+   * assert !dataStore.contains(fireCountKey);
+   *
+   * dataStore.putSync(fireCountKey, 102L);
+   * assert dataStore.contains(fireCountKey);
+   * ```
+   *
+   * @param key The typed key of the entry to find.
+   */
   fun <T> contains(key: Preferences.Key<T>): Boolean = runBlocking {
     dataStore.data.firstOrNull()?.contains(key) ?: false
   }
 
+  /**
+   * Sets and saves data in the datastore _synchronously_.
+   *
+   * Existing values will be overwritten.
+   *
+   * Blocks on the currently running thread.
+   *
+   * Example:
+   * ```java
+   * dataStore.putSync(PreferencesKeys.longKey("fire-count"), 102L);
+   * ```
+   *
+   * @param key The typed key of the entry to save the data under.
+   * @param value The data to save.
+   *
+   * @return The [Preferences] object that the data was saved under.
+   */
   fun <T> putSync(key: Preferences.Key<T>, value: T): Preferences = runBlocking {
     dataStore.edit { it[key] = value }
   }
 
-  /** Do not modify the returned map (should be obvious, since it's immutable though) */
+  /**
+   * Gets all data in the datastore _synchronously_.
+   *
+   * Blocks on the currently running thread.
+   *
+   * Example:
+   * ```java
+   * ArrayList<String> allDates = new ArrayList<>();
+   *
+   * for (Map.Entry<Preferences.Key<?>, Object> entry : dataStore.getAllSync().entrySet()) {
+   *   if (entry.getValue() instanceof Set) {
+   *     Set<String> dates = new HashSet<>((Set<String>) entry.getValue());
+   *     if (!dates.isEmpty()) {
+   *       allDates.add(new ArrayList<>(dates));
+   *     }
+   *   }
+   * }
+   * ```
+   *
+   * @return An _immutable_ map of data currently present in the datastore.
+   */
   fun getAllSync(): Map<Preferences.Key<*>, Any> = runBlocking {
     dataStore.data.firstOrNull()?.asMap() ?: emptyMap()
   }
 
-  /** Edit calls should not be called within edit calls. Is there a way to prevent this? */
+  /**
+   * Transactionally edit data in the datastore _synchronously_.
+   *
+   * Edits made within the [transform] callback will be saved (committed) all at once once the
+   * [transform] block exits.
+   *
+   * Because of the blocking nature of this function, you should _never_ call [editSync] within an
+   * already running [transform] block. Since this can cause a deadlock, [editSync] will instead
+   * throw an exception if it's caught.
+   *
+   * Blocks on the currently running thread.
+   *
+   * Example:
+   * ```java
+   * dataStore.editSync((pref) -> {
+   *   Long heartBeatCount = pref.get(HEART_BEAT_COUNT_TAG);
+   *   if (heartBeatCount == null || heartBeatCount > 30) {
+   *     heartBeatCount = 0L;
+   *   }
+   *   pref.set(HEART_BEAT_COUNT_TAG, heartBeatCount);
+   *   pref.set(LAST_STORED_DATE, "1970-0-1");
+   *
+   *   return null;
+   * });
+   * ```
+   *
+   * @param transform A callback to invoke with the [MutablePreferences] object.
+   *
+   * @return The [Preferences] object that the data was saved under.
+   * @throws IllegalStateException If you attempt to call [editSync] within another [transform]
+   * block.
+   *
+   * @see Preferences.getOrDefault
+   */
   fun editSync(transform: (MutablePreferences) -> Unit): Preferences = runBlocking {
-    if (transforming.get() == true) {
+    if (editLock.get() == true) {
       throw IllegalStateException(
         """
         Don't call DataStorage.edit() from within an existing edit() callback.
@@ -70,15 +195,35 @@ class DataStorage(val context: Context, val name: String) {
           .trimIndent()
       )
     }
-    transforming.set(true)
+    editLock.set(true)
     try {
       dataStore.edit { transform(it) }
     } finally {
-      transforming.set(false)
+      editLock.set(false)
     }
   }
 }
 
-/** Helper for Java code */
+/**
+ * Helper method for getting the value out of a [Preferences] object if it exists, else falling back
+ * to the default value.
+ *
+ * This is primarily useful when working with an instance of [MutablePreferences]
+ * - like when working within an [DataStorage.editSync] callback.
+ *
+ * Example:
+ * ```java
+ * dataStore.editSync((pref) -> {
+ *  long heartBeatCount = DataStoreKt.getOrDefault(pref, HEART_BEAT_COUNT_TAG, 0L);
+ *  heartBeatCount+=1;
+ *  pref.set(HEART_BEAT_COUNT_TAG, heartBeatCount);
+ *
+ *  return null;
+ * });
+ * ```
+ *
+ * @param key The typed key of the entry to get data for.
+ * @param defaultValue A value to default to, if the key isn't found.
+ */
 fun <T> Preferences.getOrDefault(key: Preferences.Key<T>, defaultValue: T) =
   get(key) ?: defaultValue