Skip to content

Commit 3efd289

Browse files
jzheauxjzheaux
committed
Update Getting Started Docs
1 parent 4bf068e commit 3efd289

File tree

4 files changed

+342
-1
lines changed

4 files changed

+342
-1
lines changed

‎build.gradle

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,10 @@ antora {
5151

5252
tasks.named("generateAntoraYml") {
5353
asciidocAttributes = project.provider( {
54-
return ['project-version': project.version]
54+
return [
55+
'project-version': project.version,
56+
'spring-core-version': '6.1.6'
57+
]
5558
} )
5659
}
5760

‎modules/ROOT/pages/community.adoc

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
[[community]]
2+
= Spring Security Community
3+
4+
Welcome to the Spring Security Community!
5+
This section discusses how you can make the most of our vast community.
6+
7+
8+
[[community-help]]
9+
== Getting Help
10+
If you need help with Spring Security, we are here to help.
11+
The following are some of the best ways to get help:
12+
13+
* Read through this documentation.
14+
* Try one of our many https://github.com/spring-projects/spring-ldap-samples[sample applications].
15+
* Ask a question on https://stackoverflow.com/questions/tagged/spring-security[https://stackoverflow.com] with the `spring-security` tag.
16+
* Report bugs and enhancement requests at https://github.com/spring-projects/spring-security/issues
17+
18+
[[community-becoming-involved]]
19+
== Becoming Involved
20+
We welcome your involvement in the Spring Security project.
21+
There are many ways to contribute, including answering questions on Stack Overflow, writing new code, improving existing code, assisting with documentation, developing samples or tutorials, reporting bugs, or simply making suggestions.
22+
For more information, see our https://github.com/spring-projects/spring-security/blob/main/CONTRIBUTING.adoc[Contributing] documentation.
23+
24+
[[community-source]]
25+
== Source Code
26+
27+
You can find Spring Security's source code on GitHub at https://github.com/spring-projects/spring-security/
28+
29+
[[community-license]]
30+
== Apache 2 License
31+
32+
Spring Security is Open Source software released under the https://www.apache.org/licenses/LICENSE-2.0.html[Apache 2.0 license].
33+
34+
== Social Media
35+
36+
You can follow https://twitter.com/SpringSecurity[@SpringSecurity] and the https://twitter.com/SpringSecurity/lists/team[Spring Security team] on Twitter to stay up to date with the latest news.
37+
You can also follow https://twitter.com/SpringCentral[@SpringCentral] to keep up to date with the entire Spring portfolio.

‎modules/ROOT/pages/getting-spring-ldap.adoc

Lines changed: 289 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,289 @@
1+
[[getting]]
2+
= Getting Spring LDAP
3+
4+
This section describes how to get the Spring LDAP binaries.
5+
See xref:community.adoc#community-source[Source Code] for how to obtain the source code.
6+
7+
== Release Numbering
8+
9+
Spring LDAP versions are formatted as MAJOR.MINOR.PATCH such that:
10+
11+
* MAJOR versions may contain breaking changes.
12+
Typically, these are done to provide improved security to match modern security practices.
13+
* MINOR versions contain enhancements but are considered passive updates.
14+
* PATCH level should be perfectly compatible, forwards and backwards, with the possible exception of changes that fix bugs.
15+
16+
17+
[[maven]]
18+
== Usage
19+
20+
As most open source projects, Spring LDAP deploys its dependencies as Maven artifacts, which makes them compatible with both Maven and Gradle. The following sections demonstrate how to integrate Spring LDAP with these build tools, with examples for Spring Boot and standalone usage.
21+
22+
[[getting-maven-boot]]
23+
[[getting-gradle-boot]]
24+
=== Spring Boot
25+
26+
Spring Boot provides a `spring-boot-starter-ldap` starter that aggregates Spring LDAP-related dependencies.
27+
The simplest and preferred way to use the starter is to use https://docs.spring.io/initializr/docs/current/reference/html/[Spring Initializr] by using an IDE integration in (https://joshlong.com/jl/blogPost/tech_tip_geting_started_with_spring_boot.html[Eclipse] or https://www.jetbrains.com/help/idea/spring-boot.html#d1489567e2[IntelliJ], https://github.com/AlexFalappa/nb-springboot/wiki/Quick-Tour[NetBeans]) or through https://start.spring.io.
28+
Alternatively, you can manually add the starter, as the following example shows:
29+
30+
[tabs]
31+
======
32+
Maven::
33+
+
34+
.pom.xml
35+
[source,xml,subs="verbatim,attributes"]
36+
----
37+
<dependencies>
38+
<!-- ... other dependency elements ... -->
39+
<dependency>
40+
<groupId>org.springframework.boot</groupId>
41+
<artifactId>spring-boot-starter-ldap</artifactId>
42+
</dependency>
43+
</dependencies>
44+
----
45+
46+
Gradle::
47+
+
48+
.build.gradle
49+
[source,groovy]
50+
[subs="verbatim,attributes"]
51+
----
52+
dependencies {
53+
implementation "org.springframework.boot:spring-boot-starter-ldap"
54+
}
55+
----
56+
======
57+
58+
Since Spring Boot provides a Maven BOM to manage dependency versions, you do not need to specify a version.
59+
If you wish to override the Spring LDAP version, you can do so with a build property as shown below:
60+
61+
[tabs]
62+
======
63+
Maven::
64+
+
65+
.pom.xml
66+
[source,xml,subs="verbatim,attributes"]
67+
----
68+
<properties>
69+
<!-- ... -->
70+
<spring-ldap.version>{project-version}</spring-ldap.version>
71+
</properties>
72+
----
73+
74+
Gradle::
75+
+
76+
.build.gradle
77+
[source,groovy]
78+
[subs="verbatim,attributes"]
79+
----
80+
ext['spring-ldap.version']='{project-version}'
81+
----
82+
======
83+
84+
Since Spring LDAP makes breaking changes only in major releases, you can safely use a newer version of Spring LDAP with Spring Boot.
85+
However, at times, you may need to update the version of Spring Framework as well.
86+
You can do so by adding a build property like so:
87+
88+
[tabs]
89+
======
90+
Maven::
91+
+
92+
.pom.xml
93+
[source,xml,subs="verbatim,attributes"]
94+
----
95+
<properties>
96+
<!-- ... -->
97+
<spring.version>{spring-core-version}</spring.version>
98+
</properties>
99+
----
100+
101+
Gradle::
102+
+
103+
.build.gradle
104+
[source,groovy]
105+
[subs="verbatim,attributes"]
106+
----
107+
ext['spring.version']='{spring-core-version}'
108+
----
109+
======
110+
111+
If you use additional features (such as LDIF), you need to also include the appropriate xref:modules.adoc#modules[modules].
112+
113+
[[getting-maven-no-boot]]
114+
=== Standalone Usage (Without Spring Boot)
115+
116+
When you use Spring LDAP without Spring Boot, you must specify the version you intend to use:.
117+
118+
[tabs]
119+
======
120+
Maven::
121+
+
122+
.pom.xml
123+
[source,xml,ubs="verbatim,attributes"]
124+
----
125+
<dependencyManagement>
126+
<dependencies>
127+
<!-- ... other dependency elements ... -->
128+
<dependency>
129+
<groupId>org.springframework.ldap</groupId>
130+
<artifactId>spring-ldap-core</artifactId>
131+
<version>{project-version}</version>
132+
</dependency>
133+
</dependencies>
134+
</dependencyManagement>
135+
----
136+
137+
Gradle::
138+
+
139+
.build.gradle
140+
[source,groovy]
141+
[subs="verbatim,attributes"]
142+
----
143+
plugins {
144+
id "io.spring.dependency-management" version "1.0.6.RELEASE"
145+
}
146+
147+
dependencyManagement {
148+
imports {
149+
mavenBom 'org.springframework.ldap:spring-ldap-core:{project-version}'
150+
}
151+
}
152+
----
153+
======
154+
155+
[TIP]
156+
Spring provides a https://github.com/spring-gradle-plugins/dependency-management-plugin[`Dependency Management Plugin`] for Gradle
157+
158+
For most projects, including `spring-ldap-core` is sufficient.
159+
160+
If you use additional features (such as LDIF), you need to also include the appropriate xref:modules.adoc#modules[modules].
161+
162+
Spring LDAP builds against Spring Framework 6 but should generally work with any newer version of Spring Framework 5.x.
163+
Many users are likely to run afoul of the fact that Spring LDAP's transitive dependencies resolve Spring Framework 6, which can cause strange classpath problems.
164+
The easiest way to resolve this is to use the `spring-framework-bom` within the `<dependencyManagement>` section of your `pom.xml` or your `dependencyManagement` section of your `build.gradle`.
165+
166+
[tabs]
167+
======
168+
Maven::
169+
+
170+
.pom.xml
171+
[source,xml,subs="verbatim,attributes"]
172+
----
173+
<dependencyManagement>
174+
<dependencies>
175+
<!-- ... other dependency elements ... -->
176+
<dependency>
177+
<groupId>org.springframework</groupId>
178+
<artifactId>spring-framework-bom</artifactId>
179+
<version>{spring-core-version}</version>
180+
<type>pom</type>
181+
<scope>import</scope>
182+
</dependency>
183+
</dependencies>
184+
</dependencyManagement>
185+
----
186+
187+
Gradle::
188+
+
189+
.build.gradle
190+
[source,groovy]
191+
[subs="verbatim,attributes"]
192+
----
193+
plugins {
194+
id "io.spring.dependency-management" version "1.0.6.RELEASE"
195+
}
196+
197+
dependencyManagement {
198+
imports {
199+
mavenBom 'org.springframework:spring-framework-bom:{spring-core-version}'
200+
}
201+
}
202+
----
203+
======
204+
205+
[TIP]
206+
Spring provides a https://github.com/spring-gradle-plugins/dependency-management-plugin[`Dependency Management Plugin`] for Gradle
207+
208+
The preceding example ensures that all the transitive dependencies of Spring LDAP use the Spring 6 modules.
209+
210+
[NOTE]
211+
====
212+
This approach uses Maven's "`bill of materials`" (BOM) concept and is only available in Maven 2.0.9+.
213+
For additional details about how dependencies are resolved, see https://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html[Maven's Introduction to the Dependency Mechanism documentation].
214+
====
215+
216+
[[maven-repositories]]
217+
=== Maven Repositories
218+
All https://github.com/spring-projects/spring-security/wiki/Release-Schedule-Guidelines[GA releases] are deployed to Maven Central, so you need not declare additional Maven repositories in your build configuration.
219+
220+
For Gradle using the `mavenCentral()` repository is sufficient for GA releases.
221+
222+
.build.gradle
223+
[source,groovy]
224+
----
225+
repositories {
226+
mavenCentral()
227+
}
228+
----
229+
230+
If you use a SNAPSHOT version, you need to ensure that you have the Spring Snapshot repository defined:
231+
232+
[tabs]
233+
======
234+
Maven::
235+
+
236+
.pom.xml
237+
[source,xml]
238+
----
239+
<repositories>
240+
<!-- ... possibly other repository elements ... -->
241+
<repository>
242+
<id>spring-snapshot</id>
243+
<name>Spring Snapshot Repository</name>
244+
<url>https://repo.spring.io/snapshot</url>
245+
</repository>
246+
</repositories>
247+
----
248+
249+
Gradle::
250+
+
251+
.build.gradle
252+
[source,groovy]
253+
----
254+
repositories {
255+
maven { url 'https://repo.spring.io/snapshot' }
256+
}
257+
----
258+
======
259+
260+
If you use a milestone or release candidate version, you need to ensure that you have the Spring Milestone repository defined, as the following example shows:
261+
262+
[tabs]
263+
======
264+
Maven::
265+
+
266+
.pom.xml
267+
[source,xml]
268+
----
269+
<repositories>
270+
<!-- ... possibly other repository elements ... -->
271+
<repository>
272+
<id>spring-milestone</id>
273+
<name>Spring Milestone Repository</name>
274+
<url>https://repo.spring.io/milestone</url>
275+
</repository>
276+
</repositories>
277+
----
278+
279+
Gradle::
280+
+
281+
.build.gradle
282+
[source,groovy]
283+
----
284+
repositories {
285+
maven { url 'https://repo.spring.io/milestone' }
286+
}
287+
----
288+
======
289+

‎modules/ROOT/pages/modules.adoc

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
// FIXME: This might make sense in Getting Spring Security along with the artifact information
2+
3+
[[modules]]
4+
= Project Modules
5+
Spring LDAP is broken up into the following separate modules:
6+
7+
* spring-ldap-core - the xref:spring-ldap-basic-usage.adoc[core] Spring LDAP library, including xref:odm.adoc[the ODM framework]
8+
* spring-ldap-test - support classes that help LDAP with xref:testing.adoc[integration testing]
9+
* spring-ldap-ldif-core - the Spring LDAP xref:ldif-parsing.adoc[LDIF parsing library]
10+
* spring-ldap-ldif-batch - the Spring Batch integration layer for the LDIF parsing library
11+
12+
Also of interest is https://docs.spring.io/spring-data/ldap/reference[spring-data-ldap], Spring Data's integration with Spring LDAP.

0 commit comments

Comments
 (0)