DOCSP-4381 Revamp crud flow, add examples

android/services/mongodb-remote/src/main/java/com/mongodb/stitch/android/services/mongodb/remote/RemoteMongoClient.java

@@ -22,7 +22,19 @@
 import com.mongodb.stitch.core.services.mongodb.remote.sync.internal.CoreRemoteClientFactory;
 
 /**
- * The remote MongoClient used for working with data in MongoDB remotely via Stitch.
+ * The RemoteMongoClient is the entry point for working with data in MongoDB
+ * remotely via Stitch.
+ * <p>
+ * An instance can be retrieved using {@link com.mongodb.stitch.android.core.StitchAppClient#getServiceClient}
+ * with this class's {@link factory}.
+ * </p><p>
+ * Before using the database, you will have to log in using {@link com.mongodb.stitch.android.core.auth.StitchAuth}.
+ * </p><p>
+ * Once logged in, you can access the database with {@link getDatabase}.
+ * </p>
+ * @see com.mongodb.stitch.android.core.StitchAppClient
+ * @see com.mongodb.stitch.android.core.auth.StitchAuth
+ * @see RemoteMongoDatabase
  */
 public interface RemoteMongoClient {
 

android/services/mongodb-remote/src/main/java/com/mongodb/stitch/android/services/mongodb/remote/RemoteMongoCollection.java

@@ -35,22 +35,42 @@
 import org.bson.types.ObjectId;
 
 /**
- * The RemoteMongoCollection interface.
+ * The RemoteMongoCollection interface provides read and write access to documents.
+ * <p>
+ * Use {@link RemoteMongoDatabase#getCollection} to get a collection instance.
+ * </p><p>
+ * Before any access is possible, there must be an active, logged-in user. See
+ * {@link com.mongodb.stitch.android.core.auth.StitchAuth} for how to log in.
+ * </p><p>
+ * Create, read, update and delete (CRUD) functionality is available depending
+ * on the privileges of the active logged-in user. You can set up 
+ * <a href="https://docs.mongodb.com/stitch/mongodb/define-roles-and-permissions/" target=".">Roles</a>
+ * in the Stitch console. Stitch checks any given request against the Roles for the
+ * active user and determines whether the request is permitted for each requested
+ * document.
+ * </p>
+ *
+ * @see RemoteMongoDatabase
+ * @see <a href="https://docs.mongodb.com/stitch/mongodb/" target=".">MongoDB Atlas Overview with Stitch</a>
  *
  * @param <DocumentT> The type that this collection will encode documents from and decode documents
  *                   to.
  */
 public interface RemoteMongoCollection<DocumentT> {
 
   /**
-   * Gets the namespace of this collection.
+   * Gets the namespace of this collection, i.e. the database and collection names together.
    *
    * @return the namespace
    */
   MongoNamespace getNamespace();
 
   /**
    * Get the class of documents stored in this collection.
+   * <p>
+   * If you used the simple {@link RemoteMongoDatabase#getCollection(String)} to get this collection,
+   * this is {@link org.bson.Document}.
+   * </p>
    *
    * @return the class
    */
@@ -125,15 +145,15 @@ <NewDocumentT> RemoteMongoCollection<NewDocumentT> withDocumentClass(
   <ResultT> RemoteFindIterable<ResultT> find(final Class<ResultT> resultClass);
 
   /**
-   * Finds all documents in the collection.
+   * Finds all documents in the collection that match the given filter.
    *
    * @param filter the query filter
    * @return the find iterable interface
    */
   RemoteFindIterable<DocumentT> find(final Bson filter);
 
   /**
-   * Finds all documents in the collection.
+   * Finds all documents in the collection that match the given filter.
    *
    * @param filter      the query filter
    * @param resultClass the class to decode each document into

android/services/mongodb-remote/src/main/java/com/mongodb/stitch/android/services/mongodb/remote/RemoteMongoDatabase.java

@@ -19,7 +19,15 @@
 import org.bson.Document;
 
 /**
- * The RemoteMongoDatabase interface.
+ * The RemoteMongoDatabase interface provides access to its {@link RemoteMongoCollection}s.
+ * <p>
+ * In order to obtain an instance of the database, use {@link RemoteMongoClient#getDatabase}.
+ * </p><p>
+ * Once you have a database, you can use {@link getCollection} to get a collection
+ * to start reading and writing documents.
+ * </p>
+ * @see RemoteMongoClient
+ * @see RemoteMongoCollection
  */
 public interface RemoteMongoDatabase {
 
@@ -31,7 +39,7 @@ public interface RemoteMongoDatabase {
   String getName();
 
   /**
-   * Gets a collection.
+   * Gets a {@link RemoteMongoCollection}.
    *
    * @param collectionName the name of the collection to return
    * @return the collection

contrib/docs-examples/com/mongodb/stitch/android/core/StitchAppClient.java

@@ -0,0 +1,28 @@
+// Get the default app client. This is automatically initialized by Stitch
+// if there is a `stitch_client_app_id` value in the values/strings.xml file.
+StitchAppClient appClient = Stitch.getDefaultAppClient();
+
+// Log in anonymously. Some form of login is required before we can read documents.
+appClient.getAuth().loginWithCredential(new AnonymousCredential()).addOnCompleteListener(new OnCompleteListener<StitchUser>() {
+    @Override
+    public void onComplete(@NonNull Task<StitchUser> task) {
+        if (!task.isSuccessful()) {
+            Log.e(TAG, "Failed to log in!", task.getException());
+            return;
+        }
+
+        // Get the Atlas client.
+        RemoteMongoClient mongoClient = appClient.getServiceClient(RemoteMongoClient.factory, "mongodb-atlas");
+        RemoteMongoDatabase db = mongoClient.getDatabase("video");
+        RemoteMongoCollection<Document> movieDetails = db.getCollection("movieDetails");
+
+        // Find 20 documents
+        movieDetails.find()
+                .projection(new Document().append("title", 1).append("year", 1))
+                .limit(20)
+                .forEach(document -> {
+            // Print documents to the log.
+            Log.i(TAG, "Got document: " + document.toString());
+        });
+    }
+});

contrib/docs-examples/com/mongodb/stitch/android/services/mongodb/remote/RemoteMongoClient.java

@@ -0,0 +1,8 @@
+// Find 20 documents in a collection
+// Note: log in first -- see StitchAuth
+RemoteMongoClient mongoClient = appClient.getServiceClient(RemoteMongoClient.factory, "mongodb-atlas");
+RemoteMongoDatabase db = mongoClient.getDatabase("video");
+RemoteMongoCollection<Document> movieDetails = db.getCollection("movieDetails");
+movieDetails.find().limit(20).forEach(document -> {
+    Log.i(TAG, "Got document: " + document.toString());
+});

contrib/docs-examples/com/mongodb/stitch/android/services/mongodb/remote/RemoteMongoCollection.java

@@ -0,0 +1,14 @@
+// Note: log in first -- see StitchAuth
+// Get the Atlas client.
+RemoteMongoClient mongoClient = appClient.getServiceClient(RemoteMongoClient.factory, "mongodb-atlas");
+RemoteMongoDatabase db = mongoClient.getDatabase("video");
+RemoteMongoCollection<Document> movieDetails = db.getCollection("movieDetails");
+
+// Find 20 documents
+movieDetails.find()
+        .projection(new Document().append("title", 1).append("year", 1))
+        .limit(20)
+        .forEach(document -> {
+    // Print documents to the log.
+    Log.i(TAG, "Got document: " + document.toString());
+});

contrib/docs-examples/com/mongodb/stitch/android/services/mongodb/remote/RemoteMongoCollection/count-Bson-RemoteCountOptions.java

@@ -0,0 +1,18 @@
+// Get the Atlas client.
+RemoteMongoClient mongoClient = appClient.getServiceClient(RemoteMongoClient.factory, "mongodb-atlas");
+RemoteMongoDatabase db = mongoClient.getDatabase("video");
+RemoteMongoCollection<Document> movieDetails = db.getCollection("movieDetails");
+
+// Count all documents where title matches a regex up to a limit
+movieDetails.count(
+        new Document().append("title", new BsonRegularExpression("^A")),
+        new RemoteCountOptions().limit(25)).addOnCompleteListener(new OnCompleteListener<Long>() {
+    @Override
+    public void onComplete(@android.support.annotation.NonNull Task<Long> task) {
+        if (!task.isSuccessful()) {
+            Log.e(TAG, "Count failed", task.getException());
+            return;
+        }
+        Log.i(TAG, "Count is " + task.getResult());
+    }
+});

contrib/docs-examples/com/mongodb/stitch/android/services/mongodb/remote/RemoteMongoCollection/count-Bson.java

@@ -0,0 +1,16 @@
+// Get the Atlas client.
+RemoteMongoClient mongoClient = appClient.getServiceClient(RemoteMongoClient.factory, "mongodb-atlas");
+RemoteMongoDatabase db = mongoClient.getDatabase("video");
+RemoteMongoCollection<Document> movieDetails = db.getCollection("movieDetails");
+
+// Count all documents where title matches a regex
+movieDetails.count(new Document().append("title", new BsonRegularExpression("Star Wars"))).addOnCompleteListener(new OnCompleteListener<Long>() {
+    @Override
+    public void onComplete(@android.support.annotation.NonNull Task<Long> task) {
+        if (!task.isSuccessful()) {
+            Log.e(TAG, "Count failed", task.getException());
+            return;
+        }
+        Log.i(TAG, "Count is " + task.getResult());
+    }
+});

contrib/docs-examples/com/mongodb/stitch/android/services/mongodb/remote/RemoteMongoCollection/count.java

@@ -0,0 +1,16 @@
+// Get the Atlas client.
+RemoteMongoClient mongoClient = appClient.getServiceClient(RemoteMongoClient.factory, "mongodb-atlas");
+RemoteMongoDatabase db = mongoClient.getDatabase("video");
+RemoteMongoCollection<Document> movieDetails = db.getCollection("movieDetails");
+
+// Count all documents
+movieDetails.count().addOnCompleteListener(new OnCompleteListener<Long>() {
+    @Override
+    public void onComplete(@android.support.annotation.NonNull Task<Long> task) {
+        if (!task.isSuccessful()) {
+            Log.e(TAG, "Count failed", task.getException());
+            return;
+        }
+        Log.i(TAG, "Count is " + task.getResult());
+    }
+});

contrib/docs-examples/com/mongodb/stitch/android/services/mongodb/remote/RemoteMongoCollection/find-Bson.java

@@ -0,0 +1,11 @@
+// Get the Atlas client.
+RemoteMongoClient mongoClient = appClient.getServiceClient(RemoteMongoClient.factory, "mongodb-atlas");
+RemoteMongoDatabase db = mongoClient.getDatabase("video");
+RemoteMongoCollection<Document> movieDetails = db.getCollection("movieDetails");
+
+// Find up to 20 documents that match the title regex
+movieDetails.find(new Document().append("title", new BsonRegularExpression("Star Wars")))
+        .limit(20)
+        .forEach(document -> {
+    Log.i(TAG, "Found document: " + document.toString());
+});

contrib/docs-examples/com/mongodb/stitch/android/services/mongodb/remote/RemoteMongoCollection/find.java

@@ -0,0 +1,9 @@
+// Get the Atlas client.
+RemoteMongoClient mongoClient = appClient.getServiceClient(RemoteMongoClient.factory, "mongodb-atlas");
+RemoteMongoDatabase db = mongoClient.getDatabase("video");
+RemoteMongoCollection<Document> movieDetails = db.getCollection("movieDetails");
+
+// Find 20 documents
+movieDetails.find().limit(20).forEach(document -> {
+    Log.i(TAG, "Found document: " + document.toString());
+});

contrib/docs-examples/com/mongodb/stitch/android/services/mongodb/remote/RemoteMongoDatabase.java

@@ -0,0 +1,8 @@
+// Find 20 documents in a collection
+// Note: log in first -- see StitchAuth
+RemoteMongoClient mongoClient = appClient.getServiceClient(RemoteMongoClient.factory, "mongodb-atlas");
+RemoteMongoDatabase db = mongoClient.getDatabase("video");
+RemoteMongoCollection<Document> movieDetails = db.getCollection("movieDetails");
+movieDetails.find().limit(20).forEach(document -> {
+    Log.i(TAG, "Got document: " + document.toString());
+});