Personalización de POJO

Modelo de clase

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, consulte la documentación de la API de ClassModel.

Para instanciar un ClassModel, use el método ClassModel.builder() y especifique su clase POJO. El generador usa la reflexión para crear los metadatos necesarios.

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

Modelo de propiedad

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 documentación de la API PropertyModel.Builder.

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.

Considere una situación en la que almacena y recupera datos para una tienda en línea utilizando el POJO de producto del ejemplo anterior. A medida que ofrece una mayor variedad de productos para la tienda, descubre que necesita campos adicionales para describirlos. En lugar de asignar cada campo adicional al POJO, puede 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 agregó campos adicionales para dimensions y weight a los datos del producto de modo que los documentos contuvieran la siguiente información:

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

El documento anterior recuperado mediante 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, el uso de la anotación @BsonRepresentation para convertir entre tipos de datos distintos de String y ObjectId genera 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.

Supongamos que definió un POJO que hace referencia a una clase abstracta User en uno de sus campos de la siguiente manera:

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, consulte 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:

• pasa la configuración ANNOTATION_CONVENTION a tu ClassModelBuilder

• Identificar 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

De forma predeterminada, ClassModelBuilder intenta serializar todas las propiedades no nulas del POJO. Si el valor de una propiedad es null, la implementación predeterminada de PropertySerialization omite ese campo.

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

• Use la @BsonIgnore anotación para una propiedad para omitir siempre la serialización. Asegúrese de habilitar las anotaciones con las convenciones adecuadas.

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

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

El siguiente código de muestra muestra una clase personalizada que implementa la interfaz PropertySerialization para anular las condiciones predeterminadas para determinar 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;
    // ...
}

Puede especificar la serialización personalizada agregando la instancia CourteousAgeSerialization a la PropertyModelBuilder de la propiedad ClassModel asociada con el campo age usando 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 inserta un POJO que contiene un valor mayor que 29 en el campo age, el documento serializado lo omite. La declaración del POJO y el documento resultante son similares a los siguientes:

// 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 LocalDateserialización de?

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

¿Puedo serializar un java.util.Date como una cadena 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 POJO lean/escriban directamente en el campo y no utilizar los captadores/establecedores 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 específica? ¿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 fragmento especifica el nombre de la colección para una clase POJO particular:

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