From 61df79c583eb110f0cb596e1a8b6083322e303b3 Mon Sep 17 00:00:00 2001 From: John Blum Date: Sat, 24 Sep 2022 01:16:54 -0700 Subject: [PATCH] Add section in the reference documentation on declaring (transitive) dependency exclusions when using Gradle or Maven. --- .../src/docs/asciidoc/index.adoc | 158 ++++++++++++++++++ 1 file changed, 158 insertions(+) diff --git a/spring-geode-project/spring-geode-docs/src/docs/asciidoc/index.adoc b/spring-geode-project/spring-geode-docs/src/docs/asciidoc/index.adoc index 60048f10..6ce73920 100644 --- a/spring-geode-project/spring-geode-docs/src/docs/asciidoc/index.adoc +++ b/spring-geode-project/spring-geode-docs/src/docs/asciidoc/index.adoc @@ -747,6 +747,164 @@ the https://maven.apache.org/guides/introduction/introduction-to-dependency-mech For more details on Gradle dependency management, please refer to the https://docs.gradle.org/current/userguide/core_dependency_management.html[documentation] +[[sbdg-dependency-exclusions]] +=== Excluding Dependencies + +Sometimes, though rarely, it may be necessary to exclude a (transitive) dependency included by a Spring Boot, +or Spring Boot for Apache Geode, starter. + +Perhaps a transitive dependency, such as Apache Log4j or Jackson, is pulled in by an underlying data store dependency, +such as Apache Geode or Redis, when using a starter (for example: `spring-boot-starter-data-redis`, or `spring-geode-starter`), +that could cause a conflict with your Spring Boot application. Or, maybe the transitive dependency currently contains +a serious bug or CVE. + +Either way, you have concluded that it is safe to exclude this (transitive) dependency without adversely affecting +the runtime behavior and correctness of your Spring Boot application. + +WARNING: You should be absolutely certain that removing the (transitive) dependency, rather than <> +the (transitive) dependency is the correct course of action. + +For example, when you include the `spring-geode-starter` (the base starter of Spring Boot for Apache Geode), you notice +that Apache Lucene is transitively included by `org.apache.geode:geode-lucene`: + +.Analyzing Dependencies using Gradle +[source, text] +---- +$ gradlew :spring-geode-starter:dependencies + +... +compileClasspath - Compile classpath for source set 'main'. ++--- org.springframework.boot:spring-boot-starter -> 3.0.0-M5 +| +--- org.springframework.boot:spring-boot:3.0.0-M5 +| | +--- org.springframework:spring-core:6.0.0-M6 +... ++--- project :spring-geode +| +--- project :apache-geode-extensions +| | +--- org.apache.geode:geode-core:1.15.0 +| | | +--- antlr:antlr:2.7.7 +... +| | +--- org.apache.geode:geode-lucene:1.15.0 +| | | +--- org.apache.geode:geode-core:1.15.0 (*) +| | | \--- org.apache.lucene:lucene-core:6.6.6 +... +| | \--- org.apache.geode:geode-wan:1.15.0 +... +---- + +.Analyzing Dependencies using Maven +[source,txt] +---- +$ mvn dependency:tree + +... +[INFO] --- maven-dependency-plugin:3.3.0:tree (default-cli) @ spring-geode-app --- +[INFO] org.example.app:spring-geode-app:jar:0.0.1-SNAPSHOT +[INFO] +- org.springframework.geode:spring-geode-starter:jar:1.7.4:compile +[INFO] | +- org.springframework.boot:spring-boot-starter:jar:2.7.1:compile +[INFO] | | +- org.springframework.boot:spring-boot:jar:2.7.1:compile +... +[INFO] | +- org.springframework.geode:spring-geode:jar:1.7.4:compile +[INFO] | | +- org.springframework.data:spring-data-geode:jar:2.7.1:compile +[INFO] | | | +- org.apache.geode:geode-core:jar:1.14.4:compile +... +[INFO] | | | +- org.apache.geode:geode-lucene:jar:1.14.4:compile +[INFO] | | | | +- org.apache.lucene:lucene-core:jar:6.6.6:compile +[INFO] | | | | +- org.apache.geode:geode-gfsh:jar:1.14.4:runtime +[INFO] | | | | +- org.apache.lucene:lucene-analyzers-common:jar:6.6.6:runtime +[INFO] | | | | +- org.apache.lucene:lucene-queryparser:jar:6.6.6:runtime +[INFO] | | | | | \- org.apache.lucene:lucene-queries:jar:6.6.6:runtime +[INFO] | | | | +- mx4j:mx4j:jar:3.0.2:runtime +[INFO] | | | | \- org.apache.lucene:lucene-analyzers-phonetic:jar:6.6.6:runtime +[INFO] | | | | \- commons-codec:commons-codec:jar:1.15:runtime +... +[INFO] | | | +- org.apache.geode:geode-wan:jar:1.14.4:compile +---- + +However, you do not have any "search" use cases in your Spring Boot application that would require Apache Geode's +integration with Apache Lucene. + +Using your build tool, such as Gradle or Maven, you can add an exclusion on the `org.apache.geode:geode-lucene` +transitive dependency pulled in and included by Spring Boot for Apache Geode's `spring-geode-starter`, like so: + +.Declaring Exclusions with Gradle +[source,groovy] +[subs="verbatim,attributes"] +---- +implementation("org.springframework.geode:spring-geode-starter:{version}") { + exclude group: "org.apache.geode", module: "geode-lucene" +} +---- + +.Declaring Exclusions with Maven +[source,xml] +[subs="verbatim,attributes"] +---- + + + + + org.springframework.geode + spring-geode-starter + {version} + + + org.apache.geode + geode-lucene + + + + + +---- + +After the appropriate exclusion is declared, the resulting dependencies (or dependency tree) should look like +the following: + +.Analyzing Dependencies using Gradle after Exclusions +[source, text] +---- +$ gradlew :spring-geode-starter:dependencies + +... +compileClasspath - Compile classpath for source set 'main'. ++--- org.springframework.boot:spring-boot-starter -> 3.0.0-M5 +| +--- org.springframework.boot:spring-boot:3.0.0-M5 +| | +--- org.springframework:spring-core:6.0.0-M6 +... ++--- project :spring-geode +| +--- project :apache-geode-extensions +| | +--- org.apache.geode:geode-core:1.15.0 +| | | +--- antlr:antlr:2.7.7 +... +| | \--- org.apache.geode:geode-wan:1.15.0 +... +---- + +.Analyzing Dependencies using Maven +[source,txt] +---- +$ mvn dependency:tree + +... +[INFO] --- maven-dependency-plugin:3.3.0:tree (default-cli) @ spring-geode-app --- +[INFO] org.example.app:spring-geode-app:jar:0.0.1-SNAPSHOT +[INFO] +- org.springframework.geode:spring-geode-starter:jar:1.7.4:compile +[INFO] | +- org.springframework.boot:spring-boot-starter:jar:2.7.1:compile +[INFO] | | +- org.springframework.boot:spring-boot:jar:2.7.1:compile +... +[INFO] | +- org.springframework.geode:spring-geode:jar:1.7.4:compile +[INFO] | | +- org.springframework.data:spring-data-geode:jar:2.7.1:compile +[INFO] | | | +- org.apache.geode:geode-core:jar:1.14.4:compile +... +[INFO] | | | +- org.apache.geode:geode-wan:jar:1.14.4:compile +---- + +Again, it cannot be overstated the importance of being careful when declaring exclusions. + +TIP: Please refer to the appropriate documentation in +https://maven.apache.org/guides/introduction/introduction-to-optional-and-excludes-dependencies.html[Maven] +and https://docs.gradle.org/current/userguide/dependency_downgrade_and_exclude.html[Gradle] to declare exclusions. + include::{include-dir}/clientcache-applications.adoc[] include::{include-dir}/configuration-auto.adoc[]