add more comments

Author: wenxi-zeng

android/src/test/java/com/segment/analytics/kotlin/android/StorageTests.kt

@@ -74,7 +74,7 @@ class StorageTests {
                 "123",
                 UnconfinedTestDispatcher()
             )
-            androidStorage.subscribeToStore()
+            androidStorage.initialize()
         }
 
 

core/src/main/java/com/segment/analytics/kotlin/core/Analytics.kt

@@ -128,7 +128,7 @@ open class Analytics protected constructor(
                 it.provide(System.defaultState(configuration, storage))
 
                 // subscribe to store after state is provided
-                storage.subscribeToStore()
+                storage.initialize()
                 Telemetry.subscribe(store)
             }
 

core/src/main/java/com/segment/analytics/kotlin/core/Storage.kt

@@ -4,20 +4,16 @@ import kotlinx.coroutines.CoroutineDispatcher
 import kotlinx.serialization.json.Json
 import kotlinx.serialization.json.JsonObject
 import sovran.kotlin.Store
-import java.io.File
 import java.io.InputStream
 
 /**
- * Storage interface that abstracts storage of
- * - user data
- * - segment settings
- * - segment events
- * - other configs
- *
- * Constraints:
- * - Segment Events must be stored on a file, following the batch format
- * - all storage is in terms of String (to make API simple)
- * - storage is restricted to keys declared in `Storage.Constants`
+ *     The protocol of how events are read and stored.
+ *     Implement this interface if you wanna your events
+ *     to be read and stored in the way you want (for
+ *     example: from/to remote server, from/to local database
+ *     from/to encrypted source).
+ *     By default, we have implemented read and store events
+ *     from/to memory and file storage.
  */
 interface Storage {
     companion object {
@@ -45,45 +41,64 @@ interface Storage {
         DeviceId("segment.device.id")
     }
 
-    suspend fun subscribeToStore()
+    /**
+     *  Initialization of the storage.
+     *  All prerequisite setups should be done in this method.
+     */
+    suspend fun initialize()
+
+    /**
+     * Write a value of the Storage.Constants type to storage
+     *
+     * @param key The type of the value
+     * @param value Value
+     */
     suspend fun write(key: Constants, value: String)
+
+    /**
+     * Write a key/value pair to prefs
+     *
+     * @param key Key
+     * @param value Value
+     */
     fun writePrefs(key: Constants, value: String)
+
+    /**
+     * Read the value of a given type
+     *
+     * @param key The type of the value
+     * @return value of the given type
+     */
     fun read(key: Constants): String?
+
+    /**
+     * Read the given source stream as an InputStream
+     *
+     * @param source stream to read
+     * @return result as InputStream
+     */
     fun readAsStream(source: String): InputStream?
+
+    /**
+     * Remove the data of a given type
+     *
+     * @param key type of the data to remove
+     * @return status of the operation
+     */
     fun remove(key: Constants): Boolean
+
+    /**
+     * Remove a stream
+     *
+     * @param filePath the fullname/identifier of a stream
+     * @return status of the operation
+     */
     fun removeFile(filePath: String): Boolean
 
     /**
-     * Direct writes to a new file, and close the current file.
-     * This function is useful in cases such as `flush`, that
-     * we want to finish writing the current file, and have it
-     * flushed to server.
+     * Close and finish the current stream and start a new one
      */
     suspend fun rollover()
-
-    suspend fun userInfoUpdate(userInfo: UserInfo) {
-        write(Constants.AnonymousId, userInfo.anonymousId)
-
-        userInfo.userId?.let {
-            write(Constants.UserId, it)
-        } ?: run {
-            remove(Constants.UserId)
-        }
-
-        userInfo.traits?.let {
-            write(Constants.Traits, Json.encodeToString(JsonObject.serializer(), it))
-        } ?: run {
-            remove(Constants.Traits)
-        }
-    }
-
-    suspend fun systemUpdate(system: System) {
-        system.settings?.let {
-            write(Constants.Settings, Json.encodeToString(Settings.serializer(), it))
-        } ?: run {
-            remove(Constants.Settings)
-        }
-    }
 }
 
 fun parseFilePaths(filePathStr: String?): List<String> {

core/src/main/java/com/segment/analytics/kotlin/core/utilities/EventStream.kt

@@ -7,32 +7,81 @@ import java.io.InputStream
 import java.lang.StringBuilder
 import java.util.concurrent.ConcurrentHashMap
 
+/**
+ *     The protocol of how events are read and stored.
+ *     Implement this interface if you wanna your events
+ *     to be read and stored in the way you want (for
+ *     example: from/to remote server, from/to local database
+ *     from/to encrypted source).
+ *     By default, we have implemented read and store events
+ *     from/to memory and file storage.
+ *
+ *     A stream is defined as something that contains a batch of
+ *     events. It can be in the form of any of the following:
+ *      * a file
+ *      * an in-memory entry
+ *      * a table entry in database
+ */
 interface EventStream {
+    /**
+     * Length of current stream
+     */
     val length: Long
 
+    /**
+     * Check if a stream is opened
+     */
     val isOpened: Boolean
 
     /**
-     * open or create a file
-     * @param file name of file
-     * @return true if a new file is created
+     * Open the stream with the given name. Creates a new one if not already exists.
+     *
+     * @param file name of the stream
+     * @return true if a new stream is created
      */
     fun openOrCreate(file: String): Boolean
 
+    /**
+     * Append content to the opening stream
+     *
+     * @param content Content to append
+     */
     fun write(content: String)
 
     /**
-     * read the list of files in directory
-     * @return a list of file names in directory
+     * Read the list of streams in directory
+     * @return a list of stream names in directory
      */
     fun read(): List<String>
 
+    /**
+     * Remove the stream with the given name
+     *
+     * @param file name of stream to be removed
+     */
     fun remove(file: String)
 
+    /**
+     * Close the current opening stream without finish it,
+     * so that the stream can be opened for future appends.
+     */
     fun close()
 
+    /**
+     * Close and finish the current opening stream.
+     * Pass a withRename closure if you want to distinguish completed
+     * streams from ongoing stream
+     *
+     * @param withRename a callback that renames a finished stream
+     */
     fun finishAndClose(withRename: ((name: String) -> String)? = null)
 
+    /**
+     * Read the stream with the given name as an InputStream.
+     * Needed for HTTPClient to upload data
+     *
+     * @param source the full name of a stream
+     */
     fun readAsStream(source: String): InputStream?
 }
 
@@ -81,16 +130,14 @@ class InMemoryEventStream: EventStream {
     }
 
     override fun finishAndClose(withRename: ((name: String) -> String)?) {
-        currFile ?: return
-
         currFile?.let {
             withRename?.let { rename ->
                 directory.remove(it.name)
                 directory[rename(it.name)] = it
             }
+            currFile = null
         }
 
-        currFile = null
     }
 
     override fun readAsStream(source: String): InputStream? = directory[source]?.toStream()
@@ -158,6 +205,13 @@ class FileEventStream(
 
     override fun read(): List<String> = (directory.listFiles() ?: emptyArray()).map { it.absolutePath }
 
+    /**
+     * Remove the given file from disk
+     *
+     * NOTE: file string has to be the full path of the file
+     *
+     * @param file full path of the file to be deleted
+     */
     override fun remove(file: String) {
         File(file).delete()
     }

core/src/main/java/com/segment/analytics/kotlin/core/utilities/KVS.kt

@@ -12,11 +12,52 @@ interface KVS {
     @Deprecated("Deprecated in favor of `put`", ReplaceWith("put(key, value)"))
     fun putInt(key: String, value: Int): Boolean = put(key, value)
 
+    /**
+     * Read the value of a given key as integer
+     * @param key Key
+     * @param defaultVal Fallback value to use
+     * @return Value
+     */
     fun get(key: String, defaultVal: Int): Int
+
+    /**
+     * Store the key value pair
+     * @param key Key
+     * @param value Fallback value to use
+     * @return Status of the operation
+     */
     fun put(key: String, value: Int): Boolean
+
+    /**
+     * Read the value of a given key as integer
+     * @param key Key
+     * @param defaultVal Fallback value to use
+     * @return Value
+     */
     fun get(key: String, defaultVal: String?): String?
+
+    /**
+     * Store the key value pair
+     * @param key Key
+     * @param value Fallback value to use
+     * @return Status of the operation
+     */
     fun put(key: String, value: String): Boolean
+
+    /**
+     * Remove a key/value pair by key
+     *
+     * @param key Key
+     * @return Status of the operation
+     */
     fun remove(key: String): Boolean
+
+    /**
+     * checks if a given key exists
+     *
+     * @param Key
+     * @return Status of the operation
+     */
     fun contains(key: String): Boolean
 }
 

core/src/main/java/com/segment/analytics/kotlin/core/utilities/StorageImpl.kt

@@ -1,6 +1,7 @@
 package com.segment.analytics.kotlin.core.utilities
 
 import com.segment.analytics.kotlin.core.Analytics
+import com.segment.analytics.kotlin.core.Settings
 import com.segment.analytics.kotlin.core.Storage
 import com.segment.analytics.kotlin.core.Storage.Companion.MAX_FILE_SIZE
 import com.segment.analytics.kotlin.core.Storage.Companion.MAX_PAYLOAD_SIZE
@@ -10,6 +11,8 @@ import com.segment.analytics.kotlin.core.UserInfo
 import com.segment.analytics.kotlin.core.reportInternalError
 import kotlinx.coroutines.CoroutineDispatcher
 import kotlinx.coroutines.sync.Semaphore
+import kotlinx.serialization.json.Json
+import kotlinx.serialization.json.JsonObject
 import sovran.kotlin.Store
 import sovran.kotlin.Subscriber
 import java.io.File
@@ -41,7 +44,7 @@ open class StorageImpl(
     private val currentFile
         get() = "$writeKey-${propertiesFile.get(fileIndexKey, 0)}.$ext"
 
-    override suspend fun subscribeToStore() {
+    override suspend fun initialize() {
         store.subscribe(
             this,
             UserInfo::class,
@@ -58,6 +61,30 @@ open class StorageImpl(
         )
     }
 
+    suspend fun userInfoUpdate(userInfo: UserInfo) {
+        write(Storage.Constants.AnonymousId, userInfo.anonymousId)
+
+        userInfo.userId?.let {
+            write(Storage.Constants.UserId, it)
+        } ?: run {
+            remove(Storage.Constants.UserId)
+        }
+
+        userInfo.traits?.let {
+            write(Storage.Constants.Traits, Json.encodeToString(JsonObject.serializer(), it))
+        } ?: run {
+            remove(Storage.Constants.Traits)
+        }
+    }
+
+    suspend fun systemUpdate(system: System) {
+        system.settings?.let {
+            write(Storage.Constants.Settings, Json.encodeToString(Settings.serializer(), it))
+        } ?: run {
+            remove(Storage.Constants.Settings)
+        }
+    }
+
     override suspend fun write(key: Storage.Constants, value: String) {
         when (key) {
             Storage.Constants.Events -> {

core/src/test/kotlin/com/segment/analytics/kotlin/core/utilities/EventStreamTest.kt

@@ -177,6 +177,7 @@ class EventStreamTest {
         fun openOrCreateTest() {
             var actual = eventStream.openOrCreate("test.tmp")
             assertTrue(actual)
+            assertTrue(File(dir, "test.tmp").exists())
 
             actual = eventStream.openOrCreate("test.tmp")
             assertFalse(actual)
@@ -234,7 +235,11 @@ class EventStreamTest {
             eventStream.finishAndClose {
                 removeFileExtension(it)
             }
-            eventStream.remove("test")
+            assertTrue(File(dir, "test").exists())
+
+            eventStream.remove(File(dir, "test").absolutePath)
+            assertFalse(File(dir, "test").exists())
+
             val newFile = eventStream.openOrCreate("test.tmp")
 
             assertTrue(newFile)

core/src/test/kotlin/com/segment/analytics/kotlin/core/utilities/StorageImplTest.kt

@@ -75,7 +75,7 @@ internal class StorageImplTest {
             }
         }
         storage = storageProvider.createStorage() as StorageImpl
-        storage.subscribeToStore()
+        storage.initialize()
     }