Merge branch 'doc/hlclient-delete'

client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/DeleteDocumentationIT.java

@@ -0,0 +1,111 @@
+/*
+ * Licensed to Elasticsearch under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.elasticsearch.client.documentation;
+
+import org.elasticsearch.ElasticsearchException;
+import org.elasticsearch.action.ActionListener;
+import org.elasticsearch.action.DocWriteResponse;
+import org.elasticsearch.action.delete.DeleteRequest;
+import org.elasticsearch.action.delete.DeleteResponse;
+import org.elasticsearch.action.support.WriteRequest;
+import org.elasticsearch.client.ESRestHighLevelClientTestCase;
+import org.elasticsearch.client.RestHighLevelClient;
+import org.elasticsearch.common.unit.TimeValue;
+import org.elasticsearch.index.VersionType;
+import org.elasticsearch.rest.RestStatus;
+
+import java.io.IOException;
+
+/**
+ * This class is used to generate the Java Delete API documentation.
+ * You need to wrap your code between two tags like:
+ * // tag::example[]
+ * // end::example[]
+ *
+ * Where example is your tag name.
+ *
+ * Then in the documentation, you can extract what is between tag and end tags with
+ * ["source","java",subs="attributes,callouts"]
+ * --------------------------------------------------
+ * sys2::[perl -ne 'exit if /end::example/; print if $tag; $tag = $tag || /tag::example/' {docdir}/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/DeleteDocumentationIT.java]
+ * --------------------------------------------------
+ */
+public class DeleteDocumentationIT extends ESRestHighLevelClientTestCase {
+
+    /**
+     * This test documents docs/java-rest/high-level/document/delete.asciidoc
+     */
+    public void testDelete() throws IOException {
+        RestHighLevelClient client = highLevelClient();
+
+        // tag::delete-request[]
+        DeleteRequest request = new DeleteRequest(
+            "index",    // <1>
+            "type",     // <2>
+            "id");      // <3>
+        // end::delete-request[]
+
+        // tag::delete-request-props[]
+        request.timeout(TimeValue.timeValueSeconds(1));                     // <1>
+        request.timeout("1s");                                              // <2>
+        request.setRefreshPolicy(WriteRequest.RefreshPolicy.WAIT_UNTIL);    // <3>
+        request.setRefreshPolicy("wait_for");                               // <4>
+        request.version(2);                                                 // <5>
+        request.versionType(VersionType.EXTERNAL);                          // <6>
+        // end::delete-request-props[]
+
+        // tag::delete-execute[]
+        DeleteResponse response = client.delete(request);
+        // end::delete-execute[]
+
+        try {
+            // tag::delete-notfound[]
+            if (response.getResult().equals(DocWriteResponse.Result.NOT_FOUND)) {
+                throw new Exception("Can't find document to be removed"); // <1>
+            }
+            // end::delete-notfound[]
+        } catch (Exception ignored) { }
+
+        // tag::delete-execute-async[]
+        client.deleteAsync(request, new ActionListener<DeleteResponse>() {
+            @Override
+            public void onResponse(DeleteResponse deleteResponse) {
+                // <1>
+            }
+
+            @Override
+            public void onFailure(Exception e) {
+                // <2>
+            }
+        });
+        // end::delete-execute-async[]
+
+        // tag::delete-conflict[]
+        try {
+            client.delete(request);
+        } catch (ElasticsearchException exception) {
+            if (exception.status().equals(RestStatus.CONFLICT)) {
+                // <1>
+            }
+        }
+        // end::delete-conflict[]
+
+    }
+}

docs/java-rest/high-level/apis.asciidoc

@@ -0,0 +1,10 @@
+* index API
+
+* get API
+
+* <<java-rest-high-document-delete>>
+
+* bulk API
+
+* search API
+

docs/java-rest/high-level/document/delete.asciidoc

@@ -0,0 +1,67 @@
+[[java-rest-high-document-delete]]
+=== Delete API
+
+[[java-rest-high-document-delete-request]]
+==== Delete Request
+
+The most simple Delete Request needs is:
+
+["source","java",subs="attributes,callouts"]
+--------------------------------------------------
+sys2::[perl -ne 'exit if /end::delete-request/; print if $tag; $tag = $tag || /tag::delete-request/' {docdir}/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/DeleteDocumentationIT.java]
+--------------------------------------------------
+<1> Index name
+<2> Type
+<3> Document id
+
+You can also provide the following properties:
+
+["source","java",subs="attributes,callouts"]
+--------------------------------------------------
+sys2::[perl -ne 'exit if /end::delete-request-props/; print if $tag; $tag = $tag || /tag::delete-request-props/' {docdir}/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/DeleteDocumentationIT.java]
+--------------------------------------------------
+<1> Timeout
+<2> Timeout as String
+<3> Refresh policy
+<4> Refresh policy as String
+<5> Version
+<6> Version type
+
+[[java-rest-high-document-delete-sync]]
+==== Execution
+
+["source","java",subs="attributes,callouts"]
+--------------------------------------------------
+sys2::[perl -ne 'exit if /end::delete-execute/; print if $tag; $tag = $tag || /tag::delete-execute/' {docdir}/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/DeleteDocumentationIT.java]
+--------------------------------------------------
+
+[[java-rest-high-document-delete-async]]
+==== Asynchronous Execution
+
+["source","java",subs="attributes,callouts"]
+--------------------------------------------------
+sys2::[perl -ne 'exit if /end::delete-execute-async/; print if $tag; $tag = $tag || /tag::delete-execute-async/' {docdir}/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/DeleteDocumentationIT.java]
+--------------------------------------------------
+<1> Implement if needed when execution did not throw an exception
+<2> Implement if needed in case of failure
+
+[[java-rest-high-document-delete-response]]
+==== Delete Response
+
+In the Delete Response object, you can check for example the result of the operation:
+
+["source","java",subs="attributes,callouts"]
+--------------------------------------------------
+sys2::[perl -ne 'exit if /end::delete-notfound/; print if $tag; $tag = $tag || /tag::delete-notfound/' {docdir}/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/DeleteDocumentationIT.java]
+--------------------------------------------------
+<1> Do something if we did not find the document which should have been deleted
+
+Note that if you have a version conflict because you defined the version within the
+<<java-rest-high-document-delete-request>>, it will raise an `ElasticsearchException` like:
+
+["source","java",subs="attributes,callouts"]
+--------------------------------------------------
+sys2::[perl -ne 'exit if /end::delete-conflict/; print if $tag; $tag = $tag || /tag::delete-conflict/' {docdir}/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/DeleteDocumentationIT.java]
+--------------------------------------------------
+<1> We got a version conflict
+

docs/java-rest/high-level/document/index.asciidoc

@@ -0,0 +1 @@
+include::delete.asciidoc[]

docs/java-rest/high-level/index.asciidoc

@@ -0,0 +1,14 @@
+[[java-rest-high]]
+== Java High Level REST Client
+
+The <<java-rest-high>>'s features include:
+
+include::apis.asciidoc[]
+
+It depends on elasticsearch core project as it uses elasticsearch request and response
+objects so it will simplify a migration from the transport client.
+
+
+include::usage.asciidoc[]
+
+include::document/index.asciidoc[]

docs/java-rest/high-level/usage.asciidoc

@@ -0,0 +1,75 @@
+[[java-rest-high-usage]]
+=== Getting started
+
+[[java-rest-high-usage-maven]]
+==== Maven Repository
+
+The high-level Java REST client is hosted on
+http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22org.elasticsearch.client%22[Maven
+Central]. The minimum Java version required is `1.8`.
+
+The high-level REST client is subject to the same release cycle as
+elasticsearch. Replace the version with the desired client version.
+
+[[java-rest-high-usage-maven-maven]]
+===== Maven configuration
+
+Here is how you can configure the dependency using maven as a dependency manager.
+Add the following to your `pom.xml` file:
+
+["source","xml",subs="attributes"]
+--------------------------------------------------
+<dependency>
+    <groupId>org.elasticsearch.client</groupId>
+    <artifactId>rest-high-level</artifactId>
+    <version>{version}</version>
+</dependency>
+--------------------------------------------------
+
+[[java-rest-high-usage-maven-gradle]]
+===== Gradle configuration
+
+Here is how you can configure the dependency using gradle as a dependency manager.
+Add the following to your `build.gradle` file:
+
+["source","groovy",subs="attributes"]
+--------------------------------------------------
+dependencies {
+    compile 'org.elasticsearch.client:rest-high-level:{version}'
+}
+--------------------------------------------------
+
+[[java-rest-high-usage-dependencies]]
+==== Dependencies
+
+The high-level Java REST client depends on the following artifacts and their
+transitive dependencies:
+
+- org.elasticsearch.client:rest
+- org.elasticsearch:elasticsearch
+
+
+[[java-rest-high-usage-initialization]]
+==== Initialization
+
+A `RestHighLevelClient` instance needs a <<java-rest-low-usage-initialization,REST low-level client>>
+to be built as follows:
+
+[source,java]
+--------------------------------------------------
+RestHighLevelClient client =
+    new RestHighLevelClient(lowLevelRestClient); <1>
+--------------------------------------------------
+<1> We pass the <<java-rest-low-usage-initialization,REST low-level client>> instance
+
+In the rest of this documentation about the high-level client, the `RestHighLevelClient` instance
+will be referenced as `client`.
+
+Then you have access to the high level APIs such as:
+
+include::apis.asciidoc[]
+
+Each API can be executed synchronously (i.e. <<java-rest-high-document-delete,`delete`>>) or
+asynchronously (i.e. <<java-rest-high-document-delete,`deleteAsync`>>).
+The asynchronous APIs require a listener that is called on thread pool managed by the low level client
+when the response is received.

docs/java-rest/index.asciidoc

@@ -5,8 +5,8 @@ include::../Versions.asciidoc[]
 
 include::overview.asciidoc[]
 
-include::usage.asciidoc[]
+include::low-level/index.asciidoc[]
 
-include::configuration.asciidoc[]
+include::high-level/index.asciidoc[]
 
-include::sniffer.asciidoc[]
+include::license.asciidoc[]

docs/java-rest/license.asciidoc

@@ -0,0 +1,17 @@
+[[java-rest-license]]
+== License
+
+Copyright 2013-2017 Elasticsearch
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+

docs/java-rest/low-level/configuration.asciidoc

@@ -1,4 +1,4 @@
-== Common configuration
+=== Common configuration
 
 The `RestClientBuilder` supports providing both a `RequestConfigCallback` and
 an `HttpClientConfigCallback` which allow for any customization that the Apache
@@ -8,7 +8,7 @@ configuration that the `RestClient` is initialized with. This section
 describes some common scenarios that require additional configuration for the
 low-level Java REST Client.
 
-=== Timeouts
+==== Timeouts
 
 Configuring requests timeouts can be done by providing an instance of
 `RequestConfigCallback` while building the `RestClient` through its builder.
@@ -34,7 +34,7 @@ RestClient restClient = RestClient.builder(new HttpHost("localhost", 9200))
         .build();
 --------------------------------------------------
 
-=== Number of threads
+==== Number of threads
 
 The Apache Http Async Client starts by default one dispatcher thread, and a
 number of worker threads used by the connection manager, as many as the number
@@ -55,7 +55,7 @@ RestClient restClient = RestClient.builder(new HttpHost("localhost", 9200))
         .build();
 --------------------------------------------------
 
-=== Basic authentication
+==== Basic authentication
 
 Configuring basic authentication can be done by providing an
 `HttpClientConfigCallback` while building the `RestClient` through its builder.
@@ -104,7 +104,7 @@ RestClient restClient = RestClient.builder(new HttpHost("localhost", 9200))
         .build();
 --------------------------------------------------
 
-=== Encrypted communication
+==== Encrypted communication
 
 Encrypted communication can also be configured through the
 `HttpClientConfigCallback`. The
@@ -130,7 +130,7 @@ RestClient restClient = RestClient.builder(new HttpHost("localhost", 9200))
         .build();
 --------------------------------------------------
 
-=== Others
+==== Others
 
 For any other required configuration needed, the Apache HttpAsyncClient docs
 should be consulted: https://hc.apache.org/httpcomponents-asyncclient-4.1.x/ .

docs/java-rest/low-level/index.asciidoc

@@ -0,0 +1,27 @@
+[[java-rest-low]]
+== Java Low Level REST Client
+
+The low-level client's features include:
+
+* minimal dependencies
+
+* load balancing across all available nodes
+
+* failover in case of node failures and upon specific response codes
+
+* failed connection penalization (whether a failed node is retried depends on
+ how many consecutive times it failed; the more failed attempts the longer the
+ client will wait before trying that same node again)
+
+* persistent connections
+
+* trace logging of requests and responses
+
+* optional automatic <<sniffer,discovery of cluster nodes>>
+
+
+include::usage.asciidoc[]
+
+include::configuration.asciidoc[]
+
+include::sniffer.asciidoc[]

docs/java-rest/low-level/sniffer.asciidoc

@@ -1,5 +1,5 @@
 [[sniffer]]
-== Sniffer
+=== Sniffer
 
 Minimal library that allows to automatically discover nodes from a running
 Elasticsearch cluster and set them to an existing `RestClient` instance.
@@ -8,7 +8,7 @@ Nodes Info api and uses jackson to parse the obtained json response.
 
 Compatible with Elasticsearch 2.x and onwards.
 
-=== Maven Repository
+==== Maven Repository
 
 The low-level REST client is subject to the same release cycle as
 elasticsearch. Replace the version with the desired sniffer version, first
@@ -17,7 +17,7 @@ and the elasticsearch version that the client can communicate with. Sniffer
 supports fetching the nodes list from elasticsearch 2.x and onwards.
 
 
-==== Maven configuration
+===== Maven configuration
 
 Here is how you can configure the dependency using maven as a dependency manager.
 Add the following to your `pom.xml` file:
@@ -31,7 +31,7 @@ Add the following to your `pom.xml` file:
 </dependency>
 --------------------------------------------------
 
-==== Gradle configuration
+===== Gradle configuration
 
 Here is how you can configure the dependency using gradle as a dependency manager.
 Add the following to your `build.gradle` file:
@@ -43,7 +43,7 @@ dependencies {
 }
 --------------------------------------------------
 
-=== Usage
+==== Usage
 
 Once a `RestClient` instance has been created, a `Sniffer` can be associated
 to it. The `Sniffer` will make use of the provided `RestClient` to periodically
@@ -133,9 +133,9 @@ Sniffer sniffer = Sniffer.builder(restClient)
 Note that this last configuration parameter has no effect in case sniffing
 on failure is not enabled like explained above.
 
-=== License
+==== License
 
-Copyright 2013-2016 Elasticsearch
+Copyright 2013-2017 Elasticsearch
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.

docs/java-rest/low-level/usage.asciidoc

@@ -1,6 +1,8 @@
-== Getting started
+[[java-rest-low-usage]]
+=== Getting started
 
-=== Maven Repository
+[[java-rest-low-usage-maven]]
+==== Maven Repository
 
 The low-level Java REST client is hosted on
 http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22org.elasticsearch.client%22[Maven
@@ -8,11 +10,12 @@ Central]. The minimum Java version required is `1.7`.
 
 The low-level REST client is subject to the same release cycle as
 elasticsearch. Replace the version with the desired client version, first
-released with `5.0.0-alpha4`. There  is no relation between the client version
+released with `5.0.0-alpha4`. There is no relation between the client version
 and the elasticsearch version that the client can communicate with. The
 low-level REST client is compatible with all elasticsearch versions.
 
-==== Maven configuration
+[[java-rest-low-usage-maven-maven]]
+===== Maven configuration
 
 Here is how you can configure the dependency using maven as a dependency manager.
 Add the following to your `pom.xml` file:
@@ -26,7 +29,8 @@ Add the following to your `pom.xml` file:
 </dependency>
 --------------------------------------------------
 
-==== Gradle configuration
+[[java-rest-low-usage-maven-gradle]]
+===== Gradle configuration
 
 Here is how you can configure the dependency using gradle as a dependency manager.
 Add the following to your `build.gradle` file:
@@ -38,7 +42,8 @@ dependencies {
 }
 --------------------------------------------------
 
-=== Dependencies
+[[java-rest-low-usage-dependencies]]
+==== Dependencies
 
 The low-level Java REST client internally uses the
 http://hc.apache.org/httpcomponents-asyncclient-dev/[Apache Http Async Client]
@@ -53,7 +58,8 @@ http://hc.apache.org/httpcomponents-asyncclient-dev/[Apache Http Async Client]
 - commons-logging:commons-logging
 
 
-=== Initialization
+[[java-rest-low-usage-initialization]]
+==== Initialization
 
 A `RestClient` instance can be built through the corresponding
 `RestClientBuilder` class, created via `RestClient#builder(HttpHost...)`
@@ -101,7 +107,8 @@ http://hc.apache.org/httpcomponents-asyncclient-dev/httpasyncclient/apidocs/org/
  allows to set)
 
 
-=== Performing requests
+[[java-rest-low-usage-requests]]
+==== Performing requests
 
 Once the `RestClient` has been created, requests can be sent by calling one of
 the available `performRequest` or `performRequestAsync` method variants.
@@ -159,7 +166,8 @@ void performRequestAsync(String method, String endpoint,
                          Header... headers);
 --------------------------------------------------
 
-==== Request Arguments
+[[java-rest-low-usage-requests-arguments]]
+===== Request Arguments
 
 The following are the arguments accepted by the different methods:
 
@@ -179,7 +187,8 @@ http://hc.apache.org/httpcomponents-core-ga/httpcore-nio/apidocs/org/apache/http
 request success or failure
 `headers`:: optional request headers
 
-=== Reading responses
+[[java-rest-low-usage-responses]]
+==== Reading responses
 
 The `Response` object, either returned by the synchronous `performRequest` methods or
 received as an argument in `ResponseListener#onSuccess(Response)`, wraps the
@@ -216,7 +225,8 @@ case the response body will not contain an error but rather the usual get api
 response, just without the document as it was not found.
 
 
-=== Example requests
+[[java-rest-low-usage-example]]
+==== Example requests
 
 Here are a couple of examples:
 
@@ -293,7 +303,8 @@ latch.await();
 
 --------------------------------------------------
 
-=== Logging
+[[java-rest-low-usage-logging]]
+==== Logging
 
 The Java REST client uses the same logging library that the Apache Async Http
 Client uses: https://commons.apache.org/proper/commons-logging/[Apache Commons Logging],

docs/java-rest/overview.asciidoc

@@ -1,42 +1,11 @@
+[[java-rest-overview]]
 == Overview
 
-Official low-level client for Elasticsearch. Allows to communicate with an
+The Java REST Client comes with 2 flavors:
-Elasticsearch cluster through http. Compatible with all elasticsearch versions.
 
-=== Features
+* <<java-rest-low>>: which is the official low-level client for Elasticsearch.
-
+It allows to communicate with an Elasticsearch cluster through http and is compatible
-The low-level client's features include:
+with all elasticsearch versions.
-
-* minimal dependencies
-
-* load balancing across all available nodes
-
-* failover in case of node failures and upon specific response codes
-
-* failed connection penalization (whether a failed node is retried depends on
- how many consecutive times it failed; the more failed attempts the longer the
- client will wait before trying that same node again)
-
-* persistent connections
-
-* trace logging of requests and responses
-
-* optional automatic <<sniffer,discovery of cluster nodes>>
-
-
-=== License
-
-Copyright 2013-2016 Elasticsearch
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-    http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
 
+* <<java-rest-high>>: which is the official high-level client for Elasticsearch. It adds support
+part of the elasticsearch document level and search API on top of the low-level client.