Spring/spring-data-ldap
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Migrate documentation site to Antora.

Browse Source 
Closes #425
This commit is contained in:
Mark Paluch
2023-08-23 10:35:41 +02:00
parent bb56267bf8
commit f43b662e6c
32 changed files with 500 additions and 405 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
.gitignore vendored
View File

@@ -15,3 +15,7 @@ src/ant/.ant-targets-upload-dist.xml
atlassian-ide-plugin.xml
/.gradle/
/.idea/
package.json
package-lock.json
node
node_modules

45
pom.xml
View File

@@ -1,5 +1,6 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
@@ -134,25 +135,6 @@
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-assembly-plugin</artifactId>
</plugin>
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<configuration>
<attributes>
<version>${project.version}</version>
<projectName>${project.name}</projectName>
<projectVersion>${project.version}</projectVersion>
<aspectjVersion>${aspectj}</aspectjVersion>
<querydslVersion>${querydsl}</querydslVersion>
<springVersion>${spring}</springVersion>
<releasetrainVersion>${releasetrain}</releasetrainVersion>
<springLdapVersion>${spring-ldap}</springLdapVersion>
<allow-uri-read>true</allow-uri-read>
<toclevels>3</toclevels>
<numbered>true</numbered>
</attributes>
</configuration>
</plugin>
</plugins>
</build>
@@ -163,6 +145,29 @@
<spring-ldap>2.3.2.BUILD-SNAPSHOT</spring-ldap>
</properties>
</profile>
<profile>
<id>antora</id>
<build>
<plugins>
<plugin>
<groupId>io.spring.maven.antora</groupId>
<artifactId>antora-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
</profile>
<profile>
<id>antora-process-resources</id>
<build>
<resources>
<resource>
<directory>src/main/antora/resources/antora-resources</directory>
<filtering>true</filtering>
</resource>
</resources>
</build>
</profile>
</profiles>
<repositories>

42
src/main/antora/antora-playbook.yml Normal file
View File

@@ -0,0 +1,42 @@
# PACKAGES antora@3.2.0-alpha.2 @antora/atlas-extension:1.0.0-alpha.1 @antora/collector-extension@1.0.0-alpha.3 @springio/antora-extensions@1.1.0-alpha.2 @asciidoctor/tabs@1.0.0-alpha.12 @opendevise/antora-release-line-extension@1.0.0-alpha.2
#
# The purpose of this Antora playbook is to build the docs in the current branch.
antora:
extensions:
- '@antora/collector-extension'
- require: '@springio/antora-extensions/root-component-extension'
root_component_name: 'data-ldap'
site:
title: Spring Data LDAP
url: https://docs.spring.io/spring-data-ldap/reference/
content:
sources:
- url: ./../../..
branches: HEAD
start_path: src/main/antora
worktrees: true
- url: https://github.com/spring-projects/spring-data-commons
# Refname matching:
# https://docs.antora.org/antora/latest/playbook/content-refname-matching/
branches: [ main, 3.2.x ]
start_path: src/main/antora
asciidoc:
attributes:
page-pagination: ''
hide-uri-scheme: '@'
tabs-sync-option: '@'
chomp: 'all'
extensions:
- '@asciidoctor/tabs'
- '@springio/asciidoctor-extensions'
sourcemap: true
urls:
latest_version_segment: ''
runtime:
log:
failure_level: warn
format: pretty
ui:
bundle:
url: https://github.com/spring-io/antora-ui-spring/releases/download/v0.3.3/ui-bundle.zip
snapshot: true

12
src/main/antora/antora.yml Normal file
View File

@@ -0,0 +1,12 @@
name: data-ldap
version: true
title: Spring Data LDAP
nav:
- modules/ROOT/nav.adoc
ext:
collector:
- run:
command: ./mvnw validate process-resources -am -Pantora-process-resources
local: true
scan:
dir: target/classes/

22
src/main/antora/modules/ROOT/nav.adoc Normal file
View File

@@ -0,0 +1,22 @@
* xref:index.adoc[Overview]
** xref:commons/upgrade.adoc[]
* xref:repositories/introduction.adoc[]
** xref:repositories/core-concepts.adoc[]
** xref:repositories/definition.adoc[]
** xref:repositories/create-instances.adoc[]
** xref:repositories/query-methods-details.adoc[]
** xref:repositories/projections.adoc[]
** xref:repositories/custom-implementations.adoc[]
** xref:repositories/core-domain-events.adoc[]
** xref:repositories/core-extensions.adoc[]
** xref:repositories/null-handling.adoc[]
** xref:repositories/namespace-reference.adoc[]
** xref:repositories/query-keywords-reference.adoc[]
** xref:repositories/query-return-types-reference.adoc[]
* xref:ldap.adoc[]
** xref:ldap/configuration.adoc[]
** xref:ldap/usage.adoc[]
** xref:ldap/query-methods.adoc[]
** xref:ldap/querydsl.adoc[]
** xref:ldap/cdi-integration.adoc[]
* https://github.com/spring-projects/spring-data-commons/wiki[Wiki]

1
src/main/antora/modules/ROOT/pages/commons/upgrade.adoc Normal file
View File

@@ -0,0 +1 @@
include::{commons}@data-commons::page$upgrade.adoc[]

20
src/main/antora/modules/ROOT/pages/index.adoc Normal file
View File

@@ -0,0 +1,20 @@
[[spring-data-ldap-reference-documentation]]
= Spring Data LDAP
:revnumber: {version}
:revdate: {localdate}
:feature-scroll: true
_Spring Data LDAP provides repository support for Lightweight Directory Access Protocol (LDAP).
It eases development of applications with a consistent programming model that need to access LDAP data sources._
[horizontal]
xref:repositories/introduction.adoc[Introduction] :: Introduction to Spring Data Repositories
xref:ldap.adoc[LDAP] :: LDAP and LDAP Repositories
https://github.com/spring-projects/spring-data-commons/wiki[Wiki] :: What's New, Upgrade Notes, Supported Versions, additional cross-version information.
Mattias Hellborg Arthursson, Ulrik Sandberg, Eric Dalquist, Keith Barlow, Rob Winch, Mark Paluch, Jay Bryant
(C) 2008-2023 VMware, Inc.
Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically.

8
src/main/antora/modules/ROOT/pages/ldap.adoc Normal file
View File

@@ -0,0 +1,8 @@
[[ldap.repositories]]
= LDAP Repositories
:page-section-summary-toc: 1
This chapter points out the specialties for repository support for LDAP.
It builds on the core repository support explained in xref:repositories/introduction.adoc[Working with Spring Data Repositories].
You should have a sound understanding of the basic concepts explained there.

38
src/main/antora/modules/ROOT/pages/ldap/cdi-integration.adoc Normal file
View File

@@ -0,0 +1,38 @@
[[ldap.repositories.cdi-integration]]
= CDI Integration
Instances of the repository interfaces are usually created by a container, for which Spring is the most natural choice when working with Spring Data.
Spring Data LDAP includes a custom CDI extension that lets you use the repository abstraction in CDI environments.
The extension is part of the JAR.
To activate it, drop the Spring Data LDAP JAR into your classpath.
You can now set up the infrastructure by implementing a CDI Producer for the `LdapTemplate`, as the following example shows:
[source,java]
----
class LdapTemplateProducer {
@Produces
@ApplicationScoped
public LdapOperations createLdapTemplate() {
ContextSource contextSource = …
return new LdapTemplate(contextSource);
}
}
----
The Spring Data LDAP CDI extension picks up the `LdapTemplate` as a CDI bean and creates a proxy for a Spring Data repository whenever a bean of a repository type is requested by the container.
Thus, obtaining an instance of a Spring Data repository is a matter of declaring an injected property, as the following example shows:
[source,java]
----
class RepositoryClient {
@Inject
PersonRepository repository;
public void businessMethod() {
List<Person> people = repository.findAll();
}
}
----

119
src/main/antora/modules/ROOT/pages/ldap/configuration.adoc Normal file
View File

@@ -0,0 +1,119 @@
[[ldap.configuration]]
= Configuration
This section describes configuring Spring Data LDAP.
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:
* "`<<ldap.namespace,Spring Namespace>>`" (XML configuration)
* "`<<ldap.java-config,Annotation-based Configuration>>`" (Java configuration)
To include support for `LdapQuery` parameters in automatically generated repositories, have your interface extend `LdapRepository` rather than `CrudRepository`.
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].
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`.
Indeed, the built-in `LdapRepository` only takes one type parameter: the managed entity class, which defaults the ID to `javax.naming.Name`.
Due to specifics of the LDAP protocol, paging and sorting are not supported for Spring LDAP repositories.
NOTE: You must use ODM annotations, such as `org.springframework.ldap.odm.annotations.Id`.
Using Spring Data's annotation does not work, because Spring LDAP uses its own mapping layer.
[[ldap.java-config]]
== Annotation-based Configuration
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:
.Spring Data LDAP repositories using JavaConfig
====
[source,java]
----
@Configuration
@EnableLdapRepositories("com.acme.*.repositories")
class MyConfig {
@Bean
ContextSource contextSource() {
LdapContextSource ldapContextSource = new LdapContextSource();
ldapContextSource.setUserDn("cn=Admin");
ldapContextSource.setPassword("secret");
ldapContextSource.setUrl("ldap://127.0.0.1:389");
return ldapContextSource;
}
@Bean
LdapTemplate ldapTemplate(ContextSource contextSource) {
return new LdapTemplate(contextSource);
}
}
----
====
This configuration causes the base packages to be scanned for interfaces that extend contain LDAP repositories and create Spring beans for each one found.
If no base package is configured, the infrastructure scans the package of the annotated configuration class.
[[ldap.namespace]]
== Spring Namespace
The LDAP module of Spring Data contains a custom namespace that allows defining repository beans.
It also contains certain features and element attributes that are special to LDAP.
Generally, the LDAP repositories can be set up by using the `repositories` element, as shown in the following example:
.Setting up LDAP repositories by using the namespace
====
[source,xml]
----
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:ldap="http://www.springframework.org/schema/ldap"
xmlns:data-ldap="http://www.springframework.org/schema/data/ldap"
xsi:schemaLocation="http://www.springframework.org/schema/beans
https://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/ldap
https://www.springframework.org/schema/ldap/spring-ldap.xsd
http://www.springframework.org/schema/data/ldap
https://www.springframework.org/schema/data/ldap/spring-ldap.xsd">
<ldap:context-source url="ldap://127.0.0.1:389"
username="cn=Admin"
password="secret" />
<ldap:ldap-template />
<data-ldap:repositories base-package="com.acme.*.repositories" />
</beans>
----
====
This configuration causes the base packages to be scanned for interfaces that extend contain LDAP repositories and create Spring beans for each one found.
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.
TIP: Which is better, JavaConfig or XML?
XML is how Spring was configured long ago.
In today's era of fast-growing Java, record types, annotations, and more, new projects typically use as much pure Java as possible.
While there is no immediate plan to remove XML support, some of the newest features MAY not be available through XML.
Using the `repositories` element looks up Spring Data repositories as described in xref:repositories/create-instances.adoc[Creating Repository Instances].
[[ldap.namespace.custom-namespace-attributes]]
=== Custom Namespace Attributes
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:
.Custom LDAP-specific attributes of the `repositories` element
[options = "autowidth"]
|===============
|`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`.
|===============
NOTE: Spring Data LDAP requires a `LdapMappingContext` bean named `ldapMappingContext` to be present.
If no such bean is defined, then Spring Data LDAP registers a default instance in the application context.

78
src/main/antora/modules/ROOT/pages/ldap/query-methods.adoc Normal file
View File

@@ -0,0 +1,78 @@
[[ldap.repositories.queries]]
= Query Methods
Most of the data access operations you usually trigger on a repository result in a query being run against the LDAP directory.
Defining such a query is a matter of declaring a method on the repository interface, as the following example shows:
.PersonRepository with query methods
[source,java]
----
interface PersonRepository extends PagingAndSortingRepository<Person, String> {
List<Person> findByLastname(String lastname); <1>
List<Person> findByLastnameFirstname(String lastname, String firstname); <2>
}
----
<1> The method shows a query for all people with the given `lastname`.
The query is derived by parsing the method name for constraints that can be concatenated with `And` and `Or`.
Thus, the method name results in a query expression of `(&(objectclass=person)(lastname=lastname))`.
<2> The method shows a query for all people with the given `lastname` and `firstname`.
The query is derived by parsing the method name.
Thus, the method name results in a query expression of `(&(objectclass=person)(lastname=lastname)(firstname=firstname))`.
The following table provides samples of the keywords that you can use with query methods:
[cols="1,2,3",options="header"]
.Supported keywords for query methods
|===
| Keyword
| Sample
| Logical result
| `LessThanEqual`
| `findByAgeLessThanEqual(int age)`
| `(attribute<=age)`
| `GreaterThanEqual`
| `findByAgeGreaterThanEqual(int age)`
| `(attribute>=age)`
| `IsNotNull`, `NotNull`
| `findByFirstnameNotNull()`
| `(firstname=*)`
| `IsNull`, `Null`
| `findByFirstnameNull()`
| `(!(firstname=*))`
| `Like`
| `findByFirstnameLike(String name)`
| `(firstname=name)`
| `NotLike`, `IsNotLike`
| `findByFirstnameNotLike(String name)`
| `(!(firstname=name*))`
| `StartingWith`
| `findByStartingWith(String name)`
| `(firstname=name*)`
| `EndingWith`
| `findByFirstnameLike(String name)`
| `(firstname=*name)`
| `Containing`
| `findByFirstnameLike(String name)`
| `(firstname=\*name*)`
| `(No keyword)`
| `findByFirstname(String name)`
| `(Firstname=name)`
| `Not`
| `findByFirstnameNot(String name)`
| `(!(Firstname=name))`
|===

9
src/main/antora/modules/ROOT/pages/ldap/querydsl.adoc Normal file
View File

@@ -0,0 +1,9 @@
[[ldap.querydsl]]
= QueryDSL Support
Basic QueryDSL support is included in Spring LDAP. This support includes the following:
* An Annotation Processor, `LdapAnnotationProcessor`, for generating QueryDSL classes based on Spring LDAP ODM annotations.
See https://docs.spring.io/spring-ldap/docs/{springLdapVersion}/reference/#odm[Object-Directory Mapping] for more information on the ODM annotations.
* A Query implementation, `QueryDslLdapQuery`, for building and running QueryDSL queries in code.
* Spring Data repository support for QueryDSL predicates. `QueryDslPredicateExecutor` includes a number of additional methods with appropriate parameters.
You can extend this interface (along with `LdapRepository`) to include this support in your repository.

78
src/main/antora/modules/ROOT/pages/ldap/usage.adoc Normal file
View File

@@ -0,0 +1,78 @@
[[ldap.repo-usage]]
= Usage
To access domain entities stored in a LDAP-compliant directory, you can use our sophisticated repository support that significantly eases implementation.
To do so, create an interface for your repository, as the following example shows:
.Sample Person entity
====
[source,java]
----
@Entry(objectClasses = { "person", "top" }, base="ou=someOu")
public class Person {
@Id
private Name dn;
@Attribute(name="cn")
@DnAttribute(value="cn", index=1)
private String fullName;
@Attribute(name="firstName")
private String firstName;
// No @Attribute annotation means this is bound to the LDAP attribute
// with the same value
private String firstName;
@DnAttribute(value="ou", index=0)
@Transient
private String company;
@Transient
private String someUnmappedField;
// ...more attributes below
}
----
====
We have a simple domain object here.
Note that it has a property named `dn` of type `Name`.
With that domain object, we can create a repository to persist objects of that type by defining an interface for it, as follows:
.Basic repository interface to persist `Person` entities
====
[source]
----
public interface PersonRepository extends CrudRepository<Person, Long> {
// additional custom finder methods go here
}
----
====
Because our domain repository extends `CrudRepository`, it provides you with CRUD operations as well as methods for access to the entities.
Working with the repository instance is a matter of dependency injecting it into a client.
.Access to Person entities
====
[source,java]
----
@ExtendWith(SpringExtension.class)
@ContextConfiguration
class PersonRepositoryTests {
@Autowired PersonRepository repository;
@Test
void readAll() {
List<Person> persons = repository.findAll();
assertThat(persons.isEmpty(), is(false));
}
}
----
====
The sample creates an application context with Spring's unit test support, which will perform annotation-based dependency injection into test cases.
Inside the test method, we use the repository to query the datastore.

1
src/main/antora/modules/ROOT/pages/repositories/core-concepts.adoc Normal file
View File

@@ -0,0 +1 @@
include::{commons}@data-commons::page$repositories/core-concepts.adoc[]

1
src/main/antora/modules/ROOT/pages/repositories/core-domain-events.adoc Normal file
View File

@@ -0,0 +1 @@
include::{commons}@data-commons::page$repositories/core-domain-events.adoc[]

1
src/main/antora/modules/ROOT/pages/repositories/core-extensions.adoc Normal file
View File

@@ -0,0 +1 @@
include::{commons}@data-commons::page$repositories/core-extensions.adoc[]

1
src/main/antora/modules/ROOT/pages/repositories/create-instances.adoc Normal file
View File

@@ -0,0 +1 @@
include::{commons}@data-commons::page$repositories/create-instances.adoc[]

1
src/main/antora/modules/ROOT/pages/repositories/custom-implementations.adoc Normal file
View File

@@ -0,0 +1 @@
include::{commons}@data-commons::page$repositories/custom-implementations.adoc[]

1
src/main/antora/modules/ROOT/pages/repositories/definition.adoc Normal file
View File

@@ -0,0 +1 @@
include::{commons}@data-commons::page$repositories/definition.adoc[]

8
src/main/antora/modules/ROOT/pages/repositories/introduction.adoc Normal file
View File

@@ -0,0 +1,8 @@
[[common.basics]]
= Introduction
:page-section-summary-toc: 1
This chapter explains the basic foundations of Spring Data repositories.
Before continuing to the LDAP specifics, make sure you have a sound understanding of the basic concepts explained here.
include::{commons}@data-commons::page$repositories.adoc[leveloffset=+1]

1
src/main/antora/modules/ROOT/pages/repositories/namespace-reference.adoc Normal file
View File

@@ -0,0 +1 @@
include::{commons}@data-commons::page$repositories/namespace-reference.adoc[]

1
src/main/antora/modules/ROOT/pages/repositories/null-handling.adoc Normal file
View File

@@ -0,0 +1 @@
include::{commons}@data-commons::page$repositories/null-handling.adoc[]

4
src/main/antora/modules/ROOT/pages/repositories/projections.adoc Normal file
View File

@@ -0,0 +1,4 @@
[[ldap.projections]]
= Projections
include::{commons}@data-commons::page$repositories/projections.adoc[leveloffset=+1]

1
src/main/antora/modules/ROOT/pages/repositories/query-keywords-reference.adoc Normal file
View File

@@ -0,0 +1 @@
include::{commons}@data-commons::page$repositories/query-keywords-reference.adoc[]

1
src/main/antora/modules/ROOT/pages/repositories/query-methods-details.adoc Normal file
View File

@@ -0,0 +1 @@
include::{commons}@data-commons::page$repositories/query-methods-details.adoc[]

1
src/main/antora/modules/ROOT/pages/repositories/query-return-types-reference.adoc Normal file
View File

@@ -0,0 +1 @@
include::{commons}@data-commons::page$repositories/query-return-types-reference.adoc[]

21
src/main/antora/resources/antora-resources/antora.yml Normal file
View File

@@ -0,0 +1,21 @@
version: ${antora-component.version}
prerelease: ${antora-component.prerelease}
asciidoc:
attributes:
version: ${project.version}
springversionshort: ${spring.short}
springversion: ${spring}
attribute-missing: 'warn'
commons: ${springdata.commons.docs}
include-xml-namespaces: false
spring-data-commons-docs-url: https://docs.spring.io/spring-data-commons/reference
spring-data-commons-javadoc-base: https://docs.spring.io/spring-data/commons/docs/${springdata.commons}/api/
springdocsurl: https://docs.spring.io/spring-framework/reference/{springversionshort}
springjavadocurl: https://docs.spring.io/spring-framework/docs/${spring}/javadoc-api
spring-framework-docs: '{springdocsurl}'
spring-framework-javadoc: '{springjavadocurl}'
springhateoasversion: ${spring-hateoas}
springLdapVersion: ${spring-ldap}
releasetrainversion: ${releasetrain}
store: Ldap

BIN
src/main/asciidoc/images/epub-cover.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 39 KiB

11
src/main/asciidoc/images/epub-cover.svg
View File

File diff suppressed because one or more lines are too long
Side by Side

Before

Width:  |  Height:  |  Size: 8.8 KiB

31
src/main/asciidoc/index.adoc
View File

@@ -1,31 +0,0 @@
= Spring Data LDAP - Reference Documentation
Mattias Hellborg Arthursson; Ulrik Sandberg; Eric Dalquist; Keith Barlow; Rob Winch; Mark Paluch; Jay Bryant
:revnumber: {version}
:revdate: {localdate}
ifdef::backend-epub3[:front-cover-image: image:epub-cover.png[Front Cover,1050,1600]]
:spring-data-commons-docs: ../../../../spring-data-commons/src/main/asciidoc
:spring-framework-docs: {springDocsUrl}
:store: Ldap
(C) 2008-2022 The original authors.
NOTE: Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically.
include::preface.adoc[]
include::{spring-data-commons-docs}/upgrade.adoc[leveloffset=+1]
include::{spring-data-commons-docs}/dependencies.adoc[leveloffset=+1]
include::{spring-data-commons-docs}/repositories.adoc[leveloffset=+1]
[[reference]]
= Reference Documentation
include::reference/ldap-repositories.adoc[leveloffset=+1]
[[appendix]]
= Appendix
:numbered!:
include::{spring-data-commons-docs}/repository-namespace-reference.adoc[leveloffset=+1]
include::{spring-data-commons-docs}/repository-populator-namespace-reference.adoc[leveloffset=+1]
include::{spring-data-commons-docs}/repository-query-keywords-reference.adoc[leveloffset=+1]
include::{spring-data-commons-docs}/repository-query-return-types-reference.adoc[leveloffset=+1]

69
src/main/asciidoc/preface.adoc
View File

@@ -1,69 +0,0 @@
[[preface]]
= Preface
Spring Data LDAP makes it easier to build Spring-based applications that use the Lightweight Directory Access Protocol (LDAP).
This document is the reference guide for Spring Data - Document Support. It explains Document module concepts and semantics and the syntax for various data store namespaces.
[[get-started:first-steps:spring]]
== Knowing Spring
Spring Data uses the Spring Framework's {spring-framework-docs}core.html[core]
functionality, including:
* {spring-framework-docs}core.html#beans[IoC] container
* {spring-framework-docs}core.html#validation[validation, type conversion and data binding]
* {spring-framework-docs}core.html#expressions[expression language]
* {spring-framework-docs}core.html#aop[AOP]
* {spring-framework-docs}integration.html#jmx[JMX integration]
* {spring-framework-docs}data-access.html[DAO support]
* {spring-framework-docs}data-access.html#dao-exceptions[DAO Exception Hierarchy]
While it is not important to know the Spring APIs, understanding the concepts behind them is important. At a minimum, the idea
behind IoC should be familiar, no matter what IoC container you choose to use.
The core functionality of the LDAP support can be used directly, with no need to invoke the IoC services
of the Spring container. This is much like `JdbcTemplate`, which can be used 'standalone' without any other services
of the Spring container. To use all the features of Spring Data LDAP, such as the repository support,
you must configure some parts of the library by using Spring.
To learn more about Spring, you can refer to the comprehensive {spring-framework-docs}[documentation]
that explains the Spring Framework in detail. There are a lot of articles, blog entries, and books on Spring.
See the Spring Framework https://spring.io/projects/spring-framework/[home page] for more information.
While it is not important to know the Spring APIs, you do need to understand the concepts behind them. At a minimum, the idea behind IoC should be familiar for whatever IoC container you choose to use.
To learn more about Spring, you can refer to the comprehensive documentation that explains the Spring Framework in detail. You can find a lot of articles, blog entries, and books on Spring. See the Spring framework https://spring.io/projects[home page] for more information.
[[requirements]]
== Requirements
Spring Data LDAP 2.x binaries requires JDK level 8.0 or later, https://spring.io/projects/spring-framework/[Spring Framework] {springVersion} or later, and https://spring.io/projects/spring-ldap[Spring LDAP] {springLdapVersion} or later.
[[get-started:help]]
== Additional Help Resources
Learning a new framework is not always straight forward. In this section, we try to provide what we think is an easy-to-follow guide for starting with the Spring Data LDAP module. However, if you encounter issues or are looking for advice, try one or more of the following resources:
[[get-started:help:community]]
Community Forum::
Spring Data on Stackoverflow https://stackoverflow.com/questions/tagged/spring-data[Stack Overflow] is a tag for all of Spring Data (not just Document) users to share information and help each other. Note that registration is needed only for posting.
[[get-started:help:professional]]
Professional Support::
Professional, from-the-source support, with guaranteed response time, is available from https://pivotal.io/[Pivotal Sofware, Inc.], the company behind Spring and Spring Data.
[[get-started:up-to-date]]
=== Following Development
For information on the Spring Data LDAP source code repository, nightly builds, and snapshot artifacts, see the https://spring.io/projects/spring-data-ldap/[Spring Data LDAP homepage]. You can help make Spring Data best serve the needs of the Spring community by interacting with developers through the community on https://stackoverflow.com/questions/tagged/spring-data[Stackoverflow]. To follow developer activity, look for the mailing list information on the Spring Data LDAP homepage. If you encounter a bug or want to suggest an improvement, please create a ticket on the Spring Data issue https://github.com/spring-projects/spring-data-ldap/issues[tracker]. To stay up-to-date with the latest news and announcements in the Spring ecosystem, subscribe to the Spring Community https://spring.io[Portal]. Finally, you can follow the Spring https://spring.io/blog[blog] or the project team on Twitter (https://twitter.com/SpringData[SpringData]).
[[get-started:project-metadata]]
=== Project Metadata
* Version Control: https://github.com/spring-projects/spring-data-ldap
* Bugtracker: https://github.com/spring-projects/spring-data-ldap/issues
* Release repository: https://repo1.maven.org/maven2/
* Milestone repository: https://repo.spring.io/milestone/
* Snapshot repository: https://repo.spring.io/snapshot/

274
src/main/asciidoc/reference/ldap-repositories.adoc
View File

@@ -1,274 +0,0 @@
[[ldap.repositories]]
= LDAP Repositories
This chapter points out the specialties for repository support for LDAP. It builds on the core repository support explained in <<repositories>>. You should have a sound understanding of the basic concepts explained there.
You should keep in mind the following points as you work with Spring LDAP repositories:
* 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.
* To include support for `LdapQuery` parameters in automatically generated repositories, have your interface extend `LdapRepository` rather than `CrudRepository`.
* All Spring LDAP repositories must work with entities annotated with the ODM annotations, as described in https://docs.spring.io/spring-ldap/docs/{springLdapVersion}/reference/#odm[Object-Directory Mapping].
* 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`.
Indeed, the built-in `LdapRepository` only takes one type parameter: the managed entity class, which defaults the ID to `javax.naming.Name`.
* Due to specifics of the LDAP protocol, paging and sorting are not supported for Spring LDAP repositories.
NOTE: You must use ODM annotations, such as `org.springframework.ldap.odm.annotations.Id`. Using Spring Data's annotation does not work, because Spring LDAP uses its own mapping layer.
[[ldap.repo-usage]]
== Usage
To access domain entities stored in a LDAP-compliant directory, you can use our sophisticated repository support that significantly eases implementation. To do so, create an interface for your repository, as the following example shows:
.Sample Person entity
====
[source,java]
----
@Entry(objectClasses = { "person", "top" }, base="ou=someOu")
public class Person {
@Id
private Name dn;
@Attribute(name="cn")
@DnAttribute(value="cn", index=1)
private String fullName;
@Attribute(name="firstName")
private String firstName;
// No @Attribute annotation means this is bound to the LDAP attribute
// with the same value
private String firstName;
@DnAttribute(value="ou", index=0)
@Transient
private String company;
@Transient
private String someUnmappedField;
// ...more attributes below
}
----
====
We have a simple domain object here. Note that it has a property named `dn` of type `Name`. With that domain object, we can create a repository to persist objects of that type by defining an interface for it, as follows:
.Basic repository interface to persist `Person` entities
====
[source]
----
public interface PersonRepository extends CrudRepository<Person, Long> {
// additional custom finder methods go here
}
----
====
Right now, this interface serves only typing purposes, but we can add additional methods to it later. In your Spring configuration, add the following:
.General LDAP repository Spring configuration
====
.Java
[source,java,role="primary"]
----
@Configuration
@EnableLdapRepositories("com.acme.*.repositories")
class MyConfig {
@Bean
ContextSource contextSource() {
LdapContextSource ldapContextSource = new LdapContextSource();
ldapContextSource.setUserDn("cn=Admin");
ldapContextSource.setPassword("secret");
ldapContextSource.setUrl("ldap://127.0.0.1:389");
return ldapContextSource;
}
@Bean
LdapTemplate ldapTemplate(ContextSource contextSource) {
return new LdapTemplate(contextSource);
}
}
----
.XML
[source,xml,role="secondary"]
----
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:ldap="http://www.springframework.org/schema/ldap"
xmlns:data-ldap="http://www.springframework.org/schema/data/ldap"
xsi:schemaLocation="http://www.springframework.org/schema/beans
https://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/ldap
https://www.springframework.org/schema/ldap/spring-ldap.xsd
http://www.springframework.org/schema/data/ldap
https://www.springframework.org/schema/data/ldap/spring-ldap.xsd">
<ldap:context-source url="ldap://127.0.0.1:389"
username="cn=Admin"
password="secret" />
<ldap:ldap-template />
<data-ldap:repositories base-package="com.acme.*.repositories" />
</beans>
----
====
This configuration causes the base packages to be scanned for interfaces that extend `LdapRepository` and create Spring beans for each one found.
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.
If you want to go with Java configuration, use the `@EnableLdapRepositories` annotation. The annotation carries the same attributes as the namespace element. If no base package is configured, the infrastructure scans the package of the annotated configuration class.
Because our domain repository extends `CrudRepository`, it provides you with CRUD operations as well as methods for access to the entities. Working with the repository instance is a matter of dependency injecting it into a client.
We can add paging access to our repository, as follows:
.Paging access to Person entities
====
[source,java]
----
@ExtendWith({SpringExtension.class})
@ContextConfiguration
class PersonRepositoryTests {
@Autowired PersonRepository repository;
@Test
void readAll() {
List<Person> persons = repository.findAll();
assertThat(persons.isEmpty(), is(false));
}
}
----
====
The sample creates an application context with Spring's unit test support, which will perform annotation-based dependency injection into test cases. Inside the test method, we use the repository to query the datastore.
[[ldap.repositories.queries]]
== Query Methods
Most of the data access operations you usually trigger on a repository result in a query being run against the LDAP directory. Defining such a query is a matter of declaring a method on the repository interface, as the following example shows:
.PersonRepository with query methods
====
[source,java]
----
interface PersonRepository extends PagingAndSortingRepository<Person, String> {
List<Person> findByLastname(String lastname); <1>
List<Person> findByLastnameFirstname(String lastname, String firstname); <2>
}
----
<1> The method shows a query for all people with the given `lastname`. The query is derived by parsing the method name for constraints that can be concatenated with `And` and `Or`. Thus, the method name results in a query expression of `(&(objectclass=person)(lastname=lastname))`.
<2> The method shows a query for all people with the given `lastname` and `firstname`. The query is derived by parsing the method name. Thus, the method name results in a query expression of `(&(objectclass=person)(lastname=lastname)(firstname=firstname))`.
====
The following table provides samples of the keywords that you can use with query methods:
[cols="1,2,3", options="header"]
.Supported keywords for query methods
|===
| Keyword
| Sample
| Logical result
| `LessThanEqual`
| `findByAgeLessThanEqual(int age)`
| `(attribute<=age)`
| `GreaterThanEqual`
| `findByAgeGreaterThanEqual(int age)`
| `(attribute>=age)`
| `IsNotNull`, `NotNull`
| `findByFirstnameNotNull()`
| `(firstname=*)`
| `IsNull`, `Null`
| `findByFirstnameNull()`
| `(!(firstname=*))`
| `Like`
| `findByFirstnameLike(String name)`
| `(firstname=name)`
| `NotLike`, `IsNotLike`
| `findByFirstnameNotLike(String name)`
| `(!(firstname=name*))`
| `StartingWith`
| `findByStartingWith(String name)`
| `(firstname=name*)`
| `EndingWith`
| `findByFirstnameLike(String name)`
| `(firstname=*name)`
| `Containing`
| `findByFirstnameLike(String name)`
| `(firstname=\*name*)`
| `(No keyword)`
| `findByFirstname(String name)`
| `(Firstname=name)`
| `Not`
| `findByFirstnameNot(String name)`
| `(!(Firstname=name))`
|===
include::../{spring-data-commons-docs}/repository-projections.adoc[leveloffset=+2]
=== QueryDSL Support
Basic QueryDSL support is included in Spring LDAP. This support includes the following:
* An Annotation Processor, `LdapAnnotationProcessor`, for generating QueryDSL classes based on Spring LDAP ODM annotations. See https://docs.spring.io/spring-ldap/docs/{springLdapVersion}/reference/#odm[Object-Directory Mapping] for more information on the ODM annotations.
* A Query implementation, `QueryDslLdapQuery`, for building and running QueryDSL queries in code.
* Spring Data repository support for QueryDSL predicates. `QueryDslPredicateExecutor` includes a number of additional methods with appropriate parameters. You can extend this interface (along with `LdapRepository`) to include this support in your repository.
[[ldap.repositories.misc]]
== Miscellaneous
[[ldap.repositories.misc.cdi-integration]]
=== CDI Integration
Instances of the repository interfaces are usually created by a container, for which Spring is the most natural choice when working with Spring Data. As of version 2.1, Spring Data LDAP includes a custom CDI extension that lets you use the repository abstraction in CDI environments. The extension is part of the JAR. To activate it, drop the Spring Data LDAP JAR into your classpath. You can now set up the infrastructure by implementing a CDI Producer for the `LdapTemplate`, as the following example shows:
[source,java]
----
class LdapTemplateProducer {
@Produces
@ApplicationScoped
public LdapOperations createLdapTemplate() {
ContextSource contextSource = …
return new LdapTemplate(contextSource);
}
}
----
The Spring Data LDAP CDI extension picks up the `LdapTemplate` as a CDI bean and creates a proxy for a Spring Data repository whenever a bean of a repository type is requested by the container. Thus, obtaining an instance of a Spring Data repository is a matter of declaring an injected property, as the following example shows:
[source,java]
----
class RepositoryClient {
@Inject
PersonRepository repository;
public void businessMethod() {
List<Person> people = repository.findAll();
}
}
----