Package org.hibernate.engine.creation

Interface CommonSharedBuilder

All Superinterfaces:

CommonBuilder

All Known Subinterfaces:

SharedSessionBuilder, SharedSessionBuilderImplementor, SharedStatelessSessionBuilder

All Known Implementing Classes:

AbstractDelegatingSharedSessionBuilder

@Incubating
public interface CommonSharedBuilder
extends CommonBuilder

Common options for builders of stateful and stateless sessions which share state from an underlying session.

Since:

7.2

Method Summary

Modifier and Type	Method	Description
CommonSharedBuilder	connection()	Signifies that the connection from the original session should be used to create the new session.
CommonBuilder	connection(Connection connection)	Adds a specific connection to the session options.
CommonSharedBuilder	connectionHandling(ConnectionAcquisitionMode acquisitionMode, ConnectionReleaseMode releaseMode)	Specifies the connection handling modes for the session.
CommonSharedBuilder	initialCacheMode(CacheMode cacheMode)	Specify the initial CacheMode for the session.
CommonSharedBuilder	interceptor()	Signifies the interceptor from the original session should be used to create the new session.
CommonSharedBuilder	interceptor(Interceptor interceptor)	Adds a specific interceptor to the session options.
CommonSharedBuilder	jdbcTimeZone(TimeZone timeZone)	Specify the JDBC time zone for the session.
CommonSharedBuilder	noInterceptor()	Specifies that no Interceptor should be used.
CommonSharedBuilder	noSessionInterceptorCreation()	Specifies that no session-scoped interceptor should be instantiated for the new session.
CommonSharedBuilder	noStatementInspector()	Signifies that no SQL statement inspector should be used.
CommonSharedBuilder	readOnly(boolean readOnly)	Specify a read-only mode for the session.
CommonSharedBuilder	statementInspector()	Signifies that the SQL statement inspector from the original session should be used.
CommonSharedBuilder	statementInspector(UnaryOperator<String> operator)	Applies the given statement inspection function to the session.
CommonSharedBuilder	tenantIdentifier(Object tenantIdentifier)	Specify the tenant identifier to be associated with the opened session.

Method Details

connection

CommonSharedBuilder connection()

Signifies that the connection from the original session should be used to create the new session. Implies that the overall "transaction context" should be shared as well.

Returns:

this, for method chaining

interceptor

CommonSharedBuilder interceptor()

Signifies the interceptor from the original session should be used to create the new session.

Returns:

this, for method chaining

statementInspector

CommonSharedBuilder statementInspector()

Signifies that the SQL statement inspector from the original session should be used.

noStatementInspector

CommonSharedBuilder noStatementInspector()

Signifies that no SQL statement inspector should be used.

Specified by:

noStatementInspector in interface CommonBuilder

Returns:

this, for method chaining

interceptor

CommonSharedBuilder interceptor(Interceptor interceptor)

Description copied from interface: CommonBuilder

Adds a specific interceptor to the session options.

Specified by:

interceptor in interface CommonBuilder

Parameters:

interceptor - The interceptor to use.

Returns:

this, for method chaining

noInterceptor

CommonSharedBuilder noInterceptor()

Description copied from interface: CommonBuilder

Specifies that no Interceptor should be used.

By default, if no Interceptor is explicitly specified, the Interceptor associated with the SessionFactory is inherited by the new session. Or, if there is no interceptor associated with the SessionFactory, but a session-scoped interceptor has been configured, a new session-scoped Interceptor will be created for the new session.

Calling interceptor(null) has the same effect.

Specified by:

noInterceptor in interface CommonBuilder

Returns:

this, for method chaining

noSessionInterceptorCreation

CommonSharedBuilder noSessionInterceptorCreation()

Description copied from interface: CommonBuilder

Specifies that no session-scoped interceptor should be instantiated for the new session.

By default, if no Interceptor is explicitly specified, and if there is no interceptor associated with the SessionFactory, but a session-scoped interceptor has been configured, a new session-scoped Interceptor will be created for the new session.

Note that this operation does not disable use of an interceptor associated with the SessionFactory.

Specified by:

noSessionInterceptorCreation in interface CommonBuilder

Returns:

this, for method chaining

See Also:

• SessionEventSettings.SESSION_SCOPED_INTERCEPTOR

statementInspector

CommonSharedBuilder statementInspector(UnaryOperator<String> operator)

Description copied from interface: CommonBuilder

Applies the given statement inspection function to the session.

Specified by:

statementInspector in interface CommonBuilder

Parameters:

operator - An operator which accepts a SQL string, returning a processed SQL string to be used by Hibernate instead of the given original SQL. The operator may simply return the original SQL.

Returns:

this, for method chaining

readOnly

CommonSharedBuilder readOnly(boolean readOnly)

Description copied from interface: CommonBuilder

Specify a read-only mode for the session. If a session is created in read-only mode, then Connection.setReadOnly(boolean) is called when a JDBC connection is obtained.

Furthermore, if read/write replication is in use, then:

• a read-only session will connect to a read-only replica, but
• a non-read-only session will connect to a writable replica.

When read/write replication is in use, it's strongly recommended that the session be created with the initial cache mode set to CacheMode.GET, to avoid writing stale data read from a read-only replica to the second-level cache. Hibernate cannot possibly guarantee that data read from a read-only replica is up to date.

When read/write replication is in use, it's possible that an item read from the second-level cache might refer to data which does not yet exist in the read-only replica. In this situation, an exception occurs when the association is fetched. To completely avoid this possibility, the initial cache mode must be set to CacheMode.IGNORE. However, it's also usually possible to structure data access code in a way which eliminates this possibility.

 try (var readOnlySession =
         sessionFactory.withOptions()
                 .readOnly(true)
                 .initialCacheMode(CacheMode.IGNORE)
                 .openSession()) {
     ...
 }
 

If a session is created in read-only mode, then it cannot be changed to read-write mode, and any call to Session.setDefaultReadOnly(boolean) with fail. On the other hand, if a session is created in read-write mode, then it may later be switched to read-only mode, but all database access is directed to the writable replica.

Specified by:

readOnly in interface CommonBuilder

Returns:

this, for method chaining

See Also:

• MultiTenantConnectionProvider.getReadOnlyConnection(Object)
• MultiTenantConnectionProvider.releaseReadOnlyConnection(Object, Connection)

initialCacheMode

CommonSharedBuilder initialCacheMode(CacheMode cacheMode)

Description copied from interface: CommonBuilder

Specify the initial CacheMode for the session.

Specified by:

initialCacheMode in interface CommonBuilder

Returns:

this, for method chaining

See Also:

• SharedSessionContract.getCacheMode()

tenantIdentifier

CommonSharedBuilder tenantIdentifier(Object tenantIdentifier)

Description copied from interface: CommonBuilder

Specify the tenant identifier to be associated with the opened session.

 try (var session =
         sessionFactory.withOptions()
             .tenantIdentifier(tenantId)
             .openSession()) {
     ...
 }
 

Specified by:

tenantIdentifier in interface CommonBuilder

Parameters:

tenantIdentifier - The tenant identifier.

Returns:

this, for method chaining

connection

CommonBuilder connection(Connection connection)

Description copied from interface: CommonBuilder

Adds a specific connection to the session options.

Specified by:

connection in interface CommonBuilder

Parameters:

connection - The connection to use.

Returns:

this, for method chaining

connectionHandling

CommonSharedBuilder connectionHandling(ConnectionAcquisitionMode acquisitionMode,
 ConnectionReleaseMode releaseMode)

Description copied from interface: CommonBuilder

Specifies the connection handling modes for the session.

Note that if ConnectionAcquisitionMode.IMMEDIATELY is specified, then the release mode must be ConnectionReleaseMode.ON_CLOSE.

Specified by:

connectionHandling in interface CommonBuilder

Returns:

this, for method chaining

jdbcTimeZone

CommonSharedBuilder jdbcTimeZone(TimeZone timeZone)

Description copied from interface: CommonBuilder

Specify the JDBC time zone for the session.

Specified by:

jdbcTimeZone in interface CommonBuilder

Returns:

this, for method chaining