org.apache.geode.cache.client

## Interface Pool

-     public interface Pool

  A pool for connections from a client to a set of GemFire Cache Servers.

  A single instance of this interface can be created using `ClientCacheFactory.create()`. Multiple instances may also be created using `PoolFactory.create(java.lang.String)`. A `PoolFactory` instance is created by calling `PoolManager.createFactory()`. So to create a default `Pool` do this:

       new ClientCacheFactory().create();

  or this:

       PoolManager.createFactory().create("myPool");

  Instances may also be created by declaring them in cache.xml with a `pool` element.

  Existing Pool instances can be found using `PoolManager.find(String)` and `PoolManager.getAll()`.

  The pool name must be configured on the client regions that will use this pool by calling `RegionFactory.setPoolName(java.lang.String)`.

  Since:
    GemFire 5.7

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `destroy()` Destroys this pool closing any connections it produced.
    `void` | `destroy(boolean keepAlive)` Destroys this pool closing any connections it produced.
    `int` | `getFreeConnectionTimeout()` Returns the connection timeout of this pool.
    `long` | `getIdleTimeout()` Get the maximum connections for this pool.
    `int` | `getLoadConditioningInterval()` Returns the load conditioning interval of this pool.
    `java.util.List<java.net.InetSocketAddress>` | `getLocators()` Returns an unmodifiable list of `InetSocketAddress` of the locators this pool is using.
    `int` | `getMaxConnections()` Get the maximum connections for this pool.
    `int` | `getMinConnections()` Get the minimum connections for this pool.
    `boolean` | `getMultiuserAuthentication()` Returns true if multiuser mode is enabled on this pool.
    `java.lang.String` | `getName()` Get the name of the connection pool
    `java.util.List<java.net.InetSocketAddress>` | `getOnlineLocators()` Returns an unmodifiable list of `InetSocketAddress` of the locators this pool is using.
    `int` | `getPendingEventCount()` Returns the approximate number of pending subscription events maintained at server for this durable client pool at the time it (re)connected to the server.
    `long` | `getPingInterval()` Get the ping interval for this pool.
    `boolean` | `getPRSingleHopEnabled()` Returns true if single-hop optimisation is enabled on this pool.
    `QueryService` | `getQueryService()` Returns the QueryService for this Pool.
    `int` | `getReadTimeout()` Returns the read timeout of this pool.
    `int` | `getRetryAttempts()` Get the retry attempts for this pool.
    `java.lang.String` | `getServerGroup()` Returns the server group of this pool.
    `java.util.List<java.net.InetSocketAddress>` | `getServers()` Returns an unmodifiable list of `InetSocketAddress` of the servers this pool is using.
    `int` | `getSocketBufferSize()` Returns the socket buffer size of this pool.
    `int` | `getSocketConnectTimeout()` Returns the socket connect timeout of this pool.
    `int` | `getStatisticInterval()` Get the statistic interval for this pool.
    `int` | `getSubscriptionAckInterval()` Returns the subscription ack interval of this pool.
    `boolean` | `getSubscriptionEnabled()` Returns the true if a server-to-client subscriptions are enabled on this pool.
    `int` | `getSubscriptionMessageTrackingTimeout()` Returns the subscription message tracking timeout of this pool.
    `int` | `getSubscriptionRedundancy()` Returns the subscription redundancy level of this pool.
    `int` | `getSubscriptionTimeoutMultiplier()` A server has an inactivity monitor that ensures a message is sent to a client at least once a minute (60,000 milliseconds).
    `boolean` | `getThreadLocalConnections()` Returns `true` if thread local connections are enabled on this pool.
    `boolean` | `isDestroyed()` Indicates whether this Pool has been destroyed.
    `void` | `releaseThreadLocalConnection()` If this pool was configured to to use thread local connections, then this method will release the connection cached for the calling thread.

- - ### Method Detail

    - #### getName

          java.lang.String getName()

      Get the name of the connection pool
      Returns:
        the name of the pool
      See Also:
        `PoolFactory.create(java.lang.String)`

    - #### getSocketConnectTimeout

          int getSocketConnectTimeout()

      Returns the socket connect timeout of this pool.
      See Also:
        `PoolFactory.setSocketConnectTimeout(int)`

    - #### getFreeConnectionTimeout

          int getFreeConnectionTimeout()

      Returns the connection timeout of this pool.
      See Also:
        `PoolFactory.setFreeConnectionTimeout(int)`

    - #### getLoadConditioningInterval

          int getLoadConditioningInterval()

      Returns the load conditioning interval of this pool.
      See Also:
        `PoolFactory.setLoadConditioningInterval(int)`

    - #### getSocketBufferSize

          int getSocketBufferSize()

      Returns the socket buffer size of this pool.
      See Also:
        `PoolFactory.setSocketBufferSize(int)`

    - #### getReadTimeout

          int getReadTimeout()

      Returns the read timeout of this pool.
      See Also:
        `PoolFactory.setReadTimeout(int)`

    - #### getMinConnections

          int getMinConnections()

      Get the minimum connections for this pool.
      See Also:
        `PoolFactory.setMinConnections(int)`

    - #### getMaxConnections

          int getMaxConnections()

      Get the maximum connections for this pool.
      See Also:
        `PoolFactory.setMaxConnections(int)`

    - #### getIdleTimeout

          long getIdleTimeout()

      Get the maximum connections for this pool.
      See Also:
        `PoolFactory.setIdleTimeout(long)`

    - #### getPingInterval

          long getPingInterval()

      Get the ping interval for this pool.
      See Also:
        `PoolFactory.setPingInterval(long)`

    - #### getStatisticInterval

          int getStatisticInterval()

      Get the statistic interval for this pool.
      See Also:
        `PoolFactory.setStatisticInterval(int)`

    - #### getRetryAttempts

          int getRetryAttempts()

      Get the retry attempts for this pool.
      See Also:
        `PoolFactory.setRetryAttempts(int)`

    - #### getThreadLocalConnections

          boolean getThreadLocalConnections()

      Returns `true` if thread local connections are enabled on this pool.
      See Also:
        `PoolFactory.setThreadLocalConnections(boolean)`

    - #### getSubscriptionEnabled

          boolean getSubscriptionEnabled()

      Returns the true if a server-to-client subscriptions are enabled on this pool.
      See Also:
        `PoolFactory.setSubscriptionEnabled(boolean)`

    - #### getPRSingleHopEnabled

          boolean getPRSingleHopEnabled()

      Returns true if single-hop optimisation is enabled on this pool.
      Since:
        GemFire 6.5
      See Also:
        `PoolFactory.setPRSingleHopEnabled(boolean)`

    - #### getSubscriptionRedundancy

          int getSubscriptionRedundancy()

      Returns the subscription redundancy level of this pool.
      See Also:
        `PoolFactory.setSubscriptionRedundancy(int)`

    - #### getSubscriptionMessageTrackingTimeout

          int getSubscriptionMessageTrackingTimeout()

      Returns the subscription message tracking timeout of this pool.
      See Also:
        `PoolFactory.setSubscriptionMessageTrackingTimeout(int)`

    - #### getSubscriptionAckInterval

          int getSubscriptionAckInterval()

      Returns the subscription ack interval of this pool.
      See Also:
        `PoolFactory.setSubscriptionAckInterval(int)`

    - #### getServerGroup

          java.lang.String getServerGroup()

      Returns the server group of this pool.
      See Also:
        `PoolFactory.setServerGroup(java.lang.String)`

    - #### getMultiuserAuthentication

          boolean getMultiuserAuthentication()

      Returns true if multiuser mode is enabled on this pool.
      Since:
        GemFire 6.5
      See Also:
        `PoolFactory.setMultiuserAuthentication(boolean)`

    - #### getLocators

          java.util.List<java.net.InetSocketAddress> getLocators()

      Returns an unmodifiable list of `InetSocketAddress` of the locators this pool is using. Each locator is either one `added explicitly` when the pool was created.

      If a pool has no locators then it can not discover servers or locators at runtime.

    - #### getOnlineLocators

          java.util.List<java.net.InetSocketAddress> getOnlineLocators()

      Returns an unmodifiable list of `InetSocketAddress` of the locators this pool is using. The returned locator is only the currently living locator found based on the periodic locator list request.

      The returned locator list may be slightly old information. If the locator does not exist, an empty list is returned.

    - #### getServers

          java.util.List<java.net.InetSocketAddress> getServers()

      Returns an unmodifiable list of `InetSocketAddress` of the servers this pool is using. These servers where either `added explicitly` when the pool was created or were discovered using this pools `locators`.

    - #### destroy

          void destroy(boolean keepAlive)

      Destroys this pool closing any connections it produced.
      Parameters:
        `keepAlive` - whether the server should keep the durable client's subscriptions alive for the timeout period
      Throws:
        `java.lang.IllegalStateException` - if the pool is still in use

    - #### destroy

          void destroy()

      Destroys this pool closing any connections it produced.
      Throws:
        `java.lang.IllegalStateException` - if the pool is still in use

    - #### isDestroyed

          boolean isDestroyed()

      Indicates whether this Pool has been destroyed.
      Returns:
        true if the pool has been destroyed

    - #### releaseThreadLocalConnection

          void releaseThreadLocalConnection()

      If this pool was configured to to use thread local connections, then this method will release the connection cached for the calling thread. The connection will then be available for use by other threads. If this pool is not using thread local connections, this method will have no effect.

    - #### getQueryService

          QueryService getQueryService()

      Returns the QueryService for this Pool. The query operations performed using this QueryService will be executed on the servers that are associated with this pool.
      Returns:
        the QueryService

    - #### getPendingEventCount

          int getPendingEventCount()

      Returns the approximate number of pending subscription events maintained at server for this durable client pool at the time it (re)connected to the server. Server would start dispatching these events to this durable client pool when it receives `ClientCache.readyForEvents()` from it.

      Durable clients can call this method on reconnect to assess the amount of 'stale' data i.e. events accumulated at server while this client was away and, importantly, before calling `ClientCache.readyForEvents()`.

      Any number of invocations of this method during a single session will return the same value.

      It may return a zero value if there are no events pending at server for this client pool. A negative value returned tells us that no queue was available at server for this client pool.

      A value -1 indicates that this client pool reconnected to server after its 'durable-client-timeout' period elapsed and hence its subscription queue at server was removed, possibly causing data loss.

      A value -2 indicates that this client pool connected to server for the first time.

      Returns:
        int The number of subscription events maintained at server for this durable client pool at the time this pool (re)connected. A negative value indicates no queue was found for this client pool.
      Throws:
        `java.lang.IllegalStateException` - If called by a non-durable client or if invoked any time after invocation of `ClientCache.readyForEvents()`.
      Since:
        GemFire 8.1

    - #### getSubscriptionTimeoutMultiplier

          int getSubscriptionTimeoutMultiplier()

      A server has an inactivity monitor that ensures a message is sent to a client at least once a minute (60,000 milliseconds). If a subscription timeout multipler is set in the client it enables timing out of the subscription feed with failover to another server.
      Returns:
        The timeout multiplier
      See Also:
        `PoolFactory.setSubscriptionTimeoutMultiplier(int)`