0
# Hibernate Core
1

2
Hibernate Core is the fundamental module of the Hibernate Object/Relational Mapping framework, providing comprehensive persistence capabilities for Java applications. It implements the full Jakarta Persistence API (JPA) specification while offering extensive additional features beyond the standard, including advanced entity mapping, session management, query processing, transaction management, caching, and performance optimization features.
3

4
## Package Information
5

6
- **Package Name**: hibernate-core
7
- **Package Type**: maven
8
- **Group ID**: org.hibernate.orm
9
- **Language**: Java
10
- **Installation**: Add to your Maven dependencies:
11

12
```xml
13
<dependency>
14
    <groupId>org.hibernate.orm</groupId>
15
    <artifactId>hibernate-core</artifactId>
16
    <version>7.1.1</version>
17
</dependency>
18
```
19

20
For Gradle:
21

22
```gradle
23
implementation 'org.hibernate.orm:hibernate-core:7.1.1'
24
```
25

26
## Core Imports
27

28
```java
29
// Core session management
30
import org.hibernate.Session;
31
import org.hibernate.SessionFactory;
32
import org.hibernate.Transaction;
33

34
// Configuration and bootstrapping
35
import org.hibernate.boot.MetadataSources;
36
import org.hibernate.boot.Metadata;
37
import org.hibernate.boot.SessionFactoryBuilder;
38

39
// Query APIs
40
import org.hibernate.query.Query;
41
import org.hibernate.query.SelectionQuery;
42
import org.hibernate.query.NativeQuery;
43

44
// Core annotations
45
import org.hibernate.annotations.Cache;
46
import org.hibernate.annotations.NaturalId;
47
import org.hibernate.annotations.Fetch;
48
```
49

50
## Basic Usage
51

52
```java
53
import org.hibernate.*;
54
import org.hibernate.boot.MetadataSources;
55
import org.hibernate.boot.registry.StandardServiceRegistry;
56
import org.hibernate.boot.registry.StandardServiceRegistryBuilder;
57

58
// Configure and build SessionFactory
59
StandardServiceRegistry registry = new StandardServiceRegistryBuilder()
60
    .configure() // configures settings from hibernate.cfg.xml
61
    .build();
62

63
SessionFactory sessionFactory = new MetadataSources(registry)
64
    .buildMetadata()
65
    .buildSessionFactory();
66

67
// Use Session for persistence operations
68
try (Session session = sessionFactory.openSession()) {
69
    Transaction tx = session.beginTransaction();
70

71
    // Create and persist an entity
72
    MyEntity entity = new MyEntity("example");
73
    session.persist(entity);
74

75
    // Query entities
76
    List<MyEntity> entities = session.createQuery(
77
        "FROM MyEntity WHERE name = :name", MyEntity.class)
78
        .setParameter("name", "example")
79
        .getResultList();
80

81
    tx.commit();
82
}
83
```
84

85
## Architecture
86

87
Hibernate Core is built around several key architectural components:
88

89
- **Session Management**: `Session` and `SessionFactory` interfaces for managing persistence contexts and entity lifecycle
90
- **Configuration System**: Bootstrap APIs for configuring mappings, connections, and runtime behavior
91
- **Query Engine**: Multiple query APIs including HQL, Criteria API, and native SQL with full type safety
92
- **Type System**: Comprehensive type mapping between Java objects and database columns
93
- **Caching**: Multi-level caching system including first-level (session) and second-level caching
94
- **Transaction Management**: Integration with JTA and resource-local transaction management
95
- **Event System**: Extensible event/listener architecture for customizing persistence behavior
96

97
## Capabilities
98

99
### Session Management
100

101
Core session and persistence context management for entity lifecycle operations, including CRUD operations, lazy loading, and transaction coordination.
102

103
```java { .api }
104
public interface Session extends SharedSessionContract, EntityManager {
105
    // Core persistence operations
106
    <T> T find(Class<T> entityClass, Object primaryKey);
107
    void persist(Object entity);
108
    <T> T merge(T entity);
109
    void remove(Object entity);
110
    void refresh(Object entity);
111

112
    // Transaction management
113
    Transaction beginTransaction();
114
    Transaction getTransaction();
115

116
    // Query creation
117
    <R> Query<R> createQuery(String queryString, Class<R> resultClass);
118
    <R> NativeQuery<R> createNativeQuery(String sqlString, Class<R> resultClass);
119
}
120

121
public interface SessionFactory extends EntityManagerFactory {
122
    Session openSession();
123
    Session getCurrentSession();
124
    <R> R inSession(Function<Session, R> work);
125
    <R> R inTransaction(Function<Session, R> work);
126
}
127
```
128

129
[Session Management](./session-management.md)
130

131
### Configuration and Bootstrap
132

133
Configuration and bootstrap APIs for setting up Hibernate, including metadata sources, service registries, and SessionFactory creation.
134

135
```java { .api }
136
public class MetadataSources {
137
    public MetadataSources(ServiceRegistry serviceRegistry);
138
    public MetadataSources addAnnotatedClass(Class<?> annotatedClass);
139
    public MetadataSources addResource(String name);
140
    public Metadata buildMetadata();
141
}
142

143
public interface Metadata {
144
    SessionFactoryBuilder getSessionFactoryBuilder();
145
    Database getDatabase();
146
    Collection<EntityBinding> getEntityBindings();
147
}
148
```
149

150
[Configuration and Bootstrap](./configuration.md)
151

152
### Query APIs
153

154
Comprehensive querying capabilities including HQL, JPQL, type-safe Criteria API, and native SQL queries with parameter binding and result mapping.
155

156
```java { .api }
157
public interface Query<R> extends CommonQueryContract {
158
    List<R> getResultList();
159
    R getSingleResult();
160
    R getSingleResultOrNull();
161

162
    // Parameter binding
163
    <P> Query<R> setParameter(String name, P value);
164
    <P> Query<R> setParameter(int position, P value);
165

166
    // Pagination
167
    Query<R> setFirstResult(int startPosition);
168
    Query<R> setMaxResults(int maxResult);
169
}
170

171
public interface SelectionQuery<R> extends Query<R> {
172
    // Selection-specific operations
173
    SelectionQuery<R> setOrder(List<Order> orderList);
174
    SelectionQuery<R> setOrder(Order... orders);
175
}
176

177
// Type-safe Criteria API
178
public interface CriteriaBuilder {
179
    <T> CriteriaQuery<T> createQuery(Class<T> resultClass);
180
    Predicate and(Predicate... restrictions);
181
    Predicate equal(Expression<?> x, Object y);
182
    <Y extends Comparable<? super Y>> Predicate greaterThan(Expression<? extends Y> x, Y y);
183
}
184
```
185

186
[Query APIs](./queries.md)
187

188
### Entity Mapping Annotations
189

190
Hibernate-specific annotations for advanced entity mapping, caching, fetching strategies, and custom behaviors beyond JPA standard annotations.
191

192
```java { .api }
193
// Caching annotations
194
@Target({TYPE, METHOD, FIELD})
195
@Retention(RUNTIME)
196
public @interface Cache {
197
    CacheConcurrencyStrategy usage() default CacheConcurrencyStrategy.READ_WRITE;
198
    String region() default "";
199
}
200

201
// Fetching strategy annotations
202
@Target({METHOD, FIELD})
203
@Retention(RUNTIME)
204
public @interface Fetch {
205
    FetchMode value();
206
}
207

208
// Natural identifier annotation
209
@Target({METHOD, FIELD})
210
@Retention(RUNTIME)
211
public @interface NaturalId {
212
    boolean mutable() default false;
213
}
214
```
215

216
[Entity Mapping](./entity-mapping.md)
217

218
### Transaction Management
219

220
Transaction management APIs for coordinating database transactions, including JTA and resource-local transaction support.
221

222
```java { .api }
223
public interface Transaction {
224
    void begin();
225
    void commit();
226
    void rollback();
227
    boolean isActive();
228

229
    // Timeout configuration
230
    void setTimeout(int seconds);
231
    int getTimeout();
232
}
233
```
234

235
[Transaction Management](./transactions.md)
236

237
### Type System
238

239
Hibernate's type system for mapping Java types to database types, including custom type definitions and user-defined types.
240

241
```java { .api }
242
public interface UserType<J> {
243
    int getSqlType();
244
    Class<J> returnedClass();
245
    boolean equals(J x, J y);
246
    int hashCode(J x);
247
    J nullSafeGet(ResultSet rs, int position, SharedSessionContractImplementor session, Object owner);
248
    void nullSafeSet(PreparedStatement st, J value, int index, SharedSessionContractImplementor session);
249
}
250
```
251

252
[Type System](./type-system.md)
253

254
## Core Types
255

256
```java { .api }
257
// Core enums
258
public enum FlushMode {
259
    /** Never flush unless explicitly requested */
260
    MANUAL,
261
    /** Flush when transaction commits */
262
    COMMIT,
263
    /** Automatically flush when needed */
264
    AUTO,
265
    /** Always flush before query execution */
266
    ALWAYS
267
}
268

269
public enum CacheMode {
270
    /** Normal cache interaction */
271
    NORMAL,
272
    /** Ignore second-level cache completely */
273
    IGNORE,
274
    /** Only read from cache, never write */
275
    GET,
276
    /** Only write to cache, never read */
277
    PUT,
278
    /** Refresh cache entries */
279
    REFRESH
280
}
281

282
public enum LockMode {
283
    /** No locking */
284
    NONE,
285
    /** Read lock */
286
    READ,
287
    /** Optimistic locking */
288
    OPTIMISTIC,
289
    /** Pessimistic read lock */
290
    PESSIMISTIC_READ,
291
    /** Pessimistic write lock */
292
    PESSIMISTIC_WRITE
293
}
294

295
// Core interfaces
296
public interface SharedSessionContract extends AutoCloseable {
297
    Transaction beginTransaction();
298
    Query createQuery(String queryString);
299
    Criteria createCriteria(Class persistentClass);
300
    void flush();
301
    void clear();
302
    boolean isOpen();
303
}
304
```