From cb0bb4a673430964faa52d7fc43cb67db6bb79ba Mon Sep 17 00:00:00 2001 From: John Blum Date: Wed, 9 Dec 2020 16:57:18 -0800 Subject: [PATCH] Add section on 'Gradle Dependency Management' under the 'Using Spring Boot for Apache Geode' section of the reference documentation. --- .../src/docs/asciidoc/index.adoc | 93 +++++++++++++++++-- 1 file changed, 84 insertions(+), 9 deletions(-) diff --git a/spring-geode-docs/src/docs/asciidoc/index.adoc b/spring-geode-docs/src/docs/asciidoc/index.adoc index 1a06bac6..e45fa342 100644 --- a/spring-geode-docs/src/docs/asciidoc/index.adoc +++ b/spring-geode-docs/src/docs/asciidoc/index.adoc @@ -49,6 +49,7 @@ John Blum :spring-data-geode-javadoc: https://docs.spring.io/spring-data/geode/docs/current/api :spring-data-geode-website: https://spring.io/projects/spring-data-geode :spring-data-website: https://spring.io/projects/spring-data +:spring-dependency-management-gradle-plugin-version: 1.0.10.RELEASE :spring-framework-docs: https://docs.spring.io/spring/docs/current/spring-framework-reference :spring-framework-javadoc: https://docs.spring.io/spring/docs/current/javadoc-api :spring-framework-website: https://spring.io/projects/spring-framework @@ -158,7 +159,8 @@ to see Spring Boot for {apache-geode-name} in action! [[maven-gradle]] == Using Spring Boot for {apache-geode-name} -To use Spring Boot for {apache-geode-name}, simply declare the `spring-geode-starter` on your application classpath: +To use Spring Boot for {apache-geode-name}, simply declare the `spring-geode-starter` on your Spring Boot application +classpath: .Maven [source,xml] @@ -182,7 +184,7 @@ dependencies { } ---- -[[maven-gradle-bom]] +[[maven-bom]] === Maven BOM If you anticipate using more than 1 Spring Boot for {apache-geode-name} (SBDG) module in your Spring Boot application, @@ -191,7 +193,7 @@ then you can also use the new `org.springframework.geode:spring-geode-bom` Maven Your application use case(s) may require more than 1 module if, for example, you need (HTTP) Session state management and replication (e.g. `spring-geode-starter-session`), or you need to enable Spring Boot Actuator endpoints for {apache-geode-name} (e.g. `spring-geode-starter-actuator`), or perhaps you need assistance writing complex Unit -and distributed Integration Tests using STDG (e.g. `spring-geode-starter-test`). +and (distributed) Integration Tests using Spring Test for Apache Geode (STDG) (e.g. `spring-geode-starter-test`). You can declare (include) and use any 1 of the SBDG modules: @@ -260,25 +262,98 @@ might appear as follows: Notice that 1) the Spring Boot application Maven POM (`pom.xml`) contains a `` section declaring the `org.springframework.geode:spring-geode-bom` and that 2) none of the `spring-geode-starter[-xyz]` dependencies -specify an explicit ``, which is 3) managed by the `spring-geode.version` property making it easy to switch -between versions of SBDG as needed. +explicitly specify a ``, which is 3) managed by the `spring-geode.version` property making it easy to switch +between versions of SBDG as needed, applied evenly to all the SBDG modules declared and used in your application Maven +POM. If you change the version of SBDG, make sure to change the `org.springframework.boot:spring-boot-starter-parent` POM version to match. SBDG is always 1 `major` version behind, but matches on `minor` version and `patch` version (and `version qualifier`, e.g. `SNAPSHOT`, `M#`, `RC#`, or `RELEASE`, if applicable). For example, SBDG `1.4.0` is based on Spring Boot `2.4.0`. SBDG `1.3.5.RELEASE` is based on -Spring Boot `2.3.5.RELEASE`. It is important that the versions align. +Spring Boot `2.3.5.RELEASE` and so on. It is important that the versions align. -Of course, all of these concerns are easy to do by simply going to https://start.spring.io[start.spring.io] -and adding the "_Spring for {apache-geode-name}_" dependency. +Of course, all of these concerns are easy to do and handled for you by simply going to +https://start.spring.io[start.spring.io] and adding the "_Spring for {apache-geode-name}_" dependency. Clink on this https://start.spring.io/#!platformVersion={spring-boot-version}&dependencies=geode[link] to get started! +[[gradle-dependency-management]] +=== Gradle Dependency Management + +The user experience when using Gradle is similar to that of Maven. + +Again, if you will be declaring and using more than 1 SBDG module in your Spring Boot application, for example, +the `spring-geode-starter` along with the `spring-geode-starter-actuator` dependency, then using the `spring-geode-bom` +inside your application Gradle build file will help. + +Your application Gradle build file configuration will roughly appear as follows: + +.Spring Boot application Gradle build file +[source,groovy] +[subs="verbatim,attributes"] +---- +plugins { + id 'org.springframework.boot' version '{spring-boot-version}' + id 'io.spring.dependency-management' version '{spring-dependency-management-gradle-plugin-version}' + id 'java' +} + +// ... + +ext { + set('springGeodeVersion', "{spring-boot-data-geode-version}") +} + +dependencies { + implementation 'org.springframework.geode:spring-geode-starter' + implementation 'org.springframework.geode:spring-geode-starter-actuator' + testImplementation 'org.springframework.boot:spring-boot-starter-test' +} + +dependencyManagement { + imports { + mavenBom "org.springframework.geode:spring-geode-bom:$\{springGeodeVersion\}" + } +} +---- + +A combination of the {spring-boot-docs-html}/using-spring-boot.html#using-boot-gradle[Spring Boot Gradle Plugin] +and the https://github.com/spring-gradle-plugins/dependency-management-plugin[Spring Dependency Management Gradle Plugin] +manage the application dependencies for you. + +In a nutshell, the _Spring Dependency Management Gradle Plugin_ provides dependency management capabilities for Gradle +much like Maven. The _Spring Boot Gradle Plugin_ defines a curated and tested set of versions for many 3rd party Java +libraries. Together they make adding dependencies and managing (compatible) versions easier! + +Again, you don't need to explicitly declare the version when adding a dependency, including a new SBDG module dependency +(e.g. `spring-geode-starter-session`) since this has already been determined for you. You can simply declare the +dependency: + +[source,groovy] +---- +implementation 'org.springframework.geode:spring-geode-starter-session' +---- + +The version of SBDG is controlled by the extension property (`springGeodeVersion`) in the application Gradle build file. + +To use a different version of SBDG, simply set the `springGeodeVersion` property to the desired version +(e.g. `1.3.5.RELEASE`). Of course, make sure the version of Spring Boot matches! + +SBDG is always 1 `major` version behind, but matches on `minor` version and `patch` version (and `version qualifier`, +e.g. `SNAPSHOT`, `M#`, `RC#`, or `RELEASE`, if applicable). For example, SBDG `1.4.0` is based on Spring Boot `2.4.0`. +SBDG `1.3.5.RELEASE` is based on Spring Boot `2.3.5.RELEASE` and so on. It is important that the versions align. + +Of course, all of these concerns are easy to do and handled for you by simply going to +https://start.spring.io[start.spring.io] and adding the "_Spring for {apache-geode-name}_" dependency. + +Clink on this https://start.spring.io/#!type=gradle-project&platformVersion={spring-boot-version}&dependencies=geode[link] +to get started! + ifeval::["{version-snapshot}" == "true"] [[maven-gradle-repository]] -=== Repository declaration +=== Repository Declaration Since you are using a `SNAPSHOT` version, you need to add the Spring Snapshot Maven Repository.