You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: src/docs/asciidoc/10-fundamentals.adoc
+10-9Lines changed: 10 additions & 9 deletions
Original file line number
Diff line number
Diff line change
@@ -12,17 +12,17 @@ In a Spring Boot application, an application module is a unit of functionality t
12
12
13
13
* An API exposed to other modules implemented by Spring bean instances and application events published by the module, usually referred to as _provided interface_.
14
14
* Internal implementation components that are not supposed to be accessed by other modules.
15
-
* References to API exposed by other modules in the form of Spring bean dependencies, application events listened to and configuration properties exposed.
15
+
* References to API exposed by other modules in the form of Spring bean dependencies, application events listened to and configuration properties exposed, usually referred to as _required interface_.
16
16
17
-
Spring Moduliths provides different ways of expressing modules, primarily differing in the level of complexity involved in the overall arrangement.
17
+
Spring Moduliths provides different ways of expressing modules within Spring Boot applications, primarily differing in the level of complexity involved in the overall arrangement.
18
18
This allows developers to start simple and naturally move to more sophisticated means as and if needed.
19
19
20
20
[[fundamentals.modules.simple]]
21
21
=== Simple Application Modules
22
22
23
-
The application's main package is the one that the main application class resides in.
24
-
The class, that is annotated with `@SpringBootApplication` and usually contains the `main(…)` method used to run it.
25
-
By default, each direct sub-package of the main package is considered an application module package.
23
+
The application's _main package_ is the one that the main application class resides in.
24
+
That is the class, that is annotated with `@SpringBootApplication` and usually contains the `main(…)` method used to run it.
25
+
By default, each direct sub-package of the main package is considered an _application module package_.
26
26
27
27
If this package does not contain any sub-packages, it is considered a simple one.
28
28
It allows to hide code inside it by using Java's package scope to hide types from being referred to by code residing in other packages and thus not subject for dependency injection into those.
@@ -31,13 +31,13 @@ Thus, naturally, the module's API consists of all public types in the package.
31
31
Let us have a look at an example arrangement (icon:plus-circle[] denotes a public type, icon:minus-circle[] a package protected one).
Note, how each module is listed and the contained Spring components are identified and the respective visibility is rendered, too.
130
131
131
-
[[fundamentals.modules.named-interface]]
132
+
[[fundamentals.modules.named-interfaces]]
132
133
=== Named Interfaces
133
134
134
135
By default and as described in <<fundamentals.modules.advanced>>, an application module's base package is considered the API package and thus is the only package to allow incoming dependencies from other modules.
.All modules and their relationships rendered as UML component diagram
103
+
[plantuml, uml-all-modules, svg]
104
+
....
105
+
skinparam {
106
+
shadowing false
107
+
arrowColor #707070
108
+
actorBorderColor #707070
109
+
componentBorderColor #707070
110
+
rectangleBorderColor #707070
111
+
noteBackgroundColor #ffffff
112
+
noteBorderColor #707070
113
+
defaultTextAlignment center
114
+
wrapWidth 200
115
+
maxMessageSize 100
116
+
componentStyle uml1
117
+
}
118
+
package "Application" <<Container>> {
119
+
component 4 <<Component: Module>> #dddddd [
120
+
com.acme.commerce.catalog
121
+
]
122
+
component 3 <<Component: Module>> #dddddd [
123
+
com.acme.commerce.core
124
+
]
125
+
component 7 <<Component: Module>> #dddddd [
126
+
com.acme.commerce.customer
127
+
]
128
+
component 5 <<Component: Module>> #dddddd [
129
+
com.acme.commerce.inventory
130
+
]
131
+
component 6 <<Component: Module>> #dddddd [
132
+
com.acme.commerce.order
133
+
]
134
+
}
135
+
4 .[#707070].> 3 : depends on
136
+
5 .[#707070].> 4 : uses
137
+
5 .[#707070].> 3 : uses
138
+
5 .[#707070].> 6 : uses
139
+
5 .[#707070].> 6 : listens to
140
+
6 .[#707070].> 4 : depends on
141
+
6 .[#707070].> 3 : depends on
142
+
6 .[#707070].> 7 : uses
143
+
....
144
+
145
+
.A subset of application modules and their relationships starting from the order module rendered as UML component diagram
146
+
[plantuml,uml-individiual-module, svg]
147
+
....
148
+
skinparam {
149
+
shadowing false
150
+
arrowColor #707070
151
+
actorBorderColor #707070
152
+
componentBorderColor #707070
153
+
rectangleBorderColor #707070
154
+
noteBackgroundColor #ffffff
155
+
noteBorderColor #707070
156
+
defaultTextAlignment center
157
+
wrapWidth 200
158
+
maxMessageSize 100
159
+
componentStyle uml1
160
+
}
161
+
package "Application" <<Container>> {
162
+
component 4 <<Component: Module>> #dddddd [
163
+
com.acme.commerce.catalog
164
+
]
165
+
component 3 <<Component: Module>> #dddddd [
166
+
com.acme.commerce.core
167
+
]
168
+
component 7 <<Component: Module>> #dddddd [
169
+
com.acme.commerce.customer
170
+
]
171
+
component 6 <<Component: Module>> #dddddd [
172
+
com.acme.commerce.order
173
+
]
174
+
}
175
+
4 .[#707070].> 3 : depends on
176
+
6 .[#707070].> 4 : depends on
177
+
6 .[#707070].> 3 : depends on
178
+
6 .[#707070].> 7 : uses
179
+
....
49
180
50
181
[[documentation.application-module-canvas]]
51
182
== Generating Application Module Canvases
@@ -70,12 +201,53 @@ class DocumentationTests {
70
201
71
202
A canvas generated looks like this:
72
203
73
-
TODO: Include generated canvas
204
+
.A sample Application Module Canvas
205
+
[cols="1h,4a"]
206
+
|===
207
+
|Base package
208
+
|`com.acme.commerce.inventory`
209
+
|Spring components
210
+
|_Services_
211
+
212
+
* `c.a.c.i.InventoryManagement`
213
+
214
+
_Repositories_
215
+
216
+
* `c.a.c.i.Inventory`
217
+
218
+
_Event listeners_
219
+
220
+
* `c.a.c.i.InternalInventoryListeners` listening to `o.s.m.m.DayHasPassed`, `c.a.c.i.QuantityReduced`
221
+
* `c.a.c.i.InventoryOrderEventListener` listening to `c.a.c.o.OrderCanceled`, `c.a.c.o.OrderCompleted`
222
+
223
+
_Configuration properties_
224
+
225
+
* `c.a.c.i.InventoryProperties`
226
+
227
+
_Others_
228
+
229
+
* `c.a.c.i.InventoryItemCreationListener`
230
+
|Aggregate roots
231
+
|* `c.a.c.i.InventoryItem`
232
+
|Published events
233
+
|* `c.a.c.i.QuantityReduced` created by:
234
+
** `c.a.c.i.InventoryItem.decreaseQuantity(…)`
235
+
* `c.a.c.i.StockShort` created by:
236
+
** `c.a.c.i.InternalInventoryListeners.on(…)`
237
+
238
+
|Events listened to
239
+
|* `c.a.c.o.OrderCompleted`
240
+
* `c.a.c.o.OrderCanceled`
241
+
|Properties
242
+
|* `acme.commerce.inventory.restock-threshold` -- `c.a.c.c.Quantity`. The threshold at which a `InventoryEvents.StockShort` is supposed to be triggered during inventory updates.
243
+
|===
74
244
75
245
It consists of the following sections:
76
-
* __The application module's name and base package.__
77
-
* __The Spring beans exposed by the application module, grouped by stereotype.__ -- In other words beans that are located in either the API package or any <<fundamentals.modules.named-interface, named interface package>>.
78
-
* __Exposed aggregate roots__
246
+
247
+
* __The application module's base package.__
248
+
* __The Spring beans exposed by the application module, grouped by stereotype.__ -- In other words beans that are located in either the API package or any <<fundamentals.modules.named-interfaces, named interface package>>.
249
+
* __Exposed aggregate roots__ -- Any entities that we find repositories for or explicitly declared as aggregate via jMolecules.
79
250
* __Application events published by the module__ -- Those event types need to be demarcated using jMolecules `@DomainEvent` or implement its `DomainEvent` interface.
80
-
* __Application events listened to by the module__ -- Derived from methods annotated with Spring's `@EventListener`, `@TransactionalEventListener` or beans implementing `ApplicationListener`.
81
-
* __Configuration properties__ -- Requires the usage of the `spring-boot-configuration-processor` artifact to extract the metadata attached to the properties.
251
+
* __Application events listened to by the module__ -- Derived from methods annotated with Spring's `@EventListener`, `@TransactionalEventListener`, jMolecules' `@DomainEventHandler` or beans implementing `ApplicationListener`.
252
+
* __Configuration properties__ -- Spring Boot Configuration properties exposed by the application module.
253
+
Requires the usage of the `spring-boot-configuration-processor` artifact to extract the metadata attached to the properties.
|`spring-modulith-starter-jdbc`|`compile`|Includes `spring-modulith-api`, `spring-modulith-moments` as well as `spring-modulith-events-jdbc`.
21
+
|`spring-modulith-starter-jpa`|`compile`|Includes `spring-modulith-api`, `spring-modulith-moments` as well as `spring-modulith-events-jpa`.
22
+
|`spring-modulith-starter-mongodb`|`compile`|Includes `spring-modulith-api`, `spring-modulith-moments` as well as `spring-modulith-events-mongodb`.
23
+
|`spring-modulith-starter-test`|`compile`|Includes `spring-modulith-docs` and `spring-modulith-test`.
24
+
|===
25
+
26
+
.Individual Spring Modulith JARs
27
+
[cols="3,1,5", options="header, unbreakable"]
28
+
|===
29
+
|Module|Typical scope|Description
30
+
|`spring-modulith-api`|`compile`|The abstractions to be used in your production code to customize Spring Modulith's default behavior.
31
+
|`spring-modulith-core`|`runtime`|The core application module model and API.
32
+
|`spring-modulith-docs`|`test`|The `Documenter` API to create Asciidoctor and PlantUML documentation from the module model.
33
+
|`spring-modulith-events-core`|`runtime`|The core implementation of the event publication registry as well as the integration abstractions `EventPublicationRegistry` and `EventPublicationSerializer`.
34
+
|`spring-modulith-events-jackson`|`runtime`|A Jackson-based implementation of the `EventPublicationSerializer`.
35
+
|`spring-modulith-events-jdbc`|`runtime`|A JDBC-based implementation of the `EventPublicationRegistry`.
36
+
|`spring-modulith-events-jpa`|`runtime`|A JPA-based implementation of the `EventPublicationRegistry`.
37
+
|`spring-modulith-events-mongodb`|`runtime`|A MongoDB-based implementation of the `EventPublicationRegistry`.
38
+
|`spring-modulith-moments`|`compile`|The Passage of Time events implementation described <<moments, here>>.
39
+
|`spring-modulith-observability`|`runtime`|Observability infrastructure described <<observability, here>>.
Copy file name to clipboardExpand all lines: src/docs/asciidoc/index.adoc
+4-1Lines changed: 4 additions & 1 deletion
Original file line number
Diff line number
Diff line change
@@ -10,8 +10,11 @@ Oliver Drotbohm
10
10
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.
0 commit comments