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

@@ -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.