Connecting to Amazon DocumentDB with a MongoDB Java driver

This section provides a step-by-step guide for connecting to Amazon DocumentDB using Java drivers. This will get you started with integrating DocumentDB into your Java applications.

Step 1: Set up your project

Step 2: Create the connection string

Amazon DocumentDB connection string is essential for establishing a connection between your application and your DocumentDB cluster. This string encapsulates crucial information such as the cluster endpoint, port, authentication details, and various connection options. To build a DocumentDB connection string, you typically start with the basic format:

"mongodb://username:password@cluster-endpoint:port/?[connection options]"

You'll need to replace "username" and "password" with your actual credentials. You can find your cluster's endpoint and port number in the AWS Management Console as well as through the AWS CLI. See Finding a cluster's endpoints to find the cluster endpoint for your cluster. The default port for DocumentDB is 27017.

Connection string examples

The different options available for the connection string are as follows:

TLS certificate

tls=true|false — This option enables or disables Transport Layer Security (TLS). By default, encryption in transit is enabled on Amazon DocumentDB cluster and therefore, unless TLS is disabled at the cluster level, the value for this option should be true.

When using TLS, the code needs to provide an SSL certificate when creating connection to a DocumentDB cluster. Download the certificate that is required to make the secure connection to the cluster: global-bundle.pem. There are two ways to use the global-bundle.pem file.

Reading from read replicas

replicaSet=rs0&readPreference=secondaryPreferred — Specifying these two options routes all the read requests to the read replicas, and write requests to the primary instance. Using replicaSet=rs0 in the connection string enables the MongoDB driver to maintain an automatically updated view of the cluster topology, allowing applications to maintain visibility of current node configurations as instances are added or removed. Not providing these options or specifying readPreference=primary sends all the reads and writes to primary instance. For more options for readPreference, see Read preference options.

Write concern and journaling

Write concern determines the level of acknowledgment requested from the database for write operations. MongoDB drivers provide an option to tune write concern and journal files. Amazon DocumentDB doesn’t expect you to set write concern and journal, and ignores the values sent for w and j (writeConcern and journal). DocumentDB always writes data with writeConcern: majority and journal: true so the writes are durably recorded on a majority of nodes before sending an acknowledgement to the client.

RetryWrites

retryWrites=false — DocumentDB does not support retryable writes and therefore this attribute should always be set to false.

IAM authentication

authSource=%24external and authMechanism=MONGODB-AWS — These two parameters are used to authenticate using AWS Identity and Access Management. IAM authentication is currently only available in instance-based cluster version 5.0. For more information, see Authentication using IAM identity.

Connection pool

These options are available for connection pooling:

Connection timeout parameters

Timeout is a mechanism to limit the amount of time an operation or connection attempt can take before it is considered failed. The following timeout parameters are available for preventing indefinite waits and managing resource allocation:

Step 3: Write the connection code

The following code example shows how to make a TLS connection to Amazon DocumentDB:

public static MongoClient makeDbConnection(String dbName, String DbUserName, String DbPassword,
    String DbClusterEndPoint, String keyStorePass) throws Exception {
    MongoClient connectedClient;
    String connectionOptions = "?replicaSet=rs0&readPreference=secondaryPreferred&retryWrites=false";
    String connectionUrl = "mongodb://" + DbUserName + ":" + DbPassword + "@" + DbClusterEndPoint + ":27017/" +
        dbName + connectionOptions;

    try {
        KeyStore trustStore = KeyStore.getInstance(KeyStore.getDefaultType());
        try (FileInputStream fis = new FileInputStream("src/main/resources/certs/truststore.jks")) {
            trustStore.load(fis, keyStorePass.toCharArray());
            TrustManagerFactory tmf = TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm());
            tmf.init(trustStore);

            SSLContext sslContext = SSLContext.getInstance("TLSv1.2");
            sslContext.init(null, tmf.getTrustManagers(), new SecureRandom());
            ConnectionString connectionString = new ConnectionString(connectionUrl);
            MongoClientSettings settings = MongoClientSettings.builder()
                .applyConnectionString(connectionString)
                .applyToSslSettings(builder - > {
                    builder.enabled(true);
                    builder.context(sslContext);
                })
                .build();
            connectedClient = MongoClients.create(settings);
        }
        return connectedClient;
    } catch (MongoException e5) {
        throw new RuntimeException(e5);
    } catch (Exception e) {
        throw new RuntimeException(e);
    }
}

Step 4: Handle connection exceptions

When working with DocumentDB in Java applications, handling connection exceptions is crucial for maintaining robust and reliable database operations. Properly managing, these exceptions not only help in diagnosing issues quickly, but also ensure that your application can gracefully handle temporary network disruptions or server unavailability, leading to improved stability and user experience. Some of the critical exceptions related to establishing connection include:

Step 5: Running the code

The following code sample creates an Amazon DocumentDB connection and prints all the databases:

public static void TestConnection() {
    try (MongoClient mongoClient = makeDbConnection(DATABASE_NAME, DB_USER_NAME, DB_PASSWORD, DB_CLUSTER_ENDPOINT, KEYSTORE_PASSWORD)) {
        List < String > databases = mongoClient.listDatabaseNames().into(new ArrayList < > ());
        System.out.println("Databases: " + databases);
    } catch (MongoException e) {
        System.err.println("MongoDB error: " + e.getMessage());
        throw new RuntimeException(e);
    }
}

Connection best practices

The following are best practices to consider when connecting to Amazon DocumentDB with a MongoDB Java driver: