Interface SharedSessionBuilder

All Superinterfaces:
CommonBuilder, CommonSharedBuilder, SessionBuilder
All Known Subinterfaces:
SharedSessionBuilderImplementor
All Known Implementing Classes:
AbstractDelegatingSharedSessionBuilder
public interface SharedSessionBuilder extends SessionBuilder, CommonSharedBuilder
Allows creation of a child Session which shares some options with another pre-existing parent session. Each session has its own isolated persistence context, and entity instances must not be shared between parent and child sessions.

A child session does not, by default, share the parent's JDBC connection, transaction coordinator, persistence context, action queue, interceptor, or SQL statement inspector. Instead, the child session starts from the normal SessionFactory defaults, with the following values inherited from the parent session as the baseline:

  • the tenant identifier,
  • the JDBC time zone,
  • the temporal or changeset identifier used for loading temporal data, and
  • whether identifier rollback is enabled.
Other stateful session options are inherited only when explicitly requested by the corresponding no-argument method, for example connection(), interceptor(), statementInspector(), flushMode(), autoJoinTransactions(), autoClose(), or connectionHandlingMode().

When resource-local transaction management is used:

  • by default, each session executes with its own dedicated JDBC connection and therefore has its own isolated transaction, but
  • calling the connection() method specifies that the connection, and therefore also the JDBC transaction, should be shared from parent to child.
A child session with a shared transaction context also receives parent flush and close notifications, so the child's work is flushed with the parent, and the child is automatically closed when the parent is closed. 
try (var childSession
         = session.sessionWithOptions()
                 .connection() // share the JDBC connection
                 .cacheMode(CacheMode.IGNORE)
                 .openSession()) {
    ...
}
On the other hand, when JTA transaction management is used, all sessions execute within the same transaction. Typically, connection sharing is handled automatically by the JTA-enabled DataSource.
See Also: