From 31a570c87b5f69ddbc061441ee60dbcb4bd1e789 Mon Sep 17 00:00:00 2001 From: Devashish Bhattacharjee Date: Tue, 19 Sep 2023 13:08:22 +0530 Subject: [PATCH] GH-255 - Add Gradle snippets for build related samples to the reference documentation. --- .../antora/modules/ROOT/pages/events.adoc | 16 +++++- src/docs/antora/modules/ROOT/pages/index.adoc | 20 ++++++- .../antora/modules/ROOT/pages/moments.adoc | 16 +++++- .../modules/ROOT/pages/production-ready.adoc | 53 +++++++++++++++++-- .../antora/modules/ROOT/pages/runtime.adoc | 17 +++++- 5 files changed, 113 insertions(+), 9 deletions(-) diff --git a/src/docs/antora/modules/ROOT/pages/events.adoc b/src/docs/antora/modules/ROOT/pages/events.adoc index 22a21c68..67314824 100644 --- a/src/docs/antora/modules/ROOT/pages/events.adoc +++ b/src/docs/antora/modules/ROOT/pages/events.adoc @@ -133,7 +133,11 @@ As the needs for that kind of housekeeping strongly vary from application to app That API is available through the `spring-modulith-events-api` artifact, that you can add to your application: .Using Spring Modulith Events API artifact -[source, xml, subs="+attributes"] +[tabs] +====== +Maven:: ++ +[source, xml, subs="+attributes", role="primary"] ---- org.springframework.modulith @@ -142,6 +146,16 @@ That API is available through the `spring-modulith-events-api` artifact, that yo ---- +Gradle:: ++ +[source, subs="+attributes", role="secondary"] +---- +dependencies { + implementation 'org.springframework.modulith:spring-modulith-events-api:{projectVersion}' +} +---- +====== + This artifact contains two primary abstractions, that are available to application code as Spring Beans: * `CompletedEventPublications` -- This interface allows accessing all completed event publications, and provides API to immediately purge all of them from the database or the completed publications older that a given duration (for example, 1 minute). diff --git a/src/docs/antora/modules/ROOT/pages/index.adoc b/src/docs/antora/modules/ROOT/pages/index.adoc index 5d043732..28cf0fae 100644 --- a/src/docs/antora/modules/ROOT/pages/index.adoc +++ b/src/docs/antora/modules/ROOT/pages/index.adoc @@ -26,8 +26,12 @@ NOTE: Copies of this document may be made for your own use and for distribution Spring Modulith consists of a set of libraries that can be used individually and depending on which features of it you would like to use. To ease the declaration of the individual modules, we recommend to declare the following BOM in your Maven POM: -.Using the Spring Modulith BOM -[source, xml, subs="+attributes"] +.Using the Spring Modulith BOM +[tabs] +====== +Maven:: ++ +[source, xml, subs="+attributes", role="primary"] ---- @@ -42,6 +46,18 @@ To ease the declaration of the individual modules, we recommend to declare the f ---- +Gradle:: ++ +[source, subs="+attributes", role="secondary"] +---- +dependencyManagement { + imports { + mavenBom 'org.springframework.modulith:spring-modulith-bom:{projectVersion}' + } +} +---- +====== + The individual sections describing Spring Modulith features will refer to the individual artifacts that are needed to make use of the feature. For an overview about all modules available, have a look at xref:appendix.adoc#artifacts[Spring Modulith modules]. diff --git a/src/docs/antora/modules/ROOT/pages/moments.adoc b/src/docs/antora/modules/ROOT/pages/moments.adoc index f361b3eb..3a02a9f3 100644 --- a/src/docs/antora/modules/ROOT/pages/moments.adoc +++ b/src/docs/antora/modules/ROOT/pages/moments.adoc @@ -6,7 +6,11 @@ It's an event-based approach to time to trigger actions that are tied to a parti To use the abstraction, include the following dependency in your project: -[source, xml] +[tabs] +====== +Maven:: ++ +[source, xml, role="primary"] ---- org.springframework.modulith @@ -14,6 +18,16 @@ To use the abstraction, include the following dependency in your project: ---- +Gradle:: ++ +[source, role="secondary"] +---- +dependencies { + implementation 'org.springframework.modulith:spring-modulith-moments' +} +---- +====== + The dependency added to the project's classpath causes the following things in your application: * Application code can refer to `HourHasPassed`, `DayHasPassed`, `WeekHasPassed`, `MonthHasPassed`, `QuarterHasPassed`, `YearHasPassed` types in Spring event listeners to get notified if a certain amount of time has passed. diff --git a/src/docs/antora/modules/ROOT/pages/production-ready.adoc b/src/docs/antora/modules/ROOT/pages/production-ready.adoc index 294a8ad7..cb4ffd5e 100644 --- a/src/docs/antora/modules/ROOT/pages/production-ready.adoc +++ b/src/docs/antora/modules/ROOT/pages/production-ready.adoc @@ -5,7 +5,11 @@ Spring Modulith provides support to expose architectural information about your As a production-ready application is likely to require both, the most convenient way to activate those features is to use the Spring Modulith Insight starter as follows: .Using the Spring Modulith Insight starter -[source, xml, subs="+attributes"] +[tabs] +====== +Maven:: ++ +[source, xml, subs="+attributes", role="primary"] ---- org.springframework.modulith @@ -15,6 +19,16 @@ As a production-ready application is likely to require both, the most convenien ---- +Gradle:: ++ +[source, subs="+attributes", role="secondary"] +---- +dependencies { + runtimeOnly 'org.springframework.modulith:spring-modulith-starter-insight:{projectVersion}' +} +---- +====== + This will include the actuator and observability support as well as Spring Boot's actuator startup for general support for actuators. Note, that you will still have to add further dependencies to connect your application to your monitoring tools such as https://zipkin.io/[Zipkin], https://docs.wavefront.com/[Wavefront] etc. usually via https://opentelemetry.io/[OpenTelemetry] or https://github.com/openzipkin/brave[Brave]. Find more information on that in https://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#actuator.micrometer-tracing[the corresponding section] of Spring Boot's reference documentation. @@ -26,7 +40,11 @@ The application module structure can be exposed as Spring Boot actuator. To enable the actuator, add the `spring-modulith-actuator` dependency to the project: .Using the Spring Modulith actuator support -[source, xml, subs="+attributes"] +[tabs] +====== +Maven:: ++ +[source, xml, subs="+attributes", role="primary"] ---- org.springframework.modulith @@ -44,6 +62,21 @@ To enable the actuator, add the `spring-modulith-actuator` dependency to the pro ---- +Gradle:: ++ +[source, subs="+attributes", role="secondary"] +---- +dependencies { + runtimeOnly 'org.springframework.modulith:spring-modulith-actuator:{projectVersion}' +} + + +dependencies { + runtimeOnly 'org.springframework.boot:spring-boot-starter-actuator' +} +---- +====== + Running the application will now expose an `modulith` actuator resource: .Accessing the actuator HTTP resource @@ -119,7 +152,11 @@ The interaction between application modules can be intercepted to create Microme To activate the instrumentation add the following runtime dependency to your project: .Using the Spring Modulith observability support -[source, xml, subs="+attributes"] +[tabs] +====== +Maven:: ++ +[source, xml, subs="+attributes", role="primary"] ---- org.springframework.modulith @@ -129,6 +166,16 @@ To activate the instrumentation add the following runtime dependency to your pro ---- +Gradle:: ++ +[source, subs="+attributes", role="secondary"] +---- +dependencies { + runtimeOnly 'org.springframework.modulith:spring-modulith-observability:{projectVersion}' +} +---- +====== + NOTE: You will have to configure additional infrastructure dependencies depending on the tooling you want to pipe the observability metadata in. For details, please check the corresponding https://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#actuator.micrometer-tracing[Spring Boot documentation] on which dependencies to include for your setup. diff --git a/src/docs/antora/modules/ROOT/pages/runtime.adoc b/src/docs/antora/modules/ROOT/pages/runtime.adoc index 78355e15..ed944d7a 100644 --- a/src/docs/antora/modules/ROOT/pages/runtime.adoc +++ b/src/docs/antora/modules/ROOT/pages/runtime.adoc @@ -8,8 +8,11 @@ In this section we are going to describe Spring Modulith's support for == Setting up Runtime Support for Application Modules To enable the runtime support for Spring Modulith, make sure you include the `spring-modulith-runtime` JAR in your project. - -[source, xml] +[tabs] +====== +Maven:: ++ +[source, xml, role="primary"] ---- org.springframework.modulith @@ -18,6 +21,16 @@ To enable the runtime support for Spring Modulith, make sure you include the `sp ---- +Gradle:: ++ +[source, xml, role="secondary"] +---- +dependencies { + runtimeOnly 'org.springframework.modulith:spring-modulith-runtime' +} +---- +====== + IMPORTANT: It's worth noting that using the runtime support of Spring Modulith will mean that you include both https://www.archunit.org/[ArchUnit] and the https://jgrapht.org/[JGraphT] (required to topologically sort application modules) library in your application. Adding this JAR will cause Spring Boot auto-configuration to run that registers the following components in your application: