Pool (Apache Geode 2.0.2)
Description: declaration: package: org.apache.geode.cache.client, interface: Pool

Package 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

  Modifier and Type
  Method
  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 idle timeout for this pool.
  `int`
  `getLoadConditioningInterval()`
  Returns the load conditioning interval of this pool.
  `List<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.
  `String`
  `getName()`
  Get the name of the connection pool
  `List<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.
  `int`
  `getServerConnectionTimeout()`
  Returns the server connection timeout of this pool.
  `String`
  `getServerGroup()`
  Returns the server group of this pool.
  `List<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.
  `SocketFactory`
  `getSocketFactory()`
  The socket factory used by this pool to create socket connections to servers and locators.
  `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 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).
  `default boolean`
  `getThreadLocalConnections()`
  Deprecated.
  Since Geode 1.10.0.
  `boolean`
  `isDestroyed()`
  Indicates whether this Pool has been destroyed.
  `default void`
  `releaseThreadLocalConnection()`
  Deprecated.
  Since Geode 1.10.0.

- ## Method Details

  - ### getName

    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.
    Returns:
      the socket connect timeout of this pool
    See Also:
      - `PoolFactory.setSocketConnectTimeout(int)`

  - ### getFreeConnectionTimeout

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

  - ### getServerConnectionTimeout

    int getServerConnectionTimeout()
    Returns the server connection timeout of this pool.
    Returns:
      the server connection timeout of this pool
    See Also:
      - `PoolFactory.setServerConnectionTimeout(int)`

  - ### getLoadConditioningInterval

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

  - ### getSocketBufferSize

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

  - ### getReadTimeout

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

  - ### getMinConnections

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

  - ### getMaxConnections

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

  - ### getIdleTimeout

    long getIdleTimeout()
    Get the idle timeout for this pool.
    Returns:
      the idle timeout for this pool
    See Also:
      - `PoolFactory.setIdleTimeout(long)`

  - ### getPingInterval

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

  - ### getStatisticInterval

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

  - ### getRetryAttempts

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

  - ### getThreadLocalConnections

    @Deprecated default boolean getThreadLocalConnections()
    Deprecated.
    Since Geode 1.10.0. Thread local connections are ignored. Will be removed in future major release. Now always returns false.
    Returns `true` if thread local connections are enabled on this pool.
    Returns:
      whether thread local connections are enabled on this pool
    See Also:
      - `PoolFactory.setThreadLocalConnections(boolean)`

  - ### getSubscriptionEnabled

    boolean getSubscriptionEnabled()
    Returns the true if server-to-client subscriptions are enabled on this pool.
    Returns:
      whether 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.
    Returns:
      whether 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.
    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.
    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.
    Returns:
      the subscription ack interval of this pool
    See Also:
      - `PoolFactory.setSubscriptionAckInterval(int)`

  - ### getServerGroup

    String getServerGroup()
    Returns the server group of this pool.
    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.
    Returns:
      whether multiuser mode is enabled on this pool
    Since:
      GemFire 6.5
    See Also:
      - `PoolFactory.setMultiuserAuthentication(boolean)`

  - ### getLocators

    List<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.

    Returns:
      an unmodifiable list of `InetSocketAddress` of the locators this pool is using

  - ### getOnlineLocators

    List<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.

    Returns:
      an unmodifiable list of `InetSocketAddress` of the locators this pool is using

  - ### getServers

    List<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`.
    Returns:
      an unmodifiable list of `InetSocketAddress` of the servers this pool is using

  - ### 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:
      `IllegalStateException` - if the pool is still in use

  - ### destroy

    void destroy()
    Destroys this pool closing any connections it produced.
    Throws:
      `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

    @Deprecated default void releaseThreadLocalConnection()
    Deprecated.
    Since Geode 1.10.0. Thread local connections are ignored. Will be removed in future major release.
    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:
      `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)`

  - ### getSocketFactory

    SocketFactory getSocketFactory()
    The socket factory used by this pool to create socket connections to servers and locators.
    Returns:
      the socket factory used by this pool to create socket connections to servers and locators
    See Also:
      - `PoolFactory.setSocketFactory(SocketFactory)`