Quick Start

Install the Java Development Kit (JDK)

Make sure that your system has JDK 8 or later installed. For more information on how to check your version of Java and install the JDK, see the Oracle Overview of JDK Installation documentation.

Create the Project

This guide shows you how to add the MongoDB Java driver dependencies using Maven or Gradle. We recommend that you use an integrated development environment (IDE) such as Intellij IDEA or Eclipse IDE make it more convenient to configure Maven or Gradle to build and run your project.

If you are not using an IDE, see Building Maven or Creating New Gradle Builds for more information on how to set up your project.

Add MongoDB as a Dependency

If you are using Maven, add the following to your pom.xml dependencies list:

<dependencies>
    <dependency>
        <groupId>org.mongodb</groupId>
        <artifactId>mongodb-driver-sync</artifactId>
        <version>4.5.1</version>
    </dependency>
</dependencies>

If you are using Gradle, add the following to your build.gradle dependencies list:

dependencies {
  implementation 'org.mongodb:mongodb-driver-sync:4.5.1'
}

Once you configure your dependencies, ensure they are available to your project which may require running your dependency manager and refreshing the project in your IDE.

Set up a Free Tier Cluster in Atlas

After setting up your Java project dependencies, create a MongoDB cluster where you can store and manage your data. Complete the Get Started with Atlas guide to set up a new Atlas account, create and launch a free tier MongoDB cluster, load datasets, and interact with the data.

After completing the steps in the Atlas guide, you should have a new MongoDB cluster deployed in Atlas, a new database user, and sample datasets loaded into your cluster.

Connect to your Cluster

In this step, we create and run an application that uses the MongoDB Java driver to connect to your MongoDB cluster and run a query on the sample data.

We pass instructions to the driver on how to connect to your MongoDB cluster in a string called the connection string. This string includes information on the hostname or IP address and port of your cluster, authentication mechanism, user credentials when applicable, and other connection options.

If you are connecting to an instance or cluster that is not hosted by Atlas, see Other Ways to Connect to MongoDB for instructions on how to format your connection string.

To retrieve your connection string for the cluster and user you created in the previous step, log into your Atlas account and navigate to the Clusters section and click Connect for the cluster that you want to connect to as shown below.

Proceed to the Connect Your Application step and select the Java driver. Select "4.3 or Later" for the version. Click the Copy icon to copy the connection string to your clipboard as shown below.

Save your Atlas connection string in a safe location that you can access for the next step.

Query Your MongoDB Cluster from Your Application

Next, create a file to contain your application called QuickStart.java in the base package directory of your project. Use the following sample code to run a query on your sample dataset in MongoDB Atlas, replacing the value of the uri variable with your MongoDB Atlas connection string.

import static com.mongodb.client.model.Filters.eq;
import org.bson.Document;
import com.mongodb.client.MongoClient;
import com.mongodb.client.MongoClients;
import com.mongodb.client.MongoCollection;
import com.mongodb.client.MongoDatabase;
public class QuickStart {
    public static void main( String[] args ) {
        // Replace the placeholder with your MongoDB deployment's connection string
        String uri = "<connection string uri>";
        try (MongoClient mongoClient = MongoClients.create(uri)) {
            MongoDatabase database = mongoClient.getDatabase("sample_mflix");
            MongoCollection<Document> collection = database.getCollection("movies");
            Document doc = collection.find(eq("title", "Back to the Future")).first();
            if (doc != null) {
                System.out.println(doc.toJson());
            } else {
                System.out.println("No matching documents found.");
            }
        }
    }
}

When you run the QuickStart class, it should output the details of the movie from the sample dataset which will look something like this:

{
  _id: ...,
  plot: 'A young man is accidentally sent 30 years into the past...',
  genres: [ 'Adventure', 'Comedy', 'Sci-Fi' ],
  ...
  title: 'Back to the Future',
  ...
}

If you receive no output or an error, check whether you included the proper connection string in your Java class, and whether you loaded the sample dataset into your MongoDB Atlas cluster.

javax.net.ssl.SSLHandshakeException: extension (5) should not be presented in certificate_request

After completing this step, you should have a working application that uses the Java driver to connect to your MongoDB cluster, run a query on the sample data, and print out the result.

Working with POJOs (Optional)

In the previous section, you ran a query on a sample collection to retrieve data in the map-like class Document. In this section, you can learn to use your own Plain Old Java Object (POJO) to store and retrieve data from MongoDB.

Create a file called Movie.java in the base package directory of your project and add the following code for a class that includes the following fields, setters, and getters:

public class Movie {
    String plot;
    List<String> genres;
    String title;
    public String getPlot() {
        return plot;
    }
    public void setPlot(String plot) {
        this.plot = plot;
    }
    public List<String> getGenres() {
        return genres;
    }
    public void setGenres(List<String> genres) {
        this.genres = genres;
    }
    public String getTitle() {
        return title;
    }
    public void setTitle(String title) {
        this.title = title;
    }
    @Override
    public String toString() {
        return "Movie [\n  plot=" + plot + ",\n  genres=" + genres + ",\n  title=" + title + "\n]";
    }
}

Create a new file QuickStartPojoExample.java in the same package directory as your Movie file in your project. Use the following sample code to run a query on your sample dataset in MongoDB Atlas, replacing the value of the uri variable with your MongoDB Atlas connection string. Ensure you replace the "<password>" section of the connection string with the password you created for your user that has atlasAdmin permissions:

import static com.mongodb.MongoClientSettings.getDefaultCodecRegistry;
import static com.mongodb.client.model.Filters.eq;
import static org.bson.codecs.configuration.CodecRegistries.fromProviders;
import static org.bson.codecs.configuration.CodecRegistries.fromRegistries;
import org.bson.codecs.configuration.CodecProvider;
import org.bson.codecs.configuration.CodecRegistry;
import org.bson.codecs.pojo.PojoCodecProvider;
import com.mongodb.client.MongoClient;
import com.mongodb.client.MongoClients;
import com.mongodb.client.MongoCollection;
import com.mongodb.client.MongoDatabase;
public class QuickStartPojoExample {
    public static void main(String[] args) {
        CodecProvider pojoCodecProvider = PojoCodecProvider.builder().automatic(true).build();
        CodecRegistry pojoCodecRegistry = fromRegistries(getDefaultCodecRegistry(), fromProviders(pojoCodecProvider));
        // Replace the uri string with your MongoDB deployment's connection string
        String uri = "<connection string uri>";
        try (MongoClient mongoClient = MongoClients.create(uri)) {
            MongoDatabase database = mongoClient.getDatabase("sample_mflix").withCodecRegistry(pojoCodecRegistry);
            MongoCollection<Movie> collection = database.getCollection("movies", Movie.class);
            Movie movie = collection.find(eq("title", "Back to the Future")).first();
            System.out.println(movie);
        }
    }
}

When you run the QuickStartPojoExample class, it should output the details of the movie from the sample dataset which should look something like this:

Movie [
  plot=A young man is accidentally sent 30 years into the past...,
  genres=[Adventure, Comedy, Sci-Fi],
  title=Back to the Future
]

If you receive no output or an error, check whether you included the proper connection string in your Java class, and whether you loaded the sample dataset into your MongoDB Atlas cluster.

See the following links for more information on using POJOs to store and retrieve data:

• Guide on using POJOs to store and retrieve data

• Guide on custom serialization of POJOs