Docs Menu
Docs Home
/ / /
Java Sync Driver
/ /

Document Data Format: POJOs

On this page

  • Overview
  • Example POJO
  • Configure the Driver for POJOs
  • Perform CRUD Operations
  • Summary

In this guide, you can learn how to store and retrieve data modeled by plain old Java objects, or POJOs. POJOs are often used for data encapsulation, which is the practice of separating business logic from data representation.


To learn more about POJOs, see the Plain old Java object Wikipedia article.

The example in this guide demonstrates how to perform the following tasks:

  • Configure the driver to serialize and deserialize POJOs

  • Perform CRUD operations that use data modeled by POJOs

The sections in this guide use the following sample POJO class, which describes the characteristics of flowers:

public class Flower {
private ObjectId id;
private String name;
private List<String> colors;
private Boolean isBlooming;
private Float height;
// public empty constructor needed for retrieving the POJO
public Flower() {
public Flower(String name, Boolean isBlooming, Float height, List<String> colors) { = name;
this.isBlooming = isBlooming;
this.height = height;
this.colors = colors;
public ObjectId getId() {
return id;
public void setId(ObjectId id) { = id;
public String getName() {
return name;
public void setName(String name) { = name;
public Boolean getIsBlooming() {
return isBlooming;
public void setIsBlooming(Boolean isBlooming) {
this.isBlooming = isBlooming;
public Float getHeight() {
return height;
public void setHeight(Float height) {
this.height = height;
public List<String> getColors() {
return colors;
public void setColors(List<String> colors) {
this.colors = colors;
public String toString() {
return "\nFlower {\n\tid: " + id + "\n\tname: " + name + "\n\tcolors: " + colors + "\n\tisBlooming: " + isBlooming + "\n\theight: " + height + "\n}";

When defining a POJO to store and retrieve data within MongoDB, use the following guidelines:

  • The POJO class cannot implement interfaces or extend classes from a framework.

  • Include all the fields for which you want to store and retrieve data, and make sure they are not marked as static or transient.

  • If you include public getter or setter methods by using the JavaBean naming conventions in your POJO, the driver calls them when serializing or deserializing data. If you omit the getter or setter methods for a public property field, the driver accesses or assigns them directly.

To configure the driver to use POJOs, you must specify the following components:

  • PojoCodecProvider instance that has codecs that define how to encode and decode the data between the POJO format and BSON. The provider also specifies which POJO classes or packages that the codecs apply to.

  • CodecRegistry instance that contains the codecs and other related information.

  • MongoDatabase or MongoCollection instance that is configured to use the CodecRegistry.

  • MongoCollection instance that is created with the POJO document class bound to the TDocument generic type.

Perform the following steps to meet the configuration requirements defined in the preceding section:

  1. Configure the PojoCodecProvider. In this example, we use the automatic(true) setting of the PojoCodecProvider.Builder to apply the codecs to any class and its properties.

    CodecProvider pojoCodecProvider = PojoCodecProvider.builder().automatic(true).build();


    Codec providers also contain other objects such as ClassModel and Convention instances that further define serialization behavior. For more information about codec providers and customization, see the guide on POJO Customization.

  2. Add the PojoCodecProvider instance to a CodecRegistry. The CodecRegistry allows you to specify one or more codec providers to encode the POJO data. In this example, we call the following methods:

    • fromRegistries() to combine multiple CodecRegistry instances into one instance

    • getDefaultCodecRegistry() to retrieve a CodecRegistry instance from a list of codec providers

    • fromProviders() to create a CodecRegistry instance from the PojoCodecProvider

    The following code shows how to instantiate the CodecRegistry:

    // Include the following static imports before your class definition
    import static com.mongodb.MongoClientSettings.getDefaultCodecRegistry;
    import static org.bson.codecs.configuration.CodecRegistries.fromProviders;
    import static org.bson.codecs.configuration.CodecRegistries.fromRegistries;
    CodecRegistry pojoCodecRegistry = fromRegistries(getDefaultCodecRegistry(), fromProviders(pojoCodecProvider));
  3. Configure the MongoDatabase or MongoCollection instance to use the codecs in the CodecRegistry. You can configure either a database or collection to specify the codecs.

    In this example, we set the CodecRegistry on a MongoDatabase called sample_pojos by using the withCodecRegistry() method:

    MongoClient mongoClient = MongoClients.create(uri);
    MongoDatabase database = mongoClient.getDatabase("sample_pojos").withCodecRegistry(pojoCodecRegistry);
  4. Pass your POJO class to your call to getCollection() as the document class parameter and specify it as the type argument of your MongoCollection instance, as shown in the following code:

    MongoCollection<Flower> collection = database.getCollection("flowers", Flower.class);

Once you have configured the MongoCollection instance to use the Flower POJO, you can perform CRUD operations on data modeled by the POJO.

This example demonstrates how to perform the following operations by using the Flower POJO:

  • Insert instances of Flower into the flowers collection

  • Update a document in the collection

  • Delete a document in the collection

  • Find and print all documents in the collection

// Insert three Flower instances
Flower roseFlower = new Flower("rose", false, 25.4f, Arrays.asList(new String[] {"red", "pink"}));
Flower daisyFlower = new Flower("daisy", true, 21.1f, Arrays.asList(new String[] {"purple", "white"}));
Flower peonyFlower = new Flower("peony", false, 19.2f, Arrays.asList(new String[] {"red", "green"}));
collection.insertMany(Arrays.asList(roseFlower, daisyFlower, peonyFlower));
// Update a document
Filters.lte("height", 22),
Updates.addToSet("colors", "pink")
// Delete a document
collection.deleteOne(Filters.eq("name", "rose"));
// Return and print all documents in the collection
List<Flower> flowers = new ArrayList<>();

The example prints the following output:

Flower {
id: 65b178ffa38ac42044ca1573
name: daisy
colors: [purple, white, pink]
isBlooming: true
height: 21.1
Flower {
id: 65b178ffa38ac42044ca1574
name: peony
colors: [red, green]
isBlooming: false
height: 19.2


By default, the PojoCodecProvider omits fields in your POJO that are set to null. For more information about how to specify this behavior, see the POJO Customization guide.

For more information about the methods and classes mentioned in this section, see the following API documentation:

This guide describes how to convert data between BSON and the POJO format by performing the following tasks:

  • Instantiate a PojoCodecProvider which contains codecs that define how to encode and decode data between BSON and the POJO fields.

  • Specify the automatic conversion behavior for the PojoCodecProvider to apply the Codecs to any class and its properties.

  • Add the PojoCodecProvider to a CodecRegistry, and specify the registry on an instance of a MongoDatabase or MongoCollection.

  • Perform CRUD operations that use the sample POJO class.

← Documents