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.