Codifica datos con códecs de tipo

Overview

En esta guía, puede aprender sobre los códecs y las clases de soporte que manejan la codificación y decodificación de objetos Java hacia y desde datos BSON en el controlador Java de MongoDB. Codec La abstracción te permite mapear cualquier tipo de Java a un tipo BSON correspondiente. Puedes usar esto para mapear tus objetos de dominio directamente hacia y desde BSON en lugar de usar un objeto intermedio basado en mapas como Document o BsonDocument.

Puedes aprender cómo especificar la lógica personalizada de codificación y decodificación utilizando la abstracción Codec y ver implementaciones de ejemplo en las siguientes secciones:

• Códec

• CodecRegistry

• CodecProvider

• Ejemplo de Codec Personalizado

Si estás personalizando la lógica de codificación y decodificación para objetos Java comunes (POJO), lee nuestra guía sobre Personalización de POJO.

Códec

La interfaz Codec contiene métodos abstractos para la serialización y deserialización de objetos Java a datos BSON. Puedes definir tu lógica de conversión entre BSON y el objeto Java en la implementación de esta interfaz.

Para implementar la interfaz Codec, sobreescribe los métodos abstractos encode(), decode() y getEncoderClass().

El método encode() requiere los siguientes parámetros:

Este método utiliza la instancia BsonWriter para enviar el valor codificado a MongoDB y no devuelve ningún valor.

El método decode() devuelve la instancia del objeto Java rellena con el valor de los datos BSON. Este método requiere los siguientes parámetros:

El método getEncoderClass() devuelve una instancia de clase de la clase Java, ya que Java no puede inferir el tipo debido a la eliminación de tipos.

Vea los siguientes ejemplos de código que muestran cómo puede implementar un Codec personalizado.

La enumeración PowerStatus contiene los valores "ON" y "OFF" para representar los estados de un interruptor eléctrico.

public enum PowerStatus {
    ON,
    OFF
}

La clase PowerStatusCodec implementa Codec para convertir los valores Java enum en los correspondientes valores booleanos BSON. El método encode() convierte un PowerStatus a un booleano BSON y el método decode() realiza la conversión en la dirección opuesta.

public class PowerStatusCodec implements Codec<PowerStatus> {
    @Override
    public void encode(BsonWriter writer, PowerStatus value, EncoderContext encoderContext) {
        if (value != null) {
            writer.writeBoolean(value.equals(PowerStatus.ON) ? Boolean.TRUE : Boolean.FALSE);
        }
    }
    @Override
    public PowerStatus decode(BsonReader reader, DecoderContext decoderContext) {
        return reader.readBoolean() ? PowerStatus.ON : PowerStatus.OFF;
    }
    @Override
    public Class<PowerStatus> getEncoderClass() {
        return PowerStatus.class;
    }
}

Puedes añadir una instancia del PowerStatusCodec a tu CodecRegistry, la cual contiene un mapeo entre tu Codec y el tipo de objeto Realm Java al que aplica. Continúa en la sección CodecRegistry de esta página para ver cómo puedes incluir tu Codec.

Para obtener más información sobre las clases e interfaces en esta sección, consulte la siguiente documentación de API:

• Códec

• BsonWriter

• BsonBinaryWriter

• EncoderContext

• BsonReader

• DecoderContext

• BsonBinaryReader

CodecRegistry

Un CodecRegistry es una colección inmutable de instancias de Codec que codifican y decodifican las clases Java que especifican. Puedes utilizar cualquiera de los siguientes métodos de fábrica estáticos de la clase CodecRegistries para construir un CodecRegistry a partir de las instancias de Codec contenidas en los tipos asociados:

• fromCodecs()

• fromProviders()

• fromRegistries()

El siguiente snippet muestra cómo construir un CodecRegistry usando el método fromCodecs():

CodecRegistry codecRegistry = CodecRegistries.fromCodecs(new IntegerCodec(), new PowerStatusCodec());

En el ejemplo anterior, asignamos al CodecRegistry las siguientes implementaciones Codec:

• IntegerCodec, un Codec que convierte Integers y forma parte del paquete BSON.

• PowerStatusCodec, nuestra muestra Codec que convierte ciertas cadenas de Java en valores booleanos BSON.

Puedes recuperar las instancias de Codec de la instancia CodecRegistry del ejemplo anterior utilizando el siguiente código:

Codec<PowerStatus> powerStatusCodec = codecRegistry.get(PowerStatus.class);
Codec<Integer> integerCodec = codecRegistry.get(Integer.class);

Si intentas recuperar una instancia Codec para una clase que no está registrada, el método get() lanza una excepción CodecConfigurationException.

Para obtener más información sobre las clases e interfaces en esta sección, consulte la siguiente documentación de API:

• CodecRegistries

• IntegerCodec

CodecProvider

Un CodecProvider es una interfaz que contiene métodos abstractos que crean instancias de Codec y las asignan a una instancia CodecRegistry. De manera similar al CodecRegistry, la biblioteca BSON utiliza las instancias de Codec recuperadas por el método get() para convertir entre los tipos de datos Java y BSON.

Sin embargo, si agrega una clase que contiene campos que requieren los objetos Codec correspondientes, debe asegurarse de instanciar los objetos Codec para los campos de la clase antes de instanciar los objetos Codec para la clase. Puede usar el parámetro CodecRegistry en el método get() para pasar cualquiera de las instancias Codec de las que depende el objeto Codec.

El siguiente ejemplo de código muestra cómo se puede implementar CodecProvider para pasar a MonolightCodec cualquier instancia de Codec que necesite en una instancia de CodecRegistry como la PowerStatusCodec de nuestro ejemplo anterior:

public class MonolightCodecProvider implements CodecProvider {
    public MonolightCodecProvider() {}
    @Override
    @SuppressWarnings("unchecked")
    public <T> Codec<T> get(Class<T> clazz, CodecRegistry registry) {
        if (clazz == Monolight.class) {
            return (Codec<T>) new MonolightCodec(registry);
        }
        // return null when not a provider for the requested class
        return null;
    }
}

Para ver un ejemplo ejecutable que demuestre operaciones de lectura y operaciones de guardar utilizando estas Codec clases, consulta la sección Ejemplo de códec personalizado de esta guía.

Cuando trabajes con POJOs, considera usar PojoCodecProvider para minimizar el código duplicado al convertir tipos de datos de uso común y personalizar su comportamiento. Consulta nuestra guía de personalización de POJO para más información.

CodecRegistry newRegistry = CodecRegistries.fromRegistries(
    CodecRegistries.fromCodecs(new MyEnumCodec()),
    MongoClientSettings.getDefaultCodecRegistry());

Mapa de clases de tipos Bson

La clase BsonTypeClassMap contiene una asignación recomendada entre BSON y Java types. Puedes utilizar esta clase en tu Codec o CodecProvider personalizada para ayudarte a gestionar a qué clases contenedoras que implementan Iterable o Map, tales como la clase Document, decodificar tus tipos BSON.

Puede agregar o modificar la asignación BsonTypeClassMap por defecto pasando un Map que contenga nuevas entradas o reemplazos.

El siguiente fragmento de código muestra cómo recuperar el tipo de clase Java que corresponde al tipo BSON en la instancia predeterminada BsonTypeClassMap:

BsonTypeClassMap bsonTypeClassMap = new BsonTypeClassMap();
Class<?> clazz = bsonTypeClassMap.get(BsonType.ARRAY);
System.out.println("Java type: " + clazz.getName());

Este código genera lo siguiente:

Java type: java.util.List

Puedes modificar estas asignaciones en tu instancia especificando reemplazos en el constructor BsonTypeClassMap. El siguiente snippet de código muestra cómo puedes reemplazar la asignación para ARRAY en tu instancia de BsonTypeClassMap con la clase Set:

Map<BsonType, Class<?>> replacements = new HashMap<BsonType, Class<?>>();
replacements.put(BsonType.ARRAY, Set.class);
BsonTypeClassMap bsonTypeClassMap = new BsonTypeClassMap(replacements);
Class<?> clazz = bsonTypeClassMap.get(BsonType.ARRAY);
System.out.println("Java type: " + clazz.getName());

Este código genera lo siguiente:

Java type: java.util.Set

Para obtener una lista completa de las asignaciones por defecto, consulte la Documentación de la API de BsonTypeClassMap.

Para ver un ejemplo de cómo la clase Document utiliza BsonTypeClassMap, consulte el código fuente del controlador para las siguientes clases:

• Proveedor de códecs de documentos

• DocumentCodec

Ejemplo de Codec Personalizado

En esta sección, mostraremos cómo puedes implementar Codec y CodecProvider para definir la lógica de codificación y decodificación para una clase Java personalizada. También mostramos cómo puedes especificar y usar tus propias implementaciones personalizadas para realizar operaciones de inserción y recuperación.

El siguiente snippet muestra nuestro ejemplo de clase personalizada llamada Monolight y sus campos que queremos almacenar y recuperar de una colección de MongoDB:

public class Monolight {
    private PowerStatus powerStatus = PowerStatus.OFF;
    private Integer colorTemperature;
    public Monolight() {}
    // ...

Esta clase contiene los siguientes campos, a cada uno de los cuales debemos asignarle un Codec:

• powerStatus describe si la luz está encendida o apagada para lo cual utilizamos el PowerStatusCodec que convierte valores enum específicos a booleanos BSON.

• colorTemperature describe el color de la luz y contiene un valor Integer para el cual usamos el IntegerCodec incluido en la librería BSON.

El siguiente ejemplo de código muestra cómo podemos implementar un Codec para la clase Monolight. Ten en cuenta que el constructor espera una instancia de CodecRegistry de la cual recupera las instancias de Codec que necesita para codificar y decodificar sus campos:

public class MonolightCodec implements Codec<Monolight>{
    private Codec<PowerStatus> powerStatusCodec;
    private Codec<Integer> integerCodec;
    public MonolightCodec(CodecRegistry registry) {
        this.powerStatusCodec = registry.get(PowerStatus.class);
        this.integerCodec = registry.get(Integer.class);
    }
    // Defines an encode() method to convert Monolight enum values to BSON values
    @Override
    public void encode(BsonWriter writer, Monolight value, EncoderContext encoderContext) {
        writer.writeStartDocument();
        writer.writeName("powerStatus");
        powerStatusCodec.encode(writer, value.getPowerStatus(), encoderContext);
        writer.writeName("colorTemperature");
        integerCodec.encode(writer, value.getColorTemperature(), encoderContext);
        writer.writeEndDocument();
    }
    // Defines a decode() method to convert BSON values to Monolight enum values
    @Override
    public Monolight decode(BsonReader reader, DecoderContext decoderContext) {
        Monolight monolight = new Monolight();
        reader.readStartDocument();
        while (reader.readBsonType() != BsonType.END_OF_DOCUMENT) {
            String fieldName = reader.readName();
            if (fieldName.equals("powerStatus")) {
                monolight.setPowerStatus(powerStatusCodec.decode(reader, decoderContext));
            } else if (fieldName.equals("colorTemperature")) {
                monolight.setColorTemperature(integerCodec.decode(reader, decoderContext));
            } else if (fieldName.equals("_id")){
                reader.readObjectId();
            }
        }
        reader.readEndDocument();
        return monolight;
    }
    // Returns an instance of the Monolight class, since Java cannot infer the class type
    @Override
    public Class<Monolight> getEncoderClass() {
        return Monolight.class;
    }
}

Para garantizar que pongamos las instancias de Codec de los campos a disposición de Monolight, implementamos un CodecProvider personalizado que se muestra en el siguiente ejemplo de código:

public class MonolightCodecProvider implements CodecProvider {
    public MonolightCodecProvider() {}
    @Override
    @SuppressWarnings("unchecked")
    public <T> Codec<T> get(Class<T> clazz, CodecRegistry registry) {
        if (clazz == Monolight.class) {
            return (Codec<T>) new MonolightCodec(registry);
        }
        // return null when not a provider for the requested class
        return null;
    }
}

Después de definir la lógica de conversión, podemos realizar lo siguiente:

• Almacena datos de instancias de Monolight en MongoDB

• Recuperar datos de MongoDB en instancias de Monolight

La siguiente clase de ejemplo contiene código que asigna el MonolightCodecProvider a la instancia de MongoCollection pasándolo al método withCodecRegistry(). La clase de ejemplo también inserta y recupera datos utilizando la clase Monolight y los códecs asociados:

public class MonolightCodecExample {
    public static void main(String[] args) {
        String uri = "<MongoDB connection URI>";
        try (MongoClient mongoClient = MongoClients.create(uri)) {
            CodecRegistry codecRegistry = CodecRegistries.fromRegistries(
                    CodecRegistries.fromCodecs(new IntegerCodec(), new PowerStatusCodec()),
                    CodecRegistries.fromProviders(new MonolightCodecProvider()),
                    MongoClientSettings.getDefaultCodecRegistry());
            MongoDatabase database = mongoClient.getDatabase("codecs_example_products");
            MongoCollection<Monolight> collection = database.getCollection("monolights", Monolight.class).withCodecRegistry(codecRegistry);
            // construct and insert an instance of Monolight
            Monolight myMonolight = new Monolight();
            myMonolight.setPowerStatus(PowerStatus.ON);
            myMonolight.setColorTemperature(5200);
            collection.insertOne(myMonolight);
            // retrieve one or more instances of Monolight
            List<Monolight> lights = new ArrayList<>();
            collection.find().into(lights);
            System.out.println(lights);
        }
    }
}

Si ejecuta el ejemplo anterior, debería ver el siguiente resultado:

[Monolight [powerStatus=ON, colorTemperature=5200]]

Para obtener más información sobre los métodos y clases mencionados en esta sección, consulte la siguiente documentación de la API:

• conCodecRegistry()

• MongoClientSettings.getDefaultCodecRegistry()

• Códec

• CodecProvider