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.

With ProtocolVersion#V2 or below: 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 if the use of opened connections drops below the configured threshold (getMinSimultaneousRequestsPerConnectionThreshold(com.datastax.driver.core.HostDistance)).

Due to known issues with the current ProtocolVersion#V2 pool implementation (see JAVA-419), it is strongly recommended to use a fixed-size pool (core connections = max connections). The default values respect this (8 for local hosts, 2 for remote hosts).

With ProtocolVersion#V3 or above: the driver uses a single connection for each LOCAL or REMOTE host. This connection can handle a larger amount of simultaneous requests, limited by getMaxSimultaneousRequestsPerHostThreshold(HostDistance).

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

Methods

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	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	getMaxSimultaneousRequestsPerHostThreshold(HostDistance distance) Returns the maximum number of requests per host.
int	getMinSimultaneousRequestsPerConnectionThreshold(HostDistance distance) Returns the number of simultaneous requests on a connection below which connections in excess are reclaimed.
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	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	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	setMaxSimultaneousRequestsPerHostThreshold(HostDistance distance, int newMaxRequests) Sets the maximum number of requests per host.
PoolingOptions	setMinSimultaneousRequestsPerConnectionThreshold(HostDistance distance, int newMinSimultaneousRequests) Sets the number of simultaneous requests on a connection below which connections in excess are reclaimed.
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

public int getMinSimultaneousRequestsPerConnectionThreshold(HostDistance distance)

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

This option is only used with ProtocolVersion#V2 or below.

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

public PoolingOptions setMinSimultaneousRequestsPerConnectionThreshold(HostDistance distance,
                                                              int newMinSimultaneousRequests)

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

This option is only used with ProtocolVersion#V2 or below.

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.

This option is only used with ProtocolVersion#V2 or below.

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.

This option is only used with ProtocolVersion#V2 or below.

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.

This option is only used with ProtocolVersion#V2 or below.

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.

This option is only used with ProtocolVersion#V2 or below.

Due to known issues with the current pool implementation (see JAVA-419), it is strongly recommended to use a fixed-size pool (core connections = max connections).

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.

getMaxConnectionsPerHost

public int getMaxConnectionsPerHost(HostDistance distance)

Returns the maximum number of connections per host.

This option is only used with ProtocolVersion#V2 or below.

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.

This option is only used with ProtocolVersion#V2 or below.

Due to known issues with the current pool implementation (see JAVA-419), it is strongly recommended to use a fixed-size pool (core connections = max connections).

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.

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.

getMaxSimultaneousRequestsPerHostThreshold

public int getMaxSimultaneousRequestsPerHostThreshold(HostDistance distance)

Returns the maximum number of requests per host.

This option is only used with ProtocolVersion#V3 or above.

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

Parameters:

distance - the HostDistance for which to return this threshold.

Returns:

the maximum number of requests per host at distance distance.

setMaxSimultaneousRequestsPerHostThreshold

public PoolingOptions setMaxSimultaneousRequestsPerHostThreshold(HostDistance distance,
                                                        int newMaxRequests)

Sets the maximum number of requests per host.

This option is only used with ProtocolVersion#V3 or above.

Parameters:

distance - the HostDistance for which to set this threshold.

newMaxRequests - the value to set (between 1 and 32768).

Returns:

this PoolingOptions.

Throws:

IllegalArgumentException - if distance == HostDistance.IGNORED, or if newMaxConnections is not within the allowed range.

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.

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