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 PropertyModel instancias que describen los campos de propiedad del POJO, si se deben convertir los campos y, opcionalmente, Codecs para convertir los campos.

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 se 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 te permite especificar un campo para deserializar datos de un documento de MongoDB que carece de una mapeo de campo POJO correspondiente. Esto es útil cuando la aplicación necesita trabajar con datos en un esquema parcialmente definido. Puede utilizar esta anotación para acceder a 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 representación BSON

La anotación @BsonRepresentation permite almacenar un campo de clase POJO como un tipo de datos diferente en tu base de datos MongoDB. El código de ejemplo de Product POJO en la sección de Anotaciones de esta página utiliza @BsonRepresentation para almacenar valores String como valores ObjectId 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 Codec personalizado para convertir los valores de purchaseDate del tipo Long a 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;
    }
}

A continuación, agrega una instancia del LongRepresentableCodec a tu CodecRegistry, que contiene un mapeo entre su Codec y el tipo de objeto Realm Java al que se aplica. Para obtener instrucciones sobre cómo registrar tu Codec personalizado con CodecRegistry, consulta la guía Codificar datos con codecs de tipo.

Tipos Abstractos o de Interfaz en Propiedades

Para serializar un POJO que incluye propiedades de tipo clase abstracta o interfaz, debes especificar discriminadores en el tipo y en 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 sus clases POJO y 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 por defecto llama al constructor vacío, sin argumentos. Para especificar un constructor diferente, debes realizar lo siguiente en tu 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 configurar el ANNOTATION_CONVENTION, consulta el consejo ANNOTATION_CONVENTION. Para un ejemplo de la anotación BsonCreator, consulta el código POJO de muestra.

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

Puesto que el valor del campo age es mayor que 29, el documento serializado es similar 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.

Agrega el códec al primero en la lista de proveedores, antes del registro de códecs por defecto y antes del 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 el PojoCodecProvider para usar el SET_PRIVATE_FIELDS_CONVENTION, lo que establece un campo privado a través de reflexión si no hay un setter público disponible.

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

No hay anotaciones. Recomendamos agregar una string estática en tu 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);