11. Hibernate
Requisitos previos: la versión 7 de la aplicación [Tax], presentada al final de este capítulo, reutiliza los módulos [tax-dao], [tax-business] y [tax-ui] de la versión 5 (capítulo 6). Antes de compilar o abrir sus proyectos, debe haber instalado la versión 5 en el repositorio local de Maven mediante el comando [mvn install] ingresado en la carpeta [06-architectures/TaxV5] (consulte el capítulo 6, sección sobre [mvn install]).
El capítulo anterior mostró cómo una aplicación Java se comunica con una base de datos a través de un controlador JDBC: se abre una conexión, se emiten comandos SQL, se leen las filas del resultado columna por columna y se copian en objetos. Este proceso de copia —de filas a objetos y de objetos a los comandos [INSERT], [UPDATE] y [DELETE] — es repetitivo. Puede automatizarse mediante una herramienta: un “mapeador objeto-relacional” (ORM). Este capítulo presenta el ORM más utilizado en el mundo Java, Hibernate, y el estándar que implementa, Jakarta Persistence.
El capítulo retoma la base de datos de ejemplo de los artículos del capítulo 10 y concluye con la versión 7 de la aplicación de cálculo de impuestos, cuya capa ORM utiliza Hibernate.
11.1. ¿Qué es un ORM?
11.1.1. Objetos y tablas
Una aplicación Java trabaja con objetos: un artículo tiene un nombre, un precio y un nivel de stock; un pedido tiene un cliente y una lista de líneas, cada una de las cuales hace referencia a un artículo. Una base de datos relacional almacena esa misma información en tablas: una fila en la tabla [articles] por artículo, una fila en la tabla [orders] por pedido, con las relaciones entre filas expresadas mediante claves externas. Los dos mundos no encajan del todo:
- un objeto hace referencia directamente a otros objetos ([order.getClient()]); una fila contiene el valor de la clave primaria de otra fila ([client_id]);
- un objeto puede contener una colección ([order.getLines()]); una tabla solo contiene valores simples; la colección se representa mediante las filas de otra tabla que apuntan al pedido;
- los tipos Java ([String], [BigDecimal], [LocalDate], [boolean]) y los tipos SQL ([varchar(30)], [decimal(10,2)], [date], [bit]) no son los mismos;
- los objetos se consultan con Java (y la API de streams), mientras que las tablas se consultan con SQL.
Un ORM tiende un puente entre ambos mundos. Definimos la correspondencia entre clases y tablas (el modelo, o “mapeo”) una vez por todas; él se encarga entonces de:
- traducir las consultas escritas en un lenguaje que hace referencia a objetos (HQL) o construidas mediante código Java (la API Criteria);
- crear objetos a partir de las filas leídas (esto se denomina materialización);
- almacenar los objetos leídos y detectar los que han sido modificados, agregados o eliminados;
- generar los comandos [INSERT], [UPDATE], y [DELETE] que reflejan esos cambios en la base de datos;
- y, si es necesario, crear y actualizar el esquema de la base de datos (tablas, columnas, índices) a partir de las clases.
La arquitectura de una aplicación que usa Hibernate con MySQL es la siguiente:

- [1]: la aplicación. Su capa [dao] ya no se comunica directamente con el controlador JDBC, sino con Hibernate, mediante un objeto [Session] y consultas HQL;
- [2]: Hibernate, independiente del SGBD: modelo, traducción de consultas, seguimiento de cambios, generación del esquema;
- [3]: el dialecto propio del SGBD (aquí, [MySQLDialect]): conoce la sintaxis SQL del SGBD, sus tipos de columna y sus funciones. Los dialectos de los principales SGBD forman parte del propio Hibernate: no es necesario agregar nada al proyecto;
- [4]: el controlador JDBC del SGBD, el del capítulo 10 (MySQL Connector/J): Hibernate no reemplaza a JDBC; lo utiliza;
- [5]: el SGBD.
11.1.2. Jakarta Persistence y Hibernate
Hibernate fue creado en 2001 por Gavin King como respuesta a la complejidad de los “entity beans” de la plataforma Java EE de entonces. Su éxito fue tal que sus conceptos se incorporaron a un estándar, JPA (Java Persistence API), publicado en 2006 con Java EE 5. Cuando Java EE se transfirió a la Fundación Eclipse y se rebautizó Jakarta EE, JPA pasó a llamarse Jakarta Persistence, y sus paquetes cambiaron de [javax.persistence] a [jakarta.persistence] (versión 3.0, 2020). La versión actual es Jakarta Persistence 3.2 (2024).
Jakarta Persistence es una especificación: un conjunto de interfaces ([EntityManagerFactory], [EntityManager]...), anotaciones ([@Entity], [@Id], [@Column]...) y un lenguaje de consultas, JPQL. Es implementada por varios productos: Hibernate ORM (el más utilizado, empleado en Spring Boot y Quarkus), EclipseLink (la implementación de referencia)... Este curso utiliza Hibernate ORM 7.4.5, que implementa Jakarta Persistence 3.2.
Hibernate ofrece dos formas de utilizarlo:
- exclusivamente a través de las interfaces estándar: en este caso, el código depende únicamente de [jakarta.persistence], y en principio sería posible cambiar de implementación;
- a través de su propia API «nativa», más rica en funcionalidades, cuyas interfaces extienden las del estándar: un [SessionFactory] es un [EntityManagerFactory], y una [Session] es un [EntityManager].
Utilizamos la API propia de Hibernate, como recomienda su documentación: ofrece todos los métodos estándar ([persist], [find], [merge], [remove]...), así como las extensiones de Hibernate. Las anotaciones, sin embargo, son siempre las definidas por el estándar. La tabla siguiente muestra las correspondencias:
Jakarta Persistence | Hibernate | Rol |
[EntityManagerFactory] | [SessionFactory] | Configuración de Hibernate para una base de datos: un objeto pesado, creado una sola vez y compartido por toda la aplicación |
[EntityManager] | [Session] | Una sesión con la base de datos: un objeto ligero y de corta duración |
[EntityTransaction] | [Transaction] | una transacción |
JPQL | HQL | el lenguaje de consultas; HQL es un superconjunto de JPQL |
[CriteriaBuilder] | [HibernateCriteriaBuilder] | Construcción de consultas mediante código Java |
11.1.3. Bibliotecas
Las bibliotecas utilizadas en este capítulo son las siguientes (se resumen en el apéndice sobre las dependencias de Maven):
Dependencia de Maven | Rol |
[org.hibernate.orm:hibernate-core] 7.4.5.Final | Hibernate propiamente dicho; incluye la API de Jakarta Persistence 3.2 ([jakarta.persistence-api]) y sus propias dependencias (Byte Buddy para la generación de clases, ANTLR para el análisis de consultas, JBoss Logging para los registros, etc.) |
[com.mysql:mysql-connector-j] 9.7.0 | el controlador JDBC para MySQL, el del capítulo 10 |
[ch.qos.logback:logback-classic] 1.5.38 | Logback, que recibirá el registro de Hibernate |
Hibernate escribe su registro (comandos SQL ejecutados, advertencias, etc.) a través de JBoss Logging, una pequeña biblioteca que simplemente reenvía los mensajes al sistema de registro que encuentra en el classpath: Log4j 2, o Logback (mediante SLF4J) o, en su defecto, el del JDK o [java.util.logging]. Sin configuración, este último muestra cada mensaje en dos líneas, en rojo en la mayoría de las consolas, lo que dificulta la lectura de la salida del programa. Por eso agregamos Logback a nuestros proyectos y lo configuramos mediante un archivo [logback.xml].
11.1.4. Code first o Database first
El modelo (la correspondencia entre clases y tablas) puede construirse de dos maneras:
- code-first: escribimos las clases Java y Hibernate deriva de ellas el esquema de la base de datos, que puede crear por sí mismo. Este es el enfoque adoptado en este capítulo;
- database-first: la base de datos ya existe y se generan las clases a partir de su esquema con las herramientas de ingeniería inversa de Hibernate (Hibernate Tools) o las de los entornos de desarrollo (IntelliJ IDEA puede generar entidades a partir de las tablas de una base de datos). Es el enfoque para las aplicaciones que deben trabajar con una base de datos existente. El código generado es similar al que escribiríamos a mano.
11.2. Un primer ejemplo
11.2.1. El proyecto
Los ejemplos de este capítulo son módulos de un proyecto Maven de varios módulos (véase el capítulo 6), ubicado en la carpeta [11-hibernate]:
El proyecto padre fija las versiones de las bibliotecas y de las extensiones de Maven para todos los módulos:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 | |
- líneas 14–30: los módulos, en el orden en que Maven debe construirlos: primero las dos bibliotecas compartidas;
- líneas 38–87: la sección [dependencyManagement] especifica la versión de cada biblioteca. Un módulo que la necesita la referencia sin indicar versión;
- líneas 108–116: la extensión [exec-maven-plugin] ejecutará la clase especificada por la propiedad [exec.mainClass], que cada módulo define.
El primer ejemplo es el módulo [first]. Es independiente de los demás:
- líneas 8–12: el proyecto padre;
- línea 18: la clase principal del módulo;
- líneas 22–35: Hibernate, el controlador JDBC para MySQL y Logback, sin número de versión (lo proporciona el proyecto padre).
Para ejecutar un ejemplo, compile una sola vez todos los módulos en la carpeta [11-hibernate] ([mvn install] instala las bibliotecas compartidas en el repositorio local de Maven) y luego diríjase a la carpeta del módulo:
La base de datos utilizada es la base [hbfirst] del servidor MySQL local, que es el servidor de Laragon (véanse los apéndices). No es necesario que exista de antemano: MySQL la creará.
11.2.2. La entidad [Article]
Una clase cuyos objetos se almacenan en una tabla se denomina entidad. Nuestra primera entidad es un artículo de una tienda, como el de la tabla [articles] del capítulo 10:
- Línea 10: la anotación [@Entity] (paquete [jakarta.persistence]) designa la clase como una entidad. Es casi una clase Java normal, que no deriva de ninguna clase de Hibernate: se le llama POJO («Plain Old Java Object»);
- líneas 14–16: la clave primaria se designa mediante la anotación [@Id]. No hay ninguna convención de nombres: la anotación es obligatoria. [@GeneratedValue(strategy = GenerationType.IDENTITY)] indica que sus valores serán generados por el SGBD (columna [AUTO_INCREMENT] de MySQL). Su tipo es [Integer], no [int]: el valor [null] significa «aún no registrado en la base de datos»;
- líneas 18–21: cada campo de la clase se convierte en una columna con el mismo nombre. Como la anotación [@Id] se aplica a un campo, Hibernate accede directamente a los campos (los lee y escribe mediante reflexión, incluso si son privados): la clase no necesita métodos de acceso;
- líneas 24–25: Jakarta Persistence exige un constructor sin parámetros, que Hibernate utiliza para crear los objetos leídos de la base de datos. Puede ser protegido ([protected]): el código de la aplicación no lo utilizará;
- líneas 28–33: el constructor utilizado por el programa. No se proporciona ningún identificador; lo generará el SGBD;
- líneas 36–39: una presentación cómoda del artículo. El formato [%.2f] muestra el precio con dos decimales, según las convenciones locales (una coma en Francia).
Una entidad no puede ser un record (capítulo 4): Hibernate debe poder crear el objeto vacío, rellenar sus campos y modificarlos cuando la aplicación los cambia, algo que la inmutabilidad de un record impide. Los records siguen siendo muy útiles con Hibernate para los resultados de consultas que no son entidades (proyecciones), como veremos.
11.2.3. [SessionFactory] y [Session]
El programa utiliza tres objetos de Hibernate:
- [SessionFactory] representa a Hibernate configurado para una base de datos: la lista de entidades, la base de datos y las opciones. Su creación es costosa en recursos (Hibernate analiza las entidades, se conecta al servidor para determinar su versión y prepara el SQL de las operaciones habituales): solo se crea uno por base de datos y por aplicación, al inicio. Es thread-safe: todos los hilos de la aplicación pueden utilizarlo;
- la [Session] representa una sesión de trabajo con la base de datos. Obtiene una conexión cuando la necesita, almacena las entidades que ha leído o guardado y sabe confirmar sus cambios en la base de datos. Es un objeto ligero y de corta duración que no es thread-safe: se abre una para cada unidad de trabajo y luego se cierra;
- [Transaction]: con Hibernate, toda escritura en la base de datos se realiza dentro de una transacción explícita, abierta con [session.beginTransaction()] y cerrada con [commit] (confirmación) o [rollback] (reversión).
[SessionFactory] y [Session] implementan la interfaz [AutoCloseable]: se crean en una instrucción [try] con recursos, que las cierra al final del bloque.
11.2.4. El programa
- líneas 14–22: creación del [SessionFactory]. Hay varias formas de configurar Hibernate (las veremos más adelante); utilizamos la clase [HibernatePersistenceConfiguration] de Hibernate 7, una versión mejorada de la clase [PersistenceConfiguration] introducida con Jakarta Persistence 3.2, que permite configurarlo todo mediante código. Su parámetro es el nombre de la unidad de persistencia, un nombre de libre elección que aparece en los mensajes de Hibernate. Cada método devuelve la propia configuración, lo que permite encadenar las llamadas;
- línea 16: la lista de entidades;
- líneas 18–19: la URL y el JDBC de la base de datos [hbfirst], con el mismo formato que en el capítulo 10, y el usuario ([root], sin contraseña en Laragon). El parámetro [createDatabaseIfNotExist=true] de la URL es una opción del controlador de MySQL: crea la base de datos si no existe;
- Línea 21: [showSql(true, true, false)] indica a Hibernate que imprima en la consola cada comando SQL que ejecuta, con formato en varias líneas (segundo parámetro) y sin colores (tercer parámetro). Examinar el SQL enviado al servidor es la mejor manera de entender lo que hace Hibernate: lo haremos en todos los ejemplos;
- Línea 22: [createEntityManagerFactory] construye el [SessionFactory] (el nombre del método es el del estándar; el tipo devuelto es el de Hibernate);
- Líneas 25–26: el objeto [SchemaManager] del [SessionFactory] (Jakarta Persistence 3.2) administra las tablas de las entidades: [drop(false)] las elimina si existen, [create(false)] las crea (el parámetro [false] especifica que no se debe eliminar ni crear la base de datos en sí). Esto es cómodo para ejemplos y pruebas; una aplicación real administra su base de datos de otra manera, como veremos;
- línea 29: [openSession()] abre una sesión;
- línea 30: el inicio de una transacción;
- líneas 32–34: [persist] agrega tres artículos nuevos a la sesión: se guardarán en la base de datos. No se especifica ningún valor para el identificador; lo generará el SGBD;
- línea 36: [commit] confirma la transacción. Antes de ello, la sesión envía al servidor los comandos SQL que aún son necesarios para guardar los cambios que ha almacenado: esto se denomina «sincronizar» (flush) la sesión con la base de datos;
- líneas 42–44: una consulta escrita en HQL, el lenguaje de consultas de Hibernate: los artículos en orden alfabético por nombre. Hace referencia a la entidad [Article] y a su campo [name], no a la tabla. El segundo parámetro de [createSelectionQuery] es el tipo del resultado: [getResultList] devuelve una [List<Article>].
El archivo [src/main/resources/logback.xml] del módulo configura Logback. Muestra los mensajes de Hibernate de nivel [INFO] o superior, uno por línea (nivel, nombre del registro, mensaje):
Resultados:
Comentarios:
- Líneas 2–17: mensajes informativos de Hibernate: el nombre de la unidad de persistencia, la versión de Hibernate y las características de la base de datos (URL, controlador, dialecto seleccionado, versión del servidor, nivel de aislamiento de las transacciones, tamaño del grupo de conexiones). Hibernate consultó al servidor para seleccionar el dialecto [MySQLDialect] adecuado para su versión;
- línea 4: una advertencia. Hibernate administra su propio pequeño grupo de conexiones, que no está pensado para una aplicación en producción. Veremos, con Spring, cómo proporcionarle el grupo HikariCP del capítulo 10; para nuestros ejemplos, el grupo integrado es suficiente;
- Líneas 18–28: eliminación y posterior creación de la tabla [Article] a partir de la entidad: el nombre de la tabla es el mismo que el de la entidad, las columnas tienen los mismos nombres que los campos, y la columna [id] es la clave primaria, con un valor generado ([auto_increment]). Las columnas de los campos de tipo primitivo ([int]) son [not null]: un [int] no puede ser igual a [null]. Las de los campos de tipo referencia ([String], [BigDecimal]) aceptan el valor [NULL];
- observe los tipos predeterminados: [varchar(255)] para una cadena, y [decimal(38,2)] para un [BigDecimal] (38 dígitos, incluidos 2 decimales). Rara vez son los que se desean: el párrafo siguiente muestra cómo especificarlos;
- Líneas 29–51: los tres comandos [INSERT] configurados se ejecutaron en cuanto se llamó a [persist], antes de [commit]. Esto es consecuencia de que la clave la genera el SGBD ([IDENTITY]): la sesión debe conocer el identificador de una entidad en cuanto se hace cargo de ella y, para obtenerlo, debe ejecutar la inserción (el controlador JDBC devuelve la clave generada; véase el capítulo 10). Con otros métodos de generación, las inserciones se aplazan hasta que la sesión se sincroniza. Los valores de los parámetros ([?]) no se muestran: veremos cómo hacer que aparezcan;
- líneas 53–63: la consulta HQL [from Article order by name] se tradujo en una instrucción [SELECT ... ORDER BY]. Hibernate asignó el alias [a1_0] a la tabla y creó un objeto [Article] por cada fila leída (líneas 64–66).
No hemos escrito ningún comando SQL ni código de lectura de columnas: ese es precisamente el objetivo de un ORM. También vemos que esto no significa que no haga falta saber SQL: para determinar si el SQL generado es correcto y eficiente, es necesario saber leerlo.
11.3. El modelo
Hibernate construye su modelo a partir de las entidades en tres pasos:
- primero aplica sus reglas predeterminadas: a todo lo que no se especifica se le asigna un valor razonable (es lo que se conoce como «configuración por excepción»);
- luego completa o corrige esos valores mediante las anotaciones colocadas en las entidades;
- por último, aplica los archivos de mapeo XML ([orm.xml]), que pueden describir por completo una clase sin anotaciones o modificar lo que especifican sus anotaciones.
11.3.1. Reglas predeterminadas
Ya vimos los fundamentos en el primer ejemplo:
- una entidad lleva la anotación [@Entity] y tiene un identificador designado por [@Id]; ambas anotaciones son obligatorias;
- la ubicación de la anotación [@Id] determina el modo de acceso: cuando se coloca en un campo, Hibernate lee y escribe directamente los campos; cuando se coloca en un método de acceso ([getId]), utiliza los métodos de acceso ([getX]/[setX]). El acceso mediante campos es el más habitual: permite que la clase tenga los métodos que desee;
- todo campo no estático se almacena en una columna, salvo que lleve la anotación [@Transient] o la palabra clave [transient];
- el nombre de la tabla es el nombre de la entidad (el nombre simple de la clase) y el nombre de la columna es el nombre del campo. Estos nombres pasan luego por una estrategia de nomenclatura: la estrategia de Hibernate conserva los nombres tal cual, mientras que otra estrategia, que probaremos más adelante, los convierte a «snake case» ([currentStock] se convierte en [current_stock]). Spring Boot utiliza esta última de forma predeterminada;
- una columna de un tipo primitivo ([int], [double], [boolean]) pasa a ser [NOT NULL]; una columna de un tipo referencia ([Integer], [String], [BigDecimal], [LocalDate]) acepta el valor [NULL];
- los tipos SQL los selecciona el dialecto. Con MySQL: [integer] para [int], [bigint] para [long], [bit] para [boolean], [varchar(255)] para [String], [decimal(38,2)] para [BigDecimal], [date] para [LocalDate], [datetime(6)] (al microsegundo) para [LocalDateTime]. De forma predeterminada, una enumeración se registra por su número de orden (véase el capítulo 3); la anotación [@Enumerated(EnumType.STRING)] la registra por su nombre, lo que es más fiable;
- un campo que hace referencia a otra entidad, o a una colección de entidades, define una relación (la veremos más adelante).
11.3.2. Las anotaciones y el archivo de mapeo XML
El módulo [model] define dos entidades configuradas de dos maneras distintas. La primera se configura mediante anotaciones:
- líneas 3–9: anotaciones de Jakarta Persistence;
- línea 15: [@Table] especifica el nombre de la tabla;
- líneas 19–21: la clave primaria, designada como [@Id] independientemente de su nombre;
- Líneas 24–25: [@Column] especifica la columna; [nullable = false] la hace obligatoria ([NOT NULL]); [length = 50] fija su longitud ([varchar(50)]);
- líneas 28–29: una descripción opcional de hasta 200 caracteres; la columna aceptará el valor [NULL];
- líneas 32–33: [@Column] también especifica el nombre de la columna ([price_excl_tax]) y, para un número decimal, su precisión (el número total de dígitos) y su escala (el número de dígitos después del punto decimal): [decimal(10,2)];
- línea 36: una fecha opcional. El tipo [LocalDate] (capítulo 5) representa una fecha sin hora: se asocia con el tipo SQL [date];
- líneas 39–40: [@Transient] excluye un campo del modelo: en este caso, información útil para la interfaz de usuario que no pertenece a la base de datos;
- líneas 46–48: un método, aunque se llame como un getter, no se registra, ya que Hibernate accede directamente a los campos. Si el acceso se hiciera mediante getters, habría que agregarle la anotación [@Transient].
La segunda entidad no tiene anotaciones:
Su mapeo a la tabla se describe en un archivo XML, ubicado en la carpeta [src/main/resources/META-INF] del módulo:
- líneas 3–7: el esquema XML de los archivos de mapeo de Jakarta Persistence 3.2;
- línea 8: la clase descrita, con acceso mediante campos;
- líneas 9–12: la tabla y un índice único sobre el nombre de la empresa: no puede haber dos proveedores con el mismo nombre. La anotación equivalente es [@Table(name = "suppliers", indexes = @Index(...))];
- líneas 14–16: el identificador, generado por el SGBD;
- líneas 17–19: una columna obligatoria de no más de 60 caracteres;
- líneas 20–22: el campo [phone] se almacena en la columna [tel];
- líneas 24–27: la fecha de creación tiene un valor predeterminado, calculado por el SGBD. El atributo [column-definition] proporciona el texto SQL de la definición de la columna, copiado literalmente en la instrucción [CREATE TABLE]; [insertable="false"] y [updatable="false"] indican que Hibernate nunca debe escribir en esta columna, lo que permite al SGBD utilizar [current_timestamp(6)].
Todo lo que hacen las anotaciones puede hacerse en XML. Las anotaciones tienen la ventaja de colocar la configuración junto al campo, y es el enfoque más habitual; el archivo XML, en cambio, mantiene las clases independientes de Jakarta Persistence y concentra la configuración en un solo lugar. Los dos enfoques pueden combinarse: el archivo XML tiene prioridad en caso de conflicto. Jakarta Persistence no permite configurar el modelo mediante código Java, como sí lo hacen otros frameworks (por ejemplo, Entity Framework en C#).
El programa muestra el modelo construido por Hibernate, seguido del script SQL que crearía las tablas:
- línea 16: un [StringWriter] (paquete [java.io]), un flujo de escritura hacia una cadena en memoria, recibirá el script SQL;
- líneas 20–21: la entidad anotada se declara mediante [managedClass] y el archivo XML mediante [mappingFile];
- líneas 23–25: la base de datos [hbmodel] nunca existirá; este [SessionFactory] se utiliza únicamente para examinar el modelo. Por eso no hay URL ni JDBC. Para seleccionar el dialecto SQL sin consultar al servidor, Hibernate necesita el nombre del SGBD y su versión; la propiedad [ALLOW_METADATA_ON_BOOT] ([hibernate.boot.allow_jdbc_metadata_access]) le impide conectarse al iniciar. Los nombres de las propiedades de configuración son constantes de la interfaz [AvailableSettings];
- líneas 27–28: la convención de nomenclatura «snake case»;
- líneas 30–33: Hibernate escribirá el script de creación de tablas (["create"]) en el objeto [script] sin ejecutarlo; los comandos terminan con un punto y coma y se formatean en varias líneas;
- línea 37: el método [getMetamodel] (Jakarta Persistence) da acceso al modelo: sus entidades ([EntityType]) y, de cada una, sus atributos ([Attribute]);
- Líneas 38–43: para cada entidad, su nombre y su clase; para cada atributo, su nombre, su tipo Java y si es el identificador. El filtrado por patrón de la línea 40 ([instanceof SingularAttribute<?, ?> s && s.isId()], capítulo 4) comprueba el tipo del atributo y, si corresponde, lo utiliza de inmediato;
- líneas 48–50: el script tal como se muestra, sin la sangría de cuatro espacios que Hibernate agrega a sus líneas.
Resultados:
- línea 2: la advertencia de Hibernate confirma que no tiene forma de obtener una conexión;
- líneas 3–13: las dos entidades y sus atributos (primero el identificador y luego los demás en orden alfabético). El campo [selected] y el método [getPriceInclTax] no aparecen en el modelo;
- líneas 15–21: la tabla [suppliers], descrita por el archivo XML. La estrategia de nomenclatura ha cambiado [companyName] y [creationDate] por [company_name] y [creation_date]; la columna [tel], cuyo nombre es fijo, permanece sin cambios. La definición de la columna [creation_date] es la del archivo XML, complementada con [not null];
- Líneas 23–30: la tabla [products]. Los tipos SQL provienen de las anotaciones ([varchar(50)], [decimal(10,2)]) o de las decisiones del dialecto para un tipo Java ([integer], [date]);
- líneas 32–33: el índice único, creado en MySQL mediante una restricción de unicidad ([unique]).
11.3.3. Identificadores generados
La anotación [@GeneratedValue] indica que el valor del identificador se genera. Su parámetro [strategy] especifica cómo:
Estrategia | Generación del identificador |
[IDENTITY] | por el SGBD, al insertar la fila (columna [AUTO_INCREMENT] de MySQL, [IDENTITY] de SQL Server y PostgreSQL) |
[SEQUENCE] | mediante una secuencia del SGBD (PostgreSQL, Oracle), que Hibernate consulta antes de la inserción |
[TABLE] | mediante una tabla de contadores administrada por Hibernate |
[UUID] | por Hibernate: un identificador universal aleatorio, como [java.util.UUID] |
[AUTO] (predeterminado) | Hibernate decide; con MySQL, que no tiene secuencias, las simula mediante una tabla llamada [<table>_SEQ] |
Con MySQL seguimos utilizando [IDENTITY], que corresponde al comportamiento natural de la columna [AUTO_INCREMENT]. Ya hemos visto su resultado: el comando [INSERT] se ejecuta en cuanto se llama a [persist], y Hibernate no puede agrupar varias inserciones en un lote (trataremos los lotes más adelante). La estrategia [SEQUENCE], que permite conocer el ID antes de la inserción, es la preferida para los SGBD que utilizan secuencias.
11.3.4. Valores opcionales y columnas [NULL]
Por lo tanto, que una columna sea opcional se determina en Java por el tipo del campo (primitivo o referencia) y por el atributo [nullable] de [@Column]. Esta decisión debe tomarse con cuidado: la regla expresa tanto una restricción en el código Java («este valor puede faltar») como una restricción en la base de datos. Algunas observaciones:
- [@Column(nullable = false)] define la restricción [NOT NULL] en el esquema creado por Hibernate, y Hibernate también la utiliza antes de enviar un comando [INSERT] o [UPDATE] : si el campo es [null], no envía el comando y lanza una [PropertyValueException] («not-null property references a null or transient value»). Esta verificación de Hibernate se desactiva de forma predeterminada cuando Jakarta Validation (más abajo) está presente: la validación recurre entonces a sus anotaciones o, en su defecto, al SGBD, que rechaza el comando;
- Para una validación más completa, realizada por Java antes de cualquier acceso a la base de datos, utilizamos Jakarta Validation (biblioteca [hibernate-validator]) y sus anotaciones [@NotNull], [@Size(max = 30)], [@Positive].... Cuando está presente en el classpath, Hibernate valida las entidades antes de guardarlas y tiene en cuenta estas anotaciones al crear las columnas;
- un campo no puede ser de tipo [Optional] (capítulo 4), que no está pensado para ese fin; sin embargo, un método de acceso puede devolver un [Optional] construido a partir de un campo opcional: [return Optional.ofNullable(description);].
11.4. Los ejemplos siguientes: dos bibliotecas comunes
Casi todos los ejemplos de los párrafos siguientes utilizan la base de datos [hbarticles] y su tabla [articles], poblada con los seis artículos del capítulo 10. En lugar de repetir la entidad y la configuración de Hibernate en cada módulo, las colocamos en una biblioteca, el módulo [articles], del que dependen los demás módulos. También reemplazamos el registro SQL de [showSql], demasiado detallado para nuestros ejemplos, por un registro más compacto, ubicado en una segunda biblioteca, el módulo [tools].
11.4.1. El registro SQL compacto
En lugar de escribir directamente en la consola ([showSql]), Hibernate puede reenviar su actividad al sistema de registro (en este caso, Logback), y cada categoría de mensajes se escribe en un registro distinto:
Registro | Nivel | Mensajes |
[org.hibernate.SQL] | [DEBUG] | Comandos SQL ejecutados |
[org.hibernate.orm.jdbc.bind] | [TRACE] | el valor de cada parámetro de un comando SQL |
[org.hibernate.orm.resource.jdbc] | [TRACE] | entre otras cosas, el inicio, la confirmación y la cancelación de transacciones |
[org.hibernate.orm.jdbc.batch] | [TRACE] | ejecución de lotes de comandos SQL |
[org.hibernate.orm.jdbc.error] | [WARN] | Errores notificados por el SGBD |
Un registro solo guarda los mensajes de un nivel igual o superior al suyo. Por lo tanto, basta con fijar el nivel deseado para estos registros en el archivo [logback.xml] para capturar esos mensajes. Los procesamos mediante una clase de diseño (layout) que los hace más compactos:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 | |
- línea 16: una clase de diseño (layout) de Logback deriva de la clase [LayoutBase<ILoggingEvent>]; su método [doLayout] (líneas 36–47) recibe cada mensaje (un [ILoggingEvent]) y devuelve el texto que se debe escribir;
- líneas 19–23: los nombres de los registros de Hibernate utilizados;
- líneas 39–46: el procesamiento depende del registro que envió el mensaje ([switch] sobre una cadena, con la sintaxis de «flecha» de Java 14);
- líneas 50–83: el comando SQL, tal como lo formatea Hibernate ([format_sql]), distribuido en varias líneas, con una columna por línea. Lo hacemos más compacto. Las líneas no vacías se dividen en cláusulas (líneas 54–61): una cláusula comienza con una línea de nivel superior ([select], [from], [where]...) e incluye las líneas con sangría que la siguen. Luego cada cláusula se escribe en una sola línea, precedida de [SQL>], si no supera los 100 caracteres (líneas 72–73); en caso contrario, se conservan sus líneas (líneas 76–78). Las cláusulas [insert] y [delete] se combinan con la siguiente (líneas 67–71);
- líneas 91–94: el mensaje de Hibernate que indica el valor de un parámetro tiene el aspecto [binding parameter (1:VARCHAR) <- [bike]]. La expresión regular de las líneas 32–33 (capítulo 5) extrae el número del parámetro y su valor;
- líneas 97–108: entre los numerosos mensajes del registro [org.hibernate.orm.resource.jdbc], solo se conservan los que indican el inicio, la confirmación y la reversión de una transacción. Cada mensaje de Hibernate comienza con un código ([HHH10003002]...) que lo identifica de forma única;
- líneas 111–113: un error del SGBD. Hibernate lo escribe en dos mensajes: uno que contiene los códigos de error (que ignoramos) y otro que contiene el texto del error;
- líneas 116–119: ejecución de un lote de comandos SQL, que encontraremos al final del capítulo;
- Líneas 122–136: el método [withoutLog] ejecuta una acción sin registro (SQL). Utiliza la API de Logback: cada registro ([Logger]) tiene un nivel que puede modificarse durante la ejecución. Fijamos los cinco registros en el nivel [OFF], ejecutamos la acción y luego restauramos los niveles originales en una cláusula [finally], de modo que permanezcan en esos niveles incluso si la acción lanza una excepción;
- líneas 139–141: [LoggerFactory] es la clase de SLF4J que devuelve un registro; como Logback es la implementación actual de SLF4J, el objeto devuelto es un [ch.qos.logback.classic.Logger].
El módulo [tools] contiene también el archivo [logback.xml] utilizado en los ejemplos. Ubicado en la raíz del classpath ([src/main/resources]), Logback lo encuentra al iniciar el programa:
- líneas 6–10: un «appender» escribe los mensajes, en este caso en la consola. Utiliza nuestro formato;
- líneas 13–17: un segundo «appender» para los demás mensajes: nivel, nombre corto del registro, texto;
- líneas 20–34: los registros de Hibernate de la tabla anterior, con sus niveles. Sus mensajes van al «appender» [SQL] y solo a él ([additivity="false"]: no se reenvían además al registro raíz);
- línea 37: se suprime la advertencia sobre el grupo de conexiones integrado de Hibernate;
- línea 40: Hibernate elimina las tablas empezando por sus claves externas; en una base de datos vacía, estas eliminaciones fallan sin consecuencias, pero Hibernate lo registra extensamente. Estos mensajes se suprimen;
- líneas 43–45: los demás registros solo guardan advertencias y errores.
El módulo [tools] tiene una sola dependencia: Logback. Una biblioteca normalmente no impone su configuración de registro a las aplicaciones que la utilizan; aquí lo hacemos para evitar repetir este archivo en cada ejemplo.
11.4.2. La entidad y la base de datos de artículos
La entidad [Article] del módulo [articles] utiliza las anotaciones del párrafo anterior. Este es el comienzo del código; el resto contiene los dos constructores de la entidad del primer ejemplo, los métodos [getX]/[setX] de lectura y escritura de cada campo (excepto [setId]: el identificador lo administra Hibernate) y el mismo método [toString]:
- líneas 14–15: la tabla se llama [articles], como en el capítulo 10. El parámetro [uniqueConstraints] declara una restricción de unicidad, llamada [uk_articles_name], sobre la columna [name]: dos artículos no pueden tener el mismo nombre. Sin un nombre explícito, Hibernate generaría uno ilegible ([UK3f8k...]), que aparecería en los mensajes de error;
- líneas 24–25: un nombre obligatorio de no más de 30 caracteres;
- líneas 28–29: un precio en [decimal(10,2)].
La clase [BaseArticles] contiene la configuración de Hibernate para la base de datos [hbarticles]:
- líneas 13–15: la URL de la base de datos y el usuario, ambos públicos para que otros módulos puedan utilizarlos;
- líneas 22–28: la configuración de Hibernate. La devuelve un método público, lo que permitirá que una instancia la complete antes de crear el [SessionFactory]. La propiedad [FORMAT_SQL] ([hibernate.format_sql]) indica a Hibernate que formatee el SQL, que luego pasa al registro [org.hibernate.SQL]: esos datos formateados son los que la clase [SqlLog] condensa a continuación;
- líneas 31–33: el [SessionFactory] de la base de datos [hbarticles];
- líneas 36–51: un método que recrea la tabla [articles] con sus seis artículos, sin el registro SQL: no queremos ver el SQL de esta inicialización en los resultados de los ejemplos;
- línea 42: [sessionFactory.inTransaction(session -> ...)] abre una sesión, inicia una transacción, ejecuta la lambda (capítulo 7) pasándole la sesión, confirma la transacción (o la revierte si la lambda lanza una excepción) y cierra la sesión. Es la forma más corta de escribir una unidad de trabajo; la utilizaremos con frecuencia, junto con sus variantes [inSession] (una sesión sin transacción), [fromTransaction], y [fromSession] (que devuelven el resultado de la lambda).
El módulo [articles] depende del módulo [tools], de Hibernate y del controlador JDBC:
Por lo tanto, los módulos de ejemplo solo necesitan una dependencia, la del módulo [articles]; Maven agrega las dependencias de este (se denominan dependencias transitivas). Estas son las dependencias del módulo [crud]:
11.4.3. Otras formas de configurar Hibernate
Configuramos Hibernate de forma programática mediante [HibernatePersistenceConfiguration]. Existen otras formas de hacerlo, que se encuentran en aplicaciones y en la documentación:
- un archivo [META-INF/persistence.xml], el enfoque tradicional de Jakarta Persistence: describe una o varias unidades de persistencia (clases de entidad, propiedades de conexión, opciones), y la fábrica se crea mediante [Persistence.createEntityManagerFactory("articles")];
- un archivo [hibernate.properties] (o [hibernate.cfg.xml]), específico de Hibernate, leído por la clase [org.hibernate.cfg.Configuration]: [new Configuration().addAnnotatedClass(Article.class).buildSessionFactory()]. Este es el enfoque utilizado en las versiones anteriores de Hibernate;
- en una aplicación Spring Boot, las propiedades [spring.datasource.*] y [spring.jpa.*] del archivo [application.properties]: Spring Boot crea la fábrica por sí mismo.
Las propiedades son las mismas en todas partes ([hibernate.format_sql], [jakarta.persistence.jdbc.url]...): solo cambia la forma de especificarlas.
11.5. Operaciones básicas: agregar, leer, actualizar, eliminar
11.5.1. El programa [crud]
El módulo [crud] muestra las cuatro operaciones básicas (CRUD: Create, Read, Update, Delete), así como el seguimiento de entidades por parte de la sesión. Para hacer visible ese seguimiento, utiliza algunos métodos internos de Hibernate (su «SPI», Service Provider Interface), destinados a las extensiones de Hibernate y no a las aplicaciones: están agrupados en los métodos utilitarios al final del programa.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 | |
Resultados:
Comentarios:
- Línea 25: [session.find(Article.class, 1)] busca el registro de clave primaria 1. Devuelve [null] si la clave no existe. El SQL generado (líneas 3–6 de los resultados) es un [SELECT] parametrizado, en el que el parámetro vale 1: el registro compacto ahora muestra los valores de los parámetros;
- línea 28: la segunda llamada a [find(Article.class, 1)] no envía ningún comando SQL y devuelve el mismo objeto (línea 9). La sesión almacena las entidades que ha leído o guardado en su contexto de persistencia, también llamado caché de primer nivel: antes de consultar la base de datos, [find] comprueba si la entidad solicitada ya está allí. Una sesión nunca contiene dos objetos para la misma fila de la base de datos;
- Líneas 34–37: adición de un artículo. Antes de [persist], el objeto está [TRANSIENT] («transitorio»): la sesión no lo reconoce y su identificador es [null] (línea 12). [persist] lo incorpora a la sesión, que ejecuta de inmediato el comando [INSERT] (líneas 13–18) para obtener la clave generada y la coloca en el campo [id]. El artículo pasa entonces a estar [MANAGED] («administrado» o «persistente») y su identificador es 7 (línea 19). La transacción se abre en la línea 33 y se confirma en la línea 38 (líneas 11 y 20 de los resultados);
- línea 43: para modificar una fila de la base de datos, basta con modificar el objeto. No se necesita ningún método [update]: la sesión ha conservado una copia de los valores leídos o guardados (el estado original) y compara con ellos los valores actuales. Esto se conoce como «dirty checking»;
- líneas 44–45: [session.isDirty()] indica si la sesión contiene cambios que aún no se han confirmado en la base de datos: así ocurre aquí (línea 23). El método [originalValue] (líneas 90–92) lee del contexto de persistencia el valor original del precio, 100, mientras que el valor actual es 110.0;
- Línea 47: [commit] sincroniza la sesión con la base de datos («flush»): se ejecuta el comando [UPDATE] (líneas 25–32) y luego se confirma la transacción. Después, la sesión no tiene cambios pendientes (línea 34);
- observe que el comando [UPDATE] escribe todas las columnas de la tabla, no solo la que ha cambiado. Este es el comportamiento predeterminado de Hibernate: se utiliza un único comando SQL, preparado de una vez por todas, para todas las actualizaciones de artículos. En cambio, la anotación [@DynamicUpdate] colocada en la entidad indica que se genere cada vez una consulta limitada a las columnas modificadas;
- Líneas 53–56: eliminación. [remove] cambia el estado del artículo a [DELETED] (línea 37); [commit] envía el comando [DELETE] (líneas 38–40). El objeto deja entonces de ser reconocido por la sesión: pasa a estar [DETACHED] («desvinculado», línea 42);
- líneas 60–63: se lee el arco (líneas 44–47) y luego se desvincula de la sesión mediante [detach]: la sesión lo olvida (línea 48). Cualquier cambio en su precio se ignora a partir de entonces. Un objeto desvinculado es algo habitual en una aplicación: es un objeto leído por una sesión que ahora está cerrada (por ejemplo, durante una petición HTTP anterior) y modificado posteriormente por el usuario;
- línea 65: [session.merge(bow)] fusiona el objeto desvinculado con la sesión. La sesión lee el registro de la base de datos (líneas 50–53), copia el estado del objeto desvinculado en la entidad que administra y devuelve esta última: no es el mismo objeto (línea 54). El objeto pasado a [merge] sigue desvinculado; el objeto devuelto es el que debe utilizarse a partir de entonces. [commit] guarda el nuevo precio (líneas 55–62);
- línea 72: se actualiza el inventario de la bicicleta, sin guardar;
- líneas 95–111: visualización del contexto de persistencia. Para cada entidad rastreada ([EntityEntry]), se muestran su nombre, su ID y su estado, seguidos del valor actual de cada propiedad y de su valor original si es distinto. El objeto [EntityPersister] es el de Hibernate que conoce la correspondencia entre una entidad y su tabla: proporciona los nombres de las propiedades y sus valores;
- Líneas 65–75 de los resultados: la sesión rastrea la bicicleta, cuyo inventario ha pasado de 10 a 9, y el arco. El cambio en la bicicleta no se guarda: la sesión se cierra sin sincronizar. No hay [commit], y una sesión no se sincroniza automáticamente al cerrarse.
11.5.2. Los estados de una entidad
Con respecto a una sesión, una entidad se encuentra en uno de los estados siguientes (Jakarta Persistence los denomina «new», «managed», «detached» y «removed»):
Estado | Significado |
Transitorio ([TRANSIENT]) | El objeto fue creado con [new] y nunca se ha guardado: no tiene identificador y ninguna sesión lo conoce |
Administrado ([MANAGED]) | El objeto ha sido leído o guardado por la sesión, que lo rastrea: los cambios que se le hagan se reflejarán en la base de datos durante la siguiente sincronización |
Eliminado ([DELETED]) | El objeto ha sido marcado para su eliminación ([remove]): la siguiente sincronización enviará el comando [DELETE] |
Desvinculado ([DETACHED]) | El objeto corresponde a una fila de la base de datos, pero la sesión que lo leyó está cerrada o lo ha olvidado ([detach], [clear]): sus cambios se ignoran a menos que se fusione con una sesión ([merge]) |
La sincronización («flush») de la sesión envía los comandos SQL al SGBD, que propagan los cambios de las entidades administradas. Esto ocurre:
- durante la fase de [commit] de la transacción;
- antes de ejecutar una consulta cuyo resultado podría depender de cambios que aún no se han confirmado (modo [FlushMode.AUTO], el modo predeterminado): así la consulta ve los datos de la sesión;
- durante una llamada explícita a [session.flush()]. Los comandos se ejecutan entonces, pero no se confirmarán de forma definitiva hasta el [commit] de la transacción.
Este es un panorama del flujo de trabajo con Hibernate: se abre una sesión y una transacción, se leen entidades, se modifican como objetos ordinarios, se agregan ([persist]) y se eliminan ([remove]), y luego se confirma la transacción, que envía a la base de datos todos los comandos necesarios en un solo lote. La sesión actúa como una «unidad de trabajo». Es un objeto ligero diseñado para una vida corta: una unidad de trabajo, como una petición HTTP en una aplicación web. No se utiliza la misma sesión durante toda la vida de una aplicación; de lo contrario, acumularía las entidades rastreadas en su contexto de persistencia.
11.6. Consultas HQL
11.6.1. HQL y JPQL
Para recuperar entidades por un medio distinto de su clave primaria, las consultas se escriben en un lenguaje similar a SQL, pero que hace referencia a entidades y atributos en lugar de tablas y columnas: HQL (Hibernate Query Language). Jakarta Persistence define un lenguaje similar, JPQL (Jakarta Persistence Query Language), del que HQL es un superconjunto: una consulta JPQL es una consulta HQL válida. Hibernate traduce la consulta a SQL, en el dialecto del SGBD, y el SGBD la ejecuta.
Algunas diferencias con SQL:
- se utiliza el nombre de la entidad ([Article]), no el de la tabla ([articles]), y los nombres de los atributos ([currentStock]), no los de las columnas. Los nombres de entidades y atributos distinguen mayúsculas de minúsculas, igual que en Java;
- la cláusula [select] es opcional en HQL: [from Article] devuelve entidades [Article]. JPQL exige escribir [select a from Article a];
- las relaciones entre entidades se recorren mediante un punto ([p.category.name]), y Hibernate escribe los joins por sí mismo, como veremos.
Una consulta se crea con el método [createSelectionQuery] de la sesión (Hibernate 6), que recibe como argumentos el texto HQL y el tipo del resultado, y devuelve un objeto [SelectionQuery<T>]. Luego se pueden establecer sus parámetros y ejecutarla con [getResultList] (una lista), [getSingleResult] (un único resultado; una excepción si hay cero o varios), [getSingleResultOrNull] ([null] si no hay ninguno) o [getResultStream] (un flujo). También existe el método [createQuery] de Jakarta Persistence, que se utiliza tanto para consultas de lectura como para actualizaciones.
11.6.2. El programa [hql]
El módulo [hql] presenta varios ejemplos de consultas:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 | |
Resultados:
Comentarios:
- Líneas 26–27: la cláusula [where] compara dos atributos de la entidad; la cláusula [order by] ordena por nombre: se convierten en las cláusulas [WHERE] y [ORDER BY] del comando SQL (líneas 5–6). La consulta se ejecuta con [getResultList];
- líneas 32–36: una proyección. La consulta no devuelve entidades, sino dos valores por artículo: el nombre y el valor del stock. El SQL generado (línea 9) solicita únicamente las columnas necesarias y realiza el cálculo por sí mismo. El tipo del resultado es el record [StockValue] de las líneas 16–17: Hibernate crea un record por cada línea, pasando a su constructor, en orden, los valores de la cláusula [select]. Estos objetos no son entidades: la sesión no los rastrea. La consulta se escribe en un bloque de texto (Java 15, capítulo 3), más legible que una cadena larga;
- líneas 44–50: una consulta escrita como en JPQL, con un alias ([a]). [:minPrice] es un parámetro con nombre, cuyo valor se asigna mediante [setParameter]. Se convierte en un parámetro del comando SQL (línea 21): por lo tanto, no tenemos que preocuparnos por las inyecciones SQL, ya que el valor se transmite por separado del texto del comando. Es la regla que el capítulo 10 aplicó a las consultas preparadas. [setMaxResults(1)] limita el resultado a una fila: la cláusula [LIMIT] de MySQL (línea 23). En cambio, un valor literal escrito en el texto de la consulta (como ['b%'] en la línea 68: línea 36 de los resultados) se copia en el texto del comando SQL: los valores que provienen del exterior del programa siempre deben pasarse como parámetros;
- líneas 55–59: las agregaciones [count] y [sum] las calcula el SGBD (líneas 28–31): solo se transfiere el resultado, no las filas. HQL también admite [avg], [min], [max] y las cláusulas [group by], y [having];
- Líneas 65–70: el operador [like] de SQL y el operador [in], cuyo operando es un parámetro que acepta una lista Java: Hibernate la expande en tantos parámetros SQL como elementos tenga la lista (línea 36). HQL admite numerosas funciones sobre cadenas ([upper], [length], [substring]...), fechas y números, que traduce al dialecto del SGBD;
- líneas 76–79: paginación, para mostrar una lista larga página por página. [setFirstResult] omite las entradas de las páginas anteriores, mientras que [setMaxResults] conserva las de la página solicitada: la cláusula [LIMIT ?, ?] de MySQL (líneas 45–47). La paginación solo tiene sentido sobre una lista ordenada ([order by]). Las líneas 80–82 construyen la presentación de la página mediante un flujo y [Collectors.joining] (capítulo 5);
- líneas 86–90: una consulta que utiliza un atributo [stock] que no existe. El error se detecta en cuanto se crea la consulta, antes de cualquier ejecución, porque Hibernate analiza el texto HQL y lo compara con el modelo: lanza una [SemanticException] (línea 50; los mensajes de Hibernate están en inglés). Un error de sintaxis produciría una [SyntaxException];
- líneas 94–98: una consulta no puede utilizar un método Java, como [Rules.isOutOfStock] (líneas 110–112): Hibernate no conoce el código y, aunque lo conociera, no necesariamente sabría expresarlo en SQL. Se pueden leer todas las entidades y filtrarlas en memoria con la API Stream: [getResultStream] devuelve un [Stream<Article>] (que debe cerrarse después de su uso, de ahí la instrucción [try] con recursos). El resultado es correcto (línea 54), pero se transfirió toda la tabla (líneas 52–53): con una tabla grande, debe evitarse. Es mejor incluir la condición en la consulta, como se muestra en la línea 26.
11.6.3. Consultas con nombre y validación en tiempo de compilación
Una consulta escrita en una cadena solo se analiza en tiempo de ejecución. Hay dos formas de detectar los errores antes:
- las consultas con nombre: la anotación
***[@NamedQuery(name = "Article.outOfStock", query = "from Article where currentStock < minimumStock")]***, colocada en la entidad, declara una consulta que Hibernate analiza al iniciar, al crear el*[SessionFactory]*. Luego se ejecuta por su nombre: [session.createNamedSelectionQuery("Article.outOfStock", Article.class)]; - el procesador de anotaciones de Hibernate («Hibernate Processor», biblioteca [org.hibernate.orm:hibernate-processor]), declarado en la configuración del compilador ([annotationProcessorPaths] de [maven-compiler-plugin]). Ejecutado por [javac] durante la compilación, verifica las solicitudes de anotaciones y genera, para cada entidad, una clase de «metamodelo» ([Article_] para [Article]), que volveremos a encontrar con la API Criteria. No lo utilizamos en este curso.
11.7. La API Criteria
11.7.1. Consultas construidas mediante código
Una consulta HQL es una cadena que puede construirse por concatenación: esto es poco fiable y difícil de leer en cuanto la consulta depende de muchos criterios opcionales (un formulario de búsqueda, por ejemplo). Jakarta Persistence ofrece otra forma de escribir consultas: la API Criteria, donde la consulta es un árbol de objetos construido mediante llamadas a métodos. Hibernate traduce este árbol a SQL, igual que hace con una consulta HQL (también traduce HQL a un árbol de este tipo). El módulo [criteria] reutiliza varias consultas del programa anterior:
Resultados:
Comentarios:
- línea 28: la sesión devuelve un [HibernateCriteriaBuilder], la versión mejorada por Hibernate del [CriteriaBuilder] de Jakarta Persistence: es la fábrica de todos los elementos de una consulta (condiciones, expresiones, ordenamientos);
- Líneas 32–36: la consulta del primer ejemplo, HQL. [createQuery(Article.class)] crea una consulta que devuelve artículos; [from(Article.class)] declara la entidad consultada y devuelve su raíz ([Root<Article>]), que equivale al alias [a] de [from Article a]; [a.get("currentStock")] designa un atributo. La condición se construye con [cb.lt(x, y)] («less than», [x < y]) y el ordenamiento con [cb.asc(...)]. La notación [a.<Integer>get(...)] proporciona al compilador el tipo del atributo, que la cadena ["currentStock"] no le permite determinar;
- línea 37: la sesión ejecuta la consulta como una consulta HQL. El SQL generado (líneas 3–6) es el mismo que el de la consulta HQL;
- Líneas 41–47: una proyección sobre el record [StockValue]. [cb.prod(x, y)] es el producto de dos expresiones; [as(BigDecimal.class)] especifica el tipo del resultado; [cb.construct(StockValue.class, ...)] indica que cada fila del resultado debe pasarse al constructor del record;
- Líneas 76–90: aquí es donde la API Criteria resulta más útil. El método [search] construye una consulta a partir de los criterios que recibe: cada condición se agrega a la lista de condiciones solo si el criterio correspondiente no es [null], y la cláusula [where] recibe todas las condiciones de la lista, combinadas mediante [and]. La primera llamada (línea 54) produce una consulta con una condición (línea 21), mientras que la segunda (línea 56) produce una consulta con dos condiciones (línea 30). Observe que con la API Criteria, Hibernate pasa los valores ([150], [d%]) como parámetros del comando SQL;
- líneas 60–68: las agregaciones [count] y [sum].
11.7.2. El metamodelo estático
El punto débil de estas consultas es que los atributos se designan mediante cadenas ([a.get("currentStock")]): un error tipográfico no se detectará hasta la ejecución, y el compilador ignora el tipo del atributo. Para resolverlo, Jakarta Persistence ofrece un metamodelo estático: para cada entidad [Article], existe una clase [Article_] que contiene un campo por atributo, con su nombre y su tipo. Entonces se escribe ***[cb.lt(a.get(Article\_.currentStock), a.get(Article\_.minimumStock))]***, que el compilador valida por completo. Estas clases no se escriben a mano: se generan durante la compilación mediante el procesador de anotaciones de Hibernate mencionado antes. Es el enfoque recomendado en un proyecto real que utilice la API Criteria.
Para una consulta fija, HQL es más legible que la API Criteria; para una consulta que se construye según las circunstancias, la API Criteria es más segura. Se pueden combinar: Hibernate permite crear una consulta Criteria a partir de una cadena HQL ([cb.createQuery(hql, Article.class)]) y luego complementarla con código.
11.8. Relaciones
11.8.1. El modelo de la tienda
Las tablas de una base de datos están vinculadas entre sí. Hibernate representa estos vínculos como asociaciones: campos que hacen referencia a otra entidad o a una colección de entidades. El módulo [relations] utiliza una base de datos [hbshop] que describe una pequeña tienda con seis entidades. Una categoría agrupa productos:
Un producto pertenece a una categoría y tiene etiquetas:
Una etiqueta se asigna a varios productos:
Un pedido pertenece a un cliente y contiene líneas de pedido:
Las entidades [Client] y [OrderLine] se construyen sobre el mismo modelo. Un cliente tiene un ID, un nombre y una lista de pedidos ([@OneToMany(mappedBy = "client", cascade = CascadeType.PERSIST)]), con un método [add(CustomerOrder)]; una línea de pedido tiene un ID, una cantidad y dos asociaciones muchos a uno: una con su pedido y otra con su producto:
Este ejemplo incluye los tres tipos de asociaciones:
- una relación muchos a uno ([@ManyToOne]): un producto pertenece a una categoría (Product, líneas 17–19). En la base de datos, esto se representa mediante una clave externa, la columna [category_id] de la tabla [products], donde [@JoinColumn] especifica el nombre y el nombre de la restricción ([fk_products_category]). [optional = false] hace obligatoria la relación: la columna será [NOT NULL];
- la relación inversa, uno a muchos ([@OneToMany]): una categoría contiene varios productos (Category, líneas 14–15). No crea nada en la base de datos: [mappedBy = "category"] indica que está descrita por el campo [category] de la entidad [Product]. [Product.category] es el lado propietario de la relación, y [Category.products] su lado inverso: Hibernate guarda el valor del lado propietario. Sin embargo, ambos lados deben mantenerse coherentes en memoria: este es el papel del método [add] (Category, líneas 25–28), que agrega el producto a la lista y establece su categoría;
- una relación muchos a muchos ([@ManyToMany]): un producto tiene varias etiquetas y una etiqueta se asocia con varios productos. Se almacena en una tabla de asociación, [products_tags], cuyo nombre, los nombres de las dos columnas y los nombres de las dos claves externas los proporciona [@JoinTable] (Product, líneas 22–28). El lado inverso es [Tag.products] ([mappedBy = "tags"]). Para una relación muchos a muchos, se prefiere un [Set] a una [List]: con una lista, Hibernate elimina y vuelve a insertar todas las filas de la tabla de asociación cada vez que se modifica la colección;
- [fetch = FetchType.LAZY] exige la carga diferida de la categoría de un producto: solo se leerá si se utiliza. Este es el comportamiento predeterminado para las colecciones ([@OneToMany], [@ManyToMany]), pero no para las relaciones con una sola entidad ([@ManyToOne]), que el estándar carga de inmediato de forma predeterminada ([EAGER]): [fetch = FetchType.LAZY] se les agrega sistemáticamente, como recomienda la documentación de Hibernate;
- [cascade = CascadeType.PERSIST] propaga la operación [persist]: al persistir una categoría se persisten sus productos, y al persistir un producto se persisten sus etiquetas. Los demás valores ([MERGE], [REMOVE], [ALL]...) propagan las demás operaciones;
- las colecciones se inicializan con una colección vacía, y el campo de una relación con una sola entidad permanece en [null] hasta que se lo rellena. Los métodos [setCategory], [setClient] y [setOrder] no son públicos: solo los métodos [add] del mismo paquete los llaman.
La clase [Shop] configura Hibernate para la base de datos [hbshop] y crea allí un conjunto de datos inicial:
- líneas 19–20: las seis entidades, declaradas mediante [managedClasses];
- líneas 34–46: un grafo de objetos: tres categorías, sus productos y las etiquetas de los productos;
- líneas 48–50: basta con persistir las categorías: gracias a la cascada, Hibernate recorre las asociaciones y persiste todas las entidades a las que llega, en el orden correcto (las categorías antes que los productos que las referencian), completando las claves externas y la tabla de asociación;
- líneas 52–57: un cliente, su pedido y las dos líneas de este, persistidos en una sola operación.
Las tablas creadas por Hibernate son las siguientes:
- Líneas 3–9: una tabla por entidad y la tabla de asociación [products_tags];
- Líneas 16–19: la clave externa [category_id] de la tabla [products] hace referencia a la tabla [categories]. Es [NOT NULL] ([optional = false]). MySQL crea un índice en cada clave externa (línea 18). A diferencia de otros ORM, Hibernate no exige la eliminación en cascada en la base de datos ([ON DELETE CASCADE]): esto puede lograrse mediante la anotación [@OnDelete(action = OnDeleteAction.CASCADE)];
- líneas 23–30: la tabla de asociación tiene dos columnas, claves externas hacia las dos tablas relacionadas, que juntas forman su clave primaria.
11.8.2. El programa
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 | |
Resultados:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 | |
Comentarios:
- líneas 15–22: los records que recibirán los resultados de las proyecciones;
- líneas 32–39: la salida la lee el método [product] (líneas 125–129); un cliente, su pedido y las dos líneas de este se persisten con una sola llamada a [persist]. El SQL (líneas 12–28 de los resultados) muestra el orden de las inserciones: el cliente, luego el pedido, cuya clave externa [client_id] recibe la clave generada para el cliente (2), y luego las líneas, cuya clave externa [order_id] recibe la clave del pedido;
- Líneas 46–52: carga diferida. La consulta lee solo los pedidos (líneas 32–34): el cliente y las líneas de cada pedido se leen únicamente cuando el programa los utiliza, mediante consultas adicionales (líneas 35–42 para el primer pedido, 44–51 para el segundo). Para el cliente, Hibernate ha colocado un proxy en el campo [client], un objeto de una subclase de [Client] generada por Hibernate (mediante Byte Buddy), que contiene solo el identificador y carga al cliente en la primera llamada a un método ([getName()]). Por eso una entidad no debe ser una clase [final]. Para las líneas, la lista es una colección de Hibernate, que se carga en su primer uso ([size()]);
- líneas 57–62: el pedido lo lee una sesión que se cierra de inmediato ([fromSession]). Estas líneas no se cargaron y, una vez cerrada la sesión, ya no se pueden cargar: acceder a la colección provoca una [LazyInitializationException] (línea 58), una de las excepciones más comunes en las aplicaciones que utilizan Hibernate. Hay que cargar lo que se necesita mientras la sesión está abierta;
- Líneas 67–72: precarga mediante una consulta. [join fetch] indica a Hibernate que cargue, junto con los pedidos, sus clientes, sus líneas y el producto de cada línea: una sola consulta con joins (líneas 60–78). La salida muestra los dos pedidos y sus líneas (líneas 79–84). El join con las líneas produce una fila SQL por línea de pedido; Hibernate obtiene un único pedido por cada identificador: la lista resultante contiene efectivamente dos pedidos;
- líneas 86–90: un «grafo de entidad» (Jakarta Persistence) describe, independientemente de cualquier consulta, las asociaciones que deben cargarse con una entidad: en este caso, los productos de la categoría. [session.find(graph, 2)] (Jakarta Persistence 3.2) recupera la categoría 2 junto con sus productos en una sola consulta (líneas 86–90 de los resultados). Una vez cerrada la sesión, los productos siguen siendo accesibles (líneas 92–93). Para cargar una asociación más tarde, mientras la sesión está abierta, se escribe [Hibernate.initialize(category.getProducts())];
- líneas 97–101: las asociaciones se utilizan en las consultas: [join p.tags e] recorre la relación muchos a muchos (dos joins, con la tabla de asociación y la tabla de etiquetas, líneas 95–96), y [p.category.name] se traduce en un join implícito con la tabla de categorías (línea 97);
- líneas 105–111: un cálculo a través de dos relaciones, el importe total de cada pedido, realizado por completo por el SGBD: joins, [sum] y [group by] (líneas 103–109);
- líneas 115–120: una agrupación. [group by p.category.name] agrupa los productos por nombre de categoría; para cada grupo, el SGBD calcula el número de productos ([count]) y el precio promedio ([avg], de tipo [Double]) (líneas 113–117). La categoría [diving], que no tiene productos, no aparece: el join con la tabla de categorías es un inner join ([join]).
11.8.3. El problema de las N+1 consultas
La carga diferida del ejemplo ilustra un problema que afecta a cualquier usuario de un ORM, conocido como el problema de las «N+1 consultas»: una consulta para leer los N pedidos y luego una consulta por pedido para leer su cliente (y otra para sus líneas). Con mil pedidos, esto da como resultado mil un viajes de ida y vuelta al servidor, cuando uno solo habría bastado. El problema es aún más insidioso porque es invisible en el código: [order.getClient().getName()] no parece una consulta. Las soluciones son las que se muestran en el ejemplo: [join fetch], un grafo de entidad o, mejor aún, una proyección que recupere solo los datos pertinentes. Hibernate también ofrece la carga por lotes ([@BatchSize(size = 20)] aplicada a una colección o a la clase de la entidad referenciada, en este caso [Client]), que, por ejemplo, recupera los clientes de veinte pedidos en una sola consulta. El registro SQL ayuda a identificar el problema: la misma consulta repetida numerosas veces.
11.9. Cambios en el esquema de la base de datos
11.9.1. El problema
Hasta ahora, Hibernate ha creado las tablas después de eliminarlas. Esto es imposible en una aplicación en producción: su base de datos contiene datos que deben conservarse cuando el modelo evoluciona (una nueva columna, una nueva tabla). Debe ser posible migrar la base de datos de una versión del esquema a la siguiente, de forma segura y reproducible, tanto en la máquina del desarrollador como en el servidor de producción. A esto se le llama migración del esquema.
Hibernate no admite migraciones: puede crear un esquema, validarlo y realizar en él actualizaciones limitadas. En el mundo Java, la práctica estándar consiste en gestionar las migraciones mediante scripts SQL versionados, aplicados por una herramienta dedicada (con mayor frecuencia Flyway o Liquibase), y en hacer que Hibernate verifique que el esquema resultante coincide con las entidades.
11.9.2. Gestión del esquema por Hibernate
La propiedad [hibernate.hbm2ddl.auto] (o el método [schemaToolingAction] en la configuración, que es el que usa el programa siguiente) especifica lo que Hibernate debe hacer con el esquema al crear el [SessionFactory]:
Valor | Constante [Action] | Efecto |
[none] | [NONE] | ninguno (valor predeterminado) |
[create-only] | [CREATE_ONLY] | creación de tablas |
[create] | [CREATE] | Eliminación y luego creación de tablas |
[create-drop] | [CREATE_DROP] | como [create], y eliminación de las tablas al cerrar el [SessionFactory]: para pruebas |
[drop] | [DROP] | Eliminación de tablas |
[validate] | [VALIDATE] | Verifica que las tablas y columnas de las entidades existan y tengan tipos compatibles; de lo contrario, lanza una excepción |
[update] | [UPDATE] | Crea las tablas y columnas que falten |
Jakarta Persistence define una propiedad relacionada, [jakarta.persistence.schema-generation.database.action], con los valores [none], [create], [drop-and-create], y [drop]. Las mismas acciones están disponibles de forma programática, como hicimos con [SchemaManager] desde [SessionFactory] ([create], [drop], [validate], [truncate]).
El valor [update] resulta tentador: Hibernate compara las entidades con el esquema de la base de datos y agrega lo que falta. Tiene limitaciones que lo hacen inadecuado para una aplicación en producción:
- solo agrega: nunca elimina una columna o tabla que ya no es necesaria, no modifica el tipo ni la longitud de una columna existente y no puede renombrar (renombrar un campo crea una nueva columna vacía, mientras que la antigua permanece con sus datos);
- no puede transformar datos (rellenar una nueva columna obligatoria, dividir una columna en dos);
- lo que hace depende del estado de la base de datos que encuentra: es imposible saber de antemano qué comandos se ejecutarán, ni en qué orden, y no se conserva ningún registro de ello.
Por lo tanto, reservamos [create], [create-drop] y [update] para el desarrollo y las pruebas, y usamos [validate] (o [none]) en producción, con el esquema gestionado mediante scripts.
11.9.3. Scripts SQL versionados
El principio de las migraciones basadas en scripts es sencillo:
- cada cambio del esquema se describe mediante un script SQL numerado: [V1__create_clients.sql], [V2__add_phone.sql]... Una vez que un script se ha aplicado a una base de datos, nunca se vuelve a modificar: cualquier corrección es objeto de un nuevo script;
- la base de datos contiene una tabla de historial que enumera las versiones que se le han aplicado;
- cuando la aplicación se inicia (o durante el despliegue), una herramienta compara los scripts disponibles con el historial y aplica, en orden, los que aún no se han aplicado.
Los scripts forman parte del código fuente de la aplicación: se almacenan y gestionan junto con el resto del código (por ejemplo, en un repositorio Git). Para comprender cómo funciona esto, el módulo [clients] implementa un pequeño ejecutor de scripts versionados, inspirado en Flyway; luego presentaremos Flyway propiamente dicho.
11.9.4. El módulo [clients]
El módulo [clients] se basa en la base [hbclients]. La entidad es un cliente:
En la primera versión de la aplicación, el cliente no tiene número de teléfono: las líneas 16-17 aún no existen. Las agregaremos en la segunda versión. Los scripts se encuentran en la carpeta [src/main/resources/db/migration] del módulo, que se copiará al classpath. El primer script crea la tabla:
El segundo agrega la columna del número de teléfono:
La clase [Migrations] ejecuta los scripts mediante JDBC (capítulo 10), independientemente de Hibernate:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 | |
- Líneas 29-34: un script se describe mediante un registro: su versión, descripción y ruta;
- línea 37: el nombre de un script sigue la convención de Flyway: [V], el número de versión, dos guiones bajos y una descripción;
- líneas 40-45: la tabla de historial: una fila por versión aplicada, con su descripción y la fecha en que se aplicó;
- líneas 59-76: la lista de scripts. [getResource("/db/migration")] obtiene la URL de la carpeta en el classpath, que se enumera con [Files.list] (capítulo 5). Este código supone que la carpeta es una carpeta real (lo cual ocurre cuando Maven ejecuta el programa desde la carpeta [target/classes]); Flyway también puede leer scripts desde un archivo [.jar]. Los scripts se ordenan por número de versión: el orden alfabético colocaría [V10] antes de [V2];
- líneas 79-91: versiones ya aplicadas, leídas de la tabla de historial, que se crea si es necesario ([create table if not exists]);
- líneas 94-97: los scripts que quedan por aplicar;
- líneas 100-110: la aplicación de los scripts pendientes, hasta una versión dada;
- líneas 113-138: la aplicación de un script: sus comandos (separados por punto y coma, ignorando las líneas de comentario), seguida de la adición de su versión a la tabla de historial, dentro de una transacción. Una advertencia, señalada en el comentario de la línea 133: en MySQL, un comando de modificación del esquema ([CREATE TABLE], [ALTER TABLE]) confirma implícitamente la transacción actual y no puede revertirse. Si se produce un error en medio de un script, la base de datos puede quedar en un estado intermedio. Por eso es preferible usar scripts cortos, cada uno con un solo cambio.
El programa principal aplica las migraciones y luego le pide a Hibernate que valide el esquema:
- línea 16: se puede especificar, como argumento, la versión hasta la cual aplicar las migraciones; de forma predeterminada, se aplican todas;
- líneas 19-26: el estado de las migraciones, seguido de su aplicación;
- líneas 29-35: [SessionFactory] se crea con la acción [VALIDATE]: Hibernate verifica que el esquema de la base de datos coincida con la entidad [Client]. Si no es así, la creación de [SessionFactory] falla y lanza una [PersistenceException], causada por el error de validación (líneas 44-48);
- líneas 38-43: se utiliza la nueva columna.
11.9.5. Generar los scripts con Hibernate
Los scripts SQL se escriben a mano. Sin embargo, Hibernate puede ayudar a escribirlos: puede generar (sin ejecutarlo) el script de creación del esquema o, comparando las entidades con una base de datos existente, el script para actualizarlo. Esto es lo que hace la clase [GenerateScript]:
- línea 13: la acción, pasada como argumento: [create] o [update];
- línea 16: [SessionFactory] se crea únicamente para generar el script; la variable que lo contiene nunca se usa. Java 22 permite llamarla [_] (variable anónima);
- líneas 20-23: las propiedades de generación de scripts, que ya vimos en el módulo [model]. Esta vez, Hibernate se conecta a la base de datos: para la acción [update], necesita conocer el esquema de la base de datos.
El script de creación, generado a partir de la versión actual de la entidad, sirve para crear una base de datos nueva de una sola vez (por ejemplo, para pruebas):
Con la primera versión de la entidad (sin número de teléfono), habría generado, con el mismo orden de columnas, el script [V1__create_clients.sql].
11.9.6. Aplicar las migraciones
Supongamos que la base de datos aún no existe. Aplicamos solo la primera migración, pasando la versión 1 como argumento:
- Líneas 2-3: no se ha aplicado ninguna versión; hay dos scripts pendientes. La tabla de historial fue creada por el método [appliedVersions], y la base de datos [hbclients] por MySQL ([createDatabaseIfNotExist=true]);
- línea 4: se aplica el script [V1] ;
- Línea 5: Hibernate detecta que la columna [phone] de la entidad no existe en la tabla: esto es normal, ya que la base de datos está en la versión 1 y la entidad en la versión 2. Con la entidad de la versión 1, la validación habría tenido éxito.
La aplicación evoluciona: agregamos el número de teléfono a la entidad. Para escribir el script de la versión 2, le pedimos a Hibernate que compare la entidad con la base de datos, que todavía está en la versión 1:
Esto es, salvo por el formato, igual al script [V2__add_phone.sql]. Ahora aplicamos todas las migraciones pendientes:
- Líneas 2-4: se aplica la versión 1, la versión 2 está pendiente y se aplica;
- línea 5: la validación tiene éxito;
- líneas 6-15: la nueva columna está lista para usarse.
La tabla de historial contiene ahora ambas versiones:
Al ejecutar de nuevo el programa no se aplicará ningún cambio: ambas versiones figuran en el historial.
11.9.7. Flyway
Flyway es la herramienta de migración más utilizada en el mundo Java (Spring Boot la ejecuta automáticamente al iniciar una aplicación si está presente en el classpath). Funciona exactamente con el mismo principio que nuestro ejecutor, pero es más completa: los scripts [V<version>__<description>.sql] se buscan de forma predeterminada en la carpeta [db/migration] del classpath, la tabla de historial [flyway_schema_history] y la aplicación de los scripts pendientes en orden de versión. En particular, agrega una suma de verificación a cada script, que detecta cambios en un script ya aplicado; scripts «repetibles» ([R__description.sql], reaplicados con cada cambio, por ejemplo para vistas); migraciones escritas en Java, un bloqueo que impide que dos instancias de la aplicación migren la base de datos al mismo tiempo, y una extensión de Maven ([mvn flyway:migrate], [mvn flyway:info]).
Para usarla en el módulo [clients], basta con agregar las dependencias [org.flywaydb:flyway-core] y [org.flywaydb:flyway-mysql] (en sus últimas versiones), conservar los dos scripts tal cual (ya que siguen su convención) y reemplazar el uso de la clase [Migrations] por una sola línea: [Flyway.configure().dataSource(URL, "root", "").load().migrate();]
Liquibase, la otra herramienta de uso común, describe los cambios del esquema en archivos XML, YAML o SQL (los «changelogs»), y puede generar el SQL específico de cada DBMS. En ambos casos, Hibernate se configura con [validate] o [none], y ya no modifica el esquema.
11.10. Hibernate y los hilos virtuales
Una consulta a la base de datos es una operación de E/S: mientras el servidor procesa la solicitud, el hilo en espera no hace nada. El capítulo 9 presentó dos formas de evitar desperdiciar hilos durante estas esperas: la programación asíncrona ([CompletableFuture]) y los hilos virtuales (Java 21). La API de Hibernate, al igual que el JDBC que utiliza, es bloqueante: [getResultList] no devuelve el control hasta que se han leído las filas. Con los hilos virtuales, esto deja de ser un inconveniente: un hilo virtual bloqueado en E/S libera el hilo del sistema que lo estaba ejecutando, y se pueden crear miles de ellos. Por lo tanto, escribimos código bloqueante ordinario, ejecutado por hilos virtuales.
Debe respetarse una regla: una sesión no es segura para hilos (thread-safe). Nunca debe compartirse entre varios hilos: cada hilo (cada tarea) abre su propia sesión con [SessionFactory], que sí se comparte. Hibernate no siempre detecta el uso simultáneo de una misma sesión; los errores resultantes son impredecibles.
El módulo [async] respeta esta regla:
Resultados:
Comentarios:
- Línea 25: un ejecutor que crea un hilo virtual para cada tarea (capítulo 9). La instrucción [try] con recursos espera a que todas las tareas terminen antes de cerrarlo;
- Líneas 26-32: dos tareas enviadas al ejecutor. Cada una abre su propia sesión ([fromSession]) y ejecuta una consulta; ambas consultas se ejecutan simultáneamente, usando dos conexiones del pool. Su orden en el registro (líneas 3-9) puede, por lo tanto, variar de una ejecución a otra;
- líneas 34-35: [get()] espera a que cada tarea termine y devuelve su resultado (líneas 10-13);
- líneas 41-50: un [CompletableFuture] (capítulo 9) cuyo primer paso (una transacción completa) lo ejecuta un hilo virtual ([supplyAsync(..., executor)]), y el segundo paso muestra su resultado. El registro devuelto por la transacción está desasociado (su sesión está cerrada): sus campos pueden leerse, pero sus asociaciones no pueden cargarse;
- Líneas 56-60: [getResultStream] devuelve un flujo: las entidades se procesan a medida que se leen, sin formar una lista (líneas 33-35). Esto es útil para procesar una gran cantidad de filas. Con MySQL, tenga en cuenta que, de forma predeterminada, el controlador lee todas las filas del resultado antes de devolver la primera; para una lectura realmente progresiva, hay que indicarle que use un cursor (parámetro [useCursorFetch=true] de la URL y tamaño de lote definido con [setFetchSize]);
- Líneas 66-69: un tiempo máximo de ejecución, en segundos, establecido con [setTimeout]. La consulta (una consulta SQL nativa, de la que hablaremos más adelante) tarda cinco segundos; después de un segundo, el controlador JDBC la interrumpe e Hibernate lanza una [QueryTimeoutException] (líneas 37-39). Este es el equivalente, para una consulta, de cancelar una tarea ([Future.cancel], capítulo 9), que aquí no tendría ningún efecto: interrumpir un hilo bloqueado en el controlador JDBC no interrumpe la consulta que se está ejecutando en el servidor.
Para las aplicaciones que requieren una API realmente no bloqueante, existe Hibernate Reactive, una variante de Hibernate que se apoya en controladores reactivos (los de Vert.x) en lugar de JDBC, y cuyos métodos devuelven [CompletionStage] u objetos de la biblioteca Mutiny. Los hilos virtuales eliminan esta complejidad en la mayoría de los casos: ese es el enfoque adoptado en este curso.
11.11. Transacciones y concurrencia
11.11.1. Transacciones
El capítulo 10 presentó las transacciones: un conjunto de operaciones que, o bien todas tienen éxito, o bien todas fallan. Con Hibernate:
- toda escritura se realiza dentro de una transacción, abierta con [session.beginTransaction()] y cerrada con [commit] o [rollback]. Los métodos [inTransaction] y [fromTransaction] de [SessionFactory] se encargan de esto por nosotros: confirman la transacción si la lambda termina con normalidad, y la revierten si lanza una excepción, que luego se vuelve a lanzar;
- todos los comandos enviados durante la transacción (comandos inmediatos mediante [INSERT], sincronizaciones explícitas mediante [flush] y sincronización mediante [commit]) se confirman o se revierten en conjunto;
- un error del DBMS se propaga como una excepción de Hibernate, derivada de [JDBCException], que encapsula la [SQLException] del controlador: [ConstraintViolationException] para una violación de restricción (clave primaria, unicidad, clave externa, [NOT NULL]), [SQLGrammarException] para un error en la orden SQL, etc.
El módulo [transactions] ilustra las dos formas de manejar una transacción:
Resultados:
Comentarios:
- Líneas 21-24: se agregan dos artículos a una transacción gestionada por [inTransaction]; el segundo artículo tiene el mismo nombre que uno existente. Ambas operaciones [INSERT] se ejecutan de inmediato (líneas 4-15); la segunda viola la restricción de unicidad de la columna [name]: MySQL la rechaza (línea 16), [persist] lanza una [ConstraintViolationException]; [inTransaction] revierte la transacción (línea 17) y vuelve a lanzar la excepción;
- líneas 25-28: se captura la excepción; [getConstraintName] proporciona el nombre de la restricción violada (línea 18). Esto demuestra el valor de haber nombrado la restricción;
- línea 29: la raqueta, que se había insertado correctamente, no está en la base de datos (línea 23): al revertir la transacción se eliminó;
- líneas 33-51: una transacción gestionada por el código. Se venden dos bicicletas y la actualización se envía al DBMS mediante un [flush] explícito (líneas 29-36); luego se agrega un artículo con un nombre existente: la inserción falla (línea 43);
- línea 45: nunca se llega a la confirmación;
- Líneas 46-50: en [catch], se revierte la transacción (línea 45 de los resultados). [getSQLException] informa la excepción original del controlador JDBC, y su mensaje es el de MySQL (línea 44);
- línea 53: la venta de las bicicletas, aunque fue enviada al DBMS mediante [flush], se canceló: el inventario de bicicletas sigue siendo 10 (línea 50);
- Líneas 58-64: un método que vuelve a leer un registro con una nueva sesión para ver el estado real de la base de datos, en lugar de las entidades de la sesión actual.
Después de una excepción, una sesión ya no debe utilizarse: su contexto de persistencia puede contener entidades en un estado incoherente con la base de datos. Se revierte la transacción, se cierra la sesión y, si es necesario, se comienza de nuevo con una sesión nueva. Esto es lo que hace [inTransaction], y lo que hace nuestro código al salir del bloque [try], que cierra la sesión.
El nivel de aislamiento de las transacciones es el de la conexión JDBC: [REPEATABLE_READ], el valor predeterminado de MySQL, como se mostró en el primer ejemplo. Puede cambiarse para todo el [SessionFactory] mediante el método [jdbcTransactionIsolation] en la configuración.
11.11.2. Concurrencia optimista
Dos usuarios leen el mismo artículo, que tiene un stock de 10. El primer usuario vende una unidad y actualiza el stock a 9. El segundo usuario, que leyó el valor del stock antes de esta actualización, vende tres unidades y actualiza el stock a 7: la venta del primer usuario se pierde. Este es el problema de las actualizaciones perdidas.
Una solución sería bloquear la fila durante toda la duración de la operación de cada usuario (concurrencia «pesimista»): esto bloquea a los demás usuarios, a veces durante mucho tiempo. Con Hibernate, generalmente se prefiere la concurrencia optimista: no se bloquea nada, pero en el momento de guardar se realiza una verificación para asegurarse de que la fila no haya sido modificada desde que se leyó. La forma estándar de hacerlo es agregar un número de versión a la entidad: un campo anotado con [@Version]. Hibernate incrementa este número cada vez que se modifica la fila, y agrega la condición «la versión todavía tiene el valor leído» a la cláusula [WHERE] de los comandos [UPDATE] y [DELETE]. Si el comando no modifica ninguna fila, significa que otro usuario ya accedió a los datos: Hibernate lanza una [OptimisticLockException].
El módulo [concurrency] usa su propia base de datos, [hbconcurrency], y su propia entidad, [Article], reducida a lo esencial:
- líneas 16-17: el número de versión, de tipo [int] (también se puede usar [long], o una fecha de tipo [Instant]). La aplicación nunca lo modifica por sí misma.
El programa simula a los dos usuarios con dos sesiones:
Resultados:
Comentarios:
- líneas 21-25: la tabla se vuelve a crear con un solo artículo, la bicicleta, versión 0;
- líneas 31-32: cada usuario lee la bicicleta en su propia sesión. La columna [version] se lee junto con las demás (líneas 3-10);
- Líneas 36-38: la orden [UPDATE] del primer usuario (líneas 13-20) escribe la nueva versión (1) y contiene la condición [version=?] con la versión leída (0). La fila se modifica; el campo [version] de la entidad toma el valor 1 (línea 22);
- líneas 44-48: la solicitud del segundo usuario contiene la misma condición, con la versión que leyó, 0, mientras que la versión de la fila en la base de datos es ahora 1. No se modifica ninguna fila e Hibernate dispara una [OptimisticLockException] (línea 33). Sincronizamos explícitamente la sesión ([flush]) antes del [commit] para obtener esta excepción tal cual; si se lanzara durante el [commit], quedaría encapsulada dentro de una [RollbackException];
- Líneas 57-65: la resolución depende de la aplicación: abortar, notificar al usuario o, como aquí, volver a leer el artículo con una nueva sesión (la sesión que recibió la excepción ya no debe utilizarse) y repetir la operación. El inventario repuesto es 9 en la versión 1 (línea 41), y la venta de las tres bicicletas da como resultado un inventario de 6 en la versión 2 (línea 50).
Dos variantes:
- Sin una columna de versión, Hibernate puede comprobar los valores antiguos de las propias columnas: con las anotaciones [@OptimisticLocking(type = OptimisticLockType.DIRTY)] y [@DynamicUpdate] en la entidad, la cláusula [WHERE] del [UPDATE] contiene el valor leído de cada columna modificada ([where id=? and currentStock=?]). Esto resulta útil para una base de datos existente que no puede modificarse;
- La concurrencia pesimista sigue siendo posible cuando los conflictos son frecuentes: [session.find(Article.class, 1, LockModeType.PESSIMISTIC_WRITE)] lee la fila con una orden [select ... for update], que la bloquea hasta el final de la transacción.
11.12. El SQL nativo
Hibernate genera el SQL a partir de HQL o de la API Criteria, pero sigue siendo posible escribir uno mismo el SQL de una consulta, para usar una función específica del DBMS u optimizar una consulta compleja: esto se denomina consulta nativa. El módulo [rawsql] enumera los métodos disponibles:
Resultados:
Comentarios:
- Líneas 22-27: [createNativeQuery] ejecuta una consulta (SQL) que devuelve filas de la tabla de una entidad, y el segundo parámetro ([Article.class]) le indica a Hibernate que las materialice como entidades gestionadas por la sesión. Los nombres de las columnas del resultado deben coincidir con los del modelo: [select *] es adecuado aquí. La consulta se pasa tal cual al DBMS (líneas 3-6), salvo que el parámetro con nombre [:minPrice] se convierte en un parámetro JDBC ([?]);
- líneas 32-36: un intento de inyección SQL. El valor de [name] se pasa como parámetro: se compara tal cual con la columna [name], y ningún registro coincide (línea 16);
- líneas 40-41: la misma consulta construida por concatenación. El valor de [name] se convierte en código SQL, la condición sigue siendo verdadera (línea 20) y la consulta cuenta los seis artículos (línea 21): se trata de una inyección SQL exitosa. Como en el capítulo 10, una consulta nativa debe contener solo texto constante, con los valores pasados como parámetros;
- líneas 46-54: consultas que devuelven valores únicos ([String], [BigDecimal]): el segundo parámetro de [createNativeQuery] es entonces el tipo del valor. Para varias columnas, se puede especificar un registro (sus componentes reciben las columnas en orden) o usar [Object[].class];
- líneas 59-65: [createNativeMutationQuery] prepara una instrucción de actualización, ejecutada por [executeUpdate], que devuelve el número de filas modificadas. Se ejecuta dentro de una transacción: el método [fromTransaction] de la sesión la abre, la confirma y devuelve el resultado de la lambda;
- líneas 70-79: [doWork] da acceso a la conexión JDBC de la sesión ([java.sql.Connection]) para código JDBC estándar (capítulo 10): llamar a un procedimiento almacenado, usar una función del controlador... El precio del arco, en efecto, se redujo en un 10 % (línea 40).
Una consulta nativa no es portable de un DBMS a otro, e Hibernate no puede verificarla antes de ejecutarla: se reserva para los casos en que HQL no es suficiente. HQL también cubre una gran parte de SQL (uniones de todo tipo, subconsultas, funciones de ventana, [union]...), y permite llamar a una función del DBMS que no reconoce.
11.13. Actualizaciones masivas, modo de solo lectura y lotes
El seguimiento de los cambios tiene un costo: para aumentar el precio de 100 artículos, hay que leer los 100 artículos, modificarlos uno por uno, y la sincronización de la sesión enviará 100 comandos [UPDATE]. Hibernate ofrece varias formas de procesar eficientemente grandes cantidades de filas. El módulo [bulkupdate] las presenta:
Resultados (el final repetitivo se ha abreviado):
Comentarios:
- Líneas 22-26: un comando [update] escrito en HQL, preparado con [createMutationQuery], y ejecutado con [executeUpdate]. Se convierte en un único comando SQL [UPDATE] (líneas 4-6), ejecutado por el DBMS sobre todas las filas afectadas, sin que se cargue ninguna entidad en memoria. El nuevo valor puede depender de la propia fila ([minimumStock * 2]). Un comando de este tipo se ejecuta dentro de una transacción (línea 18);
- líneas 30-32: un aumento del 10 % en los precios bajos. Las constantes de la consulta HQL ([1.1], [150]) se escriben directamente en el texto del comando SQL (líneas 10-11);
- líneas 37-39: una orden HQL [delete] elimina el arco, el único artículo con un precio superior a 550 euros (líneas 14-16);
- Líneas 46-49: una lectura de solo lectura ([setReadOnly(true)]). Las entidades leídas son gestionadas por la sesión, pero esta no conserva su estado original ni las vigila: esto es más rápido y consume menos memoria para datos que se leen sin modificarse (visualización, cálculos). La contrapartida es que cualquier modificación de una entidad de este tipo se ignora (línea 52): la sesión no tiene nada que sincronizar (línea 29), y el comando [commit] no envía ninguna instrucción. También es posible establecer una sesión completa como de solo lectura ([session.setDefaultReadOnly(true)]);
- líneas 59-65: una trampa. Un comando HQL [update] opera directamente sobre la base de datos: no modifica las entidades ya cargadas por la sesión. La bomba gestionada por la sesión conserva su precio anterior (línea 37) hasta que se vuelve a leer con [session.refresh(pump)] (líneas 38-42);
- líneas 71-81: una sesión sin estado ([StatelessSession]), abierta aquí con una transacción mediante [inStatelessTransaction]. No tiene contexto de persistencia: ni caché de primer nivel, ni seguimiento de cambios, ni carga diferida, ni cascadas. Cada operación se solicita explícitamente ([insert], [update], [delete], [get]) y se ejecuta tal cual. Es la herramienta para el procesamiento masivo: importar un archivo grande, recalcular todas las filas de una tabla;
- línea 72: los comandos SQL se enviarán al DBMS en lotes (véase el capítulo 10) de tres: el controlador JDBC transmite tres comandos en un único intercambio con el servidor. El registro muestra las tres primeras entradas [UPDATE], seguidas de la ejecución del lote (línea 58), y termina con el último lote de dos comandos (línea 63). Una aplicación establece el tamaño de lote para todas sus sesiones mediante la propiedad [hibernate.jdbc.batch_size] (normalmente entre 10 y 50). Tenga en cuenta que las inserciones en una tabla cuya clave se genera con [IDENTITY] no pueden agruparse en lotes.
Para el procesamiento masivo con una sesión normal, hay que evitar que su contexto de persistencia acumule entidades: sincronice y vacíe la sesión con regularidad, por ejemplo cada cincuenta registros ([session.flush(); session.clear();]).
11.14. Hibernate e inyección de dependencias: Spring
11.14.1. El [SessionFactory] en el contenedor
Los ejemplos anteriores creaban sus propias sesiones. En una aplicación por capas (capítulo 6), y en todas las aplicaciones Spring, el [SessionFactory] es un objeto del contenedor de inyección de dependencias, al igual que las capas que lo utilizan. Para lograrlo, Spring Framework proporciona lo siguiente en su biblioteca [spring-orm]:
- la clase [LocalSessionFactoryBean], que construye el [SessionFactory] a partir de un origen de datos ([DataSource], capítulo 10) y una lista de entidades;
- la clase [HibernateTransactionManager], un administrador de transacciones que abre una sesión de Hibernate para cada transacción, la asocia con el hilo actual y la cierra al final de la transacción;
- la anotación [@Transactional] (biblioteca [spring-tx]): cuando se aplica a un método, o a una clase para todos sus métodos públicos, indica a Spring que ejecute el método dentro de una transacción, que se confirma si el método termina con normalidad y se revierte si lanza una excepción no capturada. Estas se conocen como transacciones declarativas.
Dentro de un método transaccional, [sessionFactory.getCurrentSession()] devuelve la sesión de la transacción actual. Una capa [dao] puede entonces ser un singleton que recibe el [SessionFactory] (seguro para hilos) y le solicita la sesión actual en cada método: la regla «una sesión por unidad de trabajo, nunca compartida entre hilos» se cumple sin esfuerzo.
11.14.2. El módulo [injection]
El módulo [injection] depende, además del módulo [articles], de Spring y HikariCP:
La configuración de Spring se escribe en Java, usando las anotaciones [@Configuration] y [@Bean] del capítulo 6:
- Línea 18: [@EnableTransactionManagement] habilita la anotación [@Transactional]: Spring reemplazará todo objeto que tenga un método con esta anotación por un proxy que abre y confirma la transacción alrededor de la llamada;
- líneas 22-29: el pool de conexiones HikariCP del capítulo 10. El atributo [destroyMethod] especifica el método que se llamará cuando se cierre el contenedor;
- Líneas 32-41: el [SessionFactory]. Un [LocalSessionFactoryBean] es una fábrica de [SessionFactory]: Spring registra en el contenedor el objeto que crea, y solicitar este bean devuelve un [SessionFactory]. Recibe el pool de conexiones (que reemplaza al pool integrado de Hibernate), las entidades y las propiedades de Hibernate;
- líneas 44-47: el administrador de transacciones;
- líneas 50-53: la capa [dao], que recibe el [SessionFactory].
La capa [dao]:
- línea 10: todos los métodos públicos de la clase son transaccionales;
- líneas 21-23: durante la misma transacción, ¿dos solicitudes de la sesión actual devuelven la misma sesión?
- líneas 26-28: la sesión de la transacción se devuelve al llamador (para el siguiente experimento; esto no se hace en una aplicación real);
- líneas 31-35: una transacción de solo lectura ([readOnly = true]): Spring establece la sesión como de solo lectura y no la sincroniza;
- Líneas 47-53: la venta de una cantidad de un artículo. Si el inventario se vuelve negativo, el método lanza una [IllegalStateException], una excepción no controlada: Spring revierte la transacción. La llamada al método [article] (línea 48) es una llamada interna dentro del objeto que no pasa por el proxy: se ejecuta dentro de la transacción [sell].
El programa principal:
Resultados:
Comentarios:
- Línea 13: el contenedor de Spring, configurado por la clase [Config]. Se cierra al final del bloque [try], que cierra el [SessionFactory] y el pool de conexiones;
- línea 15: el [SessionFactory] creado por Spring; se utiliza para volver a crear la tabla de productos;
- línea 21: una transacción (líneas 3-4): dentro de la misma transacción, la sesión actual sigue siendo la misma (línea 5);
- líneas 23-26: dos llamadas, dos transacciones (líneas 6-9), dos sesiones diferentes; la primera se cierra, ya que su transacción ha terminado (línea 10);
- líneas 28-32: fuera de una transacción, no hay sesión actual: [getCurrentSession] lanza una [HibernateException] (línea 11). Este es el error clásico causado por un método que omitió la anotación [@Transactional];
- línea 36: una transacción de solo lectura (líneas 13-17);
- línea 38: la venta de dos bicicletas. La transacción se confirma y la sincronización de la sesión envía el [UPDATE] (líneas 20-33);
- líneas 40-44: la venta de cincuenta bombas provoca una excepción: Spring revierte la transacción (línea 40), y el [UPDATE] nunca se envía, ya que la sesión no se sincronizó;
- líneas 46-47: estado de la base de datos: el inventario de bicicletas cambió a 8, mientras que el inventario de bombas se mantiene en 10 (líneas 49 y 56).
En una aplicación Spring Boot, todo esto ocurre automáticamente: Spring Boot crea el pool de conexiones, la fábrica (en su forma de Jakarta Persistence, un [EntityManagerFactory]) y el administrador de transacciones a partir del archivo [application.properties]. Spring Data JPA se utiliza a menudo sobre Hibernate; genera la capa [dao] a partir de una simple interfaz: [interface ArticleRepository extends JpaRepository<Article, Integer>] proporciona [findAll], [findById], [save], [delete]..., y un método declarado [List<Article> findByPriceLessThan(BigDecimal price)] se traduce automáticamente en una consulta.
11.15. Aplicación de ejemplo - Versión 7
11.15.1. La arquitectura
La versión 6 de la aplicación de cálculo de impuestos (capítulo 10) leía los tramos del impuesto de una base de datos MySQL mediante JDBC. La versión 7 hace lo mismo con Hibernate. Como en la versión 6, solo cambia la capa [dao]: las capas [business] y [ui] de la versión 5 (capítulo 6) se reutilizan tal cual mediante dependencias de Maven.

El proyecto Maven [TaxV7], ubicado en la carpeta [11-hibernate], consta de dos módulos:
El proyecto padre ([examples.tax:tax-v7:7.0]) está estructurado como el de la versión 5: declara ambos módulos y especifica las versiones de las bibliotecas, incluidas las de los módulos de la versión 5 ([tax-dao], [tax-business], [tax-ui], versión 5.0), que se instalan en el repositorio local de Maven mediante el comando [mvn install] ejecutado en la carpeta [06-architectures/TaxV5].
11.15.2. La capa [dao]
El módulo [tax-dao-hibernate] depende de la capa [dao] de la versión 5, que contiene las entidades de la aplicación ([TaxBracket], [TaxException]) y la interfaz [ITaxDao]:
- líneas 3-6: la capa [dao] de la versión 5;
- líneas 8-19: Hibernate, el controlador JDBC para MySQL y Logback;
- líneas 25-31: la clase ejecutada por [mvn exec:java] en el directorio del módulo: crea la base de datos, como veremos.
El registro [TaxBracket] de la versión 5 no puede ser una entidad de Hibernate: es un registro, de solo lectura, y no tiene identificador. No se modifica porque forma parte del contrato entre las capas, compartido por todas las versiones. Creamos una entidad específica de la capa [dao], cuyo papel es representar una fila de la tabla:
- fila 3: la tabla [brackets];
- filas 7-9: la clave primaria, que también se utiliza para ordenar los tramos;
- filas 11-18: las tres columnas, con tipos de datos [decimal] apropiados: el límite y el coeficiente ([coeffN]) son importes con dos decimales, y [coeffR] es una tasa con cuatro decimales. Los nombres de las columnas están en minúsculas;
- Líneas 23-27: un constructor, que se usará para poblar la tabla. La entidad no tiene accesores: el resto de la aplicación nunca la ve.
La clase [HibernateTax] implementa la interfaz [ITaxDao]:
- líneas 14-15: los códigos de error de esta implementación, como en [FileTax] y [JsonTax];
- línea 21: la capa [dao] recibe la URL de la base de datos, junto con el usuario y su contraseña. Lee los tramos de una vez por todas en su constructor; será un singleton;
- líneas 23-27: un [SessionFactory] de corta duración, que existe solo el tiempo necesario para leer la tabla, y que se cierra de inmediato. Como la capa accede a la base de datos una sola vez, no hay necesidad de conservarlo; una capa [dao] que accediera a la base de datos en cada llamada recibiría, en cambio, un [SessionFactory] creado una vez por todas, como en el ejemplo anterior;
- líneas 29-32: lectura de la tabla en el orden de la clave primaria. La consulta es una proyección sobre el registro [TaxBracket]: Hibernate solicita al DBMS únicamente las tres columnas pertinentes y crea directamente los objetos de la aplicación, sin pasar por las entidades [Bracket];
- Líneas 33-37: un error de Hibernate o del DBMS (base de datos inaccesible, tabla inexistente, etc.) se manifiesta como una [PersistenceException] (la clase base de las excepciones de Jakarta Persistence, de la que derivan las excepciones de Hibernate). Como en otras implementaciones, se encapsula dentro de una [TaxException]. La excepción puede producirse desde la creación del [SessionFactory] (línea 27), que se conecta al servidor: la cláusula [catch] de una instrucción [try] con recursos también intercepta las excepciones lanzadas durante la creación de los recursos;
- líneas 39-41: una tabla vacía también es un error: la capa [business] requiere al menos un tramo.
11.15.3. La base de datos
La base de datos [hbtaxes] es creada por la clase [CreateDatabase]. Para evitar reescribir los tramos del baremo, reutiliza los de la clase [HardwiredTax] de la versión 5:
- Línea 14: la base de datos [hbtaxes], creada por MySQL si no existe;
- Línea 17: muestra las órdenes SQL, sin formato;
- línea 19: la tabla se elimina y luego se vuelve a crear al crear el [SessionFactory];
- líneas 22-26: una entidad [Bracket] por cada tramo de la clase [HardwiredTax], persistida dentro de una transacción.
El módulo también contiene un archivo llamado [logback.xml], utilizado por [CreateDatabase] y por la aplicación, que solo deja pasar los errores:
- línea 10: los errores del DBMS, que Hibernate registra antes de lanzar una excepción, no se muestran: la aplicación los informa por sí misma;
- Línea 11: los demás registros solo incluyen errores.
Ejecución:
Verificamos el contenido de la tabla:
Encontramos los tramos del baremo, con el último con un límite igual a cero (la capa [business] no lo utiliza, ya que toma el último tramo cuando ningún otro se aplica).
Para crear la base de datos en su propio sistema:
- inicie MySQL (en Laragon, vea el apéndice; usuario [root] sin contraseña);
- si aún no lo ha hecho, instale los módulos de la versión 5 en el repositorio local de Maven: [mvn install] en la carpeta [06-architectures/TaxV5];
- compile la versión 7: [mvn install] en la carpeta [11-hibernate/TaxV7];
- vaya a la carpeta [11-hibernate/TaxV7/tax-dao-hibernate] e ingrese el comando [mvn exec:java].
Se crea entonces la base de datos [hbtaxes] , con su tabla [brackets] poblada. Si el comando falla, verifique que MySQL esté en ejecución y que la URL de la clase [CreateDatabase] corresponda a su servidor (puerto 3306, usuario [root], contraseña vacía). Alternativamente, si lo prefiere, puede crear la tabla y sus filas mediante un script SQL, como se describe en el capítulo 10.
11.15.4. Integración de las capas
El módulo [tax-ui-hibernate] combina las siguientes capas:
- líneas 3-10: las capas [business] y [ui] de la versión 5. El módulo [tax-ui] contiene el programa principal de la versión 5; aquí se utiliza como biblioteca, en concreto por su clase [Dialog];
- líneas 12-15: la nueva capa [dao], que incluye Hibernate, el controlador JDBC y Logback;
- líneas 17-20: el contenedor de Spring;
- línea 30: la clase principal.
El archivo de configuración [tax-hibernate.properties], ubicado en la carpeta del módulo, especifica la base de datos:
El archivo [tax-hibernate-error.properties] especifica una base de datos llamada [hbtaxesmissing], que no existe:
El programa principal es el de la versión 5, en el que solo cambia la composición de la capa [dao]:
- línea 15: la clase no se llama [Main]: el módulo [tax-ui] de la versión 5, del que dependemos, ya contiene una clase llamada [tax.ui.Main];
- Líneas 29-34: la URL de la base de datos, obligatoria, el nombre de usuario y la contraseña, leídos de la configuración;
- línea 39: la capa [dao] es un [HibernateTax], creado por una lambda que le pasa los parámetros de la base de datos;
- Línea 41: la capa [business] de la versión 5: el contenedor le pasará la capa [dao] a su constructor;
- Línea 54: el cuadro de diálogo de la versión 5.
11.15.5. Ejecuciones
Se conservan los valores de referencia de las versiones anteriores: 4282 euros para una pareja casada con dos hijos y unos ingresos conjuntos de 60 000 euros; 2959 euros para una familia con tres hijos; y 11 519 euros para una persona soltera sin hijos.
Con el archivo de configuración [tax-hibernate-error.properties], que hace referencia a una base de datos inexistente:
- línea 12: la excepción original, lanzada por el controlador JDBC;
- líneas 8 y 10: las excepciones de Hibernate que la encapsulan: el error se produjo durante la creación del [SessionFactory], cuando Hibernate se conectó al servidor para determinar su versión;
- línea 6: la capa [dao] envolvió el error en una [TaxException];
- Línea 4: el contenedor de Spring, que estaba creando la capa [dao], encapsuló a su vez la excepción dentro de una [BeanCreationException], que fue mostrada por el programa principal.
Cambiar de DBMS equivale a cambiar la URL de la base de datos y la dependencia del controlador JDBC: Hibernate selecciona automáticamente el dialecto SQL según el DBMS que encuentra, y el código de la clase [HibernateTax], escrito en HQL, permanece sin cambios. Solo es necesario rehacer la creación de la base de datos (que depende de los tipos de columna), lo cual la clase [CreateDatabase] hace sin más cambios que el de su URL.
11.16. Conclusión: ¿JDBC, JdbcClient, jOOQ o Hibernate?
Ahora disponemos de dos formas de acceder a una base de datos: JDBC (capítulo 10) y Hibernate (este capítulo). Existen otros enfoques intermedios que se utilizan ampliamente:
- JdbcClient, de Spring Framework (biblioteca [spring-jdbc]), agrega a JDBC una API flexible que ejecuta una consulta SQL escrita a mano y transforma automáticamente las filas del resultado en objetos: [jdbcClient.sql("select * from articles where price > :price").param("price", 200).query(Article.class).list()]. Usted escribe el SQL; Spring se encarga de los parámetros y copia las columnas en los objetos (incluidos los registros). Es un «micro-ORM»;
- jOOQ genera, a partir del esquema de la base de datos, clases que permiten escribir en Java un SQL verificado por el compilador: [dsl.selectFrom(ARTICLES).where(ARTICLES.PRICE.gt(price)).fetch()]. Se conserva el control total sobre el SQL, con la seguridad de la verificación de tipos.
Fortalezas | Debilidades | |
JDBC | control total sobre el SQL; rendimiento; sin dependencias | mucho código repetitivo (parámetros, lectura de columnas); SQL en cadenas, no verificado por el compilador |
JdbcClient | SQL escrito a mano, sin código de copiar y pegar; rendimiento similar al de JDBC | Sin seguimiento de cambios ni generación de [INSERT]/[UPDATE]; SQL no verificado |
jOOQ | SQL verificado por el compilador; todas las funciones del DBMS | Generación de código con cada cambio de esquema; sin seguimiento de cambios; se requiere una licencia de pago para ciertas versiones comerciales de DBMS |
Hibernate | modelo orientado a objetos; seguimiento de cambios; relaciones; HQL y API Criteria; estándar Jakarta Persistence; independiente del DBMS | una capa adicional que comprender (sesiones, estados, carga diferida); SQL generado que hay que vigilar; menos adecuado para el procesamiento masivo complejo |
Se pueden sugerir las siguientes pautas:
- Hibernate (a menudo mediante Spring Data JPA) es adecuado para la mayoría de las aplicaciones empresariales: un modelo de entidades interconectadas, operaciones de lectura y actualización de entidades, y un esquema que evoluciona con la aplicación. Es la opción predeterminada para las aplicaciones Spring Boot;
- JDBC, JdbcClient o jOOQ son adecuados cuando se desea un control preciso sobre el código SQL que se ejecuta: consultas estadísticas complejas, procedimientos almacenados, procesamiento de volúmenes muy grandes o una base de datos existente con un esquema poco adecuado para un modelo orientado a objetos;
- Estos enfoques pueden combinarse: una aplicación puede usar Hibernate en su mayor parte y código SQL escrito a mano, en consultas nativas, con [JdbcClient] o con JDBC ([doWork]), para unas pocas consultas críticas.
En cualquier caso, el ORM no elimina la necesidad de comprender SQL y el funcionamiento del DBMS: el registro de los comandos SQL ejecutados, que hemos mostrado a lo largo de este capítulo, es la herramienta principal para verificar lo que Hibernate realmente está haciendo.
Para profundizar, la documentación de Hibernate es exhaustiva, y su guía introductoria es el mejor punto de partida: Hibernate ORM - documentation. La especificación Jakarta Persistence es publicada por la Eclipse Foundation: Jakarta Persistence.