com.verisign.epp.pool

## Class EPPSessionPool

- java.lang.Object
- - com.verisign.epp.pool.EPPSessionPool

-     public class EPPSessionPool
      extends java.lang.Object

  Singleton EPP session pool that will handle creating sessions dynamically, expiring session after an absolute timeout, keeping sessions alive based on an idle timeout, and dynamically grows and shrinks the pool based on configurable settings. One of the `init` methods must be called before useing the pool. The `init()` method uses configuration settings defined in the `Environment` class. The `Environment` settings include the following:
  - EPP.SessionPool.poolableClassName - (required) EPPSessionPoolableFactory class used by the pool.
  - EPP.SessionPool.clientId - (required) Login name
  - EPP.SessionPool.password - (required) password
  - EPP.SessionPool.absoluteTimeout - (optional) Session absolute timeout. Default is 24 hours
  - EPP.SessionPool.idleTimeout - (optional) Session idle timeout used to determine when keep alive messages are sent. Default is 10 minutes.
  - EPP.SessionPool.maxIdle - (optional) Maximum number of idle sessions in pool. Default is 10.
  - EPP.SessionPool.maxActive - (optional) Maximum number of active sessions in pool. Default is 10.
  - EPP.SessionPool.initMaxActive - (optional) Boolean value indicating if the `maxActive` sessions should be pre-initialized at initialization in the `init()` method. Default is `false`.
  - EPP.SessionPool.maxWait - (optional) Maximum time in milliseconds for a client to block waiting for a pooled session. Default is 60 seconds.
  - EPP.SessionPool.minIdle - (optional) Minimum number of idle sessions in the pool. Default is 0.
  - EPP.SessionPool.timeBetweenEvictionRunsMillis - (optional) Frequency in milliseconds of scanning the pool for idle and absolute timeout sessions. Default is 60 seconds.
  - EPP.SessionPool.borrowRetries - (optional) Number of retries to get/create a session when calling `borrowObject()`. Default is `0`.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `DEFAULT` Name of the default system session pool, which uses the `borrowObject()`, `returnObject(EPPSession)`, and `invalidateObject(EPPSession)`.
    `static long` | `DEFAULT_ABSOLUTE_TIMEOUT` The default session absolute timeout.
    `static long` | `DEFAULT_IDLE_TIMEOUT` The default session absolute timeout.
    `static int` | `DEFAULT_MAX_ACTIVE` The default cap on the total number of active instances from the pool.
    `static int` | `DEFAULT_MAX_IDLE` The default cap on the number of "sleeping" instances in the pool.
    `static long` | `DEFAULT_MAX_WAIT` The default maximum amount of time (in millis) the `borrowObject()` method should block before throwing an exception.
    `static int` | `DEFAULT_MIN_IDLE` The default minimum number of "sleeping" instances in the pool before before the evictor thread (if active) spawns new objects.
    `static long` | `DEFAULT_TIME_BETWEEN_EVICTION_RUNS_MILLIS` The default "time between eviction runs" value.
    `protected static EPPSessionPool` | `instance` Singleton instance

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `EPPSessionPool()` Default constructor as part of the Singleton Design Pattern.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `EPPSession` | `borrowObject()` Borrows a session from the pool.
    `EPPSession` | `borrowObject(java.lang.String aSystem)` Borrows a session from the pool.
    `void` | `close()` Closes the session pool(s) contained in `EPPSessionPool` cleanly.
    `long` | `getAbsoluteTimeout()` Gets the session absolute timeout.
    `java.lang.String` | `getClientHost()` Gets the TCP server IP address or host name to connect from.
    `java.lang.String` | `getClientId()` Gets the client identifier used to authenticate.
    `org.apache.commons.pool.impl.GenericObjectPool.Config` | `getConfig()` Gets the configuration for the `GenericObjectPool`.
    `EPPSessionPoolableFactory` | `getFactory()` Gets the factory associated with the pool.
    `org.apache.commons.pool.impl.GenericObjectPool` | `getGenericObjectPool()` Gets the contained `GenericObjectPool`.
    `org.apache.commons.pool.impl.GenericObjectPool` | `getGenericObjectPool(java.lang.String aSystem)` Gets the contained `GenericObjectPool` for a system.
    `long` | `getIdleTimeout()` Gets the session idle timeout.
    `static EPPSessionPool` | `getInstance()` Gets the Singleton Design Pattern instance.
    `java.lang.String` | `getPassword()` Gets the password used for authentication.
    `java.lang.String` | `getServerName()` Gets the TCP server IP address or host name, or the URL of the HTTP server.
    `java.lang.Integer` | `getServerPort()` Gets the TCP server port number.
    `EPPSystemSessionPool` | `getSystemSessionPool(java.lang.String aSystem)` Gets the contained `EPPSystemSessionPool` for a system.
    `boolean` | `hasSystemSessionPool(java.lang.String aSystem)` Does the system session pool exist?
    `void` | `init()`
    `void` | `init(EPPSessionPoolableFactory aFactory, org.apache.commons.pool.impl.GenericObjectPool.Config aConfig)` Initialize the pool with a specific `EPPSessionPoolableFactory` and `GenericObjectPool.Config` setting.
    `void` | `invalidateObject(EPPSession aSession)` Remove a borrowed session from the pool based on a known issue with it.
    `void` | `invalidateObject(java.lang.String aSystem, EPPSession aSession)` Remove a borrowed session from the system session pool based on a known issue with it.
    `void` | `returnObject(EPPSession aSession)` Returned a borrowed session to the pool.
    `void` | `returnObject(java.lang.String aSystem, EPPSession aSession)` Returned a borrowed session to a system session pool.
    `void` | `setClientHost(java.lang.String aClientHost)` Sets the TCP server IP address or host name to connect from.
    `void` | `setServerName(java.lang.String aServerName)` Sets the TCP server IP address or host name or the URL of the HTTP server.
    `void` | `setServerPort(java.lang.Integer aServerPort)` Sets the TCP server port number.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### DEFAULT_ABSOLUTE_TIMEOUT

          public static final long DEFAULT_ABSOLUTE_TIMEOUT

      The default session absolute timeout.
      See Also:
        Constant Field Values

    - #### DEFAULT_IDLE_TIMEOUT

          public static final long DEFAULT_IDLE_TIMEOUT

      The default session absolute timeout.
      See Also:
        Constant Field Values

    - #### DEFAULT_MAX_WAIT

          public static final long DEFAULT_MAX_WAIT

      The default maximum amount of time (in millis) the `borrowObject()` method should block before throwing an exception.
      See Also:
        Constant Field Values

    - #### DEFAULT_TIME_BETWEEN_EVICTION_RUNS_MILLIS

          public static final long DEFAULT_TIME_BETWEEN_EVICTION_RUNS_MILLIS

      The default "time between eviction runs" value.
      See Also:
        Constant Field Values

    - #### DEFAULT_MAX_IDLE

          public static final int DEFAULT_MAX_IDLE

      The default cap on the number of "sleeping" instances in the pool.
      See Also:
        Constant Field Values

    - #### DEFAULT_MAX_ACTIVE

          public static final int DEFAULT_MAX_ACTIVE

      The default cap on the total number of active instances from the pool.
      See Also:
        Constant Field Values

    - #### DEFAULT_MIN_IDLE

          public static final int DEFAULT_MIN_IDLE

      The default minimum number of "sleeping" instances in the pool before before the evictor thread (if active) spawns new objects.
      See Also:
        Constant Field Values

    - #### instance

          protected static EPPSessionPool instance

      Singleton instance

    - #### DEFAULT

          public static final java.lang.String DEFAULT

      Name of the default system session pool, which uses the `borrowObject()`, `returnObject(EPPSession)`, and `invalidateObject(EPPSession)`.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### EPPSessionPool

          protected EPPSessionPool()

      Default constructor as part of the Singleton Design Pattern.

  - ### Method Detail

    - #### getInstance

          public static EPPSessionPool getInstance()

      Gets the Singleton Design Pattern instance. Ensure the `init()` is called at least once.
      Returns:
        Singleton instance of `EPPSessionPool`.

    - #### init

          public void init(EPPSessionPoolableFactory aFactory,
                           org.apache.commons.pool.impl.GenericObjectPool.Config aConfig)

      Initialize the pool with a specific `EPPSessionPoolableFactory` and `GenericObjectPool.Config` setting.
      Parameters:
        `aFactory` - EPP session poolable object factory
        `aConfig` - Configuration attributes for pool

    - #### init

          public void init()
                    throws EPPSessionPoolException

      Throws:
        `EPPSessionPoolException`

    - #### close

          public void close()

      Closes the session pool(s) contained in `EPPSessionPool` cleanly. Cleanly closing the session pools means clearing the pools that will execute an EPP logout for each of the idle sessions and close the pool.

    - #### borrowObject

          public EPPSession borrowObject()
                                  throws EPPSessionPoolException

      Borrows a session from the pool. The session must be returned by either calling `invalidateObject(com.verisign.epp.interfaces.EPPSession)` or `returnObject(com.verisign.epp.interfaces.EPPSession)`. This method will block if there are no idle sessions in the pool for `maxWait` time.
      Returns:
        Borrowed `EPPSession` instance.
      Throws:
        `EPPSessionPoolException` - On error

    - #### borrowObject

          public EPPSession borrowObject(java.lang.String aSystem)
                                  throws EPPSessionPoolException

      Borrows a session from the pool. The session must be returned by either calling `invalidateObject(com.verisign.epp.interfaces.EPPSession)` or `returnObject(com.verisign.epp.interfaces.EPPSession)`. This method will block if there are no idle sessions in the pool for `maxWait` time.
      Parameters:
        `aSystem` - the system name
      Returns:
        Borrowed `EPPSession` instance.
      Throws:
        `EPPSessionPoolException` - On error

    - #### invalidateObject

          public void invalidateObject(EPPSession aSession)
                                throws EPPSessionPoolException

      Remove a borrowed session from the pool based on a known issue with it. The should be done if an unexpected exception occurs with the session which might be due to the server being down or the session being expired.
      Parameters:
        `aSession` - Session that is invalid
      Throws:
        `EPPSessionPoolException` - On error

    - #### invalidateObject

          public void invalidateObject(java.lang.String aSystem,
                                       EPPSession aSession)
                                throws EPPSessionPoolException

      Remove a borrowed session from the system session pool based on a known issue with it. The should be done if an unexpected exception occurs with the session which might be due to the server being down or the session being expired.
      Parameters:
        `aSystem` - the system name
        `aSession` - Session that is invalid
      Throws:
        `EPPSessionPoolException` - On error

    - #### returnObject

          public void returnObject(EPPSession aSession)
                            throws EPPSessionPoolException

      Returned a borrowed session to the pool. This session must have been returned from a call to `borrowObject()`.
      Parameters:
        `aSession` - Session to return
      Throws:
        `EPPSessionPoolException` - On error

    - #### returnObject

          public void returnObject(java.lang.String aSystem,
                                   EPPSession aSession)
                            throws EPPSessionPoolException

      Returned a borrowed session to a system session pool. This session must have been returned from a call to `borrowObject(String)`.
      Parameters:
        `aSystem` - the system name
        `aSession` - Session to return
      Throws:
        `EPPSessionPoolException` - On error

    - #### getGenericObjectPool

          public org.apache.commons.pool.impl.GenericObjectPool getGenericObjectPool()

      Gets the contained `GenericObjectPool`.
      Returns:
        Contained `GenericObjectPool` if defined; `null` otherwise.

    - #### hasSystemSessionPool

          public boolean hasSystemSessionPool(java.lang.String aSystem)

      Does the system session pool exist?
      Parameters:
        `aSystem` - System session pool name to find
      Returns:
        `true` if the system session pool exists; `false` otherwise.

    - #### getSystemSessionPool

          public EPPSystemSessionPool getSystemSessionPool(java.lang.String aSystem)
                                                    throws EPPSessionPoolException

      Gets the contained `EPPSystemSessionPool` for a system.
      Parameters:
        `aSystem` - System name for pool
      Returns:
        Contained `EPPSystemSessionPool`.
      Throws:
        `EPPSessionPoolException` - When system pool can not be found

    - #### getGenericObjectPool

          public org.apache.commons.pool.impl.GenericObjectPool getGenericObjectPool(java.lang.String aSystem)
                                                                              throws EPPSessionPoolException

      Gets the contained `GenericObjectPool` for a system.
      Parameters:
        `aSystem` - System name for pool
      Returns:
        Contained `GenericObjectPool`.
      Throws:
        `EPPSessionPoolException` - When system pool can not be found

    - #### getAbsoluteTimeout

          public long getAbsoluteTimeout()

      Gets the session absolute timeout.
      Returns:
        Returns the absolute timeout in milliseconds.

    - #### getClientId

          public java.lang.String getClientId()

      Gets the client identifier used to authenticate.
      Returns:
        Returns the client identifier.

    - #### getConfig

          public org.apache.commons.pool.impl.GenericObjectPool.Config getConfig()

      Gets the configuration for the `GenericObjectPool`.
      Returns:
        Returns the config.

    - #### getFactory

          public EPPSessionPoolableFactory getFactory()

      Gets the factory associated with the pool.
      Returns:
        Returns the factory.

    - #### getIdleTimeout

          public long getIdleTimeout()

      Gets the session idle timeout.
      Returns:
        Returns the idle timeout in milliseconds.

    - #### getPassword

          public java.lang.String getPassword()

      Gets the password used for authentication.
      Returns:
        Returns the password.

    - #### getServerName

          public java.lang.String getServerName()

      Gets the TCP server IP address or host name, or the URL of the HTTP server.
      Returns:
        Server host name, IP address, or URL

    - #### setServerName

          public void setServerName(java.lang.String aServerName)

      Sets the TCP server IP address or host name or the URL of the HTTP server.
      Parameters:
        `aServerName` - Server host name, IP address, or URL

    - #### getServerPort

          public java.lang.Integer getServerPort()

      Gets the TCP server port number. This will be `null` if connecting to a HTTP server.
      Returns:
        TCP server port number if defined; `null` otherwise.

    - #### setServerPort

          public void setServerPort(java.lang.Integer aServerPort)

      Sets the TCP server port number.
      Parameters:
        `aServerPort` - TCP server port number

    - #### getClientHost

          public java.lang.String getClientHost()

      Gets the TCP server IP address or host name to connect from. A `null` value will use the loop back.
      Returns:
        Client host name or IP address if defined;`null` otherwise.

    - #### setClientHost

          public void setClientHost(java.lang.String aClientHost)

      Sets the TCP server IP address or host name to connect from. A `null` value will use the loop back.
      Parameters:
        `aClientHost` - Client host name or IP address