com.datastax.driver.core

Class PoolingOptions

java.lang.Object

com.datastax.driver.core.PoolingOptions

public class PoolingOptions
extends Object

Options related to connection pooling.

The driver uses connections in an asynchronous manner. Meaning that multiple requests can be submitted on the same connection at the same time. This means that the driver only needs to maintain a relatively small number of connections to each Cassandra host. These options allow the driver to control how many connections are kept exactly.

For each host, the driver keeps a core pool of connections open at all times determined by calling (getCoreConnectionsPerHost(com.datastax.driver.core.HostDistance)). If the use of those connections reaches a configurable threshold (getMaxSimultaneousRequestsPerConnectionThreshold(com.datastax.driver.core.HostDistance)), more connections are created up to the configurable maximum number of connections (getMaxConnectionsPerHost(com.datastax.driver.core.HostDistance)). When the pool exceeds the maximum number of connections, connections in excess are reclaimed.

Each of these parameters can be separately set for LOCAL and REMOTE hosts (HostDistance). For IGNORED hosts, the default for all those settings is 0 and cannot be changed.

Constructor Summary

Constructors

Constructor and Description
PoolingOptions()

Method Summary

Modifier and Type	Method and Description
int	getCoreConnectionsPerHost(HostDistance distance) Returns the core number of connections per host.
int	getHeartbeatIntervalSeconds() Returns the heart beat interval, after which a message is sent on an idle connection to make sure it's still alive.
int	getIdleTimeoutSeconds() Returns the timeout before an idle connection is removed.
Executor	getInitializationExecutor() Returns the executor to use for connection initialization.
int	getMaxConnectionsPerHost(HostDistance distance) Returns the maximum number of connections per host.
int	getMaxSimultaneousRequestsPerConnectionThreshold(HostDistance distance) Returns the number of simultaneous requests on all connections to an host after which more connections are created.
int	getMinSimultaneousRequestsPerConnectionThreshold(HostDistance distance) Deprecated. this option isn't used anymore with the current pool resizing algorithm.
int	getPoolTimeoutMillis() Returns the timeout when trying to acquire a connection from a host's pool.
void	refreshConnectedHost(Host host) Requests the driver to re-evaluate the HostDistance for a given node.
void	refreshConnectedHosts() Requests the driver to re-evaluate the HostDistance (through the configured LoadBalancingPolicy.distance(com.datastax.driver.core.Host)) for every known hosts and to drop/add connections to each hosts according to the computed distance.
PoolingOptions	setConnectionsPerHost(HostDistance distance, int core, int max) Sets the core and maximum number of connections per host in one call.
PoolingOptions	setCoreConnectionsPerHost(HostDistance distance, int newCoreConnections) Sets the core number of connections per host.
PoolingOptions	setHeartbeatIntervalSeconds(int heartbeatIntervalSeconds) Sets the heart beat interval, after which a message is sent on an idle connection to make sure it's still alive.
PoolingOptions	setIdleTimeoutSeconds(int idleTimeoutSeconds) Sets the timeout before an idle connection is removed.
PoolingOptions	setInitializationExecutor(Executor initializationExecutor) Sets the executor to use for connection initialization.
PoolingOptions	setMaxConnectionsPerHost(HostDistance distance, int newMaxConnections) Sets the maximum number of connections per host.
PoolingOptions	setMaxSimultaneousRequestsPerConnectionThreshold(HostDistance distance, int newMaxSimultaneousRequests) Sets number of simultaneous requests on all connections to an host after which more connections are created.
PoolingOptions	setMinSimultaneousRequestsPerConnectionThreshold(HostDistance distance, int newMinSimultaneousRequests) Deprecated. this option isn't used anymore with the current pool resizing algorithm.
PoolingOptions	setPoolTimeoutMillis(int poolTimeoutMillis) Sets the timeout when trying to acquire a connection from a host's pool.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

PoolingOptions

public PoolingOptions()

Method Detail

getMinSimultaneousRequestsPerConnectionThreshold

@Deprecated
public int getMinSimultaneousRequestsPerConnectionThreshold(HostDistance distance)

Deprecated. this option isn't used anymore with the current pool resizing algorithm.

Returns the number of simultaneous requests on a connection below which connections in excess are reclaimed.

If an opened connection to an host at distance distance handles less than this number of simultaneous requests and there is more than getCoreConnectionsPerHost(com.datastax.driver.core.HostDistance) connections open to this host, the connection is closed.

The default value for this option is 25 for LOCAL and REMOTE hosts.

Parameters:

distance - the HostDistance for which to return this threshold.

Returns:

the configured threshold, or the default one if none have been set.

setMinSimultaneousRequestsPerConnectionThreshold

@Deprecated
public PoolingOptions setMinSimultaneousRequestsPerConnectionThreshold(HostDistance distance,
                                                                                   int newMinSimultaneousRequests)

Deprecated. this option isn't used anymore with the current pool resizing algorithm.

Sets the number of simultaneous requests on a connection below which connections in excess are reclaimed.

Parameters:

distance - the HostDistance for which to configure this threshold.

newMinSimultaneousRequests - the value to set (between 0 and 128).

Returns:

this PoolingOptions.

Throws:

IllegalArgumentException - if distance == HostDistance.IGNORED, or if minSimultaneousRequests is not in range, or if newMinSimultaneousRequests is greater than the maximum value for this distance.

getMaxSimultaneousRequestsPerConnectionThreshold

public int getMaxSimultaneousRequestsPerConnectionThreshold(HostDistance distance)

Returns the number of simultaneous requests on all connections to an host after which more connections are created.

If all the connections opened to an host at distance distance connection are handling more than this number of simultaneous requests and there is less than getMaxConnectionsPerHost(com.datastax.driver.core.HostDistance) connections open to this host, a new connection is open.

Note that a given connection cannot handle more than 128 simultaneous requests (protocol limitation).

The default value for this option is 100 for LOCAL and REMOTE hosts.

Parameters:

distance - the HostDistance for which to return this threshold.

Returns:

the configured threshold, or the default one if none have been set.

setMaxSimultaneousRequestsPerConnectionThreshold

public PoolingOptions setMaxSimultaneousRequestsPerConnectionThreshold(HostDistance distance,
                                                                       int newMaxSimultaneousRequests)

Sets number of simultaneous requests on all connections to an host after which more connections are created.

Parameters:

distance - the HostDistance for which to configure this threshold.

newMaxSimultaneousRequests - the value to set (between 0 and 128).

Returns:

this PoolingOptions.

Throws:

IllegalArgumentException - if distance == HostDistance.IGNORED, or if maxSimultaneousRequests is not in range, or if newMaxSimultaneousRequests is less than the minimum value for this distance.

getCoreConnectionsPerHost

public int getCoreConnectionsPerHost(HostDistance distance)

Returns the core number of connections per host.

For the provided distance, this correspond to the number of connections initially created and kept open to each host of that distance.

Parameters:

distance - the HostDistance for which to return this threshold.

Returns:

the core number of connections per host at distance distance.

setCoreConnectionsPerHost

public PoolingOptions setCoreConnectionsPerHost(HostDistance distance,
                                                int newCoreConnections)

Sets the core number of connections per host.

Parameters:

distance - the HostDistance for which to set this threshold.

newCoreConnections - the value to set

Returns:

this PoolingOptions.

Throws:

IllegalArgumentException - if distance == HostDistance.IGNORED, or if newCoreConnections is greater than the maximum value for this distance.

See Also:

setConnectionsPerHost(HostDistance, int, int)

getMaxConnectionsPerHost

public int getMaxConnectionsPerHost(HostDistance distance)

Returns the maximum number of connections per host.

For the provided distance, this correspond to the maximum number of connections that can be created per host at that distance.

Parameters:

distance - the HostDistance for which to return this threshold.

Returns:

the maximum number of connections per host at distance distance.

setMaxConnectionsPerHost

public PoolingOptions setMaxConnectionsPerHost(HostDistance distance,
                                               int newMaxConnections)

Sets the maximum number of connections per host.

Parameters:

distance - the HostDistance for which to set this threshold.

newMaxConnections - the value to set

Returns:

this PoolingOptions.

Throws:

IllegalArgumentException - if distance == HostDistance.IGNORED, or if newMaxConnections is less than the core value for this distance.

See Also:

setConnectionsPerHost(HostDistance, int, int)

setConnectionsPerHost

public PoolingOptions setConnectionsPerHost(HostDistance distance,
                                            int core,
                                            int max)

Sets the core and maximum number of connections per host in one call.

This is a convenience method that is equivalent to calling setCoreConnectionsPerHost(HostDistance, int) and setMaxConnectionsPerHost(HostDistance, int).

Parameters:

distance - the HostDistance for which to set these threshold.

core - the core number of connections.

max - the max number of connections.

Returns:

this PoolingOptions.

Throws:

IllegalArgumentException - if distance == HostDistance.IGNORED, or if core > max.

getIdleTimeoutSeconds

public int getIdleTimeoutSeconds()

Returns the timeout before an idle connection is removed.

Returns:

the timeout.

setIdleTimeoutSeconds

public PoolingOptions setIdleTimeoutSeconds(int idleTimeoutSeconds)

Sets the timeout before an idle connection is removed.

The order of magnitude should be a few minutes (the default is 120 seconds). The timeout that triggers the removal has a granularity of 10 seconds.

Parameters:

idleTimeoutSeconds - the new timeout in seconds.

Returns:

this PoolingOptions.

Throws:

IllegalArgumentException - if the timeout is negative.

getPoolTimeoutMillis

public int getPoolTimeoutMillis()

Returns the timeout when trying to acquire a connection from a host's pool.

Returns:

the timeout.

setPoolTimeoutMillis

public PoolingOptions setPoolTimeoutMillis(int poolTimeoutMillis)

Sets the timeout when trying to acquire a connection from a host's pool.

If no connection is available within that time, the driver will try the next host from the query plan.

If this option is set to zero, the driver won't wait at all.

Parameters:

poolTimeoutMillis - the new value in milliseconds.

Returns:

this PoolingOptions

Throws:

IllegalArgumentException - if the timeout is negative.

getHeartbeatIntervalSeconds

public int getHeartbeatIntervalSeconds()

Returns the heart beat interval, after which a message is sent on an idle connection to make sure it's still alive.

Returns:

the interval.

setHeartbeatIntervalSeconds

public PoolingOptions setHeartbeatIntervalSeconds(int heartbeatIntervalSeconds)

Sets the heart beat interval, after which a message is sent on an idle connection to make sure it's still alive.

This is an application-level keep-alive, provided for convenience since adjusting the TCP keep-alive might not be practical in all environments.

This option should be set higher than SocketOptions.getReadTimeoutMillis().

The default value for this option is 30 seconds.

Parameters:

heartbeatIntervalSeconds - the new value in seconds. If set to 0, it will disable the feature.

Returns:

this PoolingOptions

Throws:

IllegalArgumentException - if the interval is negative.

getInitializationExecutor

public Executor getInitializationExecutor()

Returns the executor to use for connection initialization.

Returns:

the executor.

See Also:

setInitializationExecutor(java.util.concurrent.Executor)

setInitializationExecutor

public PoolingOptions setInitializationExecutor(Executor initializationExecutor)

Sets the executor to use for connection initialization.

Connections are open in a completely asynchronous manner. Since initializing the transport requires separate CQL queries, the futures representing the completion of these queries are transformed and chained. This executor is where these transformations happen.

This is an advanced option, which should be rarely needed in practice. It defaults to Guava's MoreExecutors.sameThreadExecutor(), which results in running the transformations on the network I/O threads; this is fine if the transformations are fast and not I/O bound (which is the case by default). One reason why you might want to provide a custom executor is if you use authentication with a custom Authenticator implementation that performs blocking calls.

Parameters:

initializationExecutor - the executor to use

Returns:

this PoolingOptions

Throws:

NullPointerException - if the executor is null

refreshConnectedHosts

public void refreshConnectedHosts()

Requests the driver to re-evaluate the HostDistance (through the configured LoadBalancingPolicy.distance(com.datastax.driver.core.Host)) for every known hosts and to drop/add connections to each hosts according to the computed distance.

Note that, due to backward compatibility issues, this method is not interruptible. If the caller thread gets interrupted, the method will complete and only then re-interrupt the thread (which you can check with Thread.currentThread().isInterrupted()).

refreshConnectedHost

public void refreshConnectedHost(Host host)

Requests the driver to re-evaluate the HostDistance for a given node.

Parameters:

host - the host to refresh.

See Also:

refreshConnectedHosts()