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

For more information on this class, see the PojoCodecProvider.Builder API Documentation.

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:

You can specify Conventions using one of the following methods:

• PojoCodecProvider.Builder.conventions()

• ClassModelBuilder.conventions()

To create a custom Convention, create a class that implements the Convention interface and override the apply() method from which you can access your ClassModelBuilder instance.

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:

The following code snippet shows a sample POJO called Product that uses the preceding annotations.

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

The annotations in the example POJO specify the following behavior:

• Reference the POJO with the specified discriminator key and value, adding the cls field with the value of "AnnotatedProduct" to the BSON document on write operations

• Convert between the POJO name field and value and the BSON modelName field and value in the document

• Convert between the POJO serialNumber field and value the BSON document _id field and value in the document

• Omit the relatedItems field and value when converting data

• Use the Product(String name) constructor when instantiating the POJO

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
}

The following shows sample documents created from the preceding POJOs in a single MongoDB collection:

{ "_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();