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/configuration.asciidoc

190 lines
10 KiB
Plaintext
Raw Normal View History

Checkstyle: Catch wide snippets (#34163) We use wrap code in `// tag` and `//end` to include it in our docs. Our current docs style wraps code snippets in a box that is only wide enough for 76 characters and adds a horizontal scroll bar for wider snippets which makes the snippet much harder to read. This adds a checkstyle check that looks for java code that is included in the docs and is wider than that 76 characters so all snippets fit into the box. It solves many of the failures that this catches but suppresses many more. I will clean those up in a follow up change.
2018-10-01 15:22:15 -04:00
[[java-rest-low-config]]
[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
== Common configuration
[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
As explained in <<java-rest-low-usage-initialization>>, the `RestClientBuilder`
supports providing both a `RequestConfigCallback` and an `HttpClientConfigCallback`
which allow for any customization that the Apache Async Http Client exposes.
Those callbacks make it possible to modify some specific behaviour of the client
without overriding every other default configuration that the `RestClient`
is initialized with. This section describes some common scenarios that require
additional configuration for the low-level Java REST Client.
[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] 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
=== Timeouts
[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
Configuring requests timeouts can be done by providing an instance of
`RequestConfigCallback` while building the `RestClient` through its builder.
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 interface has one method that receives an instance of
https://hc.apache.org/httpcomponents-client-ga/httpclient/apidocs/org/apache/http/client/config/RequestConfig.Builder.html[`org.apache.http.client.config.RequestConfig.Builder`]
[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
as an argument and has the same return type. The request config builder can
be modified and then returned. In the following example we increase the
Timeout improvements for rest client and reindex (#21741) Changes the default socket and connection timeouts for the rest client from 10 seconds to the more generous 30 seconds. Defaults reindex-from-remote to those timeouts and make the timeouts configurable like so: ``` POST _reindex { "source": { "remote": { "host": "http://otherhost:9200", "socket_timeout": "1m", "connect_timeout": "10s" }, "index": "source", "query": { "match": { "test": "data" } } }, "dest": { "index": "dest" } } ``` Closes #21707
2016-12-05 10:54:51 -05:00
connect timeout (defaults to 1 second) and the socket timeout (defaults to 30
Remove support for maxRetryTimeout from low-level REST client (#38085) We have had various reports of problems caused by the maxRetryTimeout setting in the low-level REST client. Such setting was initially added in the attempts to not have requests go through retries if the request already took longer than the provided timeout. The implementation was problematic though as such timeout would also expire in the first request attempt (see #31834), would leave the request executing after expiration causing memory leaks (see #33342), and would not take into account the http client internal queuing (see #25951). Given all these issues, it seems that this custom timeout mechanism gives little benefits while causing a lot of harm. We should rather rely on connect and socket timeout exposed by the underlying http client and accept that a request can overall take longer than the configured timeout, which is the case even with a single retry anyways. This commit removes the `maxRetryTimeout` setting and all of its usages.
2019-02-06 02:43:47 -05:00
seconds).
[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
["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-config-timeouts]
[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
--------------------------------------------------
LLRC RequestOptions add RequestConfig (#57972) (#59344) Different kinds of requests may need different request options from the client default. Users can optionally set RequestConfig on a single request's RequestOptions to override the default. Without this, socketTimeout can only set at RestClient initialization. Co-authored-by: weizijun <weizijun1989@gmail.com>
2020-07-14 13:34:53 -04:00
timeouts also can set by RequestOptions per request.this will override RestClient customizeRequestConfig.
["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/RestClientDocumentation.java[rest-client-config-request-options-timeouts]
--------------------------------------------------
[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
=== Number of threads
[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 Apache Http Async Client starts by default one dispatcher thread, and a
number of worker threads used by the connection manager, as many as the number
of locally detected processors (depending on what
`Runtime.getRuntime().availableProcessors()` returns). The number of threads
can be modified 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-config-threads]
[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] 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
=== Basic authentication
[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
Configuring basic authentication can be done by providing an
`HttpClientConfigCallback` while building the `RestClient` through its builder.
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 interface has one method that receives an instance of
https://hc.apache.org/httpcomponents-asyncclient-dev/httpasyncclient/apidocs/org/apache/http/impl/nio/client/HttpAsyncClientBuilder.html[`org.apache.http.impl.nio.client.HttpAsyncClientBuilder`]
[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
as an argument and has the same return type. The http client builder can be
modified and then returned. In the following example we set a default
credentials provider that requires basic authentication.
[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-config-basic-auth]
[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
Preemptive Authentication can be disabled, which means that every request will be sent without
Docs: Fixed a grammatical mistake: 'a HTTP ...' -> 'an HTTP ...' (#33744) Fixed a grammatical mistake: 'a HTTP ...' -> 'an HTTP ...' Closes #33728
2018-09-17 15:35:55 -04:00
authorization headers to see if it is accepted and, upon receiving an HTTP 401 response, it will
Support Preemptive Authentication with RestClient (#21336) This adds the necessary `AuthCache` needed to support preemptive authorization. By adding every host to the cache, the automatically added `RequestAuthCache` interceptor will add credentials on the first pass rather than waiting to do it after _each_ anonymous request is rejected (thus always sending everything twice when basic auth is required).
2017-01-24 11:34:05 -05:00
resend the exact same request with the basic authentication header. If you wish to do this, then
you can do so by disabling it via the `HttpAsyncClientBuilder`:
[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"]
Support Preemptive Authentication with RestClient (#21336) This adds the necessary `AuthCache` needed to support preemptive authorization. By adding every host to the cache, the automatically added `RequestAuthCache` interceptor will add credentials on the first pass rather than waiting to do it after _each_ anonymous request is rejected (thus always sending everything twice when basic auth is required).
2017-01-24 11:34:05 -05: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-config-disable-preemptive-auth]
Support Preemptive Authentication with RestClient (#21336) This adds the necessary `AuthCache` needed to support preemptive authorization. By adding every host to the cache, the automatically added `RequestAuthCache` interceptor will add credentials on the first pass rather than waiting to do it after _each_ anonymous request is rejected (thus always sending everything twice when basic auth is required).
2017-01-24 11:34:05 -05: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
<1> Disable preemptive authentication
Support Preemptive Authentication with RestClient (#21336) This adds the necessary `AuthCache` needed to support preemptive authorization. By adding every host to the cache, the automatically added `RequestAuthCache` interceptor will add credentials on the first pass rather than waiting to do it after _each_ anonymous request is rejected (thus always sending everything twice when basic auth is required).
2017-01-24 11:34:05 -05:00
Add HLRC docs for AuthN and TLS (#51355) (#51551) This commit adds examples in our documentation for - An HLRC instance authenticating to an elasticsearch cluster using an elasticsearch token service access token or an API key - An HLRC instance connecting to an elasticsearch cluster that is setup for TLS on the HTTP layer when the CA certificate of the cluster is available either as a PEM file or a keystore - An HLRC instance connecting to an elasticsearch cluster that requires client authentication where the client key and certificate are available in a keystore Co-Authored-By: Lisa Cawley <lcawley@elastic.co>
2020-01-29 01:14:38 -05:00
=== Other authentication methods
==== Elasticsearch Token Service tokens
If you want the client to authenticate with an Elasticsearch access token, set the relevant HTTP request header.
If the client makes requests on behalf of a single user only, you can set the necessary `Authorization` header as a default header as shown
in the following example:
["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/RestClientDocumentation.java[rest-client-auth-bearer-token]
--------------------------------------------------
==== Elasticsearch API keys
If you want the client to authenticate with an Elasticsearch API key, set the relevant HTTP request header.
If the client makes requests on behalf of a single user only, you can set the necessary `Authorization` header as a default header as shown
in the following example:
["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/RestClientDocumentation.java[rest-client-auth-api-key]
--------------------------------------------------
[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
=== Encrypted communication
[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 HLRC docs for AuthN and TLS (#51355) (#51551) This commit adds examples in our documentation for - An HLRC instance authenticating to an elasticsearch cluster using an elasticsearch token service access token or an API key - An HLRC instance connecting to an elasticsearch cluster that is setup for TLS on the HTTP layer when the CA certificate of the cluster is available either as a PEM file or a keystore - An HLRC instance connecting to an elasticsearch cluster that requires client authentication where the client key and certificate are available in a keystore Co-Authored-By: Lisa Cawley <lcawley@elastic.co>
2020-01-29 01:14:38 -05:00
Encrypted communication using TLS can also be configured through the
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
`HttpClientConfigCallback`. The
https://hc.apache.org/httpcomponents-asyncclient-dev/httpasyncclient/apidocs/org/apache/http/impl/nio/client/HttpAsyncClientBuilder.html[`org.apache.http.impl.nio.client.HttpAsyncClientBuilder`]
[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
received as an argument exposes multiple methods to configure encrypted
communication: `setSSLContext`, `setSSLSessionStrategy` and
`setConnectionManager`, in order of precedence from the least important.
Add HLRC docs for AuthN and TLS (#51355) (#51551) This commit adds examples in our documentation for - An HLRC instance authenticating to an elasticsearch cluster using an elasticsearch token service access token or an API key - An HLRC instance connecting to an elasticsearch cluster that is setup for TLS on the HTTP layer when the CA certificate of the cluster is available either as a PEM file or a keystore - An HLRC instance connecting to an elasticsearch cluster that requires client authentication where the client key and certificate are available in a keystore Co-Authored-By: Lisa Cawley <lcawley@elastic.co>
2020-01-29 01:14:38 -05:00
When accessing an Elasticsearch cluster that is setup for TLS on the HTTP layer, the client needs to trust the certificate that
Elasticsearch is using.
The following is an example of setting up the client to trust the CA that has signed the certificate that Elasticsearch is using, when
that CA certificate is available in a PKCS#12 keystore:
[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
["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-config-encrypted-communication]
[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 HLRC docs for AuthN and TLS (#51355) (#51551) This commit adds examples in our documentation for - An HLRC instance authenticating to an elasticsearch cluster using an elasticsearch token service access token or an API key - An HLRC instance connecting to an elasticsearch cluster that is setup for TLS on the HTTP layer when the CA certificate of the cluster is available either as a PEM file or a keystore - An HLRC instance connecting to an elasticsearch cluster that requires client authentication where the client key and certificate are available in a keystore Co-Authored-By: Lisa Cawley <lcawley@elastic.co>
2020-01-29 01:14:38 -05:00
The following is an example of setting up the client to trust the CA that has signed the certificate that Elasticsearch is using, when
that CA certificate is available as a PEM encoded file.
["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/RestClientDocumentation.java[rest-client-config-trust-ca-pem]
--------------------------------------------------
When Elasticsearch is configured to require client TLS authentication, for example when a PKI realm is configured, the client needs to provide
a client certificate during the TLS handshake in order to authenticate. The following is an example of setting up the client for TLS
authentication with a certificate and a private key that are stored in a PKCS#12 keystore.
["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/RestClientDocumentation.java[rest-client-config-mutual-tls-authentication]
--------------------------------------------------
If the client certificate and key are not available in a keystore but rather as PEM encoded files, you cannot use them
directly to build an SSLContext. You must rely on external libraries to parse the PEM key into a PrivateKey instance. Alternatively, you
can use external tools to build a keystore from your PEM files, as shown in the following example:
```
openssl pkcs12 -export -in client.crt -inkey private_key.pem \
-name "client" -out client.p12
```
RestClient uses system properties and system default SSLContext (#25757) This commit calls the `useSystemProperties` method on the HttpAsyncClientBuilder so that the jvm system properties are used. The primary reason for doing this is to ensure the builder uses the system default SSLContext rather than the default instance created by the http client library. Closes #23231
2017-07-20 09:36:56 -04:00
If no explicit configuration is provided, the http://docs.oracle.com/javase/7/docs/technotes/guides/security/jsse/JSSERefGuide.html#CustomizingStores[system default configuration]
will be used.
[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
=== Others
[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
For any other required configuration needed, the Apache HttpAsyncClient docs
Timeout improvements for rest client and reindex (#21741) Changes the default socket and connection timeouts for the rest client from 10 seconds to the more generous 30 seconds. Defaults reindex-from-remote to those timeouts and make the timeouts configurable like so: ``` POST _reindex { "source": { "remote": { "host": "http://otherhost:9200", "socket_timeout": "1m", "connect_timeout": "10s" }, "index": "source", "query": { "match": { "test": "data" } } }, "dest": { "index": "dest" } } ``` Closes #21707
2016-12-05 10:54:51 -05:00
should be consulted: https://hc.apache.org/httpcomponents-asyncclient-4.1.x/ .
Add note to low-level client docs for DNS caching (#29213) This commit adds a note to the low-level REST client docs regarding the possibility of being impacted by the JVM DNS cache policy under a default security manager policy.
2018-03-22 21:23:52 -04:00
NOTE: If your application runs under the security manager you might be subject
to the JVM default policies of caching positive hostname resolutions
indefinitely and negative hostname resolutions for ten seconds. If the resolved
addresses of the hosts to which you are connecting the client to vary with time
then you might want to modify the default JVM behavior. These can be modified by
adding
http://docs.oracle.com/javase/8/docs/technotes/guides/net/properties.html[`networkaddress.cache.ttl=<timeout>`]
and
http://docs.oracle.com/javase/8/docs/technotes/guides/net/properties.html[`networkaddress.cache.negative.ttl=<timeout>`]
to your
http://docs.oracle.com/javase/8/docs/technotes/guides/security/PolicyFiles.html[Java
security policy].
Node selector per client rather than per request (#31471) We have made node selectors configurable per request, but all of other language clients don't allow for that. A good reason not to do so, is that having a different node selector per request breaks round-robin. This commit makes NodeSelector configurable only at client initialization. It also improves the docs on this matter, important given that a single node selector can still affect round-robin.
2018-06-22 11:15:29 -04:00
=== Node selector
The client sends each request to one of the configured nodes in round-robin
fashion. Nodes can optionally be filtered through a node selector that needs
to be provided when initializing the client. This is useful when sniffing is
enabled, in case only dedicated master nodes should be hit by HTTP requests.
For each request the client will run the eventually configured node selector
to filter the node candidates, then select the next one in the list out of the
remaining ones.
["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/RestClientDocumentation.java[rest-client-init-allocation-aware-selector]
--------------------------------------------------
<1> Set an allocation aware node selector that allows to pick a node in the
local rack if any available, otherwise go to any other node in any rack. It
acts as a preference rather than a strict requirement, given that it goes to
another rack if none of the local nodes are available, rather than returning
no nodes in such case which would make the client forcibly revive a local node
whenever none of the nodes from the preferred rack is available.
WARNING: Node selectors that do not consistently select the same set of nodes
will make round-robin behaviour unpredictable and possibly unfair. The
preference example above is fine as it reasons about availability of nodes
which already affects the predictability of round-robin. Node selection should
not depend on other external factors or round-robin will not work properly.