Package org.hibernate

Interface SessionBuilder

All Superinterfaces:

CommonBuilder

All Known Subinterfaces:

SessionBuilderImplementor, SharedSessionBuilder, SharedSessionBuilderImplementor

All Known Implementing Classes:

AbstractDelegatingSessionBuilder, AbstractDelegatingSessionBuilderImplementor, AbstractDelegatingSharedSessionBuilder

public interface SessionBuilder
extends CommonBuilder

Allows creation of a new Session with specific options overriding the defaults from the SessionFactory.

 try (var session =
         sessionFactory.withOptions()
             .tenantIdentifier(tenantId)
             .initialCacheMode(CacheMode.PUT)
             .flushMode(FlushMode.COMMIT)
             .interceptor(new Interceptor() {
                 @Override
                 public void preFlush(Iterator<Object> entities) {
                     ...
                 }
             })
             .openSession()) {
     ...
 }
 

See Also:

• SessionFactory.withOptions()
• SharedSessionBuilder

Method Summary

Modifier and Type	Method	Description
SessionBuilder	autoClear(boolean autoClear)	Should the session be automatically cleared on a failed transaction?
SessionBuilder	autoClose(boolean autoClose)	Should the session be automatically closed after transaction completion?
SessionBuilder	autoJoinTransactions(boolean autoJoinTransactions)	Should the session built automatically join in any ongoing JTA transactions.
SessionBuilder	clearEventListeners()	Remove all listeners intended for the built session currently held here, including any auto-apply ones; in other words, start with a clean slate.
SessionBuilder	connection(Connection connection)	Adds a specific connection to the session options.
SessionBuilder	connectionHandling(ConnectionAcquisitionMode acquisitionMode, ConnectionReleaseMode releaseMode)	Specifies the connection handling modes for the session.
SessionBuilder	connectionHandlingMode(PhysicalConnectionHandlingMode mode)	Deprecated. This operation exposes the SPI type PhysicalConnectionHandlingMode and is therefore a layer-breaker.
SessionBuilder	defaultBatchFetchSize(int defaultBatchFetchSize)	Specify the default batch fetch size for the session.
SessionBuilder	eventListeners(SessionEventListener... listeners)	Add one or more SessionEventListener instances to the list of listeners for the new session to be built.
SessionBuilder	flushMode(FlushMode flushMode)	Specify the initial FlushMode to use for the opened Session
SessionBuilder	identifierRollback(boolean identifierRollback)	Enable identifier rollback after entity removal for the session.
SessionBuilder	initialCacheMode(CacheMode cacheMode)	Specify the initial CacheMode for the session.
SessionBuilder	interceptor(Interceptor interceptor)	Adds a specific interceptor to the session options.
SessionBuilder	jdbcTimeZone(TimeZone timeZone)	Specify the JDBC time zone for the session.
SessionBuilder	noInterceptor()	Specifies that no Interceptor should be used.
SessionBuilder	noSessionInterceptorCreation()	Specifies that no session-scoped interceptor should be instantiated for the new session.
SessionBuilder	noStatementInspector()	Signifies that no SQL statement inspector should be used.
Session	openSession()	Opens a session with the specified options.
SessionBuilder	readOnly(boolean readOnly)	Specify a read-only mode for the session.
SessionBuilder	statementInspector(UnaryOperator<String> operator)	Applies the given statement inspection function to the session.
SessionBuilder	statementInspector(StatementInspector statementInspector)	Deprecated. This operation exposes the SPI type StatementInspector and is therefore a layer-breaker.
SessionBuilder	subselectFetchEnabled(boolean subselectFetchEnabled)	Specify whether subselect fetching is enabled for the session.
SessionBuilder	tenantIdentifier(Object tenantIdentifier)	Define the tenant identifier to be associated with the opened session.
SessionBuilder	tenantIdentifier(String tenantIdentifier)	Deprecated, for removal: This API element is subject to removal in a future version. Use tenantIdentifier(Object) instead

Method Details

openSession

Session openSession()

Opens a session with the specified options.

Returns:

The session

interceptor

SessionBuilder 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

SessionBuilder 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

SessionBuilder 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

noStatementInspector

SessionBuilder noStatementInspector()

Description copied from interface: CommonBuilder

Signifies that no SQL statement inspector should be used.

By default, if no inspector is explicitly specified, the inspector associated with the SessionFactory is inherited by the new session.

Calling CommonBuilder.interceptor(Interceptor) with null has the same effect.

Specified by:

noStatementInspector in interface CommonBuilder

Returns:

this, for method chaining

statementInspector

SessionBuilder 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

statementInspector

@Deprecated(since="7.0")
SessionBuilder statementInspector(StatementInspector statementInspector)

Deprecated.

This operation exposes the SPI type StatementInspector and is therefore a layer-breaker. Use statementInspector(UnaryOperator) instead.

Applies the given StatementInspector to the session.

Parameters:

statementInspector - The StatementInspector to use.

Returns:

this, for method chaining

connection

SessionBuilder connection(Connection connection)

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

SessionBuilder connectionHandling(ConnectionAcquisitionMode acquisitionMode,
 ConnectionReleaseMode releaseMode)

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

Since:

7.0

connectionHandlingMode

@Deprecated(since="7.0")
SessionBuilder connectionHandlingMode(PhysicalConnectionHandlingMode mode)

Deprecated.

This operation exposes the SPI type PhysicalConnectionHandlingMode and is therefore a layer-breaker. Use connectionHandling(ConnectionAcquisitionMode, ConnectionReleaseMode) instead.

Specifies the connection handling mode.

Parameters:

mode - The connection handling mode to use.

Returns:

this, for method chaining

autoJoinTransactions

SessionBuilder autoJoinTransactions(boolean autoJoinTransactions)

Should the session built automatically join in any ongoing JTA transactions.

Parameters:

autoJoinTransactions - Should JTA transactions be automatically joined

Returns:

this, for method chaining

See Also:

• SynchronizationType.SYNCHRONIZED

autoClear

SessionBuilder autoClear(boolean autoClear)

Should the session be automatically cleared on a failed transaction?

Parameters:

autoClear - Whether the Session should be automatically cleared

Returns:

this, for method chaining

flushMode

SessionBuilder flushMode(FlushMode flushMode)

Specify the initial FlushMode to use for the opened Session

Parameters:

flushMode - The initial FlushMode to use for the opened Session

Returns:

this, for method chaining

See Also:

• PersistenceContextType

tenantIdentifier

@Deprecated(since="6.4",
            forRemoval=true)
SessionBuilder tenantIdentifier(String tenantIdentifier)

Deprecated, for removal: This API element is subject to removal in a future version.

Use tenantIdentifier(Object) instead

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

Parameters:

tenantIdentifier - The tenant identifier.

Returns:

this, for method chaining

tenantIdentifier

SessionBuilder tenantIdentifier(Object tenantIdentifier)

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

Specified by:

tenantIdentifier in interface CommonBuilder

Parameters:

tenantIdentifier - The tenant identifier.

Returns:

this, for method chaining

Since:

6.4

readOnly

SessionBuilder 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

SessionBuilder 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()

eventListeners

SessionBuilder eventListeners(SessionEventListener... listeners)

Add one or more SessionEventListener instances to the list of listeners for the new session to be built.

Parameters:

listeners - The listeners to incorporate into the built Session

Returns:

this, for method chaining

clearEventListeners

SessionBuilder clearEventListeners()

Remove all listeners intended for the built session currently held here, including any auto-apply ones; in other words, start with a clean slate.

Returns:

this, for method chaining

jdbcTimeZone

SessionBuilder jdbcTimeZone(TimeZone timeZone)

Specify the JDBC time zone for the session.

Specified by:

jdbcTimeZone in interface CommonBuilder

Returns:

this, for method chaining

autoClose

SessionBuilder autoClose(boolean autoClose)

Should the session be automatically closed after transaction completion?

Parameters:

autoClose - Should the session be automatically closed

Returns:

this, for method chaining

See Also:

• PersistenceContextType

identifierRollback

SessionBuilder identifierRollback(boolean identifierRollback)

Enable identifier rollback after entity removal for the session.

Returns:

this, for method chaining

Since:

7.0

See Also:

• AvailableSettings.USE_IDENTIFIER_ROLLBACK

defaultBatchFetchSize

SessionBuilder defaultBatchFetchSize(int defaultBatchFetchSize)

Specify the default batch fetch size for the session.

Returns:

this, for method chaining

Since:

7.2

See Also:

• FetchSettings.DEFAULT_BATCH_FETCH_SIZE
• Session.setFetchBatchSize(int)

subselectFetchEnabled

SessionBuilder subselectFetchEnabled(boolean subselectFetchEnabled)

Specify whether subselect fetching is enabled for the session.

Returns:

this, for method chaining

Since:

7.2

See Also:

• FetchSettings.USE_SUBSELECT_FETCH
• Session.setSubselectFetchingEnabled(boolean)