Class SessionPoolOptions.Builder (6.68.0) 

public static class SessionPoolOptions.Builder

Builder for creating SessionPoolOptions.

Inheritance

java.lang.Object > SessionPoolOptions.Builder

Constructors

Builder()

public Builder()

Methods

build()

public SessionPoolOptions build()

Build a SessionPoolOption object

Returns
Type Description
SessionPoolOptions

setAcquireSessionTimeout(Duration acquireSessionTimeout)

public SessionPoolOptions.Builder setAcquireSessionTimeout(Duration acquireSessionTimeout)

If greater than zero, we wait for said duration when no sessions are available in the SessionPool. The default is a 60s timeout. Set the value to null to disable the timeout.

Parameter
Name Description
acquireSessionTimeout org.threeten.bp.Duration
Returns
Type Description
SessionPoolOptions.Builder

setAutoDetectDialect(boolean autoDetectDialect)

public SessionPoolOptions.Builder setAutoDetectDialect(boolean autoDetectDialect)

Sets whether the client should automatically execute a background query to detect the dialect that is used by the database or not. Set this option to true if you do not know what the dialect of the database will be.

Note that you can always call DatabaseClient#getDialect() to get the dialect of a database regardless of this setting, but by setting this to true, the value will be pre-populated and cached in the client.

Parameter
Name Description
autoDetectDialect boolean

Whether the client should automatically execute a background query to detect the dialect of the underlying database
Returns
Type Description
SessionPoolOptions.Builder

this builder for chaining

setBlockIfPoolExhausted()

public SessionPoolOptions.Builder setBlockIfPoolExhausted()

If all sessions are in use and there is no more room for creating new sessions, block for a session to become available. Default behavior is same.

By default the requests are blocked for 60s and will fail with a SpannerException with error code ResourceExhausted if this timeout is exceeded. If you wish to block for a different period use the option Builder#setAcquireSessionTimeout(Duration) ()}

Returns
Type Description
SessionPoolOptions.Builder

setFailIfPoolExhausted()

public SessionPoolOptions.Builder setFailIfPoolExhausted()

If all sessions are in use and and maxSessions has been reached, fail the request by throwing a SpannerException with the error code RESOURCE_EXHAUSTED. Default behavior is to block the request.

Returns
Type Description
SessionPoolOptions.Builder

setKeepAliveIntervalMinutes(int intervalMinutes)

public SessionPoolOptions.Builder setKeepAliveIntervalMinutes(int intervalMinutes)

How frequently to keep alive idle sessions. This should be less than 60 since an idle session is automatically closed after 60 minutes. Sessions will be kept alive by sending a dummy query "Select 1". Default value is 30 minutes.

Parameter
Name Description
intervalMinutes int
Returns
Type Description
SessionPoolOptions.Builder

setMaxIdleSessions(int maxIdleSessions) (deprecated)

public SessionPoolOptions.Builder setMaxIdleSessions(int maxIdleSessions)

Deprecated. set a higher value for #setMinSessions(int) instead of using this configuration option. This option will be removed in a future release.

Maximum number of idle sessions that this pool will maintain. Pool will close any sessions beyond this but making sure to always have at least as many sessions as specified by #setMinSessions. To determine how many sessions are idle we look at maximum number of sessions used concurrently over a window of time. Any sessions beyond that are idle. Defaults to 0.

Parameter
Name Description
maxIdleSessions int
Returns
Type Description
SessionPoolOptions.Builder

setMaxSessions(int maxSessions)

public SessionPoolOptions.Builder setMaxSessions(int maxSessions)

Maximum number of sessions that this pool will have. If current numbers of sessions in the pool is less than this and they are all busy, then a new session will be created for any new operation. If current number of in use sessions is same as this and a new request comes, pool can either block or fail. Defaults to 400.

Parameter
Name Description
maxSessions int
Returns
Type Description
SessionPoolOptions.Builder

setMinSessions(int minSessions)

public SessionPoolOptions.Builder setMinSessions(int minSessions)

Minimum number of sessions that this pool will always maintain. These will be created eagerly in parallel. Defaults to 100.

Parameter
Name Description
minSessions int
Returns
Type Description
SessionPoolOptions.Builder

setRemoveInactiveSessionAfter(Duration duration)

public SessionPoolOptions.Builder setRemoveInactiveSessionAfter(Duration duration)
Parameter
Name Description
duration org.threeten.bp.Duration
Returns
Type Description
SessionPoolOptions.Builder

setTrackStackTraceOfSessionCheckout(boolean trackStackTraceOfSessionCheckout)

public SessionPoolOptions.Builder setTrackStackTraceOfSessionCheckout(boolean trackStackTraceOfSessionCheckout)

Sets whether the session pool should capture the call stack trace when a session is checked out of the pool. This will internally prepare a com.google.cloud.spanner.SessionPool.LeakedSessionException that will only be thrown if the session is actually leaked. This makes it easier to debug session leaks, as the stack trace of the thread that checked out the session will be available in the exception.

Some monitoring tools might log these exceptions even though they are not thrown. This option can be used to suppress the creation and logging of these exceptions.

Parameter
Name Description
trackStackTraceOfSessionCheckout boolean
Returns
Type Description
SessionPoolOptions.Builder

setUseMultiplexedSession(boolean useMultiplexedSession)

public SessionPoolOptions.Builder setUseMultiplexedSession(boolean useMultiplexedSession)

Sets whether the client should use multiplexed session or not. If set to true, the client optimises and runs multiple applicable requests concurrently on a single session. A single multiplexed session is sufficient to handle all concurrent traffic.

When set to false, the client uses the regular session cached in the session pool for running 1 concurrent transaction per session. We require to provision sufficient sessions by making use of SessionPoolOptions#minSessions and SessionPoolOptions#maxSessions based on the traffic load. Failing to do so will result in higher latencies.

Parameter
Name Description
useMultiplexedSession boolean
Returns
Type Description
SessionPoolOptions.Builder

setWaitForMinSessions(Duration waitForMinSessions)

public SessionPoolOptions.Builder setWaitForMinSessions(Duration waitForMinSessions)

If greater than zero, waits for the session pool to have at least SessionPoolOptions#minSessions before returning the database client to the caller. Note that this check is only done during the session pool creation. This is usually done asynchronously in order to provide the client back to the caller as soon as possible. We don't recommend using this option unless you are executing benchmarks and want to guarantee the session pool has min sessions in the pool before continuing.

Defaults to zero (initialization is done asynchronously).

Parameter
Name Description
waitForMinSessions org.threeten.bp.Duration
Returns
Type Description
SessionPoolOptions.Builder

setWarnAndCloseIfInactiveTransactions()

public SessionPoolOptions.Builder setWarnAndCloseIfInactiveTransactions()

If there are inactive transactions, release the resources consumed by such transactions. A transaction is classified as inactive if it executes for more than a system defined duration. The option would also produce necessary warning logs through which it can be debugged as to what resources were released due to this option.

Use the option Builder#setWarnIfInactiveTransactions() if you only want to log warnings about long-running transactions.

Returns
Type Description
SessionPoolOptions.Builder

this builder for chaining

setWarnIfInactiveTransactions()

public SessionPoolOptions.Builder setWarnIfInactiveTransactions()

If there are inactive transactions, log warning messages with the origin of such transactions to aid debugging. A transaction is classified as inactive if it executes for more than a system defined duration.

This option won't change the state of the transactions. It only generates warning logs that can be used for debugging.

Returns
Type Description
SessionPoolOptions.Builder

this builder for chaining

setWriteSessionsFraction(float writeSessionsFraction) (deprecated)

public SessionPoolOptions.Builder setWriteSessionsFraction(float writeSessionsFraction)

Deprecated. This configuration value is no longer in use. The session pool does not prepare any sessions for read/write transactions. Instead, a transaction will automatically be started by the first statement that is executed by a transaction by including a BeginTransaction option with that statement.

This method may be removed in a future release.

Parameter
Name Description
writeSessionsFraction float
Returns
Type Description
SessionPoolOptions.Builder