MongoDB Reactive Streams Driver Quick Start

The following code snippets come from the QuickTour.java example code that can be found with the reactive streams driver source on github.

Prerequisites

• A running MongoDB on localhost using the default port for MongoDB 27017

• MongoDB Reactive Streams Driver. See Installation for instructions on how to install the MongoDB driver.

• The following import statements:

New MongoClient API (since 3.7):

import com.mongodb.bulk.BulkWriteResult;
import com.mongodb.client.model.BulkWriteOptions;
import com.mongodb.client.model.DeleteOneModel;
import com.mongodb.client.model.InsertOneModel;
import com.mongodb.client.model.ReplaceOneModel;
import com.mongodb.client.model.UpdateOneModel;
import com.mongodb.client.model.WriteModel;
import com.mongodb.client.result.InsertOneResult;
import com.mongodb.client.result.InsertManyResult;
import com.mongodb.client.result.DeleteResult;
import com.mongodb.client.result.UpdateResult;

import com.mongodb.reactivestreams.client.MongoClient;
import com.mongodb.reactivestreams.client.MongoClients;
import com.mongodb.reactivestreams.client.MongoCollection;
import com.mongodb.reactivestreams.client.MongoDatabase;
import com.mongodb.reactivestreams.client.Success;

import org.bson.Document;

import java.util.ArrayList;
import java.util.List;

import static com.mongodb.client.model.Accumulators.*;
import static com.mongodb.client.model.Aggregates.*;
import static com.mongodb.client.model.Filters.*;
import static com.mongodb.client.model.Projections.*;
import static com.mongodb.client.model.Sorts.*;
import static com.mongodb.client.model.Updates.*;

import static java.util.Arrays.asList;
import static java.util.Collections.singletonList;

Make a Connection

Use MongoClients.create() to make a connection to a running MongoDB instance.

The MongoClient instance represents a pool of connections to the database; you will only need one instance of class MongoClient even with concurrent operations threads.

Connect to a Single MongoDB instance

The following example shows several ways to connect to a single MongoDB server.

To connect to a single MongoDB instance:

• You can instantiate a MongoClient object without any parameters to connect to a MongoDB instance running on localhost on port 27017:

MongoClient mongoClient = MongoClients.create();

• You can explicitly specify the hostname to connect to a MongoDB instance running on the specified host on port 27017:

MongoClient mongoClient = MongoClients.create(
        MongoClientSettings.builder()
                .applyToClusterSettings(builder ->
                        builder.hosts(Arrays.asList(new ServerAddress("hostOne"))))
                .build());

• You can explicitly specify the hostname and the port:

MongoClient mongoClient = MongoClients.create(
        MongoClientSettings.builder()
                .applyToClusterSettings(builder ->
                        builder.hosts(Arrays.asList(new ServerAddress("hostOne", 27018))))
                .build());

• You can specify the ConnectionString:

MongoClient mongoClient = MongoClients.create("mongodb://hostOne:27017");

Access a Database

Once you have a MongoClient instance connected to a MongoDB deployment, use the MongoClient.getDatabase() method to access a database.

Specify the name of the database to the getDatabase() method. If a database does not exist, MongoDB creates the database when you first store data for that database.

The following example accesses the mydb database:

 MongoDatabase database = mongoClient.getDatabase("mydb");

MongoDatabase instances are immutable.

Access a Collection

Once you have a MongoDatabase instance, use its getCollection() method to access a collection.

Specify the name of the collection to the getCollection() method. If a collection does not exist, MongoDB creates the collection when you first store data for that collection.

For example, using the database instance, the following statement accesses the collection named test in the mydb database:

MongoCollection<Document> collection = database.getCollection("test");

MongoCollection instances are immutable.

Create a Document

To create the document using the Java driver, use the Document class.

For example, consider the following JSON document:

  {
   "name" : "MongoDB",
   "type" : "database",
   "count" : 1,
   "versions": [ "v3.2", "v3.0", "v2.6" ],
   "info" : { x : 203, y : 102 }
  }

To create the document using the Java driver, instantiate a Document object with a field and value, and use its append() method to include additional fields and values to the document object. The value can be another Document object to specify an embedded document:

 Document doc = new Document("name", "MongoDB")
                .append("type", "database")
                .append("count", 1)
                .append("versions", Arrays.asList("v3.2", "v3.0", "v2.6"))
                .append("info", new Document("x", 203).append("y", 102));

Insert a Document

Once you have the MongoCollection object, you can insert documents into the collection.

Insert One Document

To insert a single document into the collection, you can use the collection’s insertOne() method.

collection.insertOne(doc).subscribe(new OperationSubscriber<InsertOneResult>());

Publisher<InsertOneResult> publisher = collection.insertOne(doc);

publisher.subscribe(new Subscriber<InsertOneResult>() {
    @Override
    public void onSubscribe(final Subscription s) {
        s.request(1);  // <--- Data requested and the insertion will now occur
    }

    @Override
    public void onNext(final InsertOneResult result) {
        System.out.println("Inserted: " + result);
    }

    @Override
    public void onError(final Throwable t) {
        System.out.println("Failed");
    }

    @Override
    public void onComplete() {
        System.out.println("Completed");
    }
});

Insert Multiple Documents

To add multiple documents, you can use the collection’s insertMany() method which takes a list of documents to insert.

The following example will add multiple documents of the form:

{ "i" : value }

Create the documents in a loop and add to the documents list:

List<Document> documents = new ArrayList<Document>();
for (int i = 0; i < 100; i++) {
    documents.add(new Document("i", i));
}

To insert these documents to the collection, pass the list of documents to the insertMany() method.

collection.insertMany(documents).subscribe(new ObservableSubscriber<InsertManyResult>());

Here we block on the Publisher to finish so that when we call the next operation we know the data has been inserted into the database!

Count Documents in A Collection

To count the number of documents in a collection, you can use the collection’s countDocuments() method. The following code should print 101 (the 100 inserted via insertMany plus the 1 inserted via the insertOne).

collection.count()
          .subscribe(new PrintSubscriber<Long>("total # of documents after inserting "
                                              + " 100 small ones (should be 101): %s"));

Query the Collection

To query the collection, you can use the collection’s find() method. You can call the method without any arguments to query all documents in a collection or pass a filter to query for documents that match the filter criteria.

Find the First Document in a Collection

To return the first document in the collection, use the find() method without any parameters and chain to find() method the first() method.

The following example prints the first document found in the collection.

collection.find().first().subscribe(new PrintDocumentSubscriber());

The example should print the following document:

{ "_id" : { "$oid" : "551582c558c7b4fbacf16735" },
  "name" : "MongoDB",
  "type" : "database",
  "count" : 1,
  "info" : { "x" : 203, "y" : 102 } }

Find All Documents in a Collection

To retrieve all the documents in the collection, we will use the find() method. The find() method returns a FindPublisher instance that provides a fluent interface for chaining or controlling find operations. The following code retrieves all documents in the collection and prints them out (101 documents):

collection.find().subscribe(new PrintDocumentSubscriber());

Specify a Query Filter

To query for documents that match certain conditions, pass a filter object to the find() method. To facilitate creating filter objects, the Java driver provides the Filters helper.

Get A Single Document That Matches a Filter

For example, to find the first document where the field i has the value 71, pass an eq filter object to specify the equality condition:

collection.find(eq("i", 71)).first().subscribe(new PrintDocumentSubscriber());

The example prints one document:

{ "_id" : { "$oid" : "5515836e58c7b4fbc756320b" }, "i" : 71 }

Get All Documents That Match a Filter

The following example returns and prints all documents where "i" > 50:

// now use a range query to get a larger subset
collection.find(gt("i", 50)).subscribe(new PrintDocumentSubscriber());

which should print the documents where i > 50.

To specify a filter for a range, such as 50 < i <= 100, you can use the and helper:

collection.find(and(gt("i", 50), lte("i", 100))).subscribe(new PrintDocumentSubscriber());

Update Documents

To update documents in a collection, you can use the collection’s updateOne and updateMany methods.

Pass to the methods:

• A filter object to determine the document or documents to update. To facilitate creating filter objects, the Java driver provides the Filters helper. To specify an empty filter (i.e. match all documents in a collection), use an empty Document object.

• An update document that specifies the modifications. For a list of the available operators, see update operators.

The update methods return an UpdateResult which provides information about the operation including the number of documents modified by the update.

Update a Single Document

To update at most a single document, use the updateOne

The following example updates the first document that meets the filter i equals 10 and sets the value of i to 110:

collection.updateOne(eq("i", 10), set("i", 110))
    .subscribe(new PrintSubscriber<UpdateResult>("Update Result: %s"));

Update Multiple Documents

To update all documents matching the filter, use the updateMany method.

The following example increments the value of i by 100 for all documents where =i is less than 100:

UpdateResult updateResult = collection.updateMany(lt("i", 100), inc("i", 100));
    .subscribe(new PrintSubscriber<UpdateResult>("Update Result: %s"));

Delete Documents

To delete documents from a collection, you can use the collection’s deleteOne and deleteMany methods.

Pass to the methods a filter object to determine the document or documents to delete. To facilitate creating filter objects, the Java driver provides the Filters helper. To specify an empty filter (i.e. match all documents in a collection), use an empty Document object.

The delete methods return a DeleteResult which provides information about the operation including the number of documents deleted.

Delete a Single Document That Match a Filter

To delete at most a single document that match the filter, use the deleteOne method:

The following example deletes at most one document that meets the filter i equals 110:

collection.deleteOne(eq("i", 110))
          .subscribe(new PrintSubscriber<DeleteResult>("Delete Result: %s"));

Delete All Documents That Match a Filter

To delete all documents matching the filter use the deleteMany method.

The following example deletes all documents where i is greater or equal to 100:

DeleteResult deleteResult = collection.deleteMany(gte("i", 100))
          .subscribe(new PrintSubscriber<DeleteResult>("Delete Result: %s"));

Create Indexes

To create an index on a field or fields, pass an index specification document to the createIndex() method. An index key specification document contains the fields to index and the index type for each field:

new Document(<field1>, <type1>).append(<field2>, <type2>) ...

• For an ascending index type, specify 1 for <type>.
• For a descending index type, specify -1 for <type>.

The following example creates an ascending index on the i field:

collection.createIndex(new Document("i", 1))
          .subscribe(new PrintSubscriber<String>("Create Index Result: %s"));

For a list of other index types, see Create Indexes

Additional Information

For additional tutorials about using MongoDB with Pojos, see the Pojos Quick Start.

For additional tutorials (such as to use the aggregation framework, specify write concern, etc.), see Java Driver Tutorials