From 29e01bebb79da1a2658e2e3702c36e34b69dd535 Mon Sep 17 00:00:00 2001 From: Cora Iberkleid Date: Wed, 11 Dec 2024 15:27:34 -0500 Subject: [PATCH] GH-943 - Explain when to add org.springframework.modulith.core as compile-time dependency --- .../modules/ROOT/pages/fundamentals.adoc | 34 ++++++++++++++++--- 1 file changed, 29 insertions(+), 5 deletions(-) diff --git a/src/docs/antora/modules/ROOT/pages/fundamentals.adoc b/src/docs/antora/modules/ROOT/pages/fundamentals.adoc index c0741cbd..9e4e2c72 100644 --- a/src/docs/antora/modules/ROOT/pages/fundamentals.adoc +++ b/src/docs/antora/modules/ROOT/pages/fundamentals.adoc @@ -17,13 +17,13 @@ In a Spring Boot application, an application module is a unit of functionality t * Internal implementation components that are not supposed to be accessed by other modules. * 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_. -Spring Moduliths provides different ways of expressing modules within Spring Boot applications, primarily differing in the level of complexity involved in the overall arrangement. +Spring Modulith provides different ways of expressing modules within Spring Boot applications, primarily differing in the level of complexity involved in the overall arrangement. This allows developers to start simple and naturally move to more sophisticated means as and if needed. [[modules.application-modules]] === The `ApplicationModules` Type -Spring Moduliths allows to inspect a codebase to derive an application module model based on the given arrangement and optional configuration. +Spring Modulith allows to inspect a codebase to derive an application module model based on the given arrangement and optional configuration. The `spring-modulith-core` artifact contains `ApplicationModules` that can be pointed to a Spring Boot application class: .Creating an application module model @@ -397,7 +397,7 @@ package example.inventory [[customizing-modules-arrangement]] == Customizing the Application Modules Arrangement -Spring Moduliths allows to configure some core aspects around the application module arrangement you create via the `@Modulithic` annotation to be used on the main Spring Boot application class. +Spring Modulith allows to configure some core aspects around the application module arrangement you create via the `@Modulithic` annotation to be used on the main Spring Boot application class. [tabs] ====== @@ -462,7 +462,7 @@ The annotation exposes the following attributes to customize: === Customizing Module Detection By default, application modules will be expected to be located in direct sub-packages of the package the Spring Boot application class resides in. -An alternative detection strategy can be activated to only consider package explicitly annotated, either via Spring Modulith's `@ApplicationModule` or jMolecules `@Module` annotation. +An alternative detection strategy can be activated to only consider packages explicitly annotated, either via Spring Modulith's `@ApplicationModule` or jMolecules `@Module` annotation. That strategy can be activated by configuring the `spring.modulith.detection-strategy` to `explicitly-annotated`. .Switching the application module detection strategy to only consider annotated packages @@ -471,7 +471,7 @@ That strategy can be activated by configuring the `spring.modulith.detection-str spring.modulith.detection-strategy=explicitly-annotated ---- -If the neither default application module detection strategy nor the manually annotated one does not work for your application, the detection of the modules can be customized by providing an implementation of `ApplicationModuleDetectionStrategy`. +If neither the default application module detection strategy nor the manually annotated one works for your application, the detection of the modules can be customized by providing an implementation of `ApplicationModuleDetectionStrategy`. That interface exposes a single method `Stream getModuleBasePackages(JavaPackage)` and will be called with the package the Spring Boot application class resides in. You can then inspect the packages residing within that and select the ones to be considered application module base packages based on a naming convention or the like. @@ -516,6 +516,30 @@ This class can now be registered as `spring.modulith.detection-strategy` as foll spring.modulith.detection-strategy=example.CustomApplicationModuleDetectionStrategy ---- +If you are implementing the `ApplicationModuleDetectionStrategy` interface to customize the verification and documentation of modules, include the customization and its registration in your application's test sources. However, if the customization is intended for runtime components that require access to the module structure—potentially in relation to xref:runtime.adoc#spring-modulith-runtime-support[Spring Modulith runtime support] or xref:production-ready.adoc#production-ready-features[production-ready features] (e.g., actuator and observability support)—you must explicitly declare the following as a compile-time dependency: + +[tabs] +====== +Maven:: ++ +[source, xml, role="primary"] +---- + + org.springframework.modulith + spring-modulith-core + +---- +Gradle:: ++ +[source, groovy, role="secondary"] +---- +dependencies { + implementation 'org.springframework.modulith:spring-modulith-core' +} +---- +====== + + [[contributing-application-modules]] === Contributing Application Modules From Other Packages