org.apache.geode.cache.client

## Interface PoolFactory

-     public interface PoolFactory

  This interface provides for the configuration and creation of instances of `Pool`.

  Every pool needs to have at least one `locator` or `server` added to it. Locators should be added unless direct connections to cache servers are desired.

  The setter methods are used to specify non-default values for the other pool properties.

  Once it is configured `create(java.lang.String)` will produce an instance.

  The factory can be restored to its default configuration by calling `reset()`.

  Instances of this interface can be created by calling `PoolManager.createFactory()`.

  If a subscription is going to be made using a pool then subscriptions `must be enabled` on the pool. Subscriptions are made using these APIs:

  - `QueryService.newCq(String, CqAttributes)`
  - `QueryService.newCq(String, CqAttributes, boolean)`
  - `QueryService.newCq(String, String, CqAttributes)`
  - `QueryService.newCq(String, String, CqAttributes, boolean)`
  - `Region.registerInterest(Object)`
  - `Region.registerInterest(Object, boolean)`
  - `Region.registerInterest(Object, InterestResultPolicy)`
  - `Region.registerInterest(Object, InterestResultPolicy, boolean)`
  - `Region.registerInterestRegex(String)`
  - `Region.registerInterestRegex(String, boolean)`
  - `Region.registerInterestRegex(String, InterestResultPolicy)`
  - `Region.registerInterestRegex(String, InterestResultPolicy, boolean)`
  Since:
    GemFire 5.7

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `DEFAULT_FREE_CONNECTION_TIMEOUT` The default amount of time, in milliseconds, which we will wait for a free connection if max connections is set and all of the connections are in use.
    `static long` | `DEFAULT_IDLE_TIMEOUT` The default amount of time in milliseconds, to wait for a connection to become idle
    `static int` | `DEFAULT_LOAD_CONDITIONING_INTERVAL` The default interval in which the pool will check to see if a connection to a given server should be moved to a different server to improve the load balance.
    `static int` | `DEFAULT_MAX_CONNECTIONS` The default maximum number of connections to create
    `static int` | `DEFAULT_MIN_CONNECTIONS` The default number of connections to initially create
    `static boolean` | `DEFAULT_MULTIUSER_AUTHENTICATION` The default value for whether to use multiuser mode.
    `static long` | `DEFAULT_PING_INTERVAL` The default frequency, in milliseconds, to ping servers.
    `static boolean` | `DEFAULT_PR_SINGLE_HOP_ENABLED` The default value for whether to have single hop optimisations enabled.
    `static int` | `DEFAULT_READ_TIMEOUT` The default amount of time, in milliseconds, to wait for a response from a server
    `static int` | `DEFAULT_RETRY_ATTEMPTS` The default number of times to retry an operation after a timeout or exception.
    `static java.lang.String` | `DEFAULT_SERVER_GROUP` The default server group.
    `static int` | `DEFAULT_SOCKET_BUFFER_SIZE` Default size in bytes of the socket buffer on each connection established.
    `static int` | `DEFAULT_STATISTIC_INTERVAL` The default frequency, in milliseconds, that client statistics will be sent to the server.
    `static int` | `DEFAULT_SUBSCRIPTION_ACK_INTERVAL` The default amount of time, in milliseconds, to wait before sending an acknowledgement to the server about events received from the subscriptions.
    `static boolean` | `DEFAULT_SUBSCRIPTION_ENABLED` The default value for whether to establish a server to client subscription.
    `static int` | `DEFAULT_SUBSCRIPTION_MESSAGE_TRACKING_TIMEOUT` The default amount of time, in milliseconds, that messages sent from a server to a client will be tracked.
    `static int` | `DEFAULT_SUBSCRIPTION_REDUNDANCY` The default redundancy for servers holding subscriptions established by this client
    `static boolean` | `DEFAULT_THREAD_LOCAL_CONNECTIONS` The default value for whether connections should have affinity to the thread that last used them.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `PoolFactory` | `addLocator(java.lang.String host, int port)` Add a locator, given its host and port, to this factory.
    `PoolFactory` | `addServer(java.lang.String host, int port)` Add a server, given its host and port, to this factory.
    `Pool` | `create(java.lang.String name)` Create a new Pool for connecting a client to a set of GemFire Cache Servers.
    `PoolFactory` | `reset()` Resets the configuration of this factory to its defaults.
    `PoolFactory` | `setFreeConnectionTimeout(int connectionTimeout)` Sets the free connection timeout for this pool.
    `PoolFactory` | `setIdleTimeout(long idleTimeout)` Set the amount of time a connection can be idle before expiring the connection.
    `PoolFactory` | `setLoadConditioningInterval(int loadConditioningInterval)` Sets the load conditioning interval for this pool.
    `PoolFactory` | `setMaxConnections(int maxConnections)` Set the max number of client to server connections that the pool will create.
    `PoolFactory` | `setMinConnections(int minConnections)` Set the minimum number of connections to keep available at all times.
    `PoolFactory` | `setMultiuserAuthentication(boolean enabled)` If set to `true` then the created pool can be used by multiple authenticated users.
    `PoolFactory` | `setPingInterval(long pingInterval)` How often to ping servers to verify that they are still alive.
    `PoolFactory` | `setPRSingleHopEnabled(boolean enabled)` By default setPRSingleHopEnabled is `true` in which case the client is aware of the location of partitions on servers hosting `regions` with `DataPolicy.PARTITION`.
    `PoolFactory` | `setReadTimeout(int timeout)` Sets the number of milliseconds to wait for a response from a server before timing out the operation and trying another server (if any are available).
    `PoolFactory` | `setRetryAttempts(int retryAttempts)` Set the number of times to retry a request after timeout/exception.
    `PoolFactory` | `setServerGroup(java.lang.String group)` Configures the group that all servers this pool connects to must belong to.
    `PoolFactory` | `setSocketBufferSize(int bufferSize)` Sets the socket buffer size for each connection made in this pool.
    `PoolFactory` | `setStatisticInterval(int statisticInterval)` How often to send client statistics to the server.
    `PoolFactory` | `setSubscriptionAckInterval(int ackInterval)` Sets the interval in milliseconds to wait before sending acknowledgements to the cache server for events received from the server subscriptions.
    `PoolFactory` | `setSubscriptionEnabled(boolean enabled)` If set to `true` then the created pool will have server-to-client subscriptions enabled.
    `PoolFactory` | `setSubscriptionMessageTrackingTimeout(int messageTrackingTimeout)` Sets the messageTrackingTimeout attribute which is the time-to-live period, in milliseconds, for subscription events the client has received from the server.
    `PoolFactory` | `setSubscriptionRedundancy(int redundancy)` Sets the redundancy level for this pools server-to-client subscriptions.
    `PoolFactory` | `setThreadLocalConnections(boolean threadLocalConnections)` Sets the thread local connections policy for this pool.

- - ### Field Detail

    - #### DEFAULT_FREE_CONNECTION_TIMEOUT

          static final int DEFAULT_FREE_CONNECTION_TIMEOUT

      The default amount of time, in milliseconds, which we will wait for a free connection if max connections is set and all of the connections are in use.

      Current value: `10000`.

      See Also:
        Constant Field Values

    - #### DEFAULT_LOAD_CONDITIONING_INTERVAL

          static final int DEFAULT_LOAD_CONDITIONING_INTERVAL

      The default interval in which the pool will check to see if a connection to a given server should be moved to a different server to improve the load balance.

      Current value: `300,000` (which is 5 minutes).

      See Also:
        Constant Field Values

    - #### DEFAULT_SOCKET_BUFFER_SIZE

          static final int DEFAULT_SOCKET_BUFFER_SIZE

      Default size in bytes of the socket buffer on each connection established.

      Current value: `32768`.

      See Also:
        Constant Field Values

    - #### DEFAULT_READ_TIMEOUT

          static final int DEFAULT_READ_TIMEOUT

      The default amount of time, in milliseconds, to wait for a response from a server

      Current value: `10000`.

      See Also:
        Constant Field Values

    - #### DEFAULT_MIN_CONNECTIONS

          static final int DEFAULT_MIN_CONNECTIONS

      The default number of connections to initially create

      Current value: `1`.

      See Also:
        Constant Field Values

    - #### DEFAULT_MAX_CONNECTIONS

          static final int DEFAULT_MAX_CONNECTIONS

      The default maximum number of connections to create

      Current value: `-1`.

      See Also:
        Constant Field Values

    - #### DEFAULT_IDLE_TIMEOUT

          static final long DEFAULT_IDLE_TIMEOUT

      The default amount of time in milliseconds, to wait for a connection to become idle

      Current value: `5000`.

      See Also:
        Constant Field Values

    - #### DEFAULT_RETRY_ATTEMPTS

          static final int DEFAULT_RETRY_ATTEMPTS

      The default number of times to retry an operation after a timeout or exception.

      Current value: `-1`.

      See Also:
        Constant Field Values

    - #### DEFAULT_PING_INTERVAL

          static final long DEFAULT_PING_INTERVAL

      The default frequency, in milliseconds, to ping servers.

      Current value: `10000`.

      See Also:
        Constant Field Values

    - #### DEFAULT_STATISTIC_INTERVAL

          static final int DEFAULT_STATISTIC_INTERVAL

      The default frequency, in milliseconds, that client statistics will be sent to the server.

      Current value: `-1`.

      See Also:
        Constant Field Values

    - #### DEFAULT_THREAD_LOCAL_CONNECTIONS

          static final boolean DEFAULT_THREAD_LOCAL_CONNECTIONS

      The default value for whether connections should have affinity to the thread that last used them.

      Current value: `false`.

      See Also:
        Constant Field Values

    - #### DEFAULT_SUBSCRIPTION_ENABLED

          static final boolean DEFAULT_SUBSCRIPTION_ENABLED

      The default value for whether to establish a server to client subscription.

      Current value: `false`.

      See Also:
        Constant Field Values

    - #### DEFAULT_SUBSCRIPTION_REDUNDANCY

          static final int DEFAULT_SUBSCRIPTION_REDUNDANCY

      The default redundancy for servers holding subscriptions established by this client

      Current value: `0`.

      See Also:
        Constant Field Values

    - #### DEFAULT_SUBSCRIPTION_MESSAGE_TRACKING_TIMEOUT

          static final int DEFAULT_SUBSCRIPTION_MESSAGE_TRACKING_TIMEOUT

      The default amount of time, in milliseconds, that messages sent from a server to a client will be tracked. The tracking is done to minimize duplicate events.

      Current value: `900000`.

      See Also:
        Constant Field Values

    - #### DEFAULT_SUBSCRIPTION_ACK_INTERVAL

          static final int DEFAULT_SUBSCRIPTION_ACK_INTERVAL

      The default amount of time, in milliseconds, to wait before sending an acknowledgement to the server about events received from the subscriptions.

      Current value: `100`.

      See Also:
        Constant Field Values

    - #### DEFAULT_SERVER_GROUP

          static final java.lang.String DEFAULT_SERVER_GROUP

      The default server group.

      Current value: `""`.

      See Also:
        Constant Field Values

    - #### DEFAULT_PR_SINGLE_HOP_ENABLED

          static final boolean DEFAULT_PR_SINGLE_HOP_ENABLED

      The default value for whether to have single hop optimisations enabled.

      Current value: `true`.

      Since:
        GemFire 6.5
      See Also:
        Constant Field Values

    - #### DEFAULT_MULTIUSER_AUTHENTICATION

          static final boolean DEFAULT_MULTIUSER_AUTHENTICATION

      The default value for whether to use multiuser mode.

      Current value: `false`.

      Since:
        GemFire 6.5
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### setFreeConnectionTimeout

          PoolFactory setFreeConnectionTimeout(int connectionTimeout)

      Sets the free connection timeout for this pool. If the pool has a max connections setting, operations will block if all of the connections are in use. The free connection timeout specifies how long those operations will block waiting for a free connection before receiving an `AllConnectionsInUseException`. If max connections is not set this setting has no effect.
      Parameters:
        `connectionTimeout` - the connection timeout in milliseconds
      Returns:
        a reference to `this`
      Throws:
        `java.lang.IllegalArgumentException` - if `connectionTimeout` is less than or equal to `0`.
      See Also:
        `setMaxConnections(int)`

    - #### setLoadConditioningInterval

          PoolFactory setLoadConditioningInterval(int loadConditioningInterval)

      Sets the load conditioning interval for this pool. This interval controls how frequently the pool will check to see if a connection to a given server should be moved to a different server to improve the load balance.

      A value of `-1` disables load conditioning

      Parameters:
        `loadConditioningInterval` - the connection lifetime in milliseconds
      Returns:
        a reference to `this`
      Throws:
        `java.lang.IllegalArgumentException` - if `connectionLifetime` is less than `-1`.

    - #### setSocketBufferSize

          PoolFactory setSocketBufferSize(int bufferSize)

      Sets the socket buffer size for each connection made in this pool. Large messages can be received and sent faster when this buffer is larger. Larger buffers also optimize the rate at which servers can send events for client subscriptions.
      Parameters:
        `bufferSize` - the size of the socket buffers used for reading and writing on each connection in this pool.
      Returns:
        a reference to `this`
      Throws:
        `java.lang.IllegalArgumentException` - if `bufferSize` is less than or equal to `0`.

    - #### setThreadLocalConnections

          PoolFactory setThreadLocalConnections(boolean threadLocalConnections)

      Sets the thread local connections policy for this pool. If `true` then any time a thread goes to use a connection from this pool it will check a thread local cache and see if it already has a connection in it. If so it will use it. If not it will get one from this pool and cache it in the thread local. This gets rid of thread contention for the connections but increases the number of connections the servers see.

      If `false` then connections are returned to the pool as soon as the operation being done with the connection completes. This allows connections to be shared amonst multiple threads keeping the number of connections down.

      Parameters:
        `threadLocalConnections` - if `true` then enable thread local connections.
      Returns:
        a reference to `this`

    - #### setReadTimeout

          PoolFactory setReadTimeout(int timeout)

      Sets the number of milliseconds to wait for a response from a server before timing out the operation and trying another server (if any are available).
      Parameters:
        `timeout` - number of milliseconds to wait for a response from a server
      Returns:
        a reference to `this`
      Throws:
        `java.lang.IllegalArgumentException` - if `timeout` is less than `0`.

    - #### setMinConnections

          PoolFactory setMinConnections(int minConnections)

      Set the minimum number of connections to keep available at all times. When the pool is created, it will create this many connections. If `0` then connections will not be made until an actual operation is done that requires client-to-server communication.
      Parameters:
        `minConnections` - the initial number of connections this pool will create.
      Returns:
        a reference to `this`
      Throws:
        `java.lang.IllegalArgumentException` - if `minConnections` is less than `0`.

    - #### setMaxConnections

          PoolFactory setMaxConnections(int maxConnections)

      Set the max number of client to server connections that the pool will create. If all of the connections are in use, an operation requiring a client to server connection will block until a connection is available.
      Parameters:
        `maxConnections` - the maximum number of connections in the pool. this pool will create. -1 indicates that there is no maximum number of connections
      Returns:
        a reference to `this`
      Throws:
        `java.lang.IllegalArgumentException` - if `maxConnections` is less than `minConnections`.
      See Also:
        `setFreeConnectionTimeout(int)`

    - #### setIdleTimeout

          PoolFactory setIdleTimeout(long idleTimeout)

      Set the amount of time a connection can be idle before expiring the connection. If the pool size is greater than the minimum specified by `setMinConnections(int)`, connections which have been idle for longer than the idleTimeout will be closed.
      Parameters:
        `idleTimeout` - The amount of time in milliseconds that an idle connection should live before expiring. -1 indicates that connections should never expire.
      Returns:
        a reference to `this`
      Throws:
        `java.lang.IllegalArgumentException` - if `idleTimout` is less than `-1`.

    - #### setRetryAttempts

          PoolFactory setRetryAttempts(int retryAttempts)

      Set the number of times to retry a request after timeout/exception.
      Parameters:
        `retryAttempts` - The number of times to retry a request after timeout/exception. -1 indicates that a request should be tried against every available server before failing
      Returns:
        a reference to `this`
      Throws:
        `java.lang.IllegalArgumentException` - if `retryAttempts` is less than `-1`.

    - #### setPingInterval

          PoolFactory setPingInterval(long pingInterval)

      How often to ping servers to verify that they are still alive. Each server will be sent a ping every pingInterval if there has not been any other communication with the server. These pings are used by the server to monitor the health of the client. Make sure that the pingInterval is less than the maximum time between pings allowed by the cache server.
      Parameters:
        `pingInterval` - The amount of time in milliseconds between pings.
      Returns:
        a reference to `this`
      Throws:
        `java.lang.IllegalArgumentException` - if `pingInterval` is less than or equal to `0`.
      See Also:
        `CacheServer.setMaximumTimeBetweenPings(int)`

    - #### setStatisticInterval

          PoolFactory setStatisticInterval(int statisticInterval)

      How often to send client statistics to the server. Doing this allows `gfmon` to monitor clients.

      A value of `-1` disables the sending of client statistics to the server.

      Parameters:
        `statisticInterval` - The amount of time in milliseconds between sends of client statistics to the server.
      Returns:
        a reference to `this`
      Throws:
        `java.lang.IllegalArgumentException` - if `statisticInterval` is less than `-1`.

    - #### setServerGroup

          PoolFactory setServerGroup(java.lang.String group)

      Configures the group that all servers this pool connects to must belong to.
      Parameters:
        `group` - the server group that this pool will connect to. If `null` or `""` then all servers will be connected to.
      Returns:
        a reference to `this`

    - #### addLocator

          PoolFactory addLocator(java.lang.String host,
                                 int port)

      Add a locator, given its host and port, to this factory. The locator must be a server locator and will be used to discover other running cache servers and locators. Note that if the host is unknown at the time of this call the locator will still be added. When the pool is used for an operation if the host is still unknown an exception will be thrown.
      Parameters:
        `host` - the host name or ip address that the locator is listening on.
        `port` - the port that the locator is listening on
      Returns:
        a reference to `this`
      Throws:
        `java.lang.IllegalArgumentException` - if port is outside the valid range of [0..65535] inclusive.
        `java.lang.IllegalStateException` - if a server has already been `added` to this factory.

    - #### addServer

          PoolFactory addServer(java.lang.String host,
                                int port)

      Add a server, given its host and port, to this factory. The server must be a cache server and this client will directly connect to without consulting a server locator. Note that if the host is unknown at the time of this call the server will still be added. When the pool is used for an operation if the host is still unknown an exception will be thrown.
      Parameters:
        `host` - the host name or ip address that the server is listening on.
        `port` - the port that the server is listening on
      Returns:
        a reference to `this`
      Throws:
        `java.lang.IllegalArgumentException` - if port is outside the valid range of [0..65535] inclusive.
        `java.lang.IllegalStateException` - if a locator has already been `added` to this factory.

    - #### setSubscriptionEnabled

          PoolFactory setSubscriptionEnabled(boolean enabled)

      If set to `true` then the created pool will have server-to-client subscriptions enabled. If set to `false` then all `Subscription*` attributes are ignored at create time.
      Returns:
        a reference to `this`

    - #### setSubscriptionRedundancy

          PoolFactory setSubscriptionRedundancy(int redundancy)

      Sets the redundancy level for this pools server-to-client subscriptions. If `0` then no redundant copies will be kept on the servers. Otherwise an effort will be made to maintain the requested number of copies of the server-to-client subscriptions. At most one copy per server will be made up to the requested level.
      Parameters:
        `redundancy` - the number of redundant servers for this client's subscriptions.
      Returns:
        a reference to `this`
      Throws:
        `java.lang.IllegalArgumentException` - if `redundancyLevel` is less than `-1`.

    - #### setSubscriptionMessageTrackingTimeout

          PoolFactory setSubscriptionMessageTrackingTimeout(int messageTrackingTimeout)

      Sets the messageTrackingTimeout attribute which is the time-to-live period, in milliseconds, for subscription events the client has received from the server. It's used to minimize duplicate events. Entries that have not been modified for this amount of time are expired from the list
      Parameters:
        `messageTrackingTimeout` - number of milliseconds to set the timeout to.
      Returns:
        a reference to `this`
      Throws:
        `java.lang.IllegalArgumentException` - if `messageTrackingTimeout` is less than or equal to `0`.

    - #### setSubscriptionAckInterval

          PoolFactory setSubscriptionAckInterval(int ackInterval)

      Sets the interval in milliseconds to wait before sending acknowledgements to the cache server for events received from the server subscriptions.
      Parameters:
        `ackInterval` - number of milliseconds to wait before sending event acknowledgements.
      Returns:
        a reference to `this`
      Throws:
        `java.lang.IllegalArgumentException` - if `ackInterval` is less than or equal to `0`.

    - #### reset

          PoolFactory reset()

      Resets the configuration of this factory to its defaults.
      Returns:
        a reference to `this`

    - #### create

          Pool create(java.lang.String name)

      Create a new Pool for connecting a client to a set of GemFire Cache Servers. using this factory's settings for attributes.
      Parameters:
        `name` - the name of the pool, used when connecting regions to it
      Returns:
        the newly created pool.
      Throws:
        `java.lang.IllegalStateException` - if a pool with `name` already exists
        `java.lang.IllegalStateException` - if a locator or server has not been added.

    - #### setPRSingleHopEnabled

          PoolFactory setPRSingleHopEnabled(boolean enabled)

      By default setPRSingleHopEnabled is `true` in which case the client is aware of the location of partitions on servers hosting `regions` with `DataPolicy.PARTITION`. Using this information, the client routes the client cache operations directly to the server which is hosting the required partition for the cache operation using a single network hop. This mode works best when `setMaxConnections(int)` is set to `-1` which is the default. This mode causes the client to have more connections to the servers.

      If setPRSingleHopEnabled is `false` the client may need to do an extra network hop on servers to go to the required partition for that cache operation. The client will use fewer network connections to the servers.

      Caution: for `partition` regions with `local-max-memory` equal to zero, no cache operations mentioned above will be routed to those servers as they do not host any partitions.

      Returns:
        a reference to `this`
      Since:
        GemFire 6.5

    - #### setMultiuserAuthentication

          PoolFactory setMultiuserAuthentication(boolean enabled)

      If set to `true` then the created pool can be used by multiple authenticated users.
      This setting should only be used for applications that require the client to authenticate itself with the server multiple users.
      Note: If set to true, all the client side regions must have their data-policy set to empty.
      Returns:
        a reference to `this`
      Since:
        GemFire 6.5
      See Also:
        `ClientCache.createAuthenticatedView(java.util.Properties)`