PoolingOptions (DataStax Java Driver for Apache Cassandra

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. Therefore only a relatively small number of connections is needed. For each host, the driver uses a connection pool that may have a variable size (it will automatically adjust to the current load).
With ProtocolVersion#V2 or below, there are at most 128 simultaneous requests per connection, so the pool defaults to a variable size. You will typically raise the maximum capacity by adding more connections with setMaxConnectionsPerHost(HostDistance, int).
With ProtocolVersion#V3 or above, there are up to 32768 requests per connection, and the pool defaults to a fixed size of 1. You will typically raise the maximum capacity by allowing more simultaneous requests per connection (setMaxRequestsPerConnection(HostDistance, int)).
All parameters can be separately set for LOCAL and REMOTE hosts (HostDistance). For IGNORED hosts, no connections are created so these settings cannot be changed.

Field Summary

Fields
Modifier and Type	Field and Description
`static String`	`CORE_POOL_LOCAL_KEY`
`static String`	`CORE_POOL_REMOTE_KEY`
`static int`	`DEFAULT_HEARTBEAT_INTERVAL_SECONDS` The default value for `getHeartbeatIntervalSeconds()` (30).
`static int`	`DEFAULT_IDLE_TIMEOUT_SECONDS` The default value for `getIdleTimeoutSeconds()` (120).
`static int`	`DEFAULT_MAX_QUEUE_SIZE` The default value for `getMaxQueueSize()` (256).
`static int`	`DEFAULT_POOL_TIMEOUT_MILLIS` The default value for `getPoolTimeoutMillis()` (5000).
`static Map<ProtocolVersion,Map<String,Integer>>`	`DEFAULTS` The default values for connection options, that depend on the native protocol version.
`static String`	`MAX_POOL_LOCAL_KEY`
`static String`	`MAX_POOL_REMOTE_KEY`
`static String`	`MAX_REQUESTS_PER_CONNECTION_LOCAL_KEY`
`static String`	`MAX_REQUESTS_PER_CONNECTION_REMOTE_KEY`
`static String`	`NEW_CONNECTION_THRESHOLD_LOCAL_KEY`
`static String`	`NEW_CONNECTION_THRESHOLD_REMOTE_KEY`
`static int`	`UNSET` The value returned for connection options when they have not been set by the client, and the protocol version is not known yet.

Constructor Summary

Constructors
Constructor and Description

PoolingOptions()

Constructors
Constructor and Description
`PoolingOptions()`

Method Summary

All Methods Instance Methods Concrete 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`	`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`	`getMaxQueueSize()` Returns the maximum number of requests that get enqueued if no connection is available.
`int`	`getMaxRequestsPerConnection(HostDistance distance)` Returns the maximum number of requests per connection.
`int`	`getNewConnectionThreshold(HostDistance distance)` Returns the threshold that triggers the creation of a new connection to a host.
`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`	`setMaxQueueSize(int maxQueueSize)` Sets the maximum number of requests that get enqueued if no connection is available.
`PoolingOptions`	`setMaxRequestsPerConnection(HostDistance distance, int newMaxRequests)` Sets the maximum number of requests per connection.
`PoolingOptions`	`setNewConnectionThreshold(HostDistance distance, int newValue)` Sets the threshold that triggers the creation of a new connection to a host.
`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

- Field Detail
  - UNSET
```
public static final int UNSET
```
    The value returned for connection options when they have not been set by the client, and the protocol version is not known yet.
    Once a PoolingOptions object is associated to a Cluster and that cluster initializes, the protocol version will be detected, and connection options will take their default values for that protocol version.
    The methods that may return this value are: getCoreConnectionsPerHost(HostDistance), getMaxConnectionsPerHost(HostDistance), getNewConnectionThreshold(HostDistance), getMaxRequestsPerConnection(HostDistance).
    
    See Also:
    
    Constant Field Values
  - CORE_POOL_LOCAL_KEY
```
public static final String CORE_POOL_LOCAL_KEY
```
    See Also:
    
    Constant Field Values
  - MAX_POOL_LOCAL_KEY
```
public static final String MAX_POOL_LOCAL_KEY
```
    See Also:
    
    Constant Field Values
  - CORE_POOL_REMOTE_KEY
```
public static final String CORE_POOL_REMOTE_KEY
```
    See Also:
    
    Constant Field Values
  - MAX_POOL_REMOTE_KEY
```
public static final String MAX_POOL_REMOTE_KEY
```
    See Also:
    
    Constant Field Values
  - NEW_CONNECTION_THRESHOLD_LOCAL_KEY
```
public static final String NEW_CONNECTION_THRESHOLD_LOCAL_KEY
```
    See Also:
    
    Constant Field Values
  - NEW_CONNECTION_THRESHOLD_REMOTE_KEY
```
public static final String NEW_CONNECTION_THRESHOLD_REMOTE_KEY
```
    See Also:
    
    Constant Field Values
  - MAX_REQUESTS_PER_CONNECTION_LOCAL_KEY
```
public static final String MAX_REQUESTS_PER_CONNECTION_LOCAL_KEY
```
    See Also:
    
    Constant Field Values
  - MAX_REQUESTS_PER_CONNECTION_REMOTE_KEY
```
public static final String MAX_REQUESTS_PER_CONNECTION_REMOTE_KEY
```
    See Also:
    
    Constant Field Values
  - DEFAULTS
```
public static final Map<ProtocolVersion,Map<String,Integer>> DEFAULTS
```
    The default values for connection options, that depend on the native protocol version.
    The map stores protocol versions in ascending order, and only the versions that introduced a change are present. To find the defaults for a particular version, look for the highest key that is less than or equal to that version, in other words:
```
 ProtocolVersion referenceVersion = null;
 for (ProtocolVersion key : DEFAULTS.keySet()) {
     if (key.compareTo(actualVersion) > 0)
         break;
     else
         referenceVersion = key;
 }
 Map<String, Integer> defaults = DEFAULTS.get(referenceVersion);
 
```
    Once you've extracted the underlying map, use the keys CORE_POOL_LOCAL_KEY, MAX_POOL_LOCAL_KEY, CORE_POOL_REMOTE_KEY, MAX_POOL_REMOTE_KEY, NEW_CONNECTION_THRESHOLD_LOCAL_KEY, NEW_CONNECTION_THRESHOLD_REMOTE_KEY, MAX_REQUESTS_PER_CONNECTION_LOCAL_KEY and MAX_REQUESTS_PER_CONNECTION_REMOTE_KEY.
    See Also:
    
    UNSET
  - DEFAULT_IDLE_TIMEOUT_SECONDS
```
public static final int DEFAULT_IDLE_TIMEOUT_SECONDS
```
    The default value for getIdleTimeoutSeconds() (120).
    
    See Also:
    
    Constant Field Values
  - DEFAULT_POOL_TIMEOUT_MILLIS
```
public static final int DEFAULT_POOL_TIMEOUT_MILLIS
```
    The default value for getPoolTimeoutMillis() (5000).
    
    See Also:
    
    Constant Field Values
  - DEFAULT_MAX_QUEUE_SIZE
```
public static final int DEFAULT_MAX_QUEUE_SIZE
```
    The default value for getMaxQueueSize() (256).
    
    See Also:
    
    Constant Field Values
  - DEFAULT_HEARTBEAT_INTERVAL_SECONDS
```
public static final int DEFAULT_HEARTBEAT_INTERVAL_SECONDS
```
    The default value for getHeartbeatIntervalSeconds() (30).
    
    See Also:
    
    Constant Field Values
- Constructor Detail
  - PoolingOptions
```
public PoolingOptions()
```
- Method Detail
  - getCoreConnectionsPerHost
```
public int getCoreConnectionsPerHost(HostDistance distance)
```
    Returns the core number of connections per host.
    
    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.
    For the provided distance, this corresponds to the number of connections initially created and kept open to each host of that distance.
    The default value is:
    - with ProtocolVersion#V2 or below: 2 for LOCAL hosts and 1 for REMOTE hosts.
    - with ProtocolVersion#V3 or above: 1 for all hosts.
    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.
    
    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.
    For the provided distance, this corresponds to the maximum number of connections that can be created per host at that distance.
    The default value is:
    - with ProtocolVersion#V2 or below: 8 for LOCAL hosts and 2 for REMOTE hosts.
    - with ProtocolVersion#V3 or above: 1 for all hosts.
    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.
  - getNewConnectionThreshold
```
public int getNewConnectionThreshold(HostDistance distance)
```
    Returns the threshold that triggers the creation of a new connection to a host.
    
    Parameters:
    
    distance - the HostDistance for which to return this threshold.
    
    Returns:
    
    the configured threshold, or the default one if none have been set.
    
    See Also:
    
    setNewConnectionThreshold(HostDistance, int)
  - setNewConnectionThreshold
```
public PoolingOptions setNewConnectionThreshold(HostDistance distance,
                                                int newValue)
```
    Sets the threshold that triggers the creation of a new connection to a host.
    A new connection gets created if:
    - N connections are open
    - N < getMaxConnectionsPerHost(HostDistance)
    - the number of active requests is more than (N - 1) * getMaxRequestsPerConnection(HostDistance) + getNewConnectionThreshold(HostDistance)
    In other words, if all but the last connection are full, and the last connection is above this threshold.
    The default value is:
    - with ProtocolVersion#V2 or below: 100 for all hosts.
    - with ProtocolVersion#V3 or above: 800 for LOCAL hosts and 200 for REMOTE hosts.
    Parameters:
    
    distance - the HostDistance for which to configure this threshold.
    
    newValue - 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 newValue is less than the minimum value for this distance.
  - getMaxRequestsPerConnection
```
public int getMaxRequestsPerConnection(HostDistance distance)
```
    Returns the maximum number of requests per connection.
    
    Parameters:
    
    distance - the HostDistance for which to return this threshold.
    
    Returns:
    
    the maximum number of requests per connection at distance distance.
    
    See Also:
    
    setMaxRequestsPerConnection(HostDistance, int)
  - setMaxRequestsPerConnection
```
public PoolingOptions setMaxRequestsPerConnection(HostDistance distance,
                                                  int newMaxRequests)
```
    Sets the maximum number of requests per connection.
    The default value is:
    - with ProtocolVersion#V2 or below: 128 for all hosts (there should not be any reason to change this).
    - with ProtocolVersion#V3 or above: 1024 for LOCAL hosts and 256 for REMOTE hosts. These values were chosen so that the default V2 and V3 configuration generate the same load on a Cassandra cluster. Protocol V3 can go much higher (up to 32768), so if your number of clients is low, don't hesitate to experiment with higher values. If you have more than one connection per host, consider also adjusting setNewConnectionThreshold(HostDistance, int).
    Parameters:
    
    distance - the HostDistance for which to set this threshold.
    
    newMaxRequests - the value to set.
    
    Returns:
    
    this PoolingOptions.
    
    Throws:
    
    IllegalArgumentException - if distance == HostDistance.IGNORED, or if newMaxConnections is not within the allowed range.
  - 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.
    This option works in concert with setMaxQueueSize(int) to determine what happens if the driver tries to borrow a connection from the pool but none is available:
    - if either option is set to zero, the attempt is rejected immediately;
    - else if more than maxQueueSize requests are already waiting for a connection, the attempt is also rejected;
    - otherwise, the attempt is enqueued; if a connection becomes available before poolTimeoutMillis has elapsed, then the attempt succeeds, otherwise it is rejected.
    If the attempt is rejected, the driver will move to the next host in the LoadBalancingPolicy.newQueryPlan(String, Statement) query plan}.
    The default is 5 seconds. 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.
  - getMaxQueueSize
```
public int getMaxQueueSize()
```
    Returns the maximum number of requests that get enqueued if no connection is available.
    
    Returns:
    
    the maximum queue size.
  - setMaxQueueSize
```
public PoolingOptions setMaxQueueSize(int maxQueueSize)
```
    Sets the maximum number of requests that get enqueued if no connection is available.
    This option works in concert with setPoolTimeoutMillis(int) to determine what happens if the driver tries to borrow a connection from the pool but none is available:
    - if either options is set to zero, the attempt is rejected immediately;
    - else if more than maxQueueSize requests are already waiting for a connection, the attempt is also rejected;
    - otherwise, the attempt is enqueued; if a connection becomes available before poolTimeoutMillis has elapsed, then the attempt succeeds, otherwise it is rejected.
    If the attempt is rejected, the driver will move to the next host in the LoadBalancingPolicy.newQueryPlan(String, Statement) query plan}.
    The default value is 256. If this option is set to zero, the driver will never enqueue requests.
    Parameters:
    
    maxQueueSize - the new value.
    
    Returns:
    
    this PoolingOptions
    
    Throws:
    
    IllegalArgumentException - if the value 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()

Class PoolingOptions

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

UNSET

CORE_POOL_LOCAL_KEY

MAX_POOL_LOCAL_KEY

CORE_POOL_REMOTE_KEY

MAX_POOL_REMOTE_KEY

NEW_CONNECTION_THRESHOLD_LOCAL_KEY

NEW_CONNECTION_THRESHOLD_REMOTE_KEY

MAX_REQUESTS_PER_CONNECTION_LOCAL_KEY

MAX_REQUESTS_PER_CONNECTION_REMOTE_KEY

DEFAULTS

DEFAULT_IDLE_TIMEOUT_SECONDS

DEFAULT_POOL_TIMEOUT_MILLIS

DEFAULT_MAX_QUEUE_SIZE

DEFAULT_HEARTBEAT_INTERVAL_SECONDS

Constructor Detail

PoolingOptions

Method Detail

getCoreConnectionsPerHost

setCoreConnectionsPerHost

getMaxConnectionsPerHost

setMaxConnectionsPerHost

setConnectionsPerHost

getNewConnectionThreshold

setNewConnectionThreshold

getMaxRequestsPerConnection

setMaxRequestsPerConnection

getIdleTimeoutSeconds

setIdleTimeoutSeconds

getPoolTimeoutMillis

setPoolTimeoutMillis

getMaxQueueSize

setMaxQueueSize

getHeartbeatIntervalSeconds

setHeartbeatIntervalSeconds

getInitializationExecutor

setInitializationExecutor

refreshConnectedHosts

refreshConnectedHost