public class PoolingOptions extends Object
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.
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 and Description |
---|
PoolingOptions() |
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.
|
public static final int UNSET
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)
.
public static final String CORE_POOL_LOCAL_KEY
public static final String MAX_POOL_LOCAL_KEY
public static final String CORE_POOL_REMOTE_KEY
public static final String MAX_POOL_REMOTE_KEY
public static final String NEW_CONNECTION_THRESHOLD_LOCAL_KEY
public static final String NEW_CONNECTION_THRESHOLD_REMOTE_KEY
public static final String MAX_REQUESTS_PER_CONNECTION_LOCAL_KEY
public static final String MAX_REQUESTS_PER_CONNECTION_REMOTE_KEY
public static final Map<ProtocolVersion,Map<String,Integer>> DEFAULTS
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
.UNSET
public static final int DEFAULT_IDLE_TIMEOUT_SECONDS
getIdleTimeoutSeconds()
(120).public static final int DEFAULT_POOL_TIMEOUT_MILLIS
getPoolTimeoutMillis()
(5000).public static final int DEFAULT_MAX_QUEUE_SIZE
getMaxQueueSize()
(256).public static final int DEFAULT_HEARTBEAT_INTERVAL_SECONDS
getHeartbeatIntervalSeconds()
(30).public int getCoreConnectionsPerHost(HostDistance distance)
distance
- the HostDistance
for which to return this threshold.distance
.public PoolingOptions setCoreConnectionsPerHost(HostDistance distance, int newCoreConnections)
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:
ProtocolVersion#V2
or below: 2 for LOCAL
hosts and 1 for REMOTE
hosts.
ProtocolVersion#V3
or above: 1 for all hosts.
distance
- the HostDistance
for which to set this threshold.newCoreConnections
- the value to setPoolingOptions
.IllegalArgumentException
- if distance == HostDistance.IGNORED
, or if newCoreConnections
is greater than the maximum value for this distance.setConnectionsPerHost(HostDistance, int, int)
public int getMaxConnectionsPerHost(HostDistance distance)
distance
- the HostDistance
for which to return this threshold.distance
.public PoolingOptions setMaxConnectionsPerHost(HostDistance distance, int newMaxConnections)
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:
ProtocolVersion#V2
or below: 8 for LOCAL
hosts and 2 for REMOTE
hosts.
ProtocolVersion#V3
or above: 1 for all hosts.
distance
- the HostDistance
for which to set this threshold.newMaxConnections
- the value to setPoolingOptions
.IllegalArgumentException
- if distance == HostDistance.IGNORED
, or if newMaxConnections
is less than the core value for this distance.setConnectionsPerHost(HostDistance, int, int)
public PoolingOptions setConnectionsPerHost(HostDistance distance, int core, int max)
This is a convenience method that is equivalent to calling setCoreConnectionsPerHost(HostDistance, int)
and setMaxConnectionsPerHost(HostDistance, int)
.
distance
- the HostDistance
for which to set these threshold.core
- the core number of connections.max
- the max number of connections.PoolingOptions
.IllegalArgumentException
- if distance == HostDistance.IGNORED
, or if core
> max
.public int getNewConnectionThreshold(HostDistance distance)
distance
- the HostDistance
for which to return this threshold.setNewConnectionThreshold(HostDistance, int)
public PoolingOptions setNewConnectionThreshold(HostDistance distance, int newValue)
A new connection gets created if:
getMaxConnectionsPerHost(HostDistance)
getMaxRequestsPerConnection(HostDistance)
+ getNewConnectionThreshold(HostDistance)
The default value is:
ProtocolVersion#V2
or below: 100 for all hosts.
ProtocolVersion#V3
or above: 800 for LOCAL
hosts and 200 for REMOTE
hosts.
distance
- the HostDistance
for which to configure this threshold.newValue
- the value to set (between 0 and 128).PoolingOptions
.IllegalArgumentException
- if distance == HostDistance.IGNORED
, or if maxSimultaneousRequests
is not in range, or if newValue
is less than the minimum
value for this distance.public int getMaxRequestsPerConnection(HostDistance distance)
distance
- the HostDistance
for which to return this threshold.distance
.setMaxRequestsPerConnection(HostDistance, int)
public PoolingOptions setMaxRequestsPerConnection(HostDistance distance, int newMaxRequests)
The default value is:
ProtocolVersion#V2
or below: 128 for all hosts (there should not be any
reason to change this).
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)
.
distance
- the HostDistance
for which to set this threshold.newMaxRequests
- the value to set.PoolingOptions
.IllegalArgumentException
- if distance == HostDistance.IGNORED
, or if newMaxConnections
is not within the allowed range.public int getIdleTimeoutSeconds()
public PoolingOptions setIdleTimeoutSeconds(int idleTimeoutSeconds)
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.
idleTimeoutSeconds
- the new timeout in seconds.PoolingOptions
.IllegalArgumentException
- if the timeout is negative.public int getPoolTimeoutMillis()
public PoolingOptions setPoolTimeoutMillis(int poolTimeoutMillis)
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:
maxQueueSize
requests are already waiting for a connection, the
attempt is also rejected;
poolTimeoutMillis
has elapsed, then the attempt succeeds, otherwise it is rejected.
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.
poolTimeoutMillis
- the new value in milliseconds.PoolingOptions
IllegalArgumentException
- if the timeout is negative.public int getMaxQueueSize()
public PoolingOptions setMaxQueueSize(int maxQueueSize)
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:
maxQueueSize
requests are already waiting for a connection, the
attempt is also rejected;
poolTimeoutMillis
has elapsed, then the attempt succeeds, otherwise it is rejected.
LoadBalancingPolicy.newQueryPlan(String, Statement)
query
plan}.
The default value is 256. If this option is set to zero, the driver will never enqueue requests.
maxQueueSize
- the new value.PoolingOptions
IllegalArgumentException
- if the value is negative.public int getHeartbeatIntervalSeconds()
public PoolingOptions setHeartbeatIntervalSeconds(int heartbeatIntervalSeconds)
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.
heartbeatIntervalSeconds
- the new value in seconds. If set to 0, it will disable the
feature.PoolingOptions
IllegalArgumentException
- if the interval is negative.public Executor getInitializationExecutor()
setInitializationExecutor(java.util.concurrent.Executor)
public PoolingOptions setInitializationExecutor(Executor initializationExecutor)
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.
initializationExecutor
- the executor to usePoolingOptions
NullPointerException
- if the executor is nullpublic void refreshConnectedHosts()
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()
).
public void refreshConnectedHost(Host host)
HostDistance
for a given node.host
- the host to refresh.refreshConnectedHosts()
Copyright © 2012–2018. All rights reserved.