Añade mapeo con XML (JPA)

sio2sio2 · sio2sio2 · commit 470c08026d7f · 2025-09-13T23:16:03.000+02:00
diff --git a/source/05.orm/04.mapeo.rst b/source/05.orm/04.mapeo.rst
@@ -15,6 +15,12 @@ Fundamentalmente sirven para:
 - Establecer restricciones sobre los valores.
 - Definir relaciones entre tablas.
 
+.. seealso:: Bajo este epígrafe se verá cómo definir el mapeo mediante
+   anotaciones. Hay otra estrategia que consiste en un utilizar archivos |XML|
+   aparte. Se tratará más adelante en :ref:`mapeo mediante configuración
+   <xml-orm-mapping>`.
+
+
 .. _orm-mapping-bas:
 
 Anotaciones básicas
@@ -23,6 +29,8 @@ Ya introdujimos las anotaciones más básicas al presentar el :ref:`ejemplo de
 anotación de la clase Centro <orm-bas-map>`:
 
 .. literalinclude:: files/Centro.java
+   :class: toggle
+   :caption: Clase Centro
    :language: java
    :start-at: @Entity
 
@@ -257,6 +265,7 @@ equivalente al ``CHECK`` de |SQL|), que requieren importar la librería
    private int cantidad
 
    @Positive
+   @NotNull
    private BigDecimal precio;
 
    @Min(value = 18, message = "La entrada está vetada a menores de edad")
@@ -267,6 +276,16 @@ equivalente al ``CHECK`` de |SQL|), que requieren importar la librería
 
 .. note:: \"*message*\" permite personalizar el mensaje de error.
 
+.. note:: ``@NotNull`` impide que el valor sea nulo a nivel de aplicación,
+   mientras que el atributo ``nullable`` de ``@Column`` define la restrucción en
+   la definición del esquema (a nivel de base de datos).
+
+.. note:: Aunque hemos relacionado estas restricciones con el ``CHECK`` de
+   |SQL|, la validación que nos ofrece |JPA| no se basa en usarlo (o sea, en
+   incluir en la definición de las tablas las cláusulas ``CHECK``
+   apropiadas), sino en que la propia aplicación de Java haga las comprobaciones
+   antes de aceptar el valor del atributo.
+
 Relaciones
 ==========
 Las relaciones entre las entidades también se significan mediante anotaciones.
@@ -289,6 +308,8 @@ Hay tres tipos de relaciones binarias en el modelo relacional:
       clase ``Estudiante``:
 
       .. literalinclude:: files/Estudiante.java
+         :class: toggle
+         :caption: Clase Estudiante
          :language: java
          :start-at: @Entity
          :emphasize-lines: 13-15, 56-62
@@ -442,4 +463,5 @@ Hay tres tipos de relaciones binarias en el modelo relacional:
 .. |JPA| replace:: :abbr:`JPA (Java Persisten API)`
 .. |SQL| replace:: :abbr:`SQL (Structured Query Language)`
 .. |ORM| replace:: :abbr:`ORM (Object-Relational Mapping)`
+.. |XML| replace:: :abbr:`XML (eXtensible Markup Language)`
 .. _Hibernate: https://www.hibernate.org
diff --git a/source/05.orm/15.extra.rst b/source/05.orm/15.extra.rst
@@ -103,7 +103,7 @@ se encargará de propagar la operación en cascada.
 
 .. caution:: En SQLite la integridad referencial está deshabilitada por defecto.
 
-.. rubric:: Hibernate
+.. rubric:: |JPA|
 
 .. caution:: Por lo general, las operaciones en cascada se definen de padre a
    hijo cuando las relaciones son bidireccionales. Cuando las relaciones son
@@ -353,9 +353,130 @@ Tanto en |JPQL| como en *Criteria API*, los *JOIN* a secas respetan este
 comportamiento derivado de las anotaciones, mientras que los *FETCH JOIN*
 fuerzan siempre la carga inmediata.
 
+.. _xml-orm-mapping:
+
+Mapeo mediante archivos
+=======================
+Aunque, como ya hemos visto, el mapeo puede realizarse mediante :ref:`anotaciones al
+propio código de las clases del modelo <orm-mapping>`, también es posible no
+añadir las anotaciones al código Java y crear archivos |XML| aparte que
+sustituyan por completo a estas anotaciones. Para entender cómo crear estos
+archivos es indispensable que entendamos que las anotaciones eran de dos
+naturalezas distintas:
+
+* Las que definían propiamente el esquema (como ``@Id`` o ``@Colum``).
+* Las que incorporaban restricciones a los valores (como ``@Positive``).
+
+En los archivos ambas deben realizarse por separado, así que las trataremos bajo
+epígrafes distintos:
+
+Definición del esquema
+----------------------
+Antes de crear el archivo para *definir el esquema* debemos indicar en la
+configuración de la unidad de persistencia definida en
+:file:`META-INF/persistence.xml` cuál será tal archivo:
+
+.. code-block:: xml
+
+   <persistenceo-unit name="MiUnidadP" transaction-type="RESOURCE_LOCAL">
+      <!-- Pueden definirse varios <mapping-file> -->
+      <mapping-file>META-INF/schema.xml</mapping-file>
+
+      <!-- ... -->
+
+      <!-- Es bastante probable que no necesitemos declarar las clases con <class> -->
+
+   </presistence-unit>
+
+Hecho lo cual, podemos definir :file:`META-INF/schema.xml` con la definición del
+esquema:
+
+.. literalinclude:: files/schema.xml
+   :class: toggle
+   :caption: Definición del esquema SQL
+   :language: xml
+
+En el archivo se ha definido una relación *unidirección*. Podríamos hacerla
+*bidireccional* descomentando las líneas correspondientes en la definición de la
+entidad padre (aunque deberíamos haber definido el atributo ``estudiantes`` en
+la clase ``Centro``).
+
+Definición de restricciones
+---------------------------
+Para definir restricciones **a nivel de aplicación** debemos escribir el archivo
+``META-INF/validation``:
+
+.. code-block:: xml
+   :emphasize-lines: 9
+
+   <?xml version="1.0" encoding="UTF-8"?>
+   <validation-config
+       xmlns="http://xmlns.jcp.org/xml/ns/validation/configuration"
+       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+       xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/validation/configuration
+           http://xmlns.jcp.org/xml/ns/validation/validation-configuration-2.0.xsd"
+       version="2.0">
+
+       <!-- Podemos añadir más elementos <constraint-mapping> para repartir
+            la configuración en varios archivos. -->
+       <constraint-mapping>META-INF/constraints.xml</constraint-mapping>
+   </validation-config>
+   
+Los archivos donde propiamente se definen las restricciones tienen esta pinta:
+
+.. code-block:: xml
+   :caption: Restricciones a nivel de aplicación
+   :class: toggle
+
+   <?xml version="1.0" encoding="UTF-8"?>
+   <constraint-mappings
+       xmlns="http://xmlns.jcp.org/xml/ns/validation/mapping"
+       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+       xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/validation/mapping
+           http://xmlns.jcp.org/xml/ns/validation/validation-mapping-2.0.xsd"
+       version="2.0">
+       <bean class="edu.acceso.ejemplo.modelo.Centro" ignore-annotations="true">
+           <field name="nombre">
+               <constraint annotation="jakarta.validation.constraints.NotNull">
+                   <message>El nombre no puede ser nulo</message>
+               </constraint>
+               <constraint annotation="jakarta.validation.constraints.Size">
+                   <message>El nombre debe tener entre 2 y 100 caracteres</message>
+                   <element name="min">2</element>
+                   <element name="max">100</element>
+               </constraint>
+           </field>
+           <field name="titularidad">
+               <constraint annotation="jakarta.validation.constraints.NotNull">
+                   <message>La titularidad debe estar definida</message>
+               </constraint>
+           </field>
+       </bean>
+
+       <bean class="edu.acceso.ejemplo.modelo.Estudiante" ignore-annotations="true">
+           <field name="nombre">
+               <constraint annotation="jakarta.validation.constraints.NotNull">
+                   <message>El nombre no puede ser nulo</message>
+               </constraint>
+           </field>
+           <field name="centro">
+               <constraint annotation="jakarta.validation.constraints.NotNull">
+                   <message>El centro no puede ser nulo</message>
+               </constraint>
+           </field>
+       </bean>
+   </constraint-mappings>
+
+Podemos definir otras restricciones:
+
+* ``jakarta.validation.constraints.Positive``
+* ``jakarta.validation.constraints.PositiveOrZero``
+* etc.
+
 .. |JPQL| replace:: :abbr:`JPQL (Java Persistence Query Language)`
 .. |SGBD| replace:: :abbr:`SGBD (Sistema Gestor de Bases de Datos)`
 .. |ORM| replace:: :abbr:`ORM (Object-Relational Mapping)`
 .. |JPA| replace:: :abbr:`JPA (Java Persistence API)`
 .. |SQL| replace:: :abbr:`SQL (Structured Query Language)`
+.. |XML| replace:: :abbr:`XML (eXtensible Markup Language)`
 .. _Hibernate: https://hibernate.org/
diff --git a/source/05.orm/files/JpaBackend.java b/source/05.orm/files/JpaBackend.java
@@ -12,11 +12,27 @@
 import jakarta.persistence.EntityTransaction;
 import jakarta.persistence.Persistence;
 
+/**
+ * Clase de utilidad para gestionar múltiples instancias de {@link EntityManagerFactory}.
+ * Permite crear instancias a partir del nombre de la unidad de persistencia y un mapa de propiedades,
+ * y recuperarlas posteriormente mediante un índice.
+ * También proporciona métodos para ejecutar transacciones de forma sencilla.
+ */
 public class JpaBackend {
 
+    /**
+     * Lista de claves hash que representan las instancias creadas.
+     * Se utiliza una lista para mantener el orden de creación y permitir la recuperación por índice.
+     */
     private static ArrayList<Integer> keys = new ArrayList<>();
+    /**
+     * Mapa que asocia las claves hash con las instancias de EntityManagerFactory.
+     */
     private static Map<Integer, EntityManagerFactory> instances = new HashMap<>();
 
+    /**
+     * Constructor privado para evitar instanciación.
+     */
     private JpaBackend() { super(); }
 
     /**
@@ -55,6 +71,12 @@ public static int createEntityManagerFactory(String persistenceUnit) {
         return createEntityManagerFactory(persistenceUnit, null);
     }
 
+    /**
+     * Devuelve un objeto EntityManagerFactory generado anteriormente.
+     * @param index El índice de la instancia a recuperar.
+     * @return La instancia de EntityManagerFactory correspondiente al índice.
+     * @throws IllegalArgumentException Si el índice está fuera de rango.
+     */
     public static EntityManagerFactory getEntityManagerFactory(int index) {
         if(index < 1 || index > keys.size()) throw new IllegalArgumentException("Índice fuera de rango");
 
@@ -71,6 +93,7 @@ public static EntityManagerFactory getEntityManagerFactory(int index) {
     /**
      * Devuelve un objeto EntityManagerFactory generado anteriormente. Sólo funciona si se generó uno.
      * @return El objeto resultante.
+     * @throws IllegalStateException Si no hay ninguna instancia o si hay varias.
      */
     public static EntityManagerFactory getEntityManagerFactory() {
         EntityManagerFactory instance = null;
@@ -99,6 +122,13 @@ public static void reset() {
     }
 
     // Transacciones.
+    /**
+     * Ejecuta una acción dentro de una transacción, devolviendo un resultado.
+     * @param <T> El tipo de resultado de la acción.
+     * @param index El índice de la instancia a utilizar.
+     * @param action La acción a ejecutar.
+     * @return El resultado de la acción.
+     */
     public static <T> T transactionR(Integer index, Function<EntityManager, T> action) {
         EntityManagerFactory emf = index != null?getEntityManagerFactory(index):getEntityManagerFactory();
         try(EntityManager em = emf.createEntityManager()) {
@@ -116,17 +146,32 @@ public static <T> T transactionR(Integer index, Function<EntityManager, T> actio
         }
     }
 
+    /**
+     * Versión sin índice de {@link #transactionR(Integer, Function)} para cuando sólo hay una instancia.
+     * @param <T> El tipo de resultado de la acción.
+     * @param action La acción a ejecutar.
+     * @return El resultado de la acción.
+     */
     public static <T> T transactionR(Function<EntityManager, T> action) {
         return transactionR(null, action);
     }
 
+    /**
+     * Ejecuta una acción dentro de una transacción, sin devolver resultado.
+     * @param index El índice de la instancia a utilizar.
+     * @param action La acción a ejecutar.
+     */
     public static void transaction(Integer index, Consumer<EntityManager> action) {
         transactionR(index, em -> {
             action.accept(em);
             return null;
         });
     }
 
+    /**
+     * Versión sin índice de {@link #transaction(Integer, Consumer)} para cuando sólo hay una instancia.
+     * @param action La acción a ejecutar.
+     */
     public static void transaction(Consumer<EntityManager> action) {
         transaction(null, action);
     }
diff --git a/source/05.orm/files/schema.xml b/source/05.orm/files/schema.xml
@@ -0,0 +1,51 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<entity-mappings version="2.2"
+    xmlns="http://xmlns.jcp.org/xml/ns/persistence/orm"
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/persistence/orm 
+        http://xmlns.jcp.org/xml/ns/persistence/orm_2_2.xsd">
+
+    <entity class="edu.acceso.ejemplo.modelo.Centro" access="FIELD">
+        <table name="Centro"/>
+        <attributes>
+            <id name="id">
+                <generated-value strategy="IDENTITY"/>
+            </id>
+            <basic name="nombre">
+               <!-- El atributo name permite que la columna en la BD se llame
+                    de distinta forma -->
+                <column name="nombre" nullable="false" length="255" />
+            </basic>
+            <basic name="titularidad">
+                <!-- El Enum se almacenará como un número -->
+                <enumerated>ORDINAL</enumerated>
+            </basic>
+            <!--
+            <one-to-many name="estudiantes" target-entity="educ.acceso.ejemplo.modelo.Estudiante" mapped-by="centro">
+               <cascade>
+                  <cascade-type>ALL</cascade-type>
+               <cascade>
+            </one-to-many>
+            -->
+        </attributes>
+    </entity>
+
+    <entity class="edu.acceso.ejemplo.modelo.Estudiante" access="FIELD">
+        <table name="Estudiante"/>
+        <attributes>
+            <id name="id">
+                <!-- o SEQUENCE si queremos que se genere automáticamente -->
+                <generated-value strategy="IDENTITY"/>
+            </id>
+            <basic name="nombre">
+                <column nullable="false" length="255"/>
+            </basic>
+            <basic name="nacimiento" />
+            <!-- Optional permite valores nulos para el atributo (datos en la aplicación) -->
+            <many-to-one name="centro" target-entity="edu.acceso.ejemplo.modelo.Centro" fetch="EAGER" optional="false">
+                <!-- nullable permite valores nulos en el esquema -->
+                <join-column nullable="false"/>
+            </many-to-one>
+        </attributes>
+    </entity>
+</entity-mappings>
diff --git a/source/98.apendices/files/arquetipo.zip b/source/98.apendices/files/arquetipo.zip
diff --git a/source/99.ejercicios/05.orm.rst b/source/99.ejercicios/05.orm.rst
@@ -12,15 +12,9 @@
 
    Debe resolver **dos** veces el ejercicio usando dos estrategias distintas:
 
-   a. Modifique el código del programa para acomodarse a la |API| de |JPA|.
-   #. Respete escrupulosamente el programa ya escrito y limítese a:
+   a. Libremente con |JPA|.
+   #. Respetando escrupulosamente el código con que lo resolvió en la unidad
+      anterior, es decir, mediante el patrón de diseño |DAO|.
 
-      i. Anotar las clases del modelo para que pueda interpretarlas el |ORM|.
-      #. Escriba la traducción entre la |API| que usó en el ejercicio citado y
-         la de |JPA|, a fin de que no haya que cambiar ninguna línea del
-         programa (salvo las importaciones, claro está).
-
-.. |JDBC| replace:: :abbr:`JDBC (Java DataBase Connectivity)`
 .. |JPA| replace:: :abbr:`JPA (Java Persistent API)`
-.. |API| replace:: :abbr:`API (Application Programming Interface)`
-.. |ORM| replace:: :abbr:`ORM (Object-Relational Mapping)`
+.. |DAO| replace:: :abbr:`DAO (Data Access Object)`
