docs: document feature, brownfield integration

Author: Krzysztof Borowy

website/docs/Linking.md

@@ -5,7 +5,6 @@ sidebar_label: Manual linking
 ---
 
 
-
 ## iOS
 
 #### Project linking

website/docs/advanced/BrownfieldIntegration.md

@@ -7,9 +7,12 @@ import PlatformSupport from "../../src/components/Platform.js"
 
 **Supported platforms:**
 <PlatformSupport title="iOS/MacOS" platformIcon="icon_ios.svg"></PlatformSupport>
+<PlatformSupport title="Android" platformIcon="icon_android.svg"></PlatformSupport>
 
 ---
 
+# iOS
+
 If you're embedding React Native into native application, you can also integrate
 Async Storage module, so that both worlds will use one storage solution.
 
@@ -110,3 +113,119 @@ Called by `getItem` and `multiGet` in JS.
 **Optional:** Returns whether the delegate should be treated as a passthrough.
 This is useful for monitoring storage usage among other things. Returns `NO` by
 default.
+
+---
+
+# Android
+
+The recommended approach here is to use Kotlin language to leverage coroutines when accessing the storage.
+Java is also supported (through Kotlin interop), but the approach is more cumbersome.
+
+
+## Prerequisites
+
+1. [Next storage feature](Next.md) enabled.
+2. Add dependency on `coroutines-android` in your app's `build.gradle`
+
+```diff
+
+dependencies {
+  // other dependencies
+
+
+  // will work with coroutines 1.3.0 and up
++ implementation "org.jetbrains.kotlinx:kotlinx-coroutines-android:1.3.9"
+
+}
+```
+
+3. Your library of choice for parsing JSON storage values (since there are strings only)
+
+
+## Access storage
+
+### Kotlin (recommended)
+
+We use Coroutines to handle asynchronous code. Each method on storage is `suspend` method, so you need to
+call it from within a coroutine.
+
+
+#### Reading value
+
+```kotlin
+suspend fun readValue(ctx: Context, keys: List<String>) {
+    // get instance of the Storage by providing context object
+    val asyncStorage = StorageModule.getStorageInstance(ctx)
+
+    val entries: List<Entry> = asyncStorage.getValues(keys)
+    doSomethingWithValues(entries)
+}
+```
+
+#### Saving value
+
+```kotlin
+suspend fun saveValue(ctx: Context) {
+    val asyncStorage = StorageModule.getStorageInstance(ctx)
+
+    val entries = listOf(
+        Entry("myKey", "myValue")
+    )
+    asyncStorage.setValues(entries)
+}
+```
+
+
+### Java
+
+You can access AsyncStorage form Java, but you're still required to add Kotlin dependencies.
+There's no one way of accessing the data and there's more than one way to parse it.
+
+
+#### Reading from storage
+
+```java
+void readStorageValue(Context ctx, String key) {
+    AsyncStorageAccess asyncStorage = StorageModule.getStorageInstance(ctx);
+
+    BuildersKt.launch(GlobalScope.INSTANCE,
+            Dispatchers.getIO(),
+            CoroutineStart.DEFAULT,
+            (scope, continuation) -> {
+                List<String> keys = new ArrayList<>();
+                keys.add(key);
+
+                List<Entry> entries = (List<Entry>) asyncStorage.getValues(keys, (Continuation<? super List<? extends Entry>>) continuation);
+                doSomethingWithValues(entries);
+
+                return Unit.INSTANCE;
+            });
+
+}
+```
+
+
+#### Saving to storage
+
+```java
+void saveStorageValue(Context ctx, String key, String value) {
+  AsyncStorageAccess asyncStorage = StorageModule.getStorageInstance(ctx);
+
+  BuildersKt.launch(GlobalScope.INSTANCE,
+          Dispatchers.getIO(),
+          CoroutineStart.DEFAULT,
+          (scope, continuation) -> {
+
+            List<Entry> entries = new ArrayList<>();
+            Entry entry = new Entry(key, value);
+            entries.add(entry);
+
+            asyncStorage.setValues(entries, continuation);
+
+            return Unit.INSTANCE;
+          });
+}
+```
+
+
+

website/docs/advanced/DedicatedExecutor.md

@@ -10,10 +10,12 @@ import PlatformSupport from "../../src/components/Platform.js"
 
 ---
 
-This feature would be mostly used in brownfield apps and [in edge cases with some android devices.](https://github.com/react-native-async-storage/async-storage/issues/159)
+**Note**: This feature is obsolete when [Next storage feature is enabled](Next.md).
+
 
 ## Motivation
 
+This feature would be mostly used in brownfield apps and [in edge cases with some android devices.](https://github.com/react-native-async-storage/async-storage/issues/159)
 Dedicated thread pool executor makes `AsyncStorage` use separate thread pool for its tasks execution.
 
 Use this feature if `THREAD_POOL_EXECUTOR` from `AsyncTasks`:

website/docs/advanced/IncreaseDbSize.md

@@ -10,9 +10,13 @@ import PlatformSupport from "../../src/components/Platform.js"
 
 ---
 
+**Note**: This feature is obsolete when [Next storage feature is enabled](Next.md).
+
+## Motivation
+
 Current Async Storage's size is set to 6MB. Going over this limit causes `database or disk is full` error. This 6MB limit is a sane limit to protect the user from the app storing too much data in the database. This also protects the database from filling up the disk cache and becoming malformed (endTransaction() calls will throw an exception, not rollback, and leave the db malformed). You have to be aware of that risk when increasing the database size. We recommend to ensure that your app does not write more data to AsyncStorage than space is left on disk. Since AsyncStorage is based on SQLite on Android you also have to be aware of the [SQLite limits](https://www.sqlite.org/limits.html).
 
-### Increase limit
+## Increase limit
 
 Add a `AsyncStorage_db_size_in_MB` property to your `android/gradle.properties`:
 

website/docs/advanced/Next.md

@@ -0,0 +1,85 @@
+---
+id: next
+title: Next storage implementation
+sidebar_label: Next storage implementation
+---
+import PlatformSupport from "../../src/components/Platform.js"
+
+**Supported platforms:**
+<PlatformSupport title="Android" platformIcon="icon_android.svg"></PlatformSupport>
+
+---
+
+### Motivation
+
+Current implementation of persistence layer is created using [SQLiteOpenHelper](https://developer.android.com/reference/android/database/sqlite/SQLiteOpenHelper), 
+a helper class that manages database creation and migrations. Even if this approach is powerful, the lack of compile time query verification and a big boilerplate of mapping SQLite queries  to actual values make this implementation prone to many errors.
+
+This Async Storage feature improves the persistence layer, using modern approaches to access SQLite (using [Room](https://developer.android.com/training/data-storage/room)), to reduce possible anomalies to the minimum. 
+On top of that, it allows to access Async Storage from the native side, useful in [Brownfield integration.](BrownfieldIntegration.md#android)
+
+### Migration
+
+This feature requires no migration from the developer perspective - the current database will be recreated (based on the current one), meaning user won't lose any data if you decide to opt in.
+There's a small drawback to know - the database "recreation" happens **only once**. Unless you want to disable the feature in the future, there's nothing to worry about.
+
+#### How it works
+
+The new database (the one used by this feature) will be created based on the current database file, if the new one does not exist yet. 
+If we detect that there's already the new database on the device, recreation will not kick in.
+
+
+#### Why is it important
+
+Let's say you enabled the feature for the first time - recreation kicks in and the old database file is untouched.
+If you decide to disable the feature, your users will be back using old database. No data migrations is happening from new to old database file.
+When you enable the feature again, the new database is **not** recreated, because it already exists, and no data is copied over.
+
+
+### Enabling
+
+1. In your project's `android` directory, locate root `build.gradle` file. Add Kotlin dependency to the `buildscript`:
+
+```diff
+buildscript {
+    ext {
+        // other extensions
++        kotlinVersion = '1.4.21'
+    }
+    
+    dependencies {
+        // other dependencies
++        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlinVersion"
+    }
+}
+
+```
+
+2. In the same directory (normally `android`) locate `gradle.properties` file (if does not exists, create one) and add the line:
+
+```groovy
+AsyncStorage_useNextStorage=true
+```
+
+**How to specifying Kotlin version**
+
+Supported Kotlin versions are `1.4.x`. You can specify which one to use in two ways:
+
+- having an `kotlinVersion` extension on the `rootProject` (recommended):
+
+```groovy
+rootProject.ext.kotlinVersion = '1.4.21'
+```
+
+- specify `AsyncStorage_kotlinVersion` in `gradle.properties`:
+
+```groovy
+AsyncStorage_kotlinVersion=1.4.21
+```
+
+### Notable changes
+
+Alongside of a warning regarding `key`/`value`, errors are thrown when:
+
+- Your `key` is `null` or `not a string`
+- You provide value that is `not a string` 

website/sidebars.js

@@ -1,7 +1,7 @@
 module.exports = {
   docs: {
     'Getting started': ['install', 'usage', 'link', 'api'],
-    Advanced: ['advanced/jest', 'advanced/brownfield', 'advanced/backup', 'advanced/executor', 'advanced/db_size'],
+    Advanced: ['advanced/next', 'advanced/jest', 'advanced/brownfield', 'advanced/backup', 'advanced/executor', 'advanced/db_size'],
     Help: ['help/troubleshooting'],
   },
 };