somewhat improve the documentation of StatelessSession

mention fetch()
This commit is contained in:
Gavin King 2022-07-04 11:32:25 +02:00
parent 13c5e2a52b
commit 6588d2db46
1 changed files with 26 additions and 14 deletions

View File

@ -116,24 +116,33 @@ However, it is good practice to close the `ScrollableResults` explicitly.
==== StatelessSession ==== StatelessSession
`StatelessSession` is a command-oriented API provided by Hibernate. `StatelessSession` is an alternative to `Session` and provides:
Use it to stream data to and from the database in the form of detached objects.
A `StatelessSession` has no persistence context associated with it and does not provide many of the higher-level lifecycle semantics.
Some of the things not provided by a `StatelessSession` include: - a command-oriented API
- with no associated persistence context.
* a first-level cache Thus, a stateless session is a slightly lower-level abstraction that's closer to the underlying JDBC activity:
* interaction with any second-level or query cache
* transactional write-behind or automatic dirty checking
Limitations of `StatelessSession`: * there's no first-level cache,
* the stateless session does not interact with any second-level or query cache, and
* there's no transactional write-behind or automatic dirty checking.
* Operations performed using a stateless session never cascade to associated instances. Instead, persistence operations occur synchronously when a method of `StatelessSession` is invoked, and entities returned by a stateless session are always detached.
* Collections are ignored by a stateless session.
* Lazy loading of associations is not supported. [TIP]
* Operations performed via a stateless session bypass Hibernate's event model and interceptors. ====
* Due to the lack of a first-level cache, Stateless sessions are vulnerable to data aliasing effects. A stateless session may be used to stream data to and from the database in the form of detached objects.
* A stateless session is a lower-level abstraction that is much closer to the underlying JDBC. With a stateless session, there's no need to explicitly manage the size of the first-level cache by explicitly clearing the persistence context.
====
The `StatelessSession` API comes with certain limitations:
* operations performed using a stateless session never cascade to associated instances,
* collections are ignored by a stateless session,
* lazy loading of associations is not transparent, and is only available via an explicit operation named `fetch()`, and
* operations performed via a stateless session bypass Hibernate's event model and interceptors.
IMPORTANT: Due to the lack of a first-level cache, stateless sessions are vulnerable to data aliasing effects.
[[batch-stateless-session-example]] [[batch-stateless-session-example]]
.Using a `StatelessSession` .Using a `StatelessSession`
@ -147,9 +156,12 @@ include::{sourcedir}/BatchTest.java[tags=batch-stateless-session-example]
The `Customer` instances returned by the query are immediately detached. The `Customer` instances returned by the query are immediately detached.
They are never associated with any persistence context. They are never associated with any persistence context.
[NOTE]
====
The `insert()`, `update()`, and `delete()` operations defined by the `StatelessSession` interface operate directly on database rows. The `insert()`, `update()`, and `delete()` operations defined by the `StatelessSession` interface operate directly on database rows.
They cause the corresponding SQL operations to be executed immediately. They cause the corresponding SQL operations to be executed immediately.
They have different semantics from the `save()`, `saveOrUpdate()`, and `delete()` operations defined by the `Session` interface. They have different semantics from the `save()`, `saveOrUpdate()`, and `delete()` operations defined by the `Session` interface.
====
[[batch-bulk-hql]] [[batch-bulk-hql]]
=== Hibernate Query Language for DML === Hibernate Query Language for DML