Personalização POJO

ClassModel

Uma instância ClassModel armazena informações de conversão de dados sobre uma classe POJO específica. Ele contém uma lista de instâncias PropertyModel que descrevem os campos de propriedade do POJO, se deseja converter campos e, opcionalmente, Codecs para converter os campos.

Um ClassModel contém os seguintes campos:

Para obter mais informações sobre essa classe, consulte a documentação da API ClassModel.

Para instanciar um ClassModel, utilize o método ClassModel.builder() e especifique sua classe POJO. O construtor usa reflexão para criar os metadados necessários.

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

PropertyModel

Um PropertyModel armazena informações sobre como serializar/desserializar um campo específico em um documento.

O PropertyModel contém as seguintes informações:

Para criar um PropertyModel utilize um PropertyModelBuilder que você pode instanciar chamando o método PropertyModel.builder().

Para obter mais informações sobre esta classe, consulte o PropertyModel.Builder Documentação da API.

Exemplo de BSONExtraElements

A anotação @BsonExtraElements permite especificar um campo para desserializar dados de um documento MongoDB que não tem um mapeamento de campo POJO correspondente. Isso é útil quando seu aplicativo precisa trabalhar com dados em um esquema parcialmente definido. Você pode usar essa anotação para acessar dados de qualquer campo que não corresponda aos campos no seu POJO.

Considere uma situação em que você armazena e recupera dados de uma loja virtual usando o POJO do produto do exemplo anterior. À medida que você oferece uma variedade maior de produtos na loja, descobre que precisa de campos adicionais para descrevê-los. Em vez de mapear cada campo adicional ao POJO, você pode acessá-los a partir de um único campo anotado com @BsonExtraElements, conforme mostrado no exemplo de código a seguir:

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

Suponha que alguém tenha adicionado campos para dimensions e weight aos dados do produto, de modo que os documentos contenham as seguintes informações:

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

O documento anterior recuperado usando o POJO do Product contém os seguintes dados:

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

Exemplo de erro BsonRepresentation

A anotação @BsonRepresentation permite que você armazene um campo de classe POJO como um tipo de dados diferente em seu banco de dados MongoDB. O exemplo de código POJO do produto na seção Anotações desta página usa @BsonRepresentation para armazenar valores String como valores ObjectId nos documentos do banco de dados.

No entanto, o uso da anotação @BsonRepresentation para converter entre tipos de dados diferentes de String e ObjectId causa a seguinte mensagem de erro:

Codec must implement RepresentationConfigurable to support BsonRepresentation

Por exemplo, o código a seguir adiciona um campo purchaseDate do tipo Long ao Product PoJo. Este exemplo tenta usar @BsonRepresentation para representar valores Long como valores DateTime no banco de dados:

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

O código anterior resulta em um erro. Em vez disso, você pode criar um codec personalizado para converter os valores purchaseDate do tipo Long para 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;
    }
}

Em seguida, adicione uma instância do LongRepresentableCodec no seu CodecRegistry que contém um mapeamento entre seu Codec e o tipo de objeto Java ao qual ele se aplica. Para obter instruções sobre como registrar seu codec personalizado com o CodecRegistry, consulte o guia de codecs.

Tipos abstratos ou de interface em propriedades

Para serializar um POJO que inclui as propriedades classe abstrata ou tipo de interface, você deve especificar discriminadores no tipo e em todos os seus subtipos ou implementações.

Suponha que você definiu um POJO que referenciou uma classe abstrata User em um de seus campos da seguinte maneira:

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

Se a classe abstrata User tiver subclasses FreeUser e SubscriberUser, você poderá adicionar o POJO e as classes abstratas à CodecRegistry da seguinte forma:

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 obter mais informações sobre como especificar discriminadores, consulte a seção deste guia sobre Discriminadores.

POJOs que não têm construtores sem argumentos

O padrão do POJO Codecs é chamar o construtor vazio e sem argumentos. Para especificar um construtor diferente, você deve executar o seguinte em seu POJO:

• passe a configuração ANNOTATION_CONVENTION para o seu ClassModelBuilder

• identifique o construtor utilizando a anotação BsonCreator

Para ver um exemplo de configuração do ANNOTATION_CONVENTION, consulte o exemplo ANNOTATION_CONVENTION. Para ver um exemplo da anotação BsonCreator, consulte o exemplo de código POJO com anotação.

Personalização de serialização

Por padrão, o ClassModelBuilder tenta serializar todas as propriedades não nulas em seu POJO. Se um valor de propriedade for null, a implementação padrão do PropertySerialization pulará esse campo.

Você pode personalizar seu comportamento de serialização de POJO executando um dos seguintes procedimentos:

• Utilize a anotação @BsonIgnore para uma propriedade para sempre ignorar a serialização. Certifique-se de habilitar as anotações usando as convençõesapropriadas.

• Crie uma classe personalizada que substitua o método shouldSerialize() da interface PropertySerialization. Especifique sua implementação personalizada para PropertyModelBuilder, que pode ser acessada em ClassModelBuilder.

Para obter mais informações sobre como usar a anotação @BsonIgnore em um POJO, consulte a seção deste guia sobre Anotações.

O código de exemplo a seguir mostra uma classe personalizada que implementa a interface PropertySerialization para substituir as condições padrão pelas quais se determina a serialização de um campo:

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

A classe anterior especifica que qualquer número inteiro maior que 29 não é serializado e, portanto, não está incluído no documento MongoDB. Suponha que você tenha aplicado este comportamento de serialização personalizada à seguinte amostra POJO:

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

Você pode especificar a serialização personalizada adicionando a instância CourteousAgeSerialization ao PropertyModelBuilder da propriedade ClassModel associada ao campo age usando o seguinte 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));

Se você inserir um POJO que contém um valor maior que 29 no campo age, o documento serializado o omitirá. A declaração POJO e o documento resultante poderiam ser mais ou menos assim:

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

Como o valor do campo age é maior que 29, o documento serializado deve ser semelhante a este:

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