Añade información sobre writer (Jackson)

sio2sio2 · sio2sio2 · commit 7adf346bd602 · 2025-11-09T20:51:05.000+01:00
diff --git a/source/02.formatos/02.json/02.jackson.rst b/source/02.formatos/02.json/02.jackson.rst
@@ -170,6 +170,21 @@ Ilustrémoslo:
    de estas clases respectivamente en vez de las clases más concretas
    |JsonMapper.Builder| y |JsonMapper|.
 
+.. tip:: El ejemplo ilustra cómo puede habilitarse con ``.enable()`` una
+   característica de serialización que por defecto esté desactiva. y obviamente
+   puede hacerse al contrario con ``.disable()``. También existe ``.configure()``
+   que añade un segundo argumento *booleano* para expresar si se quiere
+   habilitada o deshabilitada la característica:
+
+   .. code-block:: java
+
+      JsonFactory factory = JsonFactory.builder()
+           .configure(JsonReadFeature.ALLOW_JAVA_COMMENTS, true)
+           .build();
+
+.. seealso:: El control de la serialización puede hacerse de un modo más exhaustivo
+   utilizando el :ref:`concepto de writer <jackson-writer>`. Lo introduciremos más adelante.
+
 Estás tres etapas pueden simplificarse si necesitamos menos configuración. Ya hemos
 visto que pueden reducirse a una, si no necesitamos configuración adicional en
 absoluto:
@@ -473,6 +488,117 @@ anotación individual en cada uno de los atributos y hacer lo siguiente:
    y deserializadora (|LocalDateDeserializer|) ya están definidas y nos
    limitamos a usarlas en vez de definirlas nosotros.
 
+.. _jackson-writer:
+
+Control de la serialización
+===========================
+
+.. rubric:: Características generales de serialización
+
+Ya hemos dicho que algunas características generales de la serialización
+independientes al formato de traducción puede configurarse antes de crear el
+mapeador. Hay, sin embargo, otro mecanismo más potente para definir la
+serialización hacia el formato: definir un |ObjectWriter|.
+
+.. code-block:: java
+   :emphasize-lines: 7
+
+   ObjectMapper mapper = JsonMapper.builder().build();  // Mapper inmutable.
+   ObjectWriter writer = mapper.writer()
+      .with(Serialization.INDENT_OUTPUT);
+
+   // Ahora usamos el writer (en vez del mapper) para escribir los datos
+
+   writer.writeValue(st, datos);
+
+.. _jackson-writer-wrapper:
+
+.. rubric:: Filtrado de atributos.
+
+Puede darse el caso de que no quiera almacenarse toda la información contenida
+en el modelo de datos. La solución general es crear |DTO|\ s, pero *Jackson*
+tiene algunas herramientas que nos permiten ahorrarnos la definición de estos
+objetos.
+
+En concreto, nos facilita dos herramientas: las **vistas**, que permiten hacer un
+filtrado estático basado en anotaciones, y los **filtros**, que permiten la
+definición de filtrados programáticos. Para ilustrarlas supongamos que tenemos
+más información referente a los alumnos:
+
+.. code-block:: java
+   :emphasize-lines: 4, 5
+
+   public class Alumno implements Serializable {
+      private String nombre;
+      private LocalDate fechaNacimiento;
+      private int telefono;
+      private String dni;
+
+      // Resto de la definición de la clase.
+   }
+
+Los datos de los alumnos no tienen la misma confidencialidad, así que nos podría
+interesar proporcionar más o menos información. Para ello se definen tres
+*vistas* de menor a mayor confidencialidad:
+
++ Views.Public
++ Views.Internal
++ Views.Admin
+
+Al anotar la clase podemos indicar a qué vista queremos que pertenezca el
+atributo:
+
+.. code-block:: java
+   :emphasize-lines: 2, 8, 11
+
+   public class Alumno implements Serializable {
+      @JsonView(Views.Public.class)
+      private String nombre;
+
+      // No pertenece a ninguna vista así que se muestra siempre.
+      private LocalDate fechaNacimiento;
+
+      @JsonView(Views.Internal.class)
+      private int telefono;
+
+      @JsonView(Views.Admin.class)
+      private String dni;
+   }
+
+Definida la *vista* de cada atributo, en el momento de serializar podemos
+indicar al objeto |ObjectWriter| qué vista debe escribir. En nuestro ejemplo:
+
++ Sin vista, sólo se serializará sólo ``fechaNacimiento``.
++ Con Views.Public se serializará ``fechaNacimiento`` y ``nombre``.
++ Con Views.Internal se añadirá a las anteriores el teléfono.
++ Con Views.Admin se serializarán todos los atributos.
+
+Para escribir con vistas, simplemente, debemos crear un *writer* y ajustar la
+vista:
+
+.. code-block:: java
+   :emphasize-lines: 2
+
+   ObjectWriter writer = mapper.writer()
+      .withWithView(Views.Public.class);
+
+   writer.writeValueAsString(grupos);
+
+El otro mecanismo para filtrar atributos es usar **filtros**:
+
+.. code-block:: java
+   :emphasize-lines: 1-3, 7
+
+   FilterProvider filters = new SimpleFilterProvider()
+      .addFilters("filtro",
+         SimpleBeanPropertyFilter.serializeAllExcept("telefono", "dni"));
+
+   // También existe .filterOutAllExcept
+
+   ObjectWriter writer = mapper.writer(filters);
+   writer.writeAsValueAsString(grupos);
+
+
 .. rubric:: Notas al pie
 
 .. [#] Siempre que el tipo, claro está, sea un primitivo de |JSON| (p. ej. una
@@ -504,6 +630,7 @@ anotación individual en cada uno de los atributos y hacer lo siguiente:
 .. |LocalDate| replace:: :java-time:`LocalDate <LocalDate>`
 .. |XML| replace:: :abbr:`XML (eXtensible Markup Language)`
 .. |YAML| replace:: :abbr:`YAML (YAML Ain't Markup Language)`
+.. |DTO| replace:: :abbr:`DTO (Data Transfer Object)`
 
 .. |JsonMapper| replace:: :jackson-databind:`JsonMapper <json/JsonMapper>`
 .. |JsonFactory| replace:: :jackson-core:`JsonFactory <json/JsonFactory>`
@@ -517,4 +644,4 @@ anotación individual en cada uno de los atributos y hacer lo siguiente:
 .. |Alumno| replace:: :ref:`Alumno <class-alumno>`
 .. |LocalDateSerializer| replace:: :jackson-databind:`LocalDateSerializer <ext/javatime/ser/LocalDateSerializer>`
 .. |LocalDateDeserializer| replace:: :jackson-databind:`LocalDateDeserializer <ext/javatime/deser/LocalDateDeserializer>`
-
+.. |ObjectWriter| replace:: :jackson-databind:`ObjectWriter <ObjectWriter>`
diff --git a/source/03.xml/02.jackson.rst b/source/03.xml/02.jackson.rst
@@ -206,19 +206,39 @@ Otra gran diferencia respecto a la traducción a |JSON| es que en |XML| nos hemo
 visto obligados a crear un elemento contenedor de la secuencia llamado
 ``<centro>``. No contiene más información que la propia secuencia, por lo que en
 el modelo de datos no se traduce en una nueva clase. En *Java*, simplemente,
-existirá un dato de tipo ``Grupo[]`` o ``List<Grupo>``.
+existirá un dato de tipo ``Grupo[]`` o ``List<Grupo>``. Si intentáramos traducir
+directamente estos tipos de datos a |XML|, la librería no nos permitiría definir
+el nombre de la etiqueta para el envoltorio (queremos que sea ``<centro>``) ni
+tampoco qué etiqueta tendría cada uno de los elementos de la secuencia (utiliza
+el predeterminado ``<item>``) por lo que obtendríamos una salida semejante a
+esta:
 
-Por eso, para poder hacer la traducción a |XML| necesitamos añadir una clase
-envoltorio auxiliar:
+.. code-block:: xml
+
+   <List1> <!-- O alguna etiqueta semejante -->
+      <item nivel="1" etapa="2" grupo="D">
+         <!-- Elementos del grupo (nombrados correctamente) -->
+      </item>
+
+      <!-- Otro grupos con la etiqueta item -->
+   </List1>
+
+Para solucionar esto tenemos dos soluciones:
+
+.. rubric:: Clase envoltorio auxiliar
 
 .. code-block:: java
    :emphasize-lines: 1, 3, 4
 
    @JsonRootName("centro")
-   private class GrupoWrapper {
+   private class GruposWrapper {
       @JacksonXmlElementWrapper(useWrapping = false)
       @JacksonXmlProperty(localName = "grupo")
-      private Grupo[] grupos;
+      public Grupo[] grupos;
+
+      public GruposWrapper(Grupo[] grupos) {
+         this.grupos = grupos;
+      }
    }
 
 Las particularidades de este código son las siguientes:
@@ -233,6 +253,37 @@ Las particularidades de este código son las siguientes:
 + El nombre del elemento es ``<grupo>``, no ``<grupos>``, así que es necesaria
   también la anotación ``@JacksonXmlProperty``.
 
+Una vez definida la clase, basta con que sea una instancia de ella la que se
+escriba (o lea):
+
+.. code-block:: java
+
+   // Escritura
+   mapper.writeValue(new GruposWrapper(grupos));
+   // Lectura
+
+   Grupo[] grupos = mapper.readValue(st, GruposWrapper.class).grupos;
+
+.. rubric:: Mapa envoltorio
+
+Consiste en improvisar un mapa con una única clave que sea el nombre que
+queremos darle a los elementos de la secuencia:
+
+.. code-block:: java
+   :emphasize-lines: 1, 4
+
+   Map<String, Object> centro = Map.of("grupo", grupos);  // Se usará <grupo>, no <item>
+
+   ObjectWriter writer = mapper.writer()
+      .withRootName("centro");   // Indicamos que se use <centro>, no <Map1>
+
+
+   // Escritura
+   writer.writeValues(st, centro);
+
+   // Lectura (no tiene dificultad)
+   mapper.readValues(st, Grupo[].class);
+
 Traductores
 -----------
 En principio, como en el caso de |JSON| necesitamos el traductor para ``Etapa``.
@@ -273,7 +324,7 @@ igual que :ref:`la escritura en el caso de JSON <json-jackson-write>`:
 
 .. code-block:: java
 
-   Path archivo = Path.of(System.getProperty("java.io.tmpdir"), "claustro.xml");
+   Path archivo = Path.of(System.getProperty("java.io.tmpdir"), "grupos.xml");
 
    Grupo[] grupos = new Grupo[] {
       new Grupo(1, Etapa.ESO, 'A', New Tutor("Florencio Vázquez Méndez", "Inglés"), {
@@ -292,13 +343,12 @@ igual que :ref:`la escritura en el caso de JSON <json-jackson-write>`:
 
    MapperBuilder<?, ?> builder = XmlMapper.builder(factory)
       .enable(SerializationFeature.INDENT_OUTPUT)
-      .addMixIn(Claustro.class, ClaustroMixin.class)
-      .addMixIn(Profesor.class, ProfesorMixin.class);
+      .addMixIn(Grupo.class, GrupoMixin.class);
 
    ObjectMapper mapper = builder.build();
 
    try (OutputStream st = Files.newOutputStream(archivo)) {
-       mapper.writeValue(st, claustro);  // Puede generar JacksonException
+       mapper.writeValue(st, new GruposWrapper(grupos));  // Puede generar JacksonException
    } catch(JacksonException | IOException err) {
        err.printStackTrace();
    }
@@ -309,7 +359,7 @@ También podríamos haber generado una cadena con la salida:
 .. code-block:: java
 
    try {
-       String contenido = mapper.writeValueAsString(claustro);
+       String contenido = mapper.writeValueAsString(new GruposWrapper(grupos));
        System.out.println(contenido);
    } catch(JacksonException err) {
        err.printStackTrace();
@@ -332,17 +382,16 @@ lectura del formato es :ref:`prácticamente la misma que para JSON <json-jackson
 
 .. code-block:: java
 
-   Path archivo = Path.of(System.getProperty("user.home"), "claustro.xml");
+   Path archivo = Path.of(System.getProperty("user.home"), "grupos.xml");
    
    MapperBuilder<?, ?> builder = XmlFactory.builder()
-      .addMixIn(Claustro.class, ClaustroMixin.class)
-      .addMixIn(Profesor.class, ProfesorMixin.class);
+      .addMixIn(Grupo.class, GrupoMixin.class)
 
    ObjectMapper mapper = builder.build();
 
    try (InputStream st = Files.newInputStream(ruta)) {
-      Claustro claustro = mapper.readValue(st, Claustro.class);
-      System.out.println(claustro);
+      Grupos[] grupos = mapper.readValue(st, GruposWrapper.class).grupos;
+      System.out.println(grupos);
    } catch(JacksonIOException | IOException err) {
       err.printStackTrace();
    }
