honeymoose
/
OpenSearch
mirror of https://github.com/honeymoose/OpenSearch.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

[DOCS] add docs for REST high level client index method (#25501) 

This commit restructures the existing high level client docs, adapts the existing delete method docs and adds docs for the index method.
This commit is contained in:
Luca Cavanna 2017-07-03 10:48:16 +02:00 committed by GitHub
parent 39d42292dd
commit 99fef2490a
9 changed files with 613 additions and 202 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

321
client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java Normal file
View File

@ -0,0 +1,321 @@
/*
* 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.DocWriteRequest;
import org.elasticsearch.action.DocWriteResponse;
import org.elasticsearch.action.delete.DeleteRequest;
import org.elasticsearch.action.delete.DeleteResponse;
import org.elasticsearch.action.index.IndexRequest;
import org.elasticsearch.action.index.IndexResponse;
import org.elasticsearch.action.support.WriteRequest;
import org.elasticsearch.action.support.replication.ReplicationResponse;
import org.elasticsearch.client.ESRestHighLevelClientTestCase;
import org.elasticsearch.client.RestHighLevelClient;
import org.elasticsearch.common.unit.TimeValue;
import org.elasticsearch.common.xcontent.XContentBuilder;
import org.elasticsearch.common.xcontent.XContentFactory;
import org.elasticsearch.common.xcontent.XContentType;
import org.elasticsearch.index.VersionType;
import org.elasticsearch.rest.RestStatus;
import java.io.IOException;
import java.util.Date;
import java.util.HashMap;
import java.util.Map;
/**
* This class is used to generate the Java CRUD 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,macros"]
* --------------------------------------------------
* include-tagged::{doc-tests}/CRUDDocumentationIT.java[example]
* --------------------------------------------------
*/
public class CRUDDocumentationIT extends ESRestHighLevelClientTestCase {
public void testIndex() throws IOException {
RestHighLevelClient client = highLevelClient();
{
//tag::index-request-map
Map<String, Object> jsonMap = new HashMap<>();
jsonMap.put("user", "kimchy");
jsonMap.put("postDate",new Date());
jsonMap.put("message","trying out Elasticsearch");
IndexRequest indexRequest = new IndexRequest("index", "type", "id")
.source(jsonMap); // <1>
//end::index-request-map
IndexResponse indexResponse = client.index(indexRequest);
assertEquals(indexResponse.getResult(), DocWriteResponse.Result.CREATED);
}
{
//tag::index-request-xcontent
XContentBuilder builder = XContentFactory.jsonBuilder();
builder.startObject();
{
builder.field("user", "kimchy");
builder.field("postDate", new Date());
builder.field("message", "trying out Elasticsearch");
}
builder.endObject();
IndexRequest indexRequest = new IndexRequest("index", "type", "id")
.source(builder); // <1>
//end::index-request-xcontent
IndexResponse indexResponse = client.index(indexRequest);
assertEquals(indexResponse.getResult(), DocWriteResponse.Result.UPDATED);
}
{
//tag::index-request-shortcut
IndexRequest indexRequest = new IndexRequest("index", "type", "id")
.source("user", "kimchy",
"postDate", new Date(),
"message", "trying out Elasticsearch"); // <1>
//end::index-request-shortcut
IndexResponse indexResponse = client.index(indexRequest);
assertEquals(indexResponse.getResult(), DocWriteResponse.Result.UPDATED);
}
{
//tag::index-request-string
IndexRequest request = new IndexRequest(
"index", // <1>
"type", // <2>
"id"); // <3>
String jsonString = "{" +
"\"user\":\"kimchy\"," +
"\"postDate\":\"2013-01-30\"," +
"\"message\":\"trying out Elasticsearch\"" +
"}";
request.source(jsonString, XContentType.JSON); //<4>
//end::index-request-string
// tag::index-execute
IndexResponse indexResponse = client.index(request);
// end::index-execute
assertEquals(indexResponse.getResult(), DocWriteResponse.Result.UPDATED);
// tag::index-response
String index = indexResponse.getIndex();
String type = indexResponse.getType();
String id = indexResponse.getId();
long version = indexResponse.getVersion();
if (indexResponse.getResult() == DocWriteResponse.Result.CREATED) {
// <1>
} else if (indexResponse.getResult() == DocWriteResponse.Result.UPDATED) {
// <2>
}
ReplicationResponse.ShardInfo shardInfo = indexResponse.getShardInfo();
if (shardInfo.getTotal() != shardInfo.getSuccessful()) {
// <3>
}
if (shardInfo.getFailed() > 0) {
for (ReplicationResponse.ShardInfo.Failure failure : shardInfo.getFailures()) {
String reason = failure.reason(); // <4>
}
}
// end::index-response
// tag::index-execute-async
client.indexAsync(request, new ActionListener<IndexResponse>() {
@Override
public void onResponse(IndexResponse indexResponse) {
// <1>
}
@Override
public void onFailure(Exception e) {
// <2>
}
});
// end::index-execute-async
}
{
IndexRequest request = new IndexRequest("index", "type", "id");
// tag::index-request-routing
request.routing("routing"); // <1>
// end::index-request-routing
// tag::index-request-parent
request.parent("parent"); // <1>
// end::index-request-parent
// tag::index-request-timeout
request.timeout(TimeValue.timeValueSeconds(1)); // <1>
request.timeout("1s"); // <2>
// end::index-request-timeout
// tag::index-request-refresh
request.setRefreshPolicy(WriteRequest.RefreshPolicy.WAIT_UNTIL); // <1>
request.setRefreshPolicy("wait_for"); // <2>
// end::index-request-refresh
// tag::index-request-version
request.version(2); // <1>
// end::index-request-version
// tag::index-request-version-type
request.versionType(VersionType.EXTERNAL); // <1>
// end::index-request-version-type
// tag::index-request-op-type
request.opType(DocWriteRequest.OpType.CREATE); // <1>
request.opType("create"); // <2>
// end::index-request-op-type
// tag::index-request-pipeline
request.setPipeline("pipeline"); // <1>
// end::index-request-pipeline
}
{
// tag::index-conflict
IndexRequest request = new IndexRequest("index", "type", "id")
.source("field", "value")
.version(1);
try {
IndexResponse response = client.index(request);
} catch(ElasticsearchException e) {
if (e.status() == RestStatus.CONFLICT) {
// <1>
}
}
// end::index-conflict
}
{
// tag::index-optype
IndexRequest request = new IndexRequest("index", "type", "id")
.source("field", "value")
.opType(DocWriteRequest.OpType.CREATE);
try {
IndexResponse response = client.index(request);
} catch(ElasticsearchException e) {
if (e.status() == RestStatus.CONFLICT) {
// <1>
}
}
// end::index-optype
}
}
public void testDelete() throws IOException {
RestHighLevelClient client = highLevelClient();
{
IndexRequest indexRequest = new IndexRequest("index", "type", "id").source("field", "value");
IndexResponse indexResponse = client.index(indexRequest);
assertSame(indexResponse.status(), RestStatus.CREATED);
}
{
// tag::delete-request
DeleteRequest request = new DeleteRequest(
"index", // <1>
"type", // <2>
"id"); // <3>
// end::delete-request
// tag::delete-execute
DeleteResponse deleteResponse = client.delete(request);
// end::delete-execute
assertSame(deleteResponse.getResult(), DocWriteResponse.Result.DELETED);
// tag::delete-response
String index = deleteResponse.getIndex();
String type = deleteResponse.getType();
String id = deleteResponse.getId();
long version = deleteResponse.getVersion();
ReplicationResponse.ShardInfo shardInfo = deleteResponse.getShardInfo();
if (shardInfo.getTotal() != shardInfo.getSuccessful()) {
//<1>
}
if (shardInfo.getFailed() > 0) {
for (ReplicationResponse.ShardInfo.Failure failure : shardInfo.getFailures()) {
String reason = failure.reason(); // <2>
}
}
// end::delete-response
// 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
}
{
DeleteRequest request = new DeleteRequest("index", "type", "id");
// tag::delete-request-routing
request.routing("routing"); // <1>
// end::delete-request-routing
// tag::delete-request-parent
request.parent("parent"); // <1>
// end::delete-request-parent
// tag::delete-request-timeout
request.timeout(TimeValue.timeValueMinutes(2)); // <1>
request.timeout("2m"); // <2>
// end::delete-request-timeout
// tag::delete-request-refresh
request.setRefreshPolicy(WriteRequest.RefreshPolicy.WAIT_UNTIL); // <1>
request.setRefreshPolicy("wait_for"); // <2>
// end::delete-request-refresh
// tag::delete-request-version
request.version(2); // <1>
// end::delete-request-version
// tag::delete-request-version-type
request.versionType(VersionType.EXTERNAL); // <1>
// end::delete-request-version-type
}
{
// tag::delete-notfound
DeleteRequest request = new DeleteRequest("index", "type", "does_not_exist");
DeleteResponse deleteResponse = client.delete(request);
if (deleteResponse.getResult() == DocWriteResponse.Result.NOT_FOUND) {
// <1>
}
// end::delete-notfound
}
{
IndexResponse indexResponse = client.index(new IndexRequest("index", "type", "id").source("field", "value"));
assertSame(indexResponse.status(), RestStatus.CREATED);
// tag::delete-conflict
try {
DeleteRequest request = new DeleteRequest("index", "type", "id").version(2);
DeleteResponse deleteResponse = client.delete(request);
} catch (ElasticsearchException exception) {
if (exception.status() == RestStatus.CONFLICT) {
// <1>
}
}
// end::delete-conflict
}
}
}

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

@ -1,112 +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.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
}
}

17
docs/java-rest/high-level/apis.asciidoc
View File

@ -1,10 +1,19 @@
* index API
=== Supported APIs
* get API
The Java High Level REST Client supports the following APIs:
* <<java-rest-high-document-index>>
* Get API
* <<java-rest-high-document-delete>>
* bulk API
* Update API
* search API
* Bulk API
* Search API
* Search Scroll API
* Clear Scroll API

151
docs/java-rest/high-level/apis/_index.asciidoc Normal file
View File

@ -0,0 +1,151 @@
[[java-rest-high-document-index]]
==== Index API
[[java-rest-high-document-index-request]]
===== Index Request
An `IndexRequest` requires the following arguments:
["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/CRUDDocumentationIT.java[index-request-string]
--------------------------------------------------
<1> Index
<2> Type
<3> Document id
<4> Document source provided as a `String`
===== Providing the document source
The document source can be provided in different ways:
["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/CRUDDocumentationIT.java[index-request-map]
--------------------------------------------------
<1> Document source provided as a `Map` which gets automatically converted
to JSON format
["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/CRUDDocumentationIT.java[index-request-xcontent]
--------------------------------------------------
<1> Document source provided as an `XContentBuilder` object, the Elasticsearch
built-in helpers to generate JSON content
["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/CRUDDocumentationIT.java[index-request-shortcut]
--------------------------------------------------
<1> Document source provided as `Object` key-pairs, which gets converted to
JSON format
===== Optional arguments
The following arguments can optionally be provided:
["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/CRUDDocumentationIT.java[index-request-routing]
--------------------------------------------------
<1> Routing value
["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/CRUDDocumentationIT.java[index-request-parent]
--------------------------------------------------
<1> Parent value
["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/CRUDDocumentationIT.java[index-request-timeout]
--------------------------------------------------
<1> Timeout to wait for primary shard to become available as a `TimeValue`
<2> Timeout to wait for primary shard to become available as a `String`
["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/CRUDDocumentationIT.java[index-request-refresh]
--------------------------------------------------
<1> Refresh policy as a `WriteRequest.RefreshPolicy` instance
<2> Refresh policy as a `String`
["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/CRUDDocumentationIT.java[index-request-version]
--------------------------------------------------
<1> Version
["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/CRUDDocumentationIT.java[index-request-version-type]
--------------------------------------------------
<1> Version type
["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/CRUDDocumentationIT.java[index-request-op-type]
--------------------------------------------------
<1> Operation type provided as an `DocWriteRequest.OpType` value
<2> Operation type provided as a `String`: can be `create` or `update` (default)
["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/CRUDDocumentationIT.java[index-request-pipeline]
--------------------------------------------------
<1> The name of the ingest pipeline to be executed before indexing the document
[[java-rest-high-document-index-sync]]
===== Synchronous Execution
["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/CRUDDocumentationIT.java[index-execute]
--------------------------------------------------
[[java-rest-high-document-index-async]]
===== Asynchronous Execution
["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/CRUDDocumentationIT.java[index-execute-async]
--------------------------------------------------
<1> Called when the execution is successfully completed. The response is
provided as an argument.
<2> Called in case of failure. The raised exception is provided as an argument.
[[java-rest-high-document-index-response]]
===== Index Response
The returned `IndexResponse` allows to retrieve information about the executed
operation as follows:
["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/CRUDDocumentationIT.java[index-response]
--------------------------------------------------
<1> Handle (if needed) the case where the document was created for the first
time
<2> Handle (if needed) the case where the document was rewriten as it was
already existing
<3> Handle the situation where number of successful shards is less than
total shards
<4> Handle the potential failures
If there is a version conflict, an `ElasticsearchException` will
be thrown:
["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/CRUDDocumentationIT.java[index-conflict]
--------------------------------------------------
<1> The raised exception indicates that a version conflict error was returned.
Same will happen in case `opType` was set to `create` and a document with
same index, type and id already existed:
["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/CRUDDocumentationIT.java[index-optype]
--------------------------------------------------
<1> The raised exception indicates that a version conflict error was returned.

108
docs/java-rest/high-level/apis/delete.asciidoc Normal file
View File

@ -0,0 +1,108 @@
[[java-rest-high-document-delete]]
==== Delete API
[[java-rest-high-document-delete-request]]
===== Delete Request
A `DeleteRequest` requires the following arguments:
["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-request]
--------------------------------------------------
<1> Index
<2> Type
<3> Document id
===== Optional arguments
The following arguments can optionally be provided:
["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-request-routing]
--------------------------------------------------
<1> Routing value
["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-request-parent]
--------------------------------------------------
<1> Parent value
["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-request-timeout]
--------------------------------------------------
<1> Timeout to wait for primary shard to become available as a `TimeValue`
<2> Timeout to wait for primary shard to become available as a `String`
["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-request-refresh]
--------------------------------------------------
<1> Refresh policy as a `WriteRequest.RefreshPolicy` instance
<2> Refresh policy as a `String`
["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-request-version]
--------------------------------------------------
<1> Version
["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-request-version-type]
--------------------------------------------------
<1> Version type
[[java-rest-high-document-delete-sync]]
===== Synchronous Execution
["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-execute]
--------------------------------------------------
[[java-rest-high-document-delete-async]]
===== Asynchronous Execution
["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-execute-async]
--------------------------------------------------
<1> Called when the execution is successfully completed. The response is
provided as an argument.
<2> Called in case of failure. The raised exception is provided as an argument.
[[java-rest-high-document-delete-response]]
===== Delete Response
The returned `DeleteResponse` allows to retrieve information about the executed
operation as follows:
["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-response]
--------------------------------------------------
<1> Handle the situation where number of successful shards is less than
total shards
<2> Handle the potential failures
It is also possible to check whether the document was found or not:
["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-notfound]
--------------------------------------------------
<1> Do something if the document to be deleted was not found
If there is a version conflict, an `ElasticsearchException` will
be thrown:
["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-conflict]
--------------------------------------------------
<1> The raised exception indicates that a version conflict error was returned.

1
docs/java-rest/high-level/document/index.asciidoc → docs/java-rest/high-level/apis/index.asciidoc
View File

@ -1,5 +1,6 @@
:doc-tests: {docdir}/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation
include::_index.asciidoc[]
include::delete.asciidoc[]
:doc-tests!:

67
docs/java-rest/high-level/document/delete.asciidoc
View File

@ -1,67 +0,0 @@
[[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,macros"]
--------------------------------------------------
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,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/DeleteDocumentationIT.java[delete-request-props]
--------------------------------------------------
<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,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/DeleteDocumentationIT.java[delete-execute]
--------------------------------------------------
[[java-rest-high-document-delete-async]]
==== Asynchronous Execution
["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
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
[[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,macros"]
--------------------------------------------------
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,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/DeleteDocumentationIT.java[delete-conflict]
--------------------------------------------------
<1> We got a version conflict

21
docs/java-rest/high-level/index.asciidoc
View File

@ -1,14 +1,23 @@
[[java-rest-high]]
== Java High Level REST Client
The <<java-rest-high>>'s features include:
The Java High Level REST Client works on top of the Java Low Level REST client.
Its main goal is to expose API specific methods, that accept request objects as
an argument and return response objects, so that request marshalling and
response un-marshalling is handled by the client itself.
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.
Each API can be called synchronously or asynchronously. The synchronous
methods return a response object, while the asynchronous methods, whose names
end with the `async` suffix, require a listener argument that is notified
(on the thread pool managed by the low level client) once a response or an
error is received.
The Java High Level REST Client depends on the Elasticsearch core project.
It accepts the same request arguments as the `TransportClient` and returns
the same response objects.
include::usage.asciidoc[]
include::document/index.asciidoc[]
include::apis.asciidoc[]
include::apis/index.asciidoc[]

17
docs/java-rest/high-level/usage.asciidoc
View File

@ -8,8 +8,8 @@ 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.
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
@ -42,7 +42,7 @@ dependencies {
[[java-rest-high-usage-dependencies]]
==== Dependencies
The high-level Java REST client depends on the following artifacts and their
The High Level Java REST Client depends on the following artifacts and their
transitive dependencies:
- org.elasticsearch.client:rest
@ -62,14 +62,5 @@ RestHighLevelClient client =
--------------------------------------------------
<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
In the rest of this documentation about the Java 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.