Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Polish reference documentation #220

Closed
wants to merge 21 commits into from
Closed
Show file tree
Hide file tree
Changes from 18 commits
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
0e0c50e
GH-189 - Better artifact names for example projects.
odrotbohm May 2, 2023
9f871c6
GH-200 - Group starters under single build module.
odrotbohm May 2, 2023
af9fca5
GH-195 - Remove support for legacy spring.modulith.jdbc-… namespace i…
odrotbohm May 2, 2023
1e3eacd
GH-195 - Unnest test cases to make sure we run the right profiles.
odrotbohm May 2, 2023
a5070d7
GH-198 - Upgrade to Spring Boot 3.1.
odrotbohm Jun 1, 2023
eabebb8
GH-208 - Switch to CopyOnWriteArrayList for DefaultPublishedEvents.
odrotbohm Jun 1, 2023
2e64ed0
GH-211 - Rename actuator to application-modules.
odrotbohm Jun 1, 2023
d7b3be5
GH-209 - Update the README with a complete pom.xml snippet to get sta…
thombergs May 26, 2023
fcda98f
GH-209 - Polishing.
odrotbohm Jun 1, 2023
c6fa5f5
Update spring-boot.version to prevent merge conficts with fork parent.
yossisp Jun 24, 2023
6cfca56
Merge branch 'spring-projects:main' into main
yossisp Jun 24, 2023
be59542
Describe how canvases generated before canvases code snippet.
yossisp Jun 24, 2023
182c3f5
Fix compilation error in code snippet: initialize() access modifier m…
yossisp Jun 24, 2023
fba973e
@Order is only useful to set init order of beans of the same type, @D…
yossisp Jun 24, 2023
1d58923
org.springframework.modulith:spring-modulith-observability artifact d…
yossisp Jun 24, 2023
facbff8
Noop commit to re-trigger CI checks.
yossisp Jun 27, 2023
0e3b348
Revert "Noop commit to re-trigger CI checks."
yossisp Jun 27, 2023
bce7092
Add the default location of generated docs.
yossisp Jun 30, 2023
ec296d2
Revert "@Order is only useful to set init order of beans of the same …
yossisp Jul 7, 2023
cac8f77
Remove reference to Maven/Gradle when explaining the location of spri…
yossisp Jul 7, 2023
3c3d224
Revert "org.springframework.modulith:spring-modulith-observability ar…
yossisp Jul 7, 2023
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions src/docs/asciidoc/60-documentation.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -183,7 +183,7 @@ package "Application" <<Container>> {

The Application Module Canvases can be generated by calling `Documenter.writeModuleCanvases()`:

.Generating application module component diagrams using `Documenter`
.Generating application module canvases using `Documenter`
[source, java]
----
class DocumentationTests {
Expand All @@ -199,7 +199,8 @@ class DocumentationTests {
}
----

A canvas generated looks like this:
odrotbohm marked this conversation as resolved.
Show resolved Hide resolved
By default, the documentation will be generated to `target/spring-modulith-docs` in a Maven project or `build/spring-modulith-docs` in a Gradle project.
A generated canvas looks like this:

.A sample Application Module Canvas
[cols="1h,4a"]
Expand Down
4 changes: 2 additions & 2 deletions src/docs/asciidoc/70-runtime.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@ ComponentB --> ComponentA

....

While developers could of course define the execution order via Spring's standard `@Order` annotation or `Ordered` interface, Spring Modulith provides an `ApplicationModuleInitializer` interface for beans to be run on application startup.
Copy link
Member

@odrotbohm odrotbohm Jul 6, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please scratch that. @DependsOn is not a recommended means for ordering user-facing components. @Order/Ordered is exactly what was meant.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I reverted the wording but I have a question: @Order is mentioned in the context of Application Module Initializers which are intended to be used for different modules, not multiple implementations of the same module:

If a module B depends on module A, the initialization code of A has to run before the one for B, even if the initializers do not directly depend on another.

This is why I think the @Order parallel is confusing as it's intended to order multiple implementations of the same interface while initializers are intended for different modules altogether. Does this make sense?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think what plays into this is the fact that for module-specific initialization, you usually want transactional behavior. That's not something you can get with simple components and an @PostConstruct callback in components you'd interconnect via @DependsOn.

In other words, you typically declare an interface for the initializer with a custom method that can be @Transactional and a central component that would depend on List<MyInitializer> and invoke those transactional methods. For that list to be ordered, you'd either use @Order/Ordered. Pretty similar to what we actually implement with ApplicationModuleInitializer.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@odrotbohm Got it, thank you for the explanation!

While developers could of course define the execution order via Spring's standard `@DependsOn` annotation, Spring Modulith provides an `ApplicationModuleInitializer` interface for beans to be run on application startup.
The execution order of those beans will automatically follow the application module dependency structure.

[source, java]
Expand All @@ -67,7 +67,7 @@ The execution order of those beans will automatically follow the application mod
class MyInitializer implements ApplicationModuleInitializer {

@Override
void initialize() {
public void initialize() {
// Initialization code goes here
}
}
Expand Down
2 changes: 1 addition & 1 deletion src/docs/asciidoc/80-observability.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -122,7 +122,7 @@ To activate the instrumentation add the following runtime dependency to your pro
[source, xml]
----
<dependency>
<groupId>org.springframework.modulith</groupId>
odrotbohm marked this conversation as resolved.
Show resolved Hide resolved
<groupId>org.springframework.experimental</groupId>
<artifactId>spring-modulith-observability</artifactId>
<version>{projectVersion}</version>
<scope>runtime</scope>
Expand Down
Loading