Interface CommonBuilder

All Known Subinterfaces:

CommonSharedBuilder, SessionBuilder, SessionBuilderImplementor, SharedSessionBuilder, SharedSessionBuilderImplementor, SharedStatelessSessionBuilder, StatelessSessionBuilder

All Known Implementing Classes:

AbstractDelegatingSessionBuilder, AbstractDelegatingSessionBuilderImplementor, AbstractDelegatingSharedSessionBuilder

@Incubating
public interface CommonBuilder

Common options for builders of stateful and stateless sessions.

Since:

7.2

Method Summary

Modifier and Type	Method	Description
CommonBuilder	asOf(Instant instant)	Specify the instant for reading temporal entity data.
CommonBuilder	atChangeset(Object changesetId)	Specify the changeset id for reading temporal of audited entity data.
CommonBuilder	cacheRetrieveMode(CacheRetrieveMode cacheRetrieveMode)	Specify the CacheRetrieveMode for the session.
CommonBuilder	cacheStoreMode(CacheStoreMode cacheStoreMode)	Specify the CacheStoreMode for the session.
CommonBuilder	connection(Connection connection)	Adds a specific connection to be used to the session options.
CommonBuilder	connectionHandling(ConnectionAcquisitionMode acquisitionMode, ConnectionReleaseMode releaseMode)	Specifies the connection handling modes for the session.
CommonBuilder	initialCacheMode(CacheMode cacheMode)	Specify the initial CacheMode for the session.
CommonBuilder	interceptor(Interceptor interceptor)	Adds a specific interceptor to the session options.
CommonBuilder	jdbcBatchSize(int batchSize)	Specifies a session-specific size for JDBC batching, overriding any SessionFactory-level size.
CommonBuilder	jdbcTimeZone(TimeZone timeZone)	Specify the JDBC time zone to use for the session.
CommonBuilder	noInterceptor()	Specifies that no Interceptor should be used.
CommonBuilder	noSessionInterceptorCreation()	Specifies that no session-scoped interceptor should be used for the session.
CommonBuilder	noStatementInspector()	Signifies that no SQL statement inspector should be used.
SharedSessionContract	open()	Open the session using the specified options.
CommonBuilder	readOnly(boolean readOnly)	Specify a read-only mode for the session.
CommonBuilder	statementInspector(UnaryOperator<String> operator)	Applies the given statement inspection function to the session.
CommonBuilder	tenantIdentifier(Object tenantIdentifier)	Specify the tenant identifier to be associated with the opened session.

Method Details

open

@Nonnull
SharedSessionContract open()

Open the session using the specified options.

connection

@Nonnull
CommonBuilder connection(@Nonnull
 Connection connection)

Adds a specific connection to be used to the session options.

Parameters:

connection - The connection to use.

Returns:

this, for method chaining

connectionHandling

@Nonnull
CommonBuilder connectionHandling(@Nonnull
 ConnectionAcquisitionMode acquisitionMode,
 @Nonnull
 ConnectionReleaseMode releaseMode)

Specifies the connection handling modes for the session.

Returns:

this, for method chaining

Since:

7.0

API Note:

If ConnectionAcquisitionMode.IMMEDIATELY is specified, then the release mode must be ConnectionReleaseMode.ON_CLOSE.

interceptor

@Nonnull
CommonBuilder interceptor(@Nullable
 Interceptor interceptor)

Adds a specific interceptor to the session options.

Parameters:

interceptor - The interceptor to use.

Returns:

this, for method chaining

noInterceptor

@Nonnull
CommonBuilder noInterceptor()

Specifies that no Interceptor should be used. This indicates to ignore both (if either) the interceptor and session-scoped interceptor associated with the SessionFactory

Returns:

this, for method chaining

API Note:

Calling interceptor(Interceptor) with null has the same effect

noSessionInterceptorCreation

@Nonnull
CommonBuilder noSessionInterceptorCreation()

Specifies that no session-scoped interceptor should be used for the session. If the SessionFactory has a configured interceptor, it will still be used.

Returns:

this, for method chaining

Since:

7.2

See Also:

• noInterceptor()

API Note:

Unlike noInterceptor(), this operation does not disable use of an interceptor associated with the SessionFactory.

statementInspector

@Nonnull
CommonBuilder statementInspector(@Nullable
 UnaryOperator<String> operator)

Applies the given statement inspection function to the session.

Parameters:

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

Returns:

this, for method chaining

noStatementInspector

@Nonnull
CommonBuilder noStatementInspector()

Signifies that no SQL statement inspector should be used.

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

Returns:

this, for method chaining

API Note:

Calling statementInspector(UnaryOperator) with null has the same effect.

tenantIdentifier

@Nonnull
CommonBuilder tenantIdentifier(Object tenantIdentifier)

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

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

Parameters:

tenantIdentifier - The tenant identifier.

Returns:

this, for method chaining

readOnly

@Incubating
@Nonnull
CommonBuilder readOnly(boolean readOnly)

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.

Returns:

this, for method chaining

Since:

7.2

See Also:

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

jdbcBatchSize

@Nonnull
CommonBuilder jdbcBatchSize(int batchSize)

Specifies a session-specific size for JDBC batching, overriding any SessionFactory-level size.

Returns:

this, for method chaining

Since:

8.0

See Also:

• BatchSettings.STATEMENT_BATCH_SIZE

initialCacheMode

@Nonnull
CommonBuilder initialCacheMode(@Nonnull
 CacheMode cacheMode)

Specify the initial CacheMode for the session.

Returns:

this, for method chaining

Since:

7.2

See Also:

• SharedSessionContract.getCacheMode()

cacheStoreMode

@Nonnull
CommonBuilder cacheStoreMode(@Nullable
 CacheStoreMode cacheStoreMode)

Specify the CacheStoreMode for the session.

Returns:

this, for method chaining

Since:

8.0

cacheRetrieveMode

@Nonnull
CommonBuilder cacheRetrieveMode(@Nullable
 CacheRetrieveMode cacheRetrieveMode)

Specify the CacheRetrieveMode for the session.

Returns:

this, for method chaining

Since:

8.0

jdbcTimeZone

@Nonnull
CommonBuilder jdbcTimeZone(@Nullable
 TimeZone timeZone)

Specify the JDBC time zone to use for the session.

Returns:

this, for method chaining

asOf

@Incubating
@Nonnull
CommonBuilder asOf(@Nullable
 Instant instant)

Specify the instant for reading temporal entity data. Instances of temporal entities retrieved in the session will represent the revisions effective at the given instant.

See Also:

• Temporal

atChangeset

@Incubating
@Nonnull
CommonBuilder atChangeset(@Nullable
 Object changesetId)

Specify the changeset id for reading temporal of audited entity data. Instances of temporal or audited entities retrieved in the session will represent the revisions effective at the end of the given changeset. The given value should match the type returned by the configured changeset id supplier.

See Also:

• Temporal