org.springframework.ldap.core.support

## Class AbstractContextSource

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

- All Implemented Interfaces:
    InitializingBean, ContextSource, BaseLdapPathContextSource, BaseLdapPathSource
  Direct Known Subclasses:
    DirContextSource, LdapContextSource

      public abstract class AbstractContextSource
      extends Object
      implements BaseLdapPathContextSource, InitializingBean

  Abstract implementation of the `ContextSource` interface. By default, returns an authenticated `DirContext` implementation for both read-only and read-write operations. To have an anonymous environment created for read-only operations, set the `anonymousReadOnly` property to `true`.

  Implementing classes need to implement `getDirContextInstance(Hashtable)` to create a `DirContext` instance of the desired type.

  If an `AuthenticationSource` is set, this will be used for getting user principal and password for each new connection, otherwise a default one will be created using the specified `userDn` and `password`.

  Note: When using implementations of this class outside of a Spring Context it is necessary to call `afterPropertiesSet()` when all properties are set, in order to finish up initialization.

  Author:
    Mattias Hellborg Arthursson, Adam Skogman, Ulrik Sandberg
  See Also:
    `LdapTemplate`, `DefaultDirObjectFactory`, `LdapContextSource`, `DirContextSource`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected String` | `password` Deprecated. use `getPassword()` and `setPassword(String)` instead
    `static String` | `SUN_LDAP_POOLING_FLAG`
    `protected String` | `userDn` Deprecated. use `getUserDn()` and `setUserDn(String)` instead

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `AbstractContextSource()`

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `afterPropertiesSet()` Checks that all necessary data is set and that there is no compatibility issues, after which the instance is initialized.
    `String` | `assembleProviderUrlString(String[] ldapUrls)` Assemble a valid url String from all registered urls to add as `PROVIDER_URL` to the environment.
    `protected DirContext` | `createContext(Hashtable<String,Object> environment)` Create a DirContext using the supplied environment.
    `protected Hashtable<String,Object>` | `getAnonymousEnv()`
    `protected Hashtable<String,Object>` | `getAuthenticatedEnv(String principal, String credentials)`
    `AuthenticationSource` | `getAuthenticationSource()` Get the authentication source.
    `LdapName` | `getBaseLdapName()` Get the base LDAP path as a `LdapName`.
    `DistinguishedName` | `getBaseLdapPath()` Deprecated. `DistinguishedName` and associated classes and methods are deprecated as of 2.0.
    `String` | `getBaseLdapPathAsString()` Get the base LDAP path as a String.
    `DirContext` | `getContext(String principal, String credentials)` Gets a `DirContext` instance authenticated using the supplied principal and credentials.
    `Class<?>` | `getContextFactory()` Get the context factory.
    `protected abstract DirContext` | `getDirContextInstance(Hashtable<String,Object> environment)` Implement in subclass to create a DirContext of the desired type (e.g.
    `Class<?>` | `getDirObjectFactory()` Get the DirObjectFactory to use.
    `String` | `getPassword()` Gets the password (credentials) to use for getting authenticated contexts.
    `DirContext` | `getReadOnlyContext()` Gets a read-only `DirContext`.
    `DirContext` | `getReadWriteContext()` Gets a read-write `DirContext` instance.
    `String[]` | `getUrls()` Get the urls of the LDAP servers.
    `String` | `getUserDn()` Gets the user distinguished name (principal) to use for getting authenticated contexts.
    `boolean` | `isAnonymousReadOnly()` Get whether an anonymous environment should be used for read-only operations.
    `boolean` | `isPooled()` Get whether the pooling flag should be set.
    `void` | `setAnonymousReadOnly(boolean anonymousReadOnly)` Set whether an anonymous environment should be used for read-only operations.
    `void` | `setAuthenticationSource(AuthenticationSource authenticationSource)` Set the authentication source to use when retrieving user principal and credentials.
    `void` | `setAuthenticationStrategy(DirContextAuthenticationStrategy authenticationStrategy)` Set the `DirContextAuthenticationStrategy` to use for preparing the environment and processing the created `DirContext` instances.
    `void` | `setBase(String base)` Set the base suffix from which all operations should origin.
    `void` | `setBaseEnvironmentProperties(Map<String,Object> baseEnvironmentProperties)` If any custom environment properties are needed, these can be set using this method.
    `void` | `setCacheEnvironmentProperties(boolean cacheEnvironmentProperties)` Set whether environment properties should be cached between requsts for anonymous environment.
    `void` | `setContextFactory(Class<?> contextFactory)` Set the context factory.
    `void` | `setDirObjectFactory(Class<?> dirObjectFactory)` Set the DirObjectFactory to use.
    `void` | `setPassword(String password)` Set the password (credentials) to use for getting authenticated contexts.
    `void` | `setPooled(boolean pooled)` Set whether the pooling flag should be set, enabling the built-in LDAP connection pooling.
    `void` | `setReferral(String referral)` Set the method to handle referrals.
    `protected void` | `setupAuthenticatedEnvironment(Hashtable<String,Object> env, String principal, String credentials)` Default implementation of setting the environment up to be authenticated.
    `void` | `setUrl(String url)` Set the url of the LDAP server.
    `void` | `setUrls(String[] urls)` Set the urls of the LDAP servers.
    `void` | `setUserDn(String userDn)` Set the user distinguished name (principal) to use for getting authenticated contexts.

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

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

- - ### Field Detail

    - #### userDn

          @Deprecated
          protected String userDn

      Deprecated. use `getUserDn()` and `setUserDn(String)` instead

    - #### password

          @Deprecated
          protected String password

      Deprecated. use `getPassword()` and `setPassword(String)` instead

    - #### SUN_LDAP_POOLING_FLAG

          public static final String SUN_LDAP_POOLING_FLAG

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### AbstractContextSource

          public AbstractContextSource()

  - ### Method Detail

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

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

    - #### setupAuthenticatedEnvironment

          protected void setupAuthenticatedEnvironment(Hashtable<String,Object> env,
                                                       String principal,
                                                       String credentials)

      Default implementation of setting the environment up to be authenticated. This method should typically NOT be overridden; any customization to the authentication mechanism should be managed by setting a different `DirContextAuthenticationStrategy` on this instance.
      Parameters:
        `env` - the environment to modify.
        `principal` - the principal to authenticate with.
        `credentials` - the credentials to authenticate with.
      See Also:
        `DirContextAuthenticationStrategy`, `setAuthenticationStrategy(DirContextAuthenticationStrategy)`

    - #### assembleProviderUrlString

          public String assembleProviderUrlString(String[] ldapUrls)

      Assemble a valid url String from all registered urls to add as `PROVIDER_URL` to the environment.
      Parameters:
        `ldapUrls` - all individual url Strings.
      Returns:
        the full url String

    - #### setBase

          public void setBase(String base)

      Set the base suffix from which all operations should origin. If a base suffix is set, you will not have to (and, indeed, must not) specify the full distinguished names in any operations performed.
      Parameters:
        `base` - the base suffix.

    - #### getBaseLdapPath

          public DistinguishedName getBaseLdapPath()

      Deprecated. `DistinguishedName` and associated classes and methods are deprecated as of 2.0.
      Description copied from interface: `BaseLdapPathSource`
      Get the base LDAP path as a `DistinguishedName`.
      Specified by:
        `getBaseLdapPath` in interface `BaseLdapPathSource`
      Returns:
        the base LDAP path as a `DistinguishedName`. The path will be empty if no base path is specified.

    - #### getBaseLdapName

          public LdapName getBaseLdapName()

      Description copied from interface: `BaseLdapPathSource`
      Get the base LDAP path as a `LdapName`.
      Specified by:
        `getBaseLdapName` in interface `BaseLdapPathSource`
      Returns:
        the base LDAP path as a `LdapName`. The path will be empty if no base path is specified.

    - #### getBaseLdapPathAsString

          public String getBaseLdapPathAsString()

      Description copied from interface: `BaseLdapPathSource`
      Get the base LDAP path as a String.
      Specified by:
        `getBaseLdapPathAsString` in interface `BaseLdapPathSource`
      Returns:
        the base LDAP path as a An empty String will be returned if no base path is specified.

    - #### createContext

          protected DirContext createContext(Hashtable<String,Object> environment)

      Create a DirContext using the supplied environment.
      Parameters:
        `environment` - the LDAP environment to use when creating the `DirContext`.
      Returns:
        a new DirContext implementation initialized with the supplied environment.

    - #### setContextFactory

          public void setContextFactory(Class<?> contextFactory)

      Set the context factory. Default is com.sun.jndi.ldap.LdapCtxFactory.
      Parameters:
        `contextFactory` - the context factory used when creating Contexts.

    - #### getContextFactory

          public Class<?> getContextFactory()

      Get the context factory.
      Returns:
        the context factory used when creating Contexts.

    - #### setDirObjectFactory

          public void setDirObjectFactory(Class<?> dirObjectFactory)

      Set the DirObjectFactory to use. Default is `DefaultDirObjectFactory`. The specified class needs to be an implementation of javax.naming.spi.DirObjectFactory. Note: Setting this value to null may have cause connection leaks when using ContextMapper methods in LdapTemplate.
      Parameters:
        `dirObjectFactory` - the DirObjectFactory to be used. Null means that no DirObjectFactory will be used.

    - #### getDirObjectFactory

          public Class<?> getDirObjectFactory()

      Get the DirObjectFactory to use.
      Returns:
        the DirObjectFactory to be used. `null` means that no DirObjectFactory will be used.

    - #### afterPropertiesSet

          public void afterPropertiesSet()

      Checks that all necessary data is set and that there is no compatibility issues, after which the instance is initialized. Note that you need to call this method explicitly after setting all desired properties if using the class outside of a Spring Context.
      Specified by:
        `afterPropertiesSet` in interface `InitializingBean`

    - #### setPassword

          public void setPassword(String password)

      Set the password (credentials) to use for getting authenticated contexts.
      Parameters:
        `password` - the password.

    - #### getPassword

          public String getPassword()

      Gets the password (credentials) to use for getting authenticated contexts.
      Returns:
        the password

    - #### setUserDn

          public void setUserDn(String userDn)

      Set the user distinguished name (principal) to use for getting authenticated contexts.
      Parameters:
        `userDn` - the user distinguished name.

    - #### getUserDn

          public String getUserDn()

      Gets the user distinguished name (principal) to use for getting authenticated contexts.
      Returns:
        the user distinguished name.

    - #### setUrls

          public void setUrls(String[] urls)

      Set the urls of the LDAP servers. Use this method if several servers are required.
      Parameters:
        `urls` - the urls of all servers.

    - #### getUrls

          public String[] getUrls()

      Get the urls of the LDAP servers.
      Returns:
        the urls of all servers.

    - #### setUrl

          public void setUrl(String url)

      Set the url of the LDAP server. Utility method if only one server is used.
      Parameters:
        `url` - the url of the LDAP server.

    - #### setPooled

          public void setPooled(boolean pooled)

      Set whether the pooling flag should be set, enabling the built-in LDAP connection pooling. Default is `false`. The built-in LDAP connection pooling suffers from a number of deficiencies, e.g. no connection validation. Also, enabling this flag when using TLS connections will explicitly not work. Consider using the Spring LDAP `PoolingContextSource` as an alternative instead of enabling this flag.

      Note that since LDAP pooling is system wide, full configuration of this needs be done using system parameters as specified in the LDAP/JNDI documentation. Also note, that pooling is done on user dn basis, i.e. each individually authenticated connection will be pooled separately. This means that LDAP pooling will be most efficient using anonymous connections or connections authenticated using one single system user.

      Parameters:
        `pooled` - whether Contexts should be pooled.

    - #### isPooled

          public boolean isPooled()

      Get whether the pooling flag should be set.
      Returns:
        whether Contexts should be pooled.

    - #### setBaseEnvironmentProperties

          public void setBaseEnvironmentProperties(Map<String,Object> baseEnvironmentProperties)

      If any custom environment properties are needed, these can be set using this method.
      Parameters:
        `baseEnvironmentProperties` - the base environment properties that should always be used when creating new Context instances.

    - #### getAnonymousEnv

          protected Hashtable<String,Object> getAnonymousEnv()

    - #### getAuthenticatedEnv

          protected Hashtable<String,Object> getAuthenticatedEnv(String principal,
                                                                 String credentials)

    - #### setAuthenticationSource

          public void setAuthenticationSource(AuthenticationSource authenticationSource)

      Set the authentication source to use when retrieving user principal and credentials.
      Parameters:
        `authenticationSource` - the `AuthenticationSource` that will provide user info.

    - #### getAuthenticationSource

          public AuthenticationSource getAuthenticationSource()

      Get the authentication source.
      Returns:
        the `AuthenticationSource` that will provide user info.

    - #### setCacheEnvironmentProperties

          public void setCacheEnvironmentProperties(boolean cacheEnvironmentProperties)

      Set whether environment properties should be cached between requsts for anonymous environment. Default is `true`; setting this property to `false` causes the environment Hashmap to be rebuilt from the current property settings of this instance between each request for an anonymous environment.
      Parameters:
        `cacheEnvironmentProperties` - `true` causes that the anonymous environment properties should be cached, `false` causes the Hashmap to be rebuilt for each request.

    - #### setAnonymousReadOnly

          public void setAnonymousReadOnly(boolean anonymousReadOnly)

      Set whether an anonymous environment should be used for read-only operations. Default is `false`.
      Parameters:
        `anonymousReadOnly` - `true` if an anonymous environment should be used for read-only operations, `false` otherwise.

    - #### isAnonymousReadOnly

          public boolean isAnonymousReadOnly()

      Get whether an anonymous environment should be used for read-only operations.
      Returns:
        `true` if an anonymous environment should be used for read-only operations, `false` otherwise.

    - #### setAuthenticationStrategy

          public void setAuthenticationStrategy(DirContextAuthenticationStrategy authenticationStrategy)

      Set the `DirContextAuthenticationStrategy` to use for preparing the environment and processing the created `DirContext` instances.
      Parameters:
        `authenticationStrategy` - the `DirContextAuthenticationStrategy` to use; default is `SimpleDirContextAuthenticationStrategy`.

    - #### setReferral

          public void setReferral(String referral)

      Set the method to handle referrals. Default is 'ignore'; setting this flag to 'follow' will enable referrals to be automatically followed. Note that this might require particular name server setup in order to work (the referred URLs will need to be automatically found using standard DNS resolution).
      Parameters:
        `referral` - the value to set the system property `Context.REFERRAL` to, customizing the way that referrals are handled.

    - #### getDirContextInstance

          protected abstract DirContext getDirContextInstance(Hashtable<String,Object> environment)
                                                       throws NamingException

      Implement in subclass to create a DirContext of the desired type (e.g. InitialDirContext or InitialLdapContext).
      Parameters:
        `environment` - the environment to use when creating the instance.
      Returns:
        a new DirContext instance.
      Throws:
        `NamingException` - if one is encountered when creating the instance.