Document Data Format: POJOs

Overview

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.

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

Example POJO

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) {
        this.name = name;
        this.isBlooming = isBlooming;
        this.height = height;
        this.colors = colors;
    }
    public ObjectId getId() {
        return id;
    }
    public void setId(ObjectId id) {
        this.id = id;
    }
    public String getName() {
        return name;
    }
    public void setName(String name) {
        this.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;
    }
    @Override
    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.

Configure the Driver for POJOs

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();

   Note

   Codec providers also contain other objects such as ClassModel and Convention instances that further define serialization behavior. For more information on 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);

// 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
collection.updateOne(
        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<>();
collection.find().into(flowers);
System.out.println(flowers);

[
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
}]

Summary

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.