Skip to content

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:

Image

  • [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]:

11-hibernate/
  pom.xml                 the parent project
  tools/                  library: the compact SQL log
  articles/               library: the Article entity and the [hbarticles] database
  first/                  a first example
  model/                  the model: annotations, XML file, creation script
  crud/                   persist, find, merge, remove
  hql/                    HQL queries
  criteria/               Criteria API queries
  relations/              relationships between entities
  clients/                the evolution of the database schema
  async/                  Hibernate and virtual threads
  transactions/           transactions
  concurrency/            optimistic concurrency
  rawsql/                 native SQL
  bulkupdate/             bulk updates
  injection/              Hibernate and Spring
  TaxV7/                  the tax calculation application, version 7 (separate project)

El proyecto padre fija las versiones de las bibliotecas y de las extensiones de Maven para todos los módulos:

<?xml version="1.0" encoding="UTF-8"?>
<!-- los ejemplos del capítulo 11: Hibernate; un módulo Maven por ejemplo -->
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>examples.hibernate</groupId>
    <artifactId>hibernate</artifactId>
    <version>1.0</version>
    <packaging>pom</packaging>

    <!-- los módulos, en el orden de sus dependencias -->
    <modules>
        <module>tools</module>
        <module>articles</module>
        <module>first</module>
        <module>model</module>
        <module>crud</module>
        <module>hql</module>
        <module>criteria</module>
        <module>relations</module>
        <module>clients</module>
        <module>async</module>
        <module>transactions</module>
        <module>concurrency</module>
        <module>rawsql</module>
        <module>bulkupdate</module>
        <module>injection</module>
    </modules>

    <properties>
        <maven.compiler.release>25</maven.compiler.release>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>

    <!-- las versiones de las bibliotecas, comunes a todos los módulos -->
    <dependencyManagement>
        <dependencies>
            <!-- las dos bibliotecas comunes del capítulo -->
            <dependency>
                <groupId>examples.hibernate</groupId>
                <artifactId>tools</artifactId>
                <version>1.0</version>
            </dependency>
            <dependency>
                <groupId>examples.hibernate</groupId>
                <artifactId>articles</artifactId>
                <version>1.0</version>
            </dependency>
            <!-- Hibernate ORM (Jakarta Persistence 3.2) -->
            <dependency>
                <groupId>org.hibernate.orm</groupId>
                <artifactId>hibernate-core</artifactId>
                <version>7.4.5.Final</version>
            </dependency>
            <!-- el controlador JDBC de MySQL -->
            <dependency>
                <groupId>com.mysql</groupId>
                <artifactId>mysql-connector-j</artifactId>
                <version>9.7.0</version>
            </dependency>
            <!-- registro de eventos (logging): Logback (a través de SLF4J) -->
            <dependency>
                <groupId>ch.qos.logback</groupId>
                <artifactId>logback-classic</artifactId>
                <version>1.5.38</version>
            </dependency>
            <!-- Spring Framework: inyección de dependencias y transacciones -->
            <dependency>
                <groupId>org.springframework</groupId>
                <artifactId>spring-context</artifactId>
                <version>7.0.9</version>
            </dependency>
            <dependency>
                <groupId>org.springframework</groupId>
                <artifactId>spring-orm</artifactId>
                <version>7.0.9</version>
            </dependency>
            <!-- el grupo de conexiones HikariCP -->
            <dependency>
                <groupId>com.zaxxer</groupId>
                <artifactId>HikariCP</artifactId>
                <version>7.0.2</version>
            </dependency>
        </dependencies>
    </dependencyManagement>

    <build>
        <pluginManagement>
            <plugins>
                <plugin>
                    <groupId>org.apache.maven.plugins</groupId>
                    <artifactId>maven-compiler-plugin</artifactId>
                    <version>3.15.0</version>
                    <configuration>
                        <parameters>true</parameters>
                        <compilerArgs>
                            <arg>-Xlint:all</arg>
                        </compilerArgs>
                    </configuration>
                </plugin>
                <plugin>
                    <groupId>org.apache.maven.plugins</groupId>
                    <artifactId>maven-surefire-plugin</artifactId>
                    <version>3.5.6</version>
                </plugin>
                <!-- mvn exec:java ejecuta la clase ${exec.mainClass}, definida por cada módulo -->
                <plugin>
                    <groupId>org.codehaus.mojo</groupId>
                    <artifactId>exec-maven-plugin</artifactId>
                    <version>3.5.1</version>
                    <configuration>
                        <mainClass>${exec.mainClass}</mainClass>
                    </configuration>
                </plugin>
            </plugins>
        </pluginManagement>
    </build>
</project>
  • 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:

<?xml version="1.0" encoding="UTF-8"?>
<!-- un primer ejemplo: una entidad, una base de datos, algunas sentencias SQL generadas por Hibernate -->
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <parent>
        <groupId>examples.hibernate</groupId>
        <artifactId>hibernate</artifactId>
        <version>1.0</version>
    </parent>

    <artifactId>first</artifactId>

    <properties>
        <!-- el programa ejecutado por mvn exec:java -->
        <exec.mainClass>first.Main</exec.mainClass>
    </properties>

    <dependencies>
        <!-- Hibernate y el controlador JDBC de MySQL -->
        <dependency>
            <groupId>org.hibernate.orm</groupId>
            <artifactId>hibernate-core</artifactId>
        </dependency>
        <dependency>
            <groupId>com.mysql</groupId>
            <artifactId>mysql-connector-j</artifactId>
        </dependency>
        <!-- Logback: recibe el registro de Hibernate -->
        <dependency>
            <groupId>ch.qos.logback</groupId>
            <artifactId>logback-classic</artifactId>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.codehaus.mojo</groupId>
                <artifactId>exec-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>
  • 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:

1
2
3
4
> cd 11-hibernate
> mvn install
> cd first
> mvn compile exec:java

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:

package first;

import jakarta.persistence.Entity;
import jakarta.persistence.GeneratedValue;
import jakarta.persistence.GenerationType;
import jakarta.persistence.Id;
import java.math.BigDecimal;

// un artículo de la tienda: una clase Java ordinaria, más algunas anotaciones
@Entity
public class Article {

    // la clave primaria, generada por el SGBD
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Integer id;
    // las demás columnas de la tabla
    private String name;
    private BigDecimal price;
    private int currentStock;
    private int minimumStock;

    // el constructor sin parámetros que exige Hibernate
    protected Article() {
    }

    // el constructor usado por el programa
    public Article(String name, BigDecimal price, int currentStock, int minimumStock) {
        this.name = name;
        this.price = price;
        this.currentStock = currentStock;
        this.minimumStock = minimumStock;
    }

    // visualización
    @Override
    public String toString() {
        return "[%d, %s, %.2f, %d, %d]".formatted(id, name, price, currentStock, minimumStock);
    }
}
  • 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

package first;

import java.math.BigDecimal;
import java.util.List;
import org.hibernate.Session;
import org.hibernate.SessionFactory;
import org.hibernate.Transaction;
import org.hibernate.jpa.HibernatePersistenceConfiguration;

public class Main {

    public static void main(String[] args) {
        // el SessionFactory: Hibernate configurado para la base de datos [hbfirst]
        try (SessionFactory sessionFactory = new HibernatePersistenceConfiguration("first")
                // las entidades
                .managedClass(Article.class)
                // la base de datos; MySQL la crea si no existe
                .jdbcUrl("jdbc:mysql://localhost:3306/hbfirst?createDatabaseIfNotExist=true")
                .jdbcCredentials("root", "")
                // visualización de las sentencias SQL, con formato, sin colores
                .showSql(true, true, false)
                .createEntityManagerFactory()) {

            // las tablas se eliminan y luego se vuelven a crear a partir de las entidades
            sessionFactory.getSchemaManager().drop(false);
            sessionFactory.getSchemaManager().create(false);

            // agregar tres artículos, en una transacción
            try (Session session = sessionFactory.openSession()) {
                Transaction transaction = session.beginTransaction();
                IO.println("--- persist");
                session.persist(new Article("bike", BigDecimal.valueOf(500), 10, 5));
                session.persist(new Article("pump", BigDecimal.valueOf(10), 10, 2));
                session.persist(new Article("bow", BigDecimal.valueOf(600), 4, 1));
                IO.println("--- commit");
                transaction.commit();
            }

            // lectura de la tabla, con una sesión nueva
            IO.println("--- reading the articles");
            try (Session session = sessionFactory.openSession()) {
                List<Article> articles = session
                        .createSelectionQuery("from Article order by name", Article.class)
                        .getResultList();
                for (Article article : articles) {
                    IO.println(article);
                }
            }
        }
    }
}
  • 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):

<?xml version="1.0" encoding="UTF-8"?>
<!-- configuración de Logback: mensajes informativos de Hibernate, cada uno en una línea -->
<configuration>
    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>%-5level %logger - %msg%n</pattern>
        </encoder>
    </appender>
    <root level="INFO">
        <appender-ref ref="CONSOLE"/>
    </root>
</configuration>

Resultados:

> mvn compile exec:java
INFO  org.hibernate.orm.jpa - HHH008540: Processing PersistenceUnitInfo [name: first]
INFO  org.hibernate.orm.core - HHH000001: Hibernate ORM core version 7.4.5.Final
WARN  org.hibernate.orm.connections.pooling - HHH10001002: Using built-in connection pool (not intended for production use)
INFO  org.hibernate.orm.connections.pooling - HHH10001005: Database info:
    Database JDBC URL [jdbc:mysql://localhost:3306/hbfirst?createDatabaseIfNotExist=true]
    Database driver: MySQL Connector/J
    Database dialect: MySQLDialect
    Database version: 8.0.46
    Default catalog/schema: hbfirst/undefined
    Autocommit mode: false
    Isolation level: REPEATABLE_READ
    JDBC fetch size: none
    Pool: DriverManagerConnectionProvider
    Minimum pool size: 1
    Maximum pool size: 20
INFO  org.hibernate.orm.core - HHH000489: No JTA platform available (set 'hibernate.transaction.jta.platform' to enable JTA platform integration)
Hibernate:
    drop table if exists Article
Hibernate:
    create table Article (
        id integer not null auto_increment,
        currentStock integer not null,
        minimumStock integer not null,
        name varchar(255),
        price decimal(38,2),
        primary key (id)
    ) engine=InnoDB
--- persist
Hibernate:
    insert
    into
        Article
        (currentStock, minimumStock, name, price)
    values
        (?, ?, ?, ?)
Hibernate:
    insert
    into
        Article
        (currentStock, minimumStock, name, price)
    values
        (?, ?, ?, ?)
Hibernate:
    insert
    into
        Article
        (currentStock, minimumStock, name, price)
    values
        (?, ?, ?, ?)
--- commit
--- reading the articles
Hibernate:
    select
        a1_0.id,
        a1_0.currentStock,
        a1_0.minimumStock,
        a1_0.name,
        a1_0.price
    from
        Article a1_0
    order by
        a1_0.name
[1, bike, 500.00, 10, 5]
[3, bow, 600.00, 4, 1]
[2, pump, 10.00, 10, 2]

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:

package model;

import jakarta.persistence.Column;
import jakarta.persistence.Entity;
import jakarta.persistence.GeneratedValue;
import jakarta.persistence.GenerationType;
import jakarta.persistence.Id;
import jakarta.persistence.Table;
import jakarta.persistence.Transient;
import java.math.BigDecimal;
import java.time.LocalDate;

// una entidad configurada mediante anotaciones
@Entity
@Table(name = "products")
public class Product {

    // la clave primaria: @Id, sea cual sea su nombre
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Integer code;

    // cadena obligatoria de 50 caracteres como máximo
    @Column(nullable = false, length = 50)
    private String name;

    // cadena opcional (columna NULL) de 200 caracteres como máximo
    @Column(length = 200)
    private String description;

    // nombre y tipo SQL de la columna fijados explícitamente
    @Column(name = "price_excl_tax", nullable = false, precision = 10, scale = 2)
    private BigDecimal priceExclTax;

    // una fecha opcional: un objeto puede ser null
    private LocalDate withdrawalDate;

    // un campo sin columna
    @Transient
    private boolean selected;

    protected Product() {
    }

    // un método nunca se guarda: aquí Hibernate accede a los campos, no a los métodos
    public BigDecimal getPriceInclTax() {
        return priceExclTax.multiply(new BigDecimal("1.2"));
    }

    public boolean isSelected() {
        return selected;
    }
}
  • 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:

package model;

import java.time.LocalDateTime;

// una clase sin ninguna anotación: su mapeo se describe en el archivo [supplier.orm.xml]
public class Supplier {

    private Integer number;
    private String companyName;
    private String phone;
    private LocalDateTime creationDate;

    protected Supplier() {
    }

    public Supplier(String companyName, String phone) {
        this.companyName = companyName;
        this.phone = phone;
    }
}

Su mapeo a la tabla se describe en un archivo XML, ubicado en la carpeta [src/main/resources/META-INF] del módulo:

<?xml version="1.0" encoding="UTF-8"?>
<!-- el mapeo de la clase [Supplier] a su tabla, descrito en XML (Jakarta Persistence 3.2) -->
<entity-mappings xmlns="https://jakarta.ee/xml/ns/persistence/orm"
                 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                 xsi:schemaLocation="https://jakarta.ee/xml/ns/persistence/orm
                                     https://jakarta.ee/xml/ns/persistence/orm/orm_3_2.xsd"
                 version="3.2">
    <entity class="model.Supplier" access="FIELD">
        <table name="suppliers">
            <!-- un índice único: dos proveedores no pueden tener el mismo nombre de empresa -->
            <index name="ix_suppliers_company_name" column-list="companyName" unique="true"/>
        </table>
        <attributes>
            <id name="number">
                <generated-value strategy="IDENTITY"/>
            </id>
            <basic name="companyName">
                <column nullable="false" length="60"/>
            </basic>
            <basic name="phone">
                <column name="tel" length="20"/>
            </basic>
            <!-- un valor por defecto calculado por el SGBD: Hibernate nunca escribe esta columna -->
            <basic name="creationDate">
                <column nullable="false" insertable="false" updatable="false"
                        column-definition="datetime(6) default current_timestamp(6)"/>
            </basic>
        </attributes>
    </entity>
</entity-mappings>
  • 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:

package model;

import jakarta.persistence.metamodel.Attribute;
import jakarta.persistence.metamodel.EntityType;
import jakarta.persistence.metamodel.SingularAttribute;
import java.io.StringWriter;
import org.hibernate.SessionFactory;
import org.hibernate.boot.model.naming.PhysicalNamingStrategySnakeCaseImpl;
import org.hibernate.cfg.AvailableSettings;
import org.hibernate.jpa.HibernatePersistenceConfiguration;

public class Main {

    public static void main(String[] args) {
        // el script de creación de tablas se escribirá en este objeto
        StringWriter script = new StringWriter();
        // un SessionFactory que nunca se conecta al servidor
        try (SessionFactory sessionFactory = new HibernatePersistenceConfiguration("model")
                // una entidad anotada y un mapeo descrito en XML
                .managedClass(Product.class)
                .mappingFile("META-INF/supplier.orm.xml")
                // sin base de datos: se indican el SGBD y su versión, para el dialecto SQL
                .property(AvailableSettings.JAKARTA_HBM2DDL_DB_NAME, "MySQL")
                .property(AvailableSettings.JAKARTA_HBM2DDL_DB_MAJOR_VERSION, "8")
                .property(AvailableSettings.ALLOW_METADATA_ON_BOOT, false)
                // los nombres de columna en "snake case": companyName -> company_name
                .property(AvailableSettings.PHYSICAL_NAMING_STRATEGY,
                        PhysicalNamingStrategySnakeCaseImpl.class.getName())
                // el script de creación de tablas, sin ejecutarlo
                .property(AvailableSettings.JAKARTA_HBM2DDL_SCRIPTS_ACTION, "create")
                .property(AvailableSettings.JAKARTA_HBM2DDL_SCRIPTS_CREATE_TARGET, script)
                .property(AvailableSettings.HBM2DDL_DELIMITER, ";")
                .property(AvailableSettings.FORMAT_SQL, true)
                .createEntityManagerFactory()) {

            // el modelo construido por Hibernate: entidades y atributos (Jakarta Persistence API)
            for (EntityType<?> entity : sessionFactory.getMetamodel().getEntities()) {
                IO.println("entity %s (%s)".formatted(entity.getName(), entity.getJavaType().getName()));
                for (Attribute<?, ?> attribute : entity.getAttributes()) {
                    boolean id = attribute instanceof SingularAttribute<?, ?> s && s.isId();
                    IO.println("  %-14s %s%s".formatted(attribute.getName(),
                            attribute.getJavaType().getSimpleName(), id ? " (identifier)" : ""));
                }
            }
        }
        // el script de creación de tablas, sin la sangría de 4 espacios de sus líneas
        IO.println("--- creation script");
        script.toString().strip().lines()
                .map(line -> line.startsWith("    ") ? line.substring(4) : line)
                .forEach(line -> IO.println(line.stripTrailing()));
    }
}
  • 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:

> mvn compile exec:java
WARN  connection - HHH102003: No appropriate connection provider encountered; client must supply connections
entity Supplier (model.Supplier)
  number         Integer (identifier)
  companyName    String
  creationDate   LocalDateTime
  phone          String
entity Product (model.Product)
  code           Integer (identifier)
  description    String
  name           String
  priceExclTax   BigDecimal
  withdrawalDate LocalDate
--- creation script
create table products (
    code integer not null auto_increment,
    price_excl_tax decimal(10,2) not null,
    withdrawal_date date,
    name varchar(50) not null,
    description varchar(200),
    primary key (code)
) engine=InnoDB;

create table suppliers (
    number integer not null auto_increment,
    creation_date datetime(6) default current_timestamp(6) not null,
    tel varchar(20),
    company_name varchar(60) not null,
    primary key (number)
) engine=InnoDB;

alter table suppliers
   add constraint ix_suppliers_company_name unique (company_name);
  • 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:

package tools;

import ch.qos.logback.classic.Level;
import ch.qos.logback.classic.Logger;
import ch.qos.logback.classic.spi.ILoggingEvent;
import ch.qos.logback.core.LayoutBase;
import java.util.ArrayList;
import java.util.List;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
import java.util.stream.Collectors;
import java.util.stream.Stream;
import org.slf4j.LoggerFactory;

// un registro compacto de las sentencias SQL ejecutadas por Hibernate: un layout de Logback
public class SqlLog extends LayoutBase<ILoggingEvent> {

    // los loggers de Hibernate utilizados
    public static final String SQL = "org.hibernate.SQL";
    public static final String PARAMETERS = "org.hibernate.orm.jdbc.bind";
    public static final String TRANSACTIONS = "org.hibernate.orm.resource.jdbc";
    public static final String ERRORS = "org.hibernate.orm.jdbc.error";
    public static final String BATCHES = "org.hibernate.orm.jdbc.batch";

    // la longitud máxima de una cláusula escrita en una sola línea
    private static final int WIDTH = 100;

    // la ejecución de un lote de sentencias SQL: "Executing JDBC batch (3 / 3) - [...]"
    private static final Pattern BATCH = Pattern.compile("Executing JDBC batch \\((\\d+) / \\d+\\).*");

    // un parámetro ligado a una sentencia SQL: "binding parameter (1:VARCHAR) <- [bike]"
    private static final Pattern PARAMETER =
            Pattern.compile("binding parameter \\((\\d+):\\w+\\) <- \\[(.*)]");

    // layout de un mensaje: se devuelve el texto que se debe escribir ("": no se escribe nada)
    @Override
    public String doLayout(ILoggingEvent event) {
        String message = event.getFormattedMessage();
        return switch (event.getLoggerName()) {
            case SQL -> sqlStatement(message);
            case PARAMETERS -> parameter(message);
            case TRANSACTIONS -> transaction(message);
            case ERRORS -> error(message);
            case BATCHES -> batch(message);
            default -> "";
        };
    }

    // la sentencia SQL formateada por Hibernate, hecha más compacta: una línea por cláusula (select, from...)
    private static String sqlStatement(String sql) {
        // las líneas no vacías, sin los espacios finales
        List<String> lines = sql.lines().map(String::stripTrailing).filter(l -> !l.isBlank()).toList();
        // las cláusulas: una línea de nivel superior (la menos sangrada) y las líneas que la siguen
        int indent = lines.stream().mapToInt(SqlLog::indent).min().orElse(0);
        List<List<String>> clauses = new ArrayList<>();
        for (String line : lines) {
            if (clauses.isEmpty() || indent(line) == indent) {
                clauses.add(new ArrayList<>());
            }
            clauses.getLast().add(line.substring(indent));
        }
        // cada cláusula se escribe en una línea, si no es demasiado larga
        StringBuilder text = new StringBuilder();
        String start = "";
        for (List<String> clause : clauses) {
            String line = start + clause.stream().map(String::strip).collect(Collectors.joining(" "));
            if (line.equals("insert") || line.equals("delete")) {
                // [insert into ...], [delete from ...]: una sola línea
                start = line + " ";
                continue;
            }
            if (line.length() <= WIDTH) {
                text.append("    SQL> ").append(line).append('\n');
            } else {
                // cláusula demasiado larga: se conservan las líneas de Hibernate
                for (int i = 0; i < clause.size(); i++) {
                    text.append("    SQL> ").append(i == 0 ? start : "").append(clause.get(i)).append('\n');
                }
            }
            start = "";
        }
        return text.toString();
    }

    // el número de espacios al inicio de la línea
    private static int indent(String line) {
        return line.length() - line.stripLeading().length();
    }

    // el valor de un parámetro de la sentencia SQL
    private static String parameter(String message) {
        Matcher m = PARAMETER.matcher(message);
        return m.matches() ? "    SQL> -- parameter " + m.group(1) + " = " + m.group(2) + "\n" : "";
    }

    // inicio, confirmación y reversión de las transacciones (los demás mensajes se ignoran)
    private static String transaction(String message) {
        if (message.startsWith("HHH10003002")) {
            return "    SQL> -- start of transaction\n";
        }
        if (message.startsWith("HHH10003004")) {
            return "    SQL> -- transaction committed (COMMIT)\n";
        }
        if (message.startsWith("HHH10003006")) {
            return "    SQL> -- transaction rolled back (ROLLBACK)\n";
        }
        return "";
    }

    // el error informado por el SGBD (la línea que da sus códigos de error se ignora)
    private static String error(String message) {
        return message.startsWith("HHH000247") ? "" : "    SQL> -- failure: " + message + "\n";
    }

    // la ejecución de un lote de sentencias SQL (los demás mensajes se ignoran)
    private static String batch(String message) {
        Matcher m = BATCH.matcher(message);
        return m.matches() ? "    SQL> -- execution of a batch of " + m.group(1) + " statement(s)\n" : "";
    }

    // ejecuta una acción sin registro SQL
    public static void withoutLog(Runnable action) {
        List<Logger> loggers = Stream.of(SQL, PARAMETERS, TRANSACTIONS, ERRORS, BATCHES)
                .map(SqlLog::logger)
                .toList();
        // los niveles actuales, restablecidos al final
        List<Level> levels = loggers.stream().map(Logger::getLevel).toList();
        loggers.forEach(l -> l.setLevel(Level.OFF));
        try {
            action.run();
        } finally {
            for (int i = 0; i < loggers.size(); i++) {
                loggers.get(i).setLevel(levels.get(i));
            }
        }
    }

    // el logger de Logback con el nombre dado
    private static Logger logger(String name) {
        return (Logger) LoggerFactory.getLogger(name);
    }
}
  • 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:

<?xml version="1.0" encoding="UTF-8"?>
<!-- configuración de Logback para los ejemplos del capítulo -->
<configuration>

    <!-- el registro SQL compacto: layout de la clase [tools.SqlLog] -->
    <appender name="SQL" class="ch.qos.logback.core.ConsoleAppender">
        <encoder class="ch.qos.logback.core.encoder.LayoutWrappingEncoder">
            <layout class="tools.SqlLog"/>
        </encoder>
    </appender>

    <!-- los demás mensajes: nivel, nombre corto del logger, texto -->
    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>%-5level %logger{0} - %msg%n</pattern>
        </encoder>
    </appender>

    <!-- las sentencias SQL (DEBUG), sus parámetros, las transacciones, los lotes (TRACE) y los errores -->
    <logger name="org.hibernate.SQL" level="DEBUG" additivity="false">
        <appender-ref ref="SQL"/>
    </logger>
    <logger name="org.hibernate.orm.jdbc.bind" level="TRACE" additivity="false">
        <appender-ref ref="SQL"/>
    </logger>
    <logger name="org.hibernate.orm.resource.jdbc" level="TRACE" additivity="false">
        <appender-ref ref="SQL"/>
    </logger>
    <logger name="org.hibernate.orm.jdbc.batch" level="TRACE" additivity="false">
        <appender-ref ref="SQL"/>
    </logger>
    <logger name="org.hibernate.orm.jdbc.error" level="WARN" additivity="false">
        <appender-ref ref="SQL"/>
    </logger>

    <!-- el grupo de conexiones integrado de Hibernate basta para nuestros ejemplos: se silencia su advertencia -->
    <logger name="org.hibernate.orm.connections.pooling" level="ERROR"/>

    <!-- eliminar las tablas de una base de datos vacía provoca errores inofensivos: se silencian -->
    <logger name="org.hibernate.tool.schema" level="OFF"/>

    <!-- todos los demás loggers: solo advertencias y errores -->
    <root level="WARN">
        <appender-ref ref="CONSOLE"/>
    </root>
</configuration>
  • 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]:

package articles;

import jakarta.persistence.Column;
import jakarta.persistence.Entity;
import jakarta.persistence.GeneratedValue;
import jakarta.persistence.GenerationType;
import jakarta.persistence.Id;
import jakarta.persistence.Table;
import jakarta.persistence.UniqueConstraint;
import java.math.BigDecimal;

// un artículo de la tienda, con las anotaciones que especifican su tabla
@Entity
@Table(name = "articles",
        uniqueConstraints = @UniqueConstraint(name = "uk_articles_name", columnNames = "name"))
public class Article {

    // clave primaria, generada por el SGBD (AUTO_INCREMENT)
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Integer id;

    // nombre del artículo: obligatorio, 30 caracteres como máximo, único (ver @Table)
    @Column(nullable = false, length = 30)
    private String name;

    // precio: 10 dígitos, de los cuales 2 después del punto decimal
    @Column(nullable = false, precision = 10, scale = 2)
    private BigDecimal price;

    // stock actual y stock mínimo por debajo del cual hay que reabastecer
    private int currentStock;
    private int minimumStock;

    // el constructor sin parámetros que exige Hibernate (puede ser protected)
    protected Article() {
    }
  • 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]:

package articles;

import java.math.BigDecimal;
import org.hibernate.SessionFactory;
import org.hibernate.cfg.AvailableSettings;
import org.hibernate.jpa.HibernatePersistenceConfiguration;
import tools.SqlLog;

// la base de datos [hbarticles]: configuración de Hibernate e inicialización de la base de datos
public final class BaseArticles {

    // la base de datos; MySQL la crea si no existe (createDatabaseIfNotExist)
    public static final String URL = "jdbc:mysql://localhost:3306/hbarticles?createDatabaseIfNotExist=true";
    public static final String USER = "root";
    public static final String PASSWORD = "";

    // clase de utilidad: sin instancias
    private BaseArticles() {
    }

    // la configuración de Hibernate: entidades, base de datos, formato del SQL registrado
    public static HibernatePersistenceConfiguration configuration() {
        return new HibernatePersistenceConfiguration("articles")
                .managedClass(Article.class)
                .jdbcUrl(URL)
                .jdbcCredentials(USER, PASSWORD)
                .property(AvailableSettings.FORMAT_SQL, true);
    }

    // un SessionFactory para la base de datos [hbarticles], con la configuración anterior
    public static SessionFactory createSessionFactory() {
        return configuration().createEntityManagerFactory();
    }

    // (re)creación de la tabla [articles] con sus seis artículos, sin registro SQL
    public static void initialize(SessionFactory sessionFactory) {
        SqlLog.withoutLog(() -> {
            // eliminación y luego creación de las tablas de las entidades
            sessionFactory.getSchemaManager().drop(false);
            sessionFactory.getSchemaManager().create(false);
            // los seis artículos, agregados en una transacción
            sessionFactory.inTransaction(session -> {
                session.persist(new Article("bike", BigDecimal.valueOf(500), 10, 5));
                session.persist(new Article("pump", BigDecimal.valueOf(10), 10, 2));
                session.persist(new Article("bow", BigDecimal.valueOf(600), 4, 1));
                session.persist(new Article("arrows - set of 6", BigDecimal.valueOf(100), 12, 20));
                session.persist(new Article("diving suit", BigDecimal.valueOf(300), 8, 2));
                session.persist(new Article("diver's oxygen tanks", BigDecimal.valueOf(120), 10, 5));
            });
        });
    }
}
  • 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:

    <dependencies>
        <!-- el registro SQL compacto (y Logback) -->
        <dependency>
            <groupId>examples.hibernate</groupId>
            <artifactId>tools</artifactId>
        </dependency>
        <!-- Hibernate y el controlador JDBC de MySQL -->
        <dependency>
            <groupId>org.hibernate.orm</groupId>
            <artifactId>hibernate-core</artifactId>
        </dependency>
        <dependency>
            <groupId>com.mysql</groupId>
            <artifactId>mysql-connector-j</artifactId>
        </dependency>
    </dependencies>

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]:

1
2
3
4
5
6
7
    <dependencies>
        <!-- la entidad [Article] y la base de datos [hbarticles] (Hibernate, MySQL y el registro SQL incluidos) -->
        <dependency>
            <groupId>examples.hibernate</groupId>
            <artifactId>articles</artifactId>
        </dependency>
    </dependencies>

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.

package crud;

import articles.Article;
import articles.BaseArticles;
import java.math.BigDecimal;
import java.util.Map;
import java.util.Objects;
import org.hibernate.Session;
import org.hibernate.SessionFactory;
import org.hibernate.Transaction;
import org.hibernate.engine.spi.EntityEntry;
import org.hibernate.engine.spi.PersistenceContext;
import org.hibernate.engine.spi.SessionImplementor;
import org.hibernate.persister.entity.EntityPersister;

public class Main {

    public static void main(String[] args) {
        try (SessionFactory sessionFactory = BaseArticles.createSessionFactory()) {
            // la tabla [articles] se vuelve a crear con sus seis artículos
            BaseArticles.initialize(sessionFactory);
            try (Session session = sessionFactory.openSession()) {
                // 1 - búsqueda por la clave primaria
                IO.println("--- find(1)");
                Article bike = session.find(Article.class, 1);
                IO.println(bike);
                IO.println("--- find(1) a second time");
                Article bike2 = session.find(Article.class, 1);
                IO.println("same object: " + (bike == bike2));

                // 2 - agregar un artículo
                IO.println("--- persist");
                Transaction transaction = session.beginTransaction();
                Article x = new Article("x", BigDecimal.valueOf(100), 10, 1);
                IO.println("before persist: state=" + state(session, x) + ", id=" + x.getId());
                session.persist(x);
                IO.println("after persist: state=" + state(session, x) + ", id=" + x.getId());
                transaction.commit();

                // 3 - modificación: basta con modificar el objeto
                IO.println("--- modification of the price");
                transaction = session.beginTransaction();
                x.setPrice(x.getPrice().multiply(new BigDecimal("1.1")));
                IO.println("session modified: %s, original price=%s, current price=%s"
                        .formatted(session.isDirty(), originalValue(session, x, "price"), x.getPrice()));
                IO.println("--- commit");
                transaction.commit();
                IO.println("after commit: session modified: " + session.isDirty());

                // 4 - eliminación
                IO.println("--- remove");
                transaction = session.beginTransaction();
                session.remove(x);
                IO.println("before commit: state=" + state(session, x));
                transaction.commit();
                IO.println("after commit: state=" + state(session, x));

                // 5 - un objeto separado (detached), modificado y luego fusionado con la sesión
                IO.println("--- detach and merge");
                Article bow = session.find(Article.class, 3);
                session.detach(bow);
                IO.println("after detach: state=" + state(session, bow));
                bow.setPrice(BigDecimal.valueOf(550));
                transaction = session.beginTransaction();
                Article managedBow = session.merge(bow);
                IO.println("merge: same object=%s, state of the returned object=%s"
                        .formatted(bow == managedBow, state(session, managedBow)));
                transaction.commit();

                // 6 - las entidades rastreadas por la sesión
                IO.println("--- the tracked entities");
                bike.setCurrentStock(bike.getCurrentStock() - 1);
                displayTrackedEntities(session);
            }
        }
    }

    // el estado de un artículo con respecto a la sesión (API interna de Hibernate)
    private static String state(Session session, Article article) {
        EntityEntry entry = context(session).getEntry(article);
        if (entry != null) {
            // MANAGED, DELETED...
            return entry.getStatus().name();
        }
        // un objeto desconocido para la sesión: nunca guardado (sin identificador) o separado
        return article.getId() == null ? "TRANSIENT" : "DETACHED";
    }

    // el valor de una propiedad tal como se leyó de la base de datos (API interna de Hibernate)
    private static Object originalValue(Session session, Object entity, String property) {
        return context(session).getEntry(entity).getLoadedValue(property);
    }

    // las entidades del contexto de persistencia de la sesión (API interna de Hibernate)
    private static void displayTrackedEntities(Session session) {
        for (Map.Entry<Object, EntityEntry> pair : context(session).reentrantSafeEntityEntries()) {
            EntityEntry entry = pair.getValue();
            EntityPersister persister = entry.getPersister();
            IO.println("%s #%s %s".formatted(persister.getEntityName(), entry.getId(), entry.getStatus()));
            // valores actuales de las propiedades, comparados con los valores leídos de la base de datos
            String[] names = persister.getPropertyNames();
            Object[] current = persister.getValues(pair.getKey());
            Object[] originals = entry.getLoadedState();
            for (int i = 0; i < names.length; i++) {
                String modification = Objects.equals(current[i], originals[i]) ? ""
                        : " (modified, original value: " + originals[i] + ")";
                IO.println("    %s : %s%s".formatted(names[i], current[i], modification));
            }
        }
        IO.println("session modified: " + session.isDirty());
    }

    // el contexto de persistencia de la sesión (API interna de Hibernate)
    private static PersistenceContext context(Session session) {
        return session.unwrap(SessionImplementor.class).getPersistenceContext();
    }
}

Resultados:

> mvn compile exec:java
--- find(1)
    SQL> select a1_0.id, a1_0.currentStock, a1_0.minimumStock, a1_0.name, a1_0.price
    SQL> from articles a1_0
    SQL> where a1_0.id=?
    SQL> -- parameter 1 = 1
[1, bike, 500.00, 10, 5]
--- find(1) a second time
same object: true
--- persist
    SQL> -- start of transaction
before persist: state=TRANSIENT, id=null
    SQL> insert into articles (currentStock, minimumStock, name, price)
    SQL> values (?, ?, ?, ?)
    SQL> -- parameter 1 = 10
    SQL> -- parameter 2 = 1
    SQL> -- parameter 3 = x
    SQL> -- parameter 4 = 100
after persist: state=MANAGED, id=7
    SQL> -- transaction committed (COMMIT)
--- modification of the price
    SQL> -- start of transaction
session modified: true, original price=100, current price=110.0
--- commit
    SQL> update articles
    SQL> set currentStock=?, minimumStock=?, name=?, price=?
    SQL> where id=?
    SQL> -- parameter 1 = 10
    SQL> -- parameter 2 = 1
    SQL> -- parameter 3 = x
    SQL> -- parameter 4 = 110.0
    SQL> -- parameter 5 = 7
    SQL> -- transaction committed (COMMIT)
after commit: session modified: false
--- remove
    SQL> -- start of transaction
before commit: state=DELETED
    SQL> delete from articles
    SQL> where id=?
    SQL> -- parameter 1 = 7
    SQL> -- transaction committed (COMMIT)
after commit: state=DETACHED
--- detach and merge
    SQL> select a1_0.id, a1_0.currentStock, a1_0.minimumStock, a1_0.name, a1_0.price
    SQL> from articles a1_0
    SQL> where a1_0.id=?
    SQL> -- parameter 1 = 3
after detach: state=DETACHED
    SQL> -- start of transaction
    SQL> select a1_0.id, a1_0.currentStock, a1_0.minimumStock, a1_0.name, a1_0.price
    SQL> from articles a1_0
    SQL> where a1_0.id=?
    SQL> -- parameter 1 = 3
merge: same object=false, state of the returned object=MANAGED
    SQL> update articles
    SQL> set currentStock=?, minimumStock=?, name=?, price=?
    SQL> where id=?
    SQL> -- parameter 1 = 4
    SQL> -- parameter 2 = 1
    SQL> -- parameter 3 = bow
    SQL> -- parameter 4 = 550
    SQL> -- parameter 5 = 3
    SQL> -- transaction committed (COMMIT)
--- the tracked entities
articles.Article #1 MANAGED
    currentStock : 9 (modified, original value: 10)
    minimumStock : 5
    name : bike
    price : 500.00
articles.Article #3 MANAGED
    currentStock : 4
    minimumStock : 1
    name : bow
    price : 550
session modified: true

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:

package hql;

import articles.Article;
import articles.BaseArticles;
import java.math.BigDecimal;
import java.util.List;
import java.util.stream.Collectors;
import java.util.stream.Stream;
import org.hibernate.Session;
import org.hibernate.SessionFactory;
import org.hibernate.query.SemanticException;

public class Main {

    // una proyección: el nombre de un artículo y el valor de su stock
    record StockValue(String name, BigDecimal value) {
    }

    public static void main(String[] args) {
        try (SessionFactory sessionFactory = BaseArticles.createSessionFactory()) {
            // la tabla [articles] se vuelve a crear con sus seis artículos
            BaseArticles.initialize(sessionFactory);
            try (Session session = sessionFactory.openSession()) {
                // 1 - filtrado y ordenación
                IO.println("--- the articles to restock, in alphabetical order");
                String hql = "from Article where currentStock < minimumStock order by name";
                List<Article> toOrder = session.createSelectionQuery(hql, Article.class).getResultList();
                toOrder.forEach(IO::println);

                // 2 - proyección: solo se solicitan las columnas útiles
                IO.println("--- value of the stock of each article");
                List<StockValue> values = session
                        .createSelectionQuery("""
                                select name, price * currentStock from Article
                                order by price * currentStock desc""", StockValue.class)
                        .getResultList();
                for (StockValue v : values) {
                    IO.println("%s : %.2f euros".formatted(v.name(), v.value()));
                }

                // 3 - un único resultado; el valor [minPrice] se pasa mediante un parámetro con nombre
                IO.println("--- the first article over 200 euros");
                BigDecimal minPrice = BigDecimal.valueOf(200);
                Article article = session
                        .createSelectionQuery("""
                                select a from Article a
                                where a.price > :minPrice order by a.price""", Article.class)
                        .setParameter("minPrice", minPrice)
                        .setMaxResults(1)
                        .getSingleResultOrNull();
                IO.println(article == null ? "none" : article);

                // 4 - agregados: el cálculo lo hace el SGBD
                IO.println("--- aggregates");
                long nbArticles = session.createSelectionQuery("select count(*) from Article", Long.class)
                        .getSingleResult();
                BigDecimal stockValue = session
                        .createSelectionQuery("select sum(price * currentStock) from Article", BigDecimal.class)
                        .getSingleResult();
                IO.println("%d articles, value of the stock: %.2f euros".formatted(nbArticles, stockValue));

                // 5 - like e in; una lista Java como valor de un parámetro
                IO.println("--- like and in");
                List<String> names = List.of("bow", "pump", "racket");
                List<String> results = session
                        .createSelectionQuery("""
                                select name from Article
                                where name like 'b%' or name in :names""", String.class)
                        .setParameter("names", names)
                        .getResultList();
                IO.println(String.join(", ", results));

                // 6 - paginación: la tercera página de dos artículos, por precio ascendente
                IO.println("--- pagination");
                int pageSize = 2, pageNumber = 3;
                List<Article> page = session.createSelectionQuery("from Article order by price", Article.class)
                        .setFirstResult((pageNumber - 1) * pageSize)
                        .setMaxResults(pageSize)
                        .getResultList();
                IO.println("page %d : %s".formatted(pageNumber, page.stream()
                        .map(a -> "%s (%.2f euros)".formatted(a.getName(), a.getPrice()))
                        .collect(Collectors.joining(", "))));

                // 7 - una consulta incorrecta se rechaza en cuanto se crea, antes de cualquier ejecución
                IO.println("--- incorrect query");
                try {
                    session.createSelectionQuery("from Article where stock < minimumStock", Article.class);
                } catch (SemanticException e) {
                    IO.println(e.getClass().getSimpleName() + " : " + e.getMessage());
                }

                // 8 - una regla escrita en Java no se puede traducir a SQL: filtrado en memoria
                IO.println("--- in-memory filtering");
                try (Stream<Article> stream = session
                        .createSelectionQuery("from Article", Article.class)
                        .getResultStream()) {
                    stream.filter(Rules::isOutOfStock).forEach(IO::println);
                }
            }
        }
    }

    // una regla de negocio escrita en Java
    static final class Rules {

        private Rules() {
        }

        // un artículo está agotado si su stock es inferior al stock mínimo
        static boolean isOutOfStock(Article a) {
            return a.getCurrentStock() < a.getMinimumStock();
        }
    }
}

Resultados:

> mvn compile exec:java
--- the articles to restock, in alphabetical order
    SQL> select a1_0.id, a1_0.currentStock, a1_0.minimumStock, a1_0.name, a1_0.price
    SQL> from articles a1_0
    SQL> where a1_0.currentStock<a1_0.minimumStock
    SQL> order by a1_0.name
[4, arrows - set of 6, 100.00, 12, 20]
--- value of the stock of each article
    SQL> select a1_0.name, (a1_0.price*a1_0.currentStock)
    SQL> from articles a1_0
    SQL> order by (a1_0.price*a1_0.currentStock) desc
bike : 5000.00 euros
bow : 2400.00 euros
diving suit : 2400.00 euros
arrows - set of 6 : 1200.00 euros
diver's oxygen tanks : 1200.00 euros
pump : 100.00 euros
--- the first article over 200 euros
    SQL> select a1_0.id, a1_0.currentStock, a1_0.minimumStock, a1_0.name, a1_0.price
    SQL> from articles a1_0
    SQL> where a1_0.price>?
    SQL> order by a1_0.price
    SQL> limit ?
    SQL> -- parameter 1 = 200
    SQL> -- parameter 2 = 1
[5, diving suit, 300.00, 8, 2]
--- aggregates
    SQL> select count(*)
    SQL> from articles a1_0
    SQL> select sum((a1_0.price*a1_0.currentStock))
    SQL> from articles a1_0
6 articles, value of the stock: 12300.00 euros
--- like and in
    SQL> select a1_0.name
    SQL> from articles a1_0
    SQL> where a1_0.name like 'b%' escape '' or a1_0.name in (?, ?, ?)
    SQL> -- parameter 1 = bow
    SQL> -- parameter 2 = pump
    SQL> -- parameter 3 = racket
bike, bow, pump
--- pagination
    SQL> select a1_0.id, a1_0.currentStock, a1_0.minimumStock, a1_0.name, a1_0.price
    SQL> from articles a1_0
    SQL> order by a1_0.price
    SQL> limit ?, ?
    SQL> -- parameter 1 = 4
    SQL> -- parameter 2 = 2
page 3 : bike (500.00 euros), bow (600.00 euros)
--- incorrect query
SemanticException : Could not interpret path expression 'stock'
--- in-memory filtering
    SQL> select a1_0.id, a1_0.currentStock, a1_0.minimumStock, a1_0.name, a1_0.price
    SQL> from articles a1_0
[4, arrows - set of 6, 100.00, 12, 20]

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:

package criteria;

import articles.Article;
import articles.BaseArticles;
import jakarta.persistence.criteria.CriteriaQuery;
import jakarta.persistence.criteria.Expression;
import jakarta.persistence.criteria.Predicate;
import jakarta.persistence.criteria.Root;
import java.math.BigDecimal;
import java.util.ArrayList;
import java.util.List;
import org.hibernate.Session;
import org.hibernate.SessionFactory;
import org.hibernate.query.criteria.HibernateCriteriaBuilder;

public class Main {

    // una proyección: el nombre de un artículo y el valor de su stock
    record StockValue(String name, BigDecimal value) {
    }

    public static void main(String[] args) {
        try (SessionFactory sessionFactory = BaseArticles.createSessionFactory()) {
            // la tabla [articles] se vuelve a crear con sus seis artículos
            BaseArticles.initialize(sessionFactory);
            try (Session session = sessionFactory.openSession()) {
                // la fábrica de los elementos de la consulta
                HibernateCriteriaBuilder cb = session.getCriteriaBuilder();

                // 1 - filtrado y ordenación
                IO.println("--- the articles to restock, in alphabetical order");
                CriteriaQuery<Article> query = cb.createQuery(Article.class);
                Root<Article> a = query.from(Article.class);
                query.select(a)
                        .where(cb.lt(a.<Integer>get("currentStock"), a.<Integer>get("minimumStock")))
                        .orderBy(cb.asc(a.get("name")));
                session.createSelectionQuery(query).getResultList().forEach(IO::println);

                // 2 - proyección en un record
                IO.println("--- value of the stock of each article");
                CriteriaQuery<StockValue> projection = cb.createQuery(StockValue.class);
                Root<Article> p = projection.from(Article.class);
                Expression<BigDecimal> value = cb
                        .prod(p.<BigDecimal>get("price"), p.<Integer>get("currentStock"))
                        .as(BigDecimal.class);
                projection.select(cb.construct(StockValue.class, p.get("name"), value))
                        .orderBy(cb.desc(value));
                for (StockValue v : session.createSelectionQuery(projection).getResultList()) {
                    IO.println("%s : %.2f euros".formatted(v.name(), v.value()));
                }

                // 3 - una consulta construida según los criterios proporcionados
                IO.println("--- search: maximum price 150 euros");
                search(session, BigDecimal.valueOf(150), null).forEach(IO::println);
                IO.println("--- search: maximum price 150 euros and name starting with [d]");
                search(session, BigDecimal.valueOf(150), "d").forEach(IO::println);

                // 4 - agregados
                IO.println("--- aggregates");
                CriteriaQuery<Long> count = cb.createQuery(Long.class);
                count.select(cb.count(count.from(Article.class)));
                long nbArticles = session.createSelectionQuery(count).getSingleResult();
                CriteriaQuery<BigDecimal> sum = cb.createQuery(BigDecimal.class);
                Root<Article> s = sum.from(Article.class);
                sum.select(cb.sum(cb
                        .prod(s.<BigDecimal>get("price"), s.<Integer>get("currentStock"))
                        .as(BigDecimal.class)));
                BigDecimal stockValue = session.createSelectionQuery(sum).getSingleResult();
                IO.println("%d articles, value of the stock: %.2f euros".formatted(nbArticles, stockValue));
            }
        }
    }

    // los artículos cuyo precio no supera [maxPrice] y cuyo nombre empieza por [nameStart],
    // cada criterio se usa solo si no es null
    static List<Article> search(Session session, BigDecimal maxPrice, String nameStart) {
        HibernateCriteriaBuilder cb = session.getCriteriaBuilder();
        CriteriaQuery<Article> query = cb.createQuery(Article.class);
        Root<Article> a = query.from(Article.class);
        // las condiciones, agregadas una a una
        List<Predicate> conditions = new ArrayList<>();
        if (maxPrice != null) {
            conditions.add(cb.le(a.get("price"), maxPrice));
        }
        if (nameStart != null) {
            conditions.add(cb.like(a.get("name"), nameStart + "%"));
        }
        query.select(a).where(conditions.toArray(Predicate[]::new)).orderBy(cb.asc(a.get("price")));
        return session.createSelectionQuery(query).getResultList();
    }
}

Resultados:

> mvn compile exec:java
--- the articles to restock, in alphabetical order
    SQL> select a1_0.id, a1_0.currentStock, a1_0.minimumStock, a1_0.name, a1_0.price
    SQL> from articles a1_0
    SQL> where a1_0.currentStock<a1_0.minimumStock
    SQL> order by a1_0.name
[4, arrows - set of 6, 100.00, 12, 20]
--- value of the stock of each article
    SQL> select a1_0.name, (a1_0.price*a1_0.currentStock)
    SQL> from articles a1_0
    SQL> order by (a1_0.price*a1_0.currentStock) desc
bike : 5000.00 euros
bow : 2400.00 euros
diving suit : 2400.00 euros
arrows - set of 6 : 1200.00 euros
diver's oxygen tanks : 1200.00 euros
pump : 100.00 euros
--- search: maximum price 150 euros
    SQL> select a1_0.id, a1_0.currentStock, a1_0.minimumStock, a1_0.name, a1_0.price
    SQL> from articles a1_0
    SQL> where a1_0.price<=?
    SQL> order by a1_0.price
    SQL> -- parameter 1 = 150
[2, pump, 10.00, 10, 2]
[4, arrows - set of 6, 100.00, 12, 20]
[6, diver's oxygen tanks, 120.00, 10, 5]
--- search: maximum price 150 euros and name starting with [d]
    SQL> select a1_0.id, a1_0.currentStock, a1_0.minimumStock, a1_0.name, a1_0.price
    SQL> from articles a1_0
    SQL> where a1_0.price<=? and a1_0.name like ? escape ''
    SQL> order by a1_0.price
    SQL> -- parameter 1 = 150
    SQL> -- parameter 2 = d%
[6, diver's oxygen tanks, 120.00, 10, 5]
--- aggregates
    SQL> select count(a1_0.id)
    SQL> from articles a1_0
    SQL> select sum((a1_0.price*a1_0.currentStock))
    SQL> from articles a1_0
6 articles, value of the stock: 12300.00 euros

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:

// una categoría agrupa varios productos (relación uno a muchos)
@Entity
@Table(name = "categories")
public class Category {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Integer id;

    @Column(nullable = false, length = 30)
    private String name;

    // los productos de la categoría: el lado inverso de la relación, descrito por Product.category
    @OneToMany(mappedBy = "category", cascade = CascadeType.PERSIST)
    private List<Product> products = new ArrayList<>();

    protected Category() {
    }

    public Category(String name) {
        this.name = name;
    }

    // agregar un producto: se actualizan los dos lados de la relación
    public void add(Product product) {
        products.add(product);
        product.setCategory(this);
    }

    public Integer getId() {
        return id;
    }

    public String getName() {
        return name;
    }

    public List<Product> getProducts() {
        return products;
    }
}

Un producto pertenece a una categoría y tiene etiquetas:

// un producto pertenece a una categoría y tiene varias etiquetas
@Entity
@Table(name = "products")
public class Product {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Integer id;

    @Column(nullable = false, length = 30)
    private String name;

    @Column(nullable = false, precision = 10, scale = 2)
    private BigDecimal price;

    // relación muchos a uno: la clave externa [category_id] de la tabla [products]
    @ManyToOne(fetch = FetchType.LAZY, optional = false)
    @JoinColumn(name = "category_id", foreignKey = @ForeignKey(name = "fk_products_category"))
    private Category category;

    // relación muchos a muchos, almacenada en una tabla de asociación
    @ManyToMany(cascade = CascadeType.PERSIST)
    @JoinTable(name = "products_tags",
            joinColumns = @JoinColumn(name = "product_id"),
            inverseJoinColumns = @JoinColumn(name = "tag_id"),
            foreignKey = @ForeignKey(name = "fk_products_tags_product"),
            inverseForeignKey = @ForeignKey(name = "fk_products_tags_tag"))
    private Set<Tag> tags = new HashSet<>();

    protected Product() {
    }

    public Product(String name, BigDecimal price, Tag... tags) {
        this.name = name;
        this.price = price;
        // solo se rellena el lado propietario de la relación: es el que Hibernate guarda
        this.tags.addAll(List.of(tags));
    }

Una etiqueta se asigna a varios productos:

// una etiqueta (promo, new...) la llevan varios productos
@Entity
@Table(name = "tags")
public class Tag {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Integer id;

    @Column(nullable = false, length = 20)
    private String label;

    // el lado inverso de la relación descrita por Product.tags
    @ManyToMany(mappedBy = "tags")
    private Set<Product> products = new HashSet<>();

    protected Tag() {
    }

    public Tag(String label) {
        this.label = label;
    }

Un pedido pertenece a un cliente y contiene líneas de pedido:

// un pedido de un cliente, formado por líneas
@Entity
@Table(name = "orders")
public class CustomerOrder {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Integer id;

    private LocalDate date;

    @ManyToOne(fetch = FetchType.LAZY, optional = false)
    @JoinColumn(name = "client_id")
    private Client client;

    @OneToMany(mappedBy = "order", cascade = CascadeType.PERSIST)
    private List<OrderLine> lines = new ArrayList<>();

    protected CustomerOrder() {
    }

    public CustomerOrder(LocalDate date) {
        this.date = date;
    }

    // agregar una línea: se actualizan los dos lados de la relación
    public void add(OrderLine line) {
        lines.add(line);
        line.setOrder(this);
    }

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:

// una línea de pedido: una cantidad de un producto
@Entity
@Table(name = "order_lines")
public class OrderLine {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Integer id;

    private int quantity;

    @ManyToOne(fetch = FetchType.LAZY, optional = false)
    @JoinColumn(name = "order_id")
    private CustomerOrder order;

    @ManyToOne(fetch = FetchType.LAZY, optional = false)
    @JoinColumn(name = "product_id")
    private Product product;

    protected OrderLine() {
    }

    public OrderLine(Product product, int quantity) {
        this.product = product;
        this.quantity = quantity;
    }

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:

package relations;

import java.math.BigDecimal;
import java.time.LocalDate;
import org.hibernate.SessionFactory;
import org.hibernate.cfg.AvailableSettings;
import org.hibernate.jpa.HibernatePersistenceConfiguration;
import tools.SqlLog;

// la base de datos [hbshop]: configuración de Hibernate y primer conjunto de datos
public final class Shop {

    private Shop() {
    }

    // un SessionFactory para la base de datos [hbshop] y sus seis entidades
    public static SessionFactory createSessionFactory() {
        return new HibernatePersistenceConfiguration("shop")
                .managedClasses(Category.class, Product.class, Tag.class,
                        Client.class, CustomerOrder.class, OrderLine.class)
                .jdbcUrl("jdbc:mysql://localhost:3306/hbshop?createDatabaseIfNotExist=true")
                .jdbcCredentials("root", "")
                .property(AvailableSettings.FORMAT_SQL, true)
                .createEntityManagerFactory();
    }

    // (re)creación de las tablas y de un primer conjunto de datos, sin registro SQL
    public static void initialize(SessionFactory sessionFactory) {
        SqlLog.withoutLog(() -> {
            sessionFactory.getSchemaManager().drop(false);
            sessionFactory.getSchemaManager().create(false);
            sessionFactory.inTransaction(session -> {
                // dos etiquetas
                Tag promo = new Tag("promo");
                Tag novelty = new Tag("new");
                // tres categorías y sus productos: un grafo de objetos
                Category cycles = new Category("cycles");
                cycles.add(new Product("bike", BigDecimal.valueOf(500), promo));
                Product pump = new Product("pump", BigDecimal.valueOf(10));
                cycles.add(pump);
                Category archery = new Category("archery");
                Product bow = new Product("bow", BigDecimal.valueOf(600), novelty);
                archery.add(bow);
                archery.add(new Product("arrows - set of 6", BigDecimal.valueOf(100),
                        promo, novelty));
                Category diving = new Category("diving");
                // la persistencia se propaga a los productos y a las etiquetas (cascade)
                session.persist(cycles);
                session.persist(archery);
                session.persist(diving);
                // un cliente y su pedido de dos líneas
                CustomerOrder order = new CustomerOrder(LocalDate.of(2026, 9, 28));
                order.add(new OrderLine(pump, 2));
                order.add(new OrderLine(bow, 1));
                Client martin = new Client("Martin");
                martin.add(order);
                session.persist(martin);
            });
        });
    }
}
  • 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:

> mysql -uroot hbshop -e "SHOW TABLES; SHOW CREATE TABLE products\G SHOW CREATE TABLE products_tags\G"
Tables_in_hbshop
categories
clients
order_lines
orders
products
products_tags
tags
*************************** 1. row ***************************
       Table: products
Create Table: CREATE TABLE `products` (
  `id` int NOT NULL AUTO_INCREMENT,
  `name` varchar(30) NOT NULL,
  `price` decimal(10,2) NOT NULL,
  `category_id` int NOT NULL,
  PRIMARY KEY (`id`),
  KEY `fk_products_category` (`category_id`),
  CONSTRAINT `fk_products_category` FOREIGN KEY (`category_id`) REFERENCES `categories` (`id`)
) ENGINE=InnoDB AUTO_INCREMENT=5 DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci
*************************** 1. row ***************************
       Table: products_tags
Create Table: CREATE TABLE `products_tags` (
  `product_id` int NOT NULL,
  `tag_id` int NOT NULL,
  PRIMARY KEY (`product_id`,`tag_id`),
  KEY `fk_products_tags_tag` (`tag_id`),
  CONSTRAINT `fk_products_tags_product` FOREIGN KEY (`product_id`) REFERENCES `products` (`id`),
  CONSTRAINT `fk_products_tags_tag` FOREIGN KEY (`tag_id`) REFERENCES `tags` (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci
  • 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

package relations;

import jakarta.persistence.EntityGraph;
import java.math.BigDecimal;
import java.time.LocalDate;
import java.util.List;
import java.util.stream.Collectors;
import org.hibernate.LazyInitializationException;
import org.hibernate.Session;
import org.hibernate.SessionFactory;

public class Main {

    // los resultados de las consultas de proyección
    record ProductCategory(String product, String category) {
    }

    record OrderAmount(Integer id, String client, BigDecimal amount) {
    }

    record CategoryStatistics(String category, Long count, Double averagePrice) {
    }

    public static void main(String[] args) {
        try (SessionFactory sessionFactory = Shop.createSessionFactory()) {
            // 1 - creación de las tablas y de un primer conjunto de datos, sin registro
            Shop.initialize(sessionFactory);

            // 2 - un cliente, su pedido y sus líneas, agregados de una sola vez
            IO.println("--- addition of a client, an order and its two lines");
            sessionFactory.inTransaction(session -> {
                Product bike = product(session, "bike");
                Product arrows = product(session, "arrows - set of 6");
                CustomerOrder order = new CustomerOrder(LocalDate.of(2026, 10, 1));
                order.add(new OrderLine(bike, 1));
                order.add(new OrderLine(arrows, 3));
                Client client = new Client("Dupont");
                client.add(order);
                session.persist(client);
                IO.println("client no. %d, order no. %d".formatted(client.getId(), order.getId()));
            });

            // 3 - carga diferida (lazy loading): las relaciones se leen bajo demanda
            IO.println("--- lazy loading");
            sessionFactory.inSession(session -> {
                List<CustomerOrder> orders = session
                        .createSelectionQuery("from CustomerOrder order by id", CustomerOrder.class)
                        .getResultList();
                for (CustomerOrder order : orders) {
                    IO.println("order no. %d : client=%s, %d line(s)".formatted(order.getId(),
                            order.getClient().getName(), order.getLines().size()));
                }
            });

            // 4 - una relación que no está cargada ya no es accesible una vez cerrada la sesión
            IO.println("--- after the session is closed");
            CustomerOrder detachedOrder = sessionFactory.fromSession(s -> s.find(CustomerOrder.class, 1));
            try {
                IO.println(detachedOrder.getLines().size() + " line(s)");
            } catch (LazyInitializationException e) {
                IO.println(e.getClass().getSimpleName() + " : " + e.getMessage());
            }

            // 5 - join fetch: los pedidos, su cliente, sus líneas y sus productos en una sola consulta
            IO.println("--- join fetch");
            sessionFactory.inSession(session -> {
                List<CustomerOrder> orders = session.createSelectionQuery("""
                        from CustomerOrder c
                        join fetch c.client
                        join fetch c.lines l
                        join fetch l.product
                        order by c.id""", CustomerOrder.class).getResultList();
                for (CustomerOrder order : orders) {
                    IO.println("order no. %d of %s for %s".formatted(order.getId(), order.getDate(),
                            order.getClient().getName()));
                    for (OrderLine line : order.getLines()) {
                        Product product = line.getProduct();
                        IO.println("  %d x %s at %.2f euros"
                                .formatted(line.getQuantity(), product.getName(), product.getPrice()));
                    }
                }
            });

            // 6 - un grafo de entidades: lo que debe cargarse con la entidad, descrito fuera de la consulta
            IO.println("--- entity graph");
            Category category = sessionFactory.fromSession(session -> {
                EntityGraph<Category> graph = session.createEntityGraph(Category.class);
                graph.addAttributeNode("products");
                return session.find(graph, 2);
            });
            // la sesión está cerrada, pero los productos se han cargado
            IO.println("%s : %s".formatted(category.getName(),
                    category.getProducts().stream().map(Product::getName).collect(Collectors.joining(", "))));

            // 7 - la relación muchos a muchos en una consulta
            IO.println("--- the products on promotion");
            sessionFactory.inSession(session -> session.createSelectionQuery("""
                            select p.name, p.category.name from Product p join p.tags e
                            where e.label = 'promo' order by p.name""", ProductCategory.class)
                    .getResultList()
                    .forEach(p -> IO.println("%s (%s)".formatted(p.product(), p.category()))));

            // 8 - un cálculo a través de las relaciones, hecho por el SGBD
            IO.println("--- amount of the orders");
            sessionFactory.inSession(session -> session.createSelectionQuery("""
                            select c.id, c.client.name, sum(l.quantity * l.product.price)
                            from CustomerOrder c join c.lines l
                            group by c.id, c.client.name order by c.id""", OrderAmount.class)
                    .getResultList()
                    .forEach(m -> IO.println("order no. %d (%s) : %.2f euros"
                            .formatted(m.id(), m.client(), m.amount()))));

            // 9 - una agrupación: número de productos y precio promedio por categoría
            IO.println("--- products per category");
            sessionFactory.inSession(session -> session.createSelectionQuery("""
                            select p.category.name, count(*), avg(p.price) from Product p
                            group by p.category.name order by p.category.name""", CategoryStatistics.class)
                    .getResultList()
                    .forEach(s -> IO.println("%s : %d product(s), average price %.2f euros".formatted(
                            s.category(), s.count(), s.averagePrice()))));
        }
    }

    // el producto con el nombre dado
    private static Product product(Session session, String name) {
        return session.createSelectionQuery("from Product where name = :name", Product.class)
                .setParameter("name", name)
                .getSingleResult();
    }
}

Resultados:

> mvn compile exec:java
--- addition of a client, an order and its two lines
    SQL> -- start of transaction
    SQL> select p1_0.id, p1_0.category_id, p1_0.name, p1_0.price
    SQL> from products p1_0
    SQL> where p1_0.name=?
    SQL> -- parameter 1 = bike
    SQL> select p1_0.id, p1_0.category_id, p1_0.name, p1_0.price
    SQL> from products p1_0
    SQL> where p1_0.name=?
    SQL> -- parameter 1 = arrows - set of 6
    SQL> insert into clients (name)
    SQL> values (?)
    SQL> -- parameter 1 = Dupont
    SQL> insert into orders (client_id, date)
    SQL> values (?, ?)
    SQL> -- parameter 1 = 2
    SQL> -- parameter 2 = 2026-10-01
    SQL> insert into order_lines (order_id, product_id, quantity)
    SQL> values (?, ?, ?)
    SQL> -- parameter 1 = 2
    SQL> -- parameter 2 = 1
    SQL> -- parameter 3 = 1
    SQL> insert into order_lines (order_id, product_id, quantity)
    SQL> values (?, ?, ?)
    SQL> -- parameter 1 = 2
    SQL> -- parameter 2 = 4
    SQL> -- parameter 3 = 3
client no. 2, order no. 2
    SQL> -- transaction committed (COMMIT)
--- lazy loading
    SQL> select co1_0.id, co1_0.client_id, co1_0.date
    SQL> from orders co1_0
    SQL> order by co1_0.id
    SQL> select c1_0.id, c1_0.name
    SQL> from clients c1_0
    SQL> where c1_0.id=?
    SQL> -- parameter 1 = 1
    SQL> select l1_0.order_id, l1_0.id, l1_0.product_id, l1_0.quantity
    SQL> from order_lines l1_0
    SQL> where l1_0.order_id=?
    SQL> -- parameter 1 = 1
order no. 1 : client=Martin, 2 line(s)
    SQL> select c1_0.id, c1_0.name
    SQL> from clients c1_0
    SQL> where c1_0.id=?
    SQL> -- parameter 1 = 2
    SQL> select l1_0.order_id, l1_0.id, l1_0.product_id, l1_0.quantity
    SQL> from order_lines l1_0
    SQL> where l1_0.order_id=?
    SQL> -- parameter 1 = 2
order no. 2 : client=Dupont, 2 line(s)
--- after the session is closed
    SQL> select co1_0.id, co1_0.client_id, co1_0.date
    SQL> from orders co1_0
    SQL> where co1_0.id=?
    SQL> -- parameter 1 = 1
LazyInitializationException : Cannot lazily initialize collection of role 'relations.CustomerOrder.lines' with key '1' (no session)
--- join fetch
    SQL> select
    SQL>     co1_0.id,
    SQL>     co1_0.client_id,
    SQL>     c1_0.id,
    SQL>     c1_0.name,
    SQL>     co1_0.date,
    SQL>     l1_0.order_id,
    SQL>     l1_0.id,
    SQL>     l1_0.product_id,
    SQL>     p1_0.id,
    SQL>     p1_0.category_id,
    SQL>     p1_0.name,
    SQL>     p1_0.price,
    SQL>     l1_0.quantity
    SQL> from orders co1_0
    SQL> join clients c1_0 on c1_0.id=co1_0.client_id
    SQL> join order_lines l1_0 on co1_0.id=l1_0.order_id
    SQL> join products p1_0 on p1_0.id=l1_0.product_id
    SQL> order by co1_0.id
order no. 1 of 2026-09-28 for Martin
  2 x pump at 10.00 euros
  1 x bow at 600.00 euros
order no. 2 of 2026-10-01 for Dupont
  1 x bike at 500.00 euros
  3 x arrows - set of 6 at 100.00 euros
--- entity graph
    SQL> select c1_0.id, c1_0.name, p1_0.category_id, p1_0.id, p1_0.name, p1_0.price
    SQL> from categories c1_0
    SQL> left join products p1_0 on c1_0.id=p1_0.category_id
    SQL> where c1_0.id=?
    SQL> -- parameter 1 = 2
archery : bow, arrows - set of 6
--- the products on promotion
    SQL> select p1_0.name, c1_0.name
    SQL> from products p1_0
    SQL> join products_tags t1_0 on p1_0.id=t1_0.product_id
    SQL> join tags t1_1 on t1_1.id=t1_0.tag_id
    SQL> join categories c1_0 on c1_0.id=p1_0.category_id
    SQL> where t1_1.label='promo'
    SQL> order by p1_0.name
arrows - set of 6 (archery)
bike (cycles)
--- amount of the orders
    SQL> select co1_0.id, c1_0.name, sum((l1_0.quantity*p1_0.price))
    SQL> from orders co1_0
    SQL> join order_lines l1_0 on co1_0.id=l1_0.order_id
    SQL> join products p1_0 on p1_0.id=l1_0.product_id
    SQL> join clients c1_0 on c1_0.id=co1_0.client_id
    SQL> group by co1_0.id, c1_0.name
    SQL> order by co1_0.id
order no. 1 (Martin) : 620.00 euros
order no. 2 (Dupont) : 800.00 euros
--- products per category
    SQL> select c1_0.name, count(*), avg(p1_0.price)
    SQL> from products p1_0
    SQL> join categories c1_0 on c1_0.id=p1_0.category_id
    SQL> group by c1_0.name
    SQL> order by c1_0.name
archery : 2 product(s), average price 350.00 euros
cycles : 2 product(s), average price 255.00 euros

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:

// un cliente
@Entity
@Table(name = "clients")
public class Client {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Integer id;

    @Column(nullable = false, length = 50)
    private String name;

    @Column(nullable = false, length = 100)
    private String email;

    @Column(length = 20)
    private String phone;

    protected Client() {
    }

    public Client(String name, String email, String phone) {
        this.name = name;
        this.email = email;
        this.phone = phone;
    }

    @Override
    public String toString() {
        String tel = phone == null ? "no phone" : phone;
        return "[%d, %s, %s, %s]".formatted(id, name, email, tel);
    }
}

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:

1
2
3
4
5
6
7
-- versión 1: la tabla de clientes
create table clients (
    id integer not null auto_increment,
    name varchar(50) not null,
    email varchar(100) not null,
    primary key (id)
) engine=InnoDB;

El segundo agrega la columna del número de teléfono:

1
2
3
-- versión 2: el teléfono (opcional) de los clientes
alter table clients
    add column phone varchar(20);

La clase [Migrations] ejecuta los scripts mediante JDBC (capítulo 10), independientemente de Hibernate:

package clients;

import java.io.IOException;
import java.net.URISyntaxException;
import java.net.URL;
import java.nio.file.Files;
import java.nio.file.Path;
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.PreparedStatement;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.sql.Statement;
import java.util.ArrayList;
import java.util.Comparator;
import java.util.List;
import java.util.Set;
import java.util.TreeSet;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
import java.util.stream.Stream;

// un pequeño ejecutor de scripts SQL versionados, inspirado en Flyway: los scripts
// [db/migration/V<version>__<description>.sql] se aplican una sola vez, en el orden de las versiones,
// y la tabla [migration_history] de la base de datos registra los que ya se han aplicado
public class Migrations {

    // un script de migración
    public record Script(int version, String description, Path path) {
        @Override
        public String toString() {
            return "V" + version + " (" + description + ")";
        }
    }

    // el nombre de un script: V1__create_clients.sql
    private static final Pattern NAME = Pattern.compile("V(\\d+)__(\\w+)\\.sql");

    // la tabla de historial
    private static final String CREATE_HISTORY = """
            create table if not exists migration_history (
                version integer not null primary key,
                description varchar(100) not null,
                applied_on datetime not null default current_timestamp
            ) engine=InnoDB""";

    // la base de datos
    private final String url;
    private final String user;
    private final String password;

    public Migrations(String url, String user, String password) {
        this.url = url;
        this.user = user;
        this.password = password;
    }

    // los scripts de la carpeta [db/migration] del classpath, en orden de versión
    public List<Script> scripts() throws IOException, URISyntaxException {
        URL folder = Migrations.class.getResource("/db/migration");
        if (folder == null) {
            return List.of();
        }
        List<Script> scripts = new ArrayList<>();
        try (Stream<Path> files = Files.list(Path.of(folder.toURI()))) {
            for (Path file : files.toList()) {
                Matcher m = NAME.matcher(file.getFileName().toString());
                if (m.matches()) {
                    int version = Integer.parseInt(m.group(1));
                    scripts.add(new Script(version, m.group(2).replace('_', ' '), file));
                }
            }
        }
        scripts.sort(Comparator.comparingInt(Script::version));
        return scripts;
    }

    // las versiones ya aplicadas a la base de datos (la tabla de historial se crea si es necesario)
    public Set<Integer> appliedVersions() throws SQLException {
        try (Connection connection = DriverManager.getConnection(url, user, password);
             Statement statement = connection.createStatement()) {
            statement.execute(CREATE_HISTORY);
            Set<Integer> versions = new TreeSet<>();
            try (ResultSet rows = statement.executeQuery("select version from migration_history")) {
                while (rows.next()) {
                    versions.add(rows.getInt(1));
                }
            }
            return versions;
        }
    }

    // los scripts que quedan por aplicar
    public List<Script> pending() throws SQLException, IOException, URISyntaxException {
        Set<Integer> applied = appliedVersions();
        return scripts().stream().filter(s -> !applied.contains(s.version())).toList();
    }

    // aplicación de los scripts pendientes, hasta la versión [target] inclusive; se devuelven los scripts aplicados
    public List<Script> apply(int target) throws SQLException, IOException, URISyntaxException {
        List<Script> applied = new ArrayList<>();
        for (Script script : pending()) {
            if (script.version() > target) {
                break;
            }
            apply(script);
            applied.add(script);
        }
        return applied;
    }

    // aplicación de un script y adición de su versión al historial, en una transacción
    private void apply(Script script) throws SQLException, IOException {
        // las sentencias del script, separadas por puntos y coma, sin las líneas de comentario
        String text = Files.readString(script.path()).lines()
                .filter(line -> !line.strip().startsWith("--"))
                .reduce("", (a, b) -> a + "\n" + b);
        try (Connection connection = DriverManager.getConnection(url, user, password)) {
            connection.setAutoCommit(false);
            try (Statement statement = connection.createStatement();
                 PreparedStatement history = connection.prepareStatement(
                         "insert into migration_history(version, description) values (?, ?)")) {
                for (String sql : text.split(";")) {
                    if (!sql.isBlank()) {
                        statement.execute(sql);
                    }
                }
                history.setInt(1, script.version());
                history.setString(2, script.description());
                history.executeUpdate();
                connection.commit();
            } catch (SQLException e) {
                // cuidado: con MySQL, una sentencia de modificación del esquema no se puede revertir
                connection.rollback();
                throw e;
            }
        }
    }
}
  • 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:

package clients;

import jakarta.persistence.PersistenceException;
import org.hibernate.SessionFactory;
import org.hibernate.cfg.AvailableSettings;
import org.hibernate.jpa.HibernatePersistenceConfiguration;
import org.hibernate.tool.schema.Action;

public class Main {

    // la base de datos de clientes; MySQL la crea si no existe
    public static final String URL = "jdbc:mysql://localhost:3306/hbclients?createDatabaseIfNotExist=true";

    public static void main(String[] args) throws Exception {
        // la versión objetivo: la última por defecto, o la que se pasa como argumento
        int target = args.length > 0 ? Integer.parseInt(args[0]) : Integer.MAX_VALUE;

        // el estado de las migraciones
        Migrations migrations = new Migrations(URL, "root", "");
        IO.println("applied versions: " + migrations.appliedVersions());
        IO.println("pending migrations: " + migrations.pending());

        // aplicación de las migraciones pendientes
        for (Migrations.Script script : migrations.apply(target)) {
            IO.println("migration applied: " + script);
        }

        // Hibernate comprueba que el esquema de la base de datos coincide con las entidades (validate)
        try (SessionFactory sessionFactory = new HibernatePersistenceConfiguration("clients")
                .managedClass(Client.class)
                .jdbcUrl(URL)
                .jdbcCredentials("root", "")
                .property(AvailableSettings.FORMAT_SQL, true)
                .schemaToolingAction(Action.VALIDATE)
                .createEntityManagerFactory()) {
            IO.println("the database schema matches the entities");
            // la nueva columna es utilizable
            sessionFactory.inTransaction(session ->
                    session.persist(new Client("Dupont", "dupont@example.com", "01 23 45 67 89")));
            sessionFactory.inSession(session -> session
                    .createSelectionQuery("from Client", Client.class)
                    .getResultList()
                    .forEach(IO::println));
        } catch (PersistenceException e) {
            // el error de validación es la causa de la excepción
            Throwable cause = e.getCause() == null ? e : e.getCause();
            IO.println(cause.getClass().getSimpleName() + " : " + cause.getMessage());
        }
    }
}
  • 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]:

package clients;

import java.io.StringWriter;
import org.hibernate.SessionFactory;
import org.hibernate.cfg.AvailableSettings;
import org.hibernate.jpa.HibernatePersistenceConfiguration;

// generación por Hibernate del script SQL que crea (create) o actualiza (update) el esquema de la base de datos
public class GenerateScript {

    public static void main(String[] args) {
        // la acción: create (por defecto) o update
        String action = args.length > 0 ? args[0] : "create";
        StringWriter script = new StringWriter();
        // un SessionFactory que escribe el script sin ejecutarlo
        try (SessionFactory _ = new HibernatePersistenceConfiguration("clients")
                .managedClass(Client.class)
                .jdbcUrl(Main.URL)
                .jdbcCredentials("root", "")
                .property(AvailableSettings.JAKARTA_HBM2DDL_SCRIPTS_ACTION, action)
                .property(AvailableSettings.JAKARTA_HBM2DDL_SCRIPTS_CREATE_TARGET, script)
                .property(AvailableSettings.HBM2DDL_DELIMITER, ";")
                .property(AvailableSettings.FORMAT_SQL, true)
                .createEntityManagerFactory()) {
            // el script, sin la sangría de 4 espacios de sus líneas
            script.toString().strip().lines()
                    .map(line -> line.startsWith("    ") ? line.substring(4) : line)
                    .forEach(line -> IO.println(line.stripTrailing()));
        }
    }
}
  • 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):

1
2
3
4
5
6
7
8
> mvn compile exec:java -Dexec.mainClass=clients.GenerateScript
create table clients (
    id integer not null auto_increment,
    phone varchar(20),
    name varchar(50) not null,
    email varchar(100) not null,
    primary key (id)
) engine=InnoDB;

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:

1
2
3
4
5
> mvn compile exec:java -Dexec.args="1"
applied versions: []
pending migrations: [V1 (create clients), V2 (add phone)]
migration applied: V1 (create clients)
SchemaManagementException : Schema validation: missing column [phone] in table [clients]
  • 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:

1
2
3
> mvn compile exec:java -Dexec.mainClass=clients.GenerateScript -Dexec.args="update"
alter table clients
   add column phone varchar(20);

Esto es, salvo por el formato, igual al script [V2__add_phone.sql]. Ahora aplicamos todas las migraciones pendientes:

> mvn compile exec:java
applied versions: [1]
pending migrations: [V2 (add phone)]
migration applied: V2 (add phone)
the database schema matches the entities
    SQL> -- start of transaction
    SQL> insert into clients (email, name, phone)
    SQL> values (?, ?, ?)
    SQL> -- parameter 1 = dupont@example.com
    SQL> -- parameter 2 = Dupont
    SQL> -- parameter 3 = 01 23 45 67 89
    SQL> -- transaction committed (COMMIT)
    SQL> select c1_0.id, c1_0.email, c1_0.name, c1_0.phone
    SQL> from clients c1_0
[1, Dupont, dupont@example.com, 01 23 45 67 89]
  • 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:

1
2
3
4
5
6
7
> mysql -uroot -t hbclients -e "SELECT * FROM migration_history"
+---------+----------------+---------------------+
| version | description    | applied_on          |
+---------+----------------+---------------------+
|       1 | create clients | 2026-10-03 17:27:22 |
|       2 | add phone      | 2026-10-03 17:27:27 |
+---------+----------------+---------------------+

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:

package async;

import articles.Article;
import articles.BaseArticles;
import jakarta.persistence.QueryTimeoutException;
import java.math.BigDecimal;
import java.util.List;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
import java.util.concurrent.Future;
import java.util.stream.Stream;
import org.hibernate.SessionFactory;

public class Main {

    public static void main(String[] args) throws InterruptedException, ExecutionException {
        try (SessionFactory sessionFactory = BaseArticles.createSessionFactory()) {
            // la tabla [articles] se vuelve a crear con sus seis artículos
            BaseArticles.initialize(sessionFactory);

            // 1 - dos consultas ejecutadas al mismo tiempo por dos hilos virtuales, cada una con su propia sesión
            IO.println("--- two queries in parallel");
            try (ExecutorService executor = Executors.newVirtualThreadPerTaskExecutor()) {
                Future<List<Article>> lowPrices = executor.submit(() -> sessionFactory.fromSession(s -> s
                        .createSelectionQuery("from Article where price < 200 order by price", Article.class)
                        .getResultList()));
                String hql = "select count(*) from Article where currentStock < minimumStock";
                Future<Long> outOfStock = executor.submit(() -> sessionFactory.fromSession(s -> s
                        .createSelectionQuery(hql, Long.class)
                        .getSingleResult()));
                // get() espera el fin de cada tarea
                lowPrices.get().forEach(IO::println);
                IO.println(outOfStock.get() + " article(s) out of stock");
            }

            // 2 - una transacción ejecutada por un hilo virtual, seguida de un procesamiento de su resultado
            IO.println("--- CompletableFuture");
            try (ExecutorService executor = Executors.newVirtualThreadPerTaskExecutor()) {
                CompletableFuture<Void> processing = CompletableFuture
                        .supplyAsync(() -> sessionFactory.fromTransaction(session -> {
                            Article bow = session
                                    .createSelectionQuery("from Article where name = 'bow'", Article.class)
                                    .getSingleResult();
                            bow.setPrice(BigDecimal.valueOf(550));
                            return bow;
                        }), executor)
                        .thenAccept(bow -> IO.println("new price of the bow: " + bow.getPrice()));
                processing.join();
            }

            // 3 - un stream: las entidades se procesan a medida que se leen
            IO.println("--- getResultStream");
            sessionFactory.inSession(session -> {
                try (Stream<Article> articles = session
                        .createSelectionQuery("from Article where price >= 300", Article.class)
                        .getResultStream()) {
                    articles.forEach(article -> IO.println("read: " + article.getName()));
                }
            });

            // 4 - una consulta demasiado larga se interrumpe tras el tiempo límite establecido (en segundos)
            IO.println("--- timeout exceeded");
            try {
                sessionFactory.inSession(session -> session
                        .createNativeQuery("select sleep(5)", Integer.class)
                        .setTimeout(1)
                        .getSingleResult());
            } catch (QueryTimeoutException e) {
                IO.println(e.getClass().getSimpleName() + " : " + e.getMessage());
            }
        }
    }
}

Resultados:

> mvn compile exec:java
--- two queries in parallel
    SQL> select a1_0.id, a1_0.currentStock, a1_0.minimumStock, a1_0.name, a1_0.price
    SQL> from articles a1_0
    SQL> where a1_0.price<200
    SQL> order by a1_0.price
    SQL> select count(*)
    SQL> from articles a1_0
    SQL> where a1_0.currentStock<a1_0.minimumStock
[2, pump, 10.00, 10, 2]
[4, arrows - set of 6, 100.00, 12, 20]
[6, diver's oxygen tanks, 120.00, 10, 5]
1 article(s) out of stock
--- CompletableFuture
    SQL> -- start of transaction
    SQL> select a1_0.id, a1_0.currentStock, a1_0.minimumStock, a1_0.name, a1_0.price
    SQL> from articles a1_0
    SQL> where a1_0.name='bow'
    SQL> update articles
    SQL> set currentStock=?, minimumStock=?, name=?, price=?
    SQL> where id=?
    SQL> -- parameter 1 = 4
    SQL> -- parameter 2 = 1
    SQL> -- parameter 3 = bow
    SQL> -- parameter 4 = 550
    SQL> -- parameter 5 = 3
    SQL> -- transaction committed (COMMIT)
new price of the bow: 550
--- getResultStream
    SQL> select a1_0.id, a1_0.currentStock, a1_0.minimumStock, a1_0.name, a1_0.price
    SQL> from articles a1_0
    SQL> where a1_0.price>=300
read: bike
read: bow
read: diving suit
--- timeout exceeded
    SQL> select sleep(5)
    SQL> -- failure: Statement cancelled due to timeout or client request
QueryTimeoutException : JDBC exception executing SQL [Statement cancelled due to timeout or client request] [select sleep(5)]

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:

package transactions;

import articles.Article;
import articles.BaseArticles;
import java.math.BigDecimal;
import org.hibernate.Session;
import org.hibernate.SessionFactory;
import org.hibernate.Transaction;
import org.hibernate.exception.ConstraintViolationException;

public class Main {

    public static void main(String[] args) {
        try (SessionFactory sessionFactory = BaseArticles.createSessionFactory()) {
            // la tabla [articles] se vuelve a crear con sus seis artículos
            BaseArticles.initialize(sessionFactory);

            // 1 - inTransaction: commit si todo tiene éxito, rollback en caso de excepción
            IO.println("--- two additions, the second of which violates the uniqueness of the name");
            try {
                sessionFactory.inTransaction(session -> {
                    session.persist(new Article("racket", BigDecimal.valueOf(80), 5, 2));
                    session.persist(new Article("bike", BigDecimal.valueOf(450), 3, 1));
                });
            } catch (ConstraintViolationException e) {
                IO.println("%s : constraint [%s] violated"
                        .formatted(e.getClass().getSimpleName(), e.getConstraintName()));
            }
            display(sessionFactory, "racket");

            // 2 - una transacción gestionada por el código: varias escrituras, confirmadas o revertidas juntas
            IO.println("--- transaction rolled back");
            try (Session session = sessionFactory.openSession()) {
                Transaction transaction = session.beginTransaction();
                try {
                    // venta de dos bicicletas: el UPDATE se envía mediante flush
                    Article bike = session
                            .createSelectionQuery("from Article where name = 'bike'", Article.class)
                            .getSingleResult();
                    bike.setCurrentStock(bike.getCurrentStock() - 2);
                    session.flush();
                    // agregar un artículo cuyo nombre ya existe: error
                    session.persist(new Article("pump", BigDecimal.valueOf(12), 5, 1));
                    // confirmación del conjunto (aquí no se llega a ella)
                    transaction.commit();
                } catch (ConstraintViolationException e) {
                    IO.println(e.getClass().getSimpleName() + " : " + e.getSQLException().getMessage());
                    // reversión de todas las operaciones de la transacción
                    transaction.rollback();
                }
            }
            // la venta de las bicicletas se ha revertido
            display(sessionFactory, "bike");
        }
    }

    // visualización de un artículo leído de la base de datos, con una sesión nueva
    private static void display(SessionFactory sessionFactory, String name) {
        Article article = sessionFactory.fromSession(session -> session
                .createSelectionQuery("from Article where name = :name", Article.class)
                .setParameter("name", name)
                .getSingleResultOrNull());
        IO.println("article [%s] in the database: %s".formatted(name, article == null ? "missing" : article));
    }
}

Resultados:

> mvn compile exec:java
--- two additions, the second of which violates the uniqueness of the name
    SQL> -- start of transaction
    SQL> insert into articles (currentStock, minimumStock, name, price)
    SQL> values (?, ?, ?, ?)
    SQL> -- parameter 1 = 5
    SQL> -- parameter 2 = 2
    SQL> -- parameter 3 = racket
    SQL> -- parameter 4 = 80
    SQL> insert into articles (currentStock, minimumStock, name, price)
    SQL> values (?, ?, ?, ?)
    SQL> -- parameter 1 = 3
    SQL> -- parameter 2 = 1
    SQL> -- parameter 3 = bike
    SQL> -- parameter 4 = 450
    SQL> -- failure: Duplicate entry 'bike' for key 'articles.uk_articles_name'
    SQL> -- transaction rolled back (ROLLBACK)
ConstraintViolationException : constraint [articles.uk_articles_name] violated
    SQL> select a1_0.id, a1_0.currentStock, a1_0.minimumStock, a1_0.name, a1_0.price
    SQL> from articles a1_0
    SQL> where a1_0.name=?
    SQL> -- parameter 1 = racket
article [racket] in the database: missing
--- transaction rolled back
    SQL> -- start of transaction
    SQL> select a1_0.id, a1_0.currentStock, a1_0.minimumStock, a1_0.name, a1_0.price
    SQL> from articles a1_0
    SQL> where a1_0.name='bike'
    SQL> update articles
    SQL> set currentStock=?, minimumStock=?, name=?, price=?
    SQL> where id=?
    SQL> -- parameter 1 = 8
    SQL> -- parameter 2 = 5
    SQL> -- parameter 3 = bike
    SQL> -- parameter 4 = 500.00
    SQL> -- parameter 5 = 1
    SQL> insert into articles (currentStock, minimumStock, name, price)
    SQL> values (?, ?, ?, ?)
    SQL> -- parameter 1 = 5
    SQL> -- parameter 2 = 1
    SQL> -- parameter 3 = pump
    SQL> -- parameter 4 = 12
    SQL> -- failure: Duplicate entry 'pump' for key 'articles.uk_articles_name'
ConstraintViolationException : Duplicate entry 'pump' for key 'articles.uk_articles_name'
    SQL> -- transaction rolled back (ROLLBACK)
    SQL> select a1_0.id, a1_0.currentStock, a1_0.minimumStock, a1_0.name, a1_0.price
    SQL> from articles a1_0
    SQL> where a1_0.name=?
    SQL> -- parameter 1 = bike
article [bike] in the database: [1, bike, 500.00, 10, 5]

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:

// un artículo cuyas modificaciones se controlan mediante un número de versión
@Entity
@Table(name = "articles")
public class Article {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Integer id;

    @Column(nullable = false, length = 30)
    private String name;

    private int currentStock;

    // el número de versión: incrementado por Hibernate en cada modificación de la fila
    @Version
    private int version;

    protected Article() {
    }

    public Article(String name, int currentStock) {
        this.name = name;
        this.currentStock = currentStock;
    }

    public int getCurrentStock() {
        return currentStock;
    }

    public void setCurrentStock(int currentStock) {
        this.currentStock = currentStock;
    }

    public int getVersion() {
        return version;
    }
}
  • 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:

package concurrency;

import jakarta.persistence.OptimisticLockException;
import org.hibernate.Session;
import org.hibernate.SessionFactory;
import org.hibernate.Transaction;
import org.hibernate.cfg.AvailableSettings;
import org.hibernate.jpa.HibernatePersistenceConfiguration;
import tools.SqlLog;

public class Main {

    public static void main(String[] args) {
        try (SessionFactory sessionFactory = new HibernatePersistenceConfiguration("concurrency")
                .managedClass(Article.class)
                .jdbcUrl("jdbc:mysql://localhost:3306/hbconcurrency?createDatabaseIfNotExist=true")
                .jdbcCredentials("root", "")
                .property(AvailableSettings.FORMAT_SQL, true)
                .createEntityManagerFactory()) {
            // la tabla [articles] se vuelve a crear con un único artículo, sin registro
            SqlLog.withoutLog(() -> {
                sessionFactory.getSchemaManager().drop(false);
                sessionFactory.getSchemaManager().create(false);
                sessionFactory.inTransaction(session -> session.persist(new Article("bike", 10)));
            });

            // dos usuarios, dos sesiones: cada uno lee el mismo artículo
            try (Session session1 = sessionFactory.openSession();
                 Session session2 = sessionFactory.openSession()) {
                IO.println("--- the two users read the bike");
                Article bike1 = session1.find(Article.class, 1);
                Article bike2 = session2.find(Article.class, 1);

                // el usuario 1 vende 1 bicicleta
                IO.println("--- user 1 sells 1 bike");
                Transaction transaction1 = session1.beginTransaction();
                bike1.setCurrentStock(bike1.getCurrentStock() - 1);
                transaction1.commit();
                IO.println("stock saved by user 1: %d (version %d)"
                        .formatted(bike1.getCurrentStock(), bike1.getVersion()));

                // el usuario 2 vende 3 bicicletas basándose en datos desactualizados (stock = 10, versión 0)
                IO.println("--- user 2 sells 3 bikes");
                Transaction transaction2 = session2.beginTransaction();
                bike2.setCurrentStock(bike2.getCurrentStock() - 3);
                try {
                    session2.flush();
                    transaction2.commit();
                } catch (OptimisticLockException e) {
                    IO.println(e.getClass().getSimpleName() + " : " + e.getMessage());
                    transaction2.rollback();
                }
            }

            // resolución: el usuario 2 vuelve a leer el artículo, con una sesión nueva, y comienza de nuevo
            IO.println("--- user 2 rereads the bike and starts again");
            sessionFactory.inTransaction(session -> {
                Article bike = session.find(Article.class, 1);
                IO.println("reread stock: %d (version %d)"
                        .formatted(bike.getCurrentStock(), bike.getVersion()));
                bike.setCurrentStock(bike.getCurrentStock() - 3);
                session.flush();
                IO.println("stock saved by user 2: %d (version %d)"
                        .formatted(bike.getCurrentStock(), bike.getVersion()));
            });
        }
    }
}

Resultados:

> mvn compile exec:java
--- the two users read the bike
    SQL> select a1_0.id, a1_0.currentStock, a1_0.name, a1_0.version
    SQL> from articles a1_0
    SQL> where a1_0.id=?
    SQL> -- parameter 1 = 1
    SQL> select a1_0.id, a1_0.currentStock, a1_0.name, a1_0.version
    SQL> from articles a1_0
    SQL> where a1_0.id=?
    SQL> -- parameter 1 = 1
--- user 1 sells 1 bike
    SQL> -- start of transaction
    SQL> update articles
    SQL> set currentStock=?, name=?, version=?
    SQL> where id=? and version=?
    SQL> -- parameter 1 = 9
    SQL> -- parameter 2 = bike
    SQL> -- parameter 3 = 1
    SQL> -- parameter 4 = 1
    SQL> -- parameter 5 = 0
    SQL> -- transaction committed (COMMIT)
stock saved by user 1: 9 (version 1)
--- user 2 sells 3 bikes
    SQL> -- start of transaction
    SQL> update articles
    SQL> set currentStock=?, name=?, version=?
    SQL> where id=? and version=?
    SQL> -- parameter 1 = 7
    SQL> -- parameter 2 = bike
    SQL> -- parameter 3 = 1
    SQL> -- parameter 4 = 1
    SQL> -- parameter 5 = 0
OptimisticLockException : Unexpected row count (expected row count 1 but was 0) [update articles set currentStock=?,name=?,version=? where id=? and version=?] for entity [concurrency.Article with id '1']
    SQL> -- transaction rolled back (ROLLBACK)
--- user 2 rereads the bike and starts again
    SQL> -- start of transaction
    SQL> select a1_0.id, a1_0.currentStock, a1_0.name, a1_0.version
    SQL> from articles a1_0
    SQL> where a1_0.id=?
    SQL> -- parameter 1 = 1
reread stock: 9 (version 1)
    SQL> update articles
    SQL> set currentStock=?, name=?, version=?
    SQL> where id=? and version=?
    SQL> -- parameter 1 = 6
    SQL> -- parameter 2 = bike
    SQL> -- parameter 3 = 2
    SQL> -- parameter 4 = 1
    SQL> -- parameter 5 = 1
stock saved by user 2: 6 (version 2)
    SQL> -- transaction committed (COMMIT)

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:

package rawsql;

import articles.Article;
import articles.BaseArticles;
import java.math.BigDecimal;
import java.sql.ResultSet;
import java.sql.Statement;
import java.util.List;
import org.hibernate.Session;
import org.hibernate.SessionFactory;

public class Main {

    public static void main(String[] args) {
        try (SessionFactory sessionFactory = BaseArticles.createSessionFactory()) {
            // la tabla [articles] se vuelve a crear con sus seis artículos
            BaseArticles.initialize(sessionFactory);
            try (Session session = sessionFactory.openSession()) {
                // 1 - una consulta SQL escrita a mano que devuelve entidades
                IO.println("--- createNativeQuery: entities");
                BigDecimal minPrice = BigDecimal.valueOf(200);
                List<Article> expensive = session
                        .createNativeQuery("""
                                select * from articles
                                where price > :minPrice order by name""", Article.class)
                        .setParameter("minPrice", minPrice)
                        .getResultList();
                expensive.forEach(IO::println);

                // 2 - un valor pasado como parámetro: no es posible la inyección SQL
                IO.println("--- SQL injection attempt with a parameter");
                String name = "x' or '1'='1";
                long nb = session
                        .createNativeQuery("select count(*) from articles where name = :name", Long.class)
                        .setParameter("name", name)
                        .getSingleResult();
                IO.println(nb + " article(s) found");
                // la misma consulta construida por concatenación: nunca haga esto
                IO.println("--- the same attempt with a concatenation");
                String sql = "select count(*) from articles where name = '" + name + "'";
                nb = session.createNativeQuery(sql, Long.class).getSingleResult();
                IO.println(nb + " article(s) found");

                // 3 - resultados que no son entidades
                IO.println("--- createNativeQuery: values");
                List<String> names = session
                        .createNativeQuery("""
                                select name from articles
                                where currentStock < minimumStock""", String.class)
                        .getResultList();
                IO.println("out of stock: " + String.join(", ", names));
                BigDecimal value = session
                        .createNativeQuery("select sum(price * currentStock) from articles", BigDecimal.class)
                        .getSingleResult();
                IO.println("stock value: %.2f euros".formatted(value));

                // 4 - una sentencia de actualización
                IO.println("--- createNativeMutationQuery");
                int nbRows = session.fromTransaction(transaction -> session
                        .createNativeMutationQuery("""
                                update articles set price = price * :coefficient
                                where name = :name""")
                        .setParameter("coefficient", new BigDecimal("0.9"))
                        .setParameter("name", "bow")
                        .executeUpdate());
                IO.println(nbRows + " row(s) modified");

                // 5 - la conexión JDBC de la sesión, para código JDBC ordinario
                IO.println("--- doWork: the JDBC connection");
                session.doWork(connection -> {
                    String query = "select name, price from articles where name = 'bow'";
                    try (Statement statement = connection.createStatement();
                         ResultSet rows = statement.executeQuery(query)) {
                        while (rows.next()) {
                            IO.println("%s : %.2f euros"
                                    .formatted(rows.getString("name"), rows.getBigDecimal("price")));
                        }
                    }
                });
            }
        }
    }
}

Resultados:

> mvn compile exec:java
--- createNativeQuery: entities
    SQL> select *
    SQL> from articles
    SQL> where price > ?
    SQL> order by name
    SQL> -- parameter 1 = 200
[1, bike, 500.00, 10, 5]
[3, bow, 600.00, 4, 1]
[5, diving suit, 300.00, 8, 2]
--- SQL injection attempt with a parameter
    SQL> select count(*)
    SQL> from articles
    SQL> where name = ?
    SQL> -- parameter 1 = x' or '1'='1
0 article(s) found
--- the same attempt with a concatenation
    SQL> select count(*)
    SQL> from articles
    SQL> where name = 'x' or '1'='1'
6 article(s) found
--- createNativeQuery: values
    SQL> select name
    SQL> from articles
    SQL> where currentStock < minimumStock
out of stock: arrows - set of 6
    SQL> select sum(price * currentStock)
    SQL> from articles
stock value: 12300.00 euros
--- createNativeMutationQuery
    SQL> -- start of transaction
    SQL> update articles
    SQL> set price = price * ?
    SQL> where name = ?
    SQL> -- parameter 1 = 0.9
    SQL> -- parameter 2 = bow
    SQL> -- transaction committed (COMMIT)
1 row(s) modified
--- doWork: the JDBC connection
bow : 540.00 euros

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:

package bulkupdate;

import articles.Article;
import articles.BaseArticles;
import java.math.BigDecimal;
import java.util.List;
import org.hibernate.Session;
import org.hibernate.SessionFactory;
import org.hibernate.Transaction;

public class Main {

    public static void main(String[] args) {
        try (SessionFactory sessionFactory = BaseArticles.createSessionFactory()) {
            // la tabla [articles] se vuelve a crear con sus seis artículos
            BaseArticles.initialize(sessionFactory);
            try (Session session = sessionFactory.openSession()) {
                Transaction transaction = session.beginTransaction();

                // 1 - actualización HQL: una única sentencia UPDATE, sin cargar ninguna entidad en memoria
                IO.println("--- restocking of the out-of-stock articles");
                int nbRows = session
                        .createMutationQuery("""
                                update Article set currentStock = minimumStock * 2
                                where currentStock < minimumStock""")
                        .executeUpdate();
                IO.println(nbRows + " article(s) modified");

                IO.println("--- 10 % increase of the prices below 150 euros");
                nbRows = session
                        .createMutationQuery("update Article set price = price * 1.1 where price < 150")
                        .executeUpdate();
                IO.println(nbRows + " article(s) modified");

                // 2 - eliminación HQL: una única sentencia DELETE
                IO.println("--- deletion of the articles over 550 euros");
                nbRows = session
                        .createMutationQuery("delete from Article where price > 550")
                        .executeUpdate();
                IO.println(nbRows + " article(s) deleted");
                transaction.commit();

                // 3 - solo lectura: las entidades leídas no se vigilan
                IO.println("--- read-only");
                transaction = session.beginTransaction();
                List<Article> articles = session
                        .createSelectionQuery("from Article order by id", Article.class)
                        .setReadOnly(true)
                        .getResultList();
                articles.forEach(IO::println);
                // la modificación de una entidad de solo lectura se ignora
                articles.getFirst().setPrice(BigDecimal.ZERO);
                IO.println("session modified: " + session.isDirty());
                transaction.commit();

                // 4 - una sentencia de actualización HQL no modifica las entidades ya cargadas por la sesión
                IO.println("--- HQL update and loaded entities");
                transaction = session.beginTransaction();
                Article pump = session.find(Article.class, 2);
                session.createMutationQuery("update Article set price = 9.5 where id = :id")
                        .setParameter("id", pump.getId())
                        .executeUpdate();
                IO.println("price in memory: " + pump.getPrice());
                session.refresh(pump);
                IO.println("price after refresh: " + pump.getPrice());
                transaction.commit();
            }

            // 5 - una sesión sin estado (StatelessSession) y sentencias enviadas por lotes
            IO.println("--- StatelessSession and batches of 3 statements");
            sessionFactory.inStatelessTransaction(session -> {
                session.setJdbcBatchSize(3);
                List<Article> articles = session
                        .createSelectionQuery("from Article order by id", Article.class)
                        .getResultList();
                for (Article article : articles) {
                    article.setCurrentStock(article.getCurrentStock() + 1);
                    // cada modificación se solicita explícitamente: las entidades no se vigilan
                    session.update(article);
                }
            });
        }
    }
}

Resultados (el final repetitivo se ha abreviado):

> mvn compile exec:java
    SQL> -- start of transaction
--- restocking of the out-of-stock articles
    SQL> update articles a1_0
    SQL> set currentStock=(a1_0.minimumStock*2)
    SQL> where a1_0.currentStock<a1_0.minimumStock
1 article(s) modified
--- 10 % increase of the prices below 150 euros
    SQL> update articles a1_0
    SQL> set price=(a1_0.price*1.1)
    SQL> where a1_0.price<150
3 article(s) modified
--- deletion of the articles over 550 euros
    SQL> delete a1_0
    SQL> from articles a1_0
    SQL> where a1_0.price>550
1 article(s) deleted
    SQL> -- transaction committed (COMMIT)
--- read-only
    SQL> -- start of transaction
    SQL> select a1_0.id, a1_0.currentStock, a1_0.minimumStock, a1_0.name, a1_0.price
    SQL> from articles a1_0
    SQL> order by a1_0.id
[1, bike, 500.00, 10, 5]
[2, pump, 11.00, 10, 2]
[4, arrows - set of 6, 110.00, 40, 20]
[5, diving suit, 300.00, 8, 2]
[6, diver's oxygen tanks, 132.00, 10, 5]
session modified: false
    SQL> -- transaction committed (COMMIT)
--- HQL update and loaded entities
    SQL> -- start of transaction
    SQL> update articles a1_0
    SQL> set price=9.5
    SQL> where a1_0.id=?
    SQL> -- parameter 1 = 2
price in memory: 11.00
    SQL> select a1_0.id, a1_0.currentStock, a1_0.minimumStock, a1_0.name, a1_0.price
    SQL> from articles a1_0
    SQL> where a1_0.id=?
    SQL> -- parameter 1 = 2
price after refresh: 9.50
    SQL> -- transaction committed (COMMIT)
--- StatelessSession and batches of 3 statements
    SQL> -- start of transaction
    SQL> select a1_0.id, a1_0.currentStock, a1_0.minimumStock, a1_0.name, a1_0.price
    SQL> from articles a1_0
    SQL> order by a1_0.id
    SQL> update articles
    SQL> set currentStock=?, minimumStock=?, name=?, price=?
    SQL> where id=?
    SQL> -- parameter 1 = 11
    SQL> -- parameter 2 = 5
    SQL> -- parameter 3 = bike
    SQL> -- parameter 4 = 500.00
    SQL> -- parameter 5 = 1
...
    SQL> -- execution of a batch of 3 statement(s)
    SQL> update articles
    SQL> set currentStock=?, minimumStock=?, name=?, price=?
    SQL> where id=?
...
    SQL> -- execution of a batch of 2 statement(s)
    SQL> -- transaction committed (COMMIT)

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:

    <dependencies>
        <!-- la entidad [Article] y la base de datos [hbarticles] (Hibernate, MySQL y el registro SQL incluidos) -->
        <dependency>
            <groupId>examples.hibernate</groupId>
            <artifactId>articles</artifactId>
        </dependency>
        <!-- Spring: contenedor, transacciones declarativas, integración con Hibernate -->
        <dependency>
            <groupId>org.springframework</groupId>
            <artifactId>spring-context</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework</groupId>
            <artifactId>spring-orm</artifactId>
        </dependency>
        <!-- el grupo de conexiones HikariCP -->
        <dependency>
            <groupId>com.zaxxer</groupId>
            <artifactId>HikariCP</artifactId>
        </dependency>
    </dependencies>

La configuración de Spring se escribe en Java, usando las anotaciones [@Configuration] y [@Bean] del capítulo 6:

package injection;

import articles.Article;
import articles.BaseArticles;
import com.zaxxer.hikari.HikariDataSource;
import java.util.Properties;
import javax.sql.DataSource;
import org.hibernate.SessionFactory;
import org.hibernate.cfg.AvailableSettings;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.orm.jpa.hibernate.HibernateTransactionManager;
import org.springframework.orm.jpa.hibernate.LocalSessionFactoryBean;
import org.springframework.transaction.annotation.EnableTransactionManagement;

// la configuración de Spring: grupo de conexiones, SessionFactory, administrador de transacciones, capa [dao]
@Configuration
@EnableTransactionManagement
public class Config {

    // el grupo de conexiones HikariCP (capítulo 10)
    @Bean(destroyMethod = "close")
    public HikariDataSource dataSource() {
        HikariDataSource dataSource = new HikariDataSource();
        dataSource.setJdbcUrl(BaseArticles.URL);
        dataSource.setUsername(BaseArticles.USER);
        dataSource.setPassword(BaseArticles.PASSWORD);
        return dataSource;
    }

    // el SessionFactory, construido por Spring con el grupo de conexiones
    @Bean
    public LocalSessionFactoryBean sessionFactory(DataSource dataSource) {
        LocalSessionFactoryBean factory = new LocalSessionFactoryBean();
        factory.setDataSource(dataSource);
        factory.setAnnotatedClasses(Article.class);
        Properties properties = new Properties();
        properties.put(AvailableSettings.FORMAT_SQL, "true");
        factory.setHibernateProperties(properties);
        return factory;
    }

    // el administrador de transacciones: una sesión de Hibernate por transacción
    @Bean
    public HibernateTransactionManager transactionManager(SessionFactory sessionFactory) {
        return new HibernateTransactionManager(sessionFactory);
    }

    // la capa [dao]: un singleton que recibe el SessionFactory
    @Bean
    public ArticlesDao articlesDao(SessionFactory sessionFactory) {
        return new ArticlesDao(sessionFactory);
    }
}
  • 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]:

package injection;

import articles.Article;
import java.util.List;
import org.hibernate.Session;
import org.hibernate.SessionFactory;
import org.springframework.transaction.annotation.Transactional;

// la capa [dao]: cada método público se ejecuta en una transacción abierta por Spring
@Transactional
public class ArticlesDao {

    // el SessionFactory, compartido por todos los hilos
    private final SessionFactory sessionFactory;

    public ArticlesDao(SessionFactory sessionFactory) {
        this.sessionFactory = sessionFactory;
    }

    // ¿dos solicitudes de la sesión actual, en la misma transacción, devuelven la misma sesión?
    public boolean sameSession() {
        return sessionFactory.getCurrentSession() == sessionFactory.getCurrentSession();
    }

    // la sesión de la transacción
    public Session session() {
        return sessionFactory.getCurrentSession();
    }

    // los artículos por reabastecer; una transacción de solo lectura
    @Transactional(readOnly = true)
    public List<String> articlesOutOfStock() {
        String hql = "select name from Article where currentStock < minimumStock";
        return sessionFactory.getCurrentSession().createSelectionQuery(hql, String.class).getResultList();
    }

    // el artículo con el nombre dado
    @Transactional(readOnly = true)
    public Article article(String name) {
        return sessionFactory.getCurrentSession()
                .createSelectionQuery("from Article where name = :name", Article.class)
                .setParameter("name", name)
                .getSingleResult();
    }

    // la venta de una cantidad de un artículo: una excepción revierte la transacción
    public void sell(String name, int quantity) {
        Article article = article(name);
        article.setCurrentStock(article.getCurrentStock() - quantity);
        if (article.getCurrentStock() < 0) {
            throw new IllegalStateException("insufficient stock for the article [" + name + "]");
        }
    }
}
  • 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:

package injection;

import articles.BaseArticles;
import org.hibernate.HibernateException;
import org.hibernate.Session;
import org.hibernate.SessionFactory;
import org.springframework.context.annotation.AnnotationConfigApplicationContext;

public class Main {

    public static void main(String[] args) {
        // el contenedor de Spring, configurado por la clase [Config]
        try (var context = new AnnotationConfigApplicationContext(Config.class)) {
            // la tabla [articles] se vuelve a crear con sus seis artículos
            SessionFactory sessionFactory = context.getBean(SessionFactory.class);
            BaseArticles.initialize(sessionFactory);
            ArticlesDao dao = context.getBean(ArticlesDao.class);

            // 1 - durante una transacción, la sesión actual es siempre la misma
            IO.println("--- sessions and transactions");
            IO.println("one transaction: same session = " + dao.sameSession());
            // 2 - dos transacciones: dos sesiones, cerradas al final de su transacción
            Session session1 = dao.session();
            Session session2 = dao.session();
            IO.println("two transactions: same session = %s, first session open = %s"
                    .formatted(session1 == session2, session1.isOpen()));
            // 3 - fuera de una transacción, no hay sesión actual
            try {
                sessionFactory.getCurrentSession();
            } catch (HibernateException e) {
                IO.println(e.getClass().getSimpleName() + " : " + e.getMessage());
            }

            // 4 - métodos transaccionales de la capa [dao]
            IO.println("--- articles out of stock");
            IO.println("out of stock: " + dao.articlesOutOfStock());
            IO.println("--- sale of 2 bikes");
            dao.sell("bike", 2);
            IO.println("--- sale of 50 pumps");
            try {
                dao.sell("pump", 50);
            } catch (IllegalStateException e) {
                IO.println(e.getClass().getSimpleName() + " : " + e.getMessage());
            }
            IO.println("--- state of the database");
            IO.println(dao.article("bike"));
            IO.println(dao.article("pump"));
        }
    }
}

Resultados:

> mvn compile exec:java
--- sessions and transactions
    SQL> -- start of transaction
    SQL> -- transaction committed (COMMIT)
one transaction: same session = true
    SQL> -- start of transaction
    SQL> -- transaction committed (COMMIT)
    SQL> -- start of transaction
    SQL> -- transaction committed (COMMIT)
two transactions: same session = false, first session open = false
HibernateException : Could not obtain transaction-synchronized Session for current thread
--- articles out of stock
    SQL> -- start of transaction
    SQL> select a1_0.name
    SQL> from articles a1_0
    SQL> where a1_0.currentStock<a1_0.minimumStock
    SQL> -- transaction committed (COMMIT)
out of stock: [arrows - set of 6]
--- sale of 2 bikes
    SQL> -- start of transaction
    SQL> select a1_0.id, a1_0.currentStock, a1_0.minimumStock, a1_0.name, a1_0.price
    SQL> from articles a1_0
    SQL> where a1_0.name=?
    SQL> -- parameter 1 = bike
    SQL> update articles
    SQL> set currentStock=?, minimumStock=?, name=?, price=?
    SQL> where id=?
    SQL> -- parameter 1 = 8
    SQL> -- parameter 2 = 5
    SQL> -- parameter 3 = bike
    SQL> -- parameter 4 = 500.00
    SQL> -- parameter 5 = 1
    SQL> -- transaction committed (COMMIT)
--- sale of 50 pumps
    SQL> -- start of transaction
    SQL> select a1_0.id, a1_0.currentStock, a1_0.minimumStock, a1_0.name, a1_0.price
    SQL> from articles a1_0
    SQL> where a1_0.name=?
    SQL> -- parameter 1 = pump
    SQL> -- transaction rolled back (ROLLBACK)
IllegalStateException : insufficient stock for the article [pump]
--- state of the database
    SQL> -- start of transaction
    SQL> select a1_0.id, a1_0.currentStock, a1_0.minimumStock, a1_0.name, a1_0.price
    SQL> from articles a1_0
    SQL> where a1_0.name=?
    SQL> -- parameter 1 = bike
    SQL> -- transaction committed (COMMIT)
[1, bike, 500.00, 8, 5]
    SQL> -- start of transaction
    SQL> select a1_0.id, a1_0.currentStock, a1_0.minimumStock, a1_0.name, a1_0.price
    SQL> from articles a1_0
    SQL> where a1_0.name=?
    SQL> -- parameter 1 = pump
    SQL> -- transaction committed (COMMIT)
[2, pump, 10.00, 10, 2]

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.

Image

El proyecto Maven [TaxV7], ubicado en la carpeta [11-hibernate], consta de dos módulos:

TaxV7/
  pom.xml                           the parent project
  tax-dao-hibernate/                library: the Hibernate [dao] layer
    pom.xml
    src/main/java/tax/dao/
      Bracket.java                  the entity
      HibernateTax.java             the implementation of ITaxDao
      CreateDatabase.java           the creation of the database [hbtaxes]
    src/main/resources/
      logback.xml
  tax-ui-hibernate/                 executable: integration of the layers
    pom.xml
    src/main/java/tax/ui/
      MainHibernate.java
    tax-hibernate.properties
    tax-hibernate-error.properties

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]:

    <dependencies>
        <!-- la capa [dao] de la versión 5: entidades, interfaz ITaxDao, HardwiredTax -->
        <dependency>
            <groupId>examples.tax</groupId>
            <artifactId>tax-dao</artifactId>
        </dependency>
        <!-- Hibernate, el controlador JDBC de MySQL y Logback -->
        <dependency>
            <groupId>org.hibernate.orm</groupId>
            <artifactId>hibernate-core</artifactId>
        </dependency>
        <dependency>
            <groupId>com.mysql</groupId>
            <artifactId>mysql-connector-j</artifactId>
        </dependency>
        <dependency>
            <groupId>ch.qos.logback</groupId>
            <artifactId>logback-classic</artifactId>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <!-- mvn exec:java crea la base de datos [hbtaxes] -->
            <plugin>
                <groupId>org.codehaus.mojo</groupId>
                <artifactId>exec-maven-plugin</artifactId>
                <configuration>
                    <mainClass>tax.dao.CreateDatabase</mainClass>
                </configuration>
            </plugin>
        </plugins>
    </build>
  • 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:

// un tramo del impuesto tal como se almacena en la base de datos: una entidad de Hibernate
@Entity
@Table(name = "brackets")
public class Bracket {

    // la clave primaria, que no existe en el record TaxBracket
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Integer id;

    @Column(name = "limits", nullable = false, precision = 10, scale = 2)
    private BigDecimal limit;

    @Column(name = "coeffr", nullable = false, precision = 6, scale = 4)
    private BigDecimal coeffR;

    @Column(name = "coeffn", nullable = false, precision = 10, scale = 2)
    private BigDecimal coeffN;

    protected Bracket() {
    }

    public Bracket(BigDecimal limit, BigDecimal coeffR, BigDecimal coeffN) {
        this.limit = limit;
        this.coeffR = coeffR;
        this.coeffN = coeffN;
    }
}
  • 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]:

package tax.dao;

import tax.entities.TaxException;
import tax.entities.TaxBracket;
import jakarta.persistence.PersistenceException;
import java.util.List;
import org.hibernate.SessionFactory;
import org.hibernate.jpa.HibernatePersistenceConfiguration;

// una capa [dao] que lee los tramos del impuesto desde una base de datos con Hibernate
public class HibernateTax implements ITaxDao {

    // códigos de error específicos de esta implementación
    public static final int ACCESS_ERROR = 1;
    public static final int EMPTY_TABLE = 2;

    // tramos del impuesto
    private final List<TaxBracket> taxBrackets;

    // constructor: la base de datos se designa por su URL JDBC
    public HibernateTax(String url, String user, String password) {
        // un SessionFactory efímero, justo el tiempo necesario para leer la tabla
        try (SessionFactory sessionFactory = new HibernatePersistenceConfiguration("tax")
                .managedClass(Bracket.class)
                .jdbcUrl(url)
                .jdbcCredentials(user, password)
                .createEntityManagerFactory()) {
            // las filas de la tabla se proyectan al record TaxBracket de la aplicación
            String hql = "select b.limit, b.coeffR, b.coeffN from Bracket b order by b.id";
            taxBrackets = sessionFactory.fromSession(session -> session
                    .createSelectionQuery(hql, TaxBracket.class)
                    .getResultList());
        } catch (PersistenceException e) {
            // error de Hibernate o del SGBD: se envuelve en una TaxException
            throw new TaxException("Error while reading the tax brackets from the database",
                    e, ACCESS_ERROR);
        }
        // la capa [business] necesita al menos un tramo
        if (taxBrackets.isEmpty()) {
            throw new TaxException("The tax brackets table is empty", EMPTY_TABLE);
        }
    }

    @Override
    public List<TaxBracket> getTaxBrackets() {
        return taxBrackets;
    }
}
  • 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:

package tax.dao;

import tax.entities.TaxBracket;
import org.hibernate.SessionFactory;
import org.hibernate.jpa.HibernatePersistenceConfiguration;
import org.hibernate.tool.schema.Action;

// creación de la base de datos [hbtaxes]: la tabla [brackets], llena con los tramos de la clase HardwiredTax
public class CreateDatabase {

    public static void main(String[] args) {
        try (SessionFactory sessionFactory = new HibernatePersistenceConfiguration("tax")
                .managedClass(Bracket.class)
                .jdbcUrl("jdbc:mysql://localhost:3306/hbtaxes?createDatabaseIfNotExist=true")
                .jdbcCredentials("root", "")
                // visualización de las sentencias SQL, sin formato
                .showSql(true, false, false)
                // la tabla se elimina y luego se vuelve a crear al crear el SessionFactory
                .schemaToolingAction(Action.CREATE)
                .createEntityManagerFactory()) {
            // los tramos de la escala del impuesto, los de la versión 5, numerados desde 1 por el SGBD
            sessionFactory.inTransaction(session -> {
                for (TaxBracket bracket : new HardwiredTax().getTaxBrackets()) {
                    session.persist(new Bracket(bracket.limit(), bracket.coeffR(), bracket.coeffN()));
                }
            });
        }
    }
}
  • 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:

<?xml version="1.0" encoding="UTF-8"?>
<!-- configuración de Logback: solo se muestran los errores de Hibernate -->
<configuration>
    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>%-5level %logger{0} - %msg%n</pattern>
        </encoder>
    </appender>
    <!-- los errores del SGBD se pasan a la aplicación mediante excepciones: no se registran -->
    <logger name="org.hibernate.orm.jdbc.error" level="OFF"/>
    <root level="ERROR">
        <appender-ref ref="CONSOLE"/>
    </root>
</configuration>
  • 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:

> mvn compile exec:java
Hibernate: drop table if exists brackets
Hibernate: create table brackets (coeffn decimal(10,2) not null, coeffr decimal(6,4) not null, id integer not null auto_increment, limits decimal(10,2) not null, primary key (id)) engine=InnoDB
Hibernate: insert into brackets (coeffn,coeffr,limits) values (?,?,?)
Hibernate: insert into brackets (coeffn,coeffr,limits) values (?,?,?)
Hibernate: insert into brackets (coeffn,coeffr,limits) values (?,?,?)
Hibernate: insert into brackets (coeffn,coeffr,limits) values (?,?,?)
Hibernate: insert into brackets (coeffn,coeffr,limits) values (?,?,?)
Hibernate: insert into brackets (coeffn,coeffr,limits) values (?,?,?)
Hibernate: insert into brackets (coeffn,coeffr,limits) values (?,?,?)

Verificamos el contenido de la tabla:

> mysql -uroot -t hbtaxes -e "SELECT id, limits, coeffr, coeffn FROM brackets"
+----+----------+--------+---------+
| id | limits   | coeffr | coeffn  |
+----+----------+--------+---------+
|  1 |  4962.00 | 0.0000 |    0.00 |
|  2 |  8382.00 | 0.0680 |  291.09 |
|  3 | 14753.00 | 0.1910 | 1322.92 |
|  4 | 23888.00 | 0.2830 | 2668.39 |
|  5 | 38868.00 | 0.3740 | 4846.98 |
|  6 | 47932.00 | 0.4260 | 6883.66 |
|  7 |     0.00 | 0.4810 | 9505.54 |
+----+----------+--------+---------+

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:

    <dependencies>
        <!-- las capas [business] y [ui] de la versión 5, sin cambios -->
        <dependency>
            <groupId>examples.tax</groupId>
            <artifactId>tax-business</artifactId>
        </dependency>
        <dependency>
            <groupId>examples.tax</groupId>
            <artifactId>tax-ui</artifactId>
        </dependency>
        <!-- la nueva capa [dao] -->
        <dependency>
            <groupId>examples.tax</groupId>
            <artifactId>tax-dao-hibernate</artifactId>
        </dependency>
        <!-- el contenedor de inyección de dependencias de Spring -->
        <dependency>
            <groupId>org.springframework</groupId>
            <artifactId>spring-context</artifactId>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <!-- mvn exec:java ejecuta la clase principal -->
            <plugin>
                <groupId>org.codehaus.mojo</groupId>
                <artifactId>exec-maven-plugin</artifactId>
                <configuration>
                    <mainClass>tax.ui.MainHibernate</mainClass>
                </configuration>
            </plugin>
        </plugins>
    </build>
  • 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:

1
2
3
4
# configuración de la aplicación [Tax], versión 7: la base de datos de los tramos del impuesto
jdbc.url=jdbc:mysql://localhost:3306/hbtaxes
jdbc.user=root
jdbc.password=

El archivo [tax-hibernate-error.properties] especifica una base de datos llamada [hbtaxesmissing], que no existe:

1
2
3
4
# una base de datos que no existe
jdbc.url=jdbc:mysql://localhost:3306/hbtaxesmissing
jdbc.user=root
jdbc.password=

El programa principal es el de la versión 5, en el que solo cambia la composición de la capa [dao]:

package tax.ui;

import tax.dao.HibernateTax;
import tax.dao.ITaxDao;
import tax.entities.TaxException;
import tax.business.ITaxBusiness;
import tax.business.TaxBusiness;
import java.io.IOException;
import java.io.Reader;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.Properties;
import org.springframework.context.support.GenericApplicationContext;

public class MainHibernate {

    public static void main(String[] args) {
        // el archivo de configuración: tax-hibernate.properties por defecto, o el que se pasa como argumento
        String configFile = args.length > 0 ? args[0] : "tax-hibernate.properties";

        // integración de las capas
        ITaxBusiness business;
        try {
            // lectura de la configuración, en la carpeta actual
            Properties config = new Properties();
            try (Reader reader = Files.newBufferedReader(Path.of(configFile))) {
                config.load(reader);
            }
            String url = config.getProperty("jdbc.url");
            if (url == null) {
                throw new TaxException("Database URL [jdbc.url] missing from the file " + configFile);
            }
            String user = config.getProperty("jdbc.user", "root");
            String password = config.getProperty("jdbc.password", "");

            // el contenedor Spring: las capas se registran en él
            GenericApplicationContext context = new GenericApplicationContext();
            // la capa [dao]: HibernateTax, con la base de datos de la configuración
            context.registerBean(ITaxDao.class, () -> new HibernateTax(url, user, password));
            // la capa [business] de la versión 5: el contenedor le pasará la capa [dao]
            context.registerBean(TaxBusiness.class);

            // inicio del contenedor: crea la capa [dao] y luego la capa [business]
            context.refresh();
            business = context.getBean(ITaxBusiness.class);
        } catch (IOException | RuntimeException e) {
            // visualización del error y fin del programa
            Dialog.displayError(e);
            System.exit(1);
            return;
        }

        // el diálogo con el usuario, el de la versión 5
        Dialog.run(business);
    }
}
  • 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

1
2
3
4
5
6
7
8
> mvn compile exec:java
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: y 2 60000
Tax=4282 euros
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: y 3 60000
Tax=2959 euros
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: n 0 60000
Tax=11519 euros
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop:

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:

> mvn compile exec:java -Dexec.args="tax-hibernate-error.properties"
Exception chain:
----------------------------------------
org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'tax.dao.ITaxDao': Instantiation of supplied bean failed
----------------------------------------
tax.entities.TaxException: Error while reading the tax brackets from the database
----------------------------------------
org.hibernate.service.spi.ServiceException: Unable to create requested service [org.hibernate.engine.jdbc.env.spi.JdbcEnvironment] due to: Error calling Driver.connect() [Unknown database 'hbtaxesmissing']
----------------------------------------
org.hibernate.exception.SQLGrammarException: Error calling Driver.connect() [Unknown database 'hbtaxesmissing']
----------------------------------------
java.sql.SQLSyntaxErrorException: Unknown database 'hbtaxesmissing'
----------------------------------------
  • 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.