From c373ed102f7b78e85657943816d33f55f9725d13 Mon Sep 17 00:00:00 2001 From: David Pilato Date: Fri, 24 Feb 2017 17:38:18 +0100 Subject: [PATCH] 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 +