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.
Tip
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
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; } 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
ortransient
.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
orMongoCollection
instance that is configured to use theCodecRegistry
.MongoCollection
instance that is created with the POJO document class bound to theTDocument
generic type.
Perform the following steps to meet the configuration requirements defined in the preceding section:
Configure the
PojoCodecProvider
. In this example, we use theautomatic(true)
setting of thePojoCodecProvider.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
andConvention
instances that further define serialization behavior. For more information about codec providers and customization, see the guide on POJO Customization.Add the
PojoCodecProvider
instance to aCodecRegistry
. TheCodecRegistry
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 multipleCodecRegistry
instances into one instancegetDefaultCodecRegistry()
to retrieve aCodecRegistry
instance from a list of codec providersfromProviders()
to create aCodecRegistry
instance from thePojoCodecProvider
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)); Configure the
MongoDatabase
orMongoCollection
instance to use the codecs in theCodecRegistry
. You can configure either a database or collection to specify the codecs.In this example, we set the
CodecRegistry
on aMongoDatabase
calledsample_pojos
by using thewithCodecRegistry()
method:MongoClient mongoClient = MongoClients.create(uri); MongoDatabase database = mongoClient.getDatabase("sample_pojos").withCodecRegistry(pojoCodecRegistry); Pass your POJO class to your call to
getCollection()
as the document class parameter and specify it as the type argument of yourMongoCollection
instance, as shown in the following code:MongoCollection<Flower> collection = database.getCollection("flowers", Flower.class);
Perform CRUD Operations
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 theflowers
collectionUpdate 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 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);
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 }]
Note
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:
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 theCodecs
to any class and its properties.Add the
PojoCodecProvider
to aCodecRegistry
, and specify the registry on an instance of aMongoDatabase
orMongoCollection
.Perform CRUD operations that use the sample POJO class.