Pequeños cambios en la exposición de JAXP

Author: sio2sio2

source/02.formatos/02.json/01.jackson.rst

@@ -72,12 +72,13 @@ en genéricos debemos recurrir a |TypeReference|:
 
 .. code-block:: java
 
-   TypeReference<List<Grupo>> GrupoLista =  new TypeReference<>(){};
-   List<Grupo> grupos = mapper.readValue(sr, GrupoLista);
+   List<Grupo> grupos = mapper.readValue(sr, new TypeReference<List<Grupo>>(){});
 
-.. note:: Cuando los atributos de clases incluidas en la traducción
-   son secuencias, es indiferente que sea listas o *arrays*: la traducción
-   se lleva a cabo de igual forma. En nuestro ejemplo, es el caso del atributo
+.. note:: Este forma particular de tratar a la secuencia se produce cuando
+   es la propia secuencia la raiz del archivo. Si las secuencias son valores de
+   propiedades incluidas en el |JSON| es irrelevante que en las clases definamos
+   el atributo correspondiente como un |List| o un ``Array``: la traducción se
+   llevará a cabo de igual forma. En nuestro ejemplo, es el caso del atributo
    ``miembros`` de :ref:`Grupo <class-grupo>`, que lo hemos definido como un
    *array*, pero podría perfectamente ser una lista.
 
@@ -688,3 +689,5 @@ El otro mecanismo para filtrar atributos es usar **filtros**:
 .. |LocalDateDeserializer| replace:: :jackson-databind:`LocalDateDeserializer <ext/javatime/deser/LocalDateDeserializer>`
 .. |ObjectWriter| replace:: :jackson-databind:`ObjectWriter <ObjectWriter>`
 .. |TypeReference| replace:: :jackson-core:`TypeReference <type/TypeReference>`
+.. |List| replace:: :java-util:`List <List>`
+

source/03.xml/01.jaxp.rst

@@ -168,117 +168,6 @@ ejemplo, |Element|:
    devuelve el atributo (|Attr|) o el valor del atributo cuyo nombre se
    proporciona en el argumento.
 
-.. _jaxp-dtd:
-
-.. rubric:: Validación
-
-Hemos evitado validar el documento hasta ahora. Sin embargo, la validación puede
-ser interesante o incluso, puede ser preciso, intentar que ni siquiera se haga
-ninguna comprobación en caso de que la declaración exista, pero el |DTD| no.
-
-En primer lugar, si queremos que la validación se lleve a cabo debemos añadir:
-
-.. code-block:: java
-
-   factory.setValidating(true);
-
-Otro aspecto importante es el de la manipulación de la validación, que se lleva
-a cabo definiendo un *resolutor de entidades*.
-
-.. code-block:: java
-   :emphasize-lines: 1,3,4,9,10,15,16
-
-    builder.setEntityResolver(new EntityResolver2() {
-        @Override
-        public InputSource getExternalSubset(String name, String baseURI)
-                throws SAXException, IOException {
-            return null;
-        }
-
-        @Override
-        public InputSource resolveEntity(String publicId, String systemId)
-                throws SAXException, IOException {
-            return resolveEntity(null, publicId, null, systemId);
-        }
-
-        @Override
-        public InputSource resolveEntity(String name, String publicId, String baseURI, String systemId)
-                throws SAXException, IOException {
-
-            if (systemId == null) return null;
-
-            try {
-                systemId = resolvePath(baseURI, systemId);
-            } catch(URISyntaxException e) {
-                return null;
-            }
-            
-            return new InputSource(systemId);
-        }
-
-        private String resolvePath(String base, String path) throws URISyntaxException {
-            if(new URI(path).isAbsolute()) return path;
-            if(base == null) throw new IllegalArgumentException("No puede calcularse una ruta relativa si la base es nula.");
-
-            if(base.contains("!")) {
-                // Nos quedamos con la parte del path dentro del jar
-                Path basePath = Path.of(base.substring(base.indexOf("!") + 1));
-                // Resolvemos el path relativo y devolvemos el recurso.
-                 URL resource = getClass().getResource(basePath.resolveSibling(path).toString());
-                return resource != null ? resource.toString() : null;
-            }
-
-            return new URI(base).resolve(path).toString();
-        }
-
-    });
-
-Debemos fijarnos en el último método. Cuando devuelve `null`, es como, si no
-hubiéramos definido nada, y el procesador obrará como lo hace habitualmente para
-llevar a cabo la validación. En cambio, si devolvemos un :code:`new
-InputSource(cadena)` utilizará el |DTD| que indique esa cadena (puede ser una
-|URL| o un archivo local) con independencia de lo que expresase la declaración
-original.
-
-.. admonition:: Advertencia
-
-   Este código da por hecho que se conoce la ruta del |XML| (``baseURI``). Esto,
-   sin embargo, puede ser cierto o no. Todo este procesamiento lo desencadena
-   :code:`builder.parse()`, el cual permite proporcionar los datos de distinto
-   modo. Puede pasarse un |String| o un |File| en cuyo caso
-   sí se sabrá ``baseURI``. En cambio, si se pasa un |InputStream| (que es
-   *precisamente la forma en la que hemos ilustrado el uso*) no hay modo de
-   conocer su valor y, en consencuencia, será ``null``. Eso sí, en este último
-   caso, se admite un segundo argumento con una cadena que defina ``baseURI``.
-
-¿Qué hace exactamente el código que hemos propuesto? En principio, si
-no hay definido ningun |DTD|, no hace nada. En cambio, si hay definido uno,
-comprueba si el |DTD| se proporciona con ruta absoluta. Si es así, respeta el
-valor y la validación se hará con el valor expresado en el archivo. En cambio,
-si la ruta es relativa, hace una distinción:
-
-* Si ``baseURI`` contiene el carácter ``!`` se ha pasado como |XML| un
-  :ref:`archivo de recursos <file-arc-pro>` y en consecuencia el |DTD| también
-  lo será y hay que buscarlo dentro del paquete |JAR|.
-
-* Si no es así, se resuelve de forma normal la ruta relativa usando como base el
-  |XML| (``baseURI``).
-
-.. tip:: El argumento del constructor de `InputSource` también puede ser un
-   :java-io:`Reader <Reader>`, así que si nuestra intención es que el programa no
-   escupa nunca un error (incluso aunque el |DTD| de la declaración no se
-   encuentre), podemos hacer hacer lo siguiente:
-
-   .. code-block:: java
-
-      @Override
-      public InputSource resolveEntity(String name, String publicID, String baseURI, String systemID)
-          throws SAXException, IOException {
-              return new InputSource(new StringReader(""));
-      }
-
-.. todo:: ¿Cómo forzar una validación, aunque no haya declaración DOCTYPE?
-
 .. _jaxp-write:
 
 Escritura
@@ -391,6 +280,82 @@ si nuestra intención es usarla una sola vez:
    int cantidad = ((Double) xPath.evaluate("count(//profesor)", xml, XPathConstants.NUMBER)).intValue();
    System.out.println(cantidad);
 
+.. _jaxp-dtd:
+
+Validación
+==========
+Hemos evitado validar el documento hasta ahora. Sin embargo, la validación puede
+ser interesante o incluso, puede ser preciso, intentar que ni siquiera se haga
+ninguna comprobación en caso de que la declaración exista, pero el |DTD| no.
+
+En primer lugar, si queremos que la validación se lleve a cabo debemos añadir:
+
+.. code-block:: java
+
+   factory.setValidating(true);
+
+Otro aspecto importante es el de la manipulación de la validación, que se lleva
+a cabo definiendo un *resolutor de entidades*:
+
+.. literalinclude:: files/MiEntityResolver.java
+   :language: java
+   :caption: MiEntityResolver.java
+   :class: toggle
+   :start-at: public class
+
+Debemos fijarnos en el último método. Cuando devuelve `null`, es como, si no
+hubiéramos definido nada, y el procesador obrará como lo hace habitualmente para
+llevar a cabo la validación. En cambio, si devolvemos un :code:`new
+InputSource(cadena)` utilizará el |DTD| que indique esa cadena (puede ser una
+|URL| o un archivo local) con independencia de lo que expresase la declaración
+original.
+
+Definido, podremos usarlo en el *builder* antes de procesar el documento:
+
+.. code-block:: java
+
+   builder.setEntityResolver(new MiEntityResolver());
+   Document xml = builder.parse(st);
+
+.. admonition:: Advertencia
+
+   Este código da por hecho que se conoce la ruta del |XML| (``baseURI``). Esto,
+   sin embargo, puede ser cierto o no. Todo este procesamiento lo desencadena
+   :code:`builder.parse()`, el cual permite proporcionar los datos de distinto
+   modo. Puede pasarse un |String| o un |File| en cuyo caso
+   sí se sabrá ``baseURI``. En cambio, si se pasa un |InputStream| (que es
+   *precisamente la forma en la que hemos ilustrado el uso*) no hay modo de
+   conocer su valor y, en consencuencia, será ``null``. Eso sí, en este último
+   caso, se admite un segundo argumento con una cadena que defina ``baseURI``.
+
+¿Qué hace exactamente el código que hemos propuesto? En principio, si
+no hay definido ningun |DTD|, no hace nada. En cambio, si hay definido uno,
+comprueba si el |DTD| se proporciona con ruta absoluta. Si es así, respeta el
+valor y la validación se hará con el valor expresado en el archivo. En cambio,
+si la ruta es relativa, hace una distinción:
+
+* Si ``baseURI`` contiene el carácter ``!`` se ha pasado como |XML| un
+  :ref:`archivo de recursos <file-arc-pro>` y en consecuencia el |DTD| también
+  lo será y hay que buscarlo dentro del paquete |JAR|.
+
+* Si no es así, se resuelve de forma normal la ruta relativa usando como base el
+  |XML| (``baseURI``).
+
+.. tip:: El argumento del constructor de `InputSource` también puede ser un
+   :java-io:`Reader <Reader>`, así que si nuestra intención es que el programa no
+   escupa nunca un error (incluso aunque el |DTD| de la declaración no se
+   encuentre), podemos hacer hacer lo siguiente:
+
+   .. code-block:: java
+
+      @Override
+      public InputSource resolveEntity(String name, String publicID, String baseURI, String systemID)
+          throws SAXException, IOException {
+              return new InputSource(new StringReader(""));
+      }
+
+.. todo:: ¿Cómo forzar una validación, aunque no haya declaración DOCTYPE?
+
 .. rubric:: Notas al pie
 
 .. [#] En realidad el método tiene sentido para otros nodos que no sean

source/03.xml/files/MiEntityResolver.java

@@ -0,0 +1,53 @@
+import java.io.IOException;
+import java.net.URI;
+import java.net.URISyntaxException;
+import java.net.URL;
+import java.nio.file.Path;
+
+import org.xml.sax.InputSource;
+import org.xml.sax.SAXException;
+import org.xml.sax.ext.EntityResolver2;
+
+public class MiEntityResolver implements EntityResolver2 {
+    @Override
+    public InputSource getExternalSubset(String name, String baseURI)
+            throws SAXException, IOException {
+        return null;
+    }
+
+    @Override
+    public InputSource resolveEntity(String publicId, String systemId)
+            throws SAXException, IOException {
+        return resolveEntity(null, publicId, null, systemId);
+    }
+
+    @Override
+    public InputSource resolveEntity(String name, String publicId, String baseURI, String systemId)
+            throws SAXException, IOException {
+
+        if (systemId == null) return null;
+
+        try {
+            systemId = resolvePath(baseURI, systemId);
+        } catch(URISyntaxException e) {
+            return null;
+        }
+        
+        return new InputSource(systemId);
+    }
+
+    private String resolvePath(String base, String path) throws URISyntaxException {
+        if(new URI(path).isAbsolute()) return path;
+        if(base == null) throw new IllegalArgumentException("No puede calcularse una ruta relativa si la base es nula.");
+
+        if(base.contains("!")) {
+            // Nos quedamos con la parte del path dentro del jar
+            Path basePath = Path.of(base.substring(base.indexOf("!") + 1));
+            // Resolvemos el path relativo y devolvemos el recurso.
+            URL resource = getClass().getResource(basePath.resolveSibling(path).toString());
+            return resource != null ? resource.toString() : null;
+        }
+
+        return new URI(base).resolve(path).toString();
+    }
+}

source/04.conector/01.basico.rst

@@ -10,7 +10,7 @@ Lo primero que debemos aprender es cómo abrir una conexión a la base de datos:
 .. code-block:: java
    :emphasize-lines: 1, 5, 11
 
-   final String protocol = "jdbc:sqlite:";
+   final String dbProtocol = "jdbc:sqlite:";
 
    // Las bases de datos de SQLite son archivos.
    Path dbPath = Path.of(System.getProperty("java.io.tmpdir"), "test.db");
@@ -69,7 +69,7 @@ Por supuesto, el código es *completamente inútil*: nos hemos conectado a la ba
 de datos para no hacer absolutamente nada. En los siguientes apartados veremos
 como leer y escribir datos.
 
-.. seealso:: La conexión a una base de datos es una operación costosa, por lo
+.. seealso:: La conexión a una base de datos es una **operación costosa**, por lo
    que, si la aplicación abre y cierra constantemente conexiones, el rendimiento
    se penalizará. Para optimizarlo reaprovechando conexiones, existen los
    :ref:`pools de conexiones <conn-pool>`.
@@ -288,7 +288,7 @@ identificador se definió. Para ello podemos hacer lo siguiente:
 .. code-block:: java
    :emphasize-lines: 11, 20-22
 
-   TimeDateFormatter df = TimeDateFormatter.ofPattern("dd/MM/yyyy");
+   DateTimeFormatter df = DateTimeFormatter.ofPattern("dd/MM/yyyy");
    // centro es un centro que ya tenemos definido.
    Profesor[] profesores = new Profesor[] {
       new Profesor ("Perico de los Palotes", LocalDate.parse("12/06/1995", df), centro),
@@ -357,14 +357,6 @@ a. El driver debe inferir el tipo |SQL| a partir del tipo de *Java*: eso
 
 .. rubric:: Notas al pie
 
-.. [#] Según el estándar, un nombre que no se encierra entre comillas dobles, se
-   sobreentiende escrito todo en mayúsculas. En particular, :program:`SQLite` se
-   salta el estándar en este aspecto y no hace esa distinción, incluso aunque
-   los nombres sí se hayan entrecomillado. Otra razón que avala el que no
-   entrecomillemos es que :program:`MariaDB`/:program:`MySQL` exige que
-   cambiemos la configuración predeterminada para soportar el entrecomillado con
-   comillas dobles, ya que este |SGBD| entrecomilla con el acento grave.
-
 .. [#] En las versiones modernas de |JDBC| no es necesario expresar el nombre
    del driver, ya que dispone de mecanismos parar inferir cuál es el driver
    adecuado a partir de la |URL| de conexión. En cambio, más adelante, al
@@ -381,15 +373,27 @@ a. El driver debe inferir el tipo |SQL| a partir del tipo de *Java*: eso
    primarias en las tablas ``Claustro``, ``Departamento`` y ``Profesor``.
    Nuestra intención es que sus identificadores se generen automáticamente sin
    necesidad de que especifiquemos un valor. Eso se hace en SQLite_ con
-   *AUTOINCREMENT*, pero en otros motores se expresa de otro modo, ya que no
-   forma parte del estándar. Desde |SQL|\ :2003, existe un modo de expresarlo:
-   :code:`GENERATED [BY DEFAULT|ALWAYS] AS IDENTITY`. Sin embargo, SQLite_ no lo
-   soporta y por eso lo hemos dejado comentado. En cambio, tiene un comportamento
-   curioso: cuando se usa ``INTEGER`` para definir la clave primaria asume el
-   comportamento de :code:`GENERATED BY DEFAULT AS IDENTITY` y cuando se usa
-   ``INT`` la clave no se genera y hay que especificarla siempre explícitamente
-   (o sea, el comportamiento que esperaríamos al no haber incluido ninguna
-   fórmula adicional como :code:`AUTOINCREMENT` o :code:`GENERATED BY...`).
+   *AUTOINCREMENT* (aunque es conveniente leer `las aclaraciones al respecto
+   <https://sqlite.org/autoinc.html>`_), pero en otros motores se expresa de
+   otro modo, ya que no forma parte del estándar. Desde |SQL|\ :2003, existe un
+   modo de expresarlo: :code:`GENERATED [BY DEFAULT|ALWAYS] AS IDENTITY`: ambas
+   fórmulas generan un identificar único automáticamente, pero la primera
+   permite la inserción manual de valores, mientras que la segunda, no. Sin
+   embargo, SQLite_ no lo soporta y por eso lo hemos dejado comentado. En
+   cambio, tiene un comportamento curioso: cuando se usa ``INTEGER`` para
+   definir la clave primaria asume el comportamento de :code:`GENERATED BY
+   DEFAULT AS IDENTITY` y cuando se usa ``INT`` la clave no se genera y hay que
+   especificarla siempre explícitamente (o sea, el comportamiento que
+   esperaríamos al no haber incluido ninguna fórmula adicional como
+   :code:`AUTOINCREMENT` o :code:`GENERATED BY...`).
+
+.. [#] Según el estándar, un nombre que no se encierra entre comillas dobles, se
+   sobreentiende escrito todo en mayúsculas. En particular, :program:`SQLite` se
+   salta el estándar en este aspecto y no hace esa distinción, incluso aunque
+   los nombres sí se hayan entrecomillado. Otra razón que avala el que no
+   entrecomillemos es que :program:`MariaDB`/:program:`MySQL` exige que
+   cambiemos la configuración predeterminada para soportar el entrecomillado con
+   comillas dobles, ya que este |SGBD| entrecomilla con el acento grave.
 
 .. |SQL| replace:: :abbr:`SQL (Structured Query Language)`
 .. |URL| replace:: :abbr:`URL (Uniform Resource Locator)`