0
# Spring ORM
1

2
Spring ORM is a comprehensive Object/Relational Mapping integration module that provides seamless integration of JPA (Java Persistence API), Hibernate, and other ORM frameworks within the Spring ecosystem. It offers declarative transaction management, dependency injection for persistence contexts, exception translation, and web tier integration patterns that simplify data access layer development in enterprise applications.
3

4
## Package Information
5

6
- **Package Name**: org.springframework:spring-orm
7
- **Package Type**: Maven
8
- **Language**: Java
9
- **Version**: 6.2.8
10
- **Installation**: 
11

12
Maven:
13
```xml
14
<dependency>
15
    <groupId>org.springframework</groupId>
16
    <artifactId>spring-orm</artifactId>
17
    <version>6.2.8</version>
18
</dependency>
19
```
20

21
Gradle:
22
```groovy
23
implementation 'org.springframework:spring-orm:6.2.8'
24
```
25

26
## Core Imports
27

28
JPA Integration:
29
```java
30
import org.springframework.orm.jpa.JpaTransactionManager;
31
import org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean;
32
import org.springframework.orm.jpa.vendor.HibernateJpaVendorAdapter;
33
import org.springframework.orm.jpa.support.PersistenceAnnotationBeanPostProcessor;
34
```
35

36
Hibernate Integration:
37
```java
38
import org.springframework.orm.hibernate5.HibernateTransactionManager;
39
import org.springframework.orm.hibernate5.LocalSessionFactoryBean;
40
import org.springframework.orm.hibernate5.HibernateTemplate;
41
```
42

43
Exception Handling:
44
```java
45
import org.springframework.orm.ObjectOptimisticLockingFailureException;
46
import org.springframework.orm.ObjectRetrievalFailureException;
47
```
48

49
Annotations:
50
```java
51
import jakarta.persistence.PersistenceContext;
52
import jakarta.persistence.PersistenceUnit;
53
```
54

55
## Basic Usage
56

57
### JPA Configuration with Spring Boot
58
```java
59
@Configuration
60
@EnableJpaRepositories(basePackages = "com.example.repository")
61
@EnableTransactionManagement
62
public class JpaConfig {
63

64
    @Bean
65
    public LocalContainerEntityManagerFactoryBean entityManagerFactory(
66
            DataSource dataSource) {
67
        LocalContainerEntityManagerFactoryBean em = new LocalContainerEntityManagerFactoryBean();
68
        em.setDataSource(dataSource);
69
        em.setPackagesToScan("com.example.entity");
70
        em.setJpaVendorAdapter(new HibernateJpaVendorAdapter());
71
        
72
        Properties jpaProperties = new Properties();
73
        jpaProperties.setProperty("hibernate.dialect", "org.hibernate.dialect.PostgreSQLDialect");
74
        jpaProperties.setProperty("hibernate.hbm2ddl.auto", "validate");
75
        em.setJpaProperties(jpaProperties);
76
        
77
        return em;
78
    }
79

80
    @Bean
81
    public PlatformTransactionManager transactionManager(
82
            EntityManagerFactory entityManagerFactory) {
83
        return new JpaTransactionManager(entityManagerFactory);
84
    }
85
}
86

87
@Entity
88
public class User {
89
    @Id
90
    @GeneratedValue(strategy = GenerationType.IDENTITY)
91
    private Long id;
92
    
93
    private String name;
94
    private String email;
95
    
96
    // getters and setters
97
}
98

99
@Repository
100
public class UserRepository {
101
    
102
    @PersistenceContext
103
    private EntityManager entityManager;
104
    
105
    @Transactional
106
    public void save(User user) {
107
        entityManager.persist(user);
108
    }
109
    
110
    public User findById(Long id) {
111
        return entityManager.find(User.class, id);
112
    }
113
}
114
```
115

116
### Hibernate Configuration
117
```java
118
@Configuration
119
@EnableTransactionManagement
120
public class HibernateConfig {
121

122
    @Bean
123
    public LocalSessionFactoryBean sessionFactory(DataSource dataSource) {
124
        LocalSessionFactoryBean sessionFactory = new LocalSessionFactoryBean();
125
        sessionFactory.setDataSource(dataSource);
126
        sessionFactory.setPackagesToScan("com.example.entity");
127
        
128
        Properties hibernateProperties = new Properties();
129
        hibernateProperties.setProperty("hibernate.dialect", "org.hibernate.dialect.PostgreSQLDialect");
130
        hibernateProperties.setProperty("hibernate.show_sql", "true");
131
        hibernateProperties.setProperty("hibernate.hbm2ddl.auto", "validate");
132
        sessionFactory.setHibernateProperties(hibernateProperties);
133
        
134
        return sessionFactory;
135
    }
136

137
    @Bean
138
    public PlatformTransactionManager transactionManager(SessionFactory sessionFactory) {
139
        return new HibernateTransactionManager(sessionFactory);
140
    }
141

142
    @Bean
143
    public HibernateTemplate hibernateTemplate(SessionFactory sessionFactory) {
144
        return new HibernateTemplate(sessionFactory);
145
    }
146
}
147

148
@Repository
149
public class HibernateUserRepository {
150
    
151
    @Autowired
152
    private HibernateTemplate hibernateTemplate;
153
    
154
    public void save(User user) {
155
        hibernateTemplate.save(user);
156
    }
157
    
158
    public User findById(Long id) {
159
        return hibernateTemplate.get(User.class, id);
160
    }
161
    
162
    @SuppressWarnings("unchecked")
163
    public List<User> findAll() {
164
        return hibernateTemplate.loadAll(User.class);
165
    }
166
}
167
```
168

169
## Architecture
170

171
Spring ORM follows a layered architecture that integrates ORM frameworks with Spring's core features:
172

173
### Transaction Management Layer
174
- **PlatformTransactionManager**: Abstraction for transaction management across different ORM providers
175
- **JpaTransactionManager**: JPA-specific transaction management with EntityManager lifecycle
176
- **HibernateTransactionManager**: Hibernate-specific transaction management with Session lifecycle
177
- **Declarative Transactions**: @Transactional annotation support with AOP
178

179
### Persistence Context Management
180
- **EntityManagerFactory**: JPA EntityManagerFactory configuration and lifecycle management
181
- **SessionFactory**: Hibernate SessionFactory configuration and lifecycle management  
182
- **Shared EntityManager**: Thread-safe EntityManager proxies for dependency injection
183
- **Open EntityManager/Session in View**: Web request-scoped persistence context patterns
184

185
### Exception Translation
186
- **PersistenceExceptionTranslator**: Converts ORM-specific exceptions to Spring's DataAccessException hierarchy
187
- **Vendor-specific Translators**: HibernateExceptionTranslator, JPA exception handling
188
- **Consistent Error Handling**: Uniform exception types across different ORM providers
189

190
### Dependency Injection Integration
191
- **@PersistenceContext**: EntityManager injection with proper lifecycle management
192
- **@PersistenceUnit**: EntityManagerFactory injection for programmatic access
193
- **PersistenceAnnotationBeanPostProcessor**: Annotation processing for persistence resource injection
194

195
## Capabilities
196

197
### JPA Integration
198

199
Comprehensive JPA support including EntityManagerFactory configuration, transaction management, shared EntityManager creation, and vendor-specific adaptations for Hibernate and EclipseLink.
200

201
```java { .api }
202
// Core JPA Configuration
203
public class LocalContainerEntityManagerFactoryBean 
204
        extends AbstractEntityManagerFactoryBean 
205
        implements ResourceLoaderAware, LoadTimeWeaverAware {
206
    public void setDataSource(DataSource dataSource);
207
    public void setPackagesToScan(String... packagesToScan);
208
    public void setJpaVendorAdapter(JpaVendorAdapter jpaVendorAdapter);
209
    public void setPersistenceUnitManager(PersistenceUnitManager persistenceUnitManager);
210
    public EntityManagerFactory createNativeEntityManagerFactory() throws PersistenceException;
211
}
212

213
// Transaction Management
214
public class JpaTransactionManager extends AbstractPlatformTransactionManager 
215
        implements ResourceTransactionManager, BeanFactoryAware, InitializingBean {
216
    public JpaTransactionManager(EntityManagerFactory emf);
217
    public void setEntityManagerFactory(EntityManagerFactory emf);
218
    public void setDataSource(DataSource dataSource);
219
    public void setJpaDialect(JpaDialect jpaDialect);
220
}
221

222
// Shared EntityManager Creation
223
public abstract class SharedEntityManagerCreator {
224
    public static EntityManager createSharedEntityManager(EntityManagerFactory emf);
225
    public static EntityManager createSharedEntityManager(EntityManagerFactory emf, Map<?, ?> properties);
226
}
227
```
228

229
[JPA Integration](./jpa-integration.md)
230

231
### Hibernate Integration
232

233
Native Hibernate 5.x support with SessionFactory configuration, transaction management, template-based data access operations, and Spring integration features.
234

235
```java { .api }
236
// SessionFactory Configuration
237
public class LocalSessionFactoryBean extends HibernateExceptionTranslator 
238
        implements FactoryBean<SessionFactory>, ResourceLoaderAware, InitializingBean, DisposableBean {
239
    public void setDataSource(DataSource dataSource);
240
    public void setPackagesToScan(String... packagesToScan);
241
    public void setHibernateProperties(Properties hibernateProperties);
242
    public void setConfigLocation(Resource configLocation);
243
}
244

245
// Transaction Management
246
public class HibernateTransactionManager extends AbstractPlatformTransactionManager 
247
        implements ResourceTransactionManager, BeanFactoryAware, InitializingBean {
248
    public HibernateTransactionManager(SessionFactory sessionFactory);
249
    public void setSessionFactory(SessionFactory sessionFactory);
250
    public void setDataSource(DataSource dataSource);
251
}
252

253
// Template Operations
254
public class HibernateTemplate implements HibernateOperations, InitializingBean {
255
    public HibernateTemplate(SessionFactory sessionFactory);
256
    public <T> T execute(HibernateCallback<T> action);
257
    public <T> T get(Class<T> entityClass, Serializable id);
258
    public Serializable save(Object entity);
259
    public void update(Object entity);
260
    public void delete(Object entity);
261
}
262
```
263

264
[Hibernate Integration](./hibernate-integration.md)
265

266
### Transaction Management
267

268
Platform-agnostic transaction management with support for declarative transactions, programmatic transaction control, and integration with various transaction managers.
269

270
```java { .api }
271
// Base Transaction Manager
272
public abstract class AbstractPlatformTransactionManager implements PlatformTransactionManager {
273
    public final TransactionStatus getTransaction(TransactionDefinition definition);
274
    public final void commit(TransactionStatus status);
275
    public final void rollback(TransactionStatus status);
276
}
277

278
// Resource Transaction Manager
279
public interface ResourceTransactionManager extends PlatformTransactionManager {
280
    Object getResourceFactory();
281
}
282

283
// Transaction Synchronization
284
public interface TransactionSynchronization {
285
    void beforeCommit(boolean readOnly);
286
    void beforeCompletion();
287
    void afterCommit();
288
    void afterCompletion(int status);
289
}
290
```
291

292
[Transaction Management](./transaction-management.md)
293

294
### Persistence Context Management
295

296
Advanced persistence context management including annotation-driven dependency injection, container-managed persistence contexts, and application-managed EntityManager creation.
297

298
```java { .api }
299
// Persistence Annotation Processing
300
public class PersistenceAnnotationBeanPostProcessor implements InstantiationAwareBeanPostProcessor, 
301
        DestructionAwareBeanPostProcessor, MergedBeanDefinitionPostProcessor, PriorityOrdered, BeanFactoryAware {
302
    public void setDefaultPersistenceUnitName(String unitName);
303
    public void setPersistenceUnits(Map<String, PersistenceUnitInfo> persistenceUnits);
304
    public void setPersistenceContexts(Map<String, EntityManagerFactory> persistenceContexts);
305
}
306

307
// Extended EntityManager Creation  
308
public abstract class ExtendedEntityManagerCreator {
309
    public static EntityManager createApplicationManagedEntityManager(EntityManager rawEntityManager, EntityManagerFactoryInfo emfInfo);
310
    public static EntityManager createContainerManagedEntityManager(EntityManagerFactory emf, Map<?, ?> properties, boolean synchronizedWithTransaction);
311
}
312

313
// Persistence Unit Management
314
public interface PersistenceUnitManager {
315
    PersistenceUnitInfo obtainDefaultPersistenceUnitInfo();
316
    PersistenceUnitInfo obtainPersistenceUnitInfo(String persistenceUnitName);
317
}
318
```
319

320
[Persistence Context](./persistence-context.md)
321

322
### Exception Handling
323

324
Comprehensive exception translation from ORM-specific exceptions to Spring's consistent DataAccessException hierarchy, with support for optimistic locking and object retrieval failures.
325

326
```java { .api }
327
// Base ORM Exceptions
328
public class ObjectOptimisticLockingFailureException extends OptimisticLockingFailureException {
329
    public ObjectOptimisticLockingFailureException(Class<?> persistentClass, Object identifier);
330
    public ObjectOptimisticLockingFailureException(Class<?> persistentClass, Object identifier, Throwable cause);
331
    public Class<?> getPersistentClass();
332
    public Object getIdentifier();
333
}
334

335
public class ObjectRetrievalFailureException extends DataRetrievalFailureException {
336
    public ObjectRetrievalFailureException(Class<?> persistentClass, Object identifier);
337
    public ObjectRetrievalFailureException(Class<?> persistentClass, Object identifier, String msg, Throwable cause);
338
    public Class<?> getPersistentClass();
339
    public Object getIdentifier();
340
}
341

342
// Exception Translation
343
public interface PersistenceExceptionTranslator {
344
    DataAccessException translateExceptionIfPossible(RuntimeException ex);
345
}
346
```
347

348
[Exception Handling](./exception-handling.md)
349

350
## Database Support
351

352
Spring ORM provides extensive database platform support through the Database enumeration:
353

354
```java { .api }
355
public enum Database {
356
    DEFAULT,     // Default/generic database
357
    DB2,         // IBM DB2 database
358
    DERBY,       // Apache Derby database
359
    H2,          // H2 database
360
    HANA,        // SAP HANA database
361
    HSQL,        // HSQLDB database
362
    INFORMIX,    // IBM Informix database
363
    MYSQL,       // MySQL database
364
    ORACLE,      // Oracle database
365
    POSTGRESQL,  // PostgreSQL database
366
    SQL_SERVER,  // Microsoft SQL Server database
367
    SYBASE       // Sybase database
368
}
369
```
370

371
## Web Integration
372

373
Spring ORM provides specialized support for web applications through filters and interceptors that manage persistence contexts across web requests:
374

375
- **OpenEntityManagerInViewFilter**: Binds JPA EntityManager to request thread
376
- **OpenSessionInViewFilter**: Binds Hibernate Session to request thread  
377
- **AsyncWebRequestInterceptor**: Supports asynchronous web request processing
378
- **Request-scoped Persistence**: Manages lazy loading in web tier