spring-projects/spring-framework

spring-orm

Active contributors: Juergen Hoeller, Sam Brannen

Purpose

spring-orm integrates Spring with JPA (Jakarta Persistence) and Hibernate. It provides a Spring-managed EntityManagerFactory setup, JPA-flavored transaction support (JpaTransactionManager), Repository exception translation, and the @PersistenceContext injection support. It is the bridge between the JDBC/transaction abstractions in spring-jdbc/spring-tx and ORM tooling.

Directory layout

spring-orm/
└── src/main/java/org/springframework/orm/
    ├── ObjectRetrievalFailureException.java
    ├── jpa/
    │   ├── EntityManagerFactoryUtils.java
    │   ├── JpaTransactionManager.java
    │   ├── LocalContainerEntityManagerFactoryBean.java
    │   ├── LocalEntityManagerFactoryBean.java
    │   ├── persistenceunit/
    │   ├── support/                                # @PersistenceContext processor
    │   └── vendor/                                 # HibernateJpaVendorAdapter, EclipseLinkJpaVendorAdapter
    └── hibernate6/                                 # Hibernate 6 integration helpers

Key abstractions

Type	File	Role
`LocalContainerEntityManagerFactoryBean`	`spring-orm/src/main/java/org/springframework/orm/jpa/LocalContainerEntityManagerFactoryBean.java`	Programmatic JPA bootstrapping (no `persistence.xml` needed)
`LocalEntityManagerFactoryBean`	`spring-orm/src/main/java/org/springframework/orm/jpa/LocalEntityManagerFactoryBean.java`	`persistence.xml`-driven setup
`JpaTransactionManager`	`spring-orm/src/main/java/org/springframework/orm/jpa/JpaTransactionManager.java`	Tx manager that integrates with JPA's `EntityTransaction`
`JpaVendorAdapter`	`spring-orm/src/main/java/org/springframework/orm/jpa/JpaVendorAdapter.java`	Vendor-specific behavior plug-in
`HibernateJpaVendorAdapter`	`spring-orm/src/main/java/org/springframework/orm/jpa/vendor/HibernateJpaVendorAdapter.java`	Hibernate adapter
`EclipseLinkJpaVendorAdapter`	`spring-orm/src/main/java/org/springframework/orm/jpa/vendor/EclipseLinkJpaVendorAdapter.java`	EclipseLink adapter
`PersistenceAnnotationBeanPostProcessor`	`spring-orm/src/main/java/org/springframework/orm/jpa/support/PersistenceAnnotationBeanPostProcessor.java`	Processes `@PersistenceContext` and `@PersistenceUnit`
`EntityManagerFactoryUtils`	`spring-orm/src/main/java/org/springframework/orm/jpa/EntityManagerFactoryUtils.java`	Tx-aware EM acquisition / exception translation

How it works

graph LR
    Bootstrap["LocalContainerEntityManagerFactoryBean"] -->|"creates"| EMF[EntityManagerFactory]
    EMF -->|"injected via @PersistenceContext"| Repo[Repository / Service]
    Repo -->|"persist/find/merge/remove"| EM[EntityManager]
    Tx["@Transactional"] -.AOP.-> Repo
    Tx -->|"controls via JpaTransactionManager"| EMF
    Repo -->|"underneath"| DS[DataSource]

LocalContainerEntityManagerFactoryBean is the de-facto standard JPA setup in Spring applications. You configure:

dataSource — JDBC DataSource to use
packagesToScan — packages with @Entity classes
jpaVendorAdapter — HibernateJpaVendorAdapter or EclipseLinkJpaVendorAdapter
jpaProperties — vendor-specific properties

@PersistenceContext injects an EntityManager proxy that delegates to the transaction-bound EntityManager (or a stand-alone one if no transaction is active). JpaTransactionManager ties the EntityManager's EntityTransaction to Spring's transaction model.

Exception translation

Spring's @Repository annotation participates in persistence exception translation via PersistenceExceptionTranslationPostProcessor. JPA's PersistenceException and Hibernate's exceptions are caught and translated to DataAccessExceptions — keeping data-access code free of vendor-specific catch blocks.

GraalVM hints

spring-orm includes AOT support: it registers reflection hints for @Entity classes and JPA infrastructure to keep them reachable in native images. See spring-orm/src/main/java/org/springframework/orm/jpa/persistenceunit/PersistenceManagedTypesBeanRegistrationAotProcessor.java for the AOT contribution.

Integration points

Depends on spring-beans, spring-core, spring-jdbc, spring-tx.
Optional dep spring-aop (for @PersistenceContext proxying).
Used by Spring Data JPA (which builds repositories on top), all JPA-using applications.

Entry points for modification

New JPA vendor adapter — Implement JpaVendorAdapter. Vendor-specific dialect, Hibernate-flush-mode handling, etc.
Custom EntityManager proxying — Subclass SharedEntityManagerCreator.
Persistence-unit customization — Provide a PersistenceUnitManager.

Caveats

Hibernate's native API (Session, Criteria) is intentionally not wrapped here; use it directly via EntityManager.unwrap(Session.class).
iBatis support has been removed; use MyBatis-Spring (an external project) instead.