[Doc] Add an UpdateRequest example to Java API doc

Closes #7083.

docs/java-api/index.asciidoc

@@ -43,6 +43,8 @@ include::get.asciidoc[]
 
 include::delete.asciidoc[]
 
+include::update.asciidoc[]
+
 include::bulk.asciidoc[]
 
 include::search.asciidoc[]

docs/java-api/update.asciidoc

@@ -0,0 +1,118 @@
+[[java-update-api]]
+== Update API
+
+
+You can either create an `UpdateRequest` and send it to the client:
+
+[source,java]
+--------------------------------------------------
+UpdateRequest updateRequest = new UpdateRequest();
+updateRequest.index("index");
+updateRequest.type("type");
+updateRequest.id("1");
+updateRequest.doc(jsonBuilder()
+        .startObject()
+            .field("gender", "male")
+        .endObject());
+client.update(updateRequest).get();
+--------------------------------------------------
+
+Or you can use `prepareUpdate()` method:
+
+[source,java]
+--------------------------------------------------
+client.prepareUpdate("ttl", "doc", "1")
+        .setScript("ctx._source.gender = \"male\"" <1> , ScriptService.ScriptType.INLINE)
+        .get();
+
+client.prepareUpdate("ttl", "doc", "1")
+        .setDoc(jsonBuilder()               <2>
+            .startObject()
+                .field("gender", "male")
+            .endObject())
+        .get();
+--------------------------------------------------
+<1> Your script. It could also be a locally stored script name.
+In that case, you'll need to use `ScriptService.ScriptType.FILE`
+<2> Document which will be merged to the existing one.
+
+Note that you can't provide both `script` and `doc`.
+
+[[java-update-api-script]]
+=== Update by script
+
+The update API allows to update a document based on a script provided:
+
+[source,java]
+--------------------------------------------------
+UpdateRequest updateRequest = new UpdateRequest("ttl", "doc", "1")
+        .script("ctx._source.gender = \"male\"");
+client.update(updateRequest).get();
+--------------------------------------------------
+
+
+[[java-update-api-merge-docs]]
+=== Update by merging documents
+
+The update API also support passing a partial document, which will be merged into the existing document (simple
+recursive merge, inner merging of objects, replacing core "keys/values" and arrays). For example:
+
+[source,java]
+--------------------------------------------------
+UpdateRequest updateRequest = new UpdateRequest("index", "type", "1")
+        .doc(jsonBuilder()
+            .startObject()
+                .field("gender", "male")
+            .endObject());
+client.update(updateRequest).get();
+--------------------------------------------------
+
+
+[[java-update-api-upsert]]
+=== Upsert
+
+There is also support for `upsert`. If the document does not already exists, the content of the `upsert`
+element will be used to index the fresh doc:
+
+[source,java]
+--------------------------------------------------
+IndexRequest indexRequest = new IndexRequest("index", "type", "1")
+        .source(jsonBuilder()
+            .startObject()
+                .field("name", "Joe Smith")
+                .field("gender", "male")
+            .endObject());
+UpdateRequest updateRequest = new UpdateRequest("index", "type", "1")
+        .doc(jsonBuilder()
+            .startObject()
+                .field("gender", "male")
+            .endObject())
+        .upsert(indexRequest);              <1>
+client.update(updateRequest).get();
+--------------------------------------------------
+<1> If the document does not exist, the one in `indexRequest` will be added
+
+If the document `index/type/1` already exists, we will have after this operation a document like:
+
+[source,js]
+--------------------------------------------------
+{
+    "name"  : "Joe Dalton",
+    "gender": "male"        <1>
+}
+--------------------------------------------------
+<1> This field is added by the update request
+
+If it does not exist, we will have a new document:
+
+[source,js]
+--------------------------------------------------
+{
+    "name" : "Joe Smith",
+    "gender": "male"
+}
+--------------------------------------------------
+
+
+
+