org.springframework.ldap.pool2.factory

## Class PooledContextSource

- java.lang.Object
- - org.springframework.ldap.core.support.DelegatingBaseLdapPathContextSourceSupport
  - - org.springframework.ldap.pool2.factory.PooledContextSource

- All Implemented Interfaces:
    DisposableBean, ContextSource, BaseLdapPathSource
  Direct Known Subclasses:
    MutablePooledContextSource

      public class PooledContextSource
      extends DelegatingBaseLdapPathContextSourceSupport
      implements ContextSource, DisposableBean

  A `ContextSource` implementation that wraps an object pool and another `ContextSource`. `DirContext`s are retrieved from the pool which maintains them. NOTE: This implementation is based on apache commons-pool2.
  Configuration:

  Property | Description | Required | Default
  --- | --- | --- | ---
  contextSource | The `ContextSource` to get `DirContext`s from for adding to the pool. | Yes | null
  dirContextValidator | The `DirContextValidator` to use for validating `DirContext`s. Required if any of the test/validate options are enabled. | No | null
  poolConfig | The `PoolConfig` to configure the pool. | No | null

  Since:
    2.0
  Author:
    Eric Dalquist, Anindya Chatterjee

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected GenericKeyedObjectPool<Object,Object>` | `keyedObjectPool`
    `protected org.slf4j.Logger` | `logger` The logger for this class and sub-classes

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `PooledContextSource(PoolConfig poolConfig)` Creates a new pooling context source, setting up the DirContext object factory and generic keyed object pool.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `destroy()`
    `protected DirContext` | `getContext(DirContextType dirContextType)` Gets a DirContext of the specified type from the keyed object pool.
    `DirContext` | `getContext(String principal, String credentials)` Gets a `DirContext` instance authenticated using the supplied principal and credentials.
    `ContextSource` | `getContextSource()`
    `DirContextValidator` | `getDirContextValidator()`
    `int` | `getNumActive()`
    `int` | `getNumActiveRead()`
    `int` | `getNumActiveWrite()`
    `int` | `getNumIdle()`
    `int` | `getNumIdleRead()`
    `int` | `getNumIdleWrite()`
    `int` | `getNumWaiters()`
    `PoolConfig` | `getPoolConfig()`
    `DirContext` | `getReadOnlyContext()` Gets a read-only `DirContext`.
    `DirContext` | `getReadWriteContext()` Gets a read-write `DirContext` instance.
    `protected ContextSource` | `getTarget()` Get the target ContextSource.
    `void` | `setContextSource(ContextSource contextSource)`
    `void` | `setDirContextValidator(DirContextValidator dirContextValidator)`
    `void` | `setNonTransientExceptions(Collection<Class<? extends Throwable>> nonTransientExceptions)` Configure the exception classes that are to be interpreted as no-transient with regards to eager context invalidation.

    - ### Methods inherited from class org.springframework.ldap.core.support.DelegatingBaseLdapPathContextSourceSupport

      `getBaseLdapName, getBaseLdapPath, getBaseLdapPathAsString`

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

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

- - ### Field Detail

    - #### logger

          protected final org.slf4j.Logger logger

      The logger for this class and sub-classes

    - #### keyedObjectPool

          protected final GenericKeyedObjectPool<Object,Object> keyedObjectPool

  - ### Constructor Detail

    - #### PooledContextSource

          public PooledContextSource(PoolConfig poolConfig)

      Creates a new pooling context source, setting up the DirContext object factory and generic keyed object pool.

  - ### Method Detail

    - #### getPoolConfig

          public PoolConfig getPoolConfig()

      Returns:
        the poolConfig

    - #### getNumIdle

          public int getNumIdle()

      See Also:
        `GenericKeyedObjectPool.getNumIdle()`

    - #### getNumIdleRead

          public int getNumIdleRead()

      See Also:
        `GenericKeyedObjectPool.getNumIdle(Object)`

    - #### getNumIdleWrite

          public int getNumIdleWrite()

      See Also:
        `GenericKeyedObjectPool.getNumIdle(Object)`

    - #### getNumActive

          public int getNumActive()

      See Also:
        `GenericKeyedObjectPool.getNumActive()`

    - #### getNumActiveRead

          public int getNumActiveRead()

      See Also:
        `GenericKeyedObjectPool.getNumActive(Object)`

    - #### getNumActiveWrite

          public int getNumActiveWrite()

      See Also:
        `GenericKeyedObjectPool.getNumActive(Object)`

    - #### getNumWaiters

          public int getNumWaiters()

      See Also:
        `GenericKeyedObjectPool.getNumWaiters()`

    - #### getContextSource

          public ContextSource getContextSource()

      Returns:
        the contextSource

    - #### getDirContextValidator

          public DirContextValidator getDirContextValidator()

      Returns:
        the dirContextValidator

    - #### setContextSource

          public void setContextSource(ContextSource contextSource)

      Parameters:
        `contextSource` - the contextSource to set Required

    - #### setDirContextValidator

          public void setDirContextValidator(DirContextValidator dirContextValidator)

      Parameters:
        `dirContextValidator` - the dirContextValidator to set Required

    - #### setNonTransientExceptions

          public void setNonTransientExceptions(Collection<Class<? extends Throwable>> nonTransientExceptions)

      Configure the exception classes that are to be interpreted as no-transient with regards to eager context invalidation. If one of the configured exceptions (or subclasses of them) is thrown by any method on a pooled DirContext, that instance will immediately be marked as invalid without any additional testing (i.e. testOnReturn). This allows for more efficient management of dead connections. Default is `CommunicationException`.
      Parameters:
        `nonTransientExceptions` - the exception classes that should be interpreted as non-transient with regards to eager invalidation.
      Since:
        2.0

    - #### destroy

          public void destroy()
                       throws Exception

      Specified by:
        `destroy` in interface `DisposableBean`
      Throws:
        `Exception`

    - #### getTarget

          protected ContextSource getTarget()

      Description copied from class: `DelegatingBaseLdapPathContextSourceSupport`
      Get the target ContextSource.
      Specified by:
        `getTarget` in class `DelegatingBaseLdapPathContextSourceSupport`
      Returns:
        the target ContextSource.

    - #### getReadOnlyContext

          public DirContext getReadOnlyContext()

      Description copied from interface: `ContextSource`
      Gets a read-only `DirContext`. The returned `DirContext` must be possible to perform read-only operations on.
      Specified by:
        `getReadOnlyContext` in interface `ContextSource`
      Returns:
        A DirContext instance, never null.

    - #### getReadWriteContext

          public DirContext getReadWriteContext()

      Description copied from interface: `ContextSource`
      Gets a read-write `DirContext` instance.
      Specified by:
        `getReadWriteContext` in interface `ContextSource`
      Returns:
        A `DirContext` instance, never `null`.

    - #### getContext

          protected DirContext getContext(DirContextType dirContextType)

      Gets a DirContext of the specified type from the keyed object pool.
      Parameters:
        `dirContextType` - The type of context to return.
      Returns:
        A wrapped DirContext of the specified type.
      Throws:
        `DataAccessResourceFailureException` - If retrieving the object from the pool throws an exception

    - #### getContext

          public DirContext getContext(String principal,
                                       String credentials)

      Description copied from interface: `ContextSource`
      Gets a `DirContext` instance authenticated using the supplied principal and credentials. Typically to be used for plain authentication purposes. Note that this method will never make use of native Java LDAP pooling, even though this instance is configured to do so. This is to force password changes in the target directory to take effect as soon as possible.
      Specified by:
        `getContext` in interface `ContextSource`
      Parameters:
        `principal` - The principal (typically a distinguished name of a user in the LDAP tree) to use for authentication.
        `credentials` - The credentials to use for authentication.
      Returns:
        an authenticated `DirContext` instance, never `null`.