Client Configuration Properties

These are the cache.xml properties for the client-cache pool configuration. Example XML:
    <pool name="publisher" subscription-enabled="true">
        <locator host="<locator1-address>" port="<port1>"/>
        <locator host="<locator2-address>" port="<port2>"/>

You can set the same configuration properties using the com.gemstone.gemfire.cache.client ClientCache and Pool interfaces. For detailed information, see the online Java API documentation.

Except where noted, all parameters are optional.
Client's <pool> Subelements Description
locator Addresses and ports of the locators to connect to. You can define multiple locators for the pool.
Note: Provide a locator list or server list, but not both.
server Addresses and ports of the servers to connect to.
Note: Provide a server list or locator list, but not both.
Client's <pool> Attributes Description


Amount of time a thread will wait to get a pool connection before timing out with an exception. This timeout keeps threads from waiting indefinitely when the pool’s max-connections has been reached and all connections in the pool are in use by other threads. Default: 10000.


Maximum time, in milliseconds, a pool connection can stay open without being used when there are more than min-connections in the pool. Pings over the connection do not count as connection use. If set to -1, there is no idle timeout. Default: 5000.
load-conditioning-interval Amount of time, in milliseconds, a pool connection can remain open before being eligible for silent replacement to a less-loaded server. Default: 300000 (5 minutes).
max-connections Maximum number of pool connections the pool can create. If the maximum connections are in use, an operation requiring a client-to-server connection blocks until a connection becomes available or the free-connection-timeout is reached. If set to -1, there is no maximum. The setting must indicate a cap greater than min-connections. Default: -1.
Note: If you need to use this to cap your pool connections, you should disable the pool attribute pr-single-hop-enabled. Leaving single hop enabled can increase thrashing and lower performance.


Minimum number of pool connections to keep available at all times. Used to establish the initial connection pool. If set to 0 (zero), no connection is created until an operation requires it. This number is the starting point, with more connections added later as needed, up to the max-connection setting. The setting must be an integer greater than or equal to 0. Default: 1.
multiuser-authentication Used for installations with security where you want to accommodate multiple users within a single client. If set to true, the pool provides authorization for multiple user instances in the same client application, and each user accesses the cache through its own RegionService instance. If false, the client either uses no authorization or just provides credentials for the single client process.
name Name of this pool. Used in the client region pool-name to assign this pool to a region in the client cache.
Note: This is a required property with no default setting.
ping-interval How often to communicate with the server to show the client is alive, set in milliseconds. Pings are only sent when the ping-interval elapses between normal client messages. Default: 10000.
Note: Set this lower than the server’s maximum-time-between-pings.
pr-single-hop-enabled Setting used to improve access to partitioned region data in the servers. Indicates whether to use metadata about the partitioned region data storage locations to decide where to send some data requests. This allows a client to send a data operation directly to the server hosting the key. Without this, the client contacts any available server and that server contacts the data store. This is used only for operations that can be carried out on a server-by-server basis, like put, get, and destroy. When you set pr-single-hop-enabled to true, you can set thread-local-connections also to true, which configures threads to use dedicated connections. This can help you scale the number of client connections. Default: true.
read-timeout Maximum time, in milliseconds, for the client to wait for a response from a server. Default: 10000.
retry-attempts Number of times to retry a client request before giving up. If one server fails, the pool moves to the next, and so on until it is successful or it hits this limit. If the available servers are fewer than this setting, the pool will retry servers that have already failed until it reaches the limit. If this is set to -1, the pool tries every available server once. Default: -1.
server-group Logical named server group to use from the pool. A null value uses the global server group to which all servers belong. Default: null.
Note: This is only used when the locator list is defined.
socket-buffer-size Size for socket buffers from the client to the server. Default: 32768.
statistic-interval Interval, in milliseconds, at which to send client statistics to the server. If set to -1, statistics are not sent. Default: -1.
subscription-ack-interval Time, in milliseconds, between messages to the primary server to acknowledge event receipt. Default: 500.
Note: Used only when subscription-redundancy is not ‘0’ (zero).
subscription-enabled Boolean indicating whether the server should connect back to the client and automatically sends server-side cache update information. Any bind address information for the client is automatically passed to the server for use in the callbacks. Default: false.
subscription-message-tracking-timeout Time-to-live, in milliseconds, for entries in the client’s message tracking list. Default: 900000 (15 minutes).
subscription-redundancy Number of servers to use as backup to the primary for highly available subscription queue management. If set to 0, none are used. If set to -1, all available servers are used. Default: 0.
thread-local-connections Boolean specifying whether connections are sticky. True causes the connection to stick to the thread for multiple requests. False causes each connection to be returned to the pool after a request finishes. A sticky connection is returned to the pool when the thread releases it through the Pool method releaseThreadLocalConnection, when the idle-timeout is reached, or when the pool is destroyed. When you set pr-single-hop-enabled to true, you can set thread-local-connections also to true, which configures threads to use dedicated connections. This can help you scale the number of client connections. Default: false.