From 60661ec9ccad6bc0552d1e4ee250b4d47e4753c8 Mon Sep 17 00:00:00 2001 From: David Pilato Date: Fri, 24 Feb 2017 13:52:36 +0100 Subject: [PATCH 1/6] Add first High level client documentation The REST Client is split into 2 parts: * Low level * High level The High level client has a main common section and the document delete API documentation as a start. --- docs/java-rest/high-level/apis.asciidoc | 10 ++ .../high-level/document/delete.asciidoc | 92 +++++++++++++++++++ .../high-level/document/index.asciidoc | 1 + docs/java-rest/high-level/index.asciidoc | 14 +++ docs/java-rest/high-level/usage.asciidoc | 83 +++++++++++++++++ docs/java-rest/index.asciidoc | 6 +- docs/java-rest/license.asciidoc | 17 ++++ .../{ => low-level}/configuration.asciidoc | 12 +-- docs/java-rest/low-level/index.asciidoc | 27 ++++++ .../{ => low-level}/sniffer.asciidoc | 14 +-- docs/java-rest/{ => low-level}/usage.asciidoc | 35 ++++--- docs/java-rest/overview.asciidoc | 45 ++------- 12 files changed, 290 insertions(+), 66 deletions(-) create mode 100644 docs/java-rest/high-level/apis.asciidoc create mode 100644 docs/java-rest/high-level/document/delete.asciidoc create mode 100644 docs/java-rest/high-level/document/index.asciidoc create mode 100644 docs/java-rest/high-level/index.asciidoc create mode 100644 docs/java-rest/high-level/usage.asciidoc create mode 100644 docs/java-rest/license.asciidoc rename docs/java-rest/{ => low-level}/configuration.asciidoc (98%) create mode 100644 docs/java-rest/low-level/index.asciidoc rename docs/java-rest/{ => low-level}/sniffer.asciidoc (97%) rename docs/java-rest/{ => low-level}/usage.asciidoc (95%) diff --git a/docs/java-rest/high-level/apis.asciidoc b/docs/java-rest/high-level/apis.asciidoc new file mode 100644 index 00000000000..f021e93b84b --- /dev/null +++ b/docs/java-rest/high-level/apis.asciidoc @@ -0,0 +1,10 @@ +* index API + +* get API + +* <> + +* bulk API + +* search API + diff --git a/docs/java-rest/high-level/document/delete.asciidoc b/docs/java-rest/high-level/document/delete.asciidoc new file mode 100644 index 00000000000..46f70b59e62 --- /dev/null +++ b/docs/java-rest/high-level/document/delete.asciidoc @@ -0,0 +1,92 @@ +[[java-rest-high-document-delete]] +=== Delete API + +[[java-rest-high-document-delete-request]] +==== Delete Request + +The most simple Delete Request needs is: + +[source,java] +-------------------------------------------------- +DeleteRequest request = new DeleteRequest( + "index", <1> + "type", <2> + "id"); <3> +-------------------------------------------------- +<1> Index name +<2> Type +<3> Document id + +You can also provide the following properties: + +[source,java] +-------------------------------------------------- +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> +-------------------------------------------------- +<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] +-------------------------------------------------- +DeleteResponse response = client.delete(request); +-------------------------------------------------- + +[[java-rest-high-document-delete-async]] +==== Asynchronous Execution + +[source,java] +-------------------------------------------------- +client.deleteAsync(request, new ActionListener() { + @Override + public void onResponse(DeleteResponse deleteResponse) { + <1> + } + + @Override + public void onFailure(Exception e) { + <2> + } +}); +-------------------------------------------------- +<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] +-------------------------------------------------- +if (response.getResult().equals(DocWriteResponse.Result.NOT_FOUND)) { + <1> +} +-------------------------------------------------- +<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 +<>, it will raise an `ElasticsearchException` like: + +[source,java] +-------------------------------------------------- +try { + client.delete(request); +} catch (ElasticsearchException exception) { + if (exception.status().equals(RestStatus.CONFLICT) { + <1> + } +} +-------------------------------------------------- +<1> We got a version conflict diff --git a/docs/java-rest/high-level/document/index.asciidoc b/docs/java-rest/high-level/document/index.asciidoc new file mode 100644 index 00000000000..15eee483baa --- /dev/null +++ b/docs/java-rest/high-level/document/index.asciidoc @@ -0,0 +1 @@ +include::delete.asciidoc[] diff --git a/docs/java-rest/high-level/index.asciidoc b/docs/java-rest/high-level/index.asciidoc new file mode 100644 index 00000000000..8b8dbe65ffd --- /dev/null +++ b/docs/java-rest/high-level/index.asciidoc @@ -0,0 +1,14 @@ +[[java-rest-high]] +== Java High Level REST Client + +The <>'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[] diff --git a/docs/java-rest/high-level/usage.asciidoc b/docs/java-rest/high-level/usage.asciidoc new file mode 100644 index 00000000000..7374923d041 --- /dev/null +++ b/docs/java-rest/high-level/usage.asciidoc @@ -0,0 +1,83 @@ +[[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, first +released with `5.x.x`. There is no relation between the client version +and the elasticsearch version that the client can communicate with as +it depends on the <> which is compatible with all elasticsearch versions. + +[[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"] +-------------------------------------------------- + + org.elasticsearch.client + rest-high-level + {version} + +-------------------------------------------------- + +[[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 <> +to be built as follows: + +[source,java] +-------------------------------------------------- +RestHighLevelClient client = + new RestHighLevelClient(lowLevelRestClient); <1> +-------------------------------------------------- +<1> We pass the <> 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 comes with 2 ways of executing it: + +* Synchronously, for example method <> + +* Asynchronously which has `Async` added to the synchronous method name. Like +<>. In which case you will have to +provide a listener. + + diff --git a/docs/java-rest/index.asciidoc b/docs/java-rest/index.asciidoc index 683c495c7f8..d4447019924 100644 --- a/docs/java-rest/index.asciidoc +++ b/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[] diff --git a/docs/java-rest/license.asciidoc b/docs/java-rest/license.asciidoc new file mode 100644 index 00000000000..0fb617d2f40 --- /dev/null +++ b/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. + diff --git a/docs/java-rest/configuration.asciidoc b/docs/java-rest/low-level/configuration.asciidoc similarity index 98% rename from docs/java-rest/configuration.asciidoc rename to docs/java-rest/low-level/configuration.asciidoc index 5fc6d37daa8..a75e1620c7e 100644 --- a/docs/java-rest/configuration.asciidoc +++ b/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/ . diff --git a/docs/java-rest/low-level/index.asciidoc b/docs/java-rest/low-level/index.asciidoc new file mode 100644 index 00000000000..b5ad9d82e28 --- /dev/null +++ b/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 <> + + +include::usage.asciidoc[] + +include::configuration.asciidoc[] + +include::sniffer.asciidoc[] diff --git a/docs/java-rest/sniffer.asciidoc b/docs/java-rest/low-level/sniffer.asciidoc similarity index 97% rename from docs/java-rest/sniffer.asciidoc rename to docs/java-rest/low-level/sniffer.asciidoc index 6c4c531306b..081ecd3dd66 100644 --- a/docs/java-rest/sniffer.asciidoc +++ b/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: -------------------------------------------------- -==== 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. diff --git a/docs/java-rest/usage.asciidoc b/docs/java-rest/low-level/usage.asciidoc similarity index 95% rename from docs/java-rest/usage.asciidoc rename to docs/java-rest/low-level/usage.asciidoc index 613b4ab7b8d..c83f9986d1f 100644 --- a/docs/java-rest/usage.asciidoc +++ b/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: -------------------------------------------------- -==== 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], diff --git a/docs/java-rest/overview.asciidoc b/docs/java-rest/overview.asciidoc index 206fcb931b4..3c5ea06c1dd 100644 --- a/docs/java-rest/overview.asciidoc +++ b/docs/java-rest/overview.asciidoc @@ -1,42 +1,11 @@ +[[java-rest-overview]] == Overview -Official low-level client for Elasticsearch. Allows to communicate with an -Elasticsearch cluster through http. Compatible with all elasticsearch versions. +The Java REST Client comes with 2 flavors: -=== Features - -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 <> - - -=== 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. +* <>: which is the official low-level client for Elasticsearch. +It allows to communicate with an Elasticsearch cluster through http and is compatible +with all elasticsearch versions. +* <>: 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. From c373ed102f7b78e85657943816d33f55f9725d13 Mon Sep 17 00:00:00 2001 From: David Pilato Date: Fri, 24 Feb 2017 17:38:18 +0100 Subject: [PATCH 2/6] Extract documentation from test code --- .../elasticsearch/client/DocumentationIT.java | 84 +++++++++++++++++++ .../high-level/document/delete.asciidoc | 41 +++------ 2 files changed, 95 insertions(+), 30 deletions(-) create mode 100644 client/rest-high-level/src/test/java/org/elasticsearch/client/DocumentationIT.java diff --git a/client/rest-high-level/src/test/java/org/elasticsearch/client/DocumentationIT.java b/client/rest-high-level/src/test/java/org/elasticsearch/client/DocumentationIT.java new file mode 100644 index 00000000000..c40a9b01515 --- /dev/null +++ b/client/rest-high-level/src/test/java/org/elasticsearch/client/DocumentationIT.java @@ -0,0 +1,84 @@ +/* + * 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; + +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.common.unit.TimeValue; +import org.elasticsearch.index.VersionType; + +import java.io.IOException; + +/** + * This class is used to generate the Java API documentation + */ +public class DocumentationIT 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[] + +// tag::delete-notfound[] +if (response.getResult().equals(DocWriteResponse.Result.NOT_FOUND)) { + // <1> +} +// end::delete-notfound[] + +// tag::delete-execute-async[] +client.deleteAsync(request, new ActionListener() { + @Override + public void onResponse(DeleteResponse deleteResponse) { + // <1> + } + + @Override + public void onFailure(Exception e) { + // <2> + } +}); +// end::delete-execute-async[] + + } +} diff --git a/docs/java-rest/high-level/document/delete.asciidoc b/docs/java-rest/high-level/document/delete.asciidoc index 46f70b59e62..f34061a81de 100644 --- a/docs/java-rest/high-level/document/delete.asciidoc +++ b/docs/java-rest/high-level/document/delete.asciidoc @@ -6,12 +6,9 @@ The most simple Delete Request needs is: -[source,java] +["source","java",subs="attributes,callouts"] -------------------------------------------------- -DeleteRequest request = new DeleteRequest( - "index", <1> - "type", <2> - "id"); <3> +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/DocumentationIT.java] -------------------------------------------------- <1> Index name <2> Type @@ -19,14 +16,9 @@ DeleteRequest request = new DeleteRequest( You can also provide the following properties: -[source,java] +["source","java",subs="attributes,callouts"] -------------------------------------------------- -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> +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/DocumentationIT.java] -------------------------------------------------- <1> Timeout <2> Timeout as String @@ -38,27 +30,17 @@ request.versionType(VersionType.EXTERNAL); <6> [[java-rest-high-document-delete-sync]] ==== Execution -[source,java] +["source","java",subs="attributes,callouts"] -------------------------------------------------- -DeleteResponse response = client.delete(request); +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/DocumentationIT.java] -------------------------------------------------- [[java-rest-high-document-delete-async]] ==== Asynchronous Execution -[source,java] +["source","java",subs="attributes,callouts"] -------------------------------------------------- -client.deleteAsync(request, new ActionListener() { - @Override - public void onResponse(DeleteResponse deleteResponse) { - <1> - } - - @Override - public void onFailure(Exception e) { - <2> - } -}); +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/DocumentationIT.java] -------------------------------------------------- <1> Implement if needed when execution did not throw an exception <2> Implement if needed in case of failure @@ -68,11 +50,9 @@ client.deleteAsync(request, new ActionListener() { In the Delete Response object, you can check for example the result of the operation: -[source,java] +["source","java",subs="attributes,callouts"] -------------------------------------------------- -if (response.getResult().equals(DocWriteResponse.Result.NOT_FOUND)) { - <1> -} +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/DocumentationIT.java] -------------------------------------------------- <1> Do something if we did not find the document which should have been deleted @@ -90,3 +70,4 @@ try { } -------------------------------------------------- <1> We got a version conflict + From 798bf966a387a0be3338eef7afbf04c9e62ad67b Mon Sep 17 00:00:00 2001 From: David Pilato Date: Wed, 1 Mar 2017 11:28:13 +0100 Subject: [PATCH 3/6] Don't mention cluster compatibility --- docs/java-rest/high-level/usage.asciidoc | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/docs/java-rest/high-level/usage.asciidoc b/docs/java-rest/high-level/usage.asciidoc index 7374923d041..c2667b7e017 100644 --- a/docs/java-rest/high-level/usage.asciidoc +++ b/docs/java-rest/high-level/usage.asciidoc @@ -9,10 +9,7 @@ http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22org.elasticsearch.client%22[Ma 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, first -released with `5.x.x`. There is no relation between the client version -and the elasticsearch version that the client can communicate with as -it depends on the <> which is compatible with all elasticsearch versions. +elasticsearch. Replace the version with the desired client version. [[java-rest-high-usage-maven-maven]] ===== Maven configuration From ee4a17a0e241398150b386f093f07fbaa5d12330 Mon Sep 17 00:00:00 2001 From: David Pilato Date: Wed, 1 Mar 2017 11:51:06 +0100 Subject: [PATCH 4/6] Adapt per Nik's comments --- .../elasticsearch/client/DocumentationIT.java | 84 ------------- .../documentation/DeleteDocumentationIT.java | 111 ++++++++++++++++++ .../high-level/document/delete.asciidoc | 20 ++-- docs/java-rest/high-level/usage.asciidoc | 13 +- 4 files changed, 122 insertions(+), 106 deletions(-) delete mode 100644 client/rest-high-level/src/test/java/org/elasticsearch/client/DocumentationIT.java create mode 100644 client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/DeleteDocumentationIT.java diff --git a/client/rest-high-level/src/test/java/org/elasticsearch/client/DocumentationIT.java b/client/rest-high-level/src/test/java/org/elasticsearch/client/DocumentationIT.java deleted file mode 100644 index c40a9b01515..00000000000 --- a/client/rest-high-level/src/test/java/org/elasticsearch/client/DocumentationIT.java +++ /dev/null @@ -1,84 +0,0 @@ -/* - * 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; - -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.common.unit.TimeValue; -import org.elasticsearch.index.VersionType; - -import java.io.IOException; - -/** - * This class is used to generate the Java API documentation - */ -public class DocumentationIT 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[] - -// tag::delete-notfound[] -if (response.getResult().equals(DocWriteResponse.Result.NOT_FOUND)) { - // <1> -} -// end::delete-notfound[] - -// tag::delete-execute-async[] -client.deleteAsync(request, new ActionListener() { - @Override - public void onResponse(DeleteResponse deleteResponse) { - // <1> - } - - @Override - public void onFailure(Exception e) { - // <2> - } -}); -// end::delete-execute-async[] - - } -} diff --git a/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/DeleteDocumentationIT.java b/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/DeleteDocumentationIT.java new file mode 100644 index 00000000000..70ac6de7c3a --- /dev/null +++ b/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::delete-request[] + * // end::delete-request[] + * + * Where delete-request 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::delete-request/; print if $tag; $tag = $tag || /tag::delete-request/' {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() { + @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[] + + } +} diff --git a/docs/java-rest/high-level/document/delete.asciidoc b/docs/java-rest/high-level/document/delete.asciidoc index f34061a81de..36cfc54994e 100644 --- a/docs/java-rest/high-level/document/delete.asciidoc +++ b/docs/java-rest/high-level/document/delete.asciidoc @@ -8,7 +8,7 @@ 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/DocumentationIT.java] +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 @@ -18,7 +18,7 @@ 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/DocumentationIT.java] +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 @@ -32,7 +32,7 @@ sys2::[perl -ne 'exit if /end::delete-request-props/; print if $tag; $tag = $tag ["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/DocumentationIT.java] +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]] @@ -40,7 +40,7 @@ sys2::[perl -ne 'exit if /end::delete-execute/; print if $tag; $tag = $tag || /t ["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/DocumentationIT.java] +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 @@ -52,22 +52,16 @@ In the Delete Response object, you can check for example the result of the opera ["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/DocumentationIT.java] +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 <>, it will raise an `ElasticsearchException` like: -[source,java] +["source","java",subs="attributes,callouts"] -------------------------------------------------- -try { - client.delete(request); -} catch (ElasticsearchException exception) { - if (exception.status().equals(RestStatus.CONFLICT) { - <1> - } -} +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 diff --git a/docs/java-rest/high-level/usage.asciidoc b/docs/java-rest/high-level/usage.asciidoc index c2667b7e017..1ea6c7b5d77 100644 --- a/docs/java-rest/high-level/usage.asciidoc +++ b/docs/java-rest/high-level/usage.asciidoc @@ -69,12 +69,7 @@ Then you have access to the high level APIs such as: include::apis.asciidoc[] -Each API comes with 2 ways of executing it: - -* Synchronously, for example method <> - -* Asynchronously which has `Async` added to the synchronous method name. Like -<>. In which case you will have to -provide a listener. - - +Each API can be executed synchronously (i.e. <>) or +asynchronously (i.e. <>). +The asynchronous APIs require a listener that is called on thread pool managed by the low level client +when the response is received. From 2629c9896c4e8466a1c8e920679ba60ffea6260e Mon Sep 17 00:00:00 2001 From: David Pilato Date: Wed, 1 Mar 2017 13:20:46 +0100 Subject: [PATCH 5/6] Missing dot and parenthesis --- .../client/documentation/DeleteDocumentationIT.java | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/DeleteDocumentationIT.java b/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/DeleteDocumentationIT.java index 70ac6de7c3a..ee7d7a1cf06 100644 --- a/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/DeleteDocumentationIT.java +++ b/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/DeleteDocumentationIT.java @@ -34,7 +34,7 @@ import org.elasticsearch.rest.RestStatus; import java.io.IOException; /** - * This class is used to generate the Java Delete API documentation + * This class is used to generate the Java Delete API documentation. * You need to wrap your code between two tags like: * // tag::delete-request[] * // end::delete-request[] @@ -101,7 +101,7 @@ public class DeleteDocumentationIT extends ESRestHighLevelClientTestCase { try { client.delete(request); } catch (ElasticsearchException exception) { - if (exception.status().equals(RestStatus.CONFLICT) { + if (exception.status().equals(RestStatus.CONFLICT)) { // <1> } } From dc80a1fa75ba23b411d61be15063f4e6db5afa18 Mon Sep 17 00:00:00 2001 From: David Pilato Date: Wed, 1 Mar 2017 13:33:12 +0100 Subject: [PATCH 6/6] Bad rendering of docs --- .../client/documentation/DeleteDocumentationIT.java | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/DeleteDocumentationIT.java b/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/DeleteDocumentationIT.java index ee7d7a1cf06..591e4d7ebbd 100644 --- a/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/DeleteDocumentationIT.java +++ b/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/DeleteDocumentationIT.java @@ -36,15 +36,15 @@ 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::delete-request[] - * // end::delete-request[] + * // tag::example[] + * // end::example[] * - * Where delete-request is your tag name. + * 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::delete-request/; print if $tag; $tag = $tag || /tag::delete-request/' {docdir}/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/DeleteDocumentationIT.java] + * 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 {