POJO Customization

ClassModel

A ClassModel instance stores data conversion information about a specific POJO class. It contains a list of PropertyModel instances which describe the property fields of the POJO, whether to convert fields, and optionally, Codecs to convert the fields.

A ClassModel contains the following fields:

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

To instantiate a ClassModel, use the ClassModel.builder() method and specify your POJO class. The builder uses reflection to create the required metadata.

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

PropertyModel

A PropertyModel stores information on how to serialize/deserialize a specific field in a document.

The PropertyModel contains the following information:

To create a PropertyModel use a PropertyModelBuilder which you can instantiate by calling the PropertyModel.builder() method.

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

BsonExtraElements Example

The @BsonExtraElements annotation allows you to specify a field to deserialize data from a MongoDB document that lacks a corresponding POJO field mapping. This is useful when your application needs to work with data in a partially-defined schema. You can use this annotation to access data from any fields that do not correspond to the fields on your POJO.

Consider a situation in which you store and retrieve data for an online store using the Product POJO from the previous example. As you offer a greater variety of products for the store, you discover that you need additional fields to describe them. Instead of mapping each additional field to the POJO, you can access them from a single field annotated with @BsonExtraElements as shown in the following code example:

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;
    // ...

Suppose someone added additional fields for dimensions and weight to the product data such that the documents contained the following information:

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

The preceding document retrieved using the Product POJO contains the following data:

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

Abstract or Interface Types in Properties

To serialize a POJO that includes abstract class or interface type properties, you must specify discriminators on the type and all its subtypes or implementations.

Suppose you defined a POJO that referenced an abstract class User in one of its fields as follows:

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

If the User abstract class has subclasses FreeUser and SubscriberUser, you can add your POJO and abstract classes to your CodecRegistry as follows:

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

For more information on specifying discriminators, see the section of this guide on Discriminators.

POJOs without No-Argument Constructors

The POJO Codecs default to calling the empty, no-argument constructor. To specify a different constructor, you must perform the following in your POJO:

• pass the ANNOTATION_CONVENTION setting to your ClassModelBuilder

• identify the constructor using the BsonCreator annotation

For an example of setting the ANNOTATION_CONVENTION, see the ANNOTATION_CONVENTION example. For an example of the BsonCreator annotation, see the POJO with annotation code example.

Serialization Customization

By default, ClassModelBuilder attempts to serialize all the non-null properties in your POJO. If a property value is null, the default PropertySerialization implementation skips that field.

You can customize your POJO serialization behavior by performing one of the following:

• Use the @BsonIgnore annotation for a property to always skip serialization. Make sure to enable annotations using the appropriate Conventions.

• Create a custom class that overrides the shouldSerialize() method of the PropertySerialization interface. Specify your custom implementation to the PropertyModelBuilder which is accessible from the ClassModelBuilder.

For more information on how to use the @BsonIgnore annotation in a POJO, see the section of this guide on Annotations.

The following sample code shows a custom class that implements the PropertySerialization interface to override the default conditions by which to determine whether to serialize a field:

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

The preceding class specifies that any integer greater than 29 is not serialized, and, therefore, not included in the MongoDB document. Suppose you applied this custom serialization behavior to the following sample POJO:

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

You can specify the custom serialization by adding the CourteousAgeSerialization instance to the PropertyModelBuilder from the ClassModel property associated with the age field using the following code:

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

If you insert a POJO that contains a value greater than 29 in the age field, the serialized document omits it. The POJO declaration and resulting document could look something like this:

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

Since the age field value is greater than 29, the serialized document should look something like this:

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