From db7ff2e7ca0217c55067069531d15cdceb057157 Mon Sep 17 00:00:00 2001
From: Sylvain Wallez <sylvain@elastic.co>
Date: Mon, 28 Mar 2022 15:25:07 +0200
Subject: [PATCH] Add docs about Spring and jakarta-json (#215)

---
 docs/installation.asciidoc | 33 +++++++++++++++++++++++++++++++--
 1 file changed, 31 insertions(+), 2 deletions(-)

diff --git a/docs/installation.asciidoc b/docs/installation.asciidoc
index 4b3d25812..3e898192e 100644
--- a/docs/installation.asciidoc
+++ b/docs/installation.asciidoc
@@ -26,8 +26,13 @@ available at https://snapshots.elastic.co/maven/.
 dependencies {
     implementation 'co.elastic.clients:elasticsearch-java:{version}'
     implementation 'com.fasterxml.jackson.core:jackson-databind:2.12.3'
+
+    // Needed only if you use the spring-dependency-management
+    // and spring-boot Gradle plugins
+    implementation 'jakarta.json:jakarta.json-api:2.0.1' //<1>
 }
 --------------------------------------------------
+<1> See <<spring-jakarta-json>> for additional details.
 
 [discrete]
 [[maven]]
@@ -39,19 +44,43 @@ dependencies:
 ["source","xml",subs="attributes+"]
 --------------------------------------------------
 <project>
-
   <dependencies>
+
     <dependency>
       <groupId>co.elastic.clients</groupId>
       <artifactId>elasticsearch-java</artifactId>
       <version>{version}</version>
     </dependency>
+
     <dependency>
       <groupId>com.fasterxml.jackson.core</groupId>
       <artifactId>jackson-databind</artifactId>
       <version>2.12.3</version>
     </dependency>
-  </dependencies>
 
+    <!-- Needed only if you use the spring-boot Maven plugin -->
+    <dependency> <!--1-->
+      <groupId>jakarta.json</groupId>
+      <artifactId>jakarta.json-api</artifactId>
+      <version>2.0.1</version>
+    </dependency>
+
+  </dependencies>
 </project>
 --------------------------------------------------
+<1> See <<spring-jakarta-json>> for additional details.
+
+
+[discrete]
+[[spring-jakarta-json]]
+=== Spring Boot and jakarta.json
+
+Spring Boot comes with Gradle and Maven plugins to ease development and dependency management. These plugins define built-in versions for a number of well-known libraries.
+
+One these libraries is `jakarta.json:json-api` that defines the standard Java JSON API. In version `1.x` this library used the `javax.json` package, while in version `2.x` it uses the `jakarta.json` package after https://blogs.oracle.com/javamagazine/post/transition-from-java-ee-to-jakarta-ee[the transition from JavaEE to JakartaEE].
+
+The {java-client} depends on version `2.0.1` of this library, in order to use the newer and future-proof `jakarta.json` package. But Spring Boot's Gradle plugin (at least in version `2.6` and below) overrides the {java-client}'s dependency to use version `1.1.6` in the older `javax.json` namespace.
+
+This is why you have to explicitly add the `jakarta.json:jakarta.json-api:2.0.1` dependency. Otherwise, this will result in the following exception at runtime: `java.lang.ClassNotFoundException: jakarta.json.spi.JsonProvider`.
+
+If your application also requires `javax.json` you can add the `javax.json:javax.json-api:1.1.4` dependency, which is equivalent to `jakarta.json:jakarta.json-api:1.1.6`.