# Technical Documentation: hibernate/hibernate-orm
> ℹ️ **Provenance:** Multi-Tier Ingestion · [CodeWiki Reference](https://codewiki.google/github.com/hibernate/hibernate-orm)
### Overview (`ci/tck-readme.md`)
Platform-tck build instructions
===============================
info: https://github.com/jakartaee/platform-tck/wiki/Instructions-for-building-and-running-JakartaEE-TCK-bundle
* Clone https://github.com/jakartaee/platform-tck
* Set env. variables:
* export WORKSPACE=/directory/where/jakartaee-tck/was/cloned
* export GF_BUNDLE_URL=https://ci.eclipse.org/jakartaee-tck/job/build-glassfish/lastSuccessfulBuild/artifact/appserver/distributions/glassfish/target/glassfish.zip
* export ANT_HOME=/path/to/apache-ant (1.10.5+)
* export JAVA_HOME=/path/to/jdk (11+)
* export PATH=$JAVA_HOME/bin:$ANT_HOME/bin/:$PATH
* Run the following cmd from the root of the repo:
$WORKSPACE/docker/build_standalone-tcks.sh jpa
* If all goes well, this should generate a zip file called persistence-tck-3.1.0_\.zip inside the $WORKSPACE/release/jpa_build/build_\/bundle/persistence-tck folder. This can then be used to build and run the hibernate jakarta-tck-runner image.
---
### Overview (`docker-compose/README.md`)
# DB containers
Describes the approach of managing DB containers.
Starting DBs relies on the Docker (Podman) compose, driven through the [`db.sh`](../db.sh)
script at the root of the repository (run `./db.sh` with no arguments, or with `-h`, to list
all the supported DBs/versions).
## Directory structure
* [build-config](build-config): contains Dockerfiles for custom-built images like EDB
or additional config files that are "mounted" to the corresponding DBs
* [latest](latest): contains a set of compose files with the latest versions of DBs.
Each subdirectory is monitored by Dependabot (see `.github/dependabot.yml`), and PRs
will be opened automatically when a new image is available.
* [versioned](versioned): contains compose files for previous versions of DBs,
the ones that we are not testing as regularly as the latest ones.
Each DB's compose file lives in its own subdirectory (e.g. `latest/mariadb/docker-compose.yaml`,
`versioned/mariadb-12-1/docker-compose.yaml`), named `--` for versioned ones.
The image is referenced through an env var with a default value pinned to a specific tag
and `@sha256` digest, e.g. `${MARIADB_IMAGE:-docker.io/library/mariadb:13.0@sha256:...}` in
`latest`, and `${DB_IMAGE_MARIADB_12_1:-docker.io/library/mariadb:12.1@sha256:...}` in `versioned`.
Pinning the digest keeps runs reproducible; Dependabot (for `latest`) or the person adding the
versioned file (for `versioned`) is responsible for resolving the digest for a new tag.
## Adding a brand-new DB
1. Add a new compose file under `latest//docker-compose.yaml`.
2. Always add a healthcheck that succeeds only when the DB is fully ready to accept requests.
If the image doesn't have the tools required to implement the healthcheck itself,
use the sidecar approach applied in [`latest/spanner/docker-compose.yaml`](latest/spanner/docker-compose.yaml).
3. Register the new `latest/` directory under the `docker-compose` entry in
[`.github/dependabot.yml`](../.github/dependabot.yml) so future image updates are picked up
automatically. Directories are listed explicitly there; a new DB is invisible to Dependabot
until it's added to that list.
4. Add the corresponding functions to [`db.sh`](../db.sh): a `()` entry point that starts
the latest version, and list it in the usage/help output near the bottom of the script.
5. If the DB should run in CI, add it to the test matrix in `.github/workflows/ci.yml`.
## Adding a new version of an existing DB
Dependabot opens PRs that bump the image in `latest//docker-compose.yaml` automatically.
Most of these bumps only refresh the image digest for the *same* tag (e.g. a rebuild of
`postgis:18-3.6`) or move a patch version (e.g. `cockroachdb:v26.3.1` -> `v26.3.2`); those can
be merged as-is, no further action needed.
When a bump instead moves to a genuinely new version (a new major/minor line, e.g.
MariaDB `12.3` -> `13.0`), and you want to keep the old version testable, do the following
*before* merging the Dependabot bump (or as a follow-up to it):
1. Create `versioned/--/docker-compose.yaml` with the contents
`latest//docker-compose.yaml` had *before* the bump, i.e. still pinned to the old
image tag and digest. Switch its env var override to a version-specific name
(e.g. `DB_IMAGE_MARIADB_12_3`) so it doesn't collide with the `latest` one.
2. In [`db.sh`](../db.sh), add a `__()` function that starts the
new versioned compose file, and a `__()` function that starts
`latest//docker-compose.yaml` — then point the plain `()` entry point at the new
latest-version function.
3. Add both new functions to the usage/help list in `db.sh`.
Not every bump needs a versioned copy — use your judgement on whether the previous version
is worth continuing to test (this repo doesn't keep one for every single minor release).
---
### Overview (`hibernate-core/src/jmh/README.md`)
# ActionQueue JMH Benchmarks
This directory contains JMH (Java Microbenchmark Harness) benchmarks for comparing the performance of legacy ActionQueue vs graph-based ActionQueue implementations.
## Benchmark Types
### 1. **ActionQueueBenchmark** (Average Time Mode)
Measures average time per operation in milliseconds. Lower is better.
- Focus: Latency and timing characteristics
- Mode: `AverageTime`
- Unit: `ms/op`
### 2. **ActionQueueThroughputBenchmark** (Throughput Mode)
Measures operations per second. Higher is better.
- Focus: Maximum throughput and operations/second
- Mode: `Throughput`
- Unit: `ops/s`
## Running Benchmarks
### Run all benchmarks
```bash
./gradlew :hibernate-core:jmh
```
### Run specific benchmark class
```bash
# Run only average time benchmarks
./gradlew :hibernate-core:jmh --args="ActionQueueBenchmark"
# Run only throughput benchmarks
./gradlew :hibernate-core:jmh --args="ActionQueueThroughputBenchmark"
```
### Run specific benchmark pattern
```bash
# Run only simple insert benchmarks (both average time and throughput)
./gradlew :hibernate-core:jmh --args="simpleInserts"
# Run only throughput benchmarks for single entity inserts
./gradlew :hibernate-core:jmh --args="singleEntityInsert"
# Run only parent-child benchmarks
./gradlew :hibernate-core:jmh --args="parentChild"
# Run only self-referencing tree benchmarks (average time only)
./gradlew :hibernate-core:jmh --args="selfRefTree"
# Run only mixed operations benchmarks
./gradlew :hibernate-core:jmh --args="mixedOperations"
# Run only OrderColumn benchmarks (throughput only)
./gradlew :hibernate-core:jmh --args="orderColumn"
```
### Run specific benchmark with custom parameters
```bash
# Run with more iterations
./gradlew :hibernate-core:jmh --args="-wi 10 -i 20 simpleInserts"
# Run with more forks for statistical stability
./gradlew :hibernate-core:jmh --args="-f 3 simpleInserts"
# Output results in JSON format
./gradlew :hibernate-core:jmh --args="-rf json -rff results.json"
```
## Benchmark Scenarios
### ActionQueueBenchmark (Average Time)
#### 1. Simple Inserts (`simpleInserts_*`)
- **What**: Bulk insert of entities with no foreign key relationships
- **Why**: Baseline performance comparison without FK dependency overhead
- **Variants**:
- `simpleInserts_100_*`: 100 entities per transaction
- `simpleInserts_1000_*`: 1,000 entities per transaction
#### 2. Parent-Child Inserts (`parentChild_*`)
- **What**: Parent entities with cascaded children (one-to-many with FK)
- **Why**: Measures FK dependency handling performance
- **Variants**:
- `parentChild_10_*`: 10 parents × 10 children = 110 entities
- `parentChild_100_*`: 100 parents × 10 children = 1,100 entities
#### 3. Self-Referencing Trees (`selfRefTree_*`)
- **What**: Hierarchical tree structures with self-referential FKs
- **Why**: Tests self-referencing FK optimization (grouping strategy)
- **Variants**:
- `selfRefTree_10_*`: 10 trees × 13 nodes = 130 entities
- `selfRefTree_50_*`: 50 trees × 13 nodes = 650 entities
- **Structure**: Each tree has 1 root + 3 children + 9 grandchildren
#### 4. Mixed Operations (`mixedOperations_*`)
- **What**: INSERT, UPDATE, DELETE operations in sequence
- **Why**: Tests realistic mixed workload performance
- **Operations**:
- Insert 50 parents with 5 children each (300 entities)
- Update all 50 parents
- Delete all 50 parents and their children
### ActionQueueThroughputBenchmark (Throughput)
#### 1. Single Entity Insert (`singleEntityInsert_*`)
- **What**: Insert one entity per transaction (minimal overhead)
- **Why**: Measures pure transaction throughput with minimal ActionQueue load
- **Metric**: Transactions per second
#### 2. Batch Insert (`batchInsert_50_*`)
- **What**: Insert 50 entities in a single transaction
- **Why**: Measures batch insertion throughput
- **Metric**: Batch operations per second
#### 3. Parent-Child Insert (`parentChildInsert_*`)
- **What**: Insert 1 parent with 10 children (cascade)
- **Why**: Measures throughput with FK dependencies
- **Metric**: Parent-child graph inserts per second
#### 4. Entity Update (`entityUpdate_*`)
- **What**: Complete lifecycle: insert → update → delete
- **Why**: Measures update operation throughput
- **Metric**: Update cycles per second
#### 5. Collection Add (`collectionAdd_*`)
- **What**: Add children to existing parent collection
- **Why**: Measures collection modification throughput
- **Metric**: Collection modification operations per second
#### 6. OrderColumn Insert (`orderColumnInsert_*`)
- **What**: Insert order with 20 line items using @OrderColumn
- **Why**: Measures @OrderColumn update SQL generation performance
- **Metric**: OrderColumn operations per second
#### 7. Mixed Workload (`mixedWorkload_*`)
- **What**: Insert 10 entities, update 5, delete all
- **Why**: Realistic mixed operation throughput
- **Metric**: Mixed workload cycles per second
#### 8. Complex Cascade (`complexCascade_*`)
- **What**: Insert 5 parents with 8 children each (40 entities total)
- **Why**: Measures complex cascade throughput
- **Metric**: Complex cascade operations per second
#### 9. Exceed Batch Size 100 (`exceedBatchSize_100_*`)
- **What**: Insert 100 entities (batch size is 50, requires 2 batches)
- **Why**: Measures performance when operations span multiple JDBC batches
- **Metric**: Operations per second with multi-batch handling
#### 10. Exceed Batch Size 500 (`exceedBatchSize_500_*`)
- **What**: Insert 500 entities (batch size is 50, requires 10 batches)
- **Why**: Measures scalability with large operations requiring many batches
- **Metric**: Large batch operations per second
#### 11. Mixed Exceed Batch (`mixedExceedBatch_*`)
- **What**: Insert 100, update 60, delete 100 (all exceed batch size)
- **Why**: Tests mixed operation types with multi-batch execution
- **Metric**: Mixed multi-batch cycles per second
#### 12. Cascade Exceed Batch (`cascadeExceedBatch_*`)
- **What**: Insert 15 parents with 5 children each (90 entities, exceeds batch size)
- **Why**: Tests cascade operations requiring multiple batches
- **Metric**: Large cascade operations per second
## Understanding Results
### Average Time Mode (ActionQueueBenchmark)
JMH reports average time per operation in milliseconds. **Lower is better.**
Example output:
```
Benchmark Mode Cnt Score Error Units
ActionQueueBenchmark.simpleInserts_100_Legacy avgt 10 45.231 ± 2.156 ms/op
ActionQueueBenchmark.simpleInserts_100_Graph avgt 10 41.087 ± 1.943 ms/op
```
This means:
- Legacy: ~45ms per operation (100 inserts)
- Graph: ~41ms per operation (100 inserts)
- **Graph is ~9% faster** for this scenario
- Calculation: `(45.231 - 41.087) / 45.231 × 100% = 9.2% improvement`
### Throughput Mode (ActionQueueThroughputBenchmark)
JMH reports operations per second. **Higher is better.**
Example output:
```
Benchmark Mode Cnt Score Error Units
ActionQueueThroughputBenchmark.singleEntityInsert_Legacy thrpt 5 245.123 ± 12.345 ops/s
ActionQueueThroughputBenchmark.singleEntityInsert_Graph thrpt 5 278.456 ± 10.234 ops/s
```
This means:
- Legacy: ~245 operations per second
- Graph: ~278 operations per second
- **Graph is ~14% higher throughput** for this scenario
- Calculation: `(278.456 - 245.123) / 245.123 × 100% = 13.6% improvement`
### Which Mode to Use?
- **Average Time**: Best for understanding latency and timing characteristics
- **Throughput**: Best for understanding maximum sustainable load
- Both are valuable for different performance concerns
## Benchmark Configuration
Default settings (configured in `hibernate-core.gradle`):
- **Warmup iterations**: 5 (1 second each)
- **Measurement iterations**: 10 (1 second each)
- **Fork**: 1 JVM fork
- **Mode**: Average time per operation
- **Time unit**: Milliseconds
These can be overridden via command-line args.
## JMH Arguments Reference
Common JMH arguments:
- `-wi `: Warmup iterations (default: 5)
- `-w `: Warmup time per iteration (default: 1s)
- `-i `: Measurement iterations (default: 10)
- `-r `: Measurement time per iteration (default: 1s)
- `-f `: Number of forks (default: 1)
- `-t `: Number of threads
- `-rf `: Result format (text, csv, json, latex)
- `-rff `: Result file name
- `-prof `: Enable profiler (gc, stack, etc.)
Example with profiling:
```bash
./gradlew :hibernate-core:jmh --args="-prof gc simpleInserts"
```
## Comparing Results
To compare legacy vs graph implementations:
1. Look for pairs of benchmarks ending in `_Legacy` and `_Graph`
2. Compare the `Score` column:
- **Average Time**: Lower is better
- **Throughput**: Higher is better
3. Calculate improvement:
- **Average Time**: `(Legacy - Graph) / Legacy × 100%` (positive = faster)
- **Throughput**: `(Graph - Legacy) / Legacy × 100%` (positive = more throughput)
### Quick Comparison Commands
```bash
# Run both implementations side-by-side for single entity inserts
./gradlew :hibernate-core:jmh --args="singleEntityInsert"
# Compare throughput across all scenarios
./gradlew :hibernate-core:jmh --args="ActionQueueThroughputBenchmark -rf json -rff throughput-results.json"
# Compare average time across all scenarios
./gradlew :hibernate-core:jmh --args="ActionQueueBenchmark -rf json -rff avgtime-results.json"
```
## CI/Automated Testing
For CI environments, use fewer iterations for faster results:
```bash
./gradlew :hibernate-core:jmh --args="-wi 2 -i 5 -rf json -rff benchmark-results.json"
```
Then parse the JSON results for regression detection.
---
### Overview (`tooling/hibernate-maven-plugin/src/intTest/resources/5-minute-tutorial/README.md`)
To run this example:
- Have [Apache Maven](https://maven.apache.org) installed
- Have [H2 Sakila database](https://github.com/hibernate/sakila-h2) running
- Issue one of the following commands from a command-line window opened in this folder:
- `mvn generate-sources -Dh2.version=${h2.version} -Dproject.version=${hibernate.version}`
---
### Overview (`tooling/hibernate-maven-plugin/src/intTest/resources/hbm2java/jpa-default/README.md`)
To run this example:
- Have [Apache Maven](https://maven.apache.org) installed
- Have [H2 Sakila database](https://github.com/hibernate/sakila-h2) running
- Issue the following commands from a command-line window opened in this folder:
`mvn generate-sources -Dh2.version=${h2.version} -Dhibernate.version=${hibernate.version}`
---
### Overview (`tooling/hibernate-maven-plugin/src/intTest/resources/hbm2java/no-annotations/README.md`)
To run this example:
- Have [Apache Maven](https://maven.apache.org) installed
- Have [H2 Sakila database](https://github.com/hibernate/sakila-h2) running
- Issue the following commands from a command-line window opened in this folder:
`mvn generate-sources -Dh2.version=${h2.version} -Dhibernate.version=${hibernate.version}`
---
### Overview (`tooling/hibernate-maven-plugin/src/intTest/resources/hbm2java/no-generics/README.md`)
To run this example:
- Have [Apache Maven](https://maven.apache.org) installed
- Have [H2 Sakila database](https://github.com/hibernate/sakila-h2) running
- Issue the following commands from a command-line window opened in this folder:
`mvn generate-sources -Dh2.version=${h2.version} -Dhibernate.version=${hibernate.version}`
---
### Overview (`tooling/hibernate-maven-plugin/src/intTest/resources/hbm2java/output-directory/README.md`)
To run this example:
- Have [Apache Maven](https://maven.apache.org) installed
- Have [H2 Sakila database](https://github.com/hibernate/sakila-h2) running
- Issue the following command from a command-line window opened in this folder:
```shell
mvn generate-sources
-Dh2.version=${h2.version}
-Dhibernate.version=${hibernate.version}
-Doutput.dir=./generated-classes
```
---
### Overview (`tooling/hibernate-maven-plugin/src/intTest/resources/hbm2java/template-path/README.md`)
To run this example:
- Have [Apache Maven](https://maven.apache.org) installed
- Have [H2 Sakila database](https://github.com/hibernate/sakila-h2) running
- Issue the following command from a command-line window opened in this folder:
```shell
mvn generate-sources
-Dh2.version=${h2.version}
-Dhibernate.version=${hibernate.version}
-Dtemplate.dir=./templates
```
---
### Overview (`tooling/hibernate-maven-plugin/src/intTest/resources/hbm2java/use-generics/README.md`)
To run this example:
- Have [Apache Maven](https://maven.apache.org) installed
- Have [H2 Sakila database](https://github.com/hibernate/sakila-h2) running
- Issue the following commands from a command-line window opened in this folder:
`mvn generate-sources -Dh2.version=${h2.version} -Dhibernate.version=${hibernate.version}`
---
### Overview (`tooling/hibernate-maven-plugin/src/intTest/resources/hbm2orm/simple-default/README.md`)
To run this example:
- Have [Apache Maven](https://maven.apache.org) installed
- Issue the following commands from a command-line window opened in this folder:
`mvn org.hibernate.tool:hibernate-tools-maven:${hibernate.version}:hbm2orm`
---
### Overview (`tooling/hibernate-maven-plugin/src/intTest/resources/hbm2orm/with-user-type/README.md`)
To run this example:
- Have [Apache Maven](https://maven.apache.org) installed
- Issue the following commands from a command-line window opened in this folder:
`mvn compile org.hibernate.tool:hibernate-tools-maven:${hibernate.version}:hbm2orm`
---
### Overview (`hibernate-core/src/jmh/java/org/hibernate/action/queue/README.md`)
# ActionQueue JMH Benchmarks
This directory contains JMH (Java Microbenchmark Harness) benchmarks for Hibernate's ActionQueue implementations.
## Available Benchmarks
### 1. ActionQueueBenchmark.java
Compares Legacy vs Graph-based ActionQueue implementations for:
- Simple entity inserts
- Parent-child relationship inserts
- Self-referencing tree structures
- Mixed operations (insert + update + delete)
### 2. CollectionBundlingBenchmark.java
Compares Legacy, Graph (no bundling), and Graph (with bundling) for collection operations:
- Small collection inserts (10 items)
- Medium collection inserts (50 items)
- Large collection inserts (200 items)
- Multiple collections per entity
- Batch processing with collections
- Very large collections (500 items)
- Mixed operations
## Running Benchmarks
### Run All ActionQueue Benchmarks
```bash
./gradlew :hibernate-core:jmh
```
### Run Specific Benchmark Class
```bash
./gradlew :hibernate-core:jmh -Pjmh.include=".*ActionQueueBenchmark.*"
./gradlew :hibernate-core:jmh -Pjmh.include=".*CollectionBundlingBenchmark.*"
```
### Run Specific Benchmark Method
```bash
./gradlew :hibernate-core:jmh -Pjmh.include=".*collectionInsert_Small.*"
./gradlew :hibernate-core:jmh -Pjmh.include=".*collectionInsert_Medium.*"
./gradlew :hibernate-core:jmh -Pjmh.include=".*collectionInsert_Large.*"
```
### Run with Custom Parameters
```bash
# More iterations for higher confidence
./gradlew :hibernate-core:jmh -Pjmh.include=".*CollectionBundling.*" \
-Djmh.iterations=20 \
-Djmh.warmup=10
# Different fork count
./gradlew :hibernate-core:jmh -Pjmh.include=".*CollectionBundling.*" \
-Djmh.fork=3
```
## Understanding Results
### Benchmark Modes
The benchmarks run in two modes:
1. **Throughput (ops/ms):** Operations per millisecond - **higher is better**
2. **Average Time (ms/op):** Milliseconds per operation - **lower is better**
### Sample Output
```
Benchmark Mode Cnt Score Error Units
CollectionBundlingBenchmark.collectionInsert_Small_Legacy thrpt 10 0.237 ± 0.002 ops/ms
CollectionBundlingBenchmark.collectionInsert_Small_GraphBundling thrpt 10 0.313 ± 0.004 ops/ms
CollectionBundlingBenchmark.collectionInsert_Small_Legacy avgt 10 4.267 ± 0.072 ms/op
CollectionBundlingBenchmark.collectionInsert_Small_GraphBundling avgt 10 3.144 ± 0.058 ms/op
```
Interpretation:
- Graph with bundling: **0.313 ops/ms** (32% faster throughput than legacy)
- Graph with bundling: **3.144 ms/op** (26% faster average time than legacy)
### Error Margins
The `±` value represents the 99.9% confidence interval. Smaller is better, indicating more consistent results.
## Results Location
Benchmark results are saved to:
```
hibernate-core/target/results/jmh/results.txt
```
## Benchmark Configuration
Default JMH settings (from `hibernate-core.gradle`):
```groovy
jmh {
jmhVersion = '1.37'
warmupIterations = 5
iterations = 10
fork = 1
}
```
### What These Mean
- **warmupIterations:** Number of warmup iterations to let JVM optimize code
- **iterations:** Number of measurement iterations for actual results
- **fork:** Number of separate JVM processes to run benchmarks in
## Tips for Accurate Benchmarking
1. **Close unnecessary applications** to reduce system noise
2. **Run multiple times** and compare results for consistency
3. **Don't run other heavy tasks** during benchmarking
4. **Use profilers** to understand why performance differs:
```bash
./gradlew :hibernate-core:jmh -Pjmh.include=".*YourBenchmark.*" -Djmh.prof=gc
```
5. **Compare similar workloads** (same collection size, same operation type)
## Adding New Benchmarks
### Basic Structure
```java
@State(Scope.Benchmark)
@BenchmarkMode({Mode.AverageTime, Mode.Throughput})
@OutputTimeUnit(TimeUnit.MILLISECONDS)
@Warmup(iterations = 5, time = 1)
@Measurement(iterations = 10, time = 1)
@Fork(value = 1)
public class MyBenchmark {
@State(Scope.Benchmark)
public static class MyState {
SessionFactory sessionFactory;
@Setup(Level.Trial)
public void setup() {
// Initialize session factory
}
@TearDown(Level.Trial)
public void tearDown() {
// Cleanup
}
}
@Benchmark
public void myBenchmark(MyState state, Blackhole blackhole) {
// Benchmark code
blackhole.consume(result);
}
}
```
### State Scopes
- **Scope.Benchmark:** Shared across all threads in benchmark
- **Scope.Thread:** One instance per thread
- **Scope.Group:** One instance per thread group
### Setup/TearDown Levels
- **Level.Trial:** Once per benchmark run
- **Level.Iteration:** Once per iteration
- **Level.Invocation:** Once per invocation (use sparingly, adds overhead)
## Profiling
JMH includes several profilers:
```bash
# GC profiler
./gradlew :hibernate-core:jmh -Pjmh.include=".*MyBench.*" -Djmh.prof=gc
# Stack profiler
./gradlew :hibernate-core:jmh -Pjmh.include=".*MyBench.*" -Djmh.prof=stack
# Class loader profiler
./gradlew :hibernate-core:jmh -Pjmh.include=".*MyBench.*" -Djmh.prof=cl
# List all available profilers
./gradlew :hibernate-core:jmh -Pjmh.include=".*MyBench.*" -Djmh.prof=help
```
## Common Issues
### OutOfMemoryError
Increase heap size:
```bash
export GRADLE_OPTS="-Xmx4g"
./gradlew :hibernate-core:jmh
```
### Inconsistent Results
- Increase warmup iterations
- Run with more forks
- Close background applications
### Slow Benchmarks
- Reduce iterations for quick testing
- Use specific benchmark includes
- Comment out slow benchmarks during development
## References
- [JMH Home](https://github.com/openjdk/jmh)
- [JMH Samples](https://hg.openjdk.java.net/code-tools/jmh/file/tip/jmh-samples/src/main/java/org/openjdk/jmh/samples/)
- [How to Write Good Benchmarks](https://psy-lob-saw.blogspot.com/p/jmh-related-posts.html)
## Result Documentation
- [JMH_BENCHMARK_RESULTS.md](JMH_BENCHMARK_RESULTS.md) - Detailed collection bundling results
- [BENCHMARK_RESULTS.md](../../../test/java/org/hibernate/orm/test/action/queue/bundling/BENCHMARK_RESULTS.md) - Simple benchmark results
---
### Documentation Src Main Asciidoc Dialect Provider Index (`documentation/src/main/asciidoc/dialect-provider/index.adoc`)
include::{root-project-dir}/.asciidoctorconfig.adoc[]
:doctype: book
:icons: font
:html-meta-canonical-link: https://docs.hibernate.org/stable/orm/dialect-provider/
:provider-fixture-dir: {root-project-dir}/tooling/hibernate-dialect-provider/src/providerFixtureTest/java/org/example/orm/dialect
:provider-fixture-main-dir: {root-project-dir}/tooling/hibernate-dialect-provider/src/providerFixture/java/org/example/orm/dialect
:provider-fixture-resources-dir: {root-project-dir}/tooling/hibernate-dialect-provider/src/providerFixture/resources
= Dialect Provider Guide
:toc2:
:toclevels: 3
:sectanchors:
This guide is for authors who publish a SQL Dialect independently of Hibernate
ORM. The link:{doc-dialect-url}[Dialect guide] catalogs available Dialects;
this guide explains how to implement, package, and verify one. Read the
link:{doc-spi-url}[SPI and Service Provider Guide] first for the meaning of
`USE`, `IMPLEMENT`, and `SUPPLY`.
== Provider project setup
Compile against the normal `org.hibernate.orm:hibernate-core` artifact. Do not
depend on `hibernate-testing` or Hibernate's test classes. Keep the provider in
its own artifact and publish an explicit Hibernate compatibility range.
For Gradle builds, apply the provider tooling plugin alongside the Java plugin:
[source,groovy,subs="attributes+"]
----
plugins {
id("java-library")
id("org.hibernate.orm.dialect-provider") version "{fullVersion}"
}
dependencies {
compileOnly("org.hibernate.orm:hibernate-core:{fullVersion}")
}
hibernateDialectProvider {
providerPackages.add("com.acme.hibernate.dialect")
contractProfiles.add("com.acme.hibernate.dialect.AcmeDialectContractProfile")
}
----
The plugin resolves the classification metadata for the Hibernate `X.Y`
release family, validates the normal provider jar, creates the
`dialectProviderTest` source set, aligns the exact-version test kit with Core,
and generates the small JUnit bridge for the explicitly named profile. Put
provider-authored tests in `src/dialectProviderTest/java`.
[NOTE]
====
The Gradle plugin is convenience tooling, not part of the Dialect SPI. Maven,
Ant, and other builds should depend directly on the exact-version
`org.hibernate.orm:hibernate-dialect-testkit`, configure JUnit Jupiter, and
write the small `@TestFactory` bridge shown below. Static external-provider
boundary validation is Gradle-only in this release. The test kit never scans
for or discovers profiles.
====
== Dialect construction and selection
Extend `org.hibernate.dialect.Dialect` or a base class explicitly classified
for `IMPLEMENT`. A no-argument constructor should select the provider's minimum
supported database version. A metadata-aware constructor should copy or default
the `DialectResolutionInfo` version before inherited registration begins.
`Dialect#getVersion()` is the immutable version captured during construction.
Keep minimum-version resolution construction-safe: it must not read subclass
fields before the superclass constructor has completed.
Applications may select a Dialect explicitly with `hibernate.dialect`.
[[dialect-provider-selection-and-resolution]]
=== Explicit names and automatic resolution
Prefer automatic resolution when the database and driver metadata reliably
identify the provider's database. Implement `DialectResolver`, return the
provider Dialect for recognized `DialectResolutionInfo`, and return `null` to
let the next resolver try. Register the implementation as a Java service:
[source,java,indent=0]
----
include::{provider-fixture-main-dir}/ExampleDialectResolver.java[tags=dialect-resolver]
----
.`META-INF/services/org.hibernate.engine.jdbc.dialect.spi.DialectResolver`
[source,text,indent=0]
----
include::{provider-fixture-resources-dir}/META-INF/services/org.hibernate.engine.jdbc.dialect.spi.DialectResolver[]
----
Applications may instead list resolver class names in
`hibernate.dialect_resolvers`. Explicitly configured resolvers run in their
configured order, then service-loaded resolvers run in discovery order, and
Hibernate's standard resolver runs last. The first non-null Dialect wins. An
ordinary resolver exception is logged and resolution continues, while a JDBC
connection exception propagates.
Use `DialectSelector` only when the provider offers an explicit short name for
`hibernate.dialect`. It maps the configured text, unchanged, to a Dialect class
without constructing a Dialect. Return `null` for any unrecognized name so the
next selector and then Hibernate's standard selector may try it:
[source,java,indent=0]
----
include::{provider-fixture-main-dir}/ExampleDialectSelector.java[tags=dialect-selector]
----
.`META-INF/services/org.hibernate.boot.registry.selector.spi.DialectSelector`
[source,text,indent=0]
----
include::{provider-fixture-resources-dir}/META-INF/services/org.hibernate.boot.registry.selector.spi.DialectSelector[]
----
Choose provider short names which are unlikely to collide. The first matching
service wins, but Java service-provider ordering across independent artifacts
is not a portable conflict-resolution mechanism. The test kit deliberately
does not discover resolvers or selectors; a `DialectContractProfile` creates
the exact Dialect under test.
[WARNING]
====
Implement only the public `DialectResolver` or `DialectSelector` contract.
`org.hibernate.boot.registry.selector.internal.LazyServiceResolver` is an
internal Core adapter with no release-family compatibility guarantee and must
not appear in provider code or signatures.
====
== Strategy-oriented architecture
The link:{doc-javadoc-url}org/hibernate/dialect/Dialect.html[`Dialect`] is the
provider's composition root. It captures the database version and resolved
configuration, and supplies focused collaborators to Hibernate's type, query,
JDBC, and schema subsystems. A strategy describes one coherent database
variation; it is not a smaller name for an arbitrary group of Dialect methods.
=== Dialect as composition root
Prefer contracts under `org.hibernate.dialect..spi` to copying
Hibernate implementation code into a provider. Hibernate implementations in a
matching `.internal` package are not provider contracts, even when their Java
visibility permits an import.
Read both sides of a strategy relationship:
* the strategy type states whether providers may use or implement it;
* the Dialect method states how the strategy is supplied;
* reciprocal `@see` links connect the two declarations;
* `IMPLEMENT` does not imply `SUPPLY`, and `SUPPLY` does not imply discovery.
A supplied object should normally be stable for the Dialect's lifetime and
immutable or thread-safe. A shared constant is appropriate for behavior which
does not depend on database version or provider configuration. Use a per-Dialect
instance when the strategy captures resolved state. A Dialect may implement a
strategy directly and return `this` when the strategy contract permits it.
Do not generalize the non-null rule. Some supply points deliberately return
`null` to select Hibernate's standard behavior or to report that a native form
is unavailable. Follow the exact contract of each method.
=== Choosing an extension level
Use the narrowest supported extension which expresses the database behavior:
. Return a named standard constant or immutable profile.
. Construct a profile with its supported builder or factory.
. Compose or implement the focused strategy.
. Override a narrowly classified rendering hook when its contract explicitly
supports provider implementation.
. Supply a custom SQL AST translator only when the variation changes SQL tree
structure or rendering control flow in a way the focused strategies cannot
express.
Do not replace a translator to change a single capability, and do not override
adjacent strategies merely because one consumer happens to use them together.
Independent capability answers allow Hibernate to compose the same database
rules in schema tooling, mutation planning, SQL AST translation, and tests.
=== Family and implementation bases
A concrete selectable Dialect is not automatically a supported superclass.
Extend `Dialect` or a family base whose Javadoc declares `IMPLEMENT`. For
example, a Sybase-derived provider uses `AbstractSybaseDialect`, while
`SybaseDialect` remains the concrete maintained Dialect selected by
applications:
[source,java,indent=0]
----
include::{provider-fixture-main-dir}/ExampleSybaseDialect.java[tags=sybase-family-base]
----
The family base preserves the maintained implementation and exposes the
audited Dialect override surface. Choose the version constructor when the
provider already knows its database version and the resolution-info constructor
when bootstrap metadata determines it. Do not infer an implementation contract
from package placement or Java visibility alone.
=== Identifier, metadata, and literal strategies
See the link:{doc-javadoc-url}org/hibernate/dialect/identifier/spi/package-summary.html[identifier SPI],
link:{doc-javadoc-url}org/hibernate/dialect/literal/spi/package-summary.html[literal SPI],
and link:{doc-javadoc-url}org/hibernate/dialect/jdbc/spi/package-summary.html[JDBC strategy SPI]
for the complete contracts.
[cols="23,30,25,22",options="header"]
|===
|Concern |Primary contract |Dialect supply point |Provider guidance
|Identifier rendering and limits
|`IdentifierSupport`
|`getIdentifierSupport()`
|Describe quoting and identifier-length rules independently from JDBC metadata.
|Identifier normalization
|`IdentifierHelperBuildRequest`
|`buildIdentifierHelper(...)`
|Refine the supplied builder and use `JdbcMetadata` availability explicitly.
|Keyword behavior
|`KeywordSupport`, `KeywordRegistration`
|`getKeywordSupport()`, `contributeKeywords(...)`
|Use the strategy for keyword policy and the callback for registration lifecycle.
|Literal rendering
|`LiteralSupport`
|`getLiteralSupport()`
|Implement only database-specific literal forms and delegate the remainder.
|Metadata correction
|`JdbcMetadataOverrides`
|`getJdbcMetadataOverrides()`
|Override unreliable driver answers without pretending that metadata was read.
|Parameter limits and markers
|`ParameterLimits`, `ParameterMarkerStrategy`
|`getParameterLimits()`, `getNativeParameterMarkerStrategy()`
|Keep driver-sensitive marker selection consistent with the configured driver.
|String-value semantics
|`StringValueSemantics`
|`getStringValueSemantics()`
|Describe empty-string, trailing-space, and comparison behavior as one profile.
|Result-column aliases
|`ColumnAliasExtractor`
|`getColumnAliasExtractor()`
|Choose name- or label-based extraction according to reliable driver behavior.
|===
[[dialect-provider-delegating-identifier-helper]]
==== Decorating identifier helpers
Prefer configuring the `IdentifierHelperBuilder` carried by
`IdentifierHelperBuildRequest`. It already represents global quoting,
automatic keyword quoting, identifier casing, namespace support, and common
automatic-quoting rules. The inherited `buildIdentifierHelper()` initializes
identifier casing, keywords, and namespace support from the request. Invoke it
before replacing any of those values with authoritative provider settings,
then build the final helper from the same builder. Settings which the inherited
implementation does not initialize may be applied before invoking it.
When builder configuration cannot express one database rule, decorate the
configured result with `DelegatingIdentifierHelper`. Do not implement
`IdentifierHelper` directly. The interface is a `USE + SUPPLY` runtime result,
while the delegating base is the supported `IMPLEMENT` contract and shields a
provider from newly added forwarding operations.
Each forwarding operation is independent. If custom normalization must affect
the three `toIdentifier()` entry points, override those entry points as well as
`normalizeQuoting()`. Call `super` for ordinary forwarding and retain only the
returned helper as the decorator's delegate; do not retain the build request,
builder, or metadata view.
This provider-owned decorator quotes an otherwise legal identifier beginning
with `provider_`:
[source,java,indent=0]
----
include::{provider-fixture-main-dir}/ExampleIdentifierHelper.java[tags=identifier-helper-decorator]
----
The Dialect applies automatic-quoting settings not initialized by the inherited
implementation and wraps its result:
[source,java,indent=0]
----
include::{provider-fixture-main-dir}/ExampleDialect.java[tags=identifier-helper-build]
----
==== Composing datetime literals
`LiteralSupport` owns the complete SQL representation of date, time, and
timestamp literals. A provider implementation is therefore responsible for
database-specific introducers, delimiters, casts, and escape syntax. The
link:{doc-javadoc-url}org/hibernate/dialect/literal/spi/StandardDateTimeLiteralRendering.html[`StandardDateTimeLiteralRendering`]
utility supplies just the standard date or time value between those
database-specific elements.
For example, a database which requires its own timestamp introducer but accepts
the standard value representation may compose the two concerns:
[source,java]
----
@Override
public void appendDateTimeLiteral(
SqlAppender appender,
TemporalAccessor temporalAccessor,
TemporalType precision,
TimeZone jdbcTimeZone) {
appender.appendSql( "vendor_timestamp '" );
StandardDateTimeLiteralRendering.appendAsTimestampWithMicros(
appender,
temporalAccessor,
getTemporalValueSemantics().supportsLiteralOffset(),
jdbcTimeZone,
ZeroOffsetLiteralStyle.NUMERIC_OFFSET
);
appender.appendSql( '\'' );
}
----
Choose the zero-offset spelling explicitly: `UTC_DESIGNATOR` emits `Z`, while
`NUMERIC_OFFSET` emits `+00:00`. Nonzero offsets retain their numeric value.
Use the overload matching the database's fractional-second precision, and use
the local-time variants only when the literal syntax intentionally excludes an
offset. Providers should not import the internal `DateTimeUtils`; the public
utility is the supported composition boundary.
JDBC metadata is authoritative only when it is accessible and trustworthy.
Metadata-free bootstrap must obtain every required fallback from the Dialect.
Keyword contribution is therefore a lifecycle operation, while identifier and
metadata support objects are stable strategies.
[NOTE]
====
The aggregate-column, locking, row-level-security, and temporal-table
extension families are incubating. Their contracts may change within an
`X.Y` release family and are excluded from the corresponding SPI compatibility
guarantee. Check the generated Javadoc for `@Incubating` before depending on a
strategy, request, result, or SQL AST contract.
The central SQL AST and translator contracts, translator factories and requests,
`JdbcParameterFactory`, and `JdbcOperations` builders are no longer incubating.
The specialized `SqlAstTranslator.renderNamedSetReturningFunction()` hook and
`SetReturningFunctionType`, together with the SQM-coupled `QueryTransformer`,
remain incubating. This does not stabilize the separate execution, mapping-model
mutation, or result-processing contracts; their individual lifecycle markers
continue to apply.
====
=== Type and temporal strategies
See the link:{doc-javadoc-url}org/hibernate/dialect/type/spi/package-summary.html[type SPI],
link:{doc-javadoc-url}org/hibernate/dialect/temporaltype/spi/package-summary.html[temporal-type SPI],
link:{doc-javadoc-url}org/hibernate/dialect/temporal/spi/package-summary.html[temporal-table SPI],
link:{doc-javadoc-url}org/hibernate/dialect/array/spi/package-summary.html[array SPI],
and link:{doc-javadoc-url}org/hibernate/dialect/lob/spi/package-summary.html[LOB SPI]
for the complete contracts.
[cols="23,30,25,22",options="header"]
|===
|Concern |Primary contract |Dialect supply point |Provider guidance
|Physical type capacities
|`TypeSizingProfile`
|`getTypeSizingProfile()`
|Report supported capacities and precision defaults; use `UNSUPPORTED` only as documented.
|Runtime size resolution
|`SizeStrategy`
|`getSizeStrategy()`
|Customize mapped-size calculation without changing the physical capability profile.
|Direct Java Time JDBC access
|`DirectJavaTimeJdbcSupport`
|`getDirectJavaTimeJdbcSupport()`
|Report exact Java classes accepted for scalar access and independently inside native JDBC `STRUCT` and `ARRAY` containers.
|Enum declarations and checks
|`EnumSupport`
|`getEnumSupport()`
|Keep enum DDL, casts, declarations, and value checks in one strategy; distinguish textual and ordinal DDL when their relational representations differ.
|Array types and literals
|`ArraySupport`
|`getArraySupport()`
|Describe native array behavior; separate it from aggregate-column support.
|LOB behavior
|`LobSupport`
|`getLobSupport()`
|Coordinate LOB type classification, materialization, binding, and merge behavior.
|Untyped null binding
|`ObjectNullBindingStrategy`
|`getObjectNullBindingStrategy()`
|Choose the complete binding policy instead of independent Boolean answers.
|Nationalized and zoned types
|`NationalizationSupport`, `TimeZoneSupport`
|`getNationalizationSupport()`, `getTimeZoneSupport()`
|Report type-system behavior, not temporal literal syntax.
|Current date and time
|`CurrentTemporalSupport`
|`getCurrentTemporalSupport()`
|Supply current temporal expressions and database-side timestamp retrieval; report whether the timestamp expression uses standard `current_timestamp` syntax.
|Temporal formatting
|`TemporalFormatSupport`
|`getTemporalFormatSupport()`
|Translate format patterns without absorbing arithmetic or value semantics.
|Temporal arithmetic
|`TemporalOperationSupport`
|`getTemporalOperationSupport()`
|Own timestamp add/diff patterns and other operation grammar.
|Temporal values
|`TemporalValueSemantics`
|`getTemporalValueSemantics()`
|Describe precision loss, rounding, and offset preservation.
|System-versioned tables
|`TemporalTableSupport`
|`getTemporalTableSupport()`
|Keep temporal-table DDL and historical-query behavior separate from temporal types.
|===
Physical type sizing, runtime size calculation, and type registration are
different stages. `registerColumnTypes()`, `contributeTypes()`, and
`initializeFunctionRegistry()` remain lifecycle callbacks, not strategy
objects. Resolve version and provider configuration before inherited type
registration so those callbacks and all supplied strategies observe one state.
When textual and ordinal named finite-domain types require different DDL,
override `EnumSupport#getCreateOrdinalTypeCommands()`. Its default delegates to
`getCreateTypeCommands()` and is therefore appropriate only when both mappings
use the same database representation.
If `CurrentTemporalSupport#currentTimestamp()` returns a database-specific
expression instead of the standard `current_timestamp` function, also override
`usesStandardCurrentTimestampFunction()` to return `false`.
==== Direct Java Time JDBC access
`DirectJavaTimeJdbcSupport` describes whether the Dialect and its selected
driver exchange an exact `java.time` class directly through JDBC. Scalar
support covers both `PreparedStatement#setObject()` and typed
`ResultSet#getObject()`, together with the corresponding callable-statement
operations. Report a class as supported only when both directions work.
The inherited `Dialect` profile assumes the scalar support required by JDBC
4.2: `LocalDate`, `LocalTime`, `LocalDateTime`, `OffsetTime`, and
`OffsetDateTime`. Override `getDirectJavaTimeJdbcSupport()` when a supported
driver does not implement part of that contract, or when the driver supports
the additional `ZonedDateTime` or `Instant` classes. Resolve any driver- or
version-sensitive answer during Dialect construction and return one stable,
thread-safe profile.
Use `DirectJavaTimeJdbcSupports.none()`, `jdbc42()`, `all()`, or `of(...)`
instead of depending on an implementation class. The three-set `of(...)`
overload reports scalar, native JDBC `STRUCT`, and native JDBC `ARRAY` support
independently:
[source,java,indent=0]
----
include::{provider-fixture-main-dir}/ExampleDialect.java[tags=direct-java-time-jdbc-support]
----
None of the scalar-only profiles infer native-container support: `jdbc42()`,
`all()`, and the varargs `of(...)` report no direct `STRUCT` or `ARRAY`
support. Use the three-set overload only when the driver accepts the exact
class while creating and extracting that container kind.
`OffsetTime` and `OffsetDateTime` are a matched pair within each access path.
Both must be present in the scalar, `STRUCT`, or `ARRAY` set to enable either
one for that path; omitting either class disables both. Support for
`OffsetDateTime` also lets Hibernate represent a mapped `ZonedDateTime` as an
`OffsetDateTime` when exact `ZonedDateTime` access is unavailable. Claim exact
`ZonedDateTime` support only when the driver itself exchanges that class.
`Instant` is not enabled merely by
`hibernate.type.java_time_use_direct_jdbc`. It is considered when the
application selects `INSTANT` with
`hibernate.type.preferred_instant_jdbc_type`, and still requires the Dialect
profile to report `Instant` support.
This strategy describes Java values at the JDBC boundary. Keep it separate
from `TimeZoneSupport`, which describes database type behavior, and
`TemporalValueSemantics`, which describes precision adjustment and temporal
literal offset preservation. If direct access is requested but the profile
reports it unsupported, Hibernate falls back to the corresponding physical
representation and logs the known limitation once per Java Time class, with
the offset pair logged together.
=== Implementing and contributing Java/JDBC types
A custom basic mapping normally pairs a
link:{doc-javadoc-url}org/hibernate/type/descriptor/java/JavaType.html[`JavaType`]
with a
link:{doc-javadoc-url}org/hibernate/type/descriptor/jdbc/JdbcType.html[`JdbcType`].
The Java descriptor owns Java-side equality, wrapping, unwrapping, mutability,
and its JDBC recommendation. The JDBC descriptor owns type codes, binding,
extraction, and optional SQL-literal formatting. Keep those responsibilities
separate even when both descriptors are implemented by the same provider.
The principal provider contracts are:
[cols="28,29,43",options="header"]
|===
|Concern |Contract or base |Guidance
|Java value semantics
|`JavaType`, `BasicJavaType`, `AbstractJavaType`, `AbstractClassJavaType`
|Implement a descriptor or extend the narrowest base whose defaults match the value.
|Mutability
|`MutabilityPlan`, `MutableMutabilityPlan`
|Supply the plan from `JavaType#getMutabilityPlan()`; make immutable plans reusable.
|JDBC access
|`JdbcType`, `BasicBinder`, `BasicExtractor`
|Supply a binder and extractor from the descriptor. Conversion belongs outside those operations.
|Parameterized JDBC types
|`JdbcTypeConstructor`
|Resolve a descriptor from the element JDBC type and the supplied mapping context.
|Aggregate and structured values
|`AggregateJdbcType`, `StructuredJdbcType`
|Treat the registered instance as a prototype, supply the mapping-specific descriptor from `resolveAggregateJdbcType(...)`, and use `AggregateJdbcValues` instead of internal struct helpers.
|Bootstrap registration
|`TypeContributor`, `TypeContributions`
|Register descriptors during metadata bootstrap and never retain the lifecycle-scoped contributions object.
|===
For independently reusable types, expose a `TypeContributor` as a Java service
or register it programmatically. A contributor may register both sides of the
pair and any parameterized constructor in one callback:
[source,java]
----
public final class ProviderTypeContributor implements TypeContributor {
@Override
public void contribute(
TypeContributions contributions,
ServiceRegistry serviceRegistry) {
contributions.contributeJavaType( ProviderJavaType.INSTANCE );
contributions.contributeJdbcType( ProviderJdbcType.INSTANCE );
contributions.contributeJdbcTypeConstructor(
ProviderJdbcTypeConstructor.INSTANCE
);
}
}
----
A Dialect may perform database-specific registration from
`contributeTypes(...)` using the same callbacks. Invoke inherited registration
before adding or replacing descriptors unless the Dialect deliberately owns
the complete inherited type set. Resolve version and driver configuration
before that inherited call.
For PostgreSQL component-format structured values, extend
`org.hibernate.dialect.type.spi.AbstractPostgreSQLStructJdbcType`. Use its
runtime-model constructor for a mapped aggregate; Hibernate resolves the
boot-model attribute ordering without exposing the boot mapping as a provider
dependency. Implement only the driver binding, extraction, and write-expression
variation owned by the provider.
==== Aggregate JDBC values and native containers
`AggregateJdbcType` separates a mapped aggregate from the single native value
bound to or extracted from the JDBC driver. A provider implementing a custom
aggregate or structured type owns the encoding of that native container. For
example, a document-oriented driver might encode an `Object[]` as a native
document and decode that document back into component values.
`AggregateJdbcValues` owns the Hibernate mapping work on either side of that
provider codec. Use `fromDomainValue(...)` before encoding a native value, use
`toLogicalJdbcValues(...)` to implement
`AggregateJdbcType#extractJdbcValues(...)`, and use `toDomainValue(...)` when a
JDBC extractor must return the mapped embeddable value:
[source,java,indent=0]
----
include::{provider-fixture-main-dir}/ExampleStructuredJdbcType.java[tags=aggregate-jdbc-values]
----
The no-order overloads use Hibernate's logical mapping order. If the native
container has a different physical order, create an immutable
`AggregateJdbcValueOrder` with the logical value found at each physical
position. Thus `physicalOrder(2, 0, 1)` transforms logical values `[A, B, C]`
to physical values `[C, A, B]`. The order is validated as a complete
permutation and its inverse is calculated once.
[IMPORTANT]
====
Decode the provider-specific container before calling `AggregateJdbcValues`,
and normalize driver-specific scalar anomalies as part of that decoding. The
facade handles mapping conversion, nested aggregates, discriminators, and
ordering; it does not understand arbitrary native document formats. Do not use
the internal `StructHelper` or expose `StructAttributeValues` from provider
code.
====
For a provider codec backed by a native JDBC `STRUCT` or `ARRAY`, component
values produced by `AggregateJdbcValues#fromDomainValue(...)` may use direct
Java Time classes selected by the mapping. Consult `supportsInStruct()` or
`supportsInArray()` before passing such a value to the driver. When that
container path does not support the exact class, use the public
`JavaTimeJdbcType` physical-type and conversion helpers to obtain the
representation expected by the corresponding SQL type. These container
capabilities do not apply to textual JSON, XML, or other provider-defined
document encodings.
Focused facilities cover common composition needs without exposing their Core
implementations:
* `DB2JdbcTypes` supplies stable stock descriptors, including the seven Java
temporal descriptors with DB2's null-safe typed-`getObject` behavior;
* `LobDataExtraction` materializes a binary stream or CLOB using Hibernate's
standard closing and exception-conversion behavior. It closes the consumed
stream or reader, but the caller remains responsible for freeing the JDBC
locator; and
* `EnumRelationalValues` returns enum names or converter-produced relational
strings in declaration order. Sort the returned fresh array only when the
database declaration requires it.
Do not import `.internal` descriptor implementations or utilities merely to
obtain stock behavior. An internal class may change between releases without
the `X.Y` SPI compatibility expectations described in the SPI and Service
Provider Guide.
=== Schema and DDL strategies
See the link:{doc-javadoc-url}org/hibernate/dialect/schema/spi/package-summary.html[schema SPI],
link:{doc-javadoc-url}org/hibernate/dialect/constraint/spi/package-summary.html[constraint SPI],
link:{doc-javadoc-url}org/hibernate/dialect/namespace/spi/package-summary.html[namespace SPI],
link:{doc-javadoc-url}org/hibernate/dialect/identity/spi/package-summary.html[identity SPI],
link:{doc-javadoc-url}org/hibernate/dialect/sequence/spi/package-summary.html[sequence SPI],
and link:{doc-javadoc-url}org/hibernate/dialect/temptable/spi/package-summary.html[temporary-table SPI]
for the complete contracts.
[cols="23,30,25,22",options="header"]
|===
|Concern |Primary contract |Dialect supply point |Provider guidance
|Catalog and schema lifecycle
|`NamespaceSupport`
|`getNamespaceSupport()`
|Render create/drop commands without conflating qualification or catalog separators.
|Conditional DDL
|`IfExistsSupport`
|`getIfExistsSupport()`
|Describe placement independently for each supported database object.
|Table alteration and creation
|`AlterTableSupport`, `TableCreationSupport`
|`getAlterTableSupport()`, `getTableCreationSupport()`
|Return focused fragments and plans which exporters compose.
|Column definitions
|`ColumnDefinitionSupport`
|`getColumnDefinitionSupport()`
|Own column declaration ordering, nullability, defaults, and generated clauses.
|Indexes and constraints
|`IndexDdlSupport`, `ConstraintControlSupport`
|`getIndexDdlSupport()`, `getConstraintControlSupport()`
|Keep index grammar separate from runtime enable/disable commands.
|Truncation and schema drop
|`TruncateSupport`, `SchemaDropSupport`
|`getTruncateSupport()`, `getSchemaDropSupport()`
|Preserve command ordering and multi-command results.
|Foreign keys and checks
|`ForeignKeySupport`, `CheckConstraintSupport`
|`getForeignKeySupport()`, `getCheckConstraintSupport()`
|Render focused constraint fragments consumed by schema exporters.
|Database-object comments
|`SchemaCommentSupport`
|`getSchemaCommentSupport()`
|Handle schema-object comments only, not SQL query comments.
|Identity and sequences
|`IdentityColumnSupport`, `SequenceSupport`
|`getIdentityColumnSupport()`, `getSequenceSupport()`
|Keep value generation and DDL/extraction behavior consistent.
|Complete object commands
|`Exporter`, `TableMigrator`, `TableCleaner`
|the `get...Exporter()`, `getTableMigrator()`, and `getTableCleaner()` methods
|Use exporters for complete commands and support strategies for focused pieces.
|Temporary-table lifecycle
|`TemporaryTableStrategy`, `TemporaryTableExporter`
|persistent/local/global strategy methods and `getTemporaryTableExporter()`
|Make the selected strategy kind, lifecycle commands, and exporter agree.
|===
`NameQualifierSupport`, `getCatalogSeparator()`, and `NamespaceSupport` are
related but independent. The first describes which qualifiers are supported,
the second supplies metadata-free catalog punctuation, and the third owns
catalog/schema creation and removal.
=== Query-shape strategies
Query strategies describe independent pieces of database grammar. They remain
Dialect capabilities even when the SQL AST translator is their primary
consumer.
See the link:{doc-javadoc-url}org/hibernate/dialect/sql/ast/spi/package-summary.html[Dialect SQL AST SPI],
link:{doc-javadoc-url}org/hibernate/dialect/function/spi/package-summary.html[function SPI],
link:{doc-javadoc-url}org/hibernate/dialect/aggregate/spi/package-summary.html[aggregate SPI],
and link:{doc-javadoc-url}org/hibernate/dialect/queryhint/spi/package-summary.html[query-hint SPI]
for the complete contracts.
[cols="23,30,25,22",options="header"]
|===
|Concern |Primary contract |Dialect supply point |Provider guidance
|Predicates and row values
|`PredicateSupport`, `RowValueSupport`
|`getPredicateSupport()`, `getRowValueSupport()`
|Describe placement and tuple grammar independently.
|Aggregate and window syntax
|`TupleCountSupport`, `ExpressionCoercionSupport`, `WindowFunctionSupport`
|the corresponding `get...Support()` methods
|Report exact function forms without creating an aggregate catch-all.
|Set operations and subqueries
|`SetOperationSupport`, `SubquerySupport`
|`getSetOperationSupport()`, `getSubquerySupport()`
|Represent each placement restriction explicitly.
|Ordering and grouping
|`NullOrderingSupport`, `FunctionalDependencyAnalysisSupport`
|`getNullOrderingSupport()`, `getFunctionalDependencyAnalysisSupport()`
|Separate null precedence from group-by functional-dependency rules.
|Tableless and synthetic roots
|`SingleRowTableSupport`, `SyntheticTableGroupSupport`
|`getSingleRowTableSupport()`, `getSyntheticTableGroupSupport()`
|Use a synthetic root only for the query shapes which require one.
|Common table expressions
|`CteSupport`
|`getCteSupport()`
|Describe placement, recursion, materialization, and mutation capabilities.
|DML grammar
|`MutationSyntaxSupport`, `DmlTargetColumnQualifierSupport`
|`getMutationSyntaxSupport()`, `getDmlTargetColumnQualifierSupport()`
|Keep mutation syntax separate from bulk-mutation execution planning.
|Values and fetch clauses
|`ValuesListSupport`, `FetchClauseSupport`
|`getValuesListSupport()`, `getFetchClauseSupport()`
|Report context support for `values` independently of list cardinality; an unsupported context is emulated even for one row.
|Query hints
|`QueryHintPlacement`
|`getQueryHintPlacement()`
|Coordinate placement with the retained focused hint-rendering methods.
|===
Prefer a named standard profile for a standard database rule:
[source,java,indent=0]
----
include::{provider-fixture-main-dir}/ExampleDialect.java[tags=standard-strategy-profile]
----
Use builders and immutable value profiles when several independent features
must be stated together:
[source,java,indent=0]
----
include::{provider-fixture-main-dir}/ExampleDialect.java[tags=built-query-strategies]
----
`SyntheticTableGroupSupport` is the canonical example of this architecture. A
focused capability replaced database-specific SQM converters which existed
only to add a synthetic table root for literal grouping or ordering.
[[dialect-provider-function-contracts]]
=== Function contribution and descriptor contracts
Function registration is a bootstrap lifecycle, not a long-lived strategy.
A Dialect contributes its database-specific function set from
`initializeFunctionRegistry(FunctionContributions)`. A library or application
which contributes functions independently of a Dialect implements
`FunctionContributor` and supplies it through Java service loading,
`Configuration#registerFunctionContributor()`, or
`MetadataBuilder#applyFunctions()`.
Both callbacks receive a boot-scoped `FunctionContributions`. Use it to obtain
the `SqmFunctionRegistry`, `TypeConfiguration`, and services, complete all
registrations before returning, and retain neither the contribution context nor
the mutable registry. Independent contributors execute in ascending ordinal
order before the Dialect callback. A later registration under the same key
replaces an earlier one.
Choose the smallest supported extension level which expresses the function:
[cols="28,33,39",options="header"]
|===
|Need |Contract |Provider guidance
|A stock Hibernate definition or database variant
|`CommonFunctionFactory`
|Construct it inside the callback, invoke the required stock methods, and
discard it before returning. The factory supports use, not subclassing or
supply.
|A simple provider-defined named or pattern function
|`SqmFunctionRegistry` descriptor builders
|Configure validation, return-type inference, argument-type inference, and
rendering through a builder, then register immediately.
|Custom SQM generation
|`SqmFunctionDescriptor` or `AbstractSqmFunctionDescriptor`
|Implement a reusable descriptor and register its stable instance through a
descriptor-accepting supply point.
|Custom self-rendering SQL
|`FunctionRenderer` or `AbstractSqmSelfRenderingFunctionDescriptor`
|Own SQL AST rendering in the descriptor. Use a supported focused Dialect
function base when its existing behavior is the intended starting point.
|===
For example, a Dialect may combine a stock definition, a simple pattern, and a
provider-owned descriptor in the same callback:
[source,java]
----
@Override
public void initializeFunctionRegistry(FunctionContributions contributions) {
super.initializeFunctionRegistry( contributions );
new CommonFunctionFactory( contributions ).cot();
contributions.getFunctionRegistry()
.patternDescriptorBuilder( "provider_concat", "(?1 || ?2)" )
.setExactArgumentCount( 2 )
.register();
contributions.getFunctionRegistry().register(
"provider_self_rendering",
new ProviderSelfRenderingFunctionDescriptor()
);
}
----
The selected general, array, and JSON descriptor bases are supported where
their Javadocs declare `IMPLEMENT`; the package as a whole is not an
implementation contract. `CommonFunctionFactory` is a supported catalog of
stock registrations for the current Hibernate `X.Y` release family. Adding a
stock method is compatible, while removing or incompatibly changing an
existing stock method is not. Its instances are callback-local helpers and are
never supplied to Hibernate.
See the link:{doc-javadoc-url}org/hibernate/boot/model/FunctionContributor.html[`FunctionContributor`],
link:{doc-javadoc-url}org/hibernate/query/sqm/function/SqmFunctionDescriptor.html[`SqmFunctionDescriptor`],
link:{doc-javadoc-url}org/hibernate/query/sqm/function/SqmFunctionRegistry.html[`SqmFunctionRegistry`],
and link:{doc-javadoc-url}org/hibernate/dialect/function/CommonFunctionFactory.html[`CommonFunctionFactory`]
contracts for exact roles, constructors, and supply points.
=== Execution, locking, and mutation strategies
See the link:{doc-javadoc-url}org/hibernate/dialect/lock/spi/package-summary.html[locking SPI],
link:{doc-javadoc-url}org/hibernate/dialect/pagination/spi/package-summary.html[pagination SPI],
link:{doc-javadoc-url}org/hibernate/dialect/mutation/spi/package-summary.html[bulk-mutation SPI],
link:{doc-javadoc-url}org/hibernate/dialect/generated/spi/package-summary.html[generated-values SPI],
link:{doc-javadoc-url}org/hibernate/dialect/rowid/spi/package-summary.html[row-id SPI],
and link:{doc-javadoc-url}org/hibernate/dialect/rowsecurity/spi/package-summary.html[row-security SPI]
for the complete contracts.
[cols="23,30,25,22",options="header"]
|===
|Concern |Primary contract |Dialect supply point |Provider guidance
|Pagination
|`LimitHandler`
|`getLimitHandler()`
|Use a standard handler or implement the request/result contract for custom SQL and JDBC instructions.
|Query locking
|`LockingSupport`, `LockingClauseStrategy`
|`getLockingSupport()`, `getLockingClauseStrategy(...)`
|Use the stable profile for capabilities and the per-request strategy for clause selection.
|Transaction concurrency
|`TransactionConcurrency`, `TransactionConcurrencyResolver`
|`LockingSupport#getTransactionConcurrencyResolver()`
|Resolve the factory's read guarantees and operation conflicts from database configuration and available bootstrap facts.
|Entity locking
|`EntityLockingStrategyFactory`
|`getEntityLockingStrategyFactory()`
|Create a strategy for the supplied request without retaining bootstrap state.
|Bulk mutation fallback
|`MultiTableMutationSupport`
|`getMultiTableMutationSupport()`
|Choose CTE or temporary/persistent-table handling separately for operation families.
|Generated values and row locators
|`GeneratedValuesSupport`, `RowIdSupport`
|`getGeneratedValuesSupport()`, `getRowIdSupport()`
|Coordinate SQL expressions, retrieval, JDBC typing, and physical declaration; return `RowIdSupports.none()` when a variant lacks an inherited row locator.
|Row-level security
|`RowLevelSecurity`
|`getRowLevelSecurity()`
|Keep tenant predicates and supporting DDL in one coherent strategy.
|Callable statements and cursors
|`CallableStatementSupport`, `RefCursorSupportFactory`
|`getCallableStatementSupport()`, `getRefCursorSupportFactory()`
|Separate callable syntax from cursor registration/extraction lifecycle.
|Multi-key loading
|`MultiKeyLoadSizingStrategy`
|`getMultiKeyLoadSizingStrategy()`, `getBatchLoadSizingStrategy()`
|Respect parameter limits when choosing batch sizes.
|===
A custom focused implementation may still be a stable singleton:
[source,java,indent=0]
----
include::{provider-fixture-main-dir}/ExampleDialect.java[tags=custom-locking-strategy]
----
==== Choosing a locking profile
`Dialect#getLockingSupport()` supplies one cohesive, stable profile for the
Dialect lifetime. Its metadata, clause renderer, table-hint renderer,
completed-SQL rewriter, follow-on policy, connection-timeout strategy, and
transaction-concurrency resolver must
describe the same database behavior. The profile and all reusable components
must be immutable or thread-safe; per-query target collection belongs to the
`LockingClauseStrategy` created for that translation.
Choose the narrowest supported approach:
* Use a named `StandardLockingSupports` factory when extending a maintained
database family. These factories preserve Hibernate's version thresholds and
coordinated syntax, timeout behavior, and concurrency resolution.
* Use `StandardLockingSupports.simple(...)` when every timeout has one
classification, or `parameterized(...)` when wait, no-wait, and skip-locked
differ. These factories return the SPI interface and do not expose the
Hibernate-owned implementation.
* Implement `LockingSupport` only when the database requires behavior which
cannot be expressed by those profiles, such as custom table hints, raw-SQL
placement, or follow-on policy. Keep the implementation provider-owned and
return stable components.
A follow-on policy reports whether follow-on locking is required; it does not
guarantee that a particular execution plan supplies the actions needed to
perform it. For completed or raw SQL without those actions, `ALLOW` proceeds
without Hibernate-applied pessimistic locking, `FORCE` fails, and `DISALLOW`
fails when either the policy or SQL-rewrite outcome requires follow-on locking.
`IGNORE` likewise proceeds without Hibernate-applied locking when follow-on is
required.
For statement-clause translation, use
`StandardLockingClauseStrategies.none()` when locking is expressed elsewhere.
Use `standard(...)` to combine a provider-owned `LockingClauseRenderer` with
Hibernate's standard root and join target collection. A custom strategy is
appropriate only when target collection itself differs.
A provider-owned connection-timeout strategy should use
`ConnectionLockTimeoutOperations` for query and command execution so it
participates in Hibernate's SQL logging, statement observation, resource
closing, and exception conversion. MySQL-compatible providers may use
`StandardConnectionLockTimeoutStrategies.mysql(waitForeverValue)` when their
only variation is the value representing an effectively unbounded wait.
==== Resolving transaction concurrency
link:{doc-javadoc-url}org/hibernate/dialect/lock/spi/TransactionConcurrency.html[`TransactionConcurrency`]
describes database behavior for the factory's connections. Hibernate uses its
answers when implementing lock modes, including optimistic version checks and
stateless-session locking. JDBC isolation constants alone do not establish these
answers: for example, SQL Server's read-committed behavior also depends on
`READ_COMMITTED_SNAPSHOT`.
Supply a provider-owned
link:{doc-javadoc-url}org/hibernate/dialect/lock/spi/TransactionConcurrencyResolver.html[`TransactionConcurrencyResolver`]
through `LockingSupport#getTransactionConcurrencyResolver()`, or use a
`StandardLockingSupports.simple(...)` or `parameterized(...)` overload accepting
a resolver. Named database-family factories already supply their associated
resolvers. The default resolver is conservative; it does not infer database
guarantees from the availability of locking syntax. The deprecated
`LockingSupport.Metadata#readsWaitForUncommittedWrites()` flag does not supply
the concurrency descriptor.
The resolver is reusable, but its result belongs to the factory's
`JdbcEnvironment` and is available from `JdbcEnvironment#getTransactionConcurrency()`.
Do not store the resolved result on a potentially shared Dialect or locking
profile. Return an immutable descriptor; `TransactionConcurrencies.builder(...)`
is available for constructing one. Connection isolation and relevant database
settings must remain consistent across the factory. This contract describes
that configuration; it does not change connections or coordinate active sessions.
===== Bootstrap and declarations
Resolution runs with the connection already borrowed by bootstrap, or with a
`null` connection when JDBC access is unavailable. Use the supplied metadata,
established database facts, and any declaration to resolve behavior. Leave
missing facts unknown. In particular, a database's default isolation does not
prove which isolation the factory's connections use.
When a connection is supplied and `JdbcMetadataOnBoot` permits access, query it
for settings needed to distinguish configurations. Do not acquire another
connection, retain or close the supplied connection, or change its settings.
Close statements and result sets created by the resolver. A failed supported
probe may leave facts unknown under `ALLOW`; under `REQUIRE`, it must fail
resolution. A fact for which no probe is supported may remain unknown under
either policy.
`hibernate.transaction.concurrency`, defined by
link:{doc-javadoc-url}org/hibernate/cfg/TransactionSettings.html#TRANSACTION_CONCURRENCY[`TransactionSettings.TRANSACTION_CONCURRENCY`],
accepts a named declaration or a `TransactionConcurrency` instance. The setting's
Javadoc lists the standard names and their meanings. Providers may document
additional names. A name supplies otherwise unavailable facts, including when
JDBC access is disabled; it must not override contradictory observations or
established database facts. Reject invalid names, contradictions, and required
probe failures with `TransactionConcurrencyResolutionException` so bootstrap
fallback does not hide them.
A supplied descriptor instance is authoritative: bootstrap uses it unchanged
without invoking the resolver. Direct resolver calls receiving an instance must
also return it unchanged without probing or validation. The caller is responsible
for its accuracy and immutability. Neither form of declaration configures
connection isolation.
===== Operations, guarantees, and rendered SQL
Describe actual database operations using `Operation`, independently of the
Hibernate lock mode which requested them:
* `READ` is an ordinary read under the configured isolation. It may itself
acquire locks or provide current committed state.
* `CURRENT_READ` is the explicit strategy for reading current committed state,
resolving conflicting uncommitted writes before succeeding. It may instead
fail on a conflict, and need not retain a lock after the statement.
* `SHARED_LOCK_READ` and `UPDATE_LOCK_READ` describe the actual row lock acquired.
Implementing `PESSIMISTIC_READ` with an update lock does not establish support
for `SHARED_LOCK_READ`.
* `WRITE` modifies or deletes an existing row and has no read guarantees.
`getBlockingDuration(precedingOperation, concurrentOperation)` describes how long
protection established by the first operation can exclude the second operation
in another transaction on the same existing row. Direction matters. This is a
static database rule, not a measurement of active sessions or elapsed wait time.
`UNKNOWN` and `CONDITIONAL` do not prove exclusion. Predicate locks, phantoms,
schema locks, escalation, and incidental internal waits are outside this contract.
Use `ReadGuarantees` to distinguish stable snapshot visibility, current committed
state, prevention of concurrent modification, and a row lock retained until
transaction completion. A stable snapshot or possible serialization failure
does not establish protection against modification. Report only guarantees
which Hibernate may rely on for the resolved configuration.
Keep the explicit `CURRENT_READ` guarantees consistent with
`LockingSupport#renderCurrentReadTableHint(String, TransactionConcurrency)` and
`renderCurrentReadClause(TransactionConcurrency)`. Hibernate first checks whether
ordinary `READ` already provides `isCurrentRead()`. Otherwise, it requires a
supported `CURRENT_READ` with that guarantee before requesting the explicit
strategy. The default renderers use the profile's share-lock hint or clause;
override them when the database needs a different strategy. A cheaper hint which
waits for writes but retains no lock must not advertise transaction-long protection.
Provider tests should cover resolution with and without JDBC, named declarations
and contradictions, authoritative descriptor instances, and optional versus
required probe failures. Test configuration variants affecting concurrency, and
verify the claimed read guarantees and directional conflicts using separate
transactions against the database, including the SQL rendered for explicit reads.
=== Cross-strategy consistency
Focused strategies remain independent, but some combinations must describe one
valid database configuration.
[cols="35,65",options="header"]
|===
|Supplied behavior |Must agree with
|Transaction concurrency descriptor
|The configured isolation and database settings, actual locks acquired, and current-read hints or clauses rendered by the locking profile.
|Multi-table mutation profile
|The selected CTE and local/global/persistent temporary-table capabilities.
|Temporary-table strategy
|The temporary-table exporter and its create, drop, truncate, and lifecycle commands.
|Temporal-table support
|Type sizing and check-constraint support used to build its DDL profile.
|Identifier helper
|Identifier, keyword, and JDBC metadata behavior.
|Native parameter markers
|Resolved driver/version behavior and parameter limits.
|Schema exporters
|The focused schema, constraint, comment, and `IF EXISTS` strategies they compose.
|SQL AST translator
|Every focused capability consulted by the standard translation pipeline.
|===
For example, the fixture's asymmetric bulk-mutation profile selects a local
temporary table for one operation family, so the Dialect supplies the matching
local strategy:
[source,java,indent=0]
----
include::{provider-fixture-main-dir}/ExampleDialect.java[tags=local-temporary-table-strategy]
----
When a complete built-in vendor profile matches the provider's database, use
`TemporaryTableStrategies.db2Global()`, `hsqlLocal()`, `mysqlLocal()`,
`oracleLocal()`, or `sqlServerLocal()`. These accessors return the public
`TemporaryTableStrategy` contract; do not depend on the concrete class or its
identity. Implement a provider-owned strategy when any naming, DDL, column, or
lifecycle answer differs.
A CTE selection likewise requires the appropriate non-query CTE feature.
Configured global or entity-specific custom mutation strategies retain their
documented precedence over the Dialect fallback profile.
== SQL AST translation and the global HQL/SQM boundary
`Dialect#getSqlAstTranslatorFactory()` is the only general translator factory
supplied by a Dialect. Returning `null` selects
link:{doc-javadoc-url}org/hibernate/dialect/sql/ast/spi/StandardSqlAstTranslatorFactory.html[`StandardSqlAstTranslatorFactory`].
A custom factory should normally extend that standard factory, remain reusable
and thread-safe, retain no translation request, and create a fresh single-use
translator for every request.
[source,java,indent=0]
----
include::{provider-fixture-main-dir}/ExampleDialect.java[tags=sql-ast-translator-factory]
----
Override a focused strategy first when the variation is declarative. Supply a
translator subclass only when rendering requires structural behavior or
control flow which the focused strategies cannot express. A custom translator
must still honor every applicable strategy supplied by its Dialect.
For a JDBC driver whose command language is fundamentally different from SQL,
the factory may instead return a direct `SqlAstTranslator` implementation. Use
`AbstractSqlAstWalker` as the structural traversal base and own the command
representation explicitly. This is appropriate, for example, for a document
database exposed through a JDBC driver; the generated command text need only be
understood by that driver.
[source,java,indent=0]
----
include::{provider-fixture-main-dir}/ExampleDirectSqlAstTranslator.java[tags=direct-sql-ast-translator]
----
Direct translators should create their executable query descriptions with
link:{doc-javadoc-url}org/hibernate/sql/exec/spi/JdbcOperations.html[`JdbcOperations`].
Its typed `select()` and `queryMutation()` builders return only SPI interfaces
and hide Hibernate's operation implementations. Supply parameter binders in
command-placeholder order, and identify affected relational tables or their
backend-equivalent query spaces so cache invalidation remains correct.
When a translated command renders query-options-backed pagination placeholders,
create them with
link:{doc-javadoc-url}org/hibernate/sql/ast/spi/query/expression/JdbcParameterFactory.html[`JdbcParameterFactory`].
Its query-limit and query-offset factories produce parameters whose binders read
the original `QueryOptions` instead of ordinary `JdbcParameterBindings`. Add each
binder in command-placeholder order and pass the same parameter instance to the
corresponding `JdbcOperations.SelectBuilder` pagination method. The overloads
accepting `TypeConfiguration` resolve Hibernate's persistence-unit-scoped
`Integer` basic type; use the `BasicType` overload only when that type
has already been resolved from the current persistence unit. For other
execution-context-backed values, `custom()` creates a parameter expression from
a JDBC mapping and provider-owned binder without exposing Hibernate internals.
[NOTE]
====
`SqlAstTranslationRequest.ModelMutation` is deliberately not accepted by
either `JdbcOperations` builder. It represents mapping-model work originating
from flush, not a query-language mutation. After translating its
`TableMutation`, call `TableMutation#createMutationOperation(command,
parameterBinders)` so the mapping model retains ownership of the concrete
operation, expectation, callable state, and table metadata.
====
Translator subclasses may call
`getVersionSeedMapping(Expression)` to recognize Hibernate's generated version
seed and obtain its public mapping, or
`isParameterInterpretation(Expression)` when behavior must distinguish an SQM
parameter interpretation from an ordinary JDBC parameter. Both methods are
final provider operations, not override points. To append an expression to a
`SelectClause` without constructing an internal selection implementation, call
`addSqlSelection(Expression)`.
=== Provider expressions and full-MERGE translators
For a provider-owned SQL AST expression, extend
link:{doc-javadoc-url}org/hibernate/dialect/sql/ast/spi/AbstractSelfRenderingExpression.html[`AbstractSelfRenderingExpression`]
instead of directly implementing the low-level `SelfRenderingExpression`
protocol. Supply the nullable mapping type once; the base retains it, owns final
visitor dispatch, and leaves one rendering callback to the provider:
[source,java,indent=0]
----
include::{provider-fixture-main-dir}/ExampleSelfRenderingExpression.java[tags=self-rendering-expression]
----
For databases whose optional-table mutations use a full insert/update/delete
`MERGE`, extend
link:{doc-javadoc-url}org/hibernate/dialect/sql/ast/spi/SqlAstTranslatorWithMerge.html[`SqlAstTranslatorWithMerge`].
Override the smallest protected `renderMerge...` callback which expresses the
grammar difference:
[source,java,indent=0]
----
include::{provider-fixture-main-dir}/ExampleMergeSqlAstTranslator.java[tags=full-merge-translator]
----
`createMergeOperation()` is final because Hibernate owns SQL collection,
parameter ordering, expectation selection, and operation construction. The
full-MERGE base does not imply that the adjacent `SqlAstTranslatorWithUpsert`
is a supported provider base.
`Dialect#getHqlTranslator()` and `Dialect#getSqmTranslatorFactory()` no longer
exist. HQL parsing and general SQM conversion are query-engine-wide concerns,
not Dialect supply points. Framework integrations which intentionally replace
them use the global settings `hibernate.query.hql.translator` and
`hibernate.query.sqm.translator`, exposed downstream by
link:{doc-javadoc-url}org/hibernate/query/spi/QueryEngineOptions.html[`QueryEngineOptions#getCustomHqlTranslator()` and `getCustomSqmTranslatorFactory()`].
There is no service-loaded or Dialect-level fallback for those global
translators. The standalone fixture's `ExampleSqmTranslatorFactory` verifies
the global request-based integration contract; `ExampleDialect` does not
supply it.
== A database-free contract profile
`org.hibernate.orm:hibernate-dialect-testkit` boots a fixed mapping model with
JDBC metadata access disabled. The profile supplies a fresh Dialect, its expected
version, optional safe settings, and applicability decisions for optional
contracts.
[source,java,indent=0]
----
include::{provider-fixture-dir}/ExampleDialectContractProfile.java[tags=profile]
----
Profile names must be stable and nonblank. `createDialect()` must return a new
instance on every call. Settings must not select a different Dialect, request
JDBC metadata, provide a connection, or execute schema commands.
== Running the generic suite
With the Gradle plugin, name each provider-owned profile in
`hibernateDialectProvider.contractProfiles`. The generated bridge constructs
profiles in declared order and calls `DialectTestKit.contractTests(profile)`;
it does not generate the profile itself and is never packaged in the provider
jar. Run the complete provider verification with:
[source,shell]
----
./gradlew verifyDialectProvider
----
The constituent tasks are `validateDialectProviderBoundaries` and
`dialectProviderTest`. Boundary reports are written to
`build/reports/hibernate-dialect-provider/boundary-validation.txt` and
`boundary-validation.json`. Set `attachToCheck = false` only when another
lifecycle task deliberately invokes `verifyDialectProvider`.
An `INTERNAL_TARGET` finding is a warning: it identifies a dependency with no
release-to-release compatibility guarantee, but does not fail validation by
default. A `MISSING_IMPLEMENT_ROLE` finding is an error because the provider is
extending, implementing, or overriding a declaration which Hibernate does not
support as a provider extension point. Set `warningsAsErrors = true` when a
provider wants internal-use warnings to fail its build. Strict mode changes
only the build outcome; reports continue to identify those findings as
`WARNING`.
A provider-owned SPI contract may extend or implement a Hibernate API contract,
or redeclare one of its methods. The validator recognizes provider SPI by an
`spi` package component or a direct `@SPI` annotation. This source-sensitive
allowance lets a provider compose its own supported contract from Hibernate's
stable API; it does not make the Hibernate API an implementation extension
point for ordinary provider classes. Extending, implementing, or overriding a
Hibernate SPI still requires the target contract to declare `IMPLEMENT`.
=== Reviewing internal-use warnings
An internal-use warning is never a compatibility promise. It means the
provider has chosen to depend on an implementation detail which may change in
any release. The preferred response is to migrate to a documented API or SPI
and make the warning disappear.
Hibernate's community Dialects are checked with the same provider-boundary
engine. Their remaining internal-use warnings stay visible in the generated
report and carry the same lack of compatibility guarantees. The published
Gradle plugin intentionally has no allowlist or suppression mechanism.
Common supported migrations include:
* use `org.hibernate.jdbc.spi.JdbcExceptionHelper` to inspect a JDBC exception
chain instead of importing the former internal utility;
* select complete vendor profiles through
`TemporaryTableStrategies` instead of importing vendor implementations from
`org.hibernate.dialect.temptable.internal`; and
* use the focused translator operations described below instead of naming
internal SQL AST expression or selection implementations.
For Maven, Ant, or intentionally manual test-kit use, expose one
provider-owned JUnit test factory:
[source,java,indent=0]
----
include::{provider-fixture-dir}/ManualDialectContractTestExample.java[tags=contract-suite]
----
The required contracts cover connectionless bootstrap, basic select and DML
translation, identifier and literal rendering, JDBC parameter order, tableless
and synthetic roots, and schema DDL. Optional contracts cover pagination,
locking, temporary tables, and multi-table mutation. A required contract cannot
be skipped. Mark an optional contract inapplicable only with a nonblank reason.
These tests verify internal consistency and provider integration. They do not
certify SQL by executing it against a database. Keep live-database and container
tests in the provider's own test matrix.
== Provider-specific assertions
Use `DialectTestKit.openContext(profile)` for behavior unique to the provider:
[source,java,indent=0]
----
include::{provider-fixture-dir}/ExampleDialectContractTest.java[tags=provider-assertion]
----
The context is thread-confined and must be closed. `translate()` accepts named
parameters, optional pagination, and a whole-query lock mode. Results are
immutable and include every generated statement and JDBC parameter position.
Positional HQL parameters and alias-specific lock modes are intentionally
outside this initial contract.
== Packaging and compatibility workflow
Before publishing a provider release:
. compile against the oldest and newest supported Hibernate versions;
. run the generic contract profile on each version;
. run provider-specific SQL assertions;
. run the provider's live database matrix;
. inspect deprecation, incubation, SPI, and migration reports;
. document the exact Hibernate and database versions supported.
Do not shade Hibernate Core, expose `.internal` types in provider signatures, or
copy Hibernate implementation classes into the provider artifact.
The Gradle validator reads
`https://docs.hibernate.org/orm/X.Y/metadata/classifications.json.gz`, where
`X.Y` is the resolved Core family. It authenticates the gzip bytes with the
adjacent SHA-256 file. Use `classificationMetadataFile` for an unpublished
family or an online-independent build, and populate the Gradle cache online
before using `--offline`. A plugin/Core family mismatch is an error; exact
maintenance versions within one family need not be identical.
== Troubleshooting
Connection requested during profile boot:: Remove metadata-dependent settings
and resolve provider configuration before inherited type registration.
Unknown HQL entity:: Use the fixed `ContractEntity` model in test-kit requests;
provider mappings are not installed in the generic context.
Parameter order mismatch:: Inspect `GeneratedParameter.jdbcPosition()` rather
than counting `?` characters; a Dialect may expand or add internal binders.
Unexpected SQL family:: Identify the supplying Dialect method and test the
focused strategy before replacing a translator.
`INTERNAL_TARGET` warning:: Replace the upstream `.internal` dependency with a documented
API/SPI contract; moving provider code into a package named `internal` does not
change ownership. The warning means the dependency has no compatibility
guarantee across releases.
`MISSING_IMPLEMENT_ROLE` error:: Extend, implement, or override a Hibernate SPI only when it
is classified with `IMPLEMENT`. A provider SPI may compose a Hibernate API,
but an ordinary provider implementation may not treat API visibility as
subclassing or implementation permission.
Offline metadata miss:: Run once online or configure
`classificationMetadataFile` with a locally generated or mirrored family file.
Live database accepts different SQL:: Keep the database result as the final
authority and add a focused provider assertion plus a live integration test.
---
### Documentation Src Main Asciidoc Dialect Index (`documentation/src/main/asciidoc/dialect/index.adoc`)
include::{root-project-dir}/.asciidoctorconfig.adoc[]
:doctype: book
:icons: font
:html-meta-canonical-link: https://docs.hibernate.org/stable/orm/dialect/
= Dialects
:toc2:
:toclevels: 1
:sectanchors:
A dialect is a class that provides information about the specifics of a database and translators for the SQL dialect of the database.
This guide catalogs available Dialects. Authors and maintainers of external
Dialect implementations should use the link:{doc-dialect-provider-url}[Dialect Provider Guide].
The link:{doc-spi-url}[SPI and Service Provider Guide] defines the general
provider-role and compatibility model used by that guide.
== Supported dialects
Hibernate ORM supports a wide range of dialects out of the box.
Usually, Hibernate supports at least the database version that is also still supported by the respective vendor.
In many cases though, Hibernate supports even older versions of the databases,
but the support for these versions is not guaranteed.
Below is a list of supported dialects and the minimum required version of the database.
include::{generated-report-dir}/dialect/dialect-table.adoc[]
[[third-party-dialects]]
== Third-party dialects
Third-parties publish additional dialects for Hibernate ORM, providing their own support for more databases, or extended support beyond what is built in Hibernate ORM.
These dialects are not directly supported by the Hibernate team:
* The Hibernate ORM CI does not run any test against these dialects, the dialect's authors have their own test suite.
* The Hibernate team will not address issues reported against these dialect, but the dialect's authors have their own issue tracker.
[NOTE]
====
Third-party dialects may not be compatible with all versions of Hibernate ORM.
Check the dialect's own documentation to know more about its compatibility constraints.
The https://hibernate.org/orm/releases/#compatibility-matrix[compatibility matrix on the Hibernate website] may also be of help.
====
Below is a list of third-party dialects with links to relevant websites.
[cols="a,a", options="header"]
|===
|Dialect |Website
|MongoDB| https://github.com/mongodb/mongo-hibernate/[MongoDB extension for Hibernate ORM]
|Google Spanner| https://github.com/GoogleCloudPlatform/google-cloud-spanner-hibernate[Google Cloud Spanner Dialect for Hibernate ORM]
|===
[[community-dialects]]
== Community dialects
Community dialects are not included in `org.hibernate.orm:hibernate-core` and require an additional dependency to `org.hibernate.orm:hibernate-community-dialects`.
These dialects are not directly supported by the Hibernate team:
* The Hibernate ORM CI does not run any test against these dialects.
* The Hibernate team will not address issues reported against these dialect.
Instead, the dialects are maintained on a best-effort basis by vendors or individuals.
Below is a list of community dialects and the minimum required version of the database.
include::{generated-report-dir}/dialect/dialect-table-community.adoc[]
[NOTE]
====
Community dialects were introduced in Hibernate ORM 6.0.
The `hibernate-core` artifact had many legacy dialects before 6.0 that were only tested and maintained on a best effort basis.
More and more database vendors requested to integrate a dialect for their database and even provided a PR with a dialect,
but the Hibernate team didn't want to add new dialects for databases that might not have a wide adoption
or any automated testing into the `hibernate-core` artifact. Even though the dialect was supposedly maintained by the vendor,
the Hibernate team was burdened with reviewing questions, issues and PRs that relate to these dialects.
To give database vendors and the community a clear way forward, the Hibernate team decided to introduce a new artifact,
called `hibernate-community-dialects` which is the new home for dialects that are maintained by vendors or individuals.
Moving forward, the `hibernate-core` artifact will only contain dialects that are supported and tested by the Hibernate team.
All the legacy dialects were moved to the `hibernate-community-dialects` artifact to have a clear separation based on the quality of the dialect.
====
== Requirements for moving from `hibernate-community-dialects` to `hibernate-core`
If a database vendor wants their database dialect to be included in the `hibernate-core` artifact,
several requirements have to be fulfilled:
* The vendor must provide access to a dedicated database server that can be used for testing
* The vendor must provide contact details to at least one employee who is mainly responsible for the maintenance of the dialect
* The responsible employee of the vendor must actively monitor and react to failures of the testsuite against the respective database
* The responsible employee of the vendor must ensure the testsuite is configured correctly in order for it to succeed on the respective database
* If the responsible employee of the vendor leaves the company, the vendor must provide contact details to a new responsible employee
In case the responsible employee is unreachable for a longer period or issues with the dialect are not attended to in a timely manner,
the Hibernate team will move the dialect back to the `hibernate-community-dialects` artifact.
The requirements for the database server are:
* JDK 17 installed
* Git installed
* Access to the database through non-confidential credentials
* Access via SSH through confidential credentials
Get in touch with the Hibernate team on https://hibernate.zulipchat.com/#narrow/stream/132096-hibernate-user[Zulip]
if you want to request the move of your dialect to hibernate-core.
---
### Documentation Src Main Asciidoc Integrationguide Credits (`documentation/src/main/asciidoc/integrationguide/credits.adoc`)
[[credits]]
== Credits
The full list of contributors to Hibernate ORM can be found on the
https://github.com/hibernate/hibernate-orm/graphs/contributors[GitHub repository].
The following contributors were involved in this documentation:
* Steve Ebersole
* Vlad Mihalcea
---
### Documentation Src Main Asciidoc Integrationguide Index (`documentation/src/main/asciidoc/integrationguide/index.adoc`)
= Hibernate ORM Integration Guide
:toc2:
:toclevels: 3
:sectanchors:
:html-meta-canonical-link: https://docs.hibernate.org/stable/orm/integrationguide/html_single/
include::preface.adoc[]
:numbered:
include::chapters/services/Services.adoc[]
include::credits.adoc[]
---
### Documentation Src Main Asciidoc Integrationguide Preface (`documentation/src/main/asciidoc/integrationguide/preface.adoc`)
[[preface]]
== Preface
Hibernate provides many integration points that allow integrating with new capabilities or supplying custom behavior for standard capabilities. This guide covers these integration points and is intended for software developers and architects who will be
- integrating Hibernate with Java EE application servers, Spring framework, caching solutions (e.g. Infinispan, Ehcache, Hazelcast),
- supplying custom integrations, or
- want to override standard capabilities
---
### Documentation Src Main Asciidoc Introduction Advanced (`documentation/src/main/asciidoc/introduction/Advanced.adoc`)
[[advanced]]
== Advanced Topics
In the last chapter of this Introduction, we turn to some topics that don't really belong in an introduction.
Here we consider some problems, and solutions, that you're probably not going to run into immediately if you're new to Hibernate.
But we do want you to know _about_ them, so that when the time comes, you'll know what tool to reach for.
[[filters]]
=== Filters
_Filters_ are one of the nicest and under-usedest features of Hibernate, and we're quite proud of them.
A filter is a named, globally-defined, parameterized restriction on the data that is visible in a given session.
Examples of well-defined filters might include:
- a filter that restricts the data visible to a given user according to row-level permissions,
- a filter which hides data which has been soft-deleted,
- in a versioned database, a filter that displays versions which were current at a given instant in the past, or
- a filter that restricts to data associated with a certain geographical region.
A filter must be declared somewhere.
A package descriptor or a module descriptor is as good a place as any for a link:{doc-javadoc-url}org/hibernate/annotations/FilterDef.html[`@FilterDef`]:
[source,java]
----
@FilterDef(name = "ByRegion",
parameters = @ParamDef(name = "region", type = String.class))
package org.hibernate.example;
----
This filter has one parameter.
Fancier filters might in principle have multiple parameters, though we admit this must be quite rare.
[IMPORTANT]
====
In container environments with <>, annotated packages/modules are auto-discovered.
In other environments, to let Hibernate know about the annotated packages/modules:
* If you're using `Configuration` to configure Hibernate, use `Configuration.addPackage()`/`Configuration.addModule()`.
* If you're using `MetadataSources` directly, use `MetadataSources.addPackage()`/`MetadataSources.addModule()`.
====
_Typically_, but not necessarily, a `@FilterDef` specifies a default restriction:
[source,java]
----
@FilterDef(name = "ByRegion",
parameters = @ParamDef(name = "region", type = String.class),
defaultCondition = "region = :region")
package org.hibernate.example;
----
Note that filter restrictions are always written in the native SQL dialect of the database, _not_ in HQL.
The restriction must contain a reference to the parameter of the filter, specified using the usual syntax for named parameters.
Any entity or collection which is affected by a filter must be annotated link:{doc-javadoc-url}org/hibernate/annotations/Filter.html[`@Filter`]:
[source,java]
----
@Entity
@Filter(name = example_.BY_REGION)
class User {
@Id String username;
String region;
...
}
----
Here, as usual, `example_.BY_REGION` is generated by Hibernate Processor, and is just a constant with the value `"ByRegion"`.
If the `@Filter` annotation does not explicitly specify a restriction, the default restriction given by the `@FilterDef` is applied to the entity.
But an entity is free to override the default condition.
[source,java]
----
@Entity
@Filter(name = example_.FILTER_BY_REGION, condition = "name = :region")
class Region {
@Id String name;
...
}
----
Note that the restriction specified by the `condition` or `defaultCondition` is a native SQL expression.
.Annotations for defining filters
[%breakable,cols="25,~"]
|===
| Annotation | Purpose
| `@FilterDef` | Defines a filter and declares its name (exactly one per filter)
| `@Filter` | Specifies how a filter applies to a given entity or collection (many per filter)
|===
[TIP]
====
A filter `condition` may not specify joins to other tables, but it may contain a subquery.
[source,java]
----
@Filter(name="notDeleted"
condition="(select r.deletionTimestamp from Record r where r.id = record_id) is not null")
----
Only unqualified column names like `record_id` in this example are interpreted as belonging to the table of the filtered entity.
====
By default, a new session comes with every filter disabled.
A filter must be explicitly enabled when the session is created, and arguments must be assigned to its parameters.
One way to do this is using a session creation option:
[source,java]
----
import org.hibernate.SessionCreationOption.EnabledFilter;
...
var enabledFilter =
new EnabledFilter(example_.FILTER_BY_REGION,
// argument to the filter parameter
Map.of("region", "es"));
try (var session = factory.createEntityManager(enabledFilter)) {
var document =
// read the version of the document
// effective at the specified instant
session.find(Document.class, documentId);
...
}
----
// A filter may be explicitly enabled in a given session by calling link:{doc-javadoc-url}org/hibernate/Session.html#enableFilter(java.lang.String)[`enableFilter()`] and assigning arguments to the parameters of the filter using the returned instance of link:{doc-javadoc-url}org/hibernate/Filter.html[`Filter`].
// You should do this right at the _start_ of the session.
//
// [source,java]
// ----
// sessionFactory.inTransaction(session -> {
// session.enableFilter(example_.FILTER_BY_REGION)
// .setParameter("region", "es")
// .validate();
//
// ...
// });
// ----
Now, any queries executed within the session will have the filter restriction applied.
Collections annotated `@Filter` will also have their members correctly filtered.
[NOTE]
====
On the other hand, by default, filters are not applied to `@ManyToOne` associations, nor to `find()`.
This is completely by design and is not in any way a mistake.
The default behavior may be overridden using `@FilterDef(applyToLoadByKey=true)`.
====
More than one filter may be enabled in a given session.
Alternatively, since Hibernate 6.5, a filter may be declared as `autoEnabled` in every session.
In this case, the argument to a filter parameter must be obtained from a `Supplier`.
[source,java]
----
@FilterDef(name = "ByRegion",
autoEnabled = true,
parameters = @ParamDef(name = "region", type = String.class,
resolver = RegionSupplier.class),
defaultCondition = "region = :region")
package org.hibernate.example;
----
It's not necessary to call `enableFilter()` for a filter declared `autoEnabled = true`.
[TIP]
====
When we only need to filter rows by a static condition with no parameters, we don't need a filter, since link:{doc-javadoc-url}org/hibernate/annotations/SQLRestriction.html[`@SQLRestriction`] provides a much simpler way to do that.
====
:envers: https://hibernate.org/orm/envers/
:envers-doc: {doc-user-guide-url}#envers
We've mentioned that a filter can be used to implement versioning, and to provide _historical_ views of the data.
But Hibernate 7.4 introduces two much more powerful ways of dealing with historical data.
[[temporal-data]]
=== Temporal data
A _temporal entity_ is an entity that keeps a history of its state over time, allowing the database to be queried for state which was effective at a given moment in the past.
The link:{doc-javadoc-url}org/hibernate/annotations/Temporal.html[`@Temporal`] annotation declares a temporal entity.
[source,java]
----
@Temporal @Entity
class Document {
...
}
----
Any temporal entity has columns holding:
- the moment at which a particular version of the entity became effective, and
- the moment, if any, at which it the version is superseded (this is null for the currently-effective version).
[source,java]
----
@Temporal(rowStart="effective",
rowEnd="superseded")
@Entity
class Document {
...
}
----
Hibernate offers several different strategies for mapping temporal entities,
enumerated by link:{doc-javadoc-url}org/hibernate/temporal/TemporalTableStrategy.html[`TemporalTableStrategy`].
.Temporal table strategies
[%breakable,cols="15,25,~"]
|===
| Strategy | Explanation | Comments
| `NATIVE` | Use ANSI SQL 2011-style temporal tables
| Requires native database support for temporal tables (Maria, SQL Server, Db2)
| `SINGLE_TABLE` | Store historical data together with current data in one table
| The table does not have the usual foreign key constraints that would exist for any non-temporal entity, and so it is the responsibility of the application program to maintain and enforce referential integrity
| `HISTORY_TABLE` | Maintain two tables, one for current data and one for historical data
| The table for current data has all the usual foreign key constraints that would exist for any non-temporal entity; the table for historical data has no foreign key constraints
|===
The temporal table strategy is controlled by the following property setting:
.Temporal data configuration
[%breakable,cols="36,~"]
|===
| Configuration property name | Purpose
| link:{doc-javadoc-url}org/hibernate/cfg/StateManagementSettings.html#TEMPORAL_TABLE_STRATEGY[`hibernate.temporal.table_strategy`] | Specifies the `TemporalTableStrategy`
|===
In the `SINGLE_TABLE` strategy, the `@HistoryPartitioning` annotation allows historical data to be shifted to a separate partition.
[source,java]
----
@Temporal @Entity
@Table(name="documents")
@Temporal.HistoryPartitioning(
currentPartition="doc_current",
historyPartition="doc_history")
class Document {
...
}
----
In the `HISTORY_TABLE` strategy, the `@HistoryTable` annotation specifies the name of the table holding the historical data.
[source,java]
----
@Temporal @Entity
@Table(name="documents")
@Temporal.HistoryTable(name="document_history")
class Document {
...
}
----
By default, a session or stateless session reads the currently effective version of any temporal entity.
To read historical versions effective at a given instant, we must specify the instant when creating the session or stateless session.
[source,java]
----
import org.hibernate.SessionCreationOption.EffectiveAt;
...
Instant instant = ... ; // a past instant
try (var session = factory.createEntityManager(new EffectiveAt(instant))) {
var document =
// read the version of the document
// effective at the specified instant
session.find(Document.class, documentId);
...
}
----
A temporal entity tracks its state as it changes over time, but it doesn't keep any record of the _changes themselves_, nor about how modifications to the temporal entity relate to other modifications as part of a _changeset_ involving multiple entities.
For this we need an audit log.
[[audit-logs]]
=== Audit logs
An _audited entity_ is quite similar to a temporal entity with a separate history table.
But whereas a history table only tracks the timestamp at which a version became effective, an _audit log_ keeps a record of each changeset and something about the nature of the change.
The link:{doc-javadoc-url}org/hibernate/annotations/Audited.html[`@Audited`] annotation declares an audited entity.
[source,java]
----
@Audited @Entity
class Document {
...
}
----
The `@Audited.Table` annotation specified the table holding the audit log for that entity:
[source,java]
----
@Audited @Entity
@Table(name="documents")
@Audited.Table(name="document_aud_log")
class Document {
...
}
----
An audit log is organized around changeset identifiers instead of timestamps.
Each audit log table has columns holding:
- an id of the changeset at which a revision of the entity became effective,
- the nature of the change to entity that resulted in the revision being created--that is, the `ModificationType`,
and
- optionally, an id of the changeset which resulted in the revision being superseded.
[source,java]
----
@Audited @Entity
@Table(name="documents")
@Audited.Table(
name="document_aud_log",
changesetIdColumn="REV",
modificationTypeColumn="REVTYPE")
class Document {
...
}
----
NOTE: In the past, audit logging was provided by {envers}[Envers].
The functionality underlying the `@Audited` annotation is completely new, but is backward compatible with the format of Envers audit logs.
To make use of audited entities, we need a source of changeset ids.
There are two approaches we could take:
1. create an entity class which holds information about each changeset, and annotate it link:{doc-javadoc-url}org/hibernate/annotations/Changelog.html[`@Changelog`] or,
2. supply our own custom implementation of link:{doc-javadoc-url}org/hibernate/temporal/spi/ChangesetIdentifierSupplier.html[`ChangesetIdentifierSupplier`] to assign changeset ids to transactions.
With the first (recommended) approach, Hibernate automatically persists a new instance of the `@Changelog` entity in each transaction, using the `@ChangesetId` field--typically the generated identifier of the entity--as the changeset id.
[source,java]
----
@Changelog @Entity
@Table(name = "REVINFO")
static class ChangesetInfo {
@Id
@GeneratedValue
@Changelog.ChangesetId
@Column(name = "REV")
int id;
@Changelog.Timestamp
@Column(name = "REVTSTMP")
long timestamp;
@Basic(optional=false)
String description;
}
----
Notice that the changelog entity is much more than a source of ids.
It also stores information about each changeset, including the moment at which the change occurred.
For those familiar with Envers, the changelog entity fills the role of the Envers "revision entity".
A typical custom changelog entity helps answer questions like "who?", "why?", and "when?".
.Audit log configuration
[%breakable,cols="36,~"]
|===
| Configuration property name | Purpose
| link:{doc-javadoc-url}org/hibernate/cfg/StateManagementSettings.html#CHANGESET_ID_SUPPLIER[`hibernate.temporal.changeset_id_supplier`] | Specify a custom `ChangesetIdentifierSupplier`
| link:{doc-javadoc-url}org/hibernate/cfg/StateManagementSettings.html#AUDIT_STRATEGY[`hibernate.audit.strategy`] | Specifies whether there is a column holding the id of the changeset which superseded a revision
|===
By default, a session or stateless session reads the currently effective version of an audited entity and ignores the audit log.
To read historical reversions, we must specify a changeset id when creating the session or stateless session.
[source,java]
----
import org.hibernate.SessionCreationOption.EffectiveChangeset;
...
Long changesetId = ... ; // a changeset id
try (var session = factory.createEntityManager(new EffectiveChangeset(changesetId))) {
var document =
// read the reversion of the document
// effective after the specified changeset
session.find(Document.class, documentId);
}
----
The link:{doc-javadoc-url}org/hibernate/audit/AuditLog.html[`AuditLog`] interface lets us run more sophisticated queries against the audit log:
[source,java]
----
try (var auditLog = AuditLogFactory.create(factory)) {
for (var changesetId : auditLog.getChangesets(Document.class, documentId)) {
// iterate over the changesets which modified the given document
try (var session = factory.createEntityManager(new EffectiveChangeset(changesetId))) {
...
}
}
}
----
For even more control, we can open a session with `ALL_CHANGESETS` and write custom HQL queries using the `changesetId()` and `modificationType()` functions:
[source,java]
----
try (var session = factory.createEntityManager(new EffectiveChangeset(AuditLog.ALL_CHANGESETS))) {
// find all documents deleted in a specific changeset
var deleted = session.createQuery(
"from Document d"
+ " where changesetId(d) = :csId"
+ " and modificationType(d) = :type",
Document.class)
.setParameter("csId", targetChangesetId)
.setParameter("type", ModificationType.DEL)
.getResultList();
// count modifications per changeset
var counts = session.createQuery(
"select changesetId(d), count(d)"
+ " from Document d"
+ " group by changesetId(d)"
+ " order by changesetId(d)",
Object[].class)
.getResultList();
}
----
You'll find much more information about these new APIs in the Javadoc.
// [[envers]]
// .Using Envers for auditing historical data
// ****
// Envers is an add-on to Hibernate ORM which keeps a historical record of each versioned entity in a separate _audit table_, and allows past revisions of the data to be viewed and queried.
// A full introduction to Envers would require a whole chapter, so we'll just give you a quick taste here.
//
// First, we must mark an entity as versioned, using the `@Audited` annotation:
// [source,java]
// ----
// @Audited @Entity
// @Table(name="CurrentDocument")
// @AuditTable("DocumentRevision")
// class Document { ... }
// ----
// [TIP]
// ====
// The `@AuditTable` annotation is optional, and it's better to set either `org.hibernate.envers.audit_table_prefix` or `org.hibernate.envers.audit_table_suffix` and let the audit table name be inferred.
// ====
// The `AuditReader` interface exposes operations for retrieving and querying historical revisions.
// It's really easy to get hold of one of these:
// [source,java]
// ----
// AuditReader reader = AuditReaderFactory.get(entityManager);
// ----
// Envers tracks revisions of the data via a global _revision number_.
// We may easily find the revision number which was current at a given instant:
// [source,java]
// ----
// Number revision = reader.getRevisionNumberForDate(datetime);
// ----
// We can use the revision number to ask for the version of our entity associated with the given revision number:
// [source,java]
// ----
// Document doc = reader.find(Document.class, id, revision);
// ----
// Alternatively, we can directly ask for the version which was current at a given instant:
// [source,java]
// ----
// Document doc = reader.find(Document.class, id, datetime);
// ----
// We can even execute queries to obtain lists of entities current at the given revision number:
// [source,java]
// ----
// List documents =
// reader.createQuery()
// .forEntitiesAtRevision(Document.class, revision)
// .getResultList();
// ----
// For much more information, see the {envers-doc}[User Guide].
// ****
//
// Historically, filters where often used to implement soft-delete.
// But, since 6.4, Hibernate now comes with soft-delete built in.
Sometimes, keeping a full record of past revisions of an entity is too much.
[[soft-delete]]
=== Soft-delete
:soft-delete-doc: {doc-user-guide-url}#soft-delete
Even when we don't need complete historical versioning, we often prefer to "delete" a row by marking it as obsolete using a SQL `update`, rather than by executing an actual SQL `delete` and removing the row from the database completely.
The link:{doc-javadoc-url}org/hibernate/annotations/SoftDelete.html[`@SoftDelete`] annotation controls how this works:
[source,java]
----
@Entity
@SoftDelete(columnName = "deleted",
converter = TrueFalseConverter.class)
class Draft {
...
}
----
The `columnName` specifies a column holding the deletion status, and the `converter` is responsible for converting a Java `Boolean` to the type of that column.
In this example, link:{doc-javadoc-url}org/hibernate/type/TrueFalseConverter.html[`TrueFalseConverter`] sets the column to the character `'F'` initially, and to `'T'` when the row is deleted.
Any JPA `AttributeConverter` for the Java `Boolean` type may be used here.
Built-in options include link:{doc-javadoc-url}org/hibernate/type/NumericBooleanConverter.html[`NumericBooleanConverter`] and link:{doc-javadoc-url}org/hibernate/type/YesNoConverter.html[`YesNoConverter`].
Much more information about soft delete is available in the {soft-delete-doc}[User Guide].
Another feature that you _could_ use filters for, but now don't need to, is multi-tenancy.
[[multitenancy]]
=== Multi-tenancy
:multitenacy-doc: {doc-user-guide-url}#multitenacy
A _multi-tenant_ database is one where the data is segregated by _tenant_.
We don't need to actually define what a "tenant" really represents here; all we care about at this level of abstraction is that each tenant may be distinguished by a unique identifier.
And that there's a well-defined _current tenant_ in each session.
We may specify the current tenant when we open a session:
// [source,java]
// ----
// var session =
// sessionFactory.withOptions()
// .tenantIdentifier(tenantId)
// .openSession();
// ----
//
// Or, when using JPA-standard APIs:
[source,java]
----
import org.hibernate.SessionCreationOption.TenantId;
...
try (var entityManager = factory.createEntityManager(new TenantId(tenantId))) {
...
}
----
However, since we often don't have this level of control over creation of the session, it's more common to supply an implementation of link:{doc-javadoc-url}org/hibernate/context/spi/CurrentTenantIdentifierResolver.html[`CurrentTenantIdentifierResolver`] to Hibernate.
To make use of multi-tenancy, we'll usually need to set at least one of these configuration properties:
.Multi-tenancy configuration
[%breakable,cols="36,~"]
|===
| Configuration property name | Purpose
| link:{doc-javadoc-url}org/hibernate/cfg/MultiTenancySettings.html#MULTI_TENANT_IDENTIFIER_RESOLVER[`hibernate.tenant_identifier_resolver`] | Specifies the `CurrentTenantIdentifierResolver`
| link:{doc-javadoc-url}org/hibernate/cfg/MultiTenancySettings.html#MULTI_TENANT_SCHEMA_MAPPER[`hibernate.multi_tenant.schema_mapper`] | Specifies the `TenantSchemaMapper` for schema-based multi-tenancy
| link:{doc-javadoc-url}org/hibernate/cfg/MultiTenancySettings.html#MULTI_TENANT_CREDENTIALS_MAPPER[`hibernate.multi_tenant.credentials_mapper`] | Specifies the `TenantCredentialsMapper` for schema-based or discriminator-based multi-tenancy
| link:{doc-javadoc-url}org/hibernate/cfg/MultiTenancySettings.html#MULTI_TENANT_CONNECTION_PROVIDER[`hibernate.multi_tenant_connection_provider`] | Specifies the `MultiTenantConnectionProvider` for database-based multi-tenancy
| link:{doc-javadoc-url}org/hibernate/cfg/MultiTenancySettings.html#MULTI_TENANT_RLS_ENABLED[`hibernate.multi_tenant.rls_enabled`] | When `false`, disables enforcement of discriminator-based multi-tenancy via database-native row-level security
|===
// Do not configure those properties if you would like the configured `BeanContainer` provide the implementation.
There are three common approaches to multi-tenancy:
1. each tenant has its own database,
2. each tenant has its own schema, or
3. tenants share tables in a single schema, and rows are tagged with the tenant id.
[discrete]
==== Database-based multi-tenancy
The first option is to give each tenant its own database.
That is, we'll use a separate source of JDBC connections for each tenant.
The interface link:{doc-javadoc-url}org/hibernate/engine/jdbc/connections/spi/MultiTenantConnectionProvider.html[`MultiTenantConnectionProvider`] is responsible for obtaining an appropriate `Connection` for a given tenant.
Typically, we'll provide a custom implementation of this interface:
- from time to time, Hibernate will ask for a connection, passing the id of the current tenant, and then we must create an appropriate connection or obtain one from a pool, and return it to Hibernate, and
- later, Hibernate will release the connection and ask us to destroy it or return it to the appropriate pool.
[TIP]
====
Check out link:{doc-javadoc-url}org/hibernate/engine/jdbc/connections/spi/DataSourceBasedMultiTenantConnectionProviderImpl.html[`DataSourceBasedMultiTenantConnectionProviderImpl`] for inspiration.
If your source of JDBC connections is a set of JNDI-bound ``DataSource``s, you might even be able to use this implementation directly.
====
[discrete]
==== Schema-based multi-tenancy
The second option is to keep all the data for different tenants in the same database, giving each tenant a different named database schema with its own set of tables.
- If all tenants connect to the database using the same credentials, we must supply a link:{doc-javadoc-url}org/hibernate/context/spi/TenantSchemaMapper.html[`TenantSchemaMapper`] which is responsible for mapping tenant ids to schema names.
- If each tenant should use distinct credentials to connect to the database, and if your JDBC `DataSource` supports this (not all do!) then we can use a link:{doc-javadoc-url}org/hibernate/context/spi/TenantCredentialsMapper.html[`TenantCredentialsMapper`] to supply the username and password of each tenant.
If each database user has a different default schema, we might not need a `TenantSchemaMapper`.
[discrete]
==== Discriminator-based multi-tenancy
The third option is quite different.
In this case we store data from all tenants in the same tables, but each table has a dedicated column holding the tenant id mapped by each of our entities.
[source,java]
----
@Entity
class Account {
@Id String id;
@TenantId String tenantId;
...
}
----
The link:{doc-javadoc-url}org/hibernate/annotations/TenantId.html[`@TenantId`] annotation is used to indicate an attribute of an entity which holds the tenant id.
Within a given session, our data is automatically filtered so that only rows tagged with the tenant id of the current tenant are visible in that session.
Since Hibernate 8.0, the visibility rules for discriminator-based multi-tenancy are enforced by the database itself on platforms with built-in support for row-level security.
Hibernate automatically generates DDL with the necessary row-level security constraints.
This feature is enabled by default, but may be disabled by setting `hibernate.multi_tenant.rls_enabled=false`.
Here there are two options:
- when a `TenantCredentialsMapper` is supplied via `hibernate.multi_tenant.credentials_mapper`, the tenant id must represent the authenticated database user, and row-level ownership is tied to the current database user, or
- otherwise, when no `TenantCredentialsMapper` is supplied, a transaction-local or session variable is set to the value of the tenant id, and row-level ownership is tied to the value of this variable.
The first option is more secure, but does not work will with some connection pools.
[CAUTION]
====
On databases which don't support row-level security, or when row-level security is disabled, native SQL queries are _not_ automatically filtered by tenant id.
We must add the tenant filtering by hand.
====
[[read-only-replicas]]
=== Read-only replicas
A similar but distinct problem is accessing data held in a read-only replica of the main production database.
One way to handle this problem is to simply instantiate two instances of `SessionFactory`:
- read-only transactions use a `SessionFactory` configured to access the read-only replica, while
- other transactions use the `SessionFactory` configured to read from and write to the main database.
[CAUTION]
====
The second-level cache doesn't play well with replication, and so a `SessionFactory` with access to a read-only replica should be configured with the second-level cache disabled.
====
Alternatively, Hibernate 7.2 introduces experimental support for accessing replicas via a single instance of `SessionFactory`.
A `Session` which accesses a read-only replica must be created in a special read-only mode:
[source,java]
----
Session readOnlySession =
factory.withOptions()
.readOnly(true)
.initialCacheMode(CacheMode.IGNORE)
.openSession();
----
There are now two possibilities.
- Some JDBC drivers (MySQL) are able to automatically direct read-only sessions to the read-only replica.
In this case, there's no more work to do, since Hibernate will automatically call `Connection.setReadOnly(true)` to signal to the JDBC driver that the read-only replica may be used.
- Other drivers (Postgres, Oracle) don't feature any special support for read-only replicas, and in this case we need to supply our own custom link:{doc-javadoc-url}/org/hibernate/engine/jdbc/connections/spi/ConnectionProvider.html[`ConnectionProvider`] or link:{doc-javadoc-url}/org/hibernate/engine/jdbc/connections/spi/MultiTenantConnectionProvider.html[`MultiTenantConnectionProvider`] and implement link:{doc-javadoc-url}/org/hibernate/engine/jdbc/connections/spi/ConnectionProvider.html#getReadOnlyConnection()[`getReadOnlyConnection()`] to return a connection to the read-only replica.
Notice that we created the read-only session with link:{doc-javadoc-url}/org/hibernate/CacheMode.html#IGNORE[`CacheMode.IGNORE`], indicating that access to the read-only replica should <>.
There's two different phenomena we need to consider here:
1. A read-only replica might contain stale data which has already been updated or deleted from the main database and invalidated in the second-level cache.
A read-only session might read this stale data and recache it, exposing the stale data to subsequent sessions.
Use of `CacheMode.GET` in a read-only session prevents this phenomenon.
2. A session might read data which has not yet been replicated from the main database and add it to the second-level cache.
If a read-only session reads this data from the cache, it might fail to resolve references to other data which has not yet been replicated.
Use of `CacheMode.PUT` in a read-only session prevents this phenomenon.
Use of `CacheMode.IGNORE` in a read-only session prevents both phenomena.
[CAUTION]
====
The first issue is objectively more serious than the second, and the second issue can often be avoided by careful programming by someone _who really understands what they're doing_.
We do not, therefore, require the use of `CacheMode.IGNORE`, but we strongly encourage the use of _at least_ `CacheMode.GET` in every read-only session.
====
[[custom-sql]]
=== Using custom-written SQL
We've already discussed how to run <>, but occasionally that's not enough.
Sometimes—but much less often than you might expect—we would like to customize the SQL used by Hibernate to perform basic CRUD operations for an entity or collection.
For this we can use link:{doc-javadoc-url}org/hibernate/annotations/SQLInsert.html[`@SQLInsert`] and friends:
[source,java]
----
@Entity
@SQLInsert(sql = "insert into person (name, id, valid) values (?, ?, true)",
verify = Expectation.RowCount.class)
@SQLUpdate(sql = "update person set name = ? where id = ?")
@SQLDelete(sql = "update person set valid = false where id = ?")
@SQLSelect(sql = "select id, name from person where id = ? and valid = true")
public static class Person { ... }
----
.Annotations for overriding generated SQL
[%breakable,cols="25,~"]
|===
| Annotation | Purpose
| link:{doc-javadoc-url}org/hibernate/annotations/SQLSelect.html[`@SQLSelect`] | Overrides a generated SQL `select` statement
| link:{doc-javadoc-url}org/hibernate/annotations/SQLInsert.html[`@SQLInsert`] | Overrides a generated SQL `insert` statement
| link:{doc-javadoc-url}org/hibernate/annotations/SQLUpdate.html[`@SQLUpdate`] | Overrides a generated SQL `update` statement
| link:{doc-javadoc-url}org/hibernate/annotations/SQDelete.html[`@SQDelete`] | Overrides a generated SQL `delete` statement for a single row
| link:{doc-javadoc-url}org/hibernate/annotations/SQDeleteAll.html[`@SQDeleteAll`] | Overrides a generated SQL `delete` statement for multiple rows
| link:{doc-javadoc-url}org/hibernate/annotations/SQLRestriction.html[`@SQLRestriction`] | Adds a restriction to generated SQL
| link:{doc-javadoc-url}org/hibernate/annotations/SQLOrder.html[`@SQLOrder`] | Adds an ordering to generated SQL
|===
[TIP]
====
If the custom SQL should be executed via a `CallableStatement`, just specify `callable=true`.
====
Any SQL statement specified by one of these annotations must have exactly the number of JDBC parameters that Hibernate expects, that is, one for each column mapped by the entity, in the exact order Hibernate expects. In particular, the primary key columns must come last.
However, the `@Column` annotation does lend some flexibility here:
- if a column should not be written as part of the custom `insert` statement, and has no corresponding JDBC parameter in the custom SQL, map it `@Column(insertable=false)`, or
- if a column should not be written as part of the custom `update` statement, and has no corresponding JDBC parameter in the custom SQL, map it `@Column(updatable=false)`.
The `verify` member of these annotations specifies a class implementing `Expectation`, allowing customized logic for checking the success of an operation executed via JDBC.
There are three built-in implementations:
- `Expectation.None`, which performs no checks,
- `Expectation.RowCount`, which is what Hibernate usually uses when executing its own generated SQL,
- and `Expectation.OutParameter`, which is useful for checking an output parameter of a stored procedure.
You can write your own implementation of `Expectation` if none of these options is suitable.
[TIP]
====
If you need custom SQL, but are targeting multiple dialects of SQL, you can use the annotations defined in link:{doc-javadoc-url}org/hibernate/annotations/DialectOverride.html[`DialectOverride`].
For example, this annotation lets us override the custom `insert` statement just for PostgreSQL:
[source,java]
----
@DialectOverride.SQLInsert(dialect = PostgreSQLDialect.class,
override = @SQLInsert(sql="insert into person (name,id) values (?,gen_random_uuid())"))
----
It's even possible to override the custom SQL for specific _versions_ of a database.
====
Sometimes a custom `insert` or `update` statement assigns a value to a mapped column which is calculated when the statement is executed on the database.
For example, the value might be obtained by calling a SQL function:
[source,java]
----
@SQLInsert(sql = "insert into person (name, id) values (?, gen_random_uuid())")
----
But the entity instance which represents the row being inserted or updated won't be automatically populated with that value.
And so our persistence context loses synchronization with the database.
In situations like this, we may use the `@Generated` annotation to tell Hibernate to reread the state of the entity after each `insert` or `update`.
[[database-generated-columns]]
=== Handling database-generated columns
Sometimes, a column value is assigned or mutated by events that happen in the database, and aren't visible to Hibernate.
For example:
- a table might have a column value populated by a trigger,
- a mapped column might have a default value defined in DDL, or
- a custom SQL `insert` or `update` statement might assign a value to a mapped column, as we saw in the previous subsection.
One way to deal with this situation is to explicitly call `refresh()` at appropriate moments, forcing the session to reread the state of the entity.
But this is annoying.
The link:{doc-javadoc-url}org/hibernate/annotations/Generated.html[`@Generated`] annotation relieves us of the burden of explicitly calling `refresh()`.
It specifies that the value of the annotated entity attribute is generated by the database, and that the generated value should be automatically retrieved using a SQL `returning` clause, or separate `select` after it is generated.
A useful example is the following mapping:
[source,java]
----
@Entity
class Entity {
@Generated @Id
@ColumnDefault("gen_random_uuid()")
UUID id;
}
----
The generated DDL is:
[source,sql]
----
create table Entity (
id uuid default gen_random_uuid() not null,
primary key (uuid)
)
----
So here the value of `id` is defined by the column default clause, by calling the PostgreSQL function `gen_random_uuid()`.
When a column value is generated during updates, use `@Generated(event=UPDATE)`.
When a value is generated by both inserts _and_ updates, use `@Generated(event={INSERT,UPDATE})`.
[TIP]
====
For columns which should be generated using a SQL `generated always as` clause, prefer the link:{doc-javadoc-url}org/hibernate/annotations/GeneratedColumn.html[`@GeneratedColumn`] annotation, so that Hibernate automatically generates the correct DDL.
====
Actually, the `@Generated` and `@GeneratedColumn` annotations are defined in terms of a more generic and user-extensible framework for handling attribute values generated in Java, or by the database.
So let's drop down a layer, and see how that works.
[[user-defined-generators]]
=== User-defined generators
JPA doesn't define a standard way to extend the set of id generation strategies, but Hibernate does:
- the link:{doc-javadoc-url}org/hibernate/generator/Generator.html[`Generator`] hierarchy of interfaces in the package `org.hibernate.generator` lets you define new generators, and
- the link:{doc-javadoc-url}org/hibernate/annotations/IdGeneratorType.html[`@IdGeneratorType`] meta-annotation from the package `org.hibernate.annotations` lets you write an annotation which associates a `Generator` type with identifier attributes.
Furthermore, the link:{doc-javadoc-url}org/hibernate/annotations/ValueGenerationType.html[`@ValueGenerationType`] meta-annotation lets you write an annotation which associates a `Generator` type with a non-`@Id` attribute.
[NOTE]
// .The older APIs are still available in Hibernate 6
====
These APIs were new in Hibernate 6, and supersede the classic `IdentifierGenerator` interface and `@GenericGenerator` annotation from older versions of Hibernate.
However, the older APIs are still available and custom ``IdentifierGenerator``s written for older versions of Hibernate continue to work in Hibernate 7.
====
Hibernate has a range of built-in generators which are defined in terms of this new framework.
.Built-in generators
[%breakable,cols="20,25,~"]
|===
| Annotation | Implementation | Purpose
| link:{doc-javadoc-url}org/hibernate/annotations/Generated.html[`@Generated`] | `GeneratedGeneration` | Generically handles database-generated values
| link:{doc-javadoc-url}org/hibernate/annotations/GeneratedColumn.html[`@GeneratedColumn`] | `GeneratedAlwaysGeneration` | Handles values generated using `generated always`
| link:{doc-javadoc-url}org/hibernate/annotations/CurrentTimestamp.html[`@CurrentTimestamp`] | `CurrentTimestampGeneration` | Generic support for database or in-memory generation of creation or update timestamps
| link:{doc-javadoc-url}org/hibernate/annotations/CreationTimestamp.html[`@CreationTimestamp`] | `CurrentTimestampGeneration` | A timestamp generated when an entity is first made persistent
| link:{doc-javadoc-url}org/hibernate/annotations/UpdateTimestamp.html[`@UpdateTimestamp`] | `CurrentTimestampGeneration` | A timestamp generated when an entity is made persistent, and regenerated every time the entity is modified
| link:{doc-javadoc-url}org/hibernate/annotations/UuidGenerator.html[`@UuidGenerator`] | `UuidGenerator` | A more flexible generator for RFC 4122 UUIDs
|===
Furthermore, support for JPA's standard id generation strategies is also defined in terms of this framework.
As an example, let's look at how link:{doc-javadoc-url}org/hibernate/annotations/UuidGenerator.html[`@UuidGenerator`] is defined:
[source,java]
----
@IdGeneratorType(org.hibernate.id.uuid.UuidGenerator.class)
@ValueGenerationType(generatedBy = org.hibernate.id.uuid.UuidGenerator.class)
@Retention(RUNTIME)
@Target({ FIELD, METHOD })
public @interface UuidGenerator { ... }
----
`@UuidGenerator` is meta-annotated both `@IdGeneratorType` and `@ValueGenerationType` because it may be used to generate both ids and values of regular attributes.
Either way, link:{doc-javadoc-url}org/hibernate/id/uuid/UuidGenerator.html[this `Generator` class] does the hard work:
[source,java]
----
public class UuidGenerator
// this generator produced values before SQL is executed
implements BeforeExecutionGenerator {
// constructors accept an instance of the @UuidGenerator
// annotation, allowing the generator to be "configured"
// called to create an id generator
public UuidGenerator(
org.hibernate.annotations.UuidGenerator config,
Member idMember,
GeneratorCreationContext creationContext) {
this(config, idMember);
}
// called to create a generator for a regular attribute
public UuidGenerator(
org.hibernate.annotations.UuidGenerator config,
Member member,
GeneratorCreationContext creationContext) {
this(config, idMember);
}
...
@Override
public EnumSet getEventTypes() {
// UUIDs are only assigned on insert, and never regenerated
return INSERT_ONLY;
}
@Override
public Object generate(SharedSessionContractImplementor session, Object owner, Object currentValue, EventType eventType) {
// actually generate a UUID and transform it to the required type
return valueTransformer.transform( generator.generateUuid( session ) );
}
}
----
You can find out more about custom generators from the Javadoc for `@IdGeneratorType` and for `org.hibernate.generator`.
[[naming-strategies]]
=== Naming strategies
When working with a pre-existing relational schema, it's usual to find that the column and table naming conventions used in the schema don't match Java's naming conventions.
Of course, the `@Table` and `@Column` annotations let us explicitly specify a mapped table or column name.
But we would prefer to avoid scattering these annotations across our whole domain model.
Therefore, Hibernate lets us define a mapping between Java naming conventions, and the naming conventions of the relational schema.
Such a mapping is called a _naming strategy_.
First, we need to understand how Hibernate assigns and processes names.
- _Logical naming_ is the process of applying naming rules to determine the _logical names_ of objects which were not explicitly assigned names in the O/R mapping.
That is, when there's no `@Table` or `@Column` annotation.
- _Physical naming_ is the process of applying additional rules to transform a logical name into an actual "physical" name that is used in the database.
For example, the rules might include things like using standardized abbreviations, or trimming the length of identifiers.
Thus, there's two flavors of naming strategy, with slightly different responsibilities.
Hibernate comes with default implementations of these interfaces:
|===
| Flavor | Default implementation
| An link:{doc-javadoc-url}org/hibernate/boot/model/naming/ImplicitNamingStrategy.html[`ImplicitNamingStrategy`] is responsible for assigning a logical name when none is specified by an annotation
| A default strategy which implements the rules defined by JPA
| A link:{doc-javadoc-url}org/hibernate/boot/model/naming/PhysicalNamingStrategy.html[`PhysicalNamingStrategy`] is responsible for transforming a logical name and producing the name used in the database
| A trivial implementation which does no processing
|===
[TIP]
====
We happen to not much like the naming rules defined by JPA, which specify that mixed case and camel case identifiers should be concatenated using underscores.
We bet you could easily come up with a much better `ImplicitNamingStrategy` than that!
(Hint: it should always produce legit mixed case identifiers.)
====
[TIP]
====
The popular link:{doc-javadoc-url}org/hibernate/boot/model/naming/PhysicalNamingStrategySnakeCaseImpl.html[`PhysicalNamingStrategySnakeCaseImpl`] produces snake case identifiers.
====
Custom naming strategies may be enabled using the configuration properties we already mentioned without much explanation back in <>.
.Naming strategy configuration
[%breakable,cols="35,~"]
|===
| Configuration property name | Purpose
| link:{doc-javadoc-url}org/hibernate/cfg/MappingSettings.html#IMPLICIT_NAMING_STRATEGY[`hibernate.implicit_naming_strategy`] | Specifies the `ImplicitNamingStrategy`
| link:{doc-javadoc-url}org/hibernate/cfg/MappingSettings.html#PHYSICAL_NAMING_STRATEGY[`hibernate.physical_naming_strategy`] | Specifies the `PhysicalNamingStrategy`
|===
[[spatial]]
=== Spatial datatypes
:ogc: https://www.ogc.org
:geolatte: https://github.com/GeoLatte/geolatte-geom
:spatial-doc: {doc-user-guide-url}#spatial
Hibernate Spatial augments the <> with a set of Java mappings for {ogc}[OGC] spatial types.
- {geolatte}[Geolatte-geom] defines a set of Java types implementing the OGC spatial types, and codecs for translating to and from database-native spatial datatypes.
- {spatial-doc}[Hibernate Spatial] itself supplies integration with Hibernate.
To use Hibernate Spatial, we must add it as a dependency, as described in <>.
Then we may immediately use Geolatte-geom and JTS types in our entities.
No special annotations are needed:
[source,java]
----
import org.locationtech.jts.geom.Point;
import jakarta.persistence.*;
@Entity
class Event {
Event() {}
Event(String name, Point location) {
this.name = name;
this.location = location;
}
@Id @GeneratedValue
Long id;
String name;
Point location;
}
----
The generated DDL uses `geometry` as the type of the column mapped by `location`:
[source,sql]
----
create table Event (
id bigint not null,
location geometry,
name varchar(255),
primary key (id)
)
----
Hibernate Spatial lets us work with spatial types just as we would with any of the built-in basic attribute types.
[source,java]
----
var geometryFactory = new GeometryFactory();
...
Point point = geometryFactory.createPoint(new Coordinate(10, 5));
session.persist(new Event("Hibernate ORM presentation", point));
----
But what makes this powerful is that we may write some very fancy queries involving functions of spatial types:
[source,java]
----
Polygon triangle =
geometryFactory.createPolygon(
new Coordinate[] {
new Coordinate(9, 4),
new Coordinate(11, 4),
new Coordinate(11, 20),
new Coordinate(9, 4)
}
);
Point event =
session.createQuery("select location from Event where within(location, :zone) = true", Point.class)
.setParameter("zone", triangle)
.getSingleResult();
----
:matrix: {doc-user-guide-url}#spatial-configuration-dialect-features
Here, `within()` is one of the functions for testing spatial relations defined by the OpenGIS specification.
Other such functions include `touches()`, `intersects()`, `distance()`, `boundary()`, etc.
Not every spatial relation function is supported on every database.
A matrix of support for spatial relation functions may be found in the {matrix}[User Guide].
[TIP]
====
If you want to play with spatial functions on H2, run the following code first:
[source,java]
----
sessionFactory.inTransaction(session -> {
session.doWork(connection -> {
try (var statement = connection.createStatement()) {
statement.execute("create alias if not exists h2gis_spatial for \"org.h2gis.functions.factory.H2GISFunctions.load\"");
statement.execute("call h2gis_spatial()");
}
});
} );
----
====
[[ordered-sorted]]
=== Ordered and sorted collections and map keys
Java lists and maps don't map very naturally to foreign key relationships between tables, and so we tend to avoid using them to represent associations between our entity classes.
But if you feel like you _really_ need a collection with a fancier structure than `Set`, Hibernate does have options.
TIP: For more detail about the use of these annotations, please refer to https://in.relation.to/2024/11/12/-what-collection/[this post on the Hibernate blog].
The following options let us map the index of a `List` or key of a `Map` to a column, and are used with:
- `@ElementCollection`, or
- on the owning side of an association.
They should not be used on the unowned (that is, `mappedBy`) side of an association.
.Annotations for mapping lists and maps
[%breakable,cols="22,~,^13"]
|===
| Annotation | Purpose | JPA-standard
| `@OrderColumn` | Specifies the column used to maintain the order of a list | ✔
| link:{doc-javadoc-url}org/hibernate/annotations/ListIndexBase.html[`@ListIndexBase`] | The column value for the first element of the list (zero by default) | ✖
| `@MapKeyColumn` | Specifies the column used to persist the keys of a map
(used when the key is of basic type)| ✔
| `@MapKeyJoinColumn` | Specifies the column used to persist the keys of a map
(used when the key is an entity) | ✔
|===
The name of the `@OrderColumn` or `@MapKeyColumn` may be defaulted, for example:
[source,java]
----
@ManyToMany
@OrderColumn // order of list is persistent
List authors = new ArrayList<>();
----
But it's usually better to specify the column name explicitly:
[source,java]
----
@ElementCollection
@OrderColumn(name="tag_order")
@ListIndexBase(1) // order column and base value
List tags;
----
Such mappings can get pretty complicated:
[source,java]
----
@ElementCollection
@CollectionTable(name = "author_bios", // table name
joinColumns = @JoinColumn(name = "book_isbn")) // column holding foreign key of owner
@Column(name="bio") // column holding map values
@MapKeyJoinColumn(name="author_ssn") // column holding map keys
Map biographies;
----
As you can imagine, we think you should use such mappings very sparingly, if at all.
For a `Map` representing an unowned `@OneToMany` association, the column holding the key of the map must also be mapped on the owning side, usually by an attribute of the target entity.
In this case we use a different annotation:
.Annotation for mapping an entity attribute to a map key
[%breakable,cols="22,~,^13"]
|===
| Annotation | Purpose | JPA-standard
| `@MapKey` | Specifies an attribute of the target entity which acts as the key of the map | ✔
|===
Note that `@MapKey` specifies a field or property name, not a column name.
[source,java]
----
@OneToMany(mappedBy = Book_.PUBLISHER)
@MapKey(name = Book_.TITLE) // the key of the map is the title of the book
Map booksByTitle = new HashMap<>();
----
In fact, `@MapKey` may also be used for owned collections.
Now, let's introduce a little distinction:
- an _ordered collection_ is one with an ordering maintained in the database, and
- a _sorted collection_ is one which is sorted in Java code.
These annotations allow us to specify how the elements of a collection should be ordered as they are read from the database:
.Annotations for ordered collections
[%breakable,cols="22,~,^13"]
|===
| Annotation | Purpose | JPA-standard
| `@OrderBy` | Specifies a fragment of JPQL used to order the collection | ✔
| `@SQLOrder` | Specifies a fragment of SQL used to order the collection | ✖
|===
On the other hand, the following annotations specify how a collection should be sorted in memory, and are used for collections of type `SortedSet` or `SortedMap`:
.Annotations for sorted collections
[%breakable,cols="22,~,^13"]
|===
| Annotation | Purpose | JPA-standard
| link:{doc-javadoc-url}org/hibernate/annotations/SortNatural.html[`@SortNatural`] | Specifies that the elements of a collection are `Comparable` | ✖
| link:{doc-javadoc-url}org/hibernate/annotations/SortComparator.html[`@SortComparator`] | Specifies a `Comparator` used to sort the collection | ✖
|===
Under the covers, Hibernate uses a `TreeSet` or `TreeMap` to maintain the collection in sorted order.
[CAUTION]
====
The unowned (`mappedBy`) side of a bidirectional association is not responsible for specifying column mappings.
So it's wrong in principle to use `@OrderColumn` or `@MapKeyColumn` on the unowned side of an association mapping.
But for unowned collections, we may use `@OrderBy` or `@MapKey` instead.
That is:
- You can use `@OrderColumn` or `@MapKeyColumn` with an `@ElementCollection`, owned `@ManyToMany`, or owned `@OneToMany`.
- But use `@OrderBy` or `@MapKey` when it's an _unowned_ `@ManyToMany` or `@OneToMany`.
====
[[any]]
=== Any mappings
:any-doc: {doc-user-guide-url}#associations-any
An link:{doc-javadoc-url}org/hibernate/annotations/Any.html[`@Any`] mapping is a sort of polymorphic many-to-one association where the target entity types are not related by the usual entity inheritance.
The target type is distinguished using a discriminator value stored on the _referring_ side of the relationship.
This is quite different to <> where the discriminator is held in the tables mapped by the referenced entity hierarchy.
For example, consider an `Order` entity containing `Payment` information, where a `Payment` might be a `CashPayment` or a `CreditCardPayment`:
[source,java]
----
interface Payment { ... }
@Entity
class CashPayment { ... }
@Entity
class CreditCardPayment { ... }
----
In this example, `Payment` is not be declared as an entity type, and is not annotated `@Entity`. It might even be an interface, or at most just a mapped superclass, of `CashPayment` and `CreditCardPayment`. So in terms of the object/relational mappings, `CashPayment` and `CreditCardPayment` would not be considered to participate in the same entity inheritance hierarchy.
On the other hand, `CashPayment` and `CreditCardPayment` do have the same identifier type.
This is important.
An `@Any` mapping would store the discriminator value identifying the concrete type of `Payment` along with the state of the associated `Order`, instead of storing it in the table mapped by `Payment`.
[source,java]
----
@Entity
class Order {
...
@Any
@AnyKeyJavaClass(UUID.class) //the foreign key type
@JoinColumn(name="payment_id") // the foreign key column
@Column(name="payment_type") // the discriminator column
// map from discriminator values to target entity types
@AnyDiscriminatorValue(discriminator="CASH", entity=CashPayment.class)
@AnyDiscriminatorValue(discriminator="CREDIT", entity=CreditCardPayment.class)
Payment payment;
...
}
----
It's reasonable to think of the "foreign key" in an `@Any` mapping as a composite value made up of the foreign key and discriminator taken together. Note, however, that this composite foreign key is only conceptual and cannot be declared as a physical constraint on the relational database table.
There are a number of annotations which are useful to express this sort of complicated and unnatural mapping:
.Annotations for `@Any` mappings
|===
| Annotations | Purpose
| link:{doc-javadoc-url}org/hibernate/annotations/Any.html[`@Any`] | Declares that an attribute is a discriminated polymorphic association mapping
| link:{doc-javadoc-url}org/hibernate/annotations/AnyDiscriminator.html[`@AnyDiscriminator`] | Specify the Java type of the discriminator
| `@JdbcType` or `@JdbcTypeCode` | Specify the JDBC type of the discriminator
| link:{doc-javadoc-url}org/hibernate/annotations/AnyDiscriminatorValue.html[`@AnyDiscriminatorValue`] | Specifies how discriminator values map to entity types
| `@Column` or `@Formula` | Specify the column or formula in which the discriminator value is stored
| `@AnyKeyJavaType` or `@AnyKeyJavaClass` | Specify the Java type of the foreign key (that is, of the ids of the target entities)
| `@AnyKeyJdbcType` or `@AnyKeyJdbcTypeCode` | Specify the JDBC type of the foreign key
| `@JoinColumn` | Specifies the foreign key column
|===
As a general principle, an `@Any` association shares the semantics of `@ManyToAny`, and, since Hibernate 7.4, may be used just like a `@ManyToOne` in HQL and so on.
Of course, `@Any` mappings are disfavored, except in extremely special cases, since it's much more difficult to enforce referential integrity at the database level.
Further information may be found in the {any-doc}[User Guide].
[[dynamic-insert-update]]
=== Selective column lists in inserts and updates
By default, Hibernate generates `insert` and `update` statements for each entity during boostrap, and reuses the same `insert` statement every time an instance of the entity is made persistent, and the same `update` statement every time an instance of the entity is modified.
This means that:
- if an attribute is `null` when the entity is made persistent, its mapped column is redundantly included in the SQL `insert`, and
- worse, if a certain attribute is unmodified when other attributes are changed, the column mapped by that attribute is redundantly included in the SQL `update`.
Most of the time, this just isn't an issue worth worrying about.
The cost of interacting with the database is _usually_ dominated by the cost of a round trip, not by the number of columns in the `insert` or `update`.
But in cases where it does become important, there are two ways to be more selective about which columns are included in the SQL.
The JPA-standard way is to indicate statically which columns are eligible for inclusion via the `@Column` annotation.
For example, if an entity is always created with an immutable `creationDate`, and with no `completionDate`, then we would write:
[source,java]
----
@Column(updatable=false) LocalDate creationDate;
@Column(insertable=false) LocalDate completionDate;
----
This approach works quite well in many cases, but often breaks down for entities with more than a handful of updatable columns.
An alternative solution is to ask Hibernate to generate SQL dynamically each time an `insert` or `update` is executed.
We do this by annotating the entity class.
.Annotations for dynamic SQL generation
[%breakable,cols="25,~"]
|===
| Annotation | Purpose
| link:{doc-javadoc-url}org/hibernate/annotations/DynamicInsert.html[`@DynamicInsert`] | Specifies that an `insert` statement should be generated each time an entity is made persistent
| link:{doc-javadoc-url}org/hibernate/annotations/DynamicUpdate.html[`@DynamicUpdate`] | Specifies that an `update` statement should be generated each time an entity is modified
|===
It's important to realize that, while `@DynamicInsert` usually has no impact on semantics, the more useful `@DynamicUpdate` annotation _does_ have a subtle side effect.
[CAUTION]
====
The wrinkle is that if an entity has no version property, `@DynamicUpdate` opens the possibility of two optimistic transactions concurrently reading and selectively updating a given instance of the entity.
In principle, this might lead to a row with inconsistent column values after both optimistic transactions commit successfully.
====
Of course, this consideration doesn't arise for entities with a `@Version` attribute.
[TIP]
====
But there's a solution!
Well-designed relational schemas should have _constraints_ to ensure data integrity.
That's true no matter what measures we take to preserve integrity in our program logic.
We may ask Hibernate to add a <> to our table using the `@Check` annotation.
Check constraints and foreign key constraints can help ensure that a row never contains inconsistent column values.
====
[[bytecode-enhancer]]
=== Using the bytecode enhancer
:enhancer: {doc-user-guide-url}#BytecodeEnhancement
Hibernate's {enhancer}[bytecode enhancer] enables the following features:
- _attribute-level lazy fetching_ for basic attributes annotated `@Basic(fetch=LAZY)` and for lazy non-polymorphic associations,
- _interception-based_—instead of the usual _snapshot-based_—detection of modifications.
In addition, use of the bytecode enhancer relaxes the usual requirement that entity and embeddable classes have default constructors.
If a class annotated `@Entity`, `@MappedSuperclass`, or `@Embeddable` has no default constructor, the bytecode enhancer will add it.
To use the bytecode enhancer, we must add the Hibernate plugin to our gradle build:
[source,groovy,subs="attributes+"]
----
plugins {
id "org.hibernate.orm" version "{fullVersion}"
}
hibernate {
enhancement {}
}
----
[CAUTION]
====
Some online documentation (including previous versions of the present one) suggest to use `hibernate { enhancement }`, which will _not_ work as it is interpreted by Gradle as a (pointless) getter call instead of actual configuration.
That form will result in bytecode enhancement NOT happening (unfortunately silently).
To enable bytecode enhancement, make sure to always use the block form (with `{}`).
====
// [discrete]
// ==== Attribute-level lazy fetching
Consider this field:
[source,java]
----
@Entity
class Book {
...
@Basic(optional = false, fetch = LAZY)
@Column(length = LONG32)
String fullText;
...
}
----
The `fullText` field maps to a `clob` or `text` column, depending on the SQL dialect.
Since it's expensive to retrieve the full book-length text, we've mapped the field `fetch=LAZY`, telling Hibernate not to read the field until it's actually used.
- _Without_ the bytecode enhancer, this instruction is ignored, and the field is always fetched immediately, as part of the initial `select` that retrieves the `Book` entity.
- _With_ bytecode enhancement, Hibernate is able to detect access to the field, and lazy fetching is possible.
[TIP]
====
By default, Hibernate fetches all lazy fields of a given entity at once, in a single `select`, when any one of them is accessed.
Using the link:{doc-javadoc-url}org/hibernate/annotations/LazyGroup.html[`@LazyGroup`] annotation, it's possible to assign fields to distinct "fetch groups", so that different lazy fields may be fetched independently.
====
Similarly, interception lets us implement lazy fetching for non-polymorphic associations without the need for a separate proxy object.
However, if an association is polymorphic, that is, if the target entity type has subclasses, then a proxy is still required.
// [discrete]
// ==== Interception-based change detection
Interception-based change detection is a nice performance optimization with a slight cost in terms of correctness.
- _Without_ the bytecode enhancer, Hibernate keeps a snapshot of the state of each entity after reading from or writing to the database.
When the session flushes, the snapshot state is compared to the current state of the entity to determine if the entity has been modified.
Maintaining these snapshots does have an impact on performance.
- _With_ bytecode enhancement, we may avoid most of this cost by intercepting writes to the field and recording these modifications as they happen--however, a snapshot is still maintained for any field whose value is itself mutable, for example, for a field of type `byte[]`.
This optimization isn't _completely_ transparent, however.
[CAUTION]
====
Interception-based change detection is less accurate than snapshot-based dirty checking.
In particular, writes to a field of an enhanced entity from outside the entity class itself are not detected by the enhanced bytecode and might not be made persistent.
====
[IMPORTANT]
Hibernate's extended bytecode enhancement feature has been deprecated, primarily because it relies on assumptions and behaviors that often require a broader runtime scope than what Hibernate alone can reliably provide, similar to container-based environments such as Quarkus or WildFly.
Applications which make use of this feature should instead use proper object-oriented encapsulation, exposing managed state via getters and setters.
[[fetch-profiles]]
=== Named fetch profiles
We've already seen two different ways to override the default <> for an association:
- <>, and
- the `join fetch` clause in <>, or, equivalently, the method `From.fetch()` in the criteria query API.
A third way is to define a named fetch profile.
First, we must declare the profile, by annotating a class, package, or module link:{doc-javadoc-url}org/hibernate/annotations/FetchProfile.html[`@FetchProfile`]:
[source,java]
----
@FetchProfile(name = "EagerBook")
@Entity
class Book { ... }
----
Note that even though we've placed this annotation on the `Book` entity, a fetch profile—unlike an entity graph—isn't "rooted" at any particular entity.
We may specify association fetching strategies using the `fetchOverrides` member of the `@FetchProfile` annotation, but frankly it looks so messy that we're embarrassed to show it to you here.
[NOTE]
====
Similarly, a JPA <> may be defined using `@NamedEntityGraph`.
But the format of this annotation is _even worse_ than `@FetchProfile(fetchOverrides=...)`, so we can't recommend it. 💀
====
A better way is to annotate an association with the fetch profiles it should be fetched in:
[source,java]
----
@FetchProfile(name = "EagerBook")
@Entity
class Book {
...
@ManyToOne(fetch = LAZY)
@FetchProfileOverride(profile = Book_.PROFILE_EAGER_BOOK, mode = JOIN)
Publisher publisher;
@ManyToMany
@FetchProfileOverride(profile = Book_.PROFILE_EAGER_BOOK, mode = JOIN)
Set authors;
...
}
----
[source,java]
----
@Entity
class Author {
...
@OneToOne
@FetchProfileOverride(profile = Book_.PROFILE_EAGER_BOOK, mode = JOIN)
Person person;
...
}
----
Here, once again, `Book_.PROFILE_EAGER_BOOK` is generated by Hibernate Processor, and is just a constant with the value `"EagerBook"`.
We may even request subselect fetching:
[source,java]
----
@FetchProfile(name = "EagerBook")
@FetchProfile(name = "BookWithAuthorsBySubselect")
@Entity
class Book {
...
@OneToOne
@FetchProfileOverride(profile = Book_.PROFILE_EAGER_BOOK, mode = JOIN)
Person person;
@ManyToMany
@FetchProfileOverride(profile = Book_.PROFILE_EAGER_BOOK, mode = JOIN)
@FetchProfileOverride(profile = Book_.BOOK_WITH_AUTHORS_BY_SUBSELECT,
mode = SUBSELECT)
Set authors;
...
}
----
We may define as many different fetch profiles as we like.
.Annotations for defining fetch profiles
[%breakable,cols="25,~"]
|===
| Annotation | Purpose
| `@FetchProfile` | Declares a named fetch profile, optionally including a list of ``@FetchOverride``s
| `@FetchProfile.FetchOverride` | Declares a fetch strategy override as part of the `@FetchProfile` declaration
| `@FetchProfileOverride` | Specifies the fetch strategy for the annotated association, in a given fetch profile
|===
A fetch profile must be explicitly enabled for a given session by passing the name of the profile to link:{doc-javadoc-url}org/hibernate/Session.html#enableFetchProfile(java.lang.String)[`enableFetchProfile()`]:
[source,java]
----
session.enableFetchProfile(Book_.PROFILE_EAGER_BOOK);
Book eagerBook = session.find(Book.class, bookId);
----
Alternatively, an instance of link:{doc-javadoc-url}org/hibernate/EnabledFetchProfile.html[`EnabledFetchProfile`] may be obtained in a type safe way from the static metamodel, and applied to the session:
[source,java]
----
Book_._EagerBook.enable(session);
Book eagerBook = session.find(Book.class, bookId);
----
Even better, the `EnabledFetchProfile` may be passed as a `FindOption`:
[source,java]
----
Book eagerBook = entityManager.find(Book.class, bookId, Book_._EagerBook);
----
So why or when might we prefer named fetch profiles to entity graphs?
Well, it's really hard to say.
It's nice that this feature _exists_, and if you love it, that's great.
But Hibernate offers alternatives that we think are more compelling most of the time.
[%unbreakable]
[TIP]
====
There's a special built-in fetch profile named `org.hibernate.defaultProfile` which is defined as the profile with `@FetchProfileOverride(mode=JOIN)` applied to every eager `@ManyToOne` or `@OneToOne` association.
If you enable this profile:
[source,java]
----
entityManager.addOption(new EnabledFetchProfile("org.hibernate.defaultProfile"));
----
Then ``outer join``s for such associations will _automatically_ be added to every HQL or criteria query.
This is nice if you can't be bothered typing out those ``join fetch``es explicitly.
And in principle it even helps partially mitigate the <> of JPA having specified the wrong default for the `fetch` member of `@ManyToOne`.
====
---
### Documentation Src Main Asciidoc Introduction Configuration (`documentation/src/main/asciidoc/introduction/Configuration.adoc`)
[[configuration]]
== Configuration and bootstrap
:data: https://jakarta.ee/specifications/data/1.1/jakarta-data-1.1-m3.pdf
:persistence: https://jakarta.ee/specifications/persistence/4.0/jakarta-persistence-spec-4.0-M4.pdf
We would love to make this section short.
Unfortunately, there are several distinct ways to configure and bootstrap Hibernate, and we're going to have to describe at least two of them in detail.
The five basic ways to obtain an instance of Hibernate are shown in the following table:
[%breakable,cols="50,50",number=0]
|===
| Using the standard JPA-defined XML, and the operation `Persistence.createEntityManagerFactory()`
| Usually chosen when portability between JPA implementations is important.
| Using the standard JPA-defined `PersistenceConfiguration` class
| Usually chosen when portability between JPA implementations is important, but programmatic control is desired.
| Using link:{doc-javadoc-url}org/hibernate/jpa/HibernatePersistenceConfiguration.html[`HibernatePersistenceConfiguration`]
// or the older link:{doc-javadoc-url}org/hibernate/cfg/Configuration.html[`Configuration`] class
to construct a `SessionFactory`
| When portability between JPA implementations is not important, this option adds some convenience and saves a typecast.
| Using the more complex APIs defined in link:{doc-javadoc-url}org/hibernate/boot/package-summary.html[`org.hibernate.boot`]
| Used primarily by framework integrators, this option is outside the scope of this document.
| By letting the container take care of the bootstrap process and of injecting the `EntityManagerFactory`
| Used in a container environment like WildFly or Quarkus.
|===
Here we'll focus on the first two options.
:hibernate-quarkus: https://quarkus.io/guides/hibernate-orm
[NOTE]
====
Actually, the last option is extremely popular, since every major Java application server and microservice framework comes with built-in support for Hibernate.
Such container environments typically also feature facilities to automatically manage the lifecycle of an `EntityManager` and its association with container-managed transactions.
To learn how to configure Hibernate in such a container environment, you'll need to refer to the documentation of your chosen container.
For Quarkus, here's the {hibernate-quarkus}[relevant documentation].
====
If you're using Hibernate outside of a container environment,
you'll need to:
- include Hibernate ORM itself, along with the appropriate JDBC driver, as dependencies of your project, and
- configure Hibernate with information about your database,
by specifying configuration properties.
[[required-dependencies]]
=== Including Hibernate in your project build
First, add the following dependency to your project:
----
org.hibernate.orm:hibernate-core:{version}
----
Where `{version}` is the version of Hibernate you're using, `{fullVersion}`, for example.
You'll also need to add a dependency for the JDBC
driver for your database.
.JDBC driver dependencies
[%breakable,cols="50,~"]
|===
| Database | Driver dependency
| PostgreSQL or CockroachDB | `org.postgresql:postgresql:{version}`
| MySQL or TiDB | `com.mysql:mysql-connector-j:{version}`
| MariaDB | `org.mariadb.jdbc:mariadb-java-client:{version}`
| DB2 | `com.ibm.db2:jcc:{version}`
| SQL Server | `com.microsoft.sqlserver:mssql-jdbc:{version}`
| Oracle | `com.oracle.database.jdbc:ojdbc17:{version}`
| Informix | `com.informix.jdbc.IfxDriver:{version}`
| H2 | `com.h2database:h2:{version}`
| HSQLDB | `org.hsqldb:hsqldb:{version}`
| MongoDB | The JDBC driver is bundled with the dialect mentioned in <>
| Google Spanner | `com.google.cloud:google-cloud-spanner-jdbc:{version}`
|===
Where `{version}` is the latest version of the JDBC driver for your database.
[[optional-dependencies]]
=== Optional dependencies
:slf4j: http://www.slf4j.org/
:enhancer: {doc-user-guide-url}#tooling-gradle
:agroal: https://agroal.github.io
:jackson: https://github.com/FasterXML/jackson
:yasson: https://projects.eclipse.org/projects/ee4j.yasson
:validator: https://hibernate.org/validator
:ehcache: https://www.ehcache.org
:infinispan: https://infinispan.org
:generator: https://hibernate.org/orm/tooling/
:caffeine: https://github.com/ben-manes/caffeine/
:bean-validation: https://beanvalidation.org
:query-validator: https://github.com/hibernate/query-validator/
Optionally, you might also add any of the following additional features:
.Optional dependencies
[%breakable,cols="50,~"]
|===
| Optional feature | Dependencies
| An {slf4j}[SLF4J] logging implementation |
`org.apache.logging.log4j:log4j-core` +
or `org.slf4j:slf4j-jdk14`
| A JDBC connection pool, for example, {agroal}[Agroal] | `org.hibernate.orm:hibernate-agroal`
| The {generator}[Hibernate Processor], especially if you're using Jakarta Data or the JPA criteria query API | `org.hibernate.orm:hibernate-processor`
| {data}[Jakarta Data] stateless and stateful repository support |
`jakarta.data:jakarta.data-api` +
and `jakarta.data:jakarta.data.stateful-api`
// | The {query-validator}[Query Validator], for compile-time checking of HQL | `org.hibernate:query-validator`
| {validator}[Hibernate Validator], an implementation of {bean-validation}[Bean Validation] |
`org.hibernate.validator:hibernate-validator` +
and `org.glassfish.expressly:expressly`
| Local second-level cache support via JCache and {ehcache}[EHCache] | `org.hibernate.orm:hibernate-jcache` +
and `org.ehcache:ehcache`
| Local second-level cache support via JCache and {caffeine}[Caffeine]| `org.hibernate.orm:hibernate-jcache` +
and `com.github.ben-manes.caffeine:jcache`
| Distributed second-level cache support via {infinispan}[Infinispan] | `org.infinispan:infinispan-hibernate-cache-v60`
// | SCRAM authentication support for PostgreSQL | `com.ongres.scram:client:2.1`
| A JSON serialization library for working with JSON datatypes, for example, {jackson}[Jackson] or {yasson}[Yasson] |
`tools.jackson.core:jackson-databind` +
or `org.eclipse:yasson`
| <> | `org.hibernate.orm:hibernate-spatial`
// | <>, deprecated since Hibernate ORM 8.0, for auditing historical data | `org.hibernate.orm:hibernate-envers`
| <>, for monitoring via Java Flight Recorder | `org.hibernate.orm:hibernate-jfr`
| Hibernate Jandex integration, for <> | `org.hibernate.orm:hibernate-scan-jandex`
| link:{doc-dialect-url}#community-dialects[Community dialects] | `org.hibernate.orm:hibernate-community-dialects`
| https://github.com/mongodb/mongo-hibernate/[MongoDB] dialect | `org.mongodb:mongodb-hibernate`
| https://github.com/GoogleCloudPlatform/google-cloud-spanner-hibernate[Google Spanner] dialect | `com.google.cloud:google-cloud-spanner-hibernate-dialect`
|===
You might also add the Hibernate {enhancer}[bytecode enhancer] to your
Gradle build if you want to use <>.
[[configuration-jpa]]
=== Configuration using JPA XML
Sticking to the JPA-standard approach, we would provide a file named `persistence.xml`, which we usually place in the `META-INF` directory of a _persistence archive_, that is, of the `.jar` file or directory which contains our entity classes.
[source,xml]
----
org.hibernate.example.Book
org.hibernate.example.Author
LAZY
----
The `` element defines a named _persistence unit_, that is:
- a collection of associated entity types, along with
- a set of default configuration settings, which may be augmented or overridden at runtime.
Each `` element specifies the fully qualified name of an entity class.
In some container environments, for example, in any EE container, the `` elements are unnecessary, as we explain <>.
The `` element specifies that many-to-one and one-to-one associations default to <>.
As <>, we strongly recommend this setting in all new code.
Each `` element specifies a _configuration property_ and its value.
Note that:
- the configuration properties in the `jakarta.persistence` namespace are standard properties defined by the JPA spec, and
- properties in the `hibernate` namespace are specific to Hibernate.
We may obtain an `EntityManagerFactory` by calling `Persistence.createEntityManagerFactory()`:
[source,java]
----
EntityManagerFactory entityManagerFactory =
Persistence.createEntityManagerFactory("org.hibernate.example");
----
If necessary, we may override configuration properties specified in `persistence.xml`:
[source,java]
----
EntityManagerFactory entityManagerFactory =
Persistence.createEntityManagerFactory("org.hibernate.example",
Map.of(Persistence.ConnectionProperties.JDBC_PASSWORD, password));
----
[[configuration-api]]
=== Programmatic configuration using JPA API
The `PersistenceConfiguration` class allows full programmatic control over creation of the `EntityManagerFactory`.
[source,java]
----
EntityManagerFactory entityManagerFactory =
new PersistenceConfiguration("Bookshop")
// all associations should be lazy by default
.defaultToOneFetchType(FetchType.LAZY)
// register the entity classes
.managedClass(Book.class)
.managedClass(Author.class)
// PostgreSQL
.property(PersistenceConfiguration.JDBC_URL, "jdbc:postgresql://localhost/example")
// Credentials
.property(PersistenceConfiguration.JDBC_USER, user)
.property(PersistenceConfiguration.JDBC_PASSWORD, password)
// SQL statement logging
.property(JdbcSettings.SHOW_SQL, true)
.property(JdbcSettings.FORMAT_SQL, true)
.property(JdbcSettings.HIGHLIGHT_SQL, true)
// Automatic schema export
.schemaManagementDatabaseAction(SchemaManagementAction.DROP_AND_CREATE)
// Create a new EntityManagerFactory
.createEntityManagerFactory();
----
The `defaultToOneFetchType()` method specifies that many-to-one and one-to-one associations default to <>.
As <>, we strongly recommend this setting in all new code.
The specification gives JPA implementors like Hibernate explicit permission to extend this class, and so Hibernate offers the link:{doc-javadoc-url}org/hibernate/jpa/HibernatePersistenceConfiguration.html[`HibernatePersistenceConfiguration`], which lets us obtain a `SessionFactory` without any need for a cast.footnote:[Alternatively, the venerable class link:{doc-javadoc-url}org/hibernate/cfg/Configuration.html[`Configuration`] offers similar functionality.]
[source,java]
----
SessionFactory sessionFactory =
new HibernatePersistenceConfiguration("Bookshop")
// all associations should be lazy by default
.defaultToOneFetchType(FetchType.LAZY)
// register the entity classes
.managedClasses(Book.class, Author.class)
// PostgreSQL
.jdbcUrl("jdbc:postgresql://localhost/example")
// Credentials
.jdbcCredentials(user, password)
// SQL statement logging
.showSql(true, true, true)
// Automatic schema export
.schemaManagementDatabaseAction(SchemaManagementAction.DROP_AND_CREATE)
// Create a new SessionFactory
.createEntityManagerFactory();
----
:native-bootstrap: {doc-user-guide-url}#bootstrap-native
:boot: {doc-javadoc-url}/org/hibernate/boot/package-summary.html
.*Read more: Advanced configuration options*
[%collapsible]
====
****
Actually, these APIs are very simple facades resting on the much more powerful--but also more complex--APIs defined in the package `org.hibernate.boot`.
This API is useful if you have very advanced requirements, for example, if you're writing a framework or implementing a container.
You'll find more information in the {native-bootstrap}[User Guide], and in the {boot}[package-level documentation] of `org.hibernate.boot`.
****
====
[[entity-discovery]]
=== Entity discovery
In a Jakarta EE container environment, we don't usually need to list entity and embeddable classes explicitly in `persistence.xml`.
Instead, the container scans the persistence unit `jar` file and automatically discovers classes annotated `@Entity`, `@Embeddable`, or `@MappedSuperclass`.
`HibernatePersistenceConfiguration` offers the same functionality if the <> `hibernate-scan-jandex` is available at runtime.
In the following code, entity classes available on the class loader which loaded `Main.class` are automatically discovered.
[source,java]
----
SessionFactory sessionFactory =
// entities discovered on ClassLoader of Main.class
new HibernatePersistenceConfiguration("Bookshop", Main.class)
// PostgreSQL
.jdbcUrl("jdbc:postgresql://localhost/example")
// Credentials
.jdbcCredentials(user, password)
// SQL statement logging
.showSql(true, true, true)
// Automatic schema export
.schemaManagementDatabaseAction(SchemaManagementAction.DROP_AND_CREATE)
// Create a new SessionFactory
.createEntityManagerFactory();
----
Notice that we were able to remove the calls to `managedClass()`.
[[configuration-properties]]
=== Configuration using Hibernate properties file
If we're using programmatic configuration, but we don't want to put certain configuration properties directly in the Java code, we can specify them in a file named `hibernate.properties`, and place the file in the root classpath.
[source,properties]
----
# PostgreSQL
jakarta.persistence.jdbc.url=jdbc:postgresql://localhost/example
# Credentials
jakarta.persistence.jdbc.user=hibernate
jakarta.persistence.jdbc.password=zAh7mY$2MNshzAQ5
# SQL statement logging
hibernate.show_sql=true
hibernate.format_sql=true
hibernate.highlight_sql=true
----
[[basic-configuration-settings]]
=== Basic configuration settings
The inner interfaces of the `Persistence` class -- which, for convenience, are inherited by `PersistenceConfiguration` -- declare `static final` constants holding the names of all configuration properties defined by the specification itself.
For example, `Persistence.ConnectionProperties.JDBC_URL` holds the property name `"jakarta.persistence.jdbc.driver"`.
Similarly, the class link:{doc-javadoc-url}org/hibernate/cfg/AvailableSettings.html[`AvailableSettings`] enumerates all the configuration properties understood by Hibernate.
Of course, we're not going to cover every useful configuration setting in this chapter.
Instead, we'll mention the ones you need to get started, and come back to some other important settings later, especially when we talk about performance tuning.
[TIP]
====
Hibernate has many--too many--switches and toggles.
Please don't go crazy messing about with these settings; most of them are rarely needed, and many only exist to provide backward compatibility with older versions of Hibernate.
With rare exception, the default behavior of every one of these settings was carefully chosen to be _the behavior we recommend_.
====
The properties you really do need to get started are these three:
.JDBC connection settings
[%breakable,cols="35,~"]
|===
| Configuration property name | Purpose
| `jakarta.persistence.jdbc.url` | JDBC URL of your database
| `jakarta.persistence.jdbc.user` and `jakarta.persistence.jdbc.password` | Your database credentials
|===
[IMPORTANT]
// .You don't need `hibernate.dialect` anymore!
====
Since Hibernate 6, you don't need to specify `hibernate.dialect`.
The correct Hibernate SQL `Dialect` will be determined for you automatically.
The only reason to specify this property is if you're using a custom user-written or link:{doc-dialect-url}#third-party-dialects[third-party] `Dialect` class.
Similarly, neither `hibernate.connection.driver_class` nor `jakarta.persistence.jdbc.driver` is needed when working with one of the supported databases.
====
In some environments it's useful to be able to start Hibernate without accessing the database.
In this case, we must explicitly specify not only the database platform, but also the version of the database, using the standard JPA configuration properties.
[source,properties]
----
# disable use of JDBC database metadata
hibernate.boot.allow_jdbc_metadata_access=false
# explicitly specify database and version
jakarta.persistence.database-product-name=PostgreSQL
jakarta.persistence.database-major-version=15
jakarta.persistence.database-minor-version=7
----
The product name is the value returned by `java.sql.DatabaseMetaData.getDatabaseProductName()`, for example, `PostgreSQL`, `MySQL`, `H2`, `Oracle`, `EnterpriseDB`, `MariaDB`, or `Microsoft SQL Server`.
.Settings needed when database is inaccessible at startup
[%breakable,cols="50,~"]
|===
| Configuration property name | Purpose
| `hibernate.boot.allow_jdbc_metadata_access` | Set to `false` to disallow access to the database at startup
| `jakarta.persistence.database-product-name` | The database product name, according to the JDBC driver
| `jakarta.persistence.database-major-version` and `jakarta.persistence.database-minor-version` | The major and minor versions of the database
|===
Pooling JDBC connections is an extremely important performance optimization.
You can set the size of Hibernate's built-in connection pool using this property:
.Built-in connection pool size
[%breakable,cols="35,~"]
|===
| Configuration property name | Purpose
| `hibernate.connection.pool_size` | The size of the connection pool
|===
This configuration property is also respected when you use Agroal, HikariCP, or c3p0 for connection pooling.
[CAUTION]
// .The default connection pool is not meant for production use
====
By default, Hibernate uses a simplistic built-in connection pool.
This pool is not meant for use in production, and later, when we discuss performance, we'll see how to <>.
====
Alternatively, in a container environment, you'll need at least one of these properties:
.Transaction management settings
[%breakable,cols="35,~"]
|===
| Configuration property name | Purpose
| `jakarta.persistence.transactionType` | (Optional, defaults to `JTA`)
Determines if transaction management is via JTA or resource-local transactions.
Specify `RESOURCE_LOCAL` if JTA should not be used.
| `jakarta.persistence.jtaDataSource` | JNDI name of a JTA datasource
| `jakarta.persistence.nonJtaDataSource` | JNDI name of a non-JTA datasource
|===
In this case, Hibernate obtains pooled JDBC database connections from a container-managed `DataSource`.
[[automatic-schema-export]]
=== Automatic schema export
You can have Hibernate infer your database schema from the mapping annotations you've specified in your Java code, and export the schema at initialization time by specifying one or more of the following configuration properties:
.Schema management settings
[%breakable,cols="50,~"]
|===
| Configuration property name | Purpose
| `jakarta.persistence.schema-generation.database.action`
a| * If `drop-and-create`, first drop the schema, then export tables, sequences, and constraints, and then populate initial data
* If `create`, export tables, sequences, and constraints, without attempting to drop them first, and then populate initial data
* If `create-drop`, drop the schema and recreate it on factory startup;
additionally, drop the schema on factory shutdown
* If `drop`, drop the schema on factory startup
* If `validate`, validate the database schema without changing it
* If `update`, only export what's missing in the schema, and alter incorrect column types
* If `populate`, only populate initial data
| `jakarta.persistence.create-database-schemas`
| (Optional) If `true`, automatically create schemas and catalogs
| `jakarta.persistence.schema-generation.create-source`
| (Optional) If `metadata-then-script` or `script-then-metadata`, execute an additional SQL script when exported tables and sequences
| `jakarta.persistence.schema-generation.create-script-source`
| (Optional) The name of a SQL DDL script to be executed
| `jakarta.persistence.sql-load-script-source`
| (Optional) The name of a SQL DML script to be executed
| `hibernate.hbm2ddl.import_files_sql_extractor`
| (Optional) If `multi-line`, SQL statements may be split across multiple lines in scripts, and must be ``;``-terminated.
|===
This feature is extremely useful for testing.
[TIP]
// .Importing test or reference data
====
The easiest way to pre-initialize a database with test or "reference" data is to place a list of SQL `insert` statements in a file named, for example, `import.sql`, and specify the path to this file using the property `jakarta.persistence.sql-load-script-source`.
We've already seen an <> of this approach, which is cleaner than writing Java code to instantiate entity instances and calling `persist()` on each of them.
====
As we mentioned <>, it can also be useful to control schema export programmatically.
[TIP]
// .Programmatic schema export
====
The link:{doc-javadoc-url}org/hibernate/relational/SchemaManager.html[`SchemaManager`] API allows programmatic control over schema export:
[source,java]
sessionFactory.getSchemaManager().create(true);
====
[[logging-generated-sql]]
=== Logging the generated SQL
:log4j: https://github.com/hibernate/hibernate-reactive/blob/main/examples/session-example/src/main/resources/log4j2.properties
To see the generated SQL as it's sent to the database, we have two options.
One way is to set the property `hibernate.show_sql` to `true`, so that Hibernate logs SQL directly to the console.
You can make the output much more readable by enabling formatting or highlighting.
These settings really help when troubleshooting the generated SQL statements.
.Settings for SQL logging to the console
[%breakable,cols="35,~"]
|===
| Configuration property name | Purpose
| `hibernate.show_sql` | If `true`, log SQL directly to the console
| `hibernate.format_sql` | If `true`, log SQL in a multiline, indented format
| `hibernate.highlight_sql` | If `true`, log SQL with syntax highlighting via ANSI escape codes
|===
Alternatively, you can enable ``DEBUG``-level logging for the category `org.hibernate.SQL` using your preferred SLF4J logging implementation.
For example, if you're using Log4J 2 (as above in <>), add these lines to your `log4j2.properties` file:
[source,properties]
----
# SQL execution
logger.hibernate.name = org.hibernate.SQL
logger.hibernate.level = debug
# JDBC parameter binding
logger.jdbc-bind.name=org.hibernate.orm.jdbc.bind
logger.jdbc-bind.level=trace
# JDBC result set extraction
logger.jdbc-extract.name=org.hibernate.orm.jdbc.extract
logger.jdbc-extract.level=trace
# JDBC batching
logger.jdbc-batch.name=org.hibernate.orm.jdbc.batch
logger.jdbc-batch.level=trace
----
SQL logging respects the settings `hibernate.format_sql` and `hibernate.highlight_sql`, so we don't miss out on the pretty formatting and highlighting.
[[minimizing]]
=== Minimizing repetitive mapping information
The following properties are very useful for minimizing the amount of information you'll need to explicitly specify in `@Table` and `@Column` annotations, which we'll discuss below in <>:
.Settings for minimizing explicit mapping information
[%breakable,cols="35,~"]
|===
| Configuration property name | Purpose
| link:{doc-javadoc-url}org/hibernate/cfg/MappingSettings.html#DEFAULT_SCHEMA[`hibernate.default_schema`] | A default schema name for entities which do not explicitly declare one
| link:{doc-javadoc-url}org/hibernate/cfg/MappingSettings.html#DEFAULT_CATALOG[`hibernate.default_catalog`] | A default catalog name for entities which do not explicitly declare one
| link:{doc-javadoc-url}org/hibernate/cfg/MappingSettings.html#PHYSICAL_NAMING_STRATEGY[`hibernate.physical_naming_strategy`] | A `PhysicalNamingStrategy` implementing your database naming standards
| link:{doc-javadoc-url}org/hibernate/cfg/MappingSettings.html#IMPLICIT_NAMING_STRATEGY[`hibernate.implicit_naming_strategy`] | An `ImplicitNamingStrategy` which specifies how "logical" names of relational objects should be inferred when no name is specified in annotations
|===
[TIP]
// .Implement your naming standards as a `PhysicalNamingStrategy`
====
Writing your own `PhysicalNamingStrategy` and/or `ImplicitNamingStrategy` is an especially good way to reduce the clutter of annotations on your entity classes, and to implement your database naming conventions, and so we think you should do it for any nontrivial data model.
We'll have more to say about them in <>.
====
[[quoted-identifiers]]
=== Quoting SQL identifiers
By default, Hibernate never quotes a SQL table or column name in generated SQL when the name contains only alphanumeric characters.
This behavior is usually much more convenient, especially when working with a legacy schema, since unquoted identifiers aren't case-sensitive, and so Hibernate doesn't need to know or care whether a column is named `NAME`, `name`, or `Name` on the database side.
On the other hand, any table or column name containing a punctuation character, or with an initial `$` is automatically quoted by default.
The following settings enable additional automatic quoting:
.Settings for identifier quoting
[%breakable,cols="35,~"]
|===
| Configuration property name | Purpose
| link:{doc-javadoc-url}org/hibernate/cfg/MappingSettings.html#KEYWORD_AUTO_QUOTING_ENABLED[`hibernate.auto_quote_keyword`] | Automatically quote any identifier which is a SQL keyword
| link:{doc-javadoc-url}org/hibernate/cfg/MappingSettings.html#GLOBALLY_QUOTED_IDENTIFIERS[`hibernate.globally_quoted_identifiers`] | Automatically quote every identifier
|===
Note that `hibernate.globally_quoted_identifiers` is a synonym for `>.
An entity has _attributes_—properties or fields—which map to columns of the table.
In particular, every entity must have an _identifier_ or _id_, which maps to the primary key of the table.
The id allows us to uniquely associate a row of the table with an instance of the Java class, at least within a given _persistence context_.
We'll explore the idea of a persistence context <>. For now, think of it as a one-to-one mapping between ids and entity instances.
An instance of a Java class cannot outlive the virtual machine to which it belongs.
But we may think of an entity instance having a lifecycle which transcends a particular instantiation in memory.
By providing its id to Hibernate, we may re-materialize the instance in a new persistence context, as long as the associated row is present in the database.
Therefore, the operations `persist()` and `remove()` may be thought of as demarcating the beginning and end of the lifecycle of an entity, at least with respect to persistence.
Thus, an id represents the _persistent identity_ of an entity, an identity that outlives a particular instantiation in memory.
And this is an important difference between entity class itself and the values of its attributes—the entity has a persistent identity, and a well-defined lifecycle with respect to persistence, whereas a `String` or `List` representing one of its attribute values doesn't.
An entity usually has associations to other entities.
Typically, an association between two entities maps to a foreign key in one of the database tables.
A group of mutually associated entities is often called a _domain model_, though _data model_ is also a perfectly good term.
[[entity-clases]]
=== Entity classes
An entity must:
- be a non-`final` class,
- with a non-`private` constructor with no parameters.
On the other hand, the entity class may be either concrete or `abstract`, and it may have any number of additional constructors.
[TIP]
// .Inner entity classes
====
An entity class may be a `static` inner class.
====
[TIP]
====
These requirements are relaxed when the <> is used.
====
Every entity class must be annotated `@Entity`.
[source,java]
----
@Entity
class Book {
Book() {}
...
}
----
Alternatively, the class may be identified as an entity type by providing an XML-based mapping for the class.
[TIP]
====
When XML-based mappings are used, the `` element is used to declare an entity class:
[source,xml]
----
org.hibernate.example
...
...
----
Since the `orm.xml` mapping file format defined by the JPA specification was modelled closely on the annotation-based mappings, it's usually easy to go back and forth between the two options.
====
We won't have much more to say about XML-based mappings in this guide, since it's not our preferred way to do things.
.*Read more: "Dynamic" models*
[%collapsible]
====
****
:maps: {doc-user-guide-url}#dynamic-model
:envers: https://hibernate.org/orm/envers/
We love representing entities as classes because the classes give us a _type-safe_ model of our data.
But Hibernate also has the ability to represent entities as detyped instances of `java.util.Map`.
There's information in the {maps}[User Guide], if you're curious.
This must sound like a weird feature for a project that places importance on type-safety.
Actually, it's a useful capability for a very particular sort of generic code.
For example, the deprecated {envers}[Hibernate Envers] module is an auditing/versioning system for Hibernate entities.
Envers makes use of maps to represent its _versioned model_ of the data.
****
====
[[access-type]]
=== Access types
Each entity class has an _access type_, either:
- direct _field access_, or
- _property access_.
Hibernate automatically determines the access type from the location of attribute-level annotations.
Concretely:
- if a field is annotated `@Id`, field access is used, or
- if a getter method is annotated `@Id`, property access is used.
Back when Hibernate was just a baby, property access was quite popular in the Hibernate community.
Today, however, field access is _much_ more common.
[NOTE]
// .Explicit access type
====
The access type may be specified explicitly using the `@Access` annotation, but we strongly discourage this, since it's ugly and never necessary.
====
[IMPORTANT]
// .Mapping annotations should be placed consistently
====
Mapping annotations should be placed consistently:
- if `@Id` annotates a field, the other mapping annotations should also be applied to fields, or,
- if `@Id` annotates a getter, the other mapping annotations should be applied to getters.
It is in principle possible to mix field and property access using explicit `@Access` annotations at the attribute level.
We don't recommend doing this.
====
An entity class like `Book`, which does not extend any other entity class, is called a _root entity_.
Every root entity must declare an identifier attribute.
[[entity-inheritance]]
=== Entity class inheritance
An entity class may `extend` another entity class.
[source,java]
----
@Entity
class AudioBook extends Book {
AudioBook() {}
...
}
----
A subclass entity inherits every persistent attribute of every entity it extends.
A root entity may also extend another class and inherit mapped attributes from the other class.
But in this case, the class which declares the mapped attributes must be annotated `@MappedSuperclass`.
[source,java]
----
@MappedSuperclass
class Versioned {
...
}
@Entity
class Book extends Versioned {
...
}
----
A root entity class must declare an attribute annotated `@Id`, or inherit one from a `@MappedSuperclass`.
A subclass entity always inherits the identifier attribute of the root entity.
It may not declare its own `@Id` attribute.
[[identifier-attributes]]
=== Identifier attributes
An identifier attribute is usually a field:
[source,java]
----
@Entity
class Book {
Book() {}
@Id
Long id;
...
}
----
But it may be a property:
[source,java]
----
@Entity
class Book {
Book() {}
private Long id;
@Id
Long getId() { return id; }
void setId(Long id) { this.id = id; }
...
}
----
An identifier attribute must be annotated `@Id` or `@EmbeddedId`.
Identifier values may be:
- assigned by the application, that is, by your Java code, or
- generated and assigned by Hibernate.
We'll discuss the second option first.
[[generated-identifiers]]
=== Generated identifiers
An identifier is often system-generated, in which case it should be annotated `@GeneratedValue`:
[source,java]
----
@Id @GeneratedValue
Long id;
----
[TIP]
// .Using surrogate keys
====
System-generated identifiers, or _surrogate keys_ make it easier to evolve or refactor the relational data model.
If you have the freedom to define the relational schema, we recommend the use of surrogate keys.
On the other hand, if, as is more common, you're working with a pre-existing database schema, you might not have the option.
====
JPA defines the following strategies for generating ids, which are enumerated by `GenerationType`:
.Standard id generation strategies
[%breakable,cols="25,15,~"]
|===
| Strategy | Java type | Implementation
| `GenerationType.UUID` | `UUID` or `String` | A Java `UUID`
| `GenerationType.IDENTITY` | `Long` or `Integer` | An identity or autoincrement column
| `GenerationType.SEQUENCE` | `Long` or `Integer` | A database sequence
| `GenerationType.TABLE` | `Long` or `Integer` | A database table
| `GenerationType.AUTO` | `Long` or `Integer` | Selects `SEQUENCE`, `TABLE`, or `UUID` based on the identifier type and capabilities of the database
|===
For example, this UUID is generated in Java code:
[source,java]
----
@Id @GeneratedValue UUID id; // AUTO strategy selects UUID based on the field type
----
This id maps to a SQL `identity`, `auto_increment`, or `bigserial` column:
[source,java]
----
@Id @GeneratedValue(strategy = IDENTITY) Long id;
----
The `@SequenceGenerator` and `@TableGenerator` annotations allow further control over `SEQUENCE` and `TABLE` generation respectively.
Consider this sequence generator:
[source,java]
----
@SequenceGenerator(name = "bookSeq", sequenceName = "seq_book", initialValue = 5, allocationSize=10)
----
Values are generated using a database sequence defined as follows:
[source,sql]
----
create sequence seq_book start with 5 increment by 10
----
Notice that Hibernate doesn't have to go to the database every time a new identifier is needed.
Instead, a given process obtains a block of ids, of size `allocationSize`, and only needs to hit the database each time the block is exhausted.
Of course, the downside is that generated identifiers are not contiguous.
[CAUTION]
// .Check the `initialValue` and `allocationSize`
====
If you let Hibernate export your database schema, the sequence definition will have the right `start with` and `increment` values.
But if you're working with a database schema managed outside Hibernate, make sure the `initialValue` and `allocationSize` members of `@SequenceGenerator` match the `start with` and `increment` specified in the DDL.
====
Any identifier attribute may now make use of the generator named `bookSeq`:
[source,java]
----
@Id
@GeneratedValue(generator = "bookSeq") // reference to generator defined elsewhere
Long id;
----
Actually, it's extremely common to place the `@SequenceGenerator` annotation on the `@Id` attribute that makes use of it:
[source,java]
----
@Id
@GeneratedValue // uses the generator defined below
@SequenceGenerator(sequenceName = "seq_book", initialValue = 5, allocationSize=10)
Long id;
----
In this case, the `name` of the `@SequenceGenerator` should not be specified.
We may even place a `@SequenceGenerator` or `@TableGenerator` annotation at the package level:
[source,java]
----
@SequenceGenerator(sequenceName = "id_sequence", initialValue = 5, allocationSize=10)
@TableGenerator(table = "id_table", initialValue = 5, allocationSize=10)
package org.example.entities;
----
Then any entity in this package which specifies `strategy=SEQUENCE` or `strategy=TABLE` without also explicitly specifying a generator `name` is assigned a generator based on the package-level annotation.
[source,java]
----
@Id
@GeneratedValue(strategy=SEQUENCE) // uses the sequence generator defined at the package level
Long id;
----
// [NOTE]
// // .JPA id generators may be shared between entities
// ====
// JPA id generators may be shared between entities.
// A `@SequenceGenerator` or `@TableGenerator` must have a name, and may be shared between multiple id attributes.
// This fits somewhat uncomfortably with the common practice of annotating the `@Id` attribute which makes use of the generator!
// ====
As you can see, JPA provides quite adequate support for the most common strategies for system-generated ids.
However, the annotations themselves are a bit more intrusive than they should be, and there's no well-defined way to extend this framework to support custom strategies for id generation.
Nor may `@GeneratedValue` be used on a property not annotated `@Id`.
Since custom id generation is a rather common requirement, Hibernate provides a very carefully-designed framework for user-defined ``Generator``s, which we'll discuss in <>.
[[natural-identifiers]]
=== Natural keys as identifiers
Not every identifier attribute maps to a (system-generated) surrogate key.
Primary keys which are meaningful to the user of the system are called _natural keys_.
When the primary key of a table is a natural key, we don't annotate the identifier attribute `@GeneratedValue`, and it's the responsibility of the application code to assign a value to the identifier attribute.
[source,java]
----
@Entity
class Book {
@Id
String isbn;
...
}
----
Of particular interest are natural keys which comprise more than one database column, and such natural keys are called _composite keys_.
[[composite-identifiers]]
=== Composite identifiers
If your database uses composite keys, you'll need more than one identifier attribute.
There are two ways to map composite keys in JPA:
- using an `@IdClass`, or
- using an `@EmbeddedId`.
Perhaps the most immediately-natural way to represent this in an entity class is with multiple fields annotated `@Id`, for example:
[source,java]
----
@Entity
@IdClass(BookId.class)
class Book {
Book() {}
@Id
String isbn;
@Id
int printing;
...
}
----
But this approach comes with a problem: what object can we use to identify a `Book` and pass to methods like `find()` which accept an identifier?
The solution is to write a separate class with fields that match the identifier attributes of the entity.
Every such id class must override `equals()` and `hashCode()`.
Of course, the easiest way to satisfy these requirements is to declare the id class as a `record`.
[source,java]
----
record BookId(String isbn, int printing) {}
----
The `@IdClass` annotation of the `Book` entity identifies `BookId` as the id class to use for that entity.
This is not our preferred approach.
Instead, we recommend that the `BookId` class be declared as an `@Embeddable` type:
[source,java]
----
@Embeddable
record BookId(String isbn, int printing) {}
----
We'll learn more about <> below.
Now the entity class may reuse this definition using `@EmbeddedId`, and the `@IdClass` annotation is no longer required:
[source,java]
----
@Entity
class Book {
Book() {}
@EmbeddedId
BookId bookId;
...
}
----
This second approach eliminates some duplicated code.
Either way, we may now use `BookId` to obtain instances of `Book`:
[source,java]
----
Book book = session.find(Book.class, new BookId(isbn, printing));
----
[[version-attributes]]
=== Version attributes
An entity may have an attribute which is used by Hibernate for <>.
A _version attribute_ is usually of type `Integer`, `Short`, `Long`, `LocalDateTime`, `OffsetDateTime`, `ZonedDateTime`, or `Instant`.
[source,java]
----
@Version
int version;
----
[source,java]
----
@Version
LocalDateTime lastUpdated;
----
A version attribute is automatically assigned by Hibernate when an entity is made persistent, and automatically incremented or updated each time the entity is updated.
If the version attribute is numeric, then an entity is, by default, assigned the version number `0` when it's first made persistent.
It's easy to specify that the initial version should be assigned the number `1` instead:
[source,java]
----
@Version
int version = 1; // the initial version number
----
If the version attribute is an `Instant` or datetime, the value assigned to the attribute is generated in the JVM by default.
[TIP]
====
If the datetime value should be generated by the database, the `@Version` annotation may be used in conjunction with a <>, for example:
[source,java]
----
@CurrentTimestamp @Version
LocalDateTime lastUpdated;
----
====
Almost every entity which is frequently updated should have a version attribute.
The `@ExcludedFromVersioning` annotation lets us selectively exclude a certain field from optimistic locking, so that modifications to the annotated field do not result in a version increment.
[TIP]
// .Optimistic locking in Hibernate
====
If an entity doesn't have a version number, which often happens when mapping legacy data, we can still do optimistic locking.
The link:{doc-javadoc-url}org/hibernate/annotations/OptimisticLocking.html[`@OptimisticLocking`] annotation lets us specify that optimistic locks should be checked by validating the values of `ALL` fields, or only the `DIRTY` fields of the entity.
And the `@ExcludedFromVersioning` annotation lets us selectively exclude certain fields from validation.
====
The `@Id` and `@Version` attributes we've already seen are just specialized examples of _basic attributes_.
[[natural-id-attributes]]
=== Natural id attributes
Even when an entity has a surrogate key, it should always be possible to write down a combination of fields which uniquely identifies an instance of the entity, from the point of view of the user of the system.
This combination of fields is its natural key.
Above, we <> the case where the natural key coincides with the primary key.
Here, the natural key is a second unique key of the entity, distinct from its surrogate primary key.
[IMPORTANT]
// .What if my entity has no natural key?
====
If you can't identify a natural key, it might be a sign that you need to think more carefully about some aspect of your data model.
If an entity doesn't have a meaningful unique key, then it's impossible to say what event or object it represents in the "real world" outside your program.
====
Since it's _extremely_ common to retrieve an entity based on its natural key, Hibernate has a way to mark the attributes of the entity which make up its natural key.
Each attribute must be annotated link:{doc-javadoc-url}org/hibernate/annotations/NaturalId.html[`@NaturalId`].
[source,java]
----
@Entity
class Book {
Book() {}
@Id @GeneratedValue
Long id; // the system-generated surrogate key
@NaturalId
String isbn; // belongs to the natural key
@NaturalId
int printing; // also belongs to the natural key
...
}
----
Hibernate automatically generates a `UNIQUE` constraint on the columns mapped by the annotated fields.
[TIP]
====
Consider using the natural id attributes to implement <>.
====
If the natural id is a composite key spanning multiple attributes, a link:{doc-javadoc-url}org/hibernate/annotations/NaturalIdClass.html[`@NaturalIdClass`] may be used.
This is very similar to the `@IdClass` annotation we <>.
[source,java]
----
record BookKey(String isbn, int printing) {}
@Entity
@NaturalIdClass(BookKey.class)
class Book {
...
}
----
The payoff for doing this extra work, as we will see <>, is that we can take advantage of optimized natural id lookups that make use of the second-level cache.
Note that even when you've identified a natural key, we still recommend the use of a generated surrogate key in foreign keys, since this makes your data model _much_ easier to change.
[[basic-attributes]]
=== Basic attributes
A _basic_ attribute of an entity is a field or property which maps to a single column of the associated database table.
The JPA specification defines a quite limited set of basic types:
[[basic-type-list]]
.JPA-standard basic attribute types
[%breakable,cols="30,^14,~"]
|====
| Classification | Package | Types
| Primitive types | | `boolean`, `int`, `double`, etc
| Primitive wrappers | `java.lang` | `Boolean`, `Integer`, `Double`, etc
| Strings | `java.lang` | `String`
| Arbitrary-precision numeric types | `java.math` | `BigInteger`, `BigDecimal`
| UUIDs | `java.util` | `UUID`
| Date/time types | `java.time` | `LocalDate`, `LocalTime`, `LocalDateTime`, `OffsetDateTime`, `Instant`, `Year`
| Deprecated date/time types 💀 | `java.util` | `Date`, `Calendar`
| Deprecated JDBC date/time types 💀 | `java.sql` | `Date`, `Time`, `Timestamp`
| Binary and character arrays | | `byte[]`, `char[]`
| Binary and character wrapper arrays 💀 | `java.lang` | `Byte[]`, `Character[]`
| Enumerated types | | Any `enum`
| Serializable types | | Any type which implements `java.io.Serializable`
|====
[IMPORTANT]
// .Please don't use `Date`!
====
We're begging you to use types from the `java.time` package instead of anything which inherits `java.util.Date`.
====
[WARNING]
====
The use of `Byte[]` and `Character[]` as basic types was deprecated by Jakarta Persistence 3.2.
Hibernate does not allow `null` elements in such arrays.
Use `byte[]` or `char[]` instead.
====
[CAUTION]
// .Serialization is usually a bad idea
====
Serializing a Java object and storing its binary representation in the database is usually wrong.
As we'll soon see in <>, Hibernate has much better ways to handle complex Java objects.
====
Hibernate slightly extends this list with the following types:
.Additional basic attribute types in Hibernate
[%breakable,cols="30,^14,56"]
|====
| Classification | Package | Types
| Additional date/time types | `java.time` | `Duration`, `ZoneId`, `ZoneOffset`, and even `ZonedDateTime`
| JDBC LOB types | `java.sql` | `Blob`, `Clob`, `NClob`
| Java class object | `java.lang` | `Class`
| Internet addresses | `java.net` | `InetAddress`
| Miscellaneous types | `java.util` | `Currency`, `Locale`, `URL`, `TimeZone`
|====
The `@Basic` annotation explicitly specifies that an attribute is basic, but it's often not needed, since attributes are assumed basic by default.
On the other hand, if a non-primitively-typed attribute cannot be null, use of `@Basic(optional=false)` is highly recommended.
[source,java]
----
@Basic(optional=false) String firstName;
@Basic(optional=false) String lastName;
String middleName; // may be null
----
Alternatively, use the Jakarta `@Nonnull` annotation.
[source,java]
----
@Nonnull String firstName;
@Nonnull String lastName;
String middleName; // may be null
----
Note that primitively-typed attributes are inferred `NOT NULL` by default.
.*Read more: Not-null columns*
[%collapsible]
====
****
Until JPA 4, there were two standard ways to add a `NOT NULL` constraint to a mapped column in JPA:
1. using `@Basic(optional=false)`, or
2. using `@Column(nullable=false)`.
You might wonder what the difference is.
Well, it's perhaps not obvious to a casual user of the JPA annotations, but they actually come in two "layers":
- annotations like `@Entity`, `@Id`, and `@Basic` belong to the _logical_ layer, the subject of the current chapter—they specify the semantics of your Java domain model, whereas
- annotations like `@Table` and `@Column` belong to the _mapping_ layer, the topic of the <>—they specify how elements of the domain model map to objects in the relational database.
Information may be inferred from the logical layer down to the mapping layer, but is never inferred in the opposite direction.
Now, the `@Column` annotation, to whom we'll be properly <> a bit later, belongs to the _mapping_ layer, and so its `nullable` member only affects schema generation (resulting in a `not null` constraint in the generated DDL).
On the other hand, the `@Basic` annotation belongs to the logical layer, and so an attribute marked `optional=false` is checked by Hibernate before it even writes an entity to the database.
Note that:
- `optional=false` implies `nullable=false`, but
- `nullable=false` _does not_ imply `optional=false`.
Therefore, we prefer `@Basic(optional=false)` to `@Column(nullable=false)`.
But wait!
JPA 4 provides two additional options:
1. Use `@Nonnull` from `jakarta.annotation`, or
2. use the `@NotNull` constraint from Bean Validation.footnote:[You'll need to add Hibernate Validator to your project build, as described in <>.]
We think that these are easier on the eyes.
****
====
[[enums]]
=== Enumerated types
We included Java ``enum``s on the list above.
An enumerated type is considered a sort of basic type, but since most databases don't have a native `ENUM` type, JPA provides a special `@Enumerated` annotation to specify how the enumerated values should be represented in the database:
- by default, an enum is stored as an integer, the value of its `ordinal()` member, but
- if the attribute is annotated `@Enumerated(STRING)`, it is stored as a string, the value of its `name()` member.
[source,java]
----
//here, an ORDINAL encoding makes sense
@Enumerated
@Basic(optional=false)
DayOfWeek dayOfWeek;
//but usually, a STRING encoding is better
@Enumerated(EnumType.STRING)
@Basic(optional=false)
Status status;
----
The `@EnumeratedValue` annotation allows the column value to be customized:
[source,java]
----
enum Resolution {
UNRESOLVED(0), FIXED(1), REJECTED(-1);
@EnumeratedValue // store the code, not the enum ordinal() value
final int code;
Resolution(int code) {
this.code = code;
}
}
----
Since Hibernate 6, an `enum` annotated `@Enumerated(STRING)` is mapped to:
- a `VARCHAR` column type with a `CHECK` constraint on most databases, or
- an `ENUM` column type on MySQL.
Any other ``enum`` is mapped to a `TINYINT` column with a `CHECK` constraint.
[TIP]
// .It's usually better to persist `enum` values by their names
====
JPA picks the wrong default here.
In most cases, storing an integer encoding of the `enum` value makes the relational data harder to interpret.
Even considering `DayOfWeek`, the encoding to integers is ambiguous.
If you check `java.time.DayOfWeek`, you'll notice that `SUNDAY` is encoded as `6`.
But in the country I was born, `SUNDAY` is the _first_ day of the week!
So we prefer `@Enumerated(STRING)` for most `enum` attributes.
====
An interesting special case arises on PostgreSQL and Oracle.
[[named-enums]]
[TIP]
====
Some databases support _named_ `ENUM` types, which must be declared using in DDL using:
- `CREATE TYPE ... AS ENUM` on PostgreSQL, or
- `CREATE DOMAIN ... AS ENUM` on Oracle.
These look like a perfect match for Java ``enum``s, which also have names!
Sadly, these `ENUM` types aren't well-integrated with the SQL language, nor well-supported by the JDBC drivers, so Hibernate doesn't use them by default.
But if you would like to use a named enumerated type on Postgres or Oracle, just annotate your `enum` attribute like this:
[source,java]
----
@JdbcTypeCode(SqlTypes.NAMED_ENUM)
@Basic(optional=false)
Status status;
----
Alternatively, you may enable the configuration property link:{doc-javadoc-url}org/hibernate/cfg/MappingSettings.html#PREFER_NATIVE_ENUM_TYPES[`hibernate.type.prefer_native_enum_types`].
====
The limited set of pre-defined basic attribute types can be stretched a bit further by supplying a _converter_.
[[converters]]
=== Converters
A JPA `AttributeConverter` is responsible for:
- converting a given Java type to one of the types listed above, and/or
- perform any other sort of pre- and post-processing you might need to perform on a basic attribute value before writing and reading it to or from the database.
Converters substantially widen the set of attribute types that can be handled by JPA.
There are two ways to apply a converter:
- the `@Convert` annotation applies an `AttributeConverter` to a particular entity attribute, or
- the `@Converter` annotation (or, alternatively, the `@ConverterRegistration` annotation) registers an `AttributeConverter` for automatic application to all attributes of a given type.
`@ConverterRegistration` should preferably be placed on a `package-info.java` or `module-info.java`.
For example, the following converter is automatically applied to any attribute of type `EnumSet`, and takes care of persisting the `EnumSet` to a column of type `INTEGER`:
[source,java]
----
@Converter(autoApply = true)
public static class EnumSetConverter
// converts Java values of type EnumSet to integers for storage in an INT column
implements AttributeConverter,Integer> {
@Override
public Integer convertToDatabaseColumn(EnumSet enumSet) {
int encoded = 0;
var values = DayOfWeek.values();
for (int i = 0; i convertToEntityAttribute(Integer encoded) {
var set = EnumSet.noneOf(DayOfWeek.class);
var values = DayOfWeek.values();
for (int i = 0; i daysOfWeek;
----
[CAUTION]
====
Converters are supposed to be used for type conversion.
Some enterprising members of the community have noticed that they can be (mis)used to perform other tasks: trimming whitespace, normalizing case, assigning a default value in place of `null`, and so on.
Hibernate _tolerates_ but does not encourage such (mis)use.
In particular, we strongly recommend against defining an `autoApply` converter acting on a <>.
====
All this is nice, but it probably won't surprise you that Hibernate goes beyond what is required by JPA.
[[compositional-basic-types]]
=== Compositional basic types
Hibernate considers a "basic type" to be formed by the marriage of two objects:
- a `JavaType`, which models the semantics of a certain Java class, and
- a `JdbcType`, representing a SQL type which is understood by JDBC.
When mapping a basic attribute, we may explicitly specify a `JavaType`, a `JdbcType`, or both.
[[java-type]]
[discrete]
==== JavaType
An instance of `org.hibernate.type.descriptor.java.JavaType` represents a particular Java class.
It's able to:
- compare instances of the class to determine if an attribute of that class type is dirty (modified),
- produce a useful hash code for an instance of the class,
- coerce values to other types, and, in particular,
- convert an instance of the class to one of several other equivalent Java representations at the request of its partner `JdbcType`.
For example, `IntegerJavaType` knows how to convert an `Integer` or `int` value to the types `Long`, `BigInteger`, and `String`, among others.
We may explicitly specify a Java type using the `@JavaType` annotation, but for the built-in ``JavaType``s this is never necessary.
[source,java]
----
@JavaType(LongJavaType.class) // not needed, this is the default JavaType for long
long currentTimeMillis;
----
For a user-written `JavaType`, the annotation is more useful:
[source,java]
----
@JavaType(BitSetJavaType.class)
BitSet bitSet;
----
Alternatively, the `@JavaTypeRegistration` annotation may be used to register `BitSetJavaType` as the default `JavaType` for `BitSet`.
This annotation should preferably be placed on a `package-info.java` or `module-info.java`.
[[jdbc-type]]
[discrete]
==== JdbcType
An `org.hibernate.type.descriptor.jdbc.JdbcType` is able to read and write a single Java type from and to JDBC.
For example, `VarcharJdbcType` takes care of:
- writing Java strings to JDBC ``PreparedStatement``s by calling `setString()`, and
- reading Java strings from JDBC ``ResultSet``s using `getString()`.
By pairing `LongJavaType` with `VarcharJdbcType` in holy matrimony, we produce a basic type which maps ``Long``s and primitive ``longs``s to the SQL type `VARCHAR`.
We may explicitly specify a JDBC type using the `@JdbcType` annotation.
[source,java]
----
@JdbcType(VarcharJdbcType.class)
long currentTimeMillis;
----
Alternatively, we may specify a JDBC type code:
[source,java]
----
@JdbcTypeCode(Types.VARCHAR)
long currentTimeMillis;
----
The `@JdbcTypeRegistration` annotation may be used to register a user-written `JdbcType` as the default for a given SQL type code.
This annotation should preferably be placed on a `package-info.java` or `module-info.java`.
[NOTE]
====
The types defined by the JDBC specification are enumerated by the integer type codes in the class `java.sql.Types`.
Each JDBC type is an abstraction of a commonly-available type in SQL.
For example, `Types.VARCHAR` represents the SQL type `VARCHAR` (or `VARCHAR2` on Oracle).
Since Hibernate understands more SQL types than JDBC, there's an extended list of integer type codes in the class link:{doc-javadoc-url}org/hibernate/type/SqlTypes.html[`org.hibernate.type.SqlTypes`].
For example, `SqlTypes.GEOMETRY` represents the spatial data type `GEOMETRY`.
====
[discrete]
==== AttributeConverter
If a given `JavaType` doesn't know how to convert its instances to the type required by its partner `JdbcType`, we must help it out by providing a JPA `AttributeConverter` to perform the conversion.
For example, to form a basic type using `LongJavaType` and `TimestampJdbcType`, we would provide an `AttributeConverter`.
[source,java]
----
@JdbcType(TimestampJdbcType.class)
@Convert(converter = LongToTimestampConverter.class)
long currentTimeMillis;
----
Let's abandon our analogy right here, before we start calling this basic type a "throuple".
[[datetime-types]]
=== Date and time types, and time zones
Dates and times should always be represented using the types defined in `java.time`.
[WARNING]
====
Never use the legacy types `java.sql.Date`, `java.sql.Time`, `java.sql.Timestamp`, or `java.util.Date`.
At our urging, support for these types has even been https://in.relation.to/2024/04/22/stop-using-date/[officially deprecated in JPA 3.2].
Eventually, we hope to completely remove support for these types from the JPA spec and from Hibernate.
====
Some of the types in `java.time` map naturally to an ANSI SQL column type.
A source of confusion is that some databases still don't follow the ANSI standard naming here.
Also, as you're probably aware, the `DATE` type on Oracle is not an ANSI SQL `DATE`.
In fact, Oracle doesn't have `DATE` or `TIME` types--every date or time must be stored as a timestamp.
.Type mappings from `java.time` to ANSI SQL
|====
| `java.time` class | ANSI SQL type | MySQL | SQL Server | Oracle
| `LocalDate` | `DATE` | `DATE` | `DATE` | `DATE` 💀
| `LocalTime` | `TIME` | `TIME` | `TIME` | `TIMESTAMP` 💀
| `LocalDateTime` | `TIMSTAMP` | `DATETIME` | `DATETIME2` | `TIMESTAMP`
| `OffsetDateTime`, `ZonedDateTime` | `TIMESTAMP WITH TIME ZONE` | `TIMESTAMP` 🙄 | `DATETIMEOFFSET` | `TIMESTAMP WITH TIME ZONE`
|====
On the other hand, there are no perfectly natural mappings for `Instant` and `Duration` on most databases.
By default:
- `Duration` is mapped to a column of type `NUMERIC(21)` holding the length of the duration in nanoseconds, and
- `Instant` is mapped to a column of type `TIMESTAMP` (`DATETIME` on MySQL) or TIMESTAMP WITH TIME ZONE, depending on the database.
Fortunately, these mappings can be modified by specifying the `JdbcType`.
For example, if we wanted to store an `Instant` using `TIMESTAMP WITH TIME ZONE` (`TIMESTAMP` on MySQL) instead of `TIMESTAMP`, then we could annotate the field:
[source,java]
----
// store the Instant as a TIMESTAMP WITH TIME ZONE, instead of as a TIMESTAMP
@JdbcTypeCode(SqlTypes.TIMESTAMP_WITH_TIMEZONE)
Instant instant;
----
Alternatively, we could set the configuration property `hibernate.type.preferred_instant_jdbc_type`:
[source,java]
----
// store field of type Instant as TIMESTAMP WITH TIME ZONE, instead of as a TIMESTAMP
config.setProperty(MappingSettings.PREFERRED_INSTANT_JDBC_TYPE, SqlTypes.TIMESTAMP_WITH_TIMEZONE);
----
We have worked very hard to make sure that Java date and time types work with consistent and correct semantics across all databases supported by Hibernate.
In particular, Hibernate is very careful in how it handles time zones.
[WARNING]
====
Unfortunately, with the notable exception of Oracle, most SQL databases feature embarrassingly poor support for timezones.
Even some databases which do supposedly support `TIMESTAMP WITH TIME ZONE` simply covert the datetime to UTC.
Here, Hibernate is limited by the capabilities of the databases themselves, and so on many databases, time zone information will not, by default, be preserved for an `OffsetDateTime` or `ZonedDateTime`.
====
[TIP]
====
The still-experimental annotation link:{doc-javadoc-url}org/hibernate/annotations/TimeZoneStorage.html[`@TimeZoneStorage`] provides some additional options in case the default behavior falls short.
//
// [source,java]
// ----
// @TimeZoneStorage(COLUMN)
// @TimeZoneColumn(name = "event_offset")
// @Column(name = "event_timestamp")
// private OffsetDateTime eventDateTime;
// ----
====
[[embeddable-objects]]
=== Embeddable objects
An embeddable object is a Java class whose state maps to multiple columns of a table, but which doesn't have its own persistent identity.
That is, it's a class with mapped attributes, but no `@Id` attribute.
An embeddable object can only be made persistent by assigning it to the attribute of an entity.
Since the embeddable object does not have its own persistent identity, its lifecycle with respect to persistence is completely determined by the lifecycle of the entity to which it belongs.
An embeddable class must be annotated `@Embeddable` instead of `@Entity`.
[source,java]
----
@Embeddable
class Name {
@Basic(optional=false)
String firstName;
@Basic(optional=false)
String lastName;
String middleName;
Name() {}
Name(String firstName, String middleName, String lastName) {
this.firstName = firstName;
this.middleName = middleName;
this.lastName = lastName;
}
...
}
----
An embeddable class must satisfy the same requirements that entity classes satisfy, with the exception that an embeddable class has no `@Id` attribute.
In particular, it must have a constructor with no parameters.
Alternatively, an embeddable type may be defined as a Java record type:
[source,java]
----
@Embeddable
record Name(String firstName, String middleName, String lastName) {}
----
In this case, the requirement for a constructor with no parameters is relaxed.
We may now use our `Name` class (or record) as the type of an entity attribute:
[source,java]
----
@Entity
class Author {
@Id @GeneratedValue
Long id;
Name name;
...
}
----
Embeddable types can be nested.
That is, an `@Embeddable` class may have an attribute whose type is itself a different `@Embeddable` class.
[TIP]
// .The `@Embedded` annotation is not required
====
JPA provides an `@Embedded` annotation to identify an attribute of an entity that refers to an embeddable type.
This annotation is completely optional, and so we don't usually use it.
====
Usually, embeddable types are stored in a "flattened" format.
Their attributes map columns of the table of their parent entity.
Later, in <>, we'll see a couple of different options.
An attribute of embeddable type represents a relationship between a Java object with a persistent identity, and a Java object with no persistent identity.
We can think of it as a whole/part relationship.
The embeddable object belongs to the entity, and can't be shared with other entity instances.
And it exists for only as long as its parent entity exists.
Since Hibernate 6.6, an embedded attribute whose declared type is an embeddable class with embeddable subclasses is fully polymorphic.
Next we'll discuss a different kind of relationship: a relationship between Java objects which each have their own distinct persistent identity and persistence lifecycle.
[[associations]]
=== Associations
An _association_ is a relationship between entities.
We usually classify associations based on their _multiplicity_.
If `R` and `F` are both entity classes, then:
- a _one-to-one_ association relates at most one unique instance `R` with at most one unique instance of `F`,
- a _many-to-one_ association relates zero or more instances of `R` with a unique instance of `F`, and
- a _many-to-many_ association relates zero or more instances of `R` with zero or more instance of `F`.
An association between entity classes may be either:
- _unidirectional_, navigable from `R` to `F` but not from `F` to `R`, or
- _bidirectional_, and navigable in either direction.
In this example data model, we can see the sorts of associations which are possible:
image::images/associations.png[Example data model,align="center",pdfwidth=90%]
[%unbreakable]
[TIP]
// .One-to-one associations and subtyping
====
An astute observer of the diagram above might notice that the relationship we've presented as a unidirectional one-to-one association could reasonably be represented in Java using subtyping.
This is quite normal.
A one-to-one association is the usual way we implement subtyping in a fully-normalized relational model.
It's related to the `JOINED` <> strategy.
====
There are three annotations for mapping associations: `@ManyToOne`, `@OneToMany`, and `@ManyToMany`.
They share some common annotation members:
.Association-defining annotation members
[%breakable,cols="13,~,35"]
|===
| Member | Interpretation | Default value
| `cascade` | Persistence operations which should <> to the associated entity; a list of ``CascadeType``s | `{}`
| `fetch` | Whether the association is <> <> or may be <>
a|
- `LAZY` for `@OneToMany` and `@ManyToMany`
- `EAGER` for `@ManyToOne` 💀💀💀
| `targetEntity` | The associated entity class | Determined from the attribute type declaration
| `optional` | For a `@ManyToOne` or `@OneToOne` association, whether the association can be `null` | `true`
| `mappedBy` | For a bidirectional association, an attribute of the associated entity which maps the association | By default, the association is assumed unidirectional
|===
We'll explain the effect of these members as we consider the various types of association mapping.
It's not a requirement to represent _every_ foreign key relationship as an association at the Java level.
It's perfectly acceptable to replace a `@ManyToOne` mapping with a basic-typed attribute holding an identifier, if it's inconvenient to think of this relationship as an association at the Java level.
That said, it's possible to take this idea way too far.
.*Read more: 💀 Aggregates 💀*
[%collapsible]
====
****
It's come to our attention that a vocal group of people advocate that Java entity classes should be broken up into tiny disconnected islands they call "aggregates". An aggregate--at least as a first approximation--corresponds roughly to what we would usually call a parent/child relationship.
Simple examples of aggregates might be `Order`/`Item`, or `Product`/`Part`.
According to this way of thinking, there should be no associations _between_ aggregates.
So the `Item.product` association should be replaced with `productId`, `Part.manufacturer` should be replaced with `manufacturerId`, and so on.
(Of course, the word "aggregate" may also be employed in other senses, but this is the sense we're discussing right now.)
In the example we've been using, `Book` would not be permitted to have a collection of entity type `Author`, and should instead hold only the ids of the authors, or perhaps instances of some `BookAuthor` type which duplicates some state of `Author` and is disconnected from the rest of the model.
Let's stipulate that this might be a perfectly natural thing to do in certain contexts, for example, when accessing a document database.
But one context where it doesn't usually make sense is when accessing a relational database via Hibernate.
The reason is that Hibernate offers <> for optimizing access to associated data, including:
- the <>, and
- join, batch, and subselect fetching, whether via HQL, <>, or <>.
But all this functionality is lost if Hibernate doesn't know it's dealing with an association, inevitably making the application program much more vulnerable to problems with <>, just as soon as we encounter a business requirement which involves data from more than one aggregate.
(Always keep in mind that business requirements change much faster than relational data models!)
To put it mildly: this is not how JPA was ever intended to be used.
It's difficult to respond charitably to most of the arguments in favor of this approach, since most of them don't rise above the level of hand-waving at boxes on drawn on whiteboards.
An argument we _can_ respond to is the concern that transparent lazy fetching can lead to "accidental" fetching of an association and the potential for N+1 selects.
This is a legit concern, and one we worry about too, but where it's really a problem we have a much better solution: just use a `EntityAgent`, or a stateless Jakarta Data repository, where <>.
Indeed, `EntityAgent` even guards against accidental _updates_, since `update()` is always an explicit operation.
****
====
Now that we know that associations are actually good and useful, let's see how to model the various kinds of association we might find need to map to a relational data model.
We begin with the most common association multiplicity.
[[many-to-one]]
=== Many-to-one
A many-to-one association is the most basic sort of association we can imagine.
It maps completely naturally to a foreign key in the database.
Almost all the associations in your domain model are going to be of this form.
[TIP]
// .One-to-many join table mappings
====
Later, we'll see how to map a many-to-one association to an <>.
====
The `@ManyToOne` annotation marks the "to one" side of the association, so a unidirectional many-to-one association looks like this:
[source,java]
----
class Book {
@Id @GeneratedValue
Long id;
@ManyToOne(fetch=LAZY)
Publisher publisher;
...
}
----
Here, the `Book` table has a foreign key column holding the identifier of the associated `Publisher`.
[[lazy-problem]]
[WARNING]
// .Almost all associations should be lazy
====
A very unfortunate misfeature of JPA is that `@ManyToOne` associations are fetched eagerly by default.
This is almost never what we want.
Almost all associations should be lazy.
The only scenario in which `fetch=EAGER` makes sense is if we think there's always a _very_ high probability that the <>.
Whenever this isn't the case, remember to explicitly specify `fetch=LAZY`.
Or, even better, configure Hibernate with a `LAZY` default fetch mode for to-one associations using `` or `defaultToOneFetchType()`.
====
Most of the time, we would like to be able to easily navigate our associations in both directions.
We do need a way to get the `Publisher` of a given `Book`, but we would also like to be able to obtain all the ``Book``s belonging to a given publisher.
To make this association bidirectional, we need to add a collection-valued attribute to the `Publisher` class, and annotate it `@OneToMany`.
[NOTE]
====
Hibernate needs to <> unfetched associations at runtime.
Therefore, the many-valued side must be declared using an interface type like `Set` or `List`, and never using a concrete type like `HashSet` or `ArrayList`.
====
To indicate clearly that this is a bidirectional association, and to reuse any mapping information already specified in the `Book` entity, we must use the `mappedBy` annotation member to refer back to `Book.publisher`.
[source,java]
----
@Entity
class Publisher {
@Id @GeneratedValue
Long id;
@OneToMany(mappedBy="publisher")
Set books;
...
}
----
The `Publisher.books` field is called the _unowned_ side of the association.
Now, we passionately _hate_ the stringly-typed `mappedBy` reference to the owning side of the association.
Thankfully, the <> gives us a way to make it a
bit more type safe:
[[mapped-by-metamodel]]
[source,java]
----
@OneToMany(mappedBy=Book_.PUBLISHER) // get used to doing it this way!
Set books;
----
We're going to use this approach for the rest of the Short Guide.
To modify a bidirectional association, we must change the _owning side_.
[[bidirectional-problem]]
[WARNING]
// .To modify a bidirectional association, you must change the _owning side_!
====
Changes made to the unowned side of an association are never synchronized to the database.
If we desire to change an association in the database, we must change it from the owning side.
Here, we must set `Book.publisher`.
In fact, it's often necessary to change _both sides_ of a bidirectional association.
For example, if the collection `Publisher.books` was stored in the second-level cache, we must also modify the collection, to ensure that the second-level cache remains synchronized with the database.
====
That said, it's _not_ a hard requirement to update the unowned side, at least if you're sure you know what you're doing.
Here we've used `Set` as the type of the collection, but Hibernate also allows the use of `List` or `Collection` here, with almost no difference in semantics.
In particular, the `List` may not contain duplicate elements, and its order will not be persistent.
[source,java]
----
@OneToMany(mappedBy=Book_.PUBLISHER)
Collection books;
----
We'll see how to map a collection with a persistent order <>.
[[set-vs-list]]
.*Read more: Set, List, or Collection?*
[%collapsible]
====
****
A one-to-many association mapped to a foreign key can never contain duplicate elements, so `Set` seems like the most semantically correct Java collection type to use here, and so that's the conventional practice in the Hibernate community.
The catch associated with using a set is that we must carefully ensure that `Book` has a high-quality implementation of <>.
Now, that's not necessarily a bad thing, since a quality `equals()` is independently useful.
But what if we used `Collection` or `List` instead?
Then our code would be much less sensitive to how `equals()` and `hashCode()` were implemented.
In the past, we were perhaps too dogmatic in recommending the use of `Set`.
Now? I guess we're happy to let you guys decide.
In hindsight, we could have done more to make clear that this was always a viable option.
****
====
[[one-to-one-fk]]
=== One-to-one (first way)
The simplest sort of one-to-one association is almost exactly like a `@ManyToOne` association, except that it maps to a foreign key column with a `UNIQUE` constraint.
[TIP]
// .One-to-many join table mappings
====
Later, we'll see how to map a one-to-one association to an <>.
====
A one-to-one association must be annotated `@OneToOne`:
[source,java]
----
@Entity
class Author {
@Id @GeneratedValue
Long id;
@OneToOne(optional=false, fetch=LAZY)
Person person;
...
}
----
Here, the `Author` table has a foreign key column holding the identifier of the associated `Person`.
[TIP]
// .One-to-one associations are a way to represent subtyping
====
A one-to-one association often models a "type of" relationship.
In our example, an `Author` is a type of `Person`.
An alternative—and often more natural—way to represent "type of" relationships in Java is via <>.
====
We can make this association bidirectional by adding a reference back to the `Author` in the `Person` entity:
[source,java]
----
@Entity
class Person {
@Id @GeneratedValue
Long id;
@OneToOne(mappedBy = Author_.PERSON)
Author author;
...
}
----
`Person.author` is the unowned side, because it's the side marked `mappedBy`.
[NOTE]
====
Notice that we did not declare the unowned end of the association `fetch=LAZY`.
That's because:
1. not every `Person` has an associated `Author`, and
2. the foreign key is held in the table mapped by `Author`, not in the table mapped by `Person`.
Therefore, Hibernate can't tell if the reference from `Person` to `Author` is `null` without fetching the associated `Author`.
On the other hand, if _every_ `Person` was an `Author`, that is, if the association were non-`optional`, we would not have to consider the possibility of `null` references, and we would map it like this:
[source,java]
----
@OneToOne(optional=false, mappedBy = Author_.PERSON, fetch=LAZY)
Author author;
----
====
This is not the only sort of one-to-one association.
[[one-to-one-pk]]
=== One-to-one (second way)
An arguably more elegant way to represent such a relationship is to share a primary key between the two tables.
To use this approach, the `Author` class must be annotated like this:
[source,java]
----
@Entity
class Author {
@Id
Long id;
@OneToOne(optional=false, fetch=LAZY)
@MapsId
Person person;
...
}
----
Notice that, compared with the previous mapping:
- the `@Id` attribute is no longer a `@GeneratedValue` and,
- instead, the `author` association is annotated `@MapsId`.
This lets Hibernate know that the association to `Person` is the source of primary key values for `Author`.
Here, there's no extra foreign key column in the `Author` table, since the `id` column holds the identifier of `Person`.
That is, the primary key of the `Author` table does double duty as the foreign key referring to the `Person` table.
The `Person` class doesn't change.
If the association is bidirectional, we annotate the unowned side `@OneToOne(mappedBy = Author_.PERSON)` just as before.
[[many-to-many]]
=== Many-to-many
A unidirectional many-to-many association is represented as a collection-valued attribute.
It always maps to a separate <> in the database.
It tends to happen that a many-to-many association eventually turns out to be an entity in disguise.
[TIP]
====
Suppose we start with a nice clean many-to-many association between `Author` and `Book`.
Later on, it's quite likely that we'll discover some additional information which comes attached to the association, so that the association table needs some extra columns.
For example, imagine that we needed to report the percentage contribution of each author to a book.
That information naturally belongs to the association table.
We can't easily store it as an attribute of `Book`, nor as an attribute of `Author`.
When this happens, we need to change our Java model, usually introducing a new entity class which maps the association table directly.
In our example, we might call this entity something like `BookAuthorship`, and it would have `@OneToMany` associations to both `Author` and `Book`, along with the `contribution` attribute.
We can evade the disruption occasioned by such "discoveries" by simply avoiding the use of `@ManyToMany` right from the start.
There's little downside to representing every—or at least _almost_ every—logical many-to-many association using an intermediate entity.
====
A many-to-many association must be annotated `@ManyToMany`:
[source,java]
----
@Entity
class Book {
@Id @GeneratedValue
Long id;
@ManyToMany
Set authors;
...
}
----
If the association is bidirectional, we add a very similar-looking attribute to `Book`, but this time we must specify `mappedBy` to indicate that this is the unowned side of the association:
[source,java]
----
@Entity
class Book {
@Id @GeneratedValue
Long id;
@ManyToMany(mappedBy=Author_.BOOKS)
Set authors;
...
}
----
Remember, if we wish to the modify the collection we must <>.
We've again used ``Set``s to represent the association.
As before, we have the option to use `Collection` or `List`.
But in this case it _does_ make a difference to the semantics of the association.
[NOTE]
// .Sets and bags
====
A many-to-many association represented as a `Collection` or `List` may contain duplicate elements.
However, as before, the order of the elements is not persistent.
That is, the collection is a _bag_, not a set.
====
[WARNING]
====
We don't usually map collections with `fetch=EAGER`, since that usually leads to poor performance and fetching of unnecessary data.
But this is especially clear in the case of many-to-many associations.
We don't much employ the word "never" when it comes to object/relational mappings, but here we will:
**never** write `@ManyToMany(fetch=EAGER)` unless you're deliberately looking for trouble.
====
[[unidirectional-one-to-many]]
=== Unidirectional one-to-many
Finally, Hibernate allows a unidirectional one-to-many association, that is, a `@OneToMany` with no matching `@ManyToOne` on the other side.
[source,java]
----
@OneToMany // no matching @ManyToOne
Set books;
----
By default, a unidirectional one-to-many association maps to a separate <>.
It therefore more closely resembles a many-to-many association than a many-to-one association.
[CAUTION]
====
If you're new to Hibernate, this is not the association mapping strategy you're looking for.
Use a <> instead.
Previous versions of this Guide advised against the use of these mappings completely.
====
Unidirectional one-to-many association mappings are only useful in one very specific circumstance.
Suppose we have a `Comment` entity, which has many different "parents" -- there can be comments on ``Document``s, comments on ``Issue``s, comments on ``Request``s, and so on.
These aren't many-to-many associations; each given `Comment` belongs to exactly one parent.
But on the other hand, it doesn't make sense to add a field for each kind of parent entity to the `Comment` class.
Nor does it make sense to add a foreign key column for each parent entity to the `COMMENTS` table.
This is the only scenario in which we can imagine ourselves using a unidirectional one-to-many.
[[collections]]
=== Collections of basic values and embeddable objects
We've now seen the following kinds of entity attribute:
[%breakable,cols="37,^15,^15,~"]
|===
| Kind of entity attribute | Kind of reference | Multiplicity | Examples
| Single-valued attribute of basic type | Non-entity | At most one | `@Basic String name`
| Single-valued attribute of embeddable type | Non-entity | At most one | `@Embedded Name name`
| Single-valued association | Entity | At most one |
`@ManyToOne Publisher publisher` +
`@OneToOne Person person`
| Many-valued association | Entity | Zero or more |
`@OneToMany Set books` +
`@ManyToMany Set authors`
|===
Scanning this taxonomy, you might ask: does Hibernate have multivalued attributes of basic or embeddable type?
Well, actually, we've already seen that it does, at least in two special cases.
So first, lets <> that JPA treats `byte[]` and `char[]` arrays as basic types.
Hibernate persists a `byte[]` or `char[]` array to a `VARBINARY` or `VARCHAR` column, respectively.
But in this section we're really concerned with cases _other_ than these two special cases.
So then, _apart from ``byte[]`` and ``char[]``_, does Hibernate have multivalued attributes of basic or embeddable type?
And the answer again is that _it does_. Indeed, there are two different ways to handle such a collection, by mapping it:
- to a column of SQL `ARRAY` type (assuming the database has an `ARRAY` type), or
- to a separate table.
So we may expand our taxonomy with:
[%breakable,cols="37,^15,^15,~"]
|===
| Kind of entity attribute | Kind of reference | Multiplicity | Examples
| `byte[]` and `char[]` arrays | Non-entity | Zero or more |
`byte[] image` +
`char[] text`
| Collection of basic-typed elements | Non-entity | Zero or more |
`@Array String[] names` +
`@ElementCollection Set names`
| Collection of embeddable elements | Non-entity | Zero or more | `@ElementCollection Set names`
|===
There's actually two new kinds of mapping here: `@Array` mappings, and `@ElementCollection` mappings.
[%unbreakable]
[CAUTION]
// .These sorts of mappings are overused
====
These sorts of mappings are overused.
There _are_ situations where we think it's appropriate to use a collection of basic-typed values in our entity class.
But such situations are rare.
Almost every many-valued relationship should map to a foreign key association between separate tables.
And almost every table should be mapped by an entity class.
The features we're about to meet in the next two subsections are used much more often by beginners than they're used by experts.
So if you're a beginner, you'll save yourself some hassle by staying away from these features for now.
====
We'll talk about `@Array` mappings first.
[[arrays]]
=== Collections mapped to SQL arrays
Let's consider a calendar event which repeats on certain days of the week.
We might represent this in our `Event` entity as an attribute of type `DayOfWeek[]` or `List`.
Since the number of elements of this array or list is upper bounded by 7, this is a reasonable case for the use of an `ARRAY`-typed column.
It's hard to see much value in storing this collection in a separate table.
[%unbreakable]
.*Read more: Learning to not hate SQL arrays*
[%collapsible]
====
****
For a long time, we thought arrays were a kind of weird and warty thing to add to the relational model, but recently we've come to realize that this view was overly closed-minded.
Indeed, we might choose to view SQL `ARRAY` types as a generalization of `VARCHAR` and `VARBINARY` to generic "element" types.
And from this point of view, SQL arrays look quite attractive, at least for certain problems.
If we're comfortable mapping `byte[]` to `VARBINARY(255)`, why would we shy away from mapping `DayOfWeek[]` to `TINYINT ARRAY[7]`?
****
====
Unfortunately, JPA doesn't define a standard way to map SQL arrays, but here's how we can do it in Hibernate:
[source, java]
----
@Entity
class Event {
@Id @GeneratedValue
Long id;
...
@Array(length=7)
DayOfWeek[] daysOfWeek; // stored as a SQL ARRAY type
...
}
----
The `@Array` annotation is optional--it lets us specify an upper bound on the length of the `ARRAY` column.
By writing `@Array(length=7)` here, we specified that DDL should be generated with the column type `TINYINT ARRAY[7]`.
Just for fun, we used an enumerated type in the code above, but the array element time may be almost any <>.
For example, the Java array types `String[]`, `UUID[]`, `double[]`, `BigDecimal[]`, `LocalDate[]`, and `OffsetDateTime[]` are all allowed, mapping to the SQL types `VARCHAR(n) ARRAY`, `UUID ARRAY`, `FLOAT(53) ARRAY`, `NUMERIC(p,s) ARRAY`, `DATE ARRAY`, and `TIMESTAMP(p) WITH TIME ZONE ARRAY`, respectively.
[WARNING]
// .Not every database has an `ARRAY` type
====
Now for the gotcha: not every database has a SQL `ARRAY` type, and some that _do_ have an `ARRAY` type don't allow it to be used as a column type.
In particular, neither Db2 nor SQL Server have array-typed columns.
On these databases, Hibernate falls back to something quite a bit worse:
the array value is encoded to XML and stored in an XML-typed column.
====
Alternatively, we could store this array or list in a separate table.
[[element-collections]]
=== Collections mapped to a separate table
JPA _does_ define a standard way to map a collection to an auxiliary table: the `@ElementCollection` annotation.
[source, java]
----
@Entity
class Event {
@Id @GeneratedValue
Long id;
...
@ElementCollection
DayOfWeek[] daysOfWeek; // stored in a dedicated table
...
}
----
Actually, we shouldn't use an array here, since array types can't be <>, and so the JPA specification doesn't even say they're supported.
Instead, we should use `Set`, `List`, or `Map`.
[source, java]
----
@Entity
class Event {
@Id @GeneratedValue
Long id;
...
@ElementCollection
@OrderColumn
List daysOfWeek; // stored in a dedicated table
...
}
----
Here, each collection element is stored as a separate row of the auxiliary table.
By default, this table has the following definition:
[source,sql]
----
create table Event_daysOfWeek (
Event_id bigint not null,
daysOfWeek tinyint check (daysOfWeek between 0 and 6),
daysOfWeek_ORDER integer not null,
primary key (Event_id, daysOfWeek_ORDER)
)
----
Which is fine, but it's still a mapping we prefer to avoid.
[%unbreakable]
[CAUTION]
// .This is not what we would do
====
`@ElementCollection` is one of our least-favorite features of JPA.
Even the name of the annotation is bad.
The code above results in a table with three columns:
- a foreign key of the `Event` table,
- a `TINYINT` encoding the `enum`, and
- an `INTEGER` encoding the ordering of elements in the array.
Instead of a surrogate primary key, it has a composite key comprising the foreign key of `Event` and the order column.
When--inevitably--we find that we need to add a fourth column to that table, our Java code must change completely.
Most likely, we'll realize that we need to add a separate entity after all.
So this mapping isn't very robust in the face of minor changes to our data model.
====
// [CAUTION]
// ====
// Consider the following very simple mapping:
// [source,java]
// ----
// @ElementCollection
// Set topics;
// ----
// Hibernate would generate the following DDL:
// [source,sql]
// ----
// create table Book_topics (
// Book_isbn varchar(255) not null,
// topics varchar(255)
// unique (Book_isbn, topics)
// )
// ----
// Here, there's no `not null` constraint on one of the columns.
// As a result, Hibernate cannot add a proper primary key to the table.
// This is not a great data model.
//
// We can fix this problem with a `@Column` annotation:
// [source,java]
// ----
// @ElementCollection
// @Column(nullable=false)
// Set topics;
// ----
// Now the generated DDL looks better:
// [source,sql]
// ----
// create table Book_topics (
// Book_isbn varchar(255) not null,
// topics varchar(255) not null,
// primary key (Book_isbn, topics)
// )
// ----
// Of course, with this mapping we can't have `null` as an element of our `Set`.
// But we can't think of a good reason why you might want that or what it would even mean for a set to contain null.
// ====
There's much more we could say about "element collections", but we won't say it, because we don't want to hand you the gun you'll shoot your foot with.
[[entities-summary]]
=== Summary of annotations
Let's pause to remember the annotations we've met so far.
.Declaring entities and embeddable types
[%breakable,cols="22,~,^13"]
|===
| Annotation | Purpose | JPA-standard
| `@Entity` | Declare an entity class | ✔
| `@MappedSuperclass` | Declare a non-entity class with mapped attributes inherited by an entity | ✔
| `@Embeddable` | Declare an embeddable type | ✔
| `@IdClass` | Declare the identifier class for an entity with multiple `@Id` attributes | ✔
|===
.Declaring basic and embedded attributes
[%breakable,cols="22,~,^10,^13"]
|===
| Annotation | Purpose | | JPA-standard
| `@Id` | Declare a basic-typed identifier attribute | | ✔
| `@Version` | Declare a version attribute | | ✔
| `@Basic` | Declare a basic attribute | Default | ✔
| `@EmbeddedId` | Declare an embeddable-typed identifier attribute | | ✔
| `@Embedded` | Declare an embeddable-typed attribute | Inferred | ✔
| `@Enumerated` | Declare an `enum`-typed attribute and specify how it is encoded | Inferred | ✔
| `@Array` | Declare that an attribute maps to a SQL `ARRAY`, and specify the length | Inferred | ✖
| `@ElementCollection` | Declare that a collection is mapped to a dedicated table | | ✔
|===
.Converters and compositional basic types
[%breakable,cols="22,~,^13"]
|===
| Annotation | Purpose | JPA-standard
| `@Converter` | Register an `AttributeConverter` | ✔
| `@Convert` | Apply a converter to an attribute | ✔
| `@JavaType` | Explicitly specify an implementation of `JavaType` for a basic attribute | ✖
| `@JdbcType` | Explicitly specify an implementation of `JdbcType` for a basic attribute | ✖
| `@JdbcTypeCode` | Explicitly specify a JDBC type code used to determine the `JdbcType` for a basic attribute | ✖
| `@JavaTypeRegistration` | Register a `JavaType` for a given Java type | ✖
| `@JdbcTypeRegistration` | Register a `JdbcType` for a given JDBC type code | ✖
|===
.System-generated identifiers
[%breakable,cols="22,~,^13"]
|===
| Annotation | Purpose | JPA-standard
| `@GeneratedValue` | Specify that an identifier is system-generated | ✔
| `@SequenceGenerator` | Define an id generator backed by a database sequence | ✔
| `@TableGenerator` | Define an id generated backed by a database table | ✔
| `@IdGeneratorType` | Declare an annotation that associates a custom `Generator` with each `@Id` attribute it annotates | ✖
| `@ValueGenerationType` | Declare an annotation that associates a custom `Generator` with each `@Basic` attribute it annotates | ✖
|===
.Declaring entity associations
[%breakable,cols="22,~,^13"]
|===
| Annotation | Purpose | JPA-standard
| `@ManyToOne` | Declare the single-valued side of a many-to-one association (the owning side) | ✔
| `@OneToMany` | Declare the many-valued side of a many-to-one association (the unowned side) | ✔
| `@ManyToMany` | Declare either side of a many-to-many association | ✔
| `@OneToOne` | Declare either side of a one-to-one association | ✔
| `@MapsId` | Declare that the owning side of a `@OneToOne` association maps the primary key column | ✔
|===
Phew!
That's already a lot of annotations, and we have not even started with the annotations for O/R mapping!
[[equals-and-hash]]
=== `equals()` and `hashCode()`
Entity classes should override `equals()` and `hashCode()`, especially when associations are <>.
People new to Hibernate or JPA are often confused by exactly which fields should be included in the `hashCode()`.
And people with more experience often argue quite religiously that one or another approach is the only right way.
The truth is, there's no unique right way to do it, but there are some constraints.
So please keep the following principles in mind:
- You should not include a mutable field in the hashcode, since that would require rehashing every collection containing the entity whenever the field is mutated.
- It's not completely wrong to include a generated identifier (surrogate key) in the hashcode, but since the identifier is not generated until the entity instance is made persistent, you must take great care to not add it to any hashed collection before the identifier is generated. We therefore advise against including any database-generated field in the hashcode.
It's OK to include any immutable, non-generated field in the hashcode.
TIP: We therefore recommend identifying a <> for each entity, that is, a combination of fields that uniquely identifies an instance of the entity, from the perspective of the data model of the program. The natural key should correspond to a unique constraint on the database, and to the fields which are included in `equals()` and `hashCode()`.
In this example, the `equals()` and `hashCode()` methods agree with the `@NaturalId` annotation:
[source,java]
----
@Entity
class Book {
@Id @GeneratedValue
Long id;
@NaturalId
@Basic(optional=false)
String isbn;
String getIsbn() {
return isbn;
}
...
@Override
public boolean equals(Object other) {
return other instanceof Book book // check type with instanceof, not getClass()
&& book.getIsbn().equals(isbn); // compare natural ids
}
@Override
public int hashCode() {
return isbn.hashCode(); // hashcode based on the natural id
}
}
----
That said, an implementation of `equals()` and `hashCode()` based on the generated identifier of the entity can work _if you're careful_.
CAUTION: Your implementation of `equals()` must be written to accommodate the possibility that the object passed to the `equals()` might be a <>.
Therefore, you should use `instanceof`, not `getClass()` to check the type of the argument, and should access fields of the passed entity via its accessor methods.
---
### Documentation Src Main Asciidoc Introduction Interacting (`documentation/src/main/asciidoc/introduction/Interacting.adoc`)
[[interacting]]
== Interacting with the database
To interact with the database, that is, to execute queries, or to insert, update, or delete data, we need an instance of one of the following objects:
- a JPA `EntityManager`,
- a JPA `EntityAgent`,
- a Hibernate `Session`, or
- a Hibernate `StatelessSession`.
The `Session` interface extends `EntityManager`, and so the only difference between the two interfaces is that `Session` offers a few more operations.
Similarly, `StatelessSession` extends `EntityAgent`.
[TIP]
// .The `Session` hiding inside an `EntityManager`
====
Actually, in Hibernate, every `EntityManager` is a `Session`, and you can narrow it like this:
[source,java]
----
Session session = entityManager.unwrap(Session.class);
----
Similarly, every `EntityAgent` is `StatelessSession`:
[source,java]
----
StatelessSession session = entityAgent.unwrap(StatelessSession.class);
----
====
An instance of `EntityManager` is a _stateful session_.
It mediates the interaction between your program and the database via operations on a _persistence context_.
In this chapter, we're going to focus on `EntityManager` first.
We'll <> to `EntityAgent` and _stateless sessions_ toward the end of the chapter.
What you need to know for now is that a stateless session doesn't have a persistence context.
Still, we should note for the record that some people prefer to use stateless sessions everywhere.
It's a simpler programming model, and lets the developer interact with the database more _directly_.
Stateful sessions certainly have their advantages, but they're more difficult to reason about, and when something goes wrong, the error messages can be more difficult to understand.
[[persistence-contexts]]
=== Persistence contexts
A persistence context is a sort of cache; we sometimes call it the "first-level cache", to distinguish it from the <>.
For every entity instance read from the database within the scope of a persistence context, and for every new entity made persistent within the scope of the persistence context, the context holds a unique mapping from the identifier of the entity instance to the instance itself.
Thus, an entity instance may be in one of three states with respect to a given persistence context:
1. _transient_ — never persistent, and not associated with the persistence context,
2. _persistent_ — currently associated with the persistence context, or
3. _detached_ — previously persistent in another session, but not currently associated with _this_ persistence context.
image::images/entity-lifecyle.png[Entity lifecycle,width=800,align="center"]
At any given moment, an instance may be associated with at most one persistence context.
The lifetime of a persistence context usually corresponds to the lifetime of a transaction, though it's possible to have a persistence context that spans several database-level transactions that form a single logical unit of work.
[WARNING]
====
A persistence context -- that is, a `Session` or `EntityManager` -- absolutely positively **must not be shared between multiple threads or between concurrent transactions.**
If you accidentally leak a session across threads, you will suffer.
====
[NOTE]
In a container environment, the lifecycle of a persistence context scoped to the transaction will usually be managed for you.
There are several reasons we like persistence contexts.
1. They help avoid _data aliasing_: if we modify an entity in one section of code, then other code executing within the same persistence context will see our modification.
2. They enable _automatic dirty checking_: after modifying an entity, we don't need to perform any explicit operation to ask Hibernate to propagate that change back to the database.
Instead, the change will be automatically synchronized with the database when the session is <>.
3. They can improve performance by avoiding a trip to the database when a given entity instance is requested repeatedly in a given unit of work.
4. They make it possible to _transparently batch_ together multiple database operations.
A persistence context also allows us to detect circularities when performing operations on graphs of entities.
(Even in a stateless session, we need some sort of temporary cache of the entity instances we've visited while executing a query.)
On the other hand, stateful sessions come with some very important restrictions, since:
- persistence contexts aren't threadsafe, and can't be shared across threads, and
- a persistence context can't be reused across unrelated transactions, since that would break the isolation and atomicity of the transactions.
Furthermore, a persistence context holds a hard references to all its entities, preventing them from being garbage collected.
Thus, the session must be discarded once a unit of work is complete.
[IMPORTANT]
// .This is important
====
If you don't completely understand the previous passage, go back and re-read it until you do.
A great deal of human suffering has resulted from users mismanaging the lifecycle of the Hibernate `Session` or JPA `EntityManager`.
====
We'll conclude by noting that whether a persistence context helps or harms the performance of a given unit of work depends greatly on the nature of the unit of work.
For this reason Hibernate provides both stateful and stateless sessions.
[[creating-session]]
=== Creating a session
We saw how to obtain an `EntityManagerFactory` in <> and <>.
It's quite unsurprising that we may use this object to create an `EntityManager` or `EntityAgent`:
[source,java]
----
EntityManager entityManager = entityManagerFactory.createEntityManager();
----
[source,java]
----
EntityAgent entityAgent = entityManagerFactory.createEntityAgent();
----
When we're finished with the `EntityManager` or `EntityAgent`, we must explicitly clean it up:
[source,java]
----
entityManager.close();
----
[source,java]
----
entityAgent.close();
----
[CAUTION]
Even though an `EntityAgent` is a "stateless" session, the `EntityAgent` itself still holds state which must be cleaned up by calling `close()`.
// On the other hand, if we're starting from a `SessionFactory`, as described in <>, we may use:
//
// [source,java]
// ----
// Session session = sessionFactory.openSession();
// ----
//
// But we still need to clean up:
//
// [source,java]
// ----
// session.close();
// ----
JPA 4 _session creation options_ let us provide some information controlling the behavior of the `EntityManager` or `EntityAgent` in a type safe way.
[source,java]
----
EntityManager entityManager =
entityManagerFactory.createEntityManager(new FetchBatchSize(20),
ReadOnlyMode.READ_ONLY,
CacheStoreMode.BYPASS);
----
Search for implementations of `EntityManager.CreationOption` or `EntityAgent.CreationOption` to find the option types provided by the specification and by Hibernate.
A number of useful options are declared by link:{doc-javadoc-url}org/hibernate/SessionCreationOption.html[`SessionCreationOption`].
.*Read more: Injecting the EntityManager or EntityAgent*
[%collapsible]
====
****
If you're writing code for some sort of container environment, you'll probably obtain the `EntityManager` or `EntityAgent` by some sort of dependency injection.
For example, in Java (or Jakarta) EE you would write:
[source,java]
----
@PersistenceContext EntityManager entityManager;
----
[source,java]
----
@PersistenceAgent EntityAgent entityAgent;
----
In Quarkus, injection is handled by CDI:
[source,java]
----
@Inject EntityManager entityManager;
----
[source,java]
----
@Inject EntityAgent entityAgent;
----
****
====
Outside a container environment, we'll also have to write code to manage database transactions.
[[managing-transactions]]
=== Managing transactions
Using JPA-standard APIs, the `EntityTransaction` interface allows us to control database transactions.
The idiom we recommend is the following:
[source,java]
----
EntityManager entityManager = entityManagerFactory.createEntityManager();
EntityTransaction tx = entityManager.getTransaction();
try {
tx.begin();
//do some work
...
tx.commit();
}
catch (Exception e) {
if (tx.isActive()) tx.rollback();
throw e;
}
finally {
entityManager.close();
}
----
But this code is extremely tedious, so there's a cleaner option:
[source,java]
----
entityManagerFactory.runInTransaction(entityManager -> {
// do the work in a stateful session
...
});
----
When we need to return a value from within the anonymous function, we use `callInTransaction()` instead of `runInTransaction()`.
In case we're using an `EntityAgent`, or if we would like direct access to the `Session` or `StatelessSession` without a type cast, `runInTransaction()` lets us specify the class of session we require:
[source,java]
----
entityManagerFactory.runInTransaction(EntityAgent.class, entityAgent -> {
// do the work in a stateless session
...
});
----
[source,java]
----
entityManagerFactory.runInTransaction(Session.class, session -> {
// do the work in a Hibernate session
...
});
----
// Using Hibernate's native APIs we can write something very similar:
// // [source,java]
// // ----
// // Session session = sessionFactory.openSession();
// // Transaction tx = null;
// // try {
// // tx = session.beginTransaction();
// // //do some work
// // ...
// // tx.commit();
// // }
// // catch (Exception e) {
// // if (tx!=null) tx.rollback();
// // throw e;
// // }
// // finally {
// // session.close();
// // }
// // ----
// [source,java]
// ----
// sessionFactory.inTransaction(session -> {
// //do the work
// ...
// });
// ----
[NOTE]
====
In a container environment, the container itself is usually responsible for managing transactions.
In Java EE or Quarkus, you'll probably indicate the boundaries of the transaction using the `@Transactional` annotation.
====
The `EntityTransaction` interface provides a standard way to set the transaction timeout:
[source,java]
----
entityManager.getTransaction().setTimeout(30); // 30 seconds
----
`EntityTransaction` also provides a way to set the transaction to rollback-only mode:
[source,java]
----
entityManager.getTransaction().setRollbackOnly();
----
A transaction in rollback-only mode will be rolled back when it completes.
[[after-tx-rollback]]
[IMPORTANT]
====
Hibernate is not a software transactional memory.
When a transaction rolls back, Hibernate makes no attempt to roll back the state of objects held in memory to their state at the beginning of the transaction.
After a transaction rollback, the persistence context must be discarded, and the state of its entities must be assumed inconsistent with the state held by the database.
====
The interface link:{doc-javadoc-url}org/hibernate/Transaction.html[`Transaction`] extends `EntityTransaction` with some additional operations, including the ability to register transaction completion callbacks.
[[persistence-operations]]
=== Operations on the persistence context
Of course, the main reason we need an `EntityManager` is to do stuff to the database.
The following important operations let us interact with the persistence context and schedule modifications to the data:
.Methods for modifying data and managing the persistence context
[%breakable,cols="30,~"]
|===
| Method name and parameters | Effect
| `persist(Object)`
| Make a transient object persistent and schedule a SQL `insert` statement for later execution
| `remove(Object)`
| Make a persistent object transient and schedule a SQL `delete` statement for later execution
| `merge(Object)`
| Copy the state of a given detached object to a corresponding managed persistent instance and return
the persistent object
| `detach(Object)`
| Disassociate a persistent object from a session without
affecting the database
| `clear()`
| Empty the persistence context and detach all its entities
| `flush()`
| Detect changes made to persistent objects association with the session and synchronize the database state with the state of the session by executing SQL `insert`, `update`, and `delete` statements
|===
Notice that `persist()` and `remove()` usually have no immediate effect on the database, and instead simply schedule a command for later execution.
Also notice that there's no `update()` operation for a stateful session.
Modifications are automatically detected when the session is <>.
On the other hand, except for `getReference()`, the following operations all result in immediate access to the database:
[[methods-for-reading]]
.Methods for reading and locking data
[%breakable,cols="30,~"]
|===
| Method name and parameters | Effect
| `get(Class,Object)`
| Obtain a persistent object given its type and its id, throwing `EntityNotFoundException` if there is no such record
| `find(Class,Object)`,
| Obtain a persistent object given its type and its id, returning `null` if there is no such record
// | `find(Class,Object,LockModeType)`
// | Obtain a persistent object given its type and its id, requesting the given <>
returning `null` if there is no such record
| `getReference(Class,id)`
| Obtain a reference to a persistent object given its type and its id, without actually loading its state from the database
| `getReference(Object)`
| Obtain a reference to a persistent object with the same identity as the given detached instance, without actually loading its state from the database
| `refresh(Object)`
| Refresh the persistent state of an object using a new SQL `select` to retrieve its current state from the database
// | `refresh(Object,LockModeType)`
// | Refresh the persistent state of an object using a new SQL `select` to retrieve its current state from the database, requesting the given <>
| `lock(Object,LockModeType)`
| Obtain an <> on a persistent object
|===
Any of these operations might throw an exception.
Now, if an exception occurs while interacting with the database, there's no good way to resynchronize the state of the current persistence context with the state held in database tables.
Therefore, a session is considered to be unusable after any of its methods throws an exception.
[[fragile-persistence-context]]
[IMPORTANT]
// .The persistence context is fragile
====
The persistence context is fragile.
If you receive an exception from Hibernate, you should immediately close and discard the current session. Open a new session if you need to, but throw the bad one away first.
====
One very important kind of exception which can happen when data is shared between concurrent units of work is an _optimistic lock failure_.
Optimistic locks are verified by checking <>.
A version check is included in the `where` clause of every SQL `update` or `delete` statement for a versioned entity.
If a version check fails--that is, if no rows are updated--Hibernate infers that the entity was updated in some other unit of work and throws an `OptimisticLockException` to indicate that the current session is working with stale data.
As with other exceptions, this loss of synchronization between the persistence context and the database means that we must discard the current session.
[CAUTION]
====
Some of these operations listed above require slightly more care than others.
When you call `detach()`, `clear()`, `flush()`, or `refresh()`, you've already strayed from the narrow path.
You didn't stray far--and you probably had a good reason for going there--but you're in territory where Hibernate just has to assume you know what you're doing.
If you start to feel that this terrain is bogging you down, consider using a <>.
====
Four of these operations accept _options_, allowing influence over their behavior.
[%breakable,cols="50,~"]
|===
| Method name and parameters | Effect
| `get(Class,Object,FindOption...)`
| Obtain a persistent object given its type and its id, using the specified options, throwing if there is no such record
| `get(EntityGraph,Object,FindOption...)`
| Obtain a persistent object given its id and an `EntityGraph` specifying its type and associations which should be eagerly fetched, using the specified options, throwing if there is no such record
| `find(Class,Object,FindOption...)`
| Obtain a persistent object given its type and its id, using the specified options, returning `null` there is no such record
| `find(EntityGraph,Object,FindOption...)`
| Obtain a persistent object given its id and an `EntityGraph` specifying its type and associations which should be eagerly fetched, using the specified options, returning `null` there is no such record
| `refresh(Object,LockModeType,RefreshOption...)`
| Refresh the persistent state of an object using a new SQL `select` to retrieve its current state from the database, requesting the given <>, using the specified options
| `lock(Object,LockModeType,LockOption...)`
| Obtain an <> on a persistent object, using the specified options
|===
For example, JPA provides the `Timeout` class which is a `FindOption`, a `RefreshOption`, and a `LockOption`.
[source,java]
----
var book = entityManger.find(Book.class, isbn, Timeout.ms(100), CacheStoreMode.BYPASS);
----
Finally, the following methods are capable of efficiently loading multiple entity instances in parallel:
[%breakable,cols="50,~"]
|===
| Method name and parameters | Effect
| `getMultiple(Class,List,FindOption...)`
| Obtain a list of persistent objects given their type and their ids, using the specified options, throwing if there is no such record
| `getMultiple(EntityGraph,List,FindOption...)`
| Obtain a list of persistent objects given their ids and an `EntityGraph` specifying their type and associations which should be eagerly fetched, using the specified options, throwing if there is no such record
| `findMultiple(Class,List,FindOption...)`
| Obtain a list of persistent objects given their type and their ids, using the specified options, returning `null` there is no such record
| `findMultiple(EntityGraph,List,FindOption...)`
| Obtain a list of persistent objects given their ids and an `EntityGraph` specifying their type and associations which should be eagerly fetched, using the specified options, returning `null` there is no such record
|===
The following code results in a single SQL `select` statement:
[source,java]
----
List books = entityManger.findMultiple(Book.class, bookIds);
----
link:{doc-javadoc-url}org/hibernate/FindMultipleOption.html[`FindMultipleOption`] declares a number of options influencing the behavior of `findMultiple()` and `getMultiple()`.
[[load-by-natural-id]]
=== Lookup by natural id
As discussed <>, Hibernate offers the ability to map a natural id and perform retrieval operations using the natural id.
This is accomplished using the option link:{doc-javadoc-url}org/hibernate/KeyType.html#NATURAL[`KeyType.NATURAL`]:
[source,java]
----
var bookKey = new BookKey(isbn, printing);
var book = entityManager.find(Book.class, bookKey, KeyType.NATURAL);
----
In this example, `BookKey` is the link:{doc-javadoc-url}org/hibernate/annotations/NaturalIdClass.html[`@NaturalIdClass`] for `Book`.
If an entity with a composite natural id lacks a natural id class, a `Map` may be used instead:
[source,java]
----
var bookKey = Map.of(Book_.ISBN, isbn, Book_.PRINTING, printing);
var book = entityManager.find(Book.class, bookKey, KeyType.NATURAL);
----
Each of the operations we've seen so far affects a single entity instance passed as an argument.
But there's a way to set things up so that an operation will propagate to associated entities.
[[cascade]]
=== Cascading persistence operations
It's quite often the case that the lifecycle of a _child_ entity is completely dependent on the lifecycle of some _parent_.
This is especially common for many-to-one and one-to-one associations, though it's very rare for many-to-many associations.
For example, it's quite common to make an `Order` and all its ``Item``s persistent in the same transaction, or to delete a `Project` and its ``Files``s at once.
This sort of relationship is sometimes called a _whole/part_-type relationship.
_Cascading_ is a convenience which allows us to propagate one of the operations listed in <> from a parent to its children.
To set up cascading, we specify the `cascade` member of one of the association mapping annotations, usually `@OneToMany` or `@OneToOne`.
[source,java]
----
@Entity
class Order {
...
@OneToMany(mappedby=Item_.ORDER,
// cascade persist(), remove(), and refresh() from Order to Item
cascade={PERSIST,REMOVE,REFRESH},
// also remove() orphaned Items
orphanRemoval=true)
private Set- items;
...
}
----
_Orphan removal_ indicates that an `Item` should be automatically deleted if it is removed from the set of items belonging to its parent `Order`.
[[proxies-and-lazy-fetching]]
=== Proxies and lazy fetching
Our data model is a set of interconnected entities, and in Java our whole dataset would be represented as an enormous interconnected graph of objects.
It's possible that this graph is disconnected, but more likely it's connected, or composed of a relatively small number of connected subgraphs.
Therefore, when we retrieve an object belonging to this graph from the database and instantiate it in memory, we simply can't recursively retrieve and instantiate all its associated entities.
Quite aside from the waste of memory on the VM side, this process would involve a huge number of round trips to the database server, or a massive multidimensional cartesian product of tables, or both.
Instead, we're forced to cut the graph somewhere.
Hibernate solves this problem using _proxies_ and _lazy fetching_.
A proxy is an object that masquerades as a real entity or collection, but doesn't actually hold any state, because that state has not yet been fetched from the database.
When you call a method of the proxy, Hibernate will detect the call and fetch the state from the database before allowing the invocation to proceed to the real entity object or collection.
Now for the gotchas:
1. Hibernate only does this for an entity which is currently associated with a persistence context.
Once the session ends, and the persistence context is cleaned up, the proxy is no longer fetchable, and instead its methods throw the hated `LazyInitializationException`.
2. For a polymorphic association, Hibernate does not know the concrete type of the referenced entity when the proxy is instantiated, and so operations like `instanceof` and typecasts do not work correctly when applied to a proxy.
3. A round trip to the database to fetch the state of a single entity instance is just about _the least efficient_ way to access data.
It almost inevitably leads to the infamous _N+1 selects_ problem we'll discuss later when we talk about how to <
>.
[TIP]
====
The link:{doc-javadoc-url}org/hibernate/annotations/ConcreteProxy.html[`@ConcreteProxy`] annotation solves gotcha 2, but at the cost of performance (extra joins), and so its use is not generally recommended, except in very special circumstances.
====
[TIP]
// .Strive to avoid triggering lazy fetching
====
We're getting a bit ahead of ourselves here, but let's quickly mention the general strategy we recommend to navigate past these gotchas:
- All associations should be set `fetch=LAZY` to avoid fetching extra data when it's not needed.
As we mentioned <>, this setting is not the default for `@ManyToOne` associations, and must be specified explicitly unless the default is changed using `` or `defaultToOneFetchType()`.
- But strive to avoid writing code which triggers lazy fetching.
Instead, fetch all the data you'll need upfront at the beginning of a unit of work, using one of the techniques described in <>, usually, using _join fetch_ in HQL or an `EntityGraph`.
====
It's important to know that some operations which may be performed with an unfetched proxy _don't_ require fetching its state from the database.
First, we're always allowed to obtain its identifier:
[source,java]
----
var pubId = entityManager.find(Book.class, bookId).getPublisher().getId(); // does not fetch publisher
----
Second, we may create an association to a proxy:
[source,java]
----
book.setPublisher(entityManager.getReference(Publisher.class, pubId)); // does not fetch publisher
----
Sometimes it's useful to test whether a proxy or collection has been fetched from the database.
JPA lets us do this using the `PersistenceUnitUtil`:
[source,java]
----
boolean authorsFetched = entityManagerFactory.getPersistenceUnitUtil().isLoaded(book.getAuthors());
----
Hibernate has a slightly easier way to do it:
[source,java]
----
boolean authorsFetched = Hibernate.isInitialized(book.getAuthors());
----
Similarly, `PersistenceUnitUtil.load()` force-fetches a proxy or collection:
[source,java]
----
Book book = entityManager.find(Book.class, bookId); // fetch just the Book, leaving authors unfetched
entityManagerFactory.getPersistenceUnitUtil().load(book.getAuthors());
----
Again, `Hibernate.initialize()` is slightly more convenient:
[source,java]
----
Book book = session.find(Book.class, bookId); // fetch just the Book, leaving authors unfetched
Hibernate.initialize(book.getAuthors()); // fetch the Authors
----
On the other hand, the above code is very inefficient, requiring two trips to the database to obtain data that could in principle be retrieved with just one query.
The static methods of the link:{doc-javadoc-url}org/hibernate/Hibernate.html[`Hibernate`] class let us do a lot more, and it's worth getting a bit familiar with them.
Of particular interest are the operations which let us work with unfetched collections without fetching their state from the database.
For example, consider this code:
[source,java]
----
Book book = session.find(Book.class, bookId); // fetch just the Book, leaving authors unfetched
Author authorRef = session.getReference(Author.class, authorId); // obtain an unfetched proxy
boolean isByAuthor = Hibernate.contains(book.getAuthors(), authorRef); // no fetching
----
This code fragment leaves both the set `book.authors` and the proxy `authorRef` unfetched.
It's clear from the discussion above that we need a way to request that an association be _eagerly_ fetched using a database `join`, thus protecting ourselves from the infamous N+1 selects.
One way to do this is by passing an `EntityGraph` to `find()`.
[[entity-graph]]
=== Entity graphs and eager fetching
When an association is mapped `fetch=LAZY`, it won't, by default, be fetched when we call the `find()` method.
We may request that an association be fetched eagerly (immediately) by passing an `EntityGraph` to `find()`.
[source,java]
----
var graph = entityManager.createEntityGraph(Book.class);
graph.addSubgraph(Book_.publisher);
Book book = entityManager.find(graph, bookId);
----
//
// [source,java]
// ----
// var graph = session.createEntityGraph(Book.class);
// graph.addSubgraph(Book_.publisher);
// Book book = session.byId(Book.class).withFetchGraph(graph).load(bookId);
// ----
This code adds a `left outer join` to our SQL query, fetching the associated `Publisher` along with the `Book`.
We may even attach additional nodes to our `EntityGraph`:
[source,java]
----
var graph = entityManager.createEntityGraph(Book.class);
graph.addSubgraph(Book_.publisher);
graph.addPluralSubgraph(Book_.authors).addSubgraph(Author_.person);
Book book = entityManager.find(graph, bookId);
----
// [source,java]
// ----
// var graph = session.createEntityGraph(Book.class);
// graph.addSubgraph(Book_.publisher);
// graph.addPluralSubgraph(Book_.authors).addSubgraph(Author_.person);
// Book book = session.byId(Book.class).withFetchGraph(graph).load(bookId);
// ----
This results in a SQL query with _four_ ``left outer join``s.
Instances of `FetchOption` influence how a node of a graph is fetched.
[source,java]
----
var graph = entityManager.createEntityGraph(Book.class);
graph.addAttributeNode(Book_.publisher)
.addOption(FetchMethod.BULK_SELECT)
.addOption(CacheStoreMode.BYPASS);
Book book = entityManager.find(graph, bookId);
----
[NOTE]
====
In the code examples above, The classes `Book_` and `Author_` are generated by <>, as we saw <>.
They let us refer to attributes of our model in a completely type-safe way.
We'll use them again, below, when we talk about <>.
====
.*Read more: Fetch graphs and load graphs*
[%collapsible]
====
****
JPA specifies that any given `EntityGraph` may be interpreted in two different ways.
- A _fetch graph_ specifies exactly the associations that should be eagerly loaded.
Any association not belonging to the entity graph is proxied and loaded lazily only if required.
- A _load graph_ specifies that the associations in the entity graph are to be fetched in addition to the associations mapped `fetch=EAGER`.
An `EntityGraph` passed directly to `find()` is always interpreted as a load graph.
You're right, the names make no sense.
But don't worry, if you take our advice, and map your associations `fetch=LAZY`, there's no difference between a "fetch" graph and a "load" graph, so the names don't matter.
****
====
[TIP]
====
JPA even specifies a way to define named entity graphs using annotations.
The annotation-based API used to be so verbose that it just not wasn't worth using.
However, in JPA 4 this API has been much improved via introduction of the `@Fetch` annotation.
So perhaps you'll find a use for it.
You'll find more information in the Javadoc for `@NamedEntityGraph`.
====
// [[load-access]]
// === Controlling lookup by id
//
// As we will soon see in the <>, we can do almost anything via <>, <>, or <> queries.
// But when we already know the identifier of the entity we need, a query can feel like overkill.
// And queries don't make efficient use of the <>.
//
// We met the `find()` and `findMultiple()` methods <>.
// These are the most basic ways to perform a _lookup_ by id.
// But they can't quite do everything.
// Therefore, Hibernate has some APIs that streamline certain more complicated lookups:
//
// .Operations for lookup by id
// [%breakable,cols="30,~"]
// |===
// | Method name | Purpose
//
// | `byId()` | Lets us specify association fetching via an `EntityGraph`, as we saw; also lets us specify some additional options, including how the lookup <>, and whether the entity should be loaded in read-only mode
// | `byMultipleIds()` | Lets us load a _batch_ of ids at the same time
// |===
//
// [NOTE]
// ====
// Since the introduction of `FindOption` in JPA 3.2, `byId()` is now much less useful and deprecated.
// Instead, use `find()` and `findMultiple()` as discussed <>.
// ====
//
// Batch loading is very useful when we need to retrieve multiple instances of the same entity class by id:
//
// [source,java]
// ----
// var graph = session.createEntityGraph(Book.class);
// graph.addSubgraph(Book_.publisher);
//
// List books =
// session.byMultipleIds(Book.class)
// .withFetchGraph(graph) // control association fetching
// .withBatchSize(20) // specify an explicit batch size
// .with(CacheMode.GET) // control interaction with the cache
// .multiLoad(bookIds);
// ----
//
// The given list of `bookIds` will be broken into batches, and each batch will be fetched from the database in a single `select`.
// If we don't specify the batch size explicitly, a batch size will be chosen automatically.
//
// We also have some operations for working with lookups by <>:
//
// [%breakable,cols="30,~"]
// |===
// | Method name | Purpose
//
// | `bySimpleNaturalId()` | For an entity with just one attribute is annotated `@NaturalId`
// | `byNaturalId()` | For an entity with multiple attributes are annotated `@NaturalId`
// | `byMultipleNaturalId()` | Lets us load a _batch_ of natural ids at the same time
// |===
//
// Again, see the link:{doc-user-guide-url}#find-by-natural-id[User Guide] for more details about loading by natural ids.
//
// Here's how we can retrieve an entity by its composite natural id:
//
// [source,java]
// ----
// Book book =
// session.byNaturalId(Book.class)
// .using(Book_.isbn, isbn)
// .using(Book_.printing, printing)
// .load();
// ----
//
// Notice that this code fragment is completely typesafe, again thanks to <>.
[[controlling-merge]]
=== Controlling state retrieval during merge
The <> operation is usually used when some interaction with a user or automated system spans multiple transactions, with each transaction having its own persistence context:
1. an entity `e` is retrieved in one persistence context, and then the current transaction ends, resulting in destruction of the persistence context and in the entity becoming detached, then
2. `e` is modified in some way while detached, and then
3. finally, the modification is made persistent by merging the detached instance in a second transaction, with a new persistence context, by calling `entityManager.merge(e)`.
In step 3, the original entity instance `e` remains detached, but `merge()` returns a distinct instance `f` representing the same row of the database and associated with the new persistence context.
That is, `merge()` trades a detached instance for a <> representing the same row.
To determine the nature of the modification held in `e` and to guarantee correct semantics with respect to optimistic locking, Hibernate first ``select``s the current persistent state of the entity from the database before applying the modification to `f`.
<> allows multiple modifications held in a graph of entity instances to be made persistent in one call to `merge()`.
When `merge()` is used with cascading -- that is, when the `merge()` operation is applied to a root entity with associations mapped `cascade=MERGE` -- Hibernate issues a single `select` statement to retrieve the current database state of the root entity and all its associated entities.
This behavior avoids the use of N+1 select statements for state retrieval during cascade merge but, in certain circumstances, the query might be suboptimal.
On the other hand, this query does not occur if the root entity was already loaded into the persistence context before `merge()` is called.
Therefore, when using the `EntityManager` API, we may gain control over the way state is loaded before a `merge()` just by calling `find()` before calling `merge()`.
[source,java]
----
Book book = ... ;
var graph = entityManager.createEntityGraph(Book.class);
graph.addSubgraph(Book_.chapters); // Book.chapters mapped cascade=MERGE
entityManager.find(graph, book.getIsbn()); // force loading of the book
entityManager.merge(book); // merge the detached objet
----
The `Session` interface provides a streamlined alternative:
[source,java]
----
Book book = ... ;
var graph = session.createEntityGraph(Book.class);
graph.addSubgraph(Book_.chapters);
session.merge(book, graph); // equivalent to find() then merge()
----
When merging multiple root entities, `findMultiple()` may be used instead of `find()`.
[source,java]
----
List books = ... ;
var isbns = books.stream().map(Book::getIsbn).toList();
var graph = entityManager.createEntityGraph(Book.class);
graph.addSubgraph(Book_.chapters); // Book.chapters mapped cascade=MERGE
entityManager.findMultiple(graph, isbns); // force loading of the books
for (var book in books) {
entityManager.merge(book);
}
----
TIP: In some cases, `merge()` is much less efficient than the <> operation of `EntityAgent`.
[[flush]]
=== Flushing the session
From time to time, a _flush_ operation is triggered, and the session synchronizes dirty state held in memory—that is, modifications to the state of entities associated with the persistence context—with persistent state held in the database. Of course, it does this by executing SQL `INSERT`, `UPDATE`, and `DELETE` statements.
By default, a flush is triggered:
- when the current transaction commits, for example, when `Transaction.commit()` is called,
- before execution of a query whose result would be affected by the synchronization of dirty state held in memory, or
- when the program directly calls `flush()`.
In the following code, the flush occurs when the transaction commits:
[source,java]
----
entityManager.getTransaction().begin();
entityManager.persist(author);
var books =
// new Author does not affect results of query for Books
entityManager.createQuery("from Book", Book.class)
// no need to flush
.getResultList();
// flush occurs here, just before transaction commits
entityManager.getTransaction().commit();
----
But in this code, the flush occurs when the query is executed:
[source,java]
----
entityManager.getTransaction().begin();
entityManager.persist(book);
var books =
// new Book would affect results of query for Books
entityManager.createQuery("from Book", Book.class)
// flush occurs here, just before query is executed
.getResultList();
// changes were already flushed to database, nothing to flush
entityManager.getTransaction().commit();
----
It's always possible to call `flush()` explicitly:
[source,java]
----
entityManager.getTransaction().begin();
entityManager.persist(author);
entityManager.flush(); // explicit flush
var books =
entityManager.createQuery("from Book", Book.class)
// nothing to flush
.getResultList();
// nothing to flush
entityManager.getTransaction().commit();
----
[NOTE]
// .SQL execution happens asynchronously
====
Notice that SQL statements are not usually executed synchronously by methods of the `Session` interface like `persist()` and `remove()`. If synchronous execution of SQL is desired, the `StatelessSession` allows this.
====
This behavior can be controlled by explicitly setting the flush mode.
For example, to disable flushes that occur before query execution, call:
[source,java]
----
entityManager.setFlushMode(FlushModeType.COMMIT);
----
// Hibernate allows greater control over the link:{doc-javadoc-url}org/hibernate/FlushMode.html[flush mode] than JPA:
//
// [source,java]
// ----
// session.setHibernateFlushMode(FlushMode.MANUAL);
// ----
Since flushing is a somewhat expensive operation (the session must dirty-check every entity in the persistence context), setting the flush mode to `COMMIT` can occasionally be a useful optimization.
But take care--in this mode, queries might return stale data:
[source,java]
----
entityManager.getTransaction().begin();
entityManager.setFlushMode(FlushModeType.COMMIT); // disable AUTO-flush
entityManager.persist(book);
var books =
// flushing on query execution disabled
entityManager.createQuery("from Book", Book.class)
// no flush, query returns stale results
.getResultList();
// flush occurs here, just before transaction commits
entityManager.getTransaction().commit();
----
.Flush modes
[%breakable,cols="15,15,~"]
|===
| Hibernate link:{doc-javadoc-url}org/hibernate/FlushMode.html[`FlushMode`] | JPA `FlushModeType` | Interpretation
| `MANUAL` | `EXPLICIT` | Never flush automatically
| `COMMIT` | `COMMIT` | Flush before transaction commit
| `AUTO` | `AUTO` | Flush before transaction commit, and before execution of a query whose results might be affected by modifications held in memory
| `ALWAYS` | | Flush before transaction commit, and before execution of every query
|===
A second way to reduce the cost of flushing is to load entities in link:{doc-javadoc-url}org/hibernate/Session.html#setDefaultReadOnly(boolean)[_read-only_ mode].
// - `Session.setDefaultReadOnly(true)` specifies that all entities loaded by a given session should be loaded in read-only mode by default,
// - `SelectionQuery.setReadOnly(true)` specifies that every entity returned by a given query should be loaded in read-only mode, and
// - `Session.setReadOnly(Object, true)` specifies that a given entity already loaded by the session should be switched to read-only mode.
The custom option link:{doc-javadoc-url}org/hibernate/ReadOnlyMode.html[`ReadOnlyMode`] may be used to control read-only mode:
[source,java]
----
// load a single entity in read-only mode
var book = entityManager.find(Book.class, isbn, ReadOnlyMode.READ_ONLY);
----
[source,java]
----
// load all query results in read-only mode
var books =
entityManager.createQuery("from Book")
.ofType(Book.class)
.addOption(ReadOnlyMode.READ_ONLY)
.getResultList();
----
[source,java]
----
// load every entity in read-only mode
entityManager.addOption(ReadOnlyMode.READ_ONLY);
----
It's not necessary to dirty-check an entity instance in read-only mode.
Indeed, read-only mode is a way to make a stateful session work a bit more like a stateless session, bypassing some of the overhead associated with the use of a persistence context.
[[bypass-persistence-context]]
=== Operations which bypass the persistence context
When we use an `EntityAgent`, we're always working with detached objects.
Thus, the programming model is a bit different to what we've just seen.
The methods for retrieving entities and querying the database are the same -- indeed, they're all declared by a common supertype named `EntityHandler` -- but these operations always return detached objects, and so lazy fetching is an explicit operation.
And the operations used to update the database are completely different.
.Important methods of the `EntityAgent`
[%autowidth.stretch]
|===
| Method name and parameters | Effect
| `fetch(Object)` | Fetch an association of a detached object
| `refresh(Object)` | Refresh the state of a detached object by executing
a `select`
| `insert(Object)` | Immediately `insert` the state of the given transient object into the database
| `update(Object)` | Immediately `update` the state of the given detached object in the database
| `delete(Object)` | Immediately `delete` the state of the given detached object from the database
| `upsert(Object)` | Immediately `insert` or `update` the state of the given detached object using a SQL `merge into` statement
|===
NOTE: The operations of a `EntityAgent` have no corresponding ``CascadeType``s, and so these operations never cascade to associated entity instances.
NOTE: There's no `flush()` operation, and so `update()` is always explicit.
Notice that all the operations listed above result in an immediate interaction with the database.
In certain circumstances, this makes stateless sessions easier to work with and simpler to reason about, but with the caveat that a stateless session is much more vulnerable to data aliasing effects, since it's easy to get two non-identical Java objects which both represent the same row of a database table.
Consider the following fragments:
[source,java]
----
var b1 = statelessSession.get(Book.class, isbn);
var b2 = statelessSession.get(Book.class, isbn);
assert b1 == b2; // fails
----
[source,java]
----
var b1 = statelessSession.get(Book.class, isbn);
var b2 = statelessSession.get(Book.class, isbn);
statelessSession.fetch(b1.publisher);
statelessSession.fetch(b2.publisher);
assert b1.publisher == b2.publisher; // fails
----
In a stateful session, entity instances are canonicalized by primary key, and so we don't usually have two different objects representing a single row.
No such canonicalization exists across invocations of a stateless session.
In a stateless session, both the assertions fail.
[%unbreakable]
[CAUTION]
====
If we use `fetch()` in a stateless session, we can very easily obtain two objects representing the same database row!
====
[[callbacks]]
=== Lifecycle callbacks and entity listeners
Lifecycle callbacks allow the application program to respond to events occurring deep within Hibernate.
- The annotations `@PrePersist`, `@PreRemove`, `@PreMerge`, `@PostPersist`, `@PostRemove`, `@PostMerge`, and `@PostLoad` allow an entity to respond to persistence lifecycle operations and maintain its transient internal state.
These events only occur in a stateful session.
- The annotations `@PreInsert`, `@PreUpdate`, `@PreUpsert`, `@PreDelete`, `@PostInsert`,`@PostUpdate`, `@PostUpsert`, and `@PostDelete` allow the application program to be notified of operations executed against the database.
These events occur in both stateful and stateless sessions.
For example:
[source,java]
----
@Entity
class Order {
...
transient double total;
@PostLoad
void computeTotal() {
total = items.stream().mapToDouble(i -> i.price * i.quantity).sum();
}
...
}
----
If we need to interact with technical objects, we can place the lifecycle callback on a separate class, called an _entity listener_.
There are two distinct ways to attach listeners to an entity:
- The `@EntityListeners` annotation specifies one or more listeners for a given entity class:
+
[source,java]
----
@Entity
@EntityListeners(OrderEvents.class)
class Order { ... }
----
- On the other hand, the newer `@EntityListener` annotation lets a listener be attached to one or more entities without the need to annotate the entities themselves:
+
[source,java]
----
@EntityListener
class OrderEvents { ... }
----
An entity listener may inject CDI beans:
[source,java]
----
// entity listener class
class OrderEvents {
@Inject
Event newOrderEvent;
@PostPersist
void newOrder(Order order) {
// send a CDI event
newOrderEvent.fire(new NewOrder(order));
}
}
----
A single entity listener class may even be a generic listener that receives lifecycle callbacks for multiple different entity classes.
[TIP]
The venerable link:{doc-javadoc-url}org/hibernate/Interceptor.html[`Interceptor`] interface is a more powerful alternative to entity listeners.
`Interceptor` and its friend link:{doc-javadoc-url}org/hibernate/CustomEntityDirtinessStrategy.html[`CustomEntityDirtinessStrategy`] allow advanced users to augment the built-in handling of managed entities with custom behavior.
These interfaces are very useful if you're building your own persistence framework with Hibernate as the foundation.
We're about to see one way `Interceptor` can be used.
[[transient-vs-detached]]
=== Transient vs detached
Sometimes, Hibernate needs to be able to distinguish whether an entity instance is:
- a brand-new transient object the client just instantiated using `new`, or
- a detached object, which previously belonged to a persistence context.
This is a bit of a problem, since there's no good and efficient way for Hibernate to just tag an entity with a Post-it saying "I've seen you before".
Therefore, Hibernate uses heuristics.
The two most useful heuristics are:
1. If the entity has a <>, the value of the id field is inspected: if the value currently assigned to the id field is the default value for the type of the field, then the object is transient; otherwise, the object is detached.
2. If the entity has a <>, the value of the version field is inspected: if the value currently assigned to the version field is null or a negative number, then the object is transient; otherwise, the object is detached.
If the entity has neither a generated id, nor a version, Hibernate usually falls back to just doing something reasonable.
In extreme cases a `SELECT` query will be issued to determine whether a matching row exists in the database.
[WARNING]
These heuristics aren't perfect.
It's quite easy to confuse Hibernate by assigning a value to the id field or version field, making a new transient instance look like it's detached.
We therefore strongly discourage assigning values to fields annotated `@GeneratedValue` or `@Version` before passing an entity to Hibernate.
If the heuristics ever happen cause a real problem, you may implement your own Post-it tagging via link:{doc-javadoc-url}org/hibernate/Interceptor.html#isTransient(java.lang.Object)[`Interceptor.isTransient()`].
[[jdbc]]
=== Interacting directly with JDBC
From time to time we run into the need to write some code that calls JDBC directly.
The `EntityManager` now offers a convenient way to do this:
[source,java]
----
entityManager.runWithConnection((Connection connection) -> {
try (var callable = connection.prepareCall("{call myproc(?)}")) {
callable.setLong(1, argument);
callable.execute();
}
});
----
To return a value, use `callWithConnection()` instead of `runWithConnection()`.
// The Hibernate `Session` has an older, slightly simpler API:
//
// [source,java]
// ----
// entityManager.unwrap(Session.class).doWork(connection -> {
// try (var callable = connection.prepareCall("{call myproc(?)}")) {
// callable.setLong(1, argument);
// callable.execute();
// }
// });
// ----
//
// If the work returns a value, use `doReturningWork()` instead of `doWork()`.
The `Connection` passed to the work is the same connection being used by the session, and so any work performed using that connection occurs in the same transaction context.
[TIP]
====
In a container environment where transactions and database connections are managed by the container, this might not be the easiest way to obtain the JDBC connection.
====
[[advice]]
=== What to do when things go wrong
Object/relational mapping has been called the "Vietnam of computer science".
The person who made this analogy is American, and so one supposes that he meant to imply some kind of unwinnable war.
This is quite ironic, since at the very moment he made this comment, Hibernate was already on the brink of winning the war.
Today, Vietnam is a peaceful country with exploding per-capita GDP, and ORM is a solved problem.
That said, Hibernate is complex, and ORM still presents many pitfalls for the inexperienced, even occasionally for the experienced.
Sometimes things go wrong.
In this section we'll quickly sketch some general strategies for avoiding "quagmires".
- Understand SQL and the relational model.
Know the capabilities of your RDBMS.
Work closely with the DBA if you're lucky enough to have one.
Hibernate is not about "transparent persistence" for Java objects.
It's about making two excellent technologies work smoothly together.
- <> executed by Hibernate.
You cannot know that your persistence logic is correct until you've actually inspected the SQL that's being executed.
Even when everything seems to be "working", there might be a lurking <>.
- Be careful when <>.
In principle, you should update _both ends_ of the association.
But Hibernate doesn't strictly enforce that, since there are situations where such a rule would be too heavy-handed.
Whatever the case, it's up to you to maintain consistency across your model.
- Never <> across threads or concurrent transactions.
Have a strategy or framework to guarantee this never happens.
- When running queries that return large result sets, take care to consider the size of the <>.
Consider using a <>.
- Think carefully about the semantics of the <>, and how the caching policies impact transaction isolation.
- Avoid fancy bells and whistles you don't need.
Hibernate is incredibly feature-rich, and that's a good thing, because it serves the needs of a huge number of users, many of whom have one or two very specialized needs.
But nobody has _all_ those specialized needs.
In all probability, you have none of them.
Write your domain model in the simplest way that's reasonable, using the simplest mapping strategies that make sense.
- When something isn't behaving as you expect, _simplify_.
Isolate the problem.
Find the absolute minimum test case which reproduces the behavior, _before_ asking for help online.
Most of the time, the mere act of isolating the problem will suggest an obvious solution.
- If you're new to Hibernate, avoid frameworks and libraries that "wrap" JPA.
You need an excellent understanding of Hibernate and JPA _first_, before introducing unnecessary additional moving parts.
If there's any one criticism of Hibernate and ORM that sometimes _does_ ring true, it's that it takes you too far from direct control over JDBC.
An additional layer just takes you even further.
If you insist you really do need this extra layer, we beg you to consider https://hibernate.org/repositories/[Hibernate Data Repositories] instead of older third-party solutions.
- Avoid copy/pasting code from random bloggers or stackoverflow reply guys.
Many of the suggestions you'll find online just aren't the simplest solution, and many aren't correct for Hibernate 6 and 7.
Instead, _understand_ what you're doing; study the Javadoc of the APIs you're using; read the JPA specification; follow the advice we give in this document; go direct to the Hibernate team on Zulip.
(Sure, we can be a bit cantankerous at times, but we _do_ always want you to be successful.)
- Always consider other options.
You don't have to use Hibernate for _everything_.
---
### Documentation Src Main Asciidoc Introduction Introduction (`documentation/src/main/asciidoc/introduction/Introduction.adoc`)
[[introduction]]
== Introduction
:persistence: https://jakarta.ee/specifications/persistence/4.0/jakarta-persistence-spec-4.0-M4.pdf
:data: https://jakarta.ee/specifications/data/1.1/jakarta-data-1.1-m3.pdf
:query: https://jakarta.ee/specifications/query/1.0/jakarta-query-1.0-m2.pdf
Hibernate is usually described as a library that makes it easy to map Java classes to relational database tables.
But this formulation does no justice to the central role played by the relational data itself.
So a better description might be:
****
Hibernate makes *relational data* visible to a program written in Java, in a *natural* and *typesafe* form,
1. making it easy to write complex queries and work with their results,
2. letting the program easily synchronize changes made in memory with the database, respecting the ACID properties of transactions,
3. automatically handling concerns like temporal data, audit logging, multi-tenancy, and row-level security, and
4. allowing performance optimizations to be made after the basic persistence logic has already been written.
****
Here the relational data is the focus, along with the importance of type safety.
The goal of _object/relational mapping_ (ORM) is to eliminate fragile and untypesafe code, and make large programs easier to maintain in the long run.
ORM takes the pain out of persistence by relieving the developer of the need to hand-write tedious, repetitive, and fragile code for flattening graphs of objects to database tables and rebuilding graphs of objects from flat SQL query result sets.
Even better, ORM makes it much easier to tune performance later, after the basic persistence logic has already been written.
Actually, the problem that object/relational mapping solves has been mischaracterized for decades, and has very little to do with any so-called "mismatch" between classes and tables. The real problem is:
1. Data is stored in **normalized tables**.
2. The process of efficiently reading data from tables **<>**.
3. In an object-oriented program, we often want to work with data in something quite close to its **original normalized form**.
Therefore, the principal task of object/relational mapping is to _renormalize the data after reading it from the database_. This need exists even if the classes in our program are identical to the database tables.
[[orm-or-sql]]
[TIP]
// .ORM or SQL?
====
A perennial question is: should I use ORM, or plain SQL?
The answer is usually: _use both_.
JPA and Hibernate were designed to work _in conjunction with_ handwritten SQL.
You see, most programs with nontrivial data access logic will benefit from the use of ORM at least _somewhere_.
But if Hibernate is making things more difficult, for some particularly tricky piece of data access logic, the only sensible thing to do is to use something better suited to the problem!
Just because you're using Hibernate for persistence doesn't mean you have to use it for _everything_.
====
Let's underline the important point here: the goal of ORM is _not_ to hide SQL or the relational model.
After all, Hibernate's query language is link:{doc-query-language-url}[nothing more than an object-oriented dialect of ANSI SQL].
On the other hand, Hibernate does help smooth over many of the differences between relational databases and SQL dialects.
.*Read more: Is Hibernate a leaky abstraction?*
[%collapsible]
====
****
Hibernate--and ORM in general--has been accused of being a _leaky abstraction_, that is, of failing to completely hide the underlying relational database.
Is this true?
Well, as you can guess from what we've already said, the short answer is: yes, _and that's a good thing._
Of course, whether you consider an abstraction "leaky" depends on what you think it's trying to abstract.
Hibernate successfully abstracts many things: variations between dialects of SQL, messy interactions with JDBC, SQL object naming conventions, and so on.
But it doesn't even attempt to pretend there's anything other than a relational data model underlying all this.
The simple reason is performance. It's just not possible to <> in data access without acknowledging the nature of the underlying persistent representation.
We're old enough to have seen multiple generations of developer relearn this lesson by experience.
****
====
Developers often ask about the relationship between Hibernate and JPA, so let's bite that cookie first.
[[hibernate-and-jpa]]
=== Hibernate and JPA
Hibernate was the inspiration behind the _Java_ (now _Jakarta_) _Persistence API_, or JPA, and includes a complete implementation of the latest revision of link:{persistence}[this specification].
In recent years, the Hibernate team has led the efforts to modernize the Jakarta EE persistence specifications, culminating in the release of this three-headed hellhound: Persistence 4.0, Query 1.0, and Data 1.1.
[[history]]
.*Read more: The early history of Hibernate and JPA*
[%collapsible]
====
****
The Hibernate project began in 2001, when Gavin King's frustration with Entity Beans in EJB 2 boiled over.
It quickly overtook other open source and commercial contenders to become the most popular persistence solution for Java, and the book _Hibernate in Action_, written with Christian Bauer, was an influential bestseller.
In 2004, Gavin and Christian joined a tiny startup called JBoss, and other early Hibernate contributors soon followed: Max Rydahl Andersen, Emmanuel Bernard, Steve Ebersole, and Sanne Grinovero.
Soon after, Gavin joined the EJB 3 expert group and convinced the group to deprecate Entity Beans in favor of a brand-new persistence API modelled after Hibernate.
Later, members of the TopLink team got involved, and the Java Persistence API evolved as a collaboration between—primarily—Sun, JBoss, Oracle, and Sybase, under the leadership of Linda Demichiel.
Over the intervening two decades, _many_ talented people have contributed to the development of Hibernate.
We're all especially grateful to Steve, who has led the project for many years, since Gavin stepped back to focus on other work.
****
====
We can think of Hibernate in terms of four basic elements:
- an implementation of the JPA-defined APIs, most importantly, of the interfaces `EntityManagerFactory`, `EntityAgent`, and `EntityManager`, and of the JPA-defined O/R mapping annotations,
- a _native API_ exposing the full set of available functionality, centered around the interfaces link:{doc-javadoc-url}org/hibernate/SessionFactory.html[`SessionFactory`], which extends `EntityManagerFactory`,
link:{doc-javadoc-url}org/hibernate/StatelessSession.html[`StatelessSession`], which extends `EntityAgent`, and link:{doc-javadoc-url}org/hibernate/Session.html[`Session`], which extends `EntityManager`,
- a set of link:{doc-javadoc-url}org/hibernate/annotations/package-summary.html[_mapping annotations_] which augment the O/R mapping annotations defined by JPA, and which may be used with the JPA-defined interfaces, or with the native API, and
- finally, <>, which is responsible for generating the _static metamodel_ and implementations of Jakarta Data repositories.
Hibernate also offers a range of SPIs for frameworks and libraries which extend or integrate with Hibernate, but we're not interested in any of that stuff here.
image::images/api-overview.png[API overview,width=700,align="center"]
Before JPA 4, many teams chose to write their program in terms of `Session` and `SessionFactory`, to take advantage of the larger feature set accessible via these APIs.
Other teams chose to maximize portability to other implementations of JPA by, wherever reasonable, writing code in terms of `EntityManager` and `EntityManagerFactory`, falling back to the native APIs only where necessary.
JPA 4 tips the balance quite far in favor of the standard JPA APIs.
[IMPORTANT]
As of Jakarta Persistence 4.0, we feel that there's no longer much advantage to be had from the direct use of `Session` and `SessionFactory`, at least not most of the time.
New code can be written in terms of the standard `EntityManager` and `EntityManagerFactory` interfaces, and a broad range of Hibernate-specific extensions are made available as JPA _option objects_.
Whichever path you take, you will use the JPA-defined mapping annotations most of the time, and the Hibernate-defined annotations for more advanced mapping problems.
You might wonder if it's possible to develop an application using _only_ JPA-defined APIs, and, indeed, that's possible in principle.
JPA is a great baseline that really nails the basics of the object/relational mapping problem.
But without the extended mapping annotations, and without the occasional use of Hibernate-specific option objects, you miss out on much of the power of Hibernate.
Since Hibernate existed before JPA, and since JPA was modelled on Hibernate, we unfortunately have some competition and duplication in naming between the standard and native APIs.
For example:
.Examples of competing APIs with similar naming
|===
| Hibernate | JPA
| `org.hibernate.FlushMode` | `javax.persistence.FlushModeType`
| `org.hibernate.annotations.FetchMode` | `javax.persistence.FetchType`
| `@org.hibernate.annotations.Fetch` | `@jakarta.persistence.Fetch`
| `org.hibernate.query.Query` | `javax.persistence.Query`
| `org.hibernate.Cache` | `javax.persistence.Cache`
| `@org.hibernate.annotations.NamedQuery` | `@javax.persistence.NamedQuery`
| `@org.hibernate.annotations.Cache` | `@javax.persistence.Cacheable`
| `org.hibernate.relational.SchemaManager` | `jakarta.persistence.SchemaManager`
|===
Typically, the Hibernate-native APIs offer something a little extra that's missing in JPA, so this isn't exactly a _flaw_.
But it's something to watch out for.
[[hello-hibernate]]
=== Hello, Hibernate
Before we get deeper into the weeds, we'll quickly present a basic example program that will help you get started if you don't already have Hibernate integrated into your project.
We begin with a simple https://gradle.org[Gradle] build file:
[[build-gradle]]
[source,groovy,subs="attributes+"]
.`build.gradle`
----
plugins {
id 'java'
}
group = 'org.example'
version = '1.0-SNAPSHOT'
repositories {
mavenCentral()
}
dependencies {
// the GOAT ORM (required)
implementation 'org.hibernate.orm:hibernate-core:{fullVersion}'
// Hibernate Processor (strongly recommended)
annotationProcessor 'org.hibernate.orm:hibernate-processor:{fullVersion}'
// Jakarta Data support (optional)
implementation 'jakarta.data:jakarta.data-api:1.1.0-M4'
implementation 'jakarta.data:jakarta.data.stateful-api:1.1.0-M4'
// Hibernate Validator (optional)
implementation 'org.hibernate.validator:hibernate-validator:9.0.1.Final'
implementation 'org.glassfish.expressly:expressly:6.0.0'
// Agroal connection pool (optional)
runtimeOnly 'org.hibernate.orm:hibernate-agroal:{fullVersion}'
// logging via Log4j (recommended)
runtimeOnly 'org.apache.logging.log4j:log4j-core:2.26.0'
// H2 database (or JDBC driver of choice)
runtimeOnly 'com.h2database:h2:2.4.240'
}
----
Only the first of these dependencies is absolutely _required_ to run Hibernate.
Next, we'll add a logging configuration file for https://logging.apache.org/log4j/[log4j]:
[source,properties]
.`log4j2.properties`
----
rootLogger.level = info
rootLogger.appenderRefs = console
rootLogger.appenderRef.console.ref = console
# SQL statements (set level=debug to enable)
logger.hibernate.name = org.hibernate.SQL
logger.hibernate.level = info
# JDBC parameter binding (set level=trace to enable)
logger.jdbc-bind.name=org.hibernate.orm.jdbc.bind
logger.jdbc-bind.level=info
# JDBC result set extraction (set level=trace to enable)
logger.jdbc-extract.name=org.hibernate.orm.jdbc.extract
logger.jdbc-extract.level=info
# JDBC batching (set level=trace to enable)
logger.batch.name=org.hibernate.orm.jdbc.batch
logger.batch.level=info
# direct log output to the console
appender.console.name = console
appender.console.type = Console
appender.console.layout.type = PatternLayout
appender.console.layout.pattern = %highlight{[%p]} %m%n
----
Now we need some Java code.
We begin with our <>:
[[book]]
[source,java]
.`Book.java`
----
package org.hibernate.example;
import jakarta.persistence.Entity;
import jakarta.persistence.Id;
import jakarta.validation.constraints.NotNull;
@Entity
public class Book {
@Id
String isbn;
@NotNull
String title;
Book() {}
public Book(String isbn, String title) {
this.isbn = isbn;
this.title = title;
}
}
----
Finally, let's see code which <> and instantiates Hibernate and asks it to <> the entity.
Don't worry if this makes no sense at all right now.
It's the job of the rest of this guide to make all this crystal clear as we go along.
[[main-hibernate]]
[source,java]
.`Main.java`
----
import org.hibernate.example.*;
import jakarta.persistence.EntityManagerFactory;
import jakarta.persistence.FetchType;
import jakarta.persistence.PersistenceConfiguration;
import static java.lang.System.out;
import static jakarta.persistence.SchemaManagementAction.CREATE;
import static jakarta.persistence.PersistenceConfiguration.*;
import static org.hibernate.cfg.JdbcSettings.*;
EntityManagerFactory factory =
new PersistenceConfiguration("Bookshelf")
// all associations should be lazy by default
.defaultToOneFetchType(FetchType.LAZY)
// register the entity class
.managedClass(Book.class)
// use H2 in-memory database
.property(JDBC_URL, "jdbc:h2:mem:db1")
.property(JDBC_USER, "sa")
.property(JDBC_PASSWORD, "")
// set the Agroal connection pool size
.property(POOL_SIZE, 16)
// display SQL in console
.property(SHOW_SQL, true)
.property(FORMAT_SQL, true)
.property(HIGHLIGHT_SQL, true)
// export the inferred database schema
.schemaManagementDatabaseAction(CREATE)
// start Hibernate
.createEntityManagerFactory();
void main() {
// persist an entity
factory.runInTransaction(manager -> {
manager.persist(new Book("9781932394153", "Hibernate in Action"));
});
// query data using HQL
factory.runInTransaction(manager -> {
manager.createQuery("select isbn || ': ' || title from Book")
.ofType(String.class)
.getResultList()
.forEach(out::println);
});
// query data using criteria API
factory.runInTransaction(manager -> {
var builder = factory.getCriteriaBuilder();
var query = builder.createQuery(String.class);
var book = query.from(Book.class);
query.select(builder.concat(
List.of(book.get(Book_.isbn),
builder.literal(": "),
book.get(Book_.title))));
manager.createQuery(query)
.getResultList()
.forEach(out::println);
});
}
----
This code introduces two very central interfaces:
- the `EntityManagerFactory`, which in Hibernate is also an instance of link:{doc-javadoc-url}org/hibernate/SessionFactory.html[`SessionFactory`], and
- a mysterious `manager` object, which in JPA an instance of `EntityManager`, and in Hibernate is also an instance of link:{doc-javadoc-url}org/hibernate/Session.html[`Session`].
In this guide, we call each instance of `EntityManager` a _session_.
In practice, we never access the database directly from a `main()` method.
// So now let's now return to the question of how to organize persistence logic in a real system.
[[java-code]]
=== Writing Java code with Hibernate
If you're completely new to Hibernate and JPA, you might already be wondering how the persistence-related code is structured.
Well, typically, our persistence-related code comes in two layers:
. a representation of our data model in Java, which takes the form of a set of annotated entity classes, and
. a larger number of functions which interact with Hibernate's APIs to perform the persistence operations associated with our various transactions.
The first part, the data or "domain" model, is usually easier to write, but doing a great and very clean job of it will strongly affect your success in the second part.
Most people implement the domain model as a set of what we used to call "Plain Old Java Objects", that is, as simple Java classes with no direct dependencies on technical infrastructure, nor on application logic which deals with request processing, transaction management, communications, or interaction with the database.
[TIP]
====
Take your time with this code, and try to produce a Java model that's as close as reasonable to the relational data model. Avoid using exotic or advanced mapping features when they're not really needed.
When in the slightest doubt, map a foreign key relationship using `@ManyToOne` with `@OneToMany(mappedBy=...)` in preference to more complicated association mappings.
====
The second part of the code is much trickier to get right. This code must:
- manage transactions and sessions,
- interact with the database via the Hibernate session,
- publish CDI events and send JMS messages,
- fetch and prepare data needed by the UI, and
- handle failures.
[TIP]
====
Responsibility for transaction and session management, and for recovery from certain kinds of failure, is best handled in some sort of framework code.
====
// [TIP]
// ====
// A great way to handle CDI event publication is via a <>.
// Whereas we would never want to inject a CDI https://jakarta.ee/specifications/cdi/3.0/apidocs/[event publisher] into an entity object, it's perfectly fine to inject them in an entity listener.
// ====
We're going to <> and describe one good way to organize persistence logic, but we will emphasize that it's not the only way.
First, let's talk about entities.
[[domain-model]]
=== Entities
A class in the domain model which directly represents a relational database table is called an <>.
Entity classes are central to object persistence and to object/relational mapping.
They're also, typically, central players in the business logic of our application program.
Entities represent the _things_ in our business domain.
This makes them very important objects indeed!
Given how much weight an entity already bears due to its very nature, we need to think carefully before weighing it down with too many additional responsibilities.
[[entity-logic]]
.*Read more: Rich and anemic entities*
[%collapsible]
====
****
There exists an extensive online literature which posits that there are _rich domain models_, where entities have methods implementing interesting business logic, and _anemic domain models_, where the entities are pure data holders, and that a developer should hold an opinion that one or the other of these sorts of domain model is "better".
We do not hold any such opinion, and if you ask us for one, we will most likely suddenly discover somewhere else we need to be.
A more interesting question is not _how much_ logic belongs in the entity class, but _what sort_ of logic belongs there.
****
====
We think that an entity should never implement technical concerns, and should never obtain references to framework objects.
Nor should it hold extra mutable state which is not very directly related to its role in representing persistent state.
For example:
- an entity may compute totals and averages, even caching them if necessary, enforce its invariants, interact with and construct other entities, and so on, and its annotations express how it maps to database tables,
- but the entity should not call the `EntityManager` or a Jakarta Data repository, build a criteria query, send a JMS message, start a transaction, publish events to the CDI event bus, maintain a stateful queue of events to be published later, or anything of a similar nature.
One way to summarize this is:
> Entities do business logic; but they don't do orchestration.
Later, we'll discuss various ways to <>, <>, and <>.
Such code will always be external to the entity itself.
[[active-record]]
.*Read more: Active Record*
[%collapsible]
====
****
The discussion above expresses our "traditional" approach--which lay behind the design of Hibernate, of JPA, and of Jakarta Data--where entity classes are plain Java objects without dependence on framework code.
An alternative approach is the Active Record pattern, as exemplified by link:https://quarkus.io/guides/hibernate-orm-panache[Panache].
In Active Record, entity types inherit framework objects, and persistence operations are located directly on the entities.
You can think of this as merging the roles of entity and DAO/Repository into a single object.
Active Record comes with both upsides and downsides, but we don't mean to exclude it from consideration.
We must therefore slightly modify the prescription we've given above: in an Active Record, it's obviously OK to access the `EntityManager` and perform other persistence-related operations, and we therefore expect our Active Record class to look somewhat more "technical" than a trad entity.
But the basic principle remains intact: an entity does not do orchestration, it does not manage transactions, it does not obtain references to _other_ sorts of framework object, and it does not hold mutable state unrelated to its persistent state.
****
====
From now on, we're going to assume that entities are implemented as plain Java classes.
An entity can't persist itself.
For that we need a session.
[[stateful-and-stateless-sessions]]
=== Stateful and stateless sessions
It should be very clear from the example code <>, that the session is also a very important object.
It exposes basic operations like `persist()` and `createQuery()`, and so it's our first port of call when we want to <> via Hibernate.
In the code we just saw, we've used a _stateful session_.
Later, we'll learn about the idea of a <>.
Oversimplifying for now, you can think of it as a cache of data which has been read in the current transaction.
Thus, in the architecture of Hibernate, it's sometimes called the _first-level cache_.
Each stateful session -- that is, every JPA <> -- has its own persistence context.
But stateful sessions are not the only possibility.
The new JPA 4 `EntityAgent` interface offers a way to interact with Hibernate _without_ going through a persistence context.
In Hibernate, every `EntityAgent` is also an instance of the much older interface <>, and so we often call an instance of `EntityAgent` a _stateless session_.
The programming model for stateless sessions is somewhat different.
.*Read more: Stateless sessions*
[%collapsible]
====
****
Among our biggest regrets is that we didn't give enough love to `StatelessSession` twenty years ago.
Sure, a stateful session is in some sense more powerful, or at least more magical.
But with that magic comes a loss of direct control over persistence operations, and some traps for inexperienced users.
A significant minority of developers find working with a persistence context frustrating, and they would surely be better served by a stateless session.
// - We used to view `StatelessSession` as an API directed toward very specific usage patterns, in particular, batch processing of large numbers of entities.
// As a result, we left out certain functionality -- for example, use of the <> -- which didn't seem relevant to those use cases.
// This left `StatelessSession` lacking feature parity with `Session`, and it was a mistake.
// In Hibernate 7, we've fixed this mistake.
// A `StatelessSession` now offers essentially all the functionality of Hibernate except, naturally, the first-level cache.
//
// - Compounding our error, we left `StatelessSession` out of JPA.
// This meant that a large number of Hibernate users _didn't even realize this option existed._
// We promise to make sure there are stateless sessions in Jakarta Persistence 4.
So, finally, let us state for the record: we messed up here.
Hibernate is all about _object/relational mapping;_ persistence contexts are something extra.
They're like the salsa verde in a Mexican dish--delicious, but optional--not like the green curry in a bowl of kaeng khiao wan.
You don't have to use stateful sessions, and you're not doing anything wrong if you decide to use stateless sessions instead.
****
====
A key decision for any new project is which of these programming models to take as a baseline.
Fortunately, the two models aren't mutually exclusive.
This is a friendly competition, where the two APIs are designed to complement each other.
Even if we decide to use stateful ``EntityManager``s most of the time, we can still use an `EntityAgent` wherever it's more convenient.
=== Managing sessions and transactions
One very nice aspect of the code we <>, which we wish to draw your attention to, is that session and transaction management is handled by generic "framework" code, just as we already recommended above.
Later, we'll discuss the traps we can fall into when we write custom code to manage <> and <>.
It's certainly not impossible to get these concerns right, but it's easy enough to get them wrong, especially if we starting getting too creative.
Since we know that you, dear reader, are nothing if not creative, we encourage you to let your container or framework take care of this stuff.
In our code, we used the <> method of `EntityManagerFactor`.
But you might prefer to use something else, for example:
- in a container environment like Jakarta EE or https://quarkus.io[Quarkus]https://xxx[,] _container-managed transactions_ and _container-managed persistence contexts_, or
- something you write yourself.
The important thing is that calls like `createEntityManager()` and `getTransaction().begin()` don't belong in regular program logic, because it's tricky and tedious to get the error handling correct.
[[organizing-persistence]]
=== Repositories
In a real program, persistence logic like the code shown above is usually interleaved with other sorts of code, including logic:
- implementing the rules of the business domain, or
- for interacting with the user.
Therefore, many developers quickly--even _too quickly_, in our opinion--reach for ways to isolate the persistence logic into some sort of separate architectural layer.
For decades, there was no clearly "best" way to implement a persistence layer based on Hibernate, and frameworks which intended to simplify life for the developer seemed to us to actually make things worse.
With link:{data}[Jakarta Data 1.1], as implemented by <>, the situation has changed, and the easiest way to write a persistence layer is now very clear.
.*Read more: Why we changed our mind about repositories*
[%collapsible]
====
****
At the time we wrote _An Introduction to Hibernate 6_, we were frustrated with the limitations of popular frameworks which claimed to simplify the use of JPA by wrapping and hiding the `EntityManager`.
In our considered opinion, such frameworks typically made JPA harder to use, sometimes misleading users into misuse of the technology.
The birth of the Jakarta Data specification has obsoleted our arguments against repositories, along with the older frameworks which were the source of our frustration.
Jakarta Data--as realized by Hibernate Data Repositories--offers a clean but very flexible way to organize code, along with much better compile-time type safety, without getting in the way of direct use of the `EntityAgent` or `EntityManager`.
Unlike other repository frameworks, Hibernate Data Repositories offers something that plain JPA simply doesn’t have: full compile-time type safety for your queries. To learn more, please refer to link:{doc-data-repositories-url}[Introducing Hibernate Data Repositories].
****
====
For now, let's see how we could rewrite our <> using a repository.
[[repository-hibernate]]
[source,java]
.`Library.java`
----
package org.hibernate.example;
import jakarta.data.repository.Query;
import jakarta.data.repository.Repository;
import jakarta.persistence.EntityAgent;
import java.util.List;
@Repository
public interface Library {
// access to the underlying stateful session
EntityManager manager();
// persist a book via the session
@Persist
void persist(Book entity);
// a query method with a generated implementation
// the query is fully validated at compile time!
@Query("select isbn || ': ' || title from Book")
List summaries();
// a repository method implemented by hand
default List summariesByCriteria() {
var builder = manager().getCriteriaBuilder();
var query = builder.createQuery(String.class);
var book = query.from(Book.class);
query.select(builder.concat(
List.of(book.get(Book_.isbn),
builder.literal(": "),
book.get(Book_.title))));
return manager().createQuery(query)
.getResultList();
}
}
----
Notice that the `@Repository` programming model lets us freely choose between:
- implementing a repository method by hand, and calling the `EntityManager` or `EntityAgent` directly, or
- having the implementation generated for us.
We could simplify our <> method as follows:
[source,java]
.`Main.java`
----
...
EntityManagerFactory factory =
new PersistenceConfiguration("Bookshelf")
// all associations should be lazy by default
.defaultToOneFetchType(FetchType.LAZY)
// register the entity class
.managedClass(Book.class)
// register the repository interface!
.managedClass(Library.class)
// use H2 in-memory database
.property(JDBC_URL, "jdbc:h2:mem:db1")
.property(JDBC_USER, "sa")
.property(JDBC_PASSWORD, "")
// set the Agroal connection pool size
.property(POOL_SIZE, 16)
// display SQL in console
.property(SHOW_SQL, true)
.property(FORMAT_SQL, true)
.property(HIGHLIGHT_SQL, true)
// export the inferred database schema
.schemaManagementDatabaseAction(CREATE)
// start Hibernate
.createEntityManagerFactory();
void main() {
// persist an entity
factory.runInTransaction(manager -> {
Library library = new _Library(manager);
library.persist(new Book("9781932394153", "Hibernate in Action"));
});
// query data using HQL
factory.runInTransaction(manager -> {
Library library = new _Library(manager);
library.summaries().forEach(out::println);
});
// query data using criteria API
factory.runInTransaction(manager -> {
Library library = new _Library(manager);
library.summariesByCriteria().forEach(out::println);
});
}
----
In a real system we would not directly instantiate the generated `_Library` repository implementation class.
Instead, we would obtain the `Library` via dependency injection.
In Quarkus, WildFly, or any Jakarta EE container, https://www.cdi-spec.org[CDI] takes care of injecting repository objects.
[source,java]
@Inject Library library;
[IMPORTANT]
Notice that we registered the repository interface with the persistence unit via `managedClass()`.
// If we had used `persistence.xml` to configure Hibernate, we would have listed it as a ``.
Now that we have a rough picture of what our persistence logic might look like, it's natural to ask how we should test our code.
[[testing]]
=== Testing persistence logic
:h2: http://www.h2database.com
When we write tests for our persistence logic, we're going to need:
1. a database, with
2. an instance of the schema mapped by our persistent entities, and
3. a set of test data, in a well-defined state at the beginning of each test.
It might seem obvious that we should test against the same database system that we're going to use in production, and, indeed, we should certainly have at least _some_ tests for this configuration.
But on the other hand, tests which perform I/O are much slower than tests which don't, and most databases can't be set up to run in-process.
So, since most persistence logic written using Hibernate 6 is _extremely_ portable between databases, it often makes good sense to test against an in-memory Java database.
({h2}[H2] is the one we recommend.)
[CAUTION]
====
We do need to be careful here if our persistence code uses native SQL, or if it uses concurrency-management features like pessimistic locks.
====
Whether we're testing against our real database, or against an in-memory Java database, we'll need to export the schema at the beginning of a test suite.
We _usually_ do this when we create the `EntityManagerFactory`, and so traditionally we've used a <> for this.
The JPA-standard property is `jakarta.persistence.schema-generation.database.action`.
But if we're using `PersistenceConfiguration` to configure Hibernate, we could write:
[source,java]
----
configuration.schemaManagementDatabaseAction(SchemaManagementAction.DROP_AND_CREATE);
----
Alternatively, we may use the link:{doc-javadoc-url}org/hibernate/relational/SchemaManager.html[`SchemaManager`] API to export the schema.
This option is especially convenient when writing tests.
[source,java]
----
factory.getSchemaManager().create(true);
----
Since executing DDL statements is very slow on many databases, we don't want to do this before every test.
Instead, to ensure that each test begins with the test data in a well-defined state, we need to do two things before each test:
1. clean up any mess left behind by the previous test, and then
2. reinitialize the test data.
We may truncate all the tables, leaving an empty database schema, using the `SchemaManager`.
[source,java]
----
factory.getSchemaManager().truncate();
----
After truncating tables, we might need to initialize our test data.
We may specify test data in a SQL script, for example:
[[import.sql]]
[source,sql]
./import.sql
----
insert into Books (isbn, title) values ('9781932394153', 'Hibernate in Action')
insert into Books (isbn, title) values ('9781932394887', 'Java Persistence with Hibernate')
insert into Books (isbn, title) values ('9781617290459', 'Java Persistence with Hibernate, Second Edition')
----
If we name this file `import.sql`, and place it in the root classpath, that's all we need to do.
Otherwise, we need to specify the file in the <> `jakarta.persistence.sql-load-script-source`.
If we're using `PersistenceConfiguration` to configure Hibernate, we could write:
[source,java]
----
configuration.property(PersistenceConfiguration.SCHEMAGEN_LOAD_SCRIPT_SOURCE,
"/org/example/test-data.sql");
----
The SQL script is executed every time `create()`, `populate()`, or `truncate()` is called.
[TIP]
====
There's another sort of mess a test can leave behind: cached data in the <>.
We recommend _disabling_ Hibernate's second-level cache for most sorts of testing.
Alternatively, if the second-level cache is not disabled, then before each test we should call:
[source,java]
----
factory.getCache()
.unwrap(org.hibernate.Cache.class)
.evictAllRegions();
----
====
Now, suppose you've followed our advice, and written your entities and query methods to minimize dependencies on "infrastructure", that is, on libraries other than JPA and Hibernate, on frameworks, on container-managed objects, and even on bits of your own system which are hard to instantiate from scratch.
Then testing persistence logic is now straightforward!
You'll need to:
- bootstrap Hibernate and create a `EntityManagerFactory` at the beginning of your test suite (we've already seen how to do that), and
- create a new `EntityManager` or `EntityAgent` inside each `@Test` method, using `inTransaction()`, for example.
Actually, some tests might require multiple sessions.
But be careful not to leak a session between different tests.
[TIP]
=====
Another important test we'll need is one which validates our <> against the actual database schema.
This is again the job of the schema management tooling, either:
[source,java]
----
configuration.schemaManagementDatabaseAction(SchemaManagementAction.VALIDATE);
----
Or:
[source,java]
----
factory.getSchemaManager().validate();
----
This "test" is one which many people like to run even in production, when the system starts up.
=====
[[overview]]
=== Overview
It's now time to begin our journey toward actually _understanding_ the code we saw earlier.
This introduction will guide you through the basic tasks involved in developing a program that uses Hibernate for persistence:
1. configuring and bootstrapping Hibernate, and obtaining an instance of `EntityManagerFactory`,
2. writing a _domain model_, that is, a set of _entity classes_ which represent the persistent types in your program, and which map to tables of your database,
3. customizing these mappings when the model maps to a pre-existing relational schema,
4. using the `EntityManager` or `EntityAgent` to perform operations which query the database and return entity instances, or which update the data held in the database,
5. using Hibernate Processor to improve compile-time type-safety,
6. writing complex queries using the Hibernate Query Language (HQL) or native SQL, and, finally
7. tuning performance of the data access logic.
Naturally, we'll start at the top of this list, with the least-interesting topic: _configuration_.
---
### Documentation Src Main Asciidoc Introduction Mapping (`documentation/src/main/asciidoc/introduction/Mapping.adoc`)
[[object-relational-mapping]]
== Object/relational mapping
Given a domain model—that is, a collection of entity classes decorated with all the fancy annotations we <> in the previous chapter—Hibernate will happily go away and infer a complete relational schema, and even <> if you ask politely.
The resulting schema will be entirely sane and reasonable, though if you look closely, you'll find some flaws.
For example, by default, every `VARCHAR` column will have the same length, `VARCHAR(255)`.
But the process I just described—which we call _top down_ mapping—simply doesn't fit the most common scenario for the use of O/R mapping.
It's only rarely that the Java classes precede the relational schema.
Usually, _we already have a relational schema_, and we're constructing our domain model around the schema.
This is called _bottom up_ mapping.
[TIP]
// ."Legacy" data
====
Developers often refer to a pre-existing relational database as "legacy" data.
This tends to conjure images of bad old "legacy apps" written in COBOL or something.
But legacy data is valuable, and learning to work with it is important.
====
Especially when mapping bottom up, we often need to customize the inferred object/relational mappings.
This is a somewhat tedious topic, and so we don't want to spend too many words on it.
Instead, we'll quickly skim the most important mapping annotations.
[[case-convention]]
.*Read more: Hibernate SQL case convention*
[%collapsible]
====
****
Computers have had lowercase letters for rather a long time now.
Most developers learned long ago that text written in MixedCase, camelCase, or even snake_case is easier to read than text written in SHOUTYCASE.
This is just as true of SQL as it is of any other language.
Therefore, for over twenty years, the convention on the Hibernate project has been that:
- query language identifiers are written in `lowercase`,
- table names are written in `MixedCase`, and
- column names are written in `camelCase`.
That is to say, we simply adopted Java's excellent conventions and applied them to SQL.
Now, there's no way we can force you to follow this convention, even if we wished to.
Hell, you can easily write a `PhysicalNamingStrategy` which makes table and column names ALL UGLY AND SHOUTY LIKE THIS IF YOU PREFER.
But, _by default_, it's the convention Hibernate follows, and it's frankly a pretty reasonable one.
****
====
[[mapping-inheritance]]
=== Mapping entity inheritance hierarchies
In <> we saw that entity classes may exist within an inheritance hierarchy.
There's three basic strategies for mapping an entity hierarchy to relational tables.
Let's put them in a table, so we can more easily compare the points of difference between them.
.Entity inheritance mapping strategies
|===
| Strategy | Mapping | Polymorphic queries | Constraints | Normalization | When to use it
| `SINGLE_TABLE`
| Map every class in the hierarchy to the same table, and uses the value of a _discriminator column_ to determine which concrete class each row represents.
| To retrieve instances of a given class, we only need to query the one table.
| Attributes declared by subclasses map to columns without `NOT NULL` constraints, and so their non-nullability is enforced via a `CHECK` constraint.
Any association may have a `FOREIGN KEY` constraint. 🤓
| Subclass data is denormalized. 🧐
| Works well when subclasses declare few or no additional attributes.
| `JOINED`
| Map every class in the hierarchy to a separate table, but each table only maps the attributes declared by the class itself.
Optionally, a discriminator column may be used.
a| To retrieve instances of a given class, we must `JOIN` the table mapped by the class with:
- all tables mapped by its superclasses and
- all tables mapped by its subclasses.
| Any attribute may map to a column with a `NOT NULL` constraint. 🤓
Any association may have a `FOREIGN KEY` constraint. 🤓
| The tables are normalized. 🤓
| The best option when we care a lot about constraints and normalization.
| `TABLE_PER_CLASS`
| Map every concrete class in the hierarchy to a separate table, but denormalize all inherited attributes into the table.
| To retrieve instances of a given class, we must take a `UNION` over the table mapped by the class and the tables mapped by its subclasses.
| Associations targeting a superclass cannot have a corresponding `FOREIGN KEY` constraint in the database. 💀💀
Any attribute may map to a column with a `NOT NULL` constraint. 🤓
| Superclass data is denormalized. 🧐
| Not very popular.
From a certain point of view, competes with `@MappedSuperclass`.
|===
The three mapping strategies are enumerated by `InheritanceType`.
We specify an inheritance mapping strategy using the `@Inheritance` annotation.
For mappings with a _discriminator column_, we should:
- specify the discriminator column name and type by annotating the root entity `@DiscriminatorColumn`, and
- specify the values of this discriminator by annotating each entity in the hierarchy `@DiscriminatorValue`.
// [[single-table-inheritance]]
// === Single table inheritance
For single table inheritance we always need a discriminator:
[source,java]
----
@Entity
@DiscriminatorColumn(discriminatorType=CHAR, name="kind")
@DiscriminatorValue('P')
class Person { ... }
@Entity
@DiscriminatorValue('A')
class Author { ... }
----
We don't need to explicitly specify `@Inheritance(strategy=SINGLE_TABLE)`, since that's the default.
// [[multiple-table-inheritance]]
// === Multiple table inheritance
For `JOINED` inheritance we don't need a discriminator:
[source,java]
----
@Entity
@Inheritance(strategy=JOINED)
class Person { ... }
@Entity
class Author { ... }
----
[TIP]
// .Discriminator columns for `JOINED` inheritance
====
However, we can add a discriminator column if we like, and in that case the generated SQL for polymorphic queries is slightly simpler.
====
Similarly, for `TABLE_PER_CLASS` inheritance we have:
[source,java]
----
@Entity
@Inheritance(strategy=TABLE_PER_CLASS)
class Person { ... }
@Entity
class Author { ... }
----
[NOTE]
// .Discriminator columns for `TABLE_PER_CLASS` inheritance
====
Hibernate doesn't allow discriminator columns for `TABLE_PER_CLASS` inheritance mappings, since they would make no sense, and offer no advantage.
====
Notice that in this last case, a polymorphic association like:
[source,java]
----
@ManyToOne Person person;
----
is a bad idea, since it's impossible to create a foreign key constraint that targets both mapped tables.
// [[mixing-inheritance]]
// === Mixed inheritance
//
// Hibernate doesn't support mixing ``InheritanceType``s within a single entity hierarchy.
// However, it's possible to emulate a mix of `SINGLE_TABLE` and `JOINED` inheritance using the `@SecondaryTable` annotation.
[CAUTION]
====
It's quite easy to overuse inheritance.
We've occasionally seen extreme cases where a `JOINED` inheritance hierarchy includes _hundreds_ of entities, spanning hundreds of tables.
Efficiently querying such a hierarchy is an almost impossible task for Hibernate.
Fortunately, a `JOINED` inheritance relationship can always be remodeled as a <>, allowing much more efficient queries.
In general, a single entity inheritance hierarchy should never span more than a few tables, including secondary tables.
====
[[table-mappings]]
=== Mapping to tables
The following annotations specify exactly how elements of the domain model map to tables of the relational model:
.Annotations for mapping tables
[%breakable,cols="25,~"]
|===
| Annotation | Purpose
| `@Table` | Map an entity class to its primary table
| `@SecondaryTable` | Define a secondary table for an entity class
| `@JoinTable` | Map a many-to-many or many-to-one association to its association table
| `@CollectionTable` | Map an `@ElementCollection` to its table
|===
The first two annotations are used to map an entity to its _primary table_ and, optionally, one or more _secondary tables_.
[[entity-table-mappings]]
=== Mapping entities to tables
By default, an entity maps to a single table, which may be specified using `@Table`:
[source,java]
----
@Entity
@Table(name="People")
class Person { ... }
----
However, the `@SecondaryTable` annotation allows us to spread its attributes across multiple _secondary tables_.
[source,java]
----
@Entity
@Table(name="Books")
@SecondaryTable(name="Editions")
class Book { ... }
----
The `@Table` annotation can do more than just specify a name:
.`@Table` annotation members
[%breakable,cols="20,~"]
|===
| Annotation member | Purpose
| `name` | The name of the mapped table
| `schema` 💀 | The schema to which the table belongs
| `catalog` 💀 | The catalog to which the table belongs
| `uniqueConstraints` | One or more `@UniqueConstraint` annotations declaring multi-column unique constraints
| `indexes` | One or more `@Index` annotations each declaring an index
| `check` | One or more `@CheckConstraint` annotations declaring multi-column check constraints
| `comment` | A DDL comment
|===
[%unbreakable]
[TIP]
// .If you don't need to, don't hardcode the schema and catalog
====
It only makes sense to explicitly specify the `schema` in annotations if the domain model is spread across multiple schemas.
Otherwise, it's a bad idea to hardcode the schema (or catalog) in a `@Table` annotation.
Instead:
- set the configuration property `hibernate.default_schema` (or `hibernate.default_catalog`), or
- simply specify the schema in the JDBC connection URL.
====
The `@SecondaryTable` annotation is even more interesting:
.`@SecondaryTable` annotation members
[%breakable,cols="20,~"]
|===
| Annotation member | Purpose
| `name` | The name of the mapped table
| `schema` 💀 | The schema to which the table belongs
| `catalog` 💀 | The catalog to which the table belongs
| `uniqueConstraints` | One or more `@UniqueConstraint` annotations declaring multi-column unique constraints
| `indexes` | One or more `@Index` annotations each declaring an index
| `pkJoinColumns` | One or more `@PrimaryKeyJoinColumn` annotations, specifying <>
| `foreignKey` | A `@ForeignKey` annotation specifying the name of the `FOREIGN KEY` constraint on the ``@PrimaryKeyJoinColumn``s
| `check` | One or more `@CheckConstraint` annotations declaring multi-column check constraints
| `comment` | A DDL comment
|===
[TIP]
====
Using `@SecondaryTable` on a subclass in a `SINGLE_TABLE` entity inheritance hierarchy gives us a sort of mix of `SINGLE_TABLE` with `JOINED` inheritance.
====
[[join-table-mappings]]
=== Mapping associations to tables
The `@JoinTable` annotation specifies an _association table_, that is, a table holding foreign keys of both associated entities.
This annotation is usually used with `@ManyToMany` associations:
[source,java]
----
@Entity
class Book {
...
@ManyToMany
@JoinTable(name="BooksAuthors")
Set authors;
...
}
----
.*Show DDL*
[%collapsible%closed]
====
[source,sql]
create table BooksAuthors (
Book_isbn varchar(255) not null,
authors_ssn varchar(255) not null,
primary key (Book_isbn, authors_ssn)
)
====
But it's even possible to use it to map a `@ManyToOne` or `@OneToOne` association to an association table.
[source,java]
----
@Entity
class Book {
...
@ManyToOne(fetch=LAZY)
@JoinTable(name="BookPublisher")
Publisher publisher;
...
}
----
.*Show DDL*
[%collapsible%closed]
====
[source,sql]
create table BookPublisher (
publisher_id bigint not null,
isbn varchar(255) not null,
primary key (isbn)
)
====
Here, there should be a `UNIQUE` constraint or `PRIMARY KEY` on one of the columns of the association table.
[source,java]
----
@Entity
class Author {
...
@OneToOne(optional=false, fetch=LAZY)
@JoinTable(name="AuthorPerson")
Person author;
...
}
----
.*Show DDL*
[%collapsible%closed]
====
[source,sql]
create table AuthorPerson (
author_ssn varchar(255) not null unique,
ssn varchar(255) not null,
primary key (ssn)
)
====
Here, there should be a `UNIQUE` constraint or `PRIMARY KEY` on _both_ columns of the association table.
Finally, `@JoinTable` may also be used with a <>.
[source,java]
----
@OneToMany // no matching @ManyToOne
@JoinTable(name="PublishedBooks")
Set books;
----
.*Show DDL*
[%collapsible%closed]
====
[source,sql]
create table PublishedBooks (
Publisher_id bigint not null,
books_isbn varchar(255) not null,
primary key (books_isbn)
)
====
Here there is a `UNIQUE` or `PRIMARY KEY` constraint on the foreign key of the `Book` table in the join table `PublishedBooks`.
.`@JoinTable` annotation members
[%breakable,cols="20,~"]
|===
| Annotation member | Purpose
| `name` | The name of the mapped association table
| `schema` 💀 | The schema to which the table belongs
| `catalog` 💀 | The catalog to which the table belongs
| `uniqueConstraints` | One or more `@UniqueConstraint` annotations declaring multi-column unique constraints
| `indexes` | One or more `@Index` annotations each declaring an index
| `joinColumns` | One or more `@JoinColumn` annotations, specifying <> to the table of the owning side
| `inverseJoinColumns` | One or more `@JoinColumn` annotations, specifying <> to the table of the unowned side
| `foreignKey` | A `@ForeignKey` annotation specifying the name of the `FOREIGN KEY` constraint on the ``joinColumns``s
| `inverseForeignKey` | A `@ForeignKey` annotation specifying the name of the `FOREIGN KEY` constraint on the ``inverseJoinColumns``s
| `check` | One or more `@CheckConstraint` annotations declaring multi-column check constraints
| `comment` | A DDL comment
|===
To better understand these annotations, we must first discuss column mappings in general.
[[column-mappings]]
=== Mapping to columns
These annotations specify how elements of the domain model map to columns of tables in the relational model:
.Annotations for mapping columns
[%breakable,cols="25,~"]
|===
| Annotation | Purpose
| `@Column` | Map an attribute to a column
| `@JoinColumn` | Map an association to a foreign key column
| `@PrimaryKeyJoinColumn` | Map the primary key used to join a secondary table with its primary, or a subclass table in `JOINED` inheritance with its root class table
| `@OrderColumn` | Specifies a column that should be used to maintain the order of a `List`.
| `@MapKeyColumn` | Specified a column that should be used to persist the keys of a `Map`.
|===
We'll come back to the last two annotations much later, in <>.
We use the `@Column` annotation to map basic attributes.
[[regular-column-mappings]]
=== Mapping basic attributes to columns
The `@Column` annotation is not only useful for specifying the column name.
.`@Column` annotation members
[%breakable,cols="20,~"]
|===
| Annotation member | Purpose
| `name` | The name of the mapped column
| `table` | The name of the table to which this column belongs
| `length` | The length of a `VARCHAR`, `CHAR`, or `VARBINARY` column type
| `precision` | The decimal digits of precision of a `FLOAT`, `DECIMAL`, or `NUMERIC` type
| `scale` | The scale of a `DECIMAL` or `NUMERIC` column type, the digits of precision that occur to the right of the decimal point
| `secondPrecision` | The digits of precision occurring to the right of the decimal point in the seconds field of a `TIME`, or `TIMESTAMP` column type
| `unique` | Whether the column has a `UNIQUE` constraint
| `nullable` | Whether the column has a `NOT NULL` constraint
| `insertable` | Whether the column should appear in generated SQL `INSERT` statements
| `updatable` | Whether the column should appear in generated SQL `UPDATE` statements
| `columnDefinition` 💀| A DDL fragment that should be used to declare the column
| `check` | One or more `@CheckConstraint` annotations declaring single-column check constraints
| `comment` | A DDL comment
|===
[TIP]
// .Use of `columnDefinition` results in unportable DDL
====
We no longer recommend the use of `columnDefinition` since it results in unportable DDL.
Hibernate has much better ways to customize the generated DDL using techniques that result in portable behavior across different databases.
====
Here we see four different ways to use the `@Column` annotation:
[source,java]
----
@Entity
@Table(name="Books")
@SecondaryTable(name="Editions",
foreignKey = @ForeignKey(name="BooksToEditionsById"))
class Book {
@Id @GeneratedValue
@Column(name="bookId") // customize column name
Long id;
@Column(length=100, nullable=false) // declare column as VARCHAR(100) NOT NULL
String title;
@Column(length=17, unique=true, nullable=false) // declare column as VARCHAR(17) NOT NULL UNIQUE
String isbn;
@Column(table="Editions", updatable=false) // column belongs to the secondary table, and is never updated
int edition;
}
----
.*Show DDL*
[%collapsible%closed]
====
[source,sql]
create table Books (
bookId bigint not null,
isbn varchar(17) not null unique,
title varchar(100) not null,
primary key (bookId)
)
create table Editions (
edition integer,
bookId bigint not null,
primary key (bookId)
)
alter table if exists Editions
add constraint BooksToEditionsById
foreign key (bookId)
references Books
====
Note that we have used the `@ForeignKey` annotation to assign a name to the foreign key constraint.
We don't use `@Column` to map associations.
[[join-column-mappings]]
=== Mapping associations to foreign key columns
The `@JoinColumn` annotation is used to customize a foreign key column.
.`@JoinColumn` annotation members
[%breakable,cols="20,~"]
|===
| Annotation member | Purpose
| `name` | The name of the mapped foreign key column
| `table` | The name of the table to which this column belongs
| `referencedColumnName` | The name of the column to which the mapped foreign key column refers
| `unique` | Whether the column has a `UNIQUE` constraint
| `nullable` | Whether the column has a `NOT NULL` constraint
| `insertable` | Whether the column should appear in generated SQL `INSERT` statements
| `updatable` | Whether the column should appear in generated SQL `UPDATE` statements
| `columnDefinition` 💀| A DDL fragment that should be used to declare the column
| `foreignKey` | A `@ForeignKey` annotation specifying the name of the `FOREIGN KEY` constraint
| `check` | One or more `@CheckConstraint` annotations declaring single-column check constraints
| `comment` | A DDL comment
|===
A foreign key column doesn't necessarily have to refer to the primary key of the referenced table.
It's quite acceptable for the foreign key to refer to any other unique key of the referenced entity, even to a unique key of a secondary table.
Here we see how to use `@JoinColumn` to define a `@ManyToOne` association mapping a foreign key column which refers to the `@NaturalId` of `Book`:
[source,java]
----
@Entity
@Table(name="Items")
class Item {
...
@ManyToOne(optional=false) // implies nullable=false
@JoinColumn(name = "bookIsbn", referencedColumnName = "isbn", // a reference to a non-PK column
foreignKey = @ForeignKey(name="ItemsToBooksBySsn")) // supply a name for the FK constraint
Book book;
...
}
----
.*Show DDL*
[%collapsible%closed]
====
[source,sql]
create table Items (
id bigint not null,
bookIsbn varchar(17) not null,
primary key (id)
)
alter table if exists Items
add constraint ItemsToBooksBySsn
foreign key (bookIsbn)
references Books (isbn)
====
In case this is confusing:
- `bookIsbn` is the name of the foreign key column in the `Items` table,
- it refers to a unique key `isbn` in the `Books` table, and
- it has a foreign key constraint named `ItemsToBooksBySsn`.
Note that the `foreignKey` member is completely optional and only affects DDL generation.
[TIP]
// .Foreign key constraint names
====
If you don't supply an explicit name using `@ForeignKey`, Hibernate will generate a quite ugly name.
The reason for this is that the maximum length of foreign key names on some databases is extremely constrained, and we need to avoid collisions.
To be fair, this is perfectly fine if you're only using the generated DDL for testing.
You can customize the generated constraint names by writing your own <>.
====
For composite foreign keys we might have multiple `@JoinColumn` annotations:
[source,java]
----
@Entity
@Table(name="Items")
class Item {
...
@ManyToOne(optional=false)
@JoinColumn(name = "bookIsbn", referencedColumnName = "isbn")
@JoinColumn(name = "bookPrinting", referencedColumnName = "printing")
Book book;
...
}
----
If we need to specify the `@ForeignKey`, this starts to get a bit messy:
[source,java]
----
@Entity
@Table(name="Items")
class Item {
...
@ManyToOne(optional=false)
@JoinColumns(value = {@JoinColumn(name = "bookIsbn", referencedColumnName = "isbn"),
@JoinColumn(name = "bookPrinting", referencedColumnName = "printing")},
foreignKey = @ForeignKey(name="ItemsToBooksBySsn"))
Book book;
...
}
----
For associations mapped to a `@JoinTable`, fetching the association requires two joins, and so we must declare the ``@JoinColumn``s inside the `@JoinTable` annotation:
[source,java]
----
@Entity
class Book {
@Id @GeneratedValue
Long id;
@ManyToMany
@JoinTable(joinColumns=@JoinColumn(name="bookId"),
inverseJoinColumns=@joinColumn(name="authorId"),
foreignKey=@ForeignKey(name="BooksToAuthors"))
Set authors;
...
}
----
Again, the `foreignKey` member is optional.
[TIP]
====
For mapping a `@OneToOne` association <> with `@MapsId`, Hibernate lets us use either `@JoinColumn` or `@PrimaryKeyJoinColumn`.
[source,java]
----
@Entity
class Author {
@Id
Long id;
@OneToOne(optional=false, fetch=LAZY)
@MapsId
@PrimaryKeyJoinColumn(name="personId")
Person author;
...
}
----
Arguably, the use of `@PrimaryKeyJoinColumn` is clearer.
====
[[primary-key-column-mappings]]
=== Mapping primary key joins between tables
The `@PrimaryKeyJoinColumn` is a special-purpose annotation for mapping:
- the primary key column of a `@SecondaryTable`—which is also a foreign key referencing the primary table, or
- the primary key column of the primary table mapped by a subclass in a `JOINED` inheritance hierarchy—which is also a foreign key referencing the primary table mapped by the root entity.
.`@PrimaryKeyJoinColumn` annotation members
[%breakable,cols="20,~"]
|===
| Annotation member | Purpose
| `name` | The name of the mapped foreign key column
| `referencedColumnName` | The name of the column to which the mapped foreign key column refers
| `columnDefinition` 💀| A DDL fragment that should be used to declare the column
| `foreignKey` | A `@ForeignKey` annotation specifying the name of the `FOREIGN KEY` constraint
|===
When mapping a subclass table primary key, we place the `@PrimaryKeyJoinColumn` annotation on the entity class:
[source,java]
----
@Entity
@Table(name="People")
@Inheritance(strategy=JOINED)
class Person { ... }
@Entity
@Table(name="Authors")
@PrimaryKeyJoinColumn(name="personId") // the primary key of the Authors table
class Author { ... }
----
But to map a secondary table primary key, the `@PrimaryKeyJoinColumn` annotation must occur inside the `@SecondaryTable` annotation:
[source,java]
----
@Entity
@Table(name="Books")
@SecondaryTable(name="Editions",
pkJoinColumns = @PrimaryKeyJoinColumn(name="bookId")) // the primary key of the Editions table
class Book {
@Id @GeneratedValue
@Column(name="bookId") // the name of the primary key of the Books table
Long id;
...
}
----
[[column-lengths]]
=== Column lengths and adaptive column types
Hibernate automatically adjusts the column type used in generated DDL based on the column length specified by the `@Column` annotation.
So we don't usually need to explicitly specify that a column should be of type `TEXT` or `CLOB`—or worry about the parade of `TINYTEXT`, `MEDIUMTEXT`, `TEXT`, `LONGTEXT` types on MySQL—because Hibernate automatically selects one of those types if required to accommodate a string of the `length` we specify.
The constant values defined in the class link:{doc-javadoc-url}org/hibernate/Length.html[`Length`] are very helpful here:
.Predefined column lengths
[%breakable,cols="10,12,~"]
|===
| Constant | Value | Description
| `DEFAULT` | 255 | The default length of a `VARCHAR` or `VARBINARY` column when none is explicitly specified
| `LONG` | 32600 | The largest column length for a `VARCHAR` or `VARBINARY` that is allowed on every database Hibernate supports
| `LONG16` | 32767 | The maximum length that can be represented using 16 bits (but this length is too large for a `VARCHAR` or `VARBINARY` column on for some database)
| `LONG32` | 2147483647 | The maximum length for a Java string
|===
We can use these constants in the `@Column` annotation:
[source,java]
----
@Column(length=LONG)
String text;
@Column(length=LONG32)
byte[] binaryData;
----
This is usually all you need to do to make use of large object types in Hibernate.
[[lobs]]
=== LOBs
JPA provides a `@Lob` annotation which specifies that a field should be persisted as a `BLOB` or `CLOB`.
[[lob-semantics]]
.*Read more: Semantics of the @Lob annotation*
[%collapsible]
====
****
What the spec actually says is that the field should be persisted
> ...as a large object to a database-supported large object type.
It's quite unclear what this means, and the spec goes on to say that
> ...the treatment of the `Lob` annotation is provider-dependent...
which doesn't help much.
****
====
Hibernate interprets this annotation in what we think is the most reasonable way.
In Hibernate, an attribute annotated `@Lob` is written to JDBC using the `setClob()` or `setBlob()` method of `PreparedStatement`, and is read from JDBC using the `getClob()` or `getBlob()` method of `ResultSet`.
Now, the use of these JDBC methods is usually unnecessary!
JDBC drivers are perfectly capable of converting between `String` and `CLOB` or between `byte[]` and `BLOB`.
So unless you specifically need to use these JDBC LOB APIs, you _don't_ need the `@Lob` annotation.
Instead, as we just saw in <>, all you need is to specify a large enough column `length` to accommodate the data you plan to write to that column.
You should usually write this:
[source,java]
----
@Column(length=LONG32) // good, correct column type inferred
String text;
----
instead of this:
[source,java]
----
@Lob // almost always unnecessary
String text;
----
This is particularly true for PostgreSQL.
[%unbreakable]
.*Read more: PostgreSQL and @Lob*
[%collapsible]
// .PostgreSQL `BYTEA` and `TEXT`
====
****
Unfortunately, the driver for PostgreSQL doesn't allow `BYTEA` or `TEXT` columns to be read via the JDBC LOB APIs.
This limitation of the Postgres driver has resulted in a whole cottage industry of bloggers and stackoverflow question-answerers recommending convoluted ways to hack the Hibernate `Dialect` for Postgres to allow an attribute annotated `@Lob` to be written using `setString()` and read using `getString()`.
But simply removing the `@Lob` annotation has exactly the same effect.
Conclusion:
- on PostgreSQL, `@Lob` always means the `OID` type,
- `@Lob` should never be used to map columns of type `BYTEA` or `TEXT`, and
- please don't believe everything you read on stackoverflow.
****
====
Finally, as an alternative, Hibernate lets you declare an attribute of type `java.sql.Blob` or `java.sql.Clob`.
[source,java]
----
@Entity
class Book {
...
Clob text;
Blob coverArt;
....
}
----
The advantage is that a `java.sql.Clob` or `java.sql.Blob` can in principle index up to 2^63^ characters or bytes, much more data than you can fit in a Java `String` or `byte[]` array (or in your computer).
To assign a value to these fields, we'll need to use a link:{doc-javadoc-url}org/hibernate/LobHelper.html[`LobHelper`].
We can get one from the `Session`:
[source,java]
----
LobHelper helper = session.getLobHelper();
book.text = helper.createClob(text);
book.coverArt = helper.createBlob(image);
----
In principle, the `Blob` and `Clob` objects provide efficient ways to read or stream LOB data from the server.
[source,java]
----
Book book = session.find(Book.class, bookId);
String text = book.text.getSubString(1, textLength);
InputStream bytes = book.coverArt.getBinaryStream();
----
Of course, the behavior here depends very much on the JDBC driver, and so we really can't promise that this is a sensible thing to do on your database.
[[mapping-embeddables]]
=== Mapping embeddable types to UDTs or to JSON
There's a couple of alternative ways to represent an embeddable type on the database side.
[[embeddable-udt]]
[discrete]
==== Embeddables as UDTs
First, a really nice option, at least in the case of Java record types, and for databases which support _user-defined types_ (UDTs), is to define a UDT which represents the record type.
This is easy: just annotate the record type, or the attribute which holds a reference to it, with the new `@Struct` annotation:
[source,java]
----
@Embeddable
@Struct(name="PersonName")
record Name(String firstName, String middleName, String lastName) {}
----
[source,java]
----
@Entity
class Person {
...
Name name;
...
}
----
This results in the following UDT:
[source,sql]
----
create type PersonName as (firstName varchar(255), middleName varchar(255), lastName varchar(255))
----
And the `name` column of the `Author` table will have the type `PersonName`.
[discrete]
==== Embeddables to JSON
A second option that's available is to map the embeddable type to a `JSON` (or `JSONB`) column.
Now, this isn't something we would exactly _recommend_ if you're defining a data model from scratch, but it's at least useful for mapping pre-existing tables with JSON-typed columns.
Since embeddable types are nestable, we can map some JSON formats this way, and even query JSON properties using HQL.
To map an attribute of embeddable type to JSON, we must annotate the attribute `@JdbcTypeCode(SqlTypes.JSON)`, instead of annotating the embeddable type.
But the embeddable type `Name` should still be annotated `@Embeddable` if we want to query its attributes using HQL.
[source,java]
----
@Embeddable
record Name(String firstName, String middleName, String lastName) {}
----
[source,java]
----
@Entity
class Person {
...
@JdbcTypeCode(SqlTypes.JSON)
Name name;
...
}
----
We also need to add Jackson or an implementation of JSONB--for example, Yasson--to our runtime classpath.
To use Jackson we could add this line to our Gradle build:
[source,groovy,subs="attributes+"]
----
runtimeOnly 'tools.jackson.core:jackson-databind:{jackson3Version}'
----
Now the `name` column of the `Author` table will have the type `jsonb`, and Hibernate will automatically use Jackson to serialize a `Name` to and from JSON format.
[[miscellaneous-mappings]]
=== Summary of SQL column type mappings
So, as we've seen, there are quite a few annotations that affect the mapping of Java types to SQL column types in DDL.
Here we summarize the ones we've just seen in the second half of this chapter, along with some we already mentioned in earlier chapters.
.Annotations for mapping SQL column types
[%autowidth.stretch]
|===
| Annotation | Interpretation
| `@Enumerated`, `@EnumeratedValue` | Specify how an <>
| `@Nationalized` | Use a <>: `NCHAR`, `NVARCHAR`, or `NCLOB`
| `@Lob` 💀 | Use <> to read and write the annotated attribute
| `@Array` | Map a collection to a <> of the specified length
| `@Struct` | Map an <> with the given name
| `@TimeZoneStorage` | Specify how the link:{doc-javadoc-url}org/hibernate/annotations/TimeZoneStorageType.html[time zone information should be persisted]
| `@JdbcType` or `@JdbcTypeCode` | Use an implementation of <> to map an arbitrary SQL type
| `@Collate` | Specify a collation for a column
|===
In addition, there are link:{doc-javadoc-url}org/hibernate/cfg/MappingSettings.html[some configuration properties] which have a _global_ effect on how basic types map to SQL column types:
.Type mapping settings
[%autowidth.stretch]
|===
| Configuration property name | Purpose
| `hibernate.use_nationalized_character_data` | Enable use of <> by default
| `hibernate.type.preferred_boolean_jdbc_type` | Specify the default SQL column type for storing a `boolean`
| `hibernate.type.preferred_uuid_jdbc_type` | Specify the default SQL column type for storing a `UUID`
| `hibernate.type.preferred_duration_jdbc_type` | Specify the default SQL column type for storing a `Duration`
| `hibernate.type.preferred_instant_jdbc_type` | Specify the default SQL column type for storing an `Instant`
| `hibernate.timezone.default_storage` | Specify the default strategy for link:{doc-javadoc-url}org/hibernate/annotations/TimeZoneStorageType.html[storing time zone information]
| `hibernate.type.prefer_native_enum_types` | Use <