Skip to content

Commit 292d606

Browse files
jxblumjxblum
committed
Add documentation on dependency version overriding.
Resolves gh-114.
1 parent d16e70e commit 292d606

File tree

1 file changed

+182
-0
lines changed
  • spring-geode-project/spring-geode-docs/src/docs/asciidoc

1 file changed

+182
-0
lines changed

‎spring-geode-project/spring-geode-docs/src/docs/asciidoc/index.adoc‎

Lines changed: 182 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -569,6 +569,188 @@ dependencyManagement {
569569
All of this is made simple by going to https://start.spring.io[start.spring.io] and creating a Spring Boot
570570
`{spring-boot-version}` project using {apache-geode-name}.
571571

572+
[[sbdg-dependency-version-overrides]]
573+
=== Overriding Dependency Versions
574+
575+
While Spring Boot for {apache-geode-name} requires baseline versions of the <<sbdg-dependency-versions,primary dependencies>>
576+
outlined above, it is possible, using Spring Boot's dependency management functionality, to override the versions of
577+
3rd-party dependencies (Java libraries) managed by Spring Boot itself.
578+
579+
When your Spring Boot application Maven POM inherits from the `org.springframework.boot:spring-boot-starter-parent`,
580+
or alternatively, applies the Spring Dependency Management Gradle Plugin (`io.spring.dependency-management`)
581+
in addition to the Spring Boot Gradle Plugin (`org.springframework.boot`) in your Spring Boot application Gradle
582+
build file, then you automatically enable the dependency management capabilities provided by Spring Boot for all
583+
3rd-party dependencies and Java libraries curated and managed by Spring Boot.
584+
585+
Spring Boot's dependency management harmonizes all 3rd-party Java libraries and dependencies that you, the user,
586+
are likely to use in your Spring Boot applications. All of these curated dependencies have been tested and proven to
587+
work with the version of Spring Boot along with all other Spring dependencies (e.g. Spring Data, Spring Security)
588+
that you may also be using in your Spring Boot applications.
589+
590+
Still, there may be times when you want, or even need to override the version of some 3rd-party Java libraries used by
591+
your Spring Boot applications, that are specifically managed by Spring Boot. In cases where you know that using a
592+
different version of a managed dependency is safe to do so, then you have a few options for how to override
593+
the dependency version:
594+
595+
* <<sbdg-dependency-version-overrides-property>>
596+
* <<sbdg-dependency-version-overrides-dependencymanagement>>
597+
598+
TIP: You should refer to Spring Boot's documentation on
599+
{spring-boot-docs-html}/using.html#using.build-systems.dependency-management[Dependency Management] for more details.
600+
601+
[[sbdg-dependency-version-overrides-property]]
602+
==== Version Property Override
603+
604+
Perhaps the easiest option to change the version of a Spring Boot managed dependency is to set the version property
605+
used by Spring Boot to control the dependency's version to the desired Java library version.
606+
607+
For example, if you want to use a different version of **Log4j** than what is currently set and determined by
608+
Spring Boot, then you would do:
609+
610+
.Maven dependency version property override
611+
[source.java]
612+
----
613+
<properties>
614+
<log4j2.version>2.17.2</log4j2.version>
615+
</properties>
616+
----
617+
618+
.Gradle dependency version property override
619+
----
620+
ext['log4j2.version'] = '2.17.2'
621+
----
622+
623+
NOTE: The Log4j version number used in the Maven and Gradle examples shown above is arbitrary. You must set
624+
the `log4j2.version` property to a valid Log4j version that would be resolvable by Maven or Gradle,
625+
given the fully qualified artifact: `org.apache.logging.log4j:log4j:2.17.2`.
626+
627+
The version property name must precisely match the version property declared in the `spring-boot-dependencies`
628+
Maven POM.
629+
630+
ifeval::["{version-snapshot}" == "true"]
631+
See the https://repo.spring.io/snapshot/org/springframework/boot/spring-boot-dependencies/{spring-boot-version}/spring-boot-dependencies-{spring-boot-version}.pom[spring-boot-dependencies POM]
632+
containing version properties for all the dependencies managed by Spring Boot.
633+
endif::[]
634+
635+
ifeval::["{version-milestone}" == "true"]
636+
See the https://repo.spring.io/milestone/org/springframework/boot/spring-boot-dependencies/{spring-boot-version}/spring-boot-dependencies-{spring-boot-version}.pom[spring-boot-dependencies POM]
637+
containing version properties for all the dependencies managed by Spring Boot.
638+
endif::[]
639+
640+
ifeval::["{version-release}" == "true"]
641+
See the https://repo.spring.io/artifactory/milestone/org/springframework/boot/spring-boot-dependencies/{spring-boot-version}/spring-boot-dependencies-{spring-boot-version}.pom[spring-boot-dependencies POM]
642+
containing version properties for all the dependencies managed by Spring Boot.
643+
endif::[]
644+
645+
More details can be found in the Spring Boot Maven Plugin
646+
https://docs.spring.io/spring-boot/docs/current/maven-plugin/reference/htmlsingle/#using.parent-pom[documentation]
647+
as well as the Spring Boot Gradle Plugin
648+
https://docs.spring.io/spring-boot/docs/current/gradle-plugin/reference/htmlsingle/#managing-dependencies[documentation].
649+
650+
[[sbdg-dependency-version-overrides-dependencymanagement]]
651+
==== Override with Dependency Management
652+
653+
This option is not specific to Spring in general, or Spring Boot in particular, but applies to Maven and Gradle,
654+
which both intrinsically have dependency management features and capabilities.
655+
656+
This approach is useful not only to control the versions of the dependencies managed by Spring Boot directly, but also
657+
to control the versions of dependencies that may be transitively pulled in by the dependencies that are managed by
658+
Spring Boot. Additionally, this approach is also more universally transferrable since it is handled by Maven or Gradle
659+
itself.
660+
661+
For example, when you declare the `org.springframework.boot:spring-boot-starter-test` dependency in your Spring Boot
662+
application Maven POM or Gradle build file for testing purposes, you will see a dependency tree similar to:
663+
664+
.$gradlew dependencies OR $mvn dependency:tree
665+
[source,xml]
666+
----
667+
...
668+
[INFO] +- org.springframework.boot:spring-boot-starter-test:jar:2.6.4:test
669+
[INFO] | +- org.springframework.boot:spring-boot-test:jar:2.6.4:test
670+
[INFO] | +- org.springframework.boot:spring-boot-test-autoconfigure:jar:2.6.4:test
671+
[INFO] | +- com.jayway.jsonpath:json-path:jar:2.6.0:test
672+
[INFO] | | +- net.minidev:json-smart:jar:2.4.8:test
673+
[INFO] | | | \- net.minidev:accessors-smart:jar:2.4.8:test
674+
[INFO] | | | \- org.ow2.asm:asm:jar:9.1:test
675+
[INFO] | | \- org.slf4j:slf4j-api:jar:1.7.36:compile
676+
[INFO] | +- jakarta.xml.bind:jakarta.xml.bind-api:jar:2.3.3:test
677+
[INFO] | | \- jakarta.activation:jakarta.activation-api:jar:1.2.2:test
678+
[INFO] | +- org.assertj:assertj-core:jar:3.21.0:compile
679+
[INFO] | +- org.hamcrest:hamcrest:jar:2.2:compile
680+
[INFO] | +- org.junit.jupiter:junit-jupiter:jar:5.8.2:test
681+
[INFO] | | +- org.junit.jupiter:junit-jupiter-api:jar:5.8.2:test
682+
[INFO] | | | +- org.opentest4j:opentest4j:jar:1.2.0:test
683+
[INFO] | | | +- org.junit.platform:junit-platform-commons:jar:1.8.2:test
684+
[INFO] | | | \- org.apiguardian:apiguardian-api:jar:1.1.2:test
685+
[INFO] | | +- org.junit.jupiter:junit-jupiter-params:jar:5.8.2:test
686+
[INFO] | | \- org.junit.jupiter:junit-jupiter-engine:jar:5.8.2:test
687+
[INFO] | | \- org.junit.platform:junit-platform-engine:jar:1.8.2:test
688+
...
689+
----
690+
691+
If you wanted to override and control the version of the `opentest4j` transitive dependency, for whatever reason,
692+
perhapsbecause you are using the `opentest4j` API directly in your application tests, then you could add dependency
693+
management in either Maven or Gradle to control the `opentest4j` dependency version.
694+
695+
Note that the `opentest4j` dependency is pulled in by JUnit and is not a dependency that Spring Boot specifically
696+
manages. Of course, Maven or Gradle's dependency management capabilities can be used to override dependencies that are
697+
managed by Spring Boot, too.
698+
699+
Using the `opentest4j` dependency as an example, you can override the dependency version by doing the following:
700+
701+
.Maven dependency version override
702+
[source,xml]
703+
----
704+
<project>
705+
706+
<dependencyManagement>
707+
<dependencies>
708+
<dependency>
709+
<groupId>org.opentest4j</groupId>
710+
<artifactId>opentest4j</artifactId>
711+
<version>1.0.0</version>
712+
</dependency>
713+
</dependencies>
714+
</dependencyManagement>
715+
716+
</project>
717+
----
718+
719+
.Gradle dependency version override
720+
[source,grooy]
721+
[subs="verbatim,attributes"]
722+
----
723+
plugins {
724+
id 'org.springframework.boot' version '{spring-boot-version}'
725+
}
726+
727+
apply plugin: 'io.spring.dependency-management'
728+
729+
dependencyManagement {
730+
dependencies {
731+
dependency 'org.opentest4j:openttest4j:1.0.0'
732+
}
733+
}
734+
----
735+
736+
After applying Maven or Gradle dependency management configuration, you will then see:
737+
738+
.$gradlew dependencies OR $mvn dependency:tree
739+
[source,xml]
740+
----
741+
...
742+
[INFO] +- org.springframework.boot:spring-boot-starter-test:jar:2.6.4:test
743+
...
744+
[INFO] | | | +- org.opentest4j:opentest4j:jar:1.0.0:test
745+
...
746+
----
747+
748+
For more details on Maven dependency management, refer to
749+
the https://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html[documentation].
750+
751+
For more details on Gradle dependency management, please refer to
752+
the https://docs.gradle.org/current/userguide/core_dependency_management.html[documentation]
753+
572754

573755
include::{include-dir}/clientcache-applications.adoc[]
574756
include::{include-dir}/configuration-auto.adoc[]

0 commit comments

Comments
 (0)