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 about 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 and 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 about 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}}
]

BsonRepresentation Error Example

The @BsonRepresentation annotation allows you to store a POJO class field as a different data type in your MongoDB database. The Product POJO code example in the Annotations section of this page uses @BsonRepresentation to store String values as ObjectId values in the database documents.

However, using the @BsonRepresentation annotation to convert between data types other than String and ObjectId causes the following error message:

Codec must implement RepresentationConfigurable to support BsonRepresentation

For example, the following code adds a purchaseDate field of type Long to the Product POJO. This example attempts to use @BsonRepresentation to represent Long values as DateTime values in the database:

public class Product {
    @BsonProperty("modelName")
    private String name;
    @BsonId()
    @BsonRepresentation(BsonType.OBJECT_ID)
    private String serialNumber;
    @BsonRepresentation(BsonType.DATE_TIME)
    private Long purchaseDate;
    // ...
    }

The preceding code results in an error. Instead, you can create a custom Codec to convert the purchaseDate values from type Long to DateTime:

public class LongRepresentableCodec implements Codec<Long>, RepresentationConfigurable<Long> {
    private final BsonType representation;
    /**
     * Constructs a LongRepresentableCodec with a Int64 representation.
     */
    public LongRepresentableCodec() {
        representation = BsonType.INT64;
    }
    private LongRepresentableCodec(final BsonType representation) {
        this.representation = representation;
    }
    @Override
    public BsonType getRepresentation() {
        return representation;
    }
    @Override
    public Codec<Long> withRepresentation(final BsonType representation) {
        if (representation != BsonType.INT64 && representation != BsonType.DATE_TIME) {
            throw new CodecConfigurationException(representation 
            + " is not a supported representation for LongRepresentableCodec");
        }
        return new LongRepresentableCodec(representation);
    }
    @Override
    public void encode(final BsonWriter writer, final Long value, final EncoderContext encoderContext) {
        switch (representation) {
            case INT64:
                writer.writeInt64(value);
                break;
            case DATE_TIME:
                writer.writeDateTime(value);
                break;
            default:
                throw new BsonInvalidOperationException("Cannot encode a Long to a " 
                + representation);
        }
    }
    @Override
    public Long decode(final BsonReader reader, final DecoderContext decoderContext) {
        switch (representation) {
            case INT64:
                return reader.readInt64();
            case DATE_TIME:
                return reader.readDateTime();
            default:
                throw new CodecConfigurationException("Cannot decode " + representation 
                + " to a Long");
        }
    }
    @Override
    public Class<Long> getEncoderClass() {
        return Long.class;
    }
}

Then, add an instance of the LongRepresentableCodec to your CodecRegistry, which contains a mapping between your Codec and the Java object type to which it applies. For instructions on registering your custom Codec with the CodecRegistry, see the Codecs guide.

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 about 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 you can access from the ClassModelBuilder.

For more information about 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 resemble the following:

// 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 resembles the following:

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