POJO Customization

Overview

In this guide, you can learn how to define custom data conversions between BSON and POJOs in the MongoDB Java driver. In our guide on POJOs , we show how to specify a PojoCodecProvider which contains classes that provide instructions on how to convert data for one or more POJO classes and their properties.

We show how to specify your data conversion using the ClassModel and PropertyModel classes. You can also learn about more specific customization from the section on Advanced Configuration .

We also show how to use helpers such as Conventions and Annotations to specify common serialization actions.

See the section on Discriminators if you want to serialize multiple POJO classes to documents in the same collection.

If you need to implement conditional serialization, or if you need to use enums, generics, interface types, or abstract types, see the section on Advanced Configuration .

If you only need to use the predefined behavior to convert data between BSON and POJOs, you can use the automatic setting for the PojoCodecProvider shown in the Document Data Formats: POJOs guide .

Customize a PojoCodecProvider

This section shows you how to specify your data conversion logic and POJO classes with a PojoCodecProvider . The PojoCodecProvider is an implementation of the CodecProvider interface that specifies the Codecs to use in data conversion. Use this implementation when performing data conversion between BSON and POJOs.

You can create a PojoCodecProvider instance using the PojoCodecProvider.builder() method. You can also chain methods to the builder to register any of the following:

• Individual POJO classes

• Package names that contain POJO classes

• Instances of ClassModel that describe conversion logic for a specific POJO class

The following example shows how you can specify the POJOs in a package named "org.example.pojos" and add the PojoCodecProvider to a CodecRegistry :

import org.bson.codecs.configuration.CodecProvider;
import org.bson.codecs.configuration.CodecRegistry;
import org.bson.codecs.pojo.PojoCodecProvider;
import static org.bson.codecs.configuration.CodecRegistries.fromRegistries;
import static org.bson.codecs.configuration.CodecRegistries.fromProviders;
import static com.mongodb.MongoClientSettings.getDefaultCodecRegistry;
CodecProvider pojoCodecProvider = PojoCodecProvider.builder().register("org.example.pojos").build();
CodecRegistry pojoCodecRegistry = fromRegistries(getDefaultCodecRegistry(), fromProviders(pojoCodecProvider));
// Call withCodecRegistry(pojoCodecRegistry) on an instance of MongoClient, MongoDatabase, or MongoCollection

ClassModel<Flower> classModel = ClassModel.builder(Flower.class).build();

Conventions

The Convention interface contains configuration options that modify the behavior of a ClassModel or PropertyModel . You can specify a Convention in a call to PojoCodecProvider.Builder.conventions() or to ClassModelBuilder.conventions() .

You can access the Convention instances defined in the BSON library from the following static fields in the Conventions class:

Annotations

You can apply annotations to the getter and setter methods of a POJO class. These annotations configure the ClassModel and PropertyModel behavior for a specific field, method, or class.

The following annotations are available from the org.bson.codecs.pojo.annotations package:

import org.bson.BsonType;
import org.bson.codecs.pojo.annotations.BsonCreator;
import org.bson.codecs.pojo.annotations.BsonDiscriminator;
import org.bson.codecs.pojo.annotations.BsonId;
import org.bson.codecs.pojo.annotations.BsonIgnore;
import org.bson.codecs.pojo.annotations.BsonProperty;
import org.bson.codecs.pojo.annotations.BsonRepresentation;
@BsonDiscriminator(value="AnnotatedProduct", key="_cls")
public class Product {
    @BsonProperty("modelName")
    private String name;
    @BsonId()
    @BsonRepresentation(BsonType.OBJECT_ID)
    private String serialNumber;
    @BsonIgnore
    private List<Product> relatedItems;
    @BsonCreator
    public Product(@BsonProperty("modelName") String name) {
        this.name = name;
    }
    // ...
}

ClassModel<Product> classModel = ClassModel.builder(Product.class).
       conventions(Arrays.asList(Conventions.ANNOTATION_CONVENTION)).build();

public class Product {
    @BsonProperty("modelName")
    private String name;
    @BsonId()
    @BsonRepresentation(BsonType.OBJECT_ID)
    private String serialNumber;
    @BsonIgnore
    private List<Product> relatedItems;
    @BsonExtraElements
    private Document additionalInfo;
    // ...

{
  "name": "MDB0123",
  "serialNumber": "62e2...",
  "dimensions": "3x4x5",
  "weight": "256g"
}

ProductWithBsonExtraElements [
  name=MDB0123,
  serialNumber=62eb...,
  relatedItems=null,
  additionalInfo=Document{{dimensions=3x4x5, weight=256g}}
]

Discriminators

A discriminator is a property that identifies a specific document schema. The discriminator key identifies a document field to use to identify the schema. The discriminator value identifies the default value of the document field.

Use discriminators to instruct the CodecProvider which object class to use when deserializing to different object classes from the same collection. When serializing the POJO to a MongoDB collection, the associated codec sets the discriminator key-value field, unless otherwise specified in the POJO property data.

You can set and enable a discriminator in a POJO by performing one of the following:

• Use the @BsonDiscriminator annotation to specify the discriminator for the POJO class

• Call enableDiscriminator(true) on the ClassModelBuilder associated with the POJO class

See the following example POJO classes that contain @BsonDiscriminator annotations and example documents that contain the discriminator fields:

@BsonDiscriminator(value="AnonymousUser", key="_cls")
public class AnonymousUser {
    // class code
}
@BsonDiscriminator(value="RegisteredUser", key="_cls")
public class RegisteredUser {
    // class code
}

{ "_cls": "AnonymousUser", "_id": ObjectId("<Object ID>"),  ... }
{ "_cls": "RegisteredUser", "_id": ObjectId("<Object ID>"), ... }

Advanced Configuration

public class UserRecordPojo {
     private User user;
     // ...
}

ClassModel<UserRecordPojo> userRecordPojo = ClassModel.builder(UserRecordPojo.class).enableDiscriminator(true).build();
ClassModel<User> userModel = ClassModel.builder(User.class).enableDiscriminator(true).build();
ClassModel<FreeUser> freeUserModel = ClassModel.builder(FreeUser.class).enableDiscriminator(true).build();
ClassModel<SubscriberUser> subscriberUserModel = ClassModel.builder(SubscriberUser.class).enableDiscriminator(true




    
).build();
PojoCodecProvider pojoCodecProvider = PojoCodecProvider.builder().register(userRecordPojo, userModel, freeUserModel, subscriberUserModel).build();
CodecRegistry pojoCodecRegistry = fromRegistries(getDefaultCodecRegistry(), fromProviders(pojoCodecProvider));

public class CourteousAgeSerialization implements PropertySerialization<Integer> {
    @Override
    public boolean shouldSerialize(Integer value) {
        return (value < 30);
    }
}

public class BirthdayInvitation {
    private String name;
    private Integer age;
    private LocalDateTime eventDateTime;
    // ...
}

ClassModelBuilder<BirthdayInvitation> classModel = ClassModel.builder(BirthdayInvitation.class);
((PropertyModelBuilder<Integer>) classModel.getProperty("age"))
        .propertySerialization(new CourteousAgeSerialization());
PojoCodecProvider pojoCodecProvider = PojoCodecProvider.builder().register(classModel.build()).build();
CodecRegistry pojoCodecRegistry = fromRegistries(getDefaultCodecRegistry(), fromProviders(pojoCodecProvider));

// constructor with parameters for name, age, and eventDateTime, respectively
BirthdayInvitation invitation = new BirthdayInvitation(
        "Galadriel",
        7582,
        LocalDateTime.of(2021, Month.JANUARY, 18, 30, 0)
    );

{ "_id" : ObjectId("..."), "eventDateTime" : ..., "name" : "Galadriel" }

public class ApplicationUser {
    private Optional<Address> optionalAddress;
    private Optional<Subscription> optionalSubscription;
    // ...
}

public class OptionalPropertyCodecProvider implements PropertyCodecProvider {
    @Override
    @SuppressWarnings({"rawtypes", "unchecked"})
    public <T> Codec<T> get(final TypeWithTypeParameters<T> type, final PropertyCodecRegistry registry) {
        // Check the main type and number of generic parameters
        if (Optional.class.isAssignableFrom(type.getType()) && type.getTypeParameters().size() == 1) {
            // Get the codec for the concrete type of the Optional, as its declared in the POJO.
            Codec<?> valueCodec = registry.get(type.getTypeParameters().get(0));
            return new OptionalCodec(type.getType(), valueCodec);
        } else {
            return null;
        }
    }
    private static final class OptionalCodec<T> implements Codec<Optional<T>> {
        private final Class<Optional<T>> encoderClass;
        private final Codec<T> codec;
        private OptionalCodec(final Class<Optional<T>> encoderClass, final Codec<T> codec) {
            this.encoderClass = encoderClass;
            this.codec = codec;
        }
        @Override
        public void encode(final BsonWriter writer, final Optional<T> optionalValue, final EncoderContext encoderContext) {
            if (optionalValue != null && optionalValue.isPresent()) {
                codec.encode(writer, optionalValue.get(), encoderContext);
            } else {
                writer.writeNull();
            }
        }
        @Override
        public Optional<T> decode(final BsonReader reader, final DecoderContext context) {
            return Optional.of(codec.decode(reader, context));
        }
        @Override
        public Class<Optional<T>> getEncoderClass() {
            return encoderClass;
        }
    }
}

CodecProvider pojoCodecProvider = PojoCodecProvider.builder()
        .register("org.example.pojos")
        .register(new OptionalPropertyCodecProvider())
        .build();