From a4e22b44e49ac01d9011d50442c5c929597204a2 Mon Sep 17 00:00:00 2001
From: David Pilato <david@pilato.fr>
Date: Mon, 30 Nov 2015 11:47:17 +0100
Subject: [PATCH] add java-api doc about shading / embedding

Two new sections added

* Dealing with JAR dependency conflicts
* Embedding jar with dependencies

Closes #15071.
---
 docs/java-api/index.asciidoc | 56 ++++++++++++++++++++++++++++++++++++
 1 file changed, 56 insertions(+)

diff --git a/docs/java-api/index.asciidoc b/docs/java-api/index.asciidoc
index 37f56df0f9f..f976ebc2426 100644
--- a/docs/java-api/index.asciidoc
+++ b/docs/java-api/index.asciidoc
@@ -34,6 +34,62 @@ For example, you can define the latest version in your `pom.xml` file:
 </dependency>
 --------------------------------------------------
 
+== Dealing with JAR dependency conflicts
+
+If you want to use Elasticsearch in your Java application, you may have to deal with version conflicts with third party
+dependencies like Guava and Joda.  For instance, perhaps Elasticsearch uses Joda 2.8, while your code uses Joda 2.1.
+
+You have two choices:
+
+* The simplest solution is to upgrade. Newer module versions are likely to have fixed old bugs.
+The further behind you fall, the harder it will be to upgrade later. Of course, it is possible that you are using a
+third party dependency that in turn depends on an outdated version of a package, which prevents you from upgrading.
+
+* The second option is to relocate the troublesome dependencies and to shade them either with your own application
+or with Elasticsearch and any plugins needed by the Elasticsearch client.
+
+The https://www.elastic.co/blog/to-shade-or-not-to-shade["Too shade or not to shade" blog post] describes
+all the steps for doing so.
+
+== Embedding jar with dependencies
+
+If you want to create a single jar containing your application and all dependencies, you should not
+use `maven-assembly-plugin` for that because it can not deal with `META-INF/services` structure which is
+required by Lucene jars.
+
+Instead, you can use `maven-shade-plugin` and configure it as follow:
+
+[source,xml]
+--------------------------------------------------
+<plugin>
+    <groupId>org.apache.maven.plugins</groupId>
+    <artifactId>maven-shade-plugin</artifactId>
+    <version>2.4.1</version>
+    <executions>
+        <execution>
+            <phase>package</phase>
+            <goals><goal>shade</goal></goals>
+            <configuration>
+                <transformers>
+                    <transformer implementation="org.apache.maven.plugins.shade.resource.ServicesResourceTransformer"/>
+                </transformers>
+            </configuration>
+        </execution>
+    </executions>
+</plugin>
+--------------------------------------------------
+
+Note that if you have a `main` class you want to automatically call when running `java -jar yourjar.jar`, just add
+it to the `transformers`:
+
+[source,xml]
+--------------------------------------------------
+<transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
+    <mainClass>org.elasticsearch.demo.Generate</mainClass>
+</transformer>
+--------------------------------------------------
+
+
 == Deploying in JBoss EAP6 module
 
 Elasticsearch and Lucene classes need to be in the same JBoss module.