Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Use include-tagged macro for high level client docs #23438

Merged
merged 1 commit into from
Mar 20, 2017
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -55,35 +55,35 @@ public class DeleteDocumentationIT extends ESRestHighLevelClientTestCase {
public void testDelete() throws IOException {
RestHighLevelClient client = highLevelClient();

// tag::delete-request[]
// tag::delete-request
DeleteRequest request = new DeleteRequest(
"index", // <1>
"type", // <2>
"id"); // <3>
// end::delete-request[]
// end::delete-request

// tag::delete-request-props[]
// 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[]
// end::delete-request-props

// tag::delete-execute[]
// tag::delete-execute
DeleteResponse response = client.delete(request);
// end::delete-execute[]
// end::delete-execute

try {
// tag::delete-notfound[]
// 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[]
// end::delete-notfound
} catch (Exception ignored) { }

// tag::delete-execute-async[]
// tag::delete-execute-async
client.deleteAsync(request, new ActionListener<DeleteResponse>() {
@Override
public void onResponse(DeleteResponse deleteResponse) {
Expand All @@ -95,17 +95,17 @@ public void onFailure(Exception e) {
// <2>
}
});
// end::delete-execute-async[]
// end::delete-execute-async

// tag::delete-conflict[]
// tag::delete-conflict
try {
client.delete(request);
} catch (ElasticsearchException exception) {
if (exception.status().equals(RestStatus.CONFLICT)) {
// <1>
}
}
// end::delete-conflict[]
// end::delete-conflict

}
}
26 changes: 13 additions & 13 deletions docs/java-rest/high-level/document/delete.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -6,19 +6,20 @@

The most simple Delete Request needs is:

["source","java",subs="attributes,callouts"]
["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
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]
include-tagged::{doc-tests}/DeleteDocumentationIT.java[delete-request]
--------------------------------------------------
<1> Index name
<2> Type
<3> Document id


You can also provide the following properties:

["source","java",subs="attributes,callouts"]
["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
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]
include-tagged::{doc-tests}/DeleteDocumentationIT.java[delete-request-props]
--------------------------------------------------
<1> Timeout
<2> Timeout as String
Expand All @@ -30,17 +31,17 @@ sys2::[perl -ne 'exit if /end::delete-request-props/; print if $tag; $tag = $tag
[[java-rest-high-document-delete-sync]]
==== Execution

["source","java",subs="attributes,callouts"]
["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
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]
include-tagged::{doc-tests}/DeleteDocumentationIT.java[delete-execute]
--------------------------------------------------

[[java-rest-high-document-delete-async]]
==== Asynchronous Execution

["source","java",subs="attributes,callouts"]
["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
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]
include-tagged::{doc-tests}/DeleteDocumentationIT.java[delete-execute-async]
--------------------------------------------------
<1> Implement if needed when execution did not throw an exception
<2> Implement if needed in case of failure
Expand All @@ -50,18 +51,17 @@ sys2::[perl -ne 'exit if /end::delete-execute-async/; print if $tag; $tag = $tag

In the Delete Response object, you can check for example the result of the operation:

["source","java",subs="attributes,callouts"]
["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
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]
include-tagged::{doc-tests}/DeleteDocumentationIT.java[delete-notfound]
--------------------------------------------------
<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"]
["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
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]
include-tagged::{doc-tests}/DeleteDocumentationIT.java[delete-conflict]
--------------------------------------------------
<1> We got a version conflict

4 changes: 4 additions & 0 deletions docs/java-rest/high-level/document/index.asciidoc
Original file line number Diff line number Diff line change
@@ -1 +1,5 @@
:doc-tests: {docdir}/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation

include::delete.asciidoc[]

:doc-tests!:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm curious about what is the effect of this?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Clears the variable so it isn't visible outside of this section.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good to know. Thanks!