(DOCSP-14675): Realm Android SDK Local-only Quickstart (mongodb#821)

examples/android/local/app/src/main/java/com/mongodb/realm/examples/java/MainActivity.java

@@ -1,3 +1,4 @@
+// :code-block-start: complete
 package com.mongodb.realm.examples.java;
 
 import io.realm.OrderedCollectionChangeSet;
@@ -31,7 +32,7 @@ public class MainActivity extends AppCompatActivity {
     protected void onCreate(Bundle savedInstanceState) {
         super.onCreate(savedInstanceState);
 
-        // :code-block-start: initialize-realm
+        // :code-block-start: initialize-realm-local
         Realm.init(this); // context, usually an Activity or Application
         // :code-block-end:
 
@@ -63,7 +64,7 @@ protected void onCreate(Bundle savedInstanceState) {
     }
 
     private void addChangeListenerToRealm(Realm realm) {
-        // :code-block-start: watch-for-changes
+        // :code-block-start: watch-for-changes-local
         // all tasks in the realm
         RealmResults<Task> tasks = uiThreadRealm.where(Task.class).findAllAsync();
 
@@ -101,32 +102,32 @@ public class BackgroundQuickStart implements Runnable {
 
         @Override
         public void run() {
-            // :code-block-start: open-a-realm
+            // :code-block-start: open-a-realm-local
             String partitionValue = "My Project";
             RealmConfiguration config = new RealmConfiguration.Builder().build();
 
             Realm backgroundThreadRealm = Realm.getInstance(config);
             // :code-block-end:
 
-            // :code-block-start: create-object
+            // :code-block-start: create-object-local
             Task task = new Task("New Task");
             backgroundThreadRealm.executeTransaction (transactionRealm -> {
                 transactionRealm.insert(task);
             });
             // :code-block-end:
 
-            // :code-block-start: read-object
+            // :code-block-start: read-object-local
             // all tasks in the realm
             RealmResults<Task> tasks = backgroundThreadRealm.where(Task.class).findAll();
             // :code-block-end:
 
-            // :code-block-start: filter-collection
+            // :code-block-start: filter-collection-local
             // you can also filter a collection
             RealmResults<Task> tasksThatBeginWithN = tasks.where().beginsWith("name", "N").findAll();
             RealmResults<Task> openTasks = tasks.where().equalTo("status", TaskStatus.Open.name()).findAll();
             // :code-block-end:
 
-            // :code-block-start: update-object
+            // :code-block-start: update-object-local
             Task otherTask = tasks.get(0);
 
             // all modifications to a realm must happen inside of a write block
@@ -136,7 +137,7 @@ public void run() {
             });
             // :code-block-end:
 
-            // :code-block-start: delete-object
+            // :code-block-start: delete-object-local
             Task yetAnotherTask = tasks.get(0);
             ObjectId yetAnotherTaskId = yetAnotherTask.get_id();
             // all modifications to a realm must happen inside of a write block
@@ -152,3 +153,4 @@ public void run() {
         }
     }
 }
+// :code-block-end:

examples/android/local/app/src/main/java/com/mongodb/realm/examples/kotlin/MainActivity.kt

@@ -1,3 +1,4 @@
+// :code-block-start: complete
 package com.mongodb.realm.examples.kotlin
 
 import org.bson.types.ObjectId
@@ -21,7 +22,7 @@ class MainActivity : AppCompatActivity() {
     override fun onCreate(savedInstanceState: Bundle?) {
         super.onCreate(savedInstanceState)
 
-        // :code-block-start: initialize-realm
+        // :code-block-start: initialize-realm-local
         Realm.init(this) // context, usually an Activity or Application
         // :code-block-end:
 
@@ -44,12 +45,10 @@ class MainActivity : AppCompatActivity() {
 
         finish() // destroy activity when background task completes
         // :hide-end:
-        // :code-block-end:
-
     }
 
     fun addChangeListenerToRealm(realm : Realm) {
-        // :code-block-start: watch-for-changes
+        // :code-block-start: watch-for-changes-local
         // all tasks in the realm
         val tasks : RealmResults<Task> = realm.where<Task>().findAllAsync()
 
@@ -84,32 +83,32 @@ class MainActivity : AppCompatActivity() {
     class BackgroundQuickStart : Runnable {
 
         override fun run() {
-            // :code-block-start: open-a-realm
+            // :code-block-start: open-a-realm-local
             val partitionValue: String = "My Project"
             val config = RealmConfiguration.Builder().build()
 
             val backgroundThreadRealm : Realm = Realm.getInstance(config)
             // :code-block-end:
 
-            // :code-block-start: create-object
+            // :code-block-start: create-object-local
             val task : Task = Task("New Task", partitionValue)
             backgroundThreadRealm.executeTransaction { transactionRealm ->
                 transactionRealm.insert(task)
             }
             // :code-block-end:
 
-            // :code-block-start: read-object
+            // :code-block-start: read-object-local
             // all tasks in the realm
             val tasks : RealmResults<Task> = backgroundThreadRealm.where<Task>().findAll()
             // :code-block-end:
 
-            // :code-block-start: filter-collection
+            // :code-block-start: filter-collection-local
             // you can also filter a collection
             val tasksThatBeginWithN : List<Task> = tasks.where().beginsWith("name", "N").findAll()
             val openTasks : List<Task> = tasks.where().equalTo("status", TaskStatus.Open.name).findAll()
             // :code-block-end:
 
-            // :code-block-start: update-object
+            // :code-block-start: update-object-local
             val otherTask: Task = tasks[0]!!
 
             // all modifications to a realm must happen inside of a write block
@@ -119,7 +118,7 @@ class MainActivity : AppCompatActivity() {
             }
             // :code-block-end:
 
-            // :code-block-start: delete-object
+            // :code-block-start: delete-object-local
             val yetAnotherTask: Task = tasks.get(0)!!
             val yetAnotherTaskId: ObjectId = yetAnotherTask._id
             // all modifications to a realm must happen inside of a write block
@@ -137,7 +136,7 @@ class MainActivity : AppCompatActivity() {
     }
 }
 
-// :code-block-start: define-object-model
+// :code-block-start: define-object-model-local
 
 enum class TaskStatus(val displayName: String) {
     Open("Open"),
@@ -165,4 +164,5 @@ open class Task(_name: String = "Task", project: String = "My Project") : RealmO
         set(value) { status = value.name }
 }
 
+// :code-block-end:
 // :code-block-end:

examples/android/local/app/src/main/java/com/mongodb/realm/examples/model/Task.java

@@ -1,4 +1,4 @@
-// :code-block-start: define-object-model
+// :code-block-start: define-object-model-local
 package com.mongodb.realm.examples.model;
 
 import io.realm.RealmObject;

examples/android/local/app/src/main/java/com/mongodb/realm/examples/model/TaskStatus.java

@@ -1,3 +1,4 @@
+// :code-block-start: define-object-model-local
 package com.mongodb.realm.examples.model;
 
 public enum TaskStatus {
@@ -10,3 +11,4 @@ public enum TaskStatus {
         this.displayName = displayName;
     }
 }
+// :code-block-end:

source/examples/generated/android/MainActivity.codeblock.complete.codeblock.create-object-local.java

@@ -0,0 +1,4 @@
+Task task = new Task("New Task");
+backgroundThreadRealm.executeTransaction (transactionRealm -> {
+    transactionRealm.insert(task);
+});

source/examples/generated/android/MainActivity.codeblock.complete.codeblock.delete-object-local.java

@@ -0,0 +1,7 @@
+Task yetAnotherTask = tasks.get(0);
+ObjectId yetAnotherTaskId = yetAnotherTask.get_id();
+// all modifications to a realm must happen inside of a write block
+backgroundThreadRealm.executeTransaction( transactionRealm -> {
+    Task innerYetAnotherTask = transactionRealm.where(Task.class).equalTo("_id", yetAnotherTaskId).findFirst();
+    innerYetAnotherTask.deleteFromRealm();
+});

source/examples/generated/android/MainActivity.codeblock.complete.codeblock.filter-collection-local.java

@@ -0,0 +1,3 @@
+// you can also filter a collection
+RealmResults<Task> tasksThatBeginWithN = tasks.where().beginsWith("name", "N").findAll();
+RealmResults<Task> openTasks = tasks.where().equalTo("status", TaskStatus.Open.name()).findAll();

source/examples/generated/android/MainActivity.codeblock.complete.codeblock.initialize-realm-local.java

@@ -0,0 +1 @@
+Realm.init(this); // context, usually an Activity or Application

source/examples/generated/android/MainActivity.codeblock.complete.codeblock.open-a-realm-local.java

@@ -0,0 +1,4 @@
+String partitionValue = "My Project";
+RealmConfiguration config = new RealmConfiguration.Builder().build();
+
+Realm backgroundThreadRealm = Realm.getInstance(config);

source/examples/generated/android/MainActivity.codeblock.complete.codeblock.read-object-local.java

@@ -0,0 +1,2 @@
+// all tasks in the realm
+RealmResults<Task> tasks = backgroundThreadRealm.where(Task.class).findAll();

source/examples/generated/android/MainActivity.codeblock.complete.codeblock.update-object-local.java

@@ -0,0 +1,7 @@
+Task otherTask = tasks.get(0);
+
+// all modifications to a realm must happen inside of a write block
+backgroundThreadRealm.executeTransaction( transactionRealm -> {
+    Task innerOtherTask = transactionRealm.where(Task.class).equalTo("_id", otherTask.get_id()).findFirst();
+    innerOtherTask.setStatus(TaskStatus.Complete);
+});

source/examples/generated/android/MainActivity.codeblock.complete.codeblock.watch-for-changes-local.java

@@ -0,0 +1,21 @@
+// all tasks in the realm
+RealmResults<Task> tasks = uiThreadRealm.where(Task.class).findAllAsync();
+
+tasks.addChangeListener(new OrderedRealmCollectionChangeListener<RealmResults<Task>>() {
+    @Override
+    public void onChange(RealmResults<Task> collection, OrderedCollectionChangeSet changeSet) {
+        // process deletions in reverse order if maintaining parallel data structures so indices don't change as you iterate
+        OrderedCollectionChangeSet.Range[] deletions = changeSet.getDeletionRanges();
+        for (OrderedCollectionChangeSet.Range range : deletions) {
+            Log.v("QUICKSTART", "Deleted range: " + range.startIndex + " to " + (range.startIndex + range.length - 1));
+        }
+
+        OrderedCollectionChangeSet.Range[] insertions = changeSet.getInsertionRanges();
+        for (OrderedCollectionChangeSet.Range range : insertions) {
+            Log.v("QUICKSTART", "Inserted range: " + range.startIndex + " to " + (range.startIndex + range.length - 1));                            }
+
+        OrderedCollectionChangeSet.Range[] modifications = changeSet.getChangeRanges();
+        for (OrderedCollectionChangeSet.Range range : modifications) {
+            Log.v("QUICKSTART", "Updated range: " + range.startIndex + " to " + (range.startIndex + range.length - 1));                            }
+    }
+});

source/examples/generated/android/MainActivity.codeblock.complete.java

@@ -0,0 +1,124 @@
+package com.mongodb.realm.examples.java;
+
+import io.realm.OrderedCollectionChangeSet;
+
+import org.bson.types.ObjectId;
+
+import android.os.Bundle;
+
+import androidx.appcompat.app.AppCompatActivity;
+import android.util.Log;
+
+import io.realm.OrderedRealmCollectionChangeListener;
+
+import io.realm.Realm;
+import io.realm.RealmConfiguration;
+import io.realm.RealmResults;
+
+import java.util.concurrent.ExecutionException;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.FutureTask;
+
+import com.mongodb.realm.examples.model.Task;
+import com.mongodb.realm.examples.model.TaskStatus;
+
+
+public class MainActivity extends AppCompatActivity {
+    Realm uiThreadRealm;
+
+    @Override
+    protected void onCreate(Bundle savedInstanceState) {
+        super.onCreate(savedInstanceState);
+
+        Realm.init(this); // context, usually an Activity or Application
+
+        String partitionValue = "My Project";
+        RealmConfiguration config = new RealmConfiguration.Builder().build();
+
+        uiThreadRealm = Realm.getInstance(config);
+
+        addChangeListenerToRealm(uiThreadRealm);
+
+        FutureTask<String> task = new FutureTask(new BackgroundQuickStart(), "test");
+        ExecutorService executorService = Executors.newFixedThreadPool(2);
+        executorService.execute(task);
+
+    }
+
+    private void addChangeListenerToRealm(Realm realm) {
+        // all tasks in the realm
+        RealmResults<Task> tasks = uiThreadRealm.where(Task.class).findAllAsync();
+
+        tasks.addChangeListener(new OrderedRealmCollectionChangeListener<RealmResults<Task>>() {
+            @Override
+            public void onChange(RealmResults<Task> collection, OrderedCollectionChangeSet changeSet) {
+                // process deletions in reverse order if maintaining parallel data structures so indices don't change as you iterate
+                OrderedCollectionChangeSet.Range[] deletions = changeSet.getDeletionRanges();
+                for (OrderedCollectionChangeSet.Range range : deletions) {
+                    Log.v("QUICKSTART", "Deleted range: " + range.startIndex + " to " + (range.startIndex + range.length - 1));
+                }
+
+                OrderedCollectionChangeSet.Range[] insertions = changeSet.getInsertionRanges();
+                for (OrderedCollectionChangeSet.Range range : insertions) {
+                    Log.v("QUICKSTART", "Inserted range: " + range.startIndex + " to " + (range.startIndex + range.length - 1));                            }
+
+                OrderedCollectionChangeSet.Range[] modifications = changeSet.getChangeRanges();
+                for (OrderedCollectionChangeSet.Range range : modifications) {
+                    Log.v("QUICKSTART", "Updated range: " + range.startIndex + " to " + (range.startIndex + range.length - 1));                            }
+            }
+        });
+    }
+
+
+        @Override
+    protected void onDestroy() {
+        super.onDestroy();
+        // the ui thread realm uses asynchronous transactions, so we can only safely close the realm
+        // when the activity ends and we can safely assume that those transactions have completed
+        uiThreadRealm.close();
+    }
+
+    public class BackgroundQuickStart implements Runnable {
+
+        @Override
+        public void run() {
+            String partitionValue = "My Project";
+            RealmConfiguration config = new RealmConfiguration.Builder().build();
+
+            Realm backgroundThreadRealm = Realm.getInstance(config);
+
+            Task task = new Task("New Task");
+            backgroundThreadRealm.executeTransaction (transactionRealm -> {
+                transactionRealm.insert(task);
+            });
+
+            // all tasks in the realm
+            RealmResults<Task> tasks = backgroundThreadRealm.where(Task.class).findAll();
+
+            // you can also filter a collection
+            RealmResults<Task> tasksThatBeginWithN = tasks.where().beginsWith("name", "N").findAll();
+            RealmResults<Task> openTasks = tasks.where().equalTo("status", TaskStatus.Open.name()).findAll();
+
+            Task otherTask = tasks.get(0);
+
+            // all modifications to a realm must happen inside of a write block
+            backgroundThreadRealm.executeTransaction( transactionRealm -> {
+                Task innerOtherTask = transactionRealm.where(Task.class).equalTo("_id", otherTask.get_id()).findFirst();
+                innerOtherTask.setStatus(TaskStatus.Complete);
+            });
+
+            Task yetAnotherTask = tasks.get(0);
+            ObjectId yetAnotherTaskId = yetAnotherTask.get_id();
+            // all modifications to a realm must happen inside of a write block
+            backgroundThreadRealm.executeTransaction( transactionRealm -> {
+                Task innerYetAnotherTask = transactionRealm.where(Task.class).equalTo("_id", yetAnotherTaskId).findFirst();
+                innerYetAnotherTask.deleteFromRealm();
+            });
+
+            // because this background thread uses synchronous realm transactions, at this point all
+            // transactions have completed and we can safely close the realm
+            backgroundThreadRealm.close();
+        }
+    }
+}