From b967d5f9ffd74d6491a1d88613bdcccaa5d1168e Mon Sep 17 00:00:00 2001 From: Chris Bush Date: Fri, 8 Mar 2019 17:01:17 -0500 Subject: [PATCH] DOCSP-4381 Revamp crud flow, add examples - Adds several example snippets to the crud-related methods and classes. These were tested locally. - Updates the text of the same classes and methods and includes more links. --- .../mongodb/remote/RemoteMongoClient.java | 14 +++++++++- .../mongodb/remote/RemoteMongoCollection.java | 28 ++++++++++++++++--- .../mongodb/remote/RemoteMongoDatabase.java | 12 ++++++-- .../stitch/android/core/StitchAppClient.java | 28 +++++++++++++++++++ .../mongodb/remote/RemoteMongoClient.java | 8 ++++++ .../mongodb/remote/RemoteMongoCollection.java | 14 ++++++++++ .../count-Bson-RemoteCountOptions.java | 18 ++++++++++++ .../RemoteMongoCollection/count-Bson.java | 16 +++++++++++ .../remote/RemoteMongoCollection/count.java | 16 +++++++++++ .../RemoteMongoCollection/find-Bson.java | 11 ++++++++ .../remote/RemoteMongoCollection/find.java | 9 ++++++ .../mongodb/remote/RemoteMongoDatabase.java | 8 ++++++ 12 files changed, 175 insertions(+), 7 deletions(-) create mode 100644 contrib/docs-examples/com/mongodb/stitch/android/core/StitchAppClient.java create mode 100644 contrib/docs-examples/com/mongodb/stitch/android/services/mongodb/remote/RemoteMongoClient.java create mode 100644 contrib/docs-examples/com/mongodb/stitch/android/services/mongodb/remote/RemoteMongoCollection.java create mode 100644 contrib/docs-examples/com/mongodb/stitch/android/services/mongodb/remote/RemoteMongoCollection/count-Bson-RemoteCountOptions.java create mode 100644 contrib/docs-examples/com/mongodb/stitch/android/services/mongodb/remote/RemoteMongoCollection/count-Bson.java create mode 100644 contrib/docs-examples/com/mongodb/stitch/android/services/mongodb/remote/RemoteMongoCollection/count.java create mode 100644 contrib/docs-examples/com/mongodb/stitch/android/services/mongodb/remote/RemoteMongoCollection/find-Bson.java create mode 100644 contrib/docs-examples/com/mongodb/stitch/android/services/mongodb/remote/RemoteMongoCollection/find.java create mode 100644 contrib/docs-examples/com/mongodb/stitch/android/services/mongodb/remote/RemoteMongoDatabase.java diff --git a/android/services/mongodb-remote/src/main/java/com/mongodb/stitch/android/services/mongodb/remote/RemoteMongoClient.java b/android/services/mongodb-remote/src/main/java/com/mongodb/stitch/android/services/mongodb/remote/RemoteMongoClient.java index 9e0f05aab..8331ee2c6 100644 --- a/android/services/mongodb-remote/src/main/java/com/mongodb/stitch/android/services/mongodb/remote/RemoteMongoClient.java +++ b/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. + *

+ * An instance can be retrieved using {@link com.mongodb.stitch.android.core.StitchAppClient#getServiceClient} + * with this class's {@link factory}. + *

+ * Before using the database, you will have to log in using {@link com.mongodb.stitch.android.core.auth.StitchAuth}. + *

+ * Once logged in, you can access the database with {@link getDatabase}. + *

+ * @see com.mongodb.stitch.android.core.StitchAppClient + * @see com.mongodb.stitch.android.core.auth.StitchAuth + * @see RemoteMongoDatabase */ public interface RemoteMongoClient { diff --git a/android/services/mongodb-remote/src/main/java/com/mongodb/stitch/android/services/mongodb/remote/RemoteMongoCollection.java b/android/services/mongodb-remote/src/main/java/com/mongodb/stitch/android/services/mongodb/remote/RemoteMongoCollection.java index 3a1ea05f1..372e7501a 100644 --- a/android/services/mongodb-remote/src/main/java/com/mongodb/stitch/android/services/mongodb/remote/RemoteMongoCollection.java +++ b/android/services/mongodb-remote/src/main/java/com/mongodb/stitch/android/services/mongodb/remote/RemoteMongoCollection.java @@ -35,7 +35,23 @@ import org.bson.types.ObjectId; /** - * The RemoteMongoCollection interface. + * The RemoteMongoCollection interface provides read and write access to documents. + *

+ * Use {@link RemoteMongoDatabase#getCollection} to get a collection instance. + *

+ * 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. + *

+ * Create, read, update and delete (CRUD) functionality is available depending + * on the privileges of the active logged-in user. You can set up + * Roles + * 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. + *

+ * + * @see RemoteMongoDatabase + * @see MongoDB Atlas Overview with Stitch * * @param The type that this collection will encode documents from and decode documents * to. @@ -43,7 +59,7 @@ public interface RemoteMongoCollection { /** - * Gets the namespace of this collection. + * Gets the namespace of this collection, i.e. the database and collection names together. * * @return the namespace */ @@ -51,6 +67,10 @@ public interface RemoteMongoCollection { /** * Get the class of documents stored in this collection. + *

+ * If you used the simple {@link RemoteMongoDatabase#getCollection(String)} to get this collection, + * this is {@link org.bson.Document}. + *

* * @return the class */ @@ -125,7 +145,7 @@ RemoteMongoCollection withDocumentClass( RemoteFindIterable find(final Class 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 @@ -133,7 +153,7 @@ RemoteMongoCollection withDocumentClass( RemoteFindIterable 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 diff --git a/android/services/mongodb-remote/src/main/java/com/mongodb/stitch/android/services/mongodb/remote/RemoteMongoDatabase.java b/android/services/mongodb-remote/src/main/java/com/mongodb/stitch/android/services/mongodb/remote/RemoteMongoDatabase.java index 095d76d9b..5b477a240 100644 --- a/android/services/mongodb-remote/src/main/java/com/mongodb/stitch/android/services/mongodb/remote/RemoteMongoDatabase.java +++ b/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. + *

+ * In order to obtain an instance of the database, use {@link RemoteMongoClient#getDatabase}. + *

+ * Once you have a database, you can use {@link getCollection} to get a collection + * to start reading and writing documents. + *

+ * @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 diff --git a/contrib/docs-examples/com/mongodb/stitch/android/core/StitchAppClient.java b/contrib/docs-examples/com/mongodb/stitch/android/core/StitchAppClient.java new file mode 100644 index 000000000..576404fc6 --- /dev/null +++ b/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() { + @Override + public void onComplete(@NonNull Task 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 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()); + }); + } +}); diff --git a/contrib/docs-examples/com/mongodb/stitch/android/services/mongodb/remote/RemoteMongoClient.java b/contrib/docs-examples/com/mongodb/stitch/android/services/mongodb/remote/RemoteMongoClient.java new file mode 100644 index 000000000..82fd6a688 --- /dev/null +++ b/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 movieDetails = db.getCollection("movieDetails"); +movieDetails.find().limit(20).forEach(document -> { + Log.i(TAG, "Got document: " + document.toString()); +}); diff --git a/contrib/docs-examples/com/mongodb/stitch/android/services/mongodb/remote/RemoteMongoCollection.java b/contrib/docs-examples/com/mongodb/stitch/android/services/mongodb/remote/RemoteMongoCollection.java new file mode 100644 index 000000000..77dbc3b87 --- /dev/null +++ b/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 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()); +}); diff --git a/contrib/docs-examples/com/mongodb/stitch/android/services/mongodb/remote/RemoteMongoCollection/count-Bson-RemoteCountOptions.java b/contrib/docs-examples/com/mongodb/stitch/android/services/mongodb/remote/RemoteMongoCollection/count-Bson-RemoteCountOptions.java new file mode 100644 index 000000000..525852a7b --- /dev/null +++ b/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 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() { + @Override + public void onComplete(@android.support.annotation.NonNull Task task) { + if (!task.isSuccessful()) { + Log.e(TAG, "Count failed", task.getException()); + return; + } + Log.i(TAG, "Count is " + task.getResult()); + } +}); diff --git a/contrib/docs-examples/com/mongodb/stitch/android/services/mongodb/remote/RemoteMongoCollection/count-Bson.java b/contrib/docs-examples/com/mongodb/stitch/android/services/mongodb/remote/RemoteMongoCollection/count-Bson.java new file mode 100644 index 000000000..1d31c9444 --- /dev/null +++ b/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 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() { + @Override + public void onComplete(@android.support.annotation.NonNull Task task) { + if (!task.isSuccessful()) { + Log.e(TAG, "Count failed", task.getException()); + return; + } + Log.i(TAG, "Count is " + task.getResult()); + } +}); diff --git a/contrib/docs-examples/com/mongodb/stitch/android/services/mongodb/remote/RemoteMongoCollection/count.java b/contrib/docs-examples/com/mongodb/stitch/android/services/mongodb/remote/RemoteMongoCollection/count.java new file mode 100644 index 000000000..ce90b15d0 --- /dev/null +++ b/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 movieDetails = db.getCollection("movieDetails"); + +// Count all documents +movieDetails.count().addOnCompleteListener(new OnCompleteListener() { + @Override + public void onComplete(@android.support.annotation.NonNull Task task) { + if (!task.isSuccessful()) { + Log.e(TAG, "Count failed", task.getException()); + return; + } + Log.i(TAG, "Count is " + task.getResult()); + } +}); diff --git a/contrib/docs-examples/com/mongodb/stitch/android/services/mongodb/remote/RemoteMongoCollection/find-Bson.java b/contrib/docs-examples/com/mongodb/stitch/android/services/mongodb/remote/RemoteMongoCollection/find-Bson.java new file mode 100644 index 000000000..075477803 --- /dev/null +++ b/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 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()); +}); diff --git a/contrib/docs-examples/com/mongodb/stitch/android/services/mongodb/remote/RemoteMongoCollection/find.java b/contrib/docs-examples/com/mongodb/stitch/android/services/mongodb/remote/RemoteMongoCollection/find.java new file mode 100644 index 000000000..44216b387 --- /dev/null +++ b/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 movieDetails = db.getCollection("movieDetails"); + +// Find 20 documents +movieDetails.find().limit(20).forEach(document -> { + Log.i(TAG, "Found document: " + document.toString()); +}); diff --git a/contrib/docs-examples/com/mongodb/stitch/android/services/mongodb/remote/RemoteMongoDatabase.java b/contrib/docs-examples/com/mongodb/stitch/android/services/mongodb/remote/RemoteMongoDatabase.java new file mode 100644 index 000000000..82fd6a688 --- /dev/null +++ b/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 movieDetails = db.getCollection("movieDetails"); +movieDetails.find().limit(20).forEach(document -> { + Log.i(TAG, "Got document: " + document.toString()); +});