diff --git a/spring-ldap/docs/reference/src/configuration.xml b/spring-ldap/docs/reference/src/configuration.xml index ad2b90e6..9555a24f 100644 --- a/spring-ldap/docs/reference/src/configuration.xml +++ b/spring-ldap/docs/reference/src/configuration.xml @@ -5,32 +5,32 @@ ContextSource Configuration - There are several properties in AbstractContextSource - (superclass of DirContextSource and LdapContextSource) + There are several properties in AbstractContextSource + (superclass of DirContextSource and LdapContextSource) that can be used to modify its behaviour. - - - LDAP Server URLs - - The URL of the LDAP server is specified using the url property. - The URL should be in the format ldap://myserver.example.com:389. - For SSL access, use the ldaps protocol and the appropriate port, e.g. - ldaps://myserver.example.com:636 - It is possible to configure multiple alternate LDAP servers using the - urls property. In this case, supply all server urls in a String - array to the urls property. - - - - Base LDAP path - - It is possible to specify the root context for all LDAP operations using the - base property of AbstractContextSource. - When a value has been specified to this property, all Distinguished Names supplied to and received from LDAP operations - will be relative to the LDAP path supplied. This can significantly simplify working against the LDAP - tree; however there are several occations when you will need to have access to the base path. - For more information on this, please refer to - + + + LDAP Server URLs + + The URL of the LDAP server is specified using the url property. + The URL should be in the format ldap://myserver.example.com:389. + For SSL access, use the ldaps protocol and the appropriate port, e.g. + ldaps://myserver.example.com:636 + It is possible to configure multiple alternate LDAP servers using the + urls property. In this case, supply all server urls in a String + array to the urls property. + + + + Base LDAP path + + It is possible to specify the root context for all LDAP operations using the + base property of AbstractContextSource. + When a value has been specified to this property, all Distinguished Names supplied to and received from LDAP operations + will be relative to the LDAP path supplied. This can significantly simplify working against the LDAP + tree; however there are several occations when you will need to have access to the base path. + For more information on this, please refer to + Authentication @@ -85,7 +85,7 @@ <bean id="contextSource" class="org.springframework.ldap.core.support.LdapContextSource"> <property name="url" value="ldap://localhost:389" /> <property name="base" value="dc=example,dc=com" /> - <property name="acegiAuthenticationSource" ref="authenticationSource" /> + <property name="authenticationSource" ref="acegiAuthenticationSource" /> </bean> <bean id="acegiAuthenticationSource" @@ -156,104 +156,104 @@ manually. Details of pooling configuration can be found here. - - - Advanced ContextSource Configuration - - Alternate ContextFactory - - It is possible to configure the ContextFactory that the - ContextSource is to use when creating Contexts using the - contextFactory property. The default value is - com.sun.jndi.ldap.LdapCtxFactory. - - - Custom DirObjectFactory - - As described in , a DirObjectFactory - can be used to translate the Attributes of found Contexts - to a more useful DirContext implementation. This can be - configured using the dirObjectFactory property. You can use - this property if you have your own, custom DirObjectFactory implementation. - The default value is DefaultDirObjectFactory. - - - Custom DirContext Environment Properties - - In some cases the user might want to specify additional environment setup properties - in addition to the ones directly configurable from AbstractContextSource. - Such properties should be set in a Map and supplied to - the baseEnvironmentProperties property. - - - - LdapTemplate Configuration - - - Ignoring PartialResultExceptions - - Some Active Directory (AD) servers are unable to automatically following - referrals, which often leads to a PartialResultException being - thrown in searches. You can specify that PartialResultException - is to be ignored by setting the ignorePartialResultException - property to true. - This causes all referrals to be ignored, and no notice will be given that - a PartialResultException has been encountered. - There is currently no way of manually following referrals using LdapTemplate. - - - - Obtaining a reference to the base LDAP path - As described above, a base LDAP path may be supplied to the ContextSource, - specifying the root in the LDAP tree to which all operations will be relative. This means that - you will only be working with relative distinguished names throughout your system, which is - typically rather handy. There are however some cases in which you will need to have access - to the base path in order to be able to construct full DNs, relative to the actual root of the LDAP tree. - One example would be when working with LDAP groups (e.g. groupOfNames objectclass), - in which case each group member attribute value will need to be the full DN of the referenced member. - For that reason, Spring LDAP has a mechanism by which any Spring controlled bean may be supplied - the base path on startup. For beans to be notified of the base path, two things need to be in place: - First of all, the bean that wants the base path reference needs to implement the - BaseLdapPathAware interface. Secondly, a BaseLdapPathBeanPostProcessor - needs to be defined in the application context - - Implementing <literal>BaseLdapPathAware</literal> - - package com.example.service; - -public class PersonService implements PersonService, BaseLdapPathAware { - ... - private DistinguishedName basePath; - - public void setBaseLdapPath(DistinguishedName basePath) { - this.basePath = basePath; - } - ... - private DistinguishedName getFullPersonDn(Person person) { - return new DistinguishedName(basePath).append(person.getDn()); - } - ... -} - - - Specifying a <literal>BaseLdapPathBeanPostProcessor</literal> in your <literal>ApplicationContext</literal> - - <beans> - ... - <bean id="contextSource" class="org.springframework.ldap.core.support.LdapContextSource"> - <property name="url" value="ldap://localhost:389" /> - <property name="base" value="dc=example,dc=com" /> - <property name="acegiAuthenticationSource" ref="authenticationSource" /> - </bean> - ... - <bean class="org.springframework.ldap.core.support.BaseLdapPathBeanPostProcessor" /> -</beans> - - - The default behaviour of the BaseLdapPathBeanPostProcessor is to use the base path of the single + + Advanced ContextSource Configuration + + Alternate ContextFactory + + It is possible to configure the ContextFactory that the + ContextSource is to use when creating Contexts using the + contextFactory property. The default value is + com.sun.jndi.ldap.LdapCtxFactory. + + + Custom DirObjectFactory + + As described in , a DirObjectFactory + can be used to translate the Attributes of found Contexts + to a more useful DirContext implementation. This can be + configured using the dirObjectFactory property. You can use + this property if you have your own, custom DirObjectFactory implementation. + The default value is DefaultDirObjectFactory. + + + Custom DirContext Environment Properties + + In some cases the user might want to specify additional environment setup properties + in addition to the ones directly configurable from AbstractContextSource. + Such properties should be set in a Map and supplied to + the baseEnvironmentProperties property. + + + + + LdapTemplate Configuration + + + Ignoring PartialResultExceptions + + Some Active Directory (AD) servers are unable to automatically following + referrals, which often leads to a PartialResultException being + thrown in searches. You can specify that PartialResultException + is to be ignored by setting the ignorePartialResultException + property to true. + This causes all referrals to be ignored, and no notice will be given that + a PartialResultException has been encountered. + There is currently no way of manually following referrals using LdapTemplate. + + + + Obtaining a reference to the base LDAP path + As described above, a base LDAP path may be supplied to the ContextSource, + specifying the root in the LDAP tree to which all operations will be relative. This means that + you will only be working with relative distinguished names throughout your system, which is + typically rather handy. There are however some cases in which you will need to have access + to the base path in order to be able to construct full DNs, relative to the actual root of the LDAP tree. + One example would be when working with LDAP groups (e.g. groupOfNames objectclass), + in which case each group member attribute value will need to be the full DN of the referenced member. + For that reason, Spring LDAP has a mechanism by which any Spring controlled bean may be supplied + the base path on startup. For beans to be notified of the base path, two things need to be in place: + First of all, the bean that wants the base path reference needs to implement the + BaseLdapPathAware interface. Secondly, a BaseLdapPathBeanPostProcessor + needs to be defined in the application context + + Implementing <literal>BaseLdapPathAware</literal> + + package com.example.service; + +public class PersonService implements PersonService, BaseLdapPathAware { + ... + private DistinguishedName basePath; + + public void setBaseLdapPath(DistinguishedName basePath) { + this.basePath = basePath; + } + ... + private DistinguishedName getFullPersonDn(Person person) { + return new DistinguishedName(basePath).append(person.getDn()); + } + ... +} + + + Specifying a <literal>BaseLdapPathBeanPostProcessor</literal> in your <literal>ApplicationContext</literal> + + <beans> + ... + <bean id="contextSource" class="org.springframework.ldap.core.support.LdapContextSource"> + <property name="url" value="ldap://localhost:389" /> + <property name="base" value="dc=example,dc=com" /> + <property name="acegiAuthenticationSource" ref="authenticationSource" /> + </bean> + ... + <bean class="org.springframework.ldap.core.support.BaseLdapPathBeanPostProcessor" /> +</beans> + + + The default behaviour of the BaseLdapPathBeanPostProcessor is to use the base path of the single defined BaseLdapPathSource (AbstractContextSource )in the ApplicationContext. If more than one BaseLdapPathSource is defined, you will need to specify which one to use with the - baseLdapPathSourceName property. + baseLdapPathSourceName property. \ No newline at end of file diff --git a/spring-ldap/docs/reference/src/pooling.xml b/spring-ldap/docs/reference/src/pooling.xml index 7d7d2ddd..2df9a509 100644 --- a/spring-ldap/docs/reference/src/pooling.xml +++ b/spring-ldap/docs/reference/src/pooling.xml @@ -7,7 +7,7 @@ Introduction - Pooling LDAP connections helps mitigated the overhead of + Pooling LDAP connections helps mitigate the overhead of creating a new LDAP connection for each LDAP interaction. While PoolingContextSource which can wrap any ContextSource - and pool both read only and read write + and pool both read-only and read-write DirContext - s. + objects. Jakarta Commons-Pool @@ -521,4 +521,30 @@ + + + Known Issues + + + Custom Authentication + + + The PoolingContextSource assumes that all + DirContext objects retrieved from + ContextSource.getReadOnlyContext() will have + the same environment and likewise that all + DirContext objects retrieved from + ContextSource.getReadWriteContext() will + have the same environment. This means that wrapping a + LdapContextSource configured with an + AuthenticationSource in a + PoolingContextSource will not function + as expected. The pool would be populated using the credentials + of the first user and unless new connections were needed + subsequent context requests would not be filled for the user + specified by the AuthenticationSource for + the requesting thread. + + + \ No newline at end of file