MongoDB Async Driver Quick Start

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

SingleResultCallback

The MongoDB Async driver provides an asynchronous API that can leverage either Netty or Java 7’s AsynchronousSocketChannel for fast and non-blocking I/O.

The MongoDB Asynchronous Driver API mirrors the new Synchronous MongoDB Driver API, but asynchronous methods that make network I/O operations take a SingleResultCallback<T> and return immediately. The SingleResultCallback<T> interface requires the implementation of a single method onResult(T result, Throwable t) which is called upon the completion of the operation. Upon successful operation, the result parameter contains the result of the operation. If the operation failed for any reason, then the t contains the reason for the failure.

To use a callback more than once, you can either create a class that implements the callback or assign the callback to a variable.

Prerequisites

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

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

• The following import statements:

import com.mongodb.Block;
import com.mongodb.ServerAddress;
import com.mongodb.async.SingleResultCallback;
import com.mongodb.async.client.*;
import com.mongodb.client.result.DeleteResult;
import com.mongodb.client.result.UpdateResult;
import com.mongodb.connection.ClusterSettings;
import com.mongodb.ConnectionString;
import org.bson.Document;

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

import static com.mongodb.client.model.Filters.*;
import static com.mongodb.client.model.Updates.inc;
import static com.mongodb.client.model.Updates.set;
import static java.util.Arrays.asList;

• The following callback code which the examples in the tutorials will use:

SingleResultCallback<Document> callbackPrintDocuments = new SingleResultCallback<Document>() {
   @Override
   public void onResult(final Document document, final Throwable t) {
       System.out.println(document.toJson());
   }
};

SingleResultCallback<Void> callbackWhenFinished = new SingleResultCallback<Void>() {
    @Override
    public void onResult(final Void result, final Throwable t) {
        System.out.println("Operation Finished!");
    }
};

• The following Block code which the examples will use to print the results of the find operations:

Block<Document> printDocumentBlock = new Block<Document>() {
    @Override
    public void apply(final Document document) {
        System.out.println(document.toJson());
    }
};

Make a Connection

To make a connection to a running MongoDB instance, use MongoClients.create to create a new MongoClient instance. A MongoClient instance actually represents a pool of connections to the database; you will only need one instance of class MongoClient even with multiple concurrently executing asynchronous operations.

Connect to a Standalone MongoDB Instance

The following example shows various ways to connect to a standalone MongoDB instance running on the local machine.

To connect to a standalone MongoDB instance:

• You can call MongoClients.create() without any parameters to connect to a MongoDB instance running on localhost on port 27017:

MongoClient mongoClient = MongoClients.create();

• You can call MongoClients.create() with a string that specifies the connection string:

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

The connection string mostly follows RFC 3986, with the exception of the domain name. For MongoDB, it is possible to list multiple domain names separated by a comma. For more information on the connection string, see connection string.

• You can call MongoClients.create() with a ConnectionString object:

MongoClient mongoClient = MongoClients.create(new ConnectionString("mongodb://localhost"));

• You can call MongoClients.create() with a MongoClientSettings object:

ClusterSettings clusterSettings = ClusterSettings.builder()
                                  .hosts(asList(new ServerAddress("localhost"))).build();
MongoClientSettings settings = MongoClientSettings.builder()
                                  .clusterSettings(clusterSettings).build();
MongoClient mongoClient = MongoClients.create(settings);

Access a Database

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

Specify the name of the database to the getDatabase() method. The getDatabase() method does not require a callback since there is no network I/O required. 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");

Get 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");

Create a Document

To create the document using the Java async 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 async 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 the document into the collection, use the insertOne() method.

collection.insertOne(doc, new SingleResultCallback<Void>() {
    @Override
    public void onResult(final Void result, final Throwable t) {
        System.out.println("Inserted!");
    }
});

SingleResultCallback<T> is a functional interface and can be implemented as a lambda if using Java 8:

collection.insertOne(doc, (Void result, final Throwable t) -> System.out.println("Inserted!"));

Insert Multiple Documents

To add multiple documents, you can use the 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, new SingleResultCallback<Void>() {
    @Override
    public void onResult(final Void result, final Throwable t) {
        System.out.println("Documents inserted!");
    }
});

Count Documents in A Collection

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

collection.countDocuments(
  new SingleResultCallback<Long>() {
      @Override
      public void onResult(final Long count, final Throwable t) {
          System.out.println(count);
      }
  });

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.

The find() method returns a FindIterable() instance that provides a fluent interface for chaining other methods.

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.

If the collection is empty, the operation returns null.

The following example prints the first document found in the collection, using the printDocument callback declared earlier in the tutorial:

collection.find().first(callbackPrintDocuments);

The example will print the following document:

{ "_id" : { "$oid" : "579f5278b9c1d14ae2a31c27" }, "name" : "MongoDB", "type" : "database", "count" : 1, "versions" : ["v3.2", "v3.0", "v2.6"], "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 without any parameters.

You can chain the forEach() method to the find() method to iterate through the results and apply a Block to each document in the results. The forEach() method also takes a callback that is run once the iteration has finished.

The following code retrieves all documents in the collection and prints the returned documents (101 documents). The example uses the callbackWhenFinished and the printDocumentBlock defined earlier in the tutorial:

collection.find().forEach(printDocumentBlock, callbackWhenFinished);

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 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. The example uses the callbackPrintDocuments defined earlier in the tutorial:

collection.find(eq("i", 71)).first(callbackPrintDocuments);

Get All Documents That Match a Filter

The following example returns and prints all documents where "i" > 50. The example uses the printDocumentBlock code and callbackWhenFinished defined earlier in the tutorial:

collection.find(gt("i", 50)).forEach(printDocumentBlock, callbackWhenFinished);

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))).forEach(printDocumentBlock, callbackWhenFinished);

Updating 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, Java async 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.

• A callback.

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),
    new SingleResultCallback<UpdateResult>() {
        @Override
        public void onResult(final UpdateResult result, final Throwable t) {
            System.out.println(result.getModifiedCount());
        }
    });

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:

collection.updateMany(lt("i", 100), inc("i", 100),
    new SingleResultCallback<UpdateResult>() {
        @Override
        public void onResult(final UpdateResult result, final Throwable t) {
            System.out.println(result.getModifiedCount());
        }
    });

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, Java driver provides the Filters helper. To specify an empty filter (i.e. match all documents in a collection), use an empty Document object.

• A callback.

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), new SingleResultCallback<DeleteResult>() {
    @Override
    public void onResult(final DeleteResult result, final Throwable t) {
        System.out.println(result.getDeletedCount());
    }
});

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:

collection.deleteMany(gte("i", 100), new SingleResultCallback<DeleteResult>() {
    @Override
    public void onResult(final DeleteResult result, final Throwable t) {
        System.out.println(result.getDeletedCount());
    }
});

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 the Java Async Driver Tutorials.