Package com.datastax.driver.core

Class 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 Detail

      • 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

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

      • 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:

        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.

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