Skip to content

Commit 36ec890

Browse files
odrotbohmodrotbohm
committed
GH-550 - Rearrange sections in reference doc.
The exclusion of types from the Application Modules model is now described in the section about the ApplicationModules type already. That general section is now located before the discussion of simple and advanced modules. The verification section now mentions the behavior for open modules as well.
1 parent 03e152d commit 36ec890

File tree

2 files changed

+98
-91
lines changed

2 files changed

+98
-91
lines changed

‎src/docs/antora/modules/ROOT/pages/fundamentals.adoc

Lines changed: 97 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,14 @@
11
[[fundamentals]]
22
= Fundamentals
3+
:toc:
4+
:toclevels: 3
35

46
Spring Modulith supports developers implementing logical modules in Spring Boot applications.
57
It allows them to apply structural validation, document the module arrangement, run integration tests for individual modules, observe the modules' interaction at runtime, and generally implement module interaction in a loosely coupled way.
68
This section will discuss the fundamental concepts that developers need to understand before diving into the technical support.
79

810
[[modules]]
9-
== Application modules
11+
== Application Modules
1012

1113
In a Spring Boot application, an application module is a unit of functionality that consists of the following parts:
1214

@@ -17,6 +19,100 @@ In a Spring Boot application, an application module is a unit of functionality t
1719
Spring Moduliths provides different ways of expressing modules within Spring Boot applications, primarily differing in the level of complexity involved in the overall arrangement.
1820
This allows developers to start simple and naturally move to more sophisticated means as and if needed.
1921

22+
[[modules.application-modules]]
23+
=== The `ApplicationModules` Type
24+
25+
Spring Moduliths allows to inspect a codebase to derive an application module model based on the given arrangement and optional configuration.
26+
The `spring-modulith-core` artifact contains `ApplicationModules` that can be pointed to a Spring Boot application class:
27+
28+
.Creating an application module model
29+
[tabs]
30+
======
31+
Java::
32+
+
33+
[source, java, role="primary"]
34+
----
35+
var modules = ApplicationModules.of(Application.class);
36+
----
37+
Kotlin::
38+
+
39+
[source, kotlin, role="secondary"]
40+
----
41+
var modules = ApplicationModules.of(Application::class)
42+
----
43+
======
44+
The `modules` will contain an in-memory representation of the application module arrangement derived from the codebase.
45+
Which parts of that will be detected as a module depends on the Java package structure underneath the package the class pointed to resides in.
46+
Find out more about the arrangement expected by default in xref:fundamentals.adoc#modules.simple[].
47+
Advanced arrangements and customization options are described in xref:fundamentals.adoc#modules.advanced[] and
48+
49+
To get an impression of what the analyzed arrangement looks like, we can just write the individual modules contained in the overall model to the console:
50+
51+
.Writing the application module arrangement to the console
52+
[tabs]
53+
======
54+
Java::
55+
+
56+
[source, java, role="primary"]
57+
----
58+
modules.forEach(System.out::println);
59+
----
60+
Kotlin::
61+
+
62+
[source, kotlin, role="secondary"]
63+
----
64+
modules.forEach(println(it))
65+
----
66+
======
67+
.The console output of our application module arrangement
68+
[source]
69+
----
70+
## example.inventory ##
71+
> Logical name: inventory
72+
> Base package: example.inventory
73+
> Spring beans:
74+
+ ….InventoryManagement
75+
o ….SomeInternalComponent
76+
77+
## example.order ##
78+
> Logical name: order
79+
> Base package: example.order
80+
> Spring beans:
81+
+ ….OrderManagement
82+
+ ….internal.SomeInternalComponent
83+
----
84+
85+
Note how each module is listed, the contained Spring components are identified, and the respective visibility is rendered, too.
86+
87+
[[modules.excluding-packages]]
88+
==== Excluding Packages
89+
90+
In case you would like to exclude certain Java classes or full packages from the application module inspection, you can do so with:
91+
92+
[tabs]
93+
======
94+
Java::
95+
+
96+
[source, java, role="primary"]
97+
----
98+
ApplicationModules.of(Application.class, JavaClass.Predicates.resideInAPackage("com.example.db")).verify();
99+
----
100+
Kotlin::
101+
+
102+
[source, kotlin, role="secondary"]
103+
----
104+
ApplicationModules.of(Application::class, JavaClass.Predicates.resideInAPackage("com.example.db")).verify()
105+
----
106+
======
107+
108+
Additional examples of exclusions:
109+
110+
* `com.example.db` -- Matches all files in the given package `com.example.db`.
111+
* `com.example.db..` -- Matches all files in the given package (`com.example.db`) and all sub-packages (`com.example.db.a` or `com.example.db.b.c`).
112+
* `..example..` -- Matches `a.example`, `a.example.b` or `a.b.example.c.d`, but not `a.exam.b`
113+
114+
Full details about possible matchers can be found in the JavaDoc of ArchUnit https://github.com/TNG/ArchUnit/blob/main/archunit/src/main/java/com/tngtech/archunit/core/domain/PackageMatcher.java[`PackageMatcher`].
115+
20116
[[modules.simple]]
21117
=== Simple Application Modules
22118

@@ -145,66 +241,6 @@ class ModuleMetadata {}
145241
In this case code within the __inventory__ module was only allowed to refer to code in the __order__ module (and code not assigned to any module in the first place).
146242
Find out about how to monitor that in xref:verification.adoc[Verifying Application Module Structure].
147243

148-
[[modules.application-modules]]
149-
=== The `ApplicationModules` Type
150-
151-
Spring Moduliths allows to inspect a codebase to derive an application module model based on the given arrangement and optional configuration.
152-
The `spring-modulith-core` artifact contains `ApplicationModules` that can be pointed to a Spring Boot application class:
153-
154-
.Creating an application module model
155-
[tabs]
156-
======
157-
Java::
158-
+
159-
[source, java, role="primary"]
160-
----
161-
var modules = ApplicationModules.of(Application.class);
162-
----
163-
Kotlin::
164-
+
165-
[source, kotlin, role="secondary"]
166-
----
167-
var modules = ApplicationModules.of(Application::class)
168-
----
169-
======
170-
To get an impression of what the analyzed arrangement looks like, we can just write the individual modules contained in the overall model to the console:
171-
172-
.Writing the application module arrangement to the console
173-
[tabs]
174-
======
175-
Java::
176-
+
177-
[source, java, role="primary"]
178-
----
179-
modules.forEach(System.out::println);
180-
----
181-
Kotlin::
182-
+
183-
[source, kotlin, role="secondary"]
184-
----
185-
modules.forEach(println(it))
186-
----
187-
======
188-
.The console output of our application module arrangement
189-
[source]
190-
----
191-
## example.inventory ##
192-
> Logical name: inventory
193-
> Base package: example.inventory
194-
> Spring beans:
195-
+ ….InventoryManagement
196-
o ….SomeInternalComponent
197-
198-
## example.order ##
199-
> Logical name: order
200-
> Base package: example.order
201-
> Spring beans:
202-
+ ….OrderManagement
203-
+ ….internal.SomeInternalComponent
204-
----
205-
206-
Note how each module is listed, the contained Spring components are identified, and the respective visibility is rendered, too.
207-
208244
[[modules.named-interfaces]]
209245
=== Named Interfaces
210246

‎src/docs/antora/modules/ROOT/pages/verification.adoc

Lines changed: 1 addition & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -24,38 +24,9 @@ The verification includes the following rules:
2424
* _No cycles on the application module level_ -- the dependencies between modules have to form a directed acyclic graph.
2525
* _Efferent module access via API packages only_ -- all references to types that reside in application module internal packages are rejected.
2626
See xref:fundamentals.adoc#modules.advanced[Advanced Application Modules] for details.
27+
Dependencies into internals of xref:fundamentals.adoc#modules.advanced.open[Open Application Modules] are allowed.
2728
* _Explicitly allowed application module dependencies only_ (optional) -- an application module can optionally define allowed dependencies via `@ApplicationModule(allowedDependencies = …)`.
2829
If those are configured, dependencies to other application modules are rejected.
2930
See xref:fundamentals.adoc#modules.explicit-dependencies[Explicit Application Module Dependencies] and xref:fundamentals.adoc#modules.named-interfaces[Named Interfaces] for details.
3031

3132
Spring Modulith optionally integrates with the jMolecules ArchUnit library and, if present, automatically triggers its Domain-Driven Design verification rules described https://github.com/xmolecules/jmolecules-integrations/tree/main/jmolecules-archunit[here].
32-
33-
[[excluding-packages]]
34-
== Excluding Packages
35-
36-
In case you would like to exclude certain Java classes or full packages from the application module inspection, you can do so with:
37-
38-
[tabs]
39-
======
40-
Java::
41-
+
42-
[source, java, role="primary"]
43-
----
44-
ApplicationModules.of(Application.class, JavaClass.Predicates.resideInAPackage("com.example.db")).verify();
45-
----
46-
Kotlin::
47-
+
48-
[source, kotlin, role="secondary"]
49-
----
50-
ApplicationModules.of(Application::class, JavaClass.Predicates.resideInAPackage("com.example.db")).verify()
51-
----
52-
======
53-
54-
Additional examples of exclusions:
55-
56-
* `com.example.db` -- Matches all files in the given package `com.example.db`.
57-
* `com.example.db..` -- Matches all files in the given package (`com.example.db`) and all sub-packages (`com.example.db.a` or `com.example.db.b.c`).
58-
* `..example..` -- Matches `a.example`, `a.example.b` or `a.b.example.c.d`, but not `a.exam.b`
59-
60-
Full details about possible matchers can be found in the JavaDoc of ArchUnit https://github.com/TNG/ArchUnit/blob/main/archunit/src/main/java/com/tngtech/archunit/core/domain/PackageMatcher.java[`PackageMatcher`].
61-

0 commit comments

Comments
 (0)