Skip to content

Commit f43b662

Browse files
mp911demp911de
committed
Migrate documentation site to Antora.
Closes #425
1 parent bb56267 commit f43b662

32 files changed

+500
-405
lines changed

‎.gitignore

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,3 +15,7 @@ src/ant/.ant-targets-upload-dist.xml
1515
atlassian-ide-plugin.xml
1616
/.gradle/
1717
/.idea/
18+
package.json
19+
package-lock.json
20+
node
21+
node_modules

‎pom.xml

Lines changed: 25 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
2-
<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">
2+
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
3+
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
34

45
<modelVersion>4.0.0</modelVersion>
56

@@ -134,25 +135,6 @@
134135
<groupId>org.apache.maven.plugins</groupId>
135136
<artifactId>maven-assembly-plugin</artifactId>
136137
</plugin>
137-
<plugin>
138-
<groupId>org.asciidoctor</groupId>
139-
<artifactId>asciidoctor-maven-plugin</artifactId>
140-
<configuration>
141-
<attributes>
142-
<version>${project.version}</version>
143-
<projectName>${project.name}</projectName>
144-
<projectVersion>${project.version}</projectVersion>
145-
<aspectjVersion>${aspectj}</aspectjVersion>
146-
<querydslVersion>${querydsl}</querydslVersion>
147-
<springVersion>${spring}</springVersion>
148-
<releasetrainVersion>${releasetrain}</releasetrainVersion>
149-
<springLdapVersion>${spring-ldap}</springLdapVersion>
150-
<allow-uri-read>true</allow-uri-read>
151-
<toclevels>3</toclevels>
152-
<numbered>true</numbered>
153-
</attributes>
154-
</configuration>
155-
</plugin>
156138
</plugins>
157139
</build>
158140

@@ -163,6 +145,29 @@
163145
<spring-ldap>2.3.2.BUILD-SNAPSHOT</spring-ldap>
164146
</properties>
165147
</profile>
148+
<profile>
149+
<id>antora</id>
150+
<build>
151+
<plugins>
152+
<plugin>
153+
<groupId>io.spring.maven.antora</groupId>
154+
<artifactId>antora-maven-plugin</artifactId>
155+
</plugin>
156+
</plugins>
157+
</build>
158+
</profile>
159+
160+
<profile>
161+
<id>antora-process-resources</id>
162+
<build>
163+
<resources>
164+
<resource>
165+
<directory>src/main/antora/resources/antora-resources</directory>
166+
<filtering>true</filtering>
167+
</resource>
168+
</resources>
169+
</build>
170+
</profile>
166171
</profiles>
167172

168173
<repositories>

‎src/main/antora/antora-playbook.yml

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# PACKAGES [email protected] @antora/atlas-extension:1.0.0-alpha.1 @antora/[email protected] @springio/[email protected] @asciidoctor/[email protected] @opendevise/[email protected]
2+
#
3+
# The purpose of this Antora playbook is to build the docs in the current branch.
4+
antora:
5+
extensions:
6+
- '@antora/collector-extension'
7+
- require: '@springio/antora-extensions/root-component-extension'
8+
root_component_name: 'data-ldap'
9+
site:
10+
title: Spring Data LDAP
11+
url: https://docs.spring.io/spring-data-ldap/reference/
12+
content:
13+
sources:
14+
- url: ./../../..
15+
branches: HEAD
16+
start_path: src/main/antora
17+
worktrees: true
18+
- url: https://github.com/spring-projects/spring-data-commons
19+
# Refname matching:
20+
# https://docs.antora.org/antora/latest/playbook/content-refname-matching/
21+
branches: [ main, 3.2.x ]
22+
start_path: src/main/antora
23+
asciidoc:
24+
attributes:
25+
page-pagination: ''
26+
hide-uri-scheme: '@'
27+
tabs-sync-option: '@'
28+
chomp: 'all'
29+
extensions:
30+
- '@asciidoctor/tabs'
31+
- '@springio/asciidoctor-extensions'
32+
sourcemap: true
33+
urls:
34+
latest_version_segment: ''
35+
runtime:
36+
log:
37+
failure_level: warn
38+
format: pretty
39+
ui:
40+
bundle:
41+
url: https://github.com/spring-io/antora-ui-spring/releases/download/v0.3.3/ui-bundle.zip
42+
snapshot: true

‎src/main/antora/antora.yml

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
name: data-ldap
2+
version: true
3+
title: Spring Data LDAP
4+
nav:
5+
- modules/ROOT/nav.adoc
6+
ext:
7+
collector:
8+
- run:
9+
command: ./mvnw validate process-resources -am -Pantora-process-resources
10+
local: true
11+
scan:
12+
dir: target/classes/

‎src/main/antora/modules/ROOT/nav.adoc

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
* xref:index.adoc[Overview]
2+
** xref:commons/upgrade.adoc[]
3+
* xref:repositories/introduction.adoc[]
4+
** xref:repositories/core-concepts.adoc[]
5+
** xref:repositories/definition.adoc[]
6+
** xref:repositories/create-instances.adoc[]
7+
** xref:repositories/query-methods-details.adoc[]
8+
** xref:repositories/projections.adoc[]
9+
** xref:repositories/custom-implementations.adoc[]
10+
** xref:repositories/core-domain-events.adoc[]
11+
** xref:repositories/core-extensions.adoc[]
12+
** xref:repositories/null-handling.adoc[]
13+
** xref:repositories/namespace-reference.adoc[]
14+
** xref:repositories/query-keywords-reference.adoc[]
15+
** xref:repositories/query-return-types-reference.adoc[]
16+
* xref:ldap.adoc[]
17+
** xref:ldap/configuration.adoc[]
18+
** xref:ldap/usage.adoc[]
19+
** xref:ldap/query-methods.adoc[]
20+
** xref:ldap/querydsl.adoc[]
21+
** xref:ldap/cdi-integration.adoc[]
22+
* https://github.com/spring-projects/spring-data-commons/wiki[Wiki]

‎src/main/antora/modules/ROOT/pages/commons/upgrade.adoc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
include::{commons}@data-commons::page$upgrade.adoc[]

‎src/main/antora/modules/ROOT/pages/index.adoc

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
[[spring-data-ldap-reference-documentation]]
2+
= Spring Data LDAP
3+
:revnumber: {version}
4+
:revdate: {localdate}
5+
:feature-scroll: true
6+
7+
_Spring Data LDAP provides repository support for Lightweight Directory Access Protocol (LDAP).
8+
It eases development of applications with a consistent programming model that need to access LDAP data sources._
9+
10+
[horizontal]
11+
xref:repositories/introduction.adoc[Introduction] :: Introduction to Spring Data Repositories
12+
xref:ldap.adoc[LDAP] :: LDAP and LDAP Repositories
13+
https://github.com/spring-projects/spring-data-commons/wiki[Wiki] :: What's New, Upgrade Notes, Supported Versions, additional cross-version information.
14+
15+
Mattias Hellborg Arthursson, Ulrik Sandberg, Eric Dalquist, Keith Barlow, Rob Winch, Mark Paluch, Jay Bryant
16+
17+
(C) 2008-2023 VMware, Inc.
18+
19+
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.
20+

‎src/main/antora/modules/ROOT/pages/ldap.adoc

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
[[ldap.repositories]]
2+
= LDAP Repositories
3+
:page-section-summary-toc: 1
4+
5+
This chapter points out the specialties for repository support for LDAP.
6+
It builds on the core repository support explained in xref:repositories/introduction.adoc[Working with Spring Data Repositories].
7+
You should have a sound understanding of the basic concepts explained there.
8+

‎src/main/antora/modules/ROOT/pages/ldap/cdi-integration.adoc

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
[[ldap.repositories.cdi-integration]]
2+
= CDI Integration
3+
4+
Instances of the repository interfaces are usually created by a container, for which Spring is the most natural choice when working with Spring Data.
5+
Spring Data LDAP includes a custom CDI extension that lets you use the repository abstraction in CDI environments.
6+
The extension is part of the JAR.
7+
To activate it, drop the Spring Data LDAP JAR into your classpath.
8+
You can now set up the infrastructure by implementing a CDI Producer for the `LdapTemplate`, as the following example shows:
9+
10+
[source,java]
11+
----
12+
class LdapTemplateProducer {
13+
14+
@Produces
15+
@ApplicationScoped
16+
public LdapOperations createLdapTemplate() {
17+
18+
ContextSource contextSource = …
19+
return new LdapTemplate(contextSource);
20+
}
21+
}
22+
----
23+
24+
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.
25+
Thus, obtaining an instance of a Spring Data repository is a matter of declaring an injected property, as the following example shows:
26+
27+
[source,java]
28+
----
29+
class RepositoryClient {
30+
31+
@Inject
32+
PersonRepository repository;
33+
34+
public void businessMethod() {
35+
List<Person> people = repository.findAll();
36+
}
37+
}
38+
----

‎src/main/antora/modules/ROOT/pages/ldap/configuration.adoc

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
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

Comments
 (0)