org.springframework.ldap.core.support

## Class SingleContextSource

- java.lang.Object
- - org.springframework.ldap.core.support.SingleContextSource

- All Implemented Interfaces:
    DisposableBean, ContextSource

      public class SingleContextSource
      extends Object
      implements ContextSource, DisposableBean

  A `ContextSource` to be used as a decorator around a target ContextSource to make sure the target is never actually closed. Useful when working with e.g. paged results, as these require the same target to be used.
  Author:
    Mattias Hellborg Arthursson

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `SingleContextSource.NonClosingDirContextInvocationHandler` A proxy for DirContext forwarding all operation to the target DirContext, but making sure that no `close` operations will be performed.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `SingleContextSource(DirContext ctx)` Constructor.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `destroy()` Destroy method that allows the target DirContext to be cleaned up when the SingleContextSource is not going to be used any more.
    `static <T> T` | `doWithSingleContext(ContextSource contextSource, LdapOperationsCallback<T> callback)` Construct a SingleContextSource and execute the LdapOperationsCallback using the created instance.
    `static <T> T` | `doWithSingleContext(ContextSource contextSource, LdapOperationsCallback<T> callback, boolean useReadOnly, boolean ignorePartialResultException, boolean ignoreNameNotFoundException)` Construct a SingleContextSource and execute the LdapOperationsCallback using the created instance.
    `DirContext` | `getContext(String principal, String credentials)` Gets a `DirContext` instance authenticated using the supplied principal and credentials.
    `DirContext` | `getReadOnlyContext()` Gets a read-only `DirContext`.
    `DirContext` | `getReadWriteContext()` Gets a read-write `DirContext` instance.

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

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

- - ### Constructor Detail

    - #### SingleContextSource

          public SingleContextSource(DirContext ctx)

      Constructor.
      Parameters:
        `ctx` - the target DirContext.

  - ### Method Detail

    - #### 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

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

    - #### destroy

          public void destroy()

      Destroy method that allows the target DirContext to be cleaned up when the SingleContextSource is not going to be used any more.
      Specified by:
        `destroy` in interface `DisposableBean`

    - #### doWithSingleContext

          public static <T> T doWithSingleContext(ContextSource contextSource,
                                                  LdapOperationsCallback<T> callback)

      Construct a SingleContextSource and execute the LdapOperationsCallback using the created instance. This makes sure the same connection will be used for all operations inside the LdapOperationsCallback, which is particularly useful when working with e.g. Paged Results as these typically require the exact same connection to be used for all requests involving the same cookie. The SingleContextSource instance will be properly disposed of once the operation has been completed.

      By default, the `ContextSource.getReadWriteContext()` method will be used to create the DirContext instance to operate on.

      Parameters:
        `contextSource` - The target ContextSource to retrieve a DirContext from.
        `callback` - the callback to perform the Ldap operations.
      Returns:
        the result returned from the callback.
      Since:
        2.0
      See Also:
        `doWithSingleContext(org.springframework.ldap.core.ContextSource, LdapOperationsCallback, boolean, boolean, boolean)`

    - #### doWithSingleContext

          public static <T> T doWithSingleContext(ContextSource contextSource,
                                                  LdapOperationsCallback<T> callback,
                                                  boolean useReadOnly,
                                                  boolean ignorePartialResultException,
                                                  boolean ignoreNameNotFoundException)

      Construct a SingleContextSource and execute the LdapOperationsCallback using the created instance. This makes sure the same connection will be used for all operations inside the LdapOperationsCallback, which is particularly useful when working with e.g. Paged Results as these typically require the exact same connection to be used for all requests involving the same cookie.. The SingleContextSource instance will be properly disposed of once the operation has been completed.
      Parameters:
        `contextSource` - The target ContextSource to retrieve a DirContext from
        `callback` - the callback to perform the Ldap operations
        `useReadOnly` - if `true`, use the `ContextSource.getReadOnlyContext()` method on the target ContextSource to get the actual DirContext instance, if `false`, use `ContextSource.getReadWriteContext()`.
        `ignorePartialResultException` - Used for populating this property on the created LdapTemplate instance.
        `ignoreNameNotFoundException` - Used for populating this property on the created LdapTemplate instance.
      Returns:
        the result returned from the callback.
      Since:
        2.0