Efficient POJO Mapping To/From Java Mongo DBObject Using Jackson

1. Introduction

When working with MongoDB in Java applications, we often need to convert between Plain Old Java Objects (POJOs) and MongoDB’s document format. While MongoDB’s Java driver provides a native POJO codec, many projects already leverage Jackson for JSON processing elsewhere in their codebase.

In this tutorial, we’ll explore two Jackson-based libraries that provide efficient POJO mapping: MongoJack and bson4jackson. Both approaches offer distinct advantages depending on our project’s requirements.

2. Understanding the Problem

MongoDB stores data in BSON (Binary JSON), which includes types that don’t exist in standard JSON, such as ObjectId, Date and Decimal128. Standard Jackson serializes POJOs to JSON strings, but converting these to MongoDB documents requires an inefficient two-step process.

First, let’s add the base MongoDB driver dependency to our pom.xml:

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

Now, let’s define a class that we’ll use throughout our examples:

public class Product {
    private String id;
    private String name;
    private double price;

    // getters and setters
}

The challenge lies in efficiently mapping this POJO to MongoDB’s Document format while preserving type information and avoiding unnecessary string intermediaries.

3. Using MongoJack for POJO Mapping

MongoJack provides a high-level abstraction that wraps MongoDB collections with Jackson-powered serialization. It handles the BSON conversion transparently, making CRUD operations straightforward.

3.1. MongoJack Setup and Service Class

Now, let’s add the required dependency:

<dependency>
    <groupId>org.mongojack</groupId>
    <artifactId>mongojack</artifactId>
    <version>5.0.3</version>
</dependency>

Next, let’s update our POJO to use MongoJack’s ObjectId annotation:

public class Product {
    @ObjectId
    @Id
    private String id;
    private String name;
    private double price;

    // getters and setters
}

The @ObjectId annotation tells MongoJack to serialize the id field as a MongoDB ObjectId rather than a plain string.

Let’s continue and add a service class that demonstrates basic CRUD operations:

public class ProductService {
    private final JacksonMongoCollection<Product> collection;

    public ProductService(MongoDatabase database) {
        this.collection = JacksonMongoCollection.builder()
          .build(database, "products", Product.class, UuidRepresentation.STANDARD);
    }

    public void save(Product product) {
        collection.insertOne(product);
    }

    public Product findById(String id) {
        return collection.findOneById(id);
    }

    public long count() {
        return collection.countDocuments();
    }
}

MongoJack’s JacksonMongoCollection wraps the standard MongoDB collection and automatically handles serialization. We don’t need to manually convert between POJOs and Document’s.

3.2. Testing MongoJack Integration

Consequently, let’s verify that MongoJack correctly persists and retrieves our POJOs. Hence, we’ll use Flapdoodle to spin up an in-memory MongoDB instance:

@Test
void whenSavingProduct_thenProductIsPersisted() {
    Product product = new Product("Laptop", 999.99);

    productService.save(product);

    assertNotNull(product.getId());
    assertEquals(1, productService.count());
}

This test demonstrates that MongoJack seamlessly handles both serialization (when saving) and deserialization (when retrieving). For this reason, the POJO fields are correctly mapped to BSON document fields and back without any manual conversion code.

4. Using BSON4Jackson for Direct Bson Serialization

While MongoJack provides convenience, bson4jackson offers more control by extending Jackson’s core functionality to handle BSON directly. For this reason, this approach is useful when we need custom serialization logic or want to integrate with existing Jackson configurations.

4.1. BSON4Jackson Implementation

With this in mind, let’s set up our code and add the dependency:

<dependency>
    <groupId>de.undercouch</groupId>
    <artifactId>bson4jackson</artifactId>
    <version>2.18.0</version>
</dependency>

Now, let’s create a mapper class that handles the conversion:

public class BsonProductMapper {
    private final ObjectMapper objectMapper;

    public BsonProductMapper() {
        this.objectMapper = new ObjectMapper(new BsonFactory());
    }

    public byte[] toBytes(Product product) throws JsonProcessingException {
        return objectMapper.writeValueAsBytes(product);
    }

    public Product fromBytes(byte[] bson) throws IOException {
        return objectMapper.readValue(bson, Product.class);
    }

    public Document toDocument(Product product) throws IOException {
        byte[] bytes = toBytes(product);
        RawBsonDocument bsonDoc = new RawBsonDocument(bytes);
        return Document.parse(bsonDoc.toJson());
    }

    public Product fromDocument(Document document) throws IOException {
        BsonDocument bsonDoc = document.toBsonDocument();
        BasicOutputBuffer buffer = new BasicOutputBuffer();
        new BsonDocumentCodec().encode(
         new BsonBinaryWriter(buffer), 
         bsonDoc, EncoderContext
           .builder()
           .build()
        );
        return fromBytes(buffer.toByteArray());
    }
}

The BsonProductMapper class encapsulates our bson4jackson conversion logic. Let’s explain the main features.

In the constructor, the BsonFactory replaces Jackson’s default JSON factory thus enabling direct BSON serialization. This bypasses the JSON string intermediary, resulting in better performance for high-throughput applications.

The toBytes() method serializes directly to binary BSON as a result of the BsonFactory constructor configuration.

Similarly,  fromBytes() uses the BsonFactory to handle the binary parsing, mapping BSON types back to their Java equivalents.

The toDocument() method bridges our BSON bytes to MongoDB’s Document class. We first serialize the POJO to bytes, wrap them in a RawBsonDocument (which interprets raw BSON without parsing). Next, this gets converted to a standard Document via JSON.

The fromDocument() method reverses this process. We convert the Document to a BsonDocument, then use MongoDB’s BsonDocumentCodec to encode it into a BasicOutputBuffer. This buffer holds the raw BSON bytes that we pass to fromBytes() for final deserialization.

4.2. Testing BSON4Jackson Serialization

Let’s verify that bson4jackson correctly serializes our POJOs to binary BSON format:

@Test
void whenSerializingProduct_thenReturnsByteArray() throws IOException {
    Product product = new Product("Test Product", 29.99);

    byte[] bytes = mapper.toBytes(product);

    assertNotNull(bytes);
    assertTrue(bytes.length > 0);
}

As we can see from the test, bson4jackson produces a valid byte array representation of our POJO. Unlike JSON serialization, this binary format is directly compatible with MongoDB’s internal storage format.

Now, let’s test the deserialization process:

@Test
void givenSerializedProduct_whenDeserializing_thenReturnsProduct() throws IOException {
    Product product = new Product("Test Product", 29.99);
    byte[] bytes = mapper.toBytes(product);

    Product deserializedProduct = mapper.fromBytes(bytes);

    assertEquals(product.getName(), deserializedProduct.getName());
    assertEquals(product.getPrice(), deserializedProduct.getPrice(), 0.01);
}

This test validates that the binary BSON data correctly deserializes back into a POJO with all field values preserved. The BsonFactory handles type mapping automatically.

4.3. Testing Document Conversion

For integration with MongoDB collections, we need to convert between POJOs and Document objects:

@Test
void whenConvertingProductToDocument_thenReturnsValidDocument() throws IOException {
    Product product = new Product("Test Product", 29.99);

    Document document = mapper.toDocument(product);

    assertNotNull(document);
    assertEquals(product.getName(), document.getString("name"));
    assertEquals(product.getPrice(), document.getDouble("price"), 0.01);
}

This test shows that our mapper correctly transforms a POJO into a MongoDB Document. Accordingly, the resulting document can be directly inserted into a MongoDB collection using the standard driver.

Finally, let’s verify the complete round-trip through the Document format:

@Test
void whenRoundTrippingProduct_thenDataIsPreserved() throws IOException {
    Product product = new Product("Round Trip Product", 149.99);

    Document document = mapper.toDocument(product);
    Product roundTrippedProduct = mapper.fromDocument(document);

    assertEquals(product.getName(), roundTrippedProduct.getName());
    assertEquals(product.getPrice(), roundTrippedProduct.getPrice(), 0.01);
}

This test confirms that data integrity is maintained throughout the entire conversion cycle: from POJO to bson bytes to Document to bson bytes and back to POJO.

5. Performance Considerations

Choosing between MongoJack and bson4jackson depends on our specific requirements.

MongoJack is best in scenarios where we need fast development with minimal boilerplate code. It provides a complete solution with built-in collection wrappers and query support. The disadvantage is less flexibility in customizing the serialization process.

bson4jackson is better suited for applications requiring more in-depth control over serialization or those with existing Jackson infrastructure. Since it operates at a lower level, we can fine-tune specific conversion paths and use custom type handlers.

For most applications, the performance difference between these approaches is negligible. The primary consideration should be developer productivity and how well each library integrates with our existing codebase.

6. Conclusion

In this article, we’ve explored two efficient approaches for mapping POJOs to MongoDB documents using Jackson.

MongoJack provides a high-level and convenient API that handles common use cases with minimal configuration needed. It automatically managed ObjectId generation. Furthermore, it seamlessly integrates with MongoDB collections.

On the other hand, bson4jackson offers lower-level control by extending Jackson to serialize directly to BSON format. This approach is better for applications requiring custom serialization logic or integration with existing Jackson configurations.

Finally, both libraries eliminate the inefficient JSON string intermediary and provide efficient options for POJO-to-MongoDB mapping.

As always, the code is available over on GitHub.