05 - Persistencia: JPA con EntityManager

En 1.º DAW la persistencia se implementó con JDBC: SQL explícito, PreparedStatement y mapeo manual de ResultSet a objetos. JPA (Jakarta Persistence API) define una forma de relacionar objetos Java con datos persistentes. Un proveedor como Hibernate interpreta ese mapeo y ejecuta las operaciones necesarias sobre la base de datos.

En Spring podemos utilizar directamente el EntityManager o apoyarnos en Spring Data JPA, que simplifica operaciones frecuentes. JPA es una especificación; Hibernate es una de sus implementaciones. Usar JPA no elimina la necesidad de comprender el esquema, las consultas ni las transacciones.

Aspecto JDBC JPA
SQL Habitualmente se escribe para cada operación El proveedor genera SQL a partir del mapeo; también admite consultas explícitas
Conversión de filas Manual, desde ResultSet El proveedor reconstruye entidades a partir de los datos
Modificaciones Se ejecuta un UPDATE explícito El contexto de persistencia detecta cambios en entidades gestionadas
Acceso API JDBC EntityManager u otra abstracción basada en JPA

Una aplicación necesita un proveedor JPA, un controlador para la base de datos y un esquema compatible con las entidades.

En una aplicación Spring Boot con Maven, estas dependencias permiten trabajar con JPA, MariaDB y migraciones Flyway:

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-data-jpa</artifactId>
    </dependency>
    <dependency>
        <groupId>org.mariadb.jdbc</groupId>
        <artifactId>mariadb-java-client</artifactId>
        <scope>runtime</scope>
    </dependency>
    <dependency>
        <groupId>org.flywaydb</groupId>
        <artifactId>flyway-core</artifactId>
    </dependency>
    <dependency>
        <groupId>org.flywaydb</groupId>
        <artifactId>flyway-mysql</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>

El proyecto debe utilizar una versión de Spring Boot que gestione las versiones de estas dependencias. En versiones recientes de Flyway, el soporte para MariaDB se proporciona mediante flyway-mysql; comprueba las dependencias necesarias si trabajas con otra versión. Aunque usemos EntityManager directamente, el starter aporta la integración JPA de Spring Boot y Hibernate.

spring.datasource.url=jdbc:mariadb://localhost:3306/app
spring.datasource.username=${DB_USER}
spring.datasource.password=${DB_PASSWORD}
spring.jpa.hibernate.ddl-auto=validate
spring.jpa.open-in-view=false
  • DB_USER y DB_PASSWORD se suministran mediante variables de entorno; no se incluyen contraseñas en el código.
  • Flyway aplica migraciones versionadas para crear y modificar el esquema.
  • ddl-auto=validate comprueba la compatibilidad básica del mapeo con el esquema; no crea ni actualiza las tablas. No sustituye a las pruebas de restricciones y consultas.
  • open-in-view=false evita mantener abierto el contexto de persistencia durante toda la petición web. Las relaciones necesarias deben cargarse y convertirse dentro de la transacción.

Para el ejemplo de pedidos, una primera migración podría guardarse en src/main/resources/db/migration/V1__create_orders.sql:

CREATE TABLE orders (
    id BIGINT NOT NULL AUTO_INCREMENT,
    customer_id VARCHAR(100) NOT NULL,
    STATUS VARCHAR(20) NOT NULL,
    PRIMARY KEY (id)
);
 
CREATE TABLE order_lines (
    id BIGINT NOT NULL AUTO_INCREMENT,
    order_id BIGINT NOT NULL,
    product_id VARCHAR(100) NOT NULL,
    quantity INT NOT NULL,
    PRIMARY KEY (id),
    CONSTRAINT fk_order_lines_order
        FOREIGN KEY (order_id) REFERENCES orders (id)
);

La base de datos y el usuario deben existir antes de arrancar la aplicación, y el usuario debe tener permisos para aplicar las migraciones.

Una entidad JPA es un objeto cuya identidad y persistencia gestiona el proveedor. En nuestra arquitectura, las entidades pertenecen a persistence: describen cómo se almacenan los datos. El modelo de domain representa los conceptos y reglas del negocio. Aunque ambos representen un mismo pedido, no son el mismo objeto: un mapper convierte entre ambas representaciones.

Anotación Función
@Entity Declara una clase como entidad JPA
@Table(name = “…”) Indica la tabla asociada
@Id Marca el identificador de la entidad
@GeneratedValue Indica cómo se genera el identificador
@Column Configura la columna: nombre, nulabilidad, longitud y otras propiedades
@Enumerated(EnumType.STRING) Almacena el nombre de una constante de un enum
@Embedded Incluye en la entidad los atributos de un tipo embebido
@Embeddable Declara un tipo cuyos atributos pueden formar parte de una entidad
@Transient Excluye un atributo del mapeo persistente
@Version Marca una versión para detectar conflictos de concurrencia optimista

Una entidad necesita un constructor sin argumentos public o protected para que JPA pueda instanciarla. La clase y los elementos persistentes no deben ser final. En los ejemplos se usa acceso por campos: como @Id está sobre un campo, JPA accede a los campos persistentes. También existe acceso por propiedades, con las anotaciones en los getters; evita mezclar ambos sin configurar explícitamente el acceso.

GenerationType.IDENTITY delega la generación del identificador en una columna autoincremental de la base de datos. El proveedor puede tener que ejecutar el INSERT antes del flush para obtenerlo. Con EnumType.STRING, PENDING se almacena como texto: es legible, pero cambiar el nombre de una constante requiere tratar los datos existentes mediante una migración.

También existen otras estrategias de identificador: SEQUENCE utiliza una secuencia de la base de datos, TABLE una tabla de generación y AUTO deja la elección al proveedor. Su disponibilidad y comportamiento dependen de la base de datos y su configuración. Sin @GeneratedValue, la aplicación asigna el identificador.

En @Column, name establece el nombre de la columna, nullable y unique describen restricciones, length se usa para columnas de texto y precision/scale para decimales. insertable y updatable controlan si el proveedor incluye la columna en esas sentencias. Estas opciones no reemplazan las restricciones reales del esquema: cuando Flyway gestiona las tablas, hay que definirlas en las migraciones.

Un tipo embebido agrupa atributos que pertenecen a una entidad, pero no tiene identidad propia como entidad:

@Embeddable
public class AddressEntity {
    @Column(name = "street", nullable = false)
    private String street;
 
    @Column(name = "city", nullable = false)
    private String city;
 
    protected AddressEntity() {
    }
 
    public AddressEntity(String street, String city) {
        this.street = street;
        this.city = city;
    }
}

Una entidad podría incorporarlo con @Embedded private AddressEntity address;. Sus columnas formarían parte de la tabla de esa entidad. Un value object del dominio puede transformarse a este tipo mediante el mapper, sin convertir el propio value object en una entidad JPA.

Las anotaciones deben corresponderse con las claves externas o tablas intermedias del esquema:

Relación Anotaciones habituales Representación frecuente
Uno a muchos @OneToMany y @ManyToOne Clave externa en el lado «muchos»
Uno a uno @OneToOne Clave externa o clave primaria compartida
Muchos a muchos @ManyToMany Tabla intermedia con claves externas

En el ejemplo, un pedido tiene varias líneas y cada línea pertenece a un pedido. La columna order_lines.order_id contiene la clave externa; las clases completas aparecen en el apartado 5.

En una relación bidireccional, el lado propietario es el que JPA utiliza para actualizar la relación en la base de datos.

  • OrderLineEntity.order, anotado con @ManyToOne, es el propietario: su @JoinColumn(name = “order_id”) representa la clave externa.
  • OrderEntity.lines es el lado inverso: mappedBy = “order” señala el nombre del atributo Java que posee la relación, no el nombre de la columna.
  • Hay que mantener coherentes ambos lados en memoria. Añadir una línea solo a la lista del pedido no establece por sí solo line.order.

Si la relación solo se recorriera en un sentido, podría modelarse como unidireccional. La bidireccionalidad es útil cuando se necesitan ambos recorridos, pero exige mantenerlos sincronizados.

En una relación uno a uno, el lado con @JoinColumn suele contener la clave externa; el esquema debe imponer unicidad sobre esa columna si se quiere garantizar la cardinalidad. En una relación muchos a muchos, el propietario puede declarar @JoinTable para describir la tabla intermedia y sus dos claves externas; el lado inverso usa mappedBy. Si la asociación necesita atributos propios, como fecha o cantidad, suele representarse con una entidad intermedia en lugar de @ManyToMany. Evita propagar REMOVE a entidades compartidas que pueden seguir relacionadas con otros objetos.

Cascada significa propagar determinadas operaciones de una entidad a sus entidades relacionadas:

  • PERSIST: propaga persist.
  • MERGE: propaga merge.
  • REMOVE: propaga remove.
  • ALL: incluye las anteriores y también REFRESH y DETACH.

La cascada no define la clave externa ni cambia el lado propietario. Tampoco equivale a una cláusula SQL ON DELETE CASCADE. Con orphanRemoval = true, al retirar una línea de la colección de un pedido gestionado, JPA programa su eliminación. Es apropiado cuando la línea pertenece exclusivamente a ese pedido; no debe aplicarse automáticamente a entidades compartidas.

Carga perezosa (LAZY) significa que la relación puede cargarse cuando se accede a ella. Carga ansiosa (EAGER) solicita que esté disponible al recuperar la entidad. Según JPA, los valores predeterminados son:

Anotación Fetch predeterminado
@OneToMany, @ManyToMany LAZY
@ManyToOne, @OneToOne EAGER

EAGER no garantiza una sola consulta: el proveedor puede usar consultas adicionales. LAZY expresa una estrategia de carga perezosa, pero JPA la define como una indicación al proveedor, no como una garantía absoluta en todos los casos.

El problema N+1 aparece, por ejemplo, al ejecutar una consulta para obtener N pedidos y después otra por cada pedido al acceder a sus líneas. LAZY evita cargar relaciones que no se usan, pero no elimina por sí solo este problema.

Para un caso de uso concreto se puede preparar una consulta con join fetch o un @EntityGraph. Hay que comprobar el SQL generado y tener cuidado con la paginación de colecciones obtenidas mediante fetch join, pues puede producir resultados o rendimiento inesperados. Con open-in-view=false, acceder a una relación aún no cargada después de cerrar el contexto puede fallar. El adaptador debe obtener y convertir los datos necesarios dentro de la transacción.

En una arquitectura modular, una entidad de un módulo no debería depender directamente de las entidades internas de otro. Puede guardar el identificador del recurso externo y consultar al otro módulo mediante sus contratos.

El EntityManager es la API principal de JPA para gestionar entidades y consultas. En Spring se puede obtener mediante @PersistenceContext. El contexto de persistencia mantiene las entidades gestionadas durante una unidad de trabajo y garantiza, dentro de ese contexto, una identidad gestionada para cada entidad de un tipo e identificador.

Operación Uso
persist(entity) Hace gestionada una entidad nueva y programa su inserción
find(Entity.class, id) Busca por tipo e identificador; devuelve null si no existe
merge(entity) Copia el estado al contexto y devuelve la instancia gestionada
remove(entity) Marca una entidad gestionada para su eliminación
flush() Sincroniza los cambios pendientes con la base de datos
clear() Separa todas las entidades del contexto
detach(entity) Separa una entidad concreta

Una entidad puede encontrarse en estos estados:

  • Nueva: se ha creado en Java, pero aún no pertenece a un contexto de persistencia.
  • Gestionada: pertenece al contexto; JPA detecta cambios en sus atributos persistentes.
  • Separada: representa una entidad persistente, pero ya no está gestionada por ese contexto.
  • Eliminada: se ha marcado para borrar dentro del contexto; el borrado se sincroniza con la base de datos.

NuevaGestionadaSeparadaEliminadaCon merge, el objeto originalcontinúa separado.find obtiene una instancia gestionadacuando existe el registro.flush sincroniza SQL: no cambiapor sí solo el estado ni hace commit.creaciónpersistdetach / clear /cierre del contextomerge: copia ainstancia gestionadaremovepersist antesde completar el borradoeliminación completada

Si una entidad gestionada cambia dentro de una transacción, el proveedor detecta la diferencia y puede generar un UPDATE al sincronizar. Este mecanismo se conoce como dirty checking.

OrderEntity entity = entityManager.find(OrderEntity.class, orderId);
entity.status = OrderStatus.CANCELLED;
// Si la entidad sigue gestionada, JPA detecta el cambio.

El fragmento presupone una transacción activa y que el pedido existe. merge funciona de otra manera:

OrderEntity managed = entityManager.merge(detached);
managed.status = OrderStatus.CANCELLED;
Si detached estaba separada, no se vuelve gestionada por llamar a merge. JPA copia su estado y devuelve la instancia gestionada, que puede ser distinta. Hay que continuar trabajando con el valor devuelto.

Copiar un grafo separado incompleto puede sobrescribir asociaciones o provocar eliminaciones no deseadas. Para modificar un pedido existente, el ejemplo de este tema carga la entidad gestionada y actualiza sus líneas explícitamente. El dirty checking afecta a entidades gestionadas, no a los objetos del dominio convertidos por un mapper. Si cambiamos un objeto Order del dominio, debemos comunicar ese cambio al repositorio; JPA no observa ese objeto.

flush() envía a la base de datos las inserciones, actualizaciones y eliminaciones pendientes. Permite, por ejemplo, detectar algunas violaciones de restricciones antes de que termine el método.

  • flush no confirma la transacción; un rollback posterior revierte los cambios transaccionales ya sincronizados.
  • El proveedor puede sincronizar antes de un flush explícito, por ejemplo antes de algunas consultas o para obtener un identificador.
  • El commit confirma la transacción; normalmente incluye la sincronización necesaria de los cambios pendientes.

El ejemplo utiliza estas responsabilidades:

  • domain contiene el modelo y el contrato OrderRepository.
  • persistence.dao.entity contiene las entidades anotadas.
  • persistence.dao define la interfaz OrderDao.
  • persistence.dao.impl.jpa implementa el DAO con EntityManager.
  • persistence.repository.mapper convierte entre entidades y modelo.
  • persistence.repository.impl implementa el repositorio del dominio utilizando el DAO y el mapper.

domainpersistencerepositoryimplmapperdaoimpljpaentityServicio de aplicaciónOrderRepositoryOrderOrderRepositoryImplOrderPersistenceMapperOrderDaoOrderDaoJpaOrderEntityOrderLineEntityEntityManagerHibernateBase de datosutiliza10..*

La interfaz DAO de este diseño conoce OrderEntity, pero esa dependencia queda dentro de persistence. El dominio sigue siendo independiente de JPA. Una abstracción DAO que tampoco conociera entidades JPA necesitaría otros tipos en su contrato y una conversión adicional.

En los bloques Java siguientes, cada clase o interfaz pública va en su propio archivo, en el paquete indicado. Se omiten algunos import para centrarse en la implementación; las anotaciones JPA pertenecen a jakarta.persistence y las de Spring a sus paquetes correspondientes.

Los nombres de paquetes son abreviados para mostrar las responsabilidades. En una aplicación real, sitúa domain y persistence bajo un paquete raíz común al de la aplicación Spring Boot, o configura explícitamente el escaneo de componentes, entidades y repositorios. Adapta también el nombre completo del constructor JPQL del apartado 6 al paquete real.

// domain/model/OrderStatus.java
package domain.model;
 
public enum OrderStatus {
    PENDING,
    CANCELLED
}
// domain/model/OrderLine.java
package domain.model;
 
public record OrderLine(Long id, String productId, int quantity) {
    public OrderLine {
        if (productId == null || productId.isBlank() || quantity <= 0) {
            throw new IllegalArgumentException("Invalid order line");
        }
    }
}
// domain/model/Order.java
package domain.model;
 
import java.util.List;
 
public record Order(Long id, String customerId, OrderStatus status,
        List<OrderLine> lines) {
    public Order {
        if (customerId == null || customerId.isBlank() || status == null) {
            throw new IllegalArgumentException("Invalid order");
        }
        lines = List.copyOf(lines);
    }
 
    public Order cancel() {
        if (status != OrderStatus.PENDING) {
            throw new IllegalStateException("Only pending orders can be cancelled");
        }
        return new Order(id, customerId, OrderStatus.CANCELLED, lines);
    }
}
// domain/repository/OrderRepository.java
package domain.repository;
 
import domain.model.Order;
import java.util.Optional;
 
public interface OrderRepository {
    Optional<Order> findById(long id);
    Order save(Order order);
}

Los registros son inmutables: cancel() devuelve un pedido nuevo. Un pedido o una línea sin persistir tienen id == null.

Para mantener el ejemplo pequeño, sus campos son públicos. En una aplicación real se pueden encapsular con getters y métodos de modificación; JPA sigue pudiendo usar acceso por campos.

// persistence/dao/entity/OrderEntity.java
package persistence.dao.entity;
 
import domain.model.OrderStatus;
import java.util.ArrayList;
import java.util.List;
 
@Entity
@Table(name = "orders")
public class OrderEntity {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    public Long id;
 
    @Column(name = "customer_id", nullable = false, length = 100)
    public String customerId;
 
    @Enumerated(EnumType.STRING)
    @Column(name = "status", nullable = false, length = 20)
    public OrderStatus status;
 
    @OneToMany(mappedBy = "order", cascade = CascadeType.ALL,
            orphanRemoval = true, fetch = FetchType.LAZY)
    public List<OrderLineEntity> lines = new ArrayList<>();
 
    protected OrderEntity() {
    }
 
    public OrderEntity(String customerId, OrderStatus status) {
        this.customerId = customerId;
        this.status = status;
    }
 
    public void addLine(OrderLineEntity line) {
        lines.add(line);
        line.order = this;
    }
 
    public void removeLine(OrderLineEntity line) {
        lines.remove(line);
        line.order = null;
    }
}
// persistence/dao/entity/OrderLineEntity.java
package persistence.dao.entity;
 
@Entity
@Table(name = "order_lines")
public class OrderLineEntity {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    public Long id;
 
    @ManyToOne(fetch = FetchType.LAZY, optional = false)
    @JoinColumn(name = "order_id", nullable = false)
    public OrderEntity order;
 
    @Column(name = "product_id", nullable = false, length = 100)
    public String productId;
 
    @Column(name = "quantity", nullable = false)
    public int quantity;
 
    protected OrderLineEntity() {
    }
 
    public OrderLineEntity(String productId, int quantity) {
        this.productId = productId;
        this.quantity = quantity;
    }
}

addLine y removeLine mantienen los dos lados de la relación. En la eliminación, orphanRemoval programa el borrado de la línea; no se pretende conservarla con order_id nulo. Aquí la entidad reutiliza OrderStatus, un tipo del dominio. La dependencia va de persistence hacia domain, no al contrario.

// persistence/dao/OrderDao.java
package persistence.dao;
 
import java.util.Optional;
import persistence.dao.entity.OrderEntity;
 
public interface OrderDao {
    Optional<OrderEntity> findById(long id);
    OrderEntity save(OrderEntity entity);
    void flush();
}
// persistence/dao/impl/jpa/OrderDaoJpa.java
package persistence.dao.impl.jpa;
 
import java.util.Optional;
import persistence.dao.OrderDao;
import persistence.dao.entity.OrderEntity;
 
@Repository
public class OrderDaoJpa implements OrderDao {
    @PersistenceContext
    private EntityManager entityManager;
 
    @Override
    public Optional<OrderEntity> findById(long id) {
        return Optional.ofNullable(entityManager.find(OrderEntity.class, id));
    }
 
    @Override
    public OrderEntity save(OrderEntity entity) {
        if (entity.id == null) {
            entityManager.persist(entity);
            return entity;
        }
        if (entityManager.contains(entity)) {
            return entity;
        }
        return entityManager.merge(entity);
    }
 
    @Override
    public void flush() {
        entityManager.flush();
    }
}

El DAO presupone que se ejecuta dentro de una transacción para las operaciones de escritura. Para una entidad nueva utiliza persist; para una separada devuelve el resultado de merge. Si ya está gestionada, no necesita volver a guardarla para que JPA detecte sus cambios.

La rama de merge es parte del contrato de este DAO, pero el adaptador siguiente no construye un grafo separado para actualizar pedidos existentes: primero carga la entidad y modifica su colección gestionada. Así evita reemplazarla accidentalmente por una colección parcial.

El mapper convierte datos y sincroniza la representación persistente; no decide si una operación de negocio, como cancelar un pedido, está permitida.

// persistence/repository/mapper/OrderPersistenceMapper.java
package persistence.repository.mapper;
 
import domain.model.Order;
import domain.model.OrderLine;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.HashSet;
import java.util.Map;
import java.util.Set;
import persistence.dao.entity.OrderEntity;
import persistence.dao.entity.OrderLineEntity;
 
@Component
public class OrderPersistenceMapper {
    public Order toModel(OrderEntity entity) {
        return new Order(entity.id, entity.customerId, entity.status,
                entity.lines.stream()
                        .map(line -> new OrderLine(
                                line.id, line.productId, line.quantity))
                        .toList());
    }
 
    public OrderEntity toNewEntity(Order order) {
        if (order.id() != null
                || order.lines().stream().anyMatch(line -> line.id() != null)) {
            throw new IllegalArgumentException("A new order cannot contain existing IDs");
        }
        OrderEntity entity = new OrderEntity(order.customerId(), order.status());
        for (OrderLine line : order.lines()) {
            entity.addLine(new OrderLineEntity(line.productId(), line.quantity()));
        }
        return entity;
    }
 
    public void updateManagedEntity(Order order, OrderEntity entity) {
        Map<Long, OrderLineEntity> existing = new HashMap<>();
        for (OrderLineEntity line : entity.lines) {
            existing.put(line.id, line);
        }
 
        // Validar antes de modificar el grafo gestionado.
        Set<Long> retainedIds = new HashSet<>();
        for (OrderLine line : order.lines()) {
            if (line.id() != null
                    && (!existing.containsKey(line.id()) || !retainedIds.add(line.id()))) {
                throw new IllegalArgumentException("Unknown or duplicate order line ID");
            }
        }
 
        entity.customerId = order.customerId();
        entity.status = order.status();
        for (OrderLineEntity line : new ArrayList<>(entity.lines)) {
            if (!retainedIds.contains(line.id)) {
                entity.removeLine(line);
            }
        }
        for (OrderLine line : order.lines()) {
            if (line.id() == null) {
                entity.addLine(new OrderLineEntity(line.productId(), line.quantity()));
            } else {
                OrderLineEntity managedLine = existing.get(line.id());
                managedLine.productId = line.productId();
                managedLine.quantity = line.quantity();
            }
        }
    }
}

Para actualizar, el método identifica las líneas que ya pertenecen al pedido, rechaza identificadores ajenos o duplicados, retira las que no aparecen en el modelo, actualiza las conservadas y añade las nuevas mediante addLine. orphanRemoval elimina las retiradas.

El ejemplo trata la lista recibida como la colección completa deseada, no como una actualización parcial. Para una operación parcial haría falta otro contrato. Tampoco persiste el orden de la lista: si el orden es una regla de negocio, hay que modelarlo y almacenarlo explícitamente. MapStruct puede generar conversiones sencillas durante la compilación, pero no elimina la necesidad de diseñar la sincronización de relaciones gestionadas. Aquí se usa un mapper manual para hacer explícito ese comportamiento.

// persistence/repository/impl/OrderRepositoryImpl.java
package persistence.repository.impl;
 
import domain.model.Order;
import domain.repository.OrderRepository;
import java.util.Optional;
import persistence.dao.OrderDao;
import persistence.dao.entity.OrderEntity;
import persistence.repository.mapper.OrderPersistenceMapper;
 
@Repository
public class OrderRepositoryImpl implements OrderRepository {
    private final OrderDao dao;
    private final OrderPersistenceMapper mapper;
 
    public OrderRepositoryImpl(OrderDao dao, OrderPersistenceMapper mapper) {
        this.dao = dao;
        this.mapper = mapper;
    }
 
    @Override
    public Optional<Order> findById(long id) {
        return dao.findById(id).map(mapper::toModel);
    }
 
    @Override
    public Order save(Order order) {
        OrderEntity entity;
        if (order.id() == null) {
            entity = mapper.toNewEntity(order);
        } else {
            entity = dao.findById(order.id())
                    .orElseThrow(() -> new IllegalArgumentException("Order not found"));
            mapper.updateManagedEntity(order, entity);
        }
        OrderEntity managed = dao.save(entity);
        dao.flush();
        return mapper.toModel(managed);
    }
}

El adaptador se usa dentro de una transacción. findById transforma las líneas mientras el contexto está disponible. save hace flush para sincronizar la operación y disponer de los identificadores generados antes de devolver el modelo; esto no confirma la transacción.

Para simplificar, el ejemplo no implementa control de concurrencia. En una aplicación real, dos modificaciones simultáneas pueden sobrescribirse; una versión con @Version permite detectar conflictos mediante bloqueo optimista.

JPQL consulta entidades y atributos Java, no tablas ni columnas SQL. Este fragmento, dentro de un componente con entityManager, busca pedidos de un estado y carga sus líneas:

List<OrderEntity> orders = entityManager.createQuery(
        "select distinct o from OrderEntity o "
                + "left join fetch o.lines "
                + "where o.status = :status",
        OrderEntity.class)
        .setParameter("status", OrderStatus.PENDING)
        .getResultList();
  • OrderEntity, status y lines son nombres del modelo JPA.
  • left join fetch también conserva pedidos sin líneas; distinct solicita resultados de pedidos sin duplicados.
  • Los valores se pasan mediante parámetros; no se concatenan datos recibidos en la consulta.

Una consulta preparada para un caso de uso evita cargar colecciones una por una. Para una lista paginada de pedidos con líneas, conviene estudiar una estrategia específica, como paginar primero identificadores y cargar después sus relaciones.

Una proyección recupera únicamente los datos necesarios. JPA permite construir un objeto de resultados en JPQL:

// persistence/projection/OrderSummary.java
package persistence.projection;
 
import domain.model.OrderStatus;
 
public record OrderSummary(Long id, String customerId, OrderStatus status) {
}
List<OrderSummary> summaries = entityManager.createQuery(
        "select new persistence.projection.OrderSummary("
                + "o.id, o.customerId, o.status) "
                + "from OrderEntity o where o.status = :status",
        OrderSummary.class)
        .setParameter("status", OrderStatus.PENDING)
        .getResultList();

JPQL requiere el nombre completo de la clase y un constructor compatible con los valores seleccionados. Los resultados son objetos normales, no entidades gestionadas: modificarlos no activa dirty checking. OrderSummary pertenece a persistencia. Si un caso de uso necesita esos datos, el adaptador los transforma a un tipo definido por la capa correspondiente; no expone esta proyección interna al dominio.

Una transacción agrupa operaciones que deben completarse juntas. commit confirma los cambios y rollback los revierte. En Spring, @Transactional permite delimitar la unidad de trabajo alrededor de un caso de uso.

@Service
public class CancelOrder {
    private final OrderRepository orderRepository;
 
    public CancelOrder(OrderRepository orderRepository) {
        this.orderRepository = orderRepository;
    }
 
    @Transactional
    public void cancel(long orderId) {
        Order order = orderRepository.findById(orderId)
                .orElseThrow(() -> new IllegalArgumentException("Order not found"));
        Order cancelled = order.cancel();
        orderRepository.save(cancelled);
    }
}

Order es un objeto de dominio separado de OrderEntity. Por eso cancel() no modifica directamente ninguna entidad gestionada: save comunica el nuevo estado al adaptador, que actualiza la entidad. La transacción engloba tanto la lectura como la escritura. Si el método termina correctamente, Spring intenta confirmar; ante una excepción no comprobada, por defecto marca la transacción para rollback. Las excepciones comprobadas no provocan rollback por defecto, salvo configuración.

En la configuración habitual basada en proxies de Spring, la llamada debe atravesar el proxy: una llamada interna de un método a otro método @Transactional del mismo objeto no inicia por sí sola la interceptación. Mantén las transacciones suficientemente cortas para no retener recursos y bloqueos innecesariamente.

Spring Data JPA puede proporcionar las operaciones habituales de acceso a entidades sin escribir un DAO con EntityManager para cada caso. Funcionalmente cubre buena parte del papel del DAO; no genera automáticamente nuestra interfaz OrderDao.

Una interfaz interna de persistencia puede extender JpaRepository:

// persistence/dao/impl/jpa/OrderSpringDataRepository.java
package persistence.dao.impl.jpa;
 
import domain.model.OrderStatus;
import java.util.List;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.data.jpa.repository.Query;
import org.springframework.data.repository.query.Param;
import persistence.dao.entity.OrderEntity;
 
public interface OrderSpringDataRepository
        extends JpaRepository<OrderEntity, Long> {
    List<OrderEntity> findByStatus(OrderStatus status);
 
    @Query("select distinct o from OrderEntity o "
            + "left join fetch o.lines where o.status = :status")
    List<OrderEntity> findWithLinesByStatus(@Param("status") OrderStatus status);
}

Spring Data implementa la interfaz y puede derivar consultas como findByStatus a partir del nombre. Para consultas más específicas se puede usar @Query.

Hay dos opciones coherentes:

  1. El adaptador del repositorio de dominio utiliza directamente OrderSpringDataRepository como detalle interno de persistence.
  2. Se conserva OrderDao y se escribe un adaptador que delega en Spring Data. En ese caso, se sustituye OrderDaoJpa por este adaptador, evitando registrar dos implementaciones ambiguas de OrderDao.

El siguiente bloque ilustra la segunda opción:

// persistence/dao/impl/jpa/SpringDataOrderDao.java
package persistence.dao.impl.jpa;
 
import java.util.Optional;
import persistence.dao.OrderDao;
import persistence.dao.entity.OrderEntity;
 
@Repository
public class SpringDataOrderDao implements OrderDao {
    private final OrderSpringDataRepository repository;
 
    public SpringDataOrderDao(OrderSpringDataRepository repository) {
        this.repository = repository;
    }
 
    @Override
    public Optional<OrderEntity> findById(long id) {
        return repository.findById(id);
    }
 
    @Override
    public OrderEntity save(OrderEntity entity) {
        return repository.save(entity);
    }
 
    @Override
    public void flush() {
        repository.flush();
    }
}

No se hace que OrderSpringDataRepository extienda a la vez JpaRepository y OrderDao: sus firmas de save no son equivalentes y pueden entrar en conflicto por sus genéricos. La delegación mantiene ambos contratos separados. Como ocurre con merge, hay que utilizar el valor devuelto por save. El adaptador de dominio sigue cargando y actualizando la entidad gestionada para evitar sustituir relaciones por un grafo incompleto.

Spring Data también admite proyecciones mediante interfaces. Esto es una funcionalidad de Spring Data, no una proyección por interfaz definida por JPA:

// persistence/projection/OrderSummaryView.java
package persistence.projection;
 
import domain.model.OrderStatus;
 
public interface OrderSummaryView {
    Long getId();
    String getCustomerId();
    OrderStatus getStatus();
}

El siguiente método se añadiría a OrderSpringDataRepository:

List<OrderSummaryView> findProjectedByStatus(OrderStatus status);

Spring Data crea vistas de los resultados a partir de las propiedades solicitadas. Estas proyecciones tampoco son entidades gestionadas y deben permanecer dentro de persistence; el adaptador las transforma si otro componente necesita sus datos.

Opción Característica
EntityManager Control explícito de operaciones y consultas JPA
JpaRepository Reduce código repetitivo para CRUD y consultas habituales
Constructor JPQL Proyección de JPA hacia una clase o registro con constructor compatible
Proyección por interfaz Funcionalidad proporcionada por Spring Data

Ninguna de estas opciones exige que el dominio conozca Hibernate, EntityManager o Spring Data.

Las pruebas de persistencia comprueban aspectos que un mock no verifica: el esquema, el mapeo, las relaciones, las consultas y la interacción con la base de datos.

@DataJpaTest prepara la infraestructura JPA y ejecuta cada prueba en una transacción que normalmente se revierte al terminar. Para probar también el adaptador y el mapper, se importan explícitamente sus componentes.

El siguiente ejemplo usa una base MariaDB de pruebas configurada mediante las propiedades del entorno. @AutoConfigureTestDatabase(replace = NONE) impide que Spring la sustituya por una base embebida. La base debe estar disponible y Flyway debe poder aplicar la migración anterior.

@DataJpaTest
@AutoConfigureTestDatabase(replace = AutoConfigureTestDatabase.Replace.NONE)
@Import({
        OrderDaoJpa.class,
        OrderPersistenceMapper.class,
        OrderRepositoryImpl.class
})
class OrderPersistenceTest {
    @Autowired
    private OrderRepository orderRepository;
 
    @PersistenceContext
    private EntityManager entityManager;
 
    @Test
    void savesAndReloadsOrderWithLines() {
        Order order = new Order(null, "customer-123", OrderStatus.PENDING,
                List.of(new OrderLine(null, "product-1", 2)));
        Order saved = orderRepository.save(order);
        entityManager.flush();
        entityManager.clear();
 
        Order loaded = orderRepository.findById(saved.id()).orElseThrow();
        assertThat(loaded.customerId()).isEqualTo("customer-123");
        assertThat(loaded.status()).isEqualTo(OrderStatus.PENDING);
        assertThat(loaded.lines()).hasSize(1);
        assertThat(loaded.lines().get(0).productId()).isEqualTo("product-1");
        assertThat(loaded.lines().get(0).quantity()).isEqualTo(2);
    }
}

Los imports de anotaciones y aserciones se omiten, igual que en los ejemplos anteriores. flush() fuerza la sincronización; clear() separa las entidades para que la lectura posterior no reutilice simplemente la instancia que seguía en el contexto. Una caché de segundo nivel, si se habilita, puede intervenir en la recuperación; hay que tenerla en cuenta cuando la prueba pretenda verificar una consulta concreta a la base de datos.

También conviene probar:

  • La eliminación de una línea con orphanRemoval y la actualización de líneas existentes.
  • El rechazo de identificadores de líneas pertenecientes a otro pedido.
  • Las consultas JPQL y las relaciones que deben cargarse.
  • Los errores de restricciones y el rollback.
  • El comportamiento transaccional mediante una prueba que atraviese el servicio y compruebe los datos después de finalizar la transacción.

Para automatizar pruebas reproducibles puede utilizarse Testcontainers con MariaDB. Probar contra la misma tecnología que producción reduce las diferencias respecto a una base embebida. Las reglas de negocio, como qué pedidos se pueden cancelar, se prueban aparte mediante pruebas unitarias del dominio, sin base de datos.

  • clase/daw/dws/jpa.txt
  • Última modificación: 2026/11/11 08:56
  • por cesguiro