|
| 1 | +[[ldap.configuration]] |
| 2 | += Configuration |
| 3 | + |
| 4 | +This section describes configuring Spring Data LDAP. |
| 5 | +Spring LDAP repositories can be enabled by using a `<data-ldap:repositories>` tag in your XML configuration or by using an `@EnableLdapRepositories` annotation on a configuration class: |
| 6 | + |
| 7 | +* "`<<ldap.namespace,Spring Namespace>>`" (XML configuration) |
| 8 | +* "`<<ldap.java-config,Annotation-based Configuration>>`" (Java configuration) |
| 9 | + |
| 10 | +To include support for `LdapQuery` parameters in automatically generated repositories, have your interface extend `LdapRepository` rather than `CrudRepository`. |
| 11 | + |
| 12 | +All Spring LDAP repositories must work with entities annotated with the ODM annotations, as described in https://docs.spring.io/spring-ldap/reference/odm.html[Object-Directory Mapping]. |
| 13 | + |
| 14 | +Since all ODM managed classes must have a Distinguished Name as the ID, all Spring LDAP repositories must have the ID type parameter set to `javax.naming.Name`. |
| 15 | + |
| 16 | +Indeed, the built-in `LdapRepository` only takes one type parameter: the managed entity class, which defaults the ID to `javax.naming.Name`. |
| 17 | + |
| 18 | +Due to specifics of the LDAP protocol, paging and sorting are not supported for Spring LDAP repositories. |
| 19 | + |
| 20 | +NOTE: You must use ODM annotations, such as `org.springframework.ldap.odm.annotations.Id`. |
| 21 | +Using Spring Data's annotation does not work, because Spring LDAP uses its own mapping layer. |
| 22 | + |
| 23 | +[[ldap.java-config]] |
| 24 | +== Annotation-based Configuration |
| 25 | + |
| 26 | +The Spring Data LDAP repositories support can be activated through both JavaConfig as well as a custom XML namespace, as shown in the following example: |
| 27 | + |
| 28 | +.Spring Data LDAP repositories using JavaConfig |
| 29 | +==== |
| 30 | +[source,java] |
| 31 | +---- |
| 32 | +@Configuration |
| 33 | +@EnableLdapRepositories("com.acme.*.repositories") |
| 34 | +class MyConfig { |
| 35 | +
|
| 36 | + @Bean |
| 37 | + ContextSource contextSource() { |
| 38 | +
|
| 39 | + LdapContextSource ldapContextSource = new LdapContextSource(); |
| 40 | +
|
| 41 | + ldapContextSource.setUserDn("cn=Admin"); |
| 42 | + ldapContextSource.setPassword("secret"); |
| 43 | + ldapContextSource.setUrl("ldap://127.0.0.1:389"); |
| 44 | +
|
| 45 | + return ldapContextSource; |
| 46 | + } |
| 47 | +
|
| 48 | + @Bean |
| 49 | + LdapTemplate ldapTemplate(ContextSource contextSource) { |
| 50 | + return new LdapTemplate(contextSource); |
| 51 | + } |
| 52 | +} |
| 53 | +---- |
| 54 | +==== |
| 55 | + |
| 56 | +This configuration causes the base packages to be scanned for interfaces that extend contain LDAP repositories and create Spring beans for each one found. |
| 57 | + |
| 58 | +If no base package is configured, the infrastructure scans the package of the annotated configuration class. |
| 59 | + |
| 60 | +[[ldap.namespace]] |
| 61 | +== Spring Namespace |
| 62 | + |
| 63 | +The LDAP module of Spring Data contains a custom namespace that allows defining repository beans. |
| 64 | +It also contains certain features and element attributes that are special to LDAP. |
| 65 | +Generally, the LDAP repositories can be set up by using the `repositories` element, as shown in the following example: |
| 66 | + |
| 67 | +.Setting up LDAP repositories by using the namespace |
| 68 | +==== |
| 69 | +[source,xml] |
| 70 | +---- |
| 71 | +<beans xmlns="http://www.springframework.org/schema/beans" |
| 72 | + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" |
| 73 | + xmlns:ldap="http://www.springframework.org/schema/ldap" |
| 74 | + xmlns:data-ldap="http://www.springframework.org/schema/data/ldap" |
| 75 | + xsi:schemaLocation="http://www.springframework.org/schema/beans |
| 76 | + https://www.springframework.org/schema/beans/spring-beans.xsd |
| 77 | + http://www.springframework.org/schema/ldap |
| 78 | + https://www.springframework.org/schema/ldap/spring-ldap.xsd |
| 79 | + http://www.springframework.org/schema/data/ldap |
| 80 | + https://www.springframework.org/schema/data/ldap/spring-ldap.xsd"> |
| 81 | +
|
| 82 | + <ldap:context-source url="ldap://127.0.0.1:389" |
| 83 | + username="cn=Admin" |
| 84 | + password="secret" /> |
| 85 | +
|
| 86 | + <ldap:ldap-template /> |
| 87 | +
|
| 88 | + <data-ldap:repositories base-package="com.acme.*.repositories" /> |
| 89 | +
|
| 90 | +</beans> |
| 91 | +---- |
| 92 | +==== |
| 93 | + |
| 94 | +This configuration causes the base packages to be scanned for interfaces that extend contain LDAP repositories and create Spring beans for each one found. |
| 95 | + |
| 96 | +By default, the repositories get an autowired `LdapTemplate` Spring bean that is called `ldapTemplate`, so you only need to configure `ldap-template-ref` explicitly if you deviate from this convention. |
| 97 | + |
| 98 | +TIP: Which is better, JavaConfig or XML? |
| 99 | +XML is how Spring was configured long ago. |
| 100 | +In today's era of fast-growing Java, record types, annotations, and more, new projects typically use as much pure Java as possible. |
| 101 | +While there is no immediate plan to remove XML support, some of the newest features MAY not be available through XML. |
| 102 | + |
| 103 | +Using the `repositories` element looks up Spring Data repositories as described in xref:repositories/create-instances.adoc[Creating Repository Instances]. |
| 104 | + |
| 105 | +[[ldap.namespace.custom-namespace-attributes]] |
| 106 | +=== Custom Namespace Attributes |
| 107 | + |
| 108 | +Beyond the xref:repositories/namespace-reference.adoc[default attributes of the `repositories` element], the LDAP namespace offers additional attributes to let you gain more detailed control over the setup of the repositories: |
| 109 | + |
| 110 | +.Custom LDAP-specific attributes of the `repositories` element |
| 111 | +[options = "autowidth"] |
| 112 | +|=============== |
| 113 | +|`ldap-template-ref`|Explicitly wire the `LdapTemplate` to be used with the repositories being detected by the `repositories` element. Usually used if multiple `LdapTemplate` beans are used within the application. If not configured, Spring Data automatically looks up the `LdapTemplate` bean with the name `ldapTemplate` in the `ApplicationContext`. |
| 114 | +|=============== |
| 115 | + |
| 116 | +NOTE: Spring Data LDAP requires a `LdapMappingContext` bean named `ldapMappingContext` to be present. |
| 117 | +If no such bean is defined, then Spring Data LDAP registers a default instance in the application context. |
| 118 | + |
| 119 | + |
0 commit comments