Personalización de POJO

ClassModel

Una instancia ClassModel almacena información de conversión de datos sobre una clase POJO específica. Contiene una lista de instancias PropertyModel que describen los campos de propiedad del POJO, si se deben convertir los campos y, opcionalmente, Codecs para convertirlos.

Un ClassModel contiene los siguientes campos:

Para obtener más información sobre esta clase, consulta la ClassModel Documentación de API.

Para crear una instancia de un ClassModel, utiliza el método ClassModel.builder() y especifica tu clase POJO. El constructor utiliza la reflexión para crear los metadatos requeridos.

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

PropertyModel

Un PropertyModel almacena información sobre cómo serializar y deserializar un campo específico en un documento.

El PropertyModel contiene la siguiente información:

Para crear un PropertyModel utilice un PropertyModelBuilder que puede instanciar llamando al método PropertyModel.builder().

Para obtener más información sobre esta clase, consulte la PropertyModel.Builder Documentación de la API.

Ejemplo de BsonExtraElements

La anotación @BsonExtraElements permite especificar un campo para deserializar datos de un documento MongoDB que no tiene una asignación de campo POJO correspondiente. Esto resulta útil cuando la aplicación necesita trabajar con datos en un esquema parcialmente definido. Puede usar esta anotación para acceder a los datos de cualquier campo que no corresponda a los campos de su POJO.

Considera una situación en la que almacenas y recuperas datos para una tienda en línea utilizando el POJO de producto del ejemplo anterior. Cuando ofreces una mayor variedad de productos para el almacenar, descubres que necesitas campos adicionales para describirlos. En lugar de mapear todos los campos adicionales al POJO, puedes acceder a ellos desde un solo campo anotado con @BsonExtraElements como se muestra en el siguiente ejemplo de código:

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

Supongamos que alguien añade campos adicionales para dimensions y weight a los datos del producto, de modo que los documentos incluyan la siguiente información:

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

El documento anterior recuperado utilizando el POJO Product contiene los siguientes datos:

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

Ejemplo de error de BsonRepresentation

La @BsonRepresentation anotación permite almacenar un campo de clase POJO como un tipo de dato diferente en la base de datos MongoDB. El ejemplo de código POJO de producto, en la sección Anotaciones de esta página, utiliza @BsonRepresentation para almacenar String valores como ObjectId valores en los documentos de la base de datos.

Sin embargo, utilizar la anotación @BsonRepresentation para convertir entre tipos de datos distintos de String y ObjectId provoca el siguiente mensaje de error:

Codec must implement RepresentationConfigurable to support BsonRepresentation

Por ejemplo, el siguiente código agrega un campo purchaseDate de tipo Long al POJO Product. Este ejemplo intenta usar @BsonRepresentation para representar valores Long como valores DateTime en la base de datos:

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

El código anterior genera un error. En su lugar, puede crear un códec personalizado para convertir los valores purchaseDate del tipo Long al tipo 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;
    }
}

Luego, agregue una instancia de a LongRepresentableCodec CodecRegistrysu, que contiene una asignación entre su códec y el tipo de objeto Java al que se aplica. Para obtener instrucciones sobre cómo registrar su códec personalizado CodecRegistry con, consulte la guía "Codificar datos con códecs de tipo".

Tipos Abstractos o de Interfaz en Propiedades

Para serializar un POJO que incluye propiedades de tipo de interfaz o clase abstracta, debe especificar discriminadores en el tipo y todos sus subtipos o implementaciones.

Supón que definiste un POJO que referenciaba una clase abstracta User en uno de sus campos así:

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

Si la clase abstracta User tiene subclases FreeUser y SubscriberUser, puede agregar su POJO y clases abstractas a su CodecRegistry de la siguiente manera:

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

Para obtener más información sobre cómo especificar discriminadores, consulta la sección de esta guía sobre Discriminadores.

POJOs sin constructores sin argumentos

El POJO Codecs llama por defecto al constructor vacío, sin argumentos. Para especificar un constructor diferente, debe realizar lo siguiente en su POJO:

• pase la configuración ANNOTATION_CONVENTION a su ClassModelBuilder

• identifique el constructor usando la anotación BsonCreator

Para ver un ejemplo de cómo ANNOTATION_CONVENTION configurar, consulte la sugerencia ANNOTATION_CONVENTION. Para ver un ejemplo de la BsonCreator anotación, consulte el código POJO de ejemplo.

Personalización de la serialización

Por defecto, ClassModelBuilder intenta serializar todas las propiedades no nulas en tu POJO. Si un valor de propiedad es null, la implementación por defecto de PropertySerialization omite ese campo.

Puedes personalizar el comportamiento de serialización de tu POJO realizando una de las siguientes acciones:

• Utiliza la anotación @BsonIgnore en una propiedad para omitir siempre la serialización. Asegúrate de habilitar las anotaciones utilizando las Convencionesadecuadas.

• Crea una clase personalizada que sobrescriba el método shouldSerialize() de la interfaz PropertySerialization. Especifique su implementación personalizada en el PropertyModelBuilder, que puede acceder desde el ClassModelBuilder.

Para obtener más información sobre cómo utilizar la anotación @BsonIgnore en un POJO, consulta la sección de esta guía sobre Anotaciones.

El siguiente código de ejemplo muestra una clase personalizada que implementa la interfaz PropertySerialization para sobrescribir las condiciones por defecto que determinan si se debe serializar un campo:

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

La clase anterior especifica que cualquier entero mayor que 29 no se serializa y, por lo tanto, no se incluye en el documento de MongoDB. Supongamos que aplicaste este comportamiento de serialización personalizada al siguiente POJO de muestra:

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

Puedes especificar la serialización personalizada añadiendo la instancia de CourteousAgeSerialization al PropertyModelBuilder desde la propiedad ClassModel asociada con el campo age utilizando el siguiente código:

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

Si insertas un POJO que contiene un valor mayor que 29 en el campo age, el documento serializado lo omite. La declaración de POJO y el documento resultante se asemejan a lo siguiente:

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

Dado que el valor del campo age es mayor que 29, el documento serializado se parece al siguiente:

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

¿Puedo controlar la serialización de LocalDate?

Sí, el controlador de Java v3.7 agrega soporte nativo para JSR-310 Instant, LocalDate y LocalDateTime.

¿Puedo serializar un java.util.Date como un string en formato aaaa-mm-dd?

Sí, puedes compilar tu propio códec para esta clase y añadirlo al registro.

Agregue el códec al primero en la lista de proveedores, antes del registro de códec predeterminado y antes de PojoCodecProvider:

CodecRegistry registry = CodecRegistries.fromRegistries(
        CodecRegistries.fromCodecs(
                new MyDateAsStringCodec()),
        MongoClientSettings.getDefaultCodecRegistry(),
        fromProviders(pojoCodecProvider));

¿Puedo hacer que los POJOs lean/guarden directamente en el campo y no utilicen los getters/setters en absoluto?

Puede configurar PojoCodecProvider para utilizar SET_PRIVATE_FIELDS_CONVENTION, que establece un campo privado a través de la reflexión si no hay ningún establecedor público disponible.

¿Cómo especifico el nombre de la colección para una clase POJO en particular? ¿Hay alguna anotación?

No hay anotación. Recomendamos agregar una cadena estática a la clase, como se muestra en el siguiente código:

public class Person {
   public static final String COLLECTION_NAME = "people";
}

El siguiente snippet especifica el nombre de la colección para una clase POJO en particular:

database.getCollection(Person.COLLECTION_NAME, Person.class);