honeymoose
/
OpenSearch
mirror of https://github.com/honeymoose/OpenSearch.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
OpenSearch/docs/java-rest/low-level/usage.asciidoc

400 lines
19 KiB
Plaintext
Raw Normal View History

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.
2017-02-24 07:52:36 -05:00
[[java-rest-low-usage]]
[DOCS] restructure java clients docs pages (#25517) This commit converts the low level client and high level client chapters into two parts, which allows each high level client supported api to be on a separate page and show up in the index on the right.
2017-07-04 04:58:57 -04:00
== Getting started
This section describes how to get started with the low-level REST client from
getting the artifact to using it in an application.
[DOCS] add java REST client docs (#19618) [DOCS] add java REST client docs Add some docs on how to get started with the Java REST client, some common configuration that may be needed and the sniffer component.
2016-07-29 05:22:47 -04:00
[DOCS] add links to javadocs to clients docs (#25745) We publish javadocs to artifacts.elastic.co (and snapshots.elastic.co) for a while. This commit adds the link to them to the transport client, low level REST client, sniffer and high level REST client pages. Closes #23761
2017-07-31 09:41:21 -04:00
[[java-rest-low-javadoc]]
=== Javadoc
The javadoc for the low level REST client can be found at {rest-client-javadoc}/index.html.
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.
2017-02-24 07:52:36 -05:00
[[java-rest-low-usage-maven]]
[DOCS] restructure java clients docs pages (#25517) This commit converts the low level client and high level client chapters into two parts, which allows each high level client supported api to be on a separate page and show up in the index on the right.
2017-07-04 04:58:57 -04:00
=== Maven Repository
[DOCS] add java REST client docs (#19618) [DOCS] add java REST client docs Add some docs on how to get started with the Java REST client, some common configuration that may be needed and the sniffer component.
2016-07-29 05:22:47 -04:00
The low-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.7`.
Add Gradle coordinates for the REST client
2016-11-22 10:34:23 -05:00
The low-level REST client is subject to the same release cycle as
[Docs] Unify spelling of Elasticsearch (#27567) Removes occurences of "elasticsearch" or "ElasticSearch" in favour of "Elasticsearch" where appropriate.
2017-11-29 03:44:25 -05:00
Elasticsearch. Replace the version with the desired client version, first
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.
2017-02-24 07:52:36 -05:00
released with `5.0.0-alpha4`. There is no relation between the client version
[Docs] Unify spelling of Elasticsearch (#27567) Removes occurences of "elasticsearch" or "ElasticSearch" in favour of "Elasticsearch" where appropriate.
2017-11-29 03:44:25 -05:00
and the Elasticsearch version that the client can communicate with. The
low-level REST client is compatible with all Elasticsearch versions.
Add Gradle coordinates for the REST client
2016-11-22 10:34:23 -05:00
Add information about the snapshot repository (#27719) From https://twitter.com/ddanieltwitt/status/938754761968451585, I think we should add in our documentation, where users can find the SNAPSHOT versions we are publishing.
2018-02-09 11:59:04 -05:00
If you are looking for a SNAPSHOT version, the Elastic Maven Snapshot repository is available
at https://snapshots.elastic.co/maven/.
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.
2017-02-24 07:52:36 -05:00
[[java-rest-low-usage-maven-maven]]
[DOCS] restructure java clients docs pages (#25517) This commit converts the low level client and high level client chapters into two parts, which allows each high level client supported api to be on a separate page and show up in the index on the right.
2017-07-04 04:58:57 -04:00
==== Maven configuration
Add Gradle coordinates for the REST client
2016-11-22 10:34:23 -05:00
[DOCS] add java REST client docs (#19618) [DOCS] add java REST client docs Add some docs on how to get started with the Java REST client, some common configuration that may be needed and the sniffer component.
2016-07-29 05:22:47 -04:00
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"]
--------------------------------------------------
<dependency>
<groupId>org.elasticsearch.client</groupId>
Rename client artifacts (#25693) It was brought up that our current client artifacts have generic names like 'rest' that may cause conflicts with other artifacts. This commit renames: - rest -> elasticsearch-rest-client - sniffer -> elasticsearch-rest-client-sniffer - rest-high-level -> elasticsearch-rest-high-level-client A couple of small changes are also preparing the high level client for its first release. Closes #20248
2017-07-13 03:44:25 -04:00
<artifactId>elasticsearch-rest-client</artifactId>
[DOCS] add java REST client docs (#19618) [DOCS] add java REST client docs Add some docs on how to get started with the Java REST client, some common configuration that may be needed and the sniffer component.
2016-07-29 05:22:47 -04:00
<version>{version}</version>
</dependency>
--------------------------------------------------
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.
2017-02-24 07:52:36 -05:00
[[java-rest-low-usage-maven-gradle]]
[DOCS] restructure java clients docs pages (#25517) This commit converts the low level client and high level client chapters into two parts, which allows each high level client supported api to be on a separate page and show up in the index on the right.
2017-07-04 04:58:57 -04:00
==== Gradle configuration
Add Gradle coordinates for the REST client
2016-11-22 10:34:23 -05:00
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 {
Rename client artifacts (#25693) It was brought up that our current client artifacts have generic names like 'rest' that may cause conflicts with other artifacts. This commit renames: - rest -> elasticsearch-rest-client - sniffer -> elasticsearch-rest-client-sniffer - rest-high-level -> elasticsearch-rest-high-level-client A couple of small changes are also preparing the high level client for its first release. Closes #20248
2017-07-13 03:44:25 -04:00
compile 'org.elasticsearch.client:elasticsearch-rest-client:{version}'
Add Gradle coordinates for the REST client
2016-11-22 10:34:23 -05:00
}
--------------------------------------------------
[DOCS] add java REST client docs (#19618) [DOCS] add java REST client docs Add some docs on how to get started with the Java REST client, some common configuration that may be needed and the sniffer component.
2016-07-29 05:22:47 -04:00
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.
2017-02-24 07:52:36 -05:00
[[java-rest-low-usage-dependencies]]
[DOCS] restructure java clients docs pages (#25517) This commit converts the low level client and high level client chapters into two parts, which allows each high level client supported api to be on a separate page and show up in the index on the right.
2017-07-04 04:58:57 -04:00
=== Dependencies
[DOCS] add java REST client docs (#19618) [DOCS] add java REST client docs Add some docs on how to get started with the Java REST client, some common configuration that may be needed and the sniffer component.
2016-07-29 05:22:47 -04:00
Revert "[Docs] Update Java Low-Level documentation to reflect shaded deps (#25882)" (#26411) This reverts commit 91dc1c5da682fd832fc27d07f657643a88f4aae5. Ref #26328
2017-08-29 10:26:36 -04:00
The low-level Java REST client internally uses the
http://hc.apache.org/httpcomponents-asyncclient-dev/[Apache Http Async Client]
to send http requests. It depends on the following artifacts, namely the async
http client and its own transitive dependencies:
[DOCS] add java REST client docs (#19618) [DOCS] add java REST client docs Add some docs on how to get started with the Java REST client, some common configuration that may be needed and the sniffer component.
2016-07-29 05:22:47 -04:00
- org.apache.httpcomponents:httpasyncclient
- org.apache.httpcomponents:httpcore-nio
- org.apache.httpcomponents:httpclient
- org.apache.httpcomponents:httpcore
- commons-codec:commons-codec
- commons-logging:commons-logging
Add a shading example to the rest client docs This adds a maven and gradle example for shading as well as the caveat about shading and commons logging. Ref #26449
2017-09-01 09:57:16 -04:00
[[java-rest-low-usage-shading]]
=== Shading
In order to avoid version conflicts, the dependencies can be shaded and packaged
within the client in a single JAR file (sometimes called an "uber JAR" or "fat
JAR"). Shading a dependency consists of taking its content (resources files and
Java class files) and renaming some of its packages before putting them in the
same JAR file as the low-level Java REST client. Shading a JAR can be
accomplished by 3rd-party plugins for Gradle and Maven.
Be advised that shading a JAR also has implications. Shading the Commons Logging
layer, for instance, means that 3rd-party logging backends need to be shaded as
well.
[[java-rest-low-usage-shading-maven]]
==== Maven configuration
Here is a configuration using the Maven
https://maven.apache.org/plugins/maven-shade-plugin/index.html[Shade]
plugin. Add the following to your `pom.xml` file:
["source","xml",subs="attributes"]
--------------------------------------------------
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-shade-plugin</artifactId>
<version>3.1.0</version>
<executions>
<execution>
<phase>package</phase>
<goals><goal>shade</goal></goals>
<configuration>
<relocations>
<relocation>
<pattern>org.apache.http</pattern>
<shadedPattern>hidden.org.apache.http</shadedPattern>
</relocation>
<relocation>
<pattern>org.apache.logging</pattern>
<shadedPattern>hidden.org.apache.logging</shadedPattern>
</relocation>
<relocation>
<pattern>org.apache.commons.codec</pattern>
<shadedPattern>hidden.org.apache.commons.codec</shadedPattern>
</relocation>
<relocation>
<pattern>org.apache.commons.logging</pattern>
<shadedPattern>hidden.org.apache.commons.logging</shadedPattern>
</relocation>
</relocations>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
--------------------------------------------------
[[java-rest-low-usage-shading-gradle]]
==== Gradle configuration
Here is a configuration using the Gradle
https://github.com/johnrengelman/shadow[ShadowJar] plugin. Add the following to
your `build.gradle` file:
["source","groovy",subs="attributes"]
--------------------------------------------------
shadowJar {
relocate 'org.apache.http', 'hidden.org.apache.http'
relocate 'org.apache.logging', 'hidden.org.apache.logging'
relocate 'org.apache.commons.codec', 'hidden.org.apache.commons.codec'
relocate 'org.apache.commons.logging', 'hidden.org.apache.commons.logging'
}
--------------------------------------------------
[DOCS] add java REST client docs (#19618) [DOCS] add java REST client docs Add some docs on how to get started with the Java REST client, some common configuration that may be needed and the sniffer component.
2016-07-29 05:22:47 -04:00
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.
2017-02-24 07:52:36 -05:00
[[java-rest-low-usage-initialization]]
[DOCS] restructure java clients docs pages (#25517) This commit converts the low level client and high level client chapters into two parts, which allows each high level client supported api to be on a separate page and show up in the index on the right.
2017-07-04 04:58:57 -04:00
=== Initialization
[DOCS] add java REST client docs (#19618) [DOCS] add java REST client docs Add some docs on how to get started with the Java REST client, some common configuration that may be needed and the sniffer component.
2016-07-29 05:22:47 -04:00
A `RestClient` instance can be built through the corresponding
`RestClientBuilder` class, created via `RestClient#builder(HttpHost...)`
static method. The only required argument is one or more hosts that the
client will communicate with, provided as instances of
https://hc.apache.org/httpcomponents-core-ga/httpcore/apidocs/org/apache/http/HttpHost.html[HttpHost]
as follows:
[DOCS] Rewrite low-level REST client docs and verify snippets compile (#25559) Using the infra that we now have in place, we can convert the low-level REST client docs so that they extract code snippets from real Java classes. This way we make sure that all the snippets properly compile. Compared to the high level REST client docs, in this case we don't run the tests themselves, as that would require depending on test-framework which requires java 8 while the low-level REST client is compatible with java 7. I think that compiling snippets is enough for now.
2017-07-06 04:05:50 -04:00
["source","java",subs="attributes,callouts,macros"]
[DOCS] add java REST client docs (#19618) [DOCS] add java REST client docs Add some docs on how to get started with the Java REST client, some common configuration that may be needed and the sniffer component.
2016-07-29 05:22:47 -04:00
--------------------------------------------------
[DOCS] Rewrite low-level REST client docs and verify snippets compile (#25559) Using the infra that we now have in place, we can convert the low-level REST client docs so that they extract code snippets from real Java classes. This way we make sure that all the snippets properly compile. Compared to the high level REST client docs, in this case we don't run the tests themselves, as that would require depending on test-framework which requires java 8 while the low-level REST client is compatible with java 7. I think that compiling snippets is enough for now.
2017-07-06 04:05:50 -04:00
include-tagged::{doc-tests}/RestClientDocumentation.java[rest-client-init]
[DOCS] add java REST client docs (#19618) [DOCS] add java REST client docs Add some docs on how to get started with the Java REST client, some common configuration that may be needed and the sniffer component.
2016-07-29 05:22:47 -04:00
--------------------------------------------------
The `RestClient` class is thread-safe and ideally has the same lifecycle as
the application that uses it. It is important that it gets closed when no
longer needed so that all the resources used by it get properly released,
as well as the underlying http client instance and its threads:
[DOCS] Rewrite low-level REST client docs and verify snippets compile (#25559) Using the infra that we now have in place, we can convert the low-level REST client docs so that they extract code snippets from real Java classes. This way we make sure that all the snippets properly compile. Compared to the high level REST client docs, in this case we don't run the tests themselves, as that would require depending on test-framework which requires java 8 while the low-level REST client is compatible with java 7. I think that compiling snippets is enough for now.
2017-07-06 04:05:50 -04:00
["source","java",subs="attributes,callouts,macros"]
[DOCS] add java REST client docs (#19618) [DOCS] add java REST client docs Add some docs on how to get started with the Java REST client, some common configuration that may be needed and the sniffer component.
2016-07-29 05:22:47 -04:00
--------------------------------------------------
[DOCS] Rewrite low-level REST client docs and verify snippets compile (#25559) Using the infra that we now have in place, we can convert the low-level REST client docs so that they extract code snippets from real Java classes. This way we make sure that all the snippets properly compile. Compared to the high level REST client docs, in this case we don't run the tests themselves, as that would require depending on test-framework which requires java 8 while the low-level REST client is compatible with java 7. I think that compiling snippets is enough for now.
2017-07-06 04:05:50 -04:00
include-tagged::{doc-tests}/RestClientDocumentation.java[rest-client-close]
[DOCS] add java REST client docs (#19618) [DOCS] add java REST client docs Add some docs on how to get started with the Java REST client, some common configuration that may be needed and the sniffer component.
2016-07-29 05:22:47 -04:00
--------------------------------------------------
`RestClientBuilder` also allows to optionally set the following configuration
parameters while building the `RestClient` instance:
[DOCS] Rewrite low-level REST client docs and verify snippets compile (#25559) Using the infra that we now have in place, we can convert the low-level REST client docs so that they extract code snippets from real Java classes. This way we make sure that all the snippets properly compile. Compared to the high level REST client docs, in this case we don't run the tests themselves, as that would require depending on test-framework which requires java 8 while the low-level REST client is compatible with java 7. I think that compiling snippets is enough for now.
2017-07-06 04:05:50 -04:00
["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/RestClientDocumentation.java[rest-client-init-default-headers]
--------------------------------------------------
<1> Set the default headers that need to be sent with each request, to
prevent having to specify them with each single request
["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/RestClientDocumentation.java[rest-client-init-max-retry-timeout]
--------------------------------------------------
<1> Set the timeout that should be honoured in case multiple attempts are made
for the same request. The default value is 30 seconds, same as the default
socket timeout. In case the socket timeout is customized, the maximum retry
timeout should be adjusted accordingly
["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/RestClientDocumentation.java[rest-client-init-failure-listener]
--------------------------------------------------
<1> Set a listener that gets notified every time a node fails, in case actions
need to be taken. Used internally when sniffing on failure is enabled.
["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/RestClientDocumentation.java[rest-client-init-request-config-callback]
--------------------------------------------------
<1> Set a callback that allows to modify the default request configuration
Revert "[Docs] Update Java Low-Level documentation to reflect shaded deps (#25882)" (#26411) This reverts commit 91dc1c5da682fd832fc27d07f657643a88f4aae5. Ref #26328
2017-08-29 10:26:36 -04:00
(e.g. request timeouts, authentication, or anything that the
https://hc.apache.org/httpcomponents-client-ga/httpclient/apidocs/org/apache/http/client/config/RequestConfig.Builder.html[`org.apache.http.client.config.RequestConfig.Builder`]
allows to set)
[DOCS] Rewrite low-level REST client docs and verify snippets compile (#25559) Using the infra that we now have in place, we can convert the low-level REST client docs so that they extract code snippets from real Java classes. This way we make sure that all the snippets properly compile. Compared to the high level REST client docs, in this case we don't run the tests themselves, as that would require depending on test-framework which requires java 8 while the low-level REST client is compatible with java 7. I think that compiling snippets is enough for now.
2017-07-06 04:05:50 -04:00
["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/RestClientDocumentation.java[rest-client-init-client-config-callback]
--------------------------------------------------
<1> Set a callback that allows to modify the http client configuration
Revert "[Docs] Update Java Low-Level documentation to reflect shaded deps (#25882)" (#26411) This reverts commit 91dc1c5da682fd832fc27d07f657643a88f4aae5. Ref #26328
2017-08-29 10:26:36 -04:00
(e.g. encrypted communication over ssl, or anything that the
http://hc.apache.org/httpcomponents-asyncclient-dev/httpasyncclient/apidocs/org/apache/http/impl/nio/client/HttpAsyncClientBuilder.html[`org.apache.http.impl.nio.client.HttpAsyncClientBuilder`]
allows to set)
[DOCS] add java REST client docs (#19618) [DOCS] add java REST client docs Add some docs on how to get started with the Java REST client, some common configuration that may be needed and the sniffer component.
2016-07-29 05:22:47 -04:00
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.
2017-02-24 07:52:36 -05:00
[[java-rest-low-usage-requests]]
[DOCS] restructure java clients docs pages (#25517) This commit converts the low level client and high level client chapters into two parts, which allows each high level client supported api to be on a separate page and show up in the index on the right.
2017-07-04 04:58:57 -04:00
=== Performing requests
[DOCS] add java REST client docs (#19618) [DOCS] add java REST client docs Add some docs on how to get started with the Java REST client, some common configuration that may be needed and the sniffer component.
2016-07-29 05:22:47 -04:00
Once the `RestClient` has been created, requests can be sent by calling one of
[DOCS] Document performRequest being renamed to performRequestAsync This updates the docs to reflect that the asynchronous variants were renamed to have "Async" at the end.
2016-08-29 14:27:01 -04:00
the available `performRequest` or `performRequestAsync` method variants.
[DOCS] Rewrite low-level REST client docs and verify snippets compile (#25559) Using the infra that we now have in place, we can convert the low-level REST client docs so that they extract code snippets from real Java classes. This way we make sure that all the snippets properly compile. Compared to the high level REST client docs, in this case we don't run the tests themselves, as that would require depending on test-framework which requires java 8 while the low-level REST client is compatible with java 7. I think that compiling snippets is enough for now.
2017-07-06 04:05:50 -04:00
The `performRequest` methods are synchronous and return the `Response` directly,
meaning that the client will block and wait for a response to be returned.
The `performRequestAsync` variants return `void` and accept an extra
`ResponseListener` as an argument instead, meaning that they are executed
asynchronously. The provided listener will be notified upon request completion
or failure.
["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/RestClientDocumentation.java[rest-client-verb-endpoint]
--------------------------------------------------
<1> Send a request by providing only the verb and the endpoint, minimum set
of required arguments
["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/RestClientDocumentation.java[rest-client-verb-endpoint-params]
--------------------------------------------------
<1> Send a request by providing the verb, the endpoint, and some querystring
parameter
["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/RestClientDocumentation.java[rest-client-verb-endpoint-params-body]
--------------------------------------------------
<1> Send a request by providing the verb, the endpoint, optional querystring
Revert "[Docs] Update Java Low-Level documentation to reflect shaded deps (#25882)" (#26411) This reverts commit 91dc1c5da682fd832fc27d07f657643a88f4aae5. Ref #26328
2017-08-29 10:26:36 -04:00
parameters and the request body enclosed in an `org.apache.http.HttpEntity`
[DOCS] Rewrite low-level REST client docs and verify snippets compile (#25559) Using the infra that we now have in place, we can convert the low-level REST client docs so that they extract code snippets from real Java classes. This way we make sure that all the snippets properly compile. Compared to the high level REST client docs, in this case we don't run the tests themselves, as that would require depending on test-framework which requires java 8 while the low-level REST client is compatible with java 7. I think that compiling snippets is enough for now.
2017-07-06 04:05:50 -04:00
object
IMPORTANT: The `ContentType` specified for the `HttpEntity` is important
because it will be used to set the `Content-Type` header so that Elasticsearch
can properly parse the content.
["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/RestClientDocumentation.java[rest-client-response-consumer]
--------------------------------------------------
<1> Send a request by providing the verb, the endpoint, optional querystring
parameters, optional request body and the optional factory that is used to
Revert "[Docs] Update Java Low-Level documentation to reflect shaded deps (#25882)" (#26411) This reverts commit 91dc1c5da682fd832fc27d07f657643a88f4aae5. Ref #26328
2017-08-29 10:26:36 -04:00
create an http://hc.apache.org/httpcomponents-core-ga/httpcore-nio/apidocs/org/apache/http/nio/protocol/HttpAsyncResponseConsumer.html[`org.apache.http.nio.protocol.HttpAsyncResponseConsumer`]
[DOCS] Rewrite low-level REST client docs and verify snippets compile (#25559) Using the infra that we now have in place, we can convert the low-level REST client docs so that they extract code snippets from real Java classes. This way we make sure that all the snippets properly compile. Compared to the high level REST client docs, in this case we don't run the tests themselves, as that would require depending on test-framework which requires java 8 while the low-level REST client is compatible with java 7. I think that compiling snippets is enough for now.
2017-07-06 04:05:50 -04:00
callback instance per request attempt. Controls how the response body gets
streamed from a non-blocking HTTP connection on the client side. When not
provided, the default implementation is used which buffers the whole response
body in heap memory, up to 100 MB.
["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/RestClientDocumentation.java[rest-client-verb-endpoint-async]
--------------------------------------------------
<1> Define what needs to happen when the request is successfully performed
<2> Define what needs to happen when the request fails, meaning whenever
there's a connection error or a response with error status code is returned.
<3> Send an async request by providing only the verb, the endpoint, and the
response listener to be notified once the request is completed, minimum set
of required arguments
["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/RestClientDocumentation.java[rest-client-verb-endpoint-params-async]
--------------------------------------------------
<1> Send an async request by providing the verb, the endpoint, some querystring
parameter and the response listener to be notified once the request is completed
["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/RestClientDocumentation.java[rest-client-verb-endpoint-params-body-async]
--------------------------------------------------
<1> Send an async request by providing the verb, the endpoint, optional
querystring parameters, the request body enclosed in an
Revert "[Docs] Update Java Low-Level documentation to reflect shaded deps (#25882)" (#26411) This reverts commit 91dc1c5da682fd832fc27d07f657643a88f4aae5. Ref #26328
2017-08-29 10:26:36 -04:00
`org.apache.http.HttpEntity` object and the response listener to be
[DOCS] Rewrite low-level REST client docs and verify snippets compile (#25559) Using the infra that we now have in place, we can convert the low-level REST client docs so that they extract code snippets from real Java classes. This way we make sure that all the snippets properly compile. Compared to the high level REST client docs, in this case we don't run the tests themselves, as that would require depending on test-framework which requires java 8 while the low-level REST client is compatible with java 7. I think that compiling snippets is enough for now.
2017-07-06 04:05:50 -04:00
notified once the request is completed
["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/RestClientDocumentation.java[rest-client-response-consumer-async]
--------------------------------------------------
<1> Send an async request by providing the verb, the endpoint, optional
querystring parameters, optional request body and the optional factory that is
Revert "[Docs] Update Java Low-Level documentation to reflect shaded deps (#25882)" (#26411) This reverts commit 91dc1c5da682fd832fc27d07f657643a88f4aae5. Ref #26328
2017-08-29 10:26:36 -04:00
used to create an http://hc.apache.org/httpcomponents-core-ga/httpcore-nio/apidocs/org/apache/http/nio/protocol/HttpAsyncResponseConsumer.html[`org.apache.http.nio.protocol.HttpAsyncResponseConsumer`]
[DOCS] Rewrite low-level REST client docs and verify snippets compile (#25559) Using the infra that we now have in place, we can convert the low-level REST client docs so that they extract code snippets from real Java classes. This way we make sure that all the snippets properly compile. Compared to the high level REST client docs, in this case we don't run the tests themselves, as that would require depending on test-framework which requires java 8 while the low-level REST client is compatible with java 7. I think that compiling snippets is enough for now.
2017-07-06 04:05:50 -04:00
callback instance per request attempt. Controls how the response body gets
streamed from a non-blocking HTTP connection on the client side. When not
provided, the default implementation is used which buffers the whole response
body in heap memory, up to 100 MB.
The following is a basic example of how async requests can be sent:
["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/RestClientDocumentation.java[rest-client-async-example]
--------------------------------------------------
<1> Process the returned response
<2> Handle the returned exception, due to communication error or a response
with status code that indicates an error
Each of the above listed method supports sending headers along with the
request through a `Header` varargs argument as in the following examples:
["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/RestClientDocumentation.java[rest-client-headers]
--------------------------------------------------
["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/RestClientDocumentation.java[rest-client-headers-async]
--------------------------------------------------
[DOCS] add java REST client docs (#19618) [DOCS] add java REST client docs Add some docs on how to get started with the Java REST client, some common configuration that may be needed and the sniffer component.
2016-07-29 05:22:47 -04:00
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.
2017-02-24 07:52:36 -05:00
[[java-rest-low-usage-responses]]
[DOCS] restructure java clients docs pages (#25517) This commit converts the low level client and high level client chapters into two parts, which allows each high level client supported api to be on a separate page and show up in the index on the right.
2017-07-04 04:58:57 -04:00
=== Reading responses
[DOCS] add java REST client docs (#19618) [DOCS] add java REST client docs Add some docs on how to get started with the Java REST client, some common configuration that may be needed and the sniffer component.
2016-07-29 05:22:47 -04:00
[DOCS] Document performRequest being renamed to performRequestAsync This updates the docs to reflect that the asynchronous variants were renamed to have "Async" at the end.
2016-08-29 14:27:01 -04:00
The `Response` object, either returned by the synchronous `performRequest` methods or
received as an argument in `ResponseListener#onSuccess(Response)`, wraps the
[DOCS] Rewrite low-level REST client docs and verify snippets compile (#25559) Using the infra that we now have in place, we can convert the low-level REST client docs so that they extract code snippets from real Java classes. This way we make sure that all the snippets properly compile. Compared to the high level REST client docs, in this case we don't run the tests themselves, as that would require depending on test-framework which requires java 8 while the low-level REST client is compatible with java 7. I think that compiling snippets is enough for now.
2017-07-06 04:05:50 -04:00
response object returned by the http client and exposes some additional information.
["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/RestClientDocumentation.java[rest-client-response2]
--------------------------------------------------
<1> Information about the performed request
<2> The host that returned the response
<3> The response status line, from which you can for instance retrieve the status code
<4> The response headers, which can also be retrieved by name though `getHeader(String)`
Revert "[Docs] Update Java Low-Level documentation to reflect shaded deps (#25882)" (#26411) This reverts commit 91dc1c5da682fd832fc27d07f657643a88f4aae5. Ref #26328
2017-08-29 10:26:36 -04:00
<5> The response body enclosed in an https://hc.apache.org/httpcomponents-core-ga/httpcore/apidocs/org/apache/http/HttpEntity.html[`org.apache.http.HttpEntity`]
object
[DOCS] add java REST client docs (#19618) [DOCS] add java REST client docs Add some docs on how to get started with the Java REST client, some common configuration that may be needed and the sniffer component.
2016-07-29 05:22:47 -04:00
When performing a request, an exception is thrown (or received as an argument
[DOCS] Document performRequest being renamed to performRequestAsync This updates the docs to reflect that the asynchronous variants were renamed to have "Async" at the end.
2016-08-29 14:27:01 -04:00
in `ResponseListener#onFailure(Exception)` in the following scenarios:
[DOCS] add java REST client docs (#19618) [DOCS] add java REST client docs Add some docs on how to get started with the Java REST client, some common configuration that may be needed and the sniffer component.
2016-07-29 05:22:47 -04:00
[DOCS] Rewrite low-level REST client docs and verify snippets compile (#25559) Using the infra that we now have in place, we can convert the low-level REST client docs so that they extract code snippets from real Java classes. This way we make sure that all the snippets properly compile. Compared to the high level REST client docs, in this case we don't run the tests themselves, as that would require depending on test-framework which requires java 8 while the low-level REST client is compatible with java 7. I think that compiling snippets is enough for now.
2017-07-06 04:05:50 -04:00
`IOException`:: communication problem (e.g. SocketTimeoutException)
[DOCS] add java REST client docs (#19618) [DOCS] add java REST client docs Add some docs on how to get started with the Java REST client, some common configuration that may be needed and the sniffer component.
2016-07-29 05:22:47 -04:00
`ResponseException`:: a response was returned, but its status code indicated
[DOCS] Document performRequest being renamed to performRequestAsync This updates the docs to reflect that the asynchronous variants were renamed to have "Async" at the end.
2016-08-29 14:27:01 -04:00
an error (not `2xx`). A `ResponseException` originates from a valid
[DOCS] add java REST client docs (#19618) [DOCS] add java REST client docs Add some docs on how to get started with the Java REST client, some common configuration that may be needed and the sniffer component.
2016-07-29 05:22:47 -04:00
http response, hence it exposes its corresponding `Response` object which gives
access to the returned response.
[DOCS] Document performRequest being renamed to performRequestAsync This updates the docs to reflect that the asynchronous variants were renamed to have "Async" at the end.
2016-08-29 14:27:01 -04:00
NOTE: A `ResponseException` is **not** thrown for `HEAD` requests that return
a `404` status code because it is an expected `HEAD` response that simply
denotes that the resource is not found. All other HTTP methods (e.g., `GET`)
move ignore parameter support from yaml test client to low level rest client (#22637) All the language clients support a special ignore parameter that doesn't get passed to elasticsearch with the request, but used to indicate which error code should not lead to an exception if returned for a specific request. Moving this to the low level REST client will allow the high level REST client to make use of it too, for instance so that it doesn't have to intercept ResponseExceptions when the get api returns a 404.
2017-01-16 12:54:44 -05:00
throw a `ResponseException` for `404` responses unless the `ignore` parameter
contains `404`. `ignore` is a special client parameter that doesn't get sent
to Elasticsearch and contains a comma separated list of error status codes.
It allows to control whether some error status code should be treated as an
expected response rather than as an exception. This is useful for instance
with the get api as it can return `404` when the document is missing, in which
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.
[DOCS] Document performRequest being renamed to performRequestAsync This updates the docs to reflect that the asynchronous variants were renamed to have "Async" at the end.
2016-08-29 14:27:01 -04:00
[DOCS] add java REST client docs (#19618) [DOCS] add java REST client docs Add some docs on how to get started with the Java REST client, some common configuration that may be needed and the sniffer component.
2016-07-29 05:22:47 -04:00
Note that the low-level client doesn't expose any helper for json marshalling
and un-marshalling. Users are free to use the library that they prefer for that
purpose.
[DOCS] Document performRequest being renamed to performRequestAsync This updates the docs to reflect that the asynchronous variants were renamed to have "Async" at the end.
2016-08-29 14:27:01 -04:00
Revert "[Docs] Update Java Low-Level documentation to reflect shaded deps (#25882)" (#26411) This reverts commit 91dc1c5da682fd832fc27d07f657643a88f4aae5. Ref #26328
2017-08-29 10:26:36 -04:00
The underlying Apache Async Http Client ships with different
https://hc.apache.org/httpcomponents-core-ga/httpcore/apidocs/org/apache/http/HttpEntity.html[`org.apache.http.HttpEntity`]
[DOCS] add java REST client docs (#19618) [DOCS] add java REST client docs Add some docs on how to get started with the Java REST client, some common configuration that may be needed and the sniffer component.
2016-07-29 05:22:47 -04:00
implementations that allow to provide the request body in different formats
(stream, byte array, string etc.). As for reading the response body, the
`HttpEntity#getContent` method comes handy which returns an `InputStream`
reading from the previously buffered response body. As an alternative, it is
Revert "[Docs] Update Java Low-Level documentation to reflect shaded deps (#25882)" (#26411) This reverts commit 91dc1c5da682fd832fc27d07f657643a88f4aae5. Ref #26328
2017-08-29 10:26:36 -04:00
possible to provide a custom
http://hc.apache.org/httpcomponents-core-ga/httpcore-nio/apidocs/org/apache/http/nio/protocol/HttpAsyncResponseConsumer.html[`org.apache.http.nio.protocol.HttpAsyncResponseConsumer`]
[DOCS] add java REST client docs (#19618) [DOCS] add java REST client docs Add some docs on how to get started with the Java REST client, some common configuration that may be needed and the sniffer component.
2016-07-29 05:22:47 -04:00
that controls how bytes are read and buffered.
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.
2017-02-24 07:52:36 -05:00
[[java-rest-low-usage-logging]]
[DOCS] restructure java clients docs pages (#25517) This commit converts the low level client and high level client chapters into two parts, which allows each high level client supported api to be on a separate page and show up in the index on the right.
2017-07-04 04:58:57 -04:00
=== Logging
[DOCS] add java REST client docs (#19618) [DOCS] add java REST client docs Add some docs on how to get started with the Java REST client, some common configuration that may be needed and the sniffer component.
2016-07-29 05:22:47 -04:00
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],
which comes with support for a number of popular logging implementations. The
java packages to enable logging for are `org.elasticsearch.client` for the
client itself and `org.elasticsearch.client.sniffer` for the sniffer.
The request tracer logging can also be enabled to log every request and
corresponding response in curl format. That comes handy when debugging, for
instance in case a request needs to be manually executed to check whether it
still yields the same response as it did. Enable trace logging for the `tracer`
package to have such log lines printed out. Do note that this type of logging is
expensive and should not be enabled at all times in production environments,
but rather temporarily used only when needed.