Skip to content

Commit 1fec464

Browse files
colleenmcginniscolleenmcginnis
committed
add migrated files
1 parent bc8a5fe commit 1fec464

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

64 files changed

+4087
-0
lines changed

‎docs/docset.yml

Lines changed: 491 additions & 0 deletions
Large diffs are not rendered by default.

‎docs/images/create-api-key.png

78.7 KB
Loading

‎docs/images/es-endpoint.jpg

361 KB
Loading

‎docs/images/otel-waterfall-instrumented-without-http.jpg

134 KB
Loading

‎docs/images/otel-waterfall-instrumented.jpg

185 KB
Loading

‎docs/images/otel-waterfall-retries.jpg

131 KB
Loading

‎docs/reference/_basic_authentication.md

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
---
2+
mapped_pages:
3+
- https://www.elastic.co/guide/en/elasticsearch/client/java-api-client/current/_basic_authentication.html
4+
---
5+
6+
# Basic authentication [_basic_authentication]
7+
8+
Configuring basic authentication can be done by providing an `HttpClientConfigCallback` while building the `RestClient` through its builder. The interface has one method that receives an instance of [`org.apache.http.impl.nio.client.HttpAsyncClientBuilder`](https://hc.apache.org/httpcomponents-asyncclient-4.1.x/current/httpasyncclient/apidocs/org/apache/http/impl/nio/client/HttpAsyncClientBuilder.md) 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.
9+
10+
```java
11+
final CredentialsProvider credentialsProvider =
12+
new BasicCredentialsProvider();
13+
credentialsProvider.setCredentials(AuthScope.ANY,
14+
new UsernamePasswordCredentials("user", "test-user-password"));
15+
16+
RestClientBuilder builder = RestClient.builder(
17+
new HttpHost("localhost", 9200))
18+
.setHttpClientConfigCallback(new HttpClientConfigCallback() {
19+
@Override
20+
public HttpAsyncClientBuilder customizeHttpClient(
21+
HttpAsyncClientBuilder httpClientBuilder) {
22+
return httpClientBuilder
23+
.setDefaultCredentialsProvider(credentialsProvider);
24+
}
25+
});
26+
```
27+
28+
Preemptive Authentication can be disabled, which means that every request will be sent without authorization headers to see if it is accepted and, upon receiving an HTTP 401 response, it will 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`:
29+
30+
```java
31+
final CredentialsProvider credentialsProvider =
32+
new BasicCredentialsProvider();
33+
credentialsProvider.setCredentials(AuthScope.ANY,
34+
new UsernamePasswordCredentials("user", "test-user-password"));
35+
36+
RestClientBuilder builder = RestClient.builder(
37+
new HttpHost("localhost", 9200))
38+
.setHttpClientConfigCallback(new HttpClientConfigCallback() {
39+
@Override
40+
public HttpAsyncClientBuilder customizeHttpClient(
41+
HttpAsyncClientBuilder httpClientBuilder) {
42+
httpClientBuilder.disableAuthCaching(); <1>
43+
return httpClientBuilder
44+
.setDefaultCredentialsProvider(credentialsProvider);
45+
}
46+
});
47+
```
48+
49+
1. Disable preemptive authentication
50+
51+

‎docs/reference/_encrypted_communication.md

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
---
2+
mapped_pages:
3+
- https://www.elastic.co/guide/en/elasticsearch/client/java-api-client/current/_encrypted_communication.html
4+
---
5+
6+
# Encrypted communication [_encrypted_communication]
7+
8+
Encrypted communication using TLS can also be configured through the `HttpClientConfigCallback`. The [`org.apache.http.impl.nio.client.HttpAsyncClientBuilder`](https://hc.apache.org/httpcomponents-asyncclient-4.1.x/current/httpasyncclient/apidocs/org/apache/http/impl/nio/client/HttpAsyncClientBuilder.md) received as an argument exposes multiple methods to configure encrypted communication: `setSSLContext`, `setSSLSessionStrategy` and `setConnectionManager`, in order of precedence from the least important.
9+
10+
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:
11+
12+
```java
13+
Path trustStorePath = Paths.get("/path/to/truststore.p12");
14+
KeyStore truststore = KeyStore.getInstance("pkcs12");
15+
try (InputStream is = Files.newInputStream(trustStorePath)) {
16+
truststore.load(is, keyStorePass.toCharArray());
17+
}
18+
SSLContextBuilder sslBuilder = SSLContexts.custom()
19+
.loadTrustMaterial(truststore, null);
20+
final SSLContext sslContext = sslBuilder.build();
21+
RestClientBuilder builder = RestClient.builder(
22+
new HttpHost("localhost", 9200, "https"))
23+
.setHttpClientConfigCallback(new HttpClientConfigCallback() {
24+
@Override
25+
public HttpAsyncClientBuilder customizeHttpClient(
26+
HttpAsyncClientBuilder httpClientBuilder) {
27+
return httpClientBuilder.setSSLContext(sslContext);
28+
}
29+
});
30+
```
31+
32+
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.
33+
34+
```java
35+
Path caCertificatePath = Paths.get("/path/to/ca.crt");
36+
CertificateFactory factory =
37+
CertificateFactory.getInstance("X.509");
38+
Certificate trustedCa;
39+
try (InputStream is = Files.newInputStream(caCertificatePath)) {
40+
trustedCa = factory.generateCertificate(is);
41+
}
42+
KeyStore trustStore = KeyStore.getInstance("pkcs12");
43+
trustStore.load(null, null);
44+
trustStore.setCertificateEntry("ca", trustedCa);
45+
SSLContextBuilder sslContextBuilder = SSLContexts.custom()
46+
.loadTrustMaterial(trustStore, null);
47+
final SSLContext sslContext = sslContextBuilder.build();
48+
RestClient.builder(
49+
new HttpHost("localhost", 9200, "https"))
50+
.setHttpClientConfigCallback(new HttpClientConfigCallback() {
51+
@Override
52+
public HttpAsyncClientBuilder customizeHttpClient(
53+
HttpAsyncClientBuilder httpClientBuilder) {
54+
return httpClientBuilder.setSSLContext(sslContext);
55+
}
56+
});
57+
```
58+
59+
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.
60+
61+
```java
62+
Path trustStorePath = Paths.get("/path/to/your/truststore.p12");
63+
Path keyStorePath = Paths.get("/path/to/your/keystore.p12");
64+
KeyStore trustStore = KeyStore.getInstance("pkcs12");
65+
KeyStore keyStore = KeyStore.getInstance("pkcs12");
66+
try (InputStream is = Files.newInputStream(trustStorePath)) {
67+
trustStore.load(is, trustStorePass.toCharArray());
68+
}
69+
try (InputStream is = Files.newInputStream(keyStorePath)) {
70+
keyStore.load(is, keyStorePass.toCharArray());
71+
}
72+
SSLContextBuilder sslBuilder = SSLContexts.custom()
73+
.loadTrustMaterial(trustStore, null)
74+
.loadKeyMaterial(keyStore, keyStorePass.toCharArray());
75+
final SSLContext sslContext = sslBuilder.build();
76+
RestClientBuilder builder = RestClient.builder(
77+
new HttpHost("localhost", 9200, "https"))
78+
.setHttpClientConfigCallback(new HttpClientConfigCallback() {
79+
@Override
80+
public HttpAsyncClientBuilder customizeHttpClient(
81+
HttpAsyncClientBuilder httpClientBuilder) {
82+
return httpClientBuilder.setSSLContext(sslContext);
83+
}
84+
});
85+
```
86+
87+
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:
88+
89+
```
90+
openssl pkcs12 -export -in client.crt -inkey private_key.pem \
91+
-name "client" -out client.p12
92+
```
93+
94+
If no explicit configuration is provided, the [system default configuration](https://docs.oracle.com/javase/7/docs/technotes/guides/security/jsse/JSSERefGuide.md#CustomizingStores) will be used.
95+

‎docs/reference/_license.md

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
---
2+
mapped_pages:
3+
- https://www.elastic.co/guide/en/elasticsearch/client/java-api-client/current/_license.html
4+
---
5+
6+
# License [_license]
7+
8+
Copyright 2013-2019 Elasticsearch
9+
10+
Licensed 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
11+
12+
```
13+
http://www.apache.org/licenses/LICENSE-2.0
14+
```
15+
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.
16+

‎docs/reference/_maven_repository.md

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
---
2+
mapped_pages:
3+
- https://www.elastic.co/guide/en/elasticsearch/client/java-api-client/current/_maven_repository.html
4+
---
5+
6+
# Maven Repository [_maven_repository]
7+
8+
The REST client sniffer is subject to the same release cycle as Elasticsearch. Replace the version with the desired sniffer version, first released with `5.0.0-alpha4`. There is no relation between the sniffer version and the Elasticsearch version that the client can communicate with. Sniffer supports fetching the nodes list from Elasticsearch 2.x and onwards.
9+
10+
If you are looking for a SNAPSHOT version, the Elastic Maven Snapshot repository is available at [https://snapshots.elastic.co/maven/](https://snapshots.elastic.co/maven/).
11+
12+
## Maven configuration [_maven_configuration]
13+
14+
Here is how you can configure the dependency using maven as a dependency manager. Add the following to your `pom.xml` file:
15+
16+
```xml
17+
<dependency>
18+
<groupId>org.elasticsearch.client</groupId>
19+
<artifactId>elasticsearch-rest-client-sniffer</artifactId>
20+
<version>9.0.0-beta1</version>
21+
</dependency>
22+
```
23+
24+
25+
## Gradle configuration [_gradle_configuration]
26+
27+
Here is how you can configure the dependency using gradle as a dependency manager. Add the following to your `build.gradle` file:
28+
29+
```groovy
30+
dependencies {
31+
compile 'org.elasticsearch.client:elasticsearch-rest-client-sniffer:9.0.0-beta1'
32+
}
33+
```
34+
35+

‎docs/reference/_node_selector.md

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
---
2+
mapped_pages:
3+
- https://www.elastic.co/guide/en/elasticsearch/client/java-api-client/current/_node_selector.html
4+
---
5+
6+
# Node selector [_node_selector]
7+
8+
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 no 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.
9+
10+
```java
11+
RestClientBuilder builder = RestClient.builder(
12+
new HttpHost("localhost", 9200, "http"));
13+
builder.setNodeSelector(new NodeSelector() { <1>
14+
@Override
15+
public void select(Iterable<Node> nodes) {
16+
/*
17+
* Prefer any node that belongs to rack_one. If none is around
18+
* we will go to another rack till it's time to try and revive
19+
* some of the nodes that belong to rack_one.
20+
*/
21+
boolean foundOne = false;
22+
for (Node node : nodes) {
23+
String rackId = node.getAttributes().get("rack_id").get(0);
24+
if ("rack_one".equals(rackId)) {
25+
foundOne = true;
26+
break;
27+
}
28+
}
29+
if (foundOne) {
30+
Iterator<Node> nodesIt = nodes.iterator();
31+
while (nodesIt.hasNext()) {
32+
Node node = nodesIt.next();
33+
String rackId = node.getAttributes().get("rack_id").get(0);
34+
if ("rack_one".equals(rackId) == false) {
35+
nodesIt.remove();
36+
}
37+
}
38+
}
39+
}
40+
});
41+
```
42+
43+
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.
44+
45+
46+
::::{warning}
47+
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.
48+
::::
49+
50+

‎docs/reference/_number_of_threads.md

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
---
2+
mapped_pages:
3+
- https://www.elastic.co/guide/en/elasticsearch/client/java-api-client/current/_number_of_threads.html
4+
---
5+
6+
# Number of threads [_number_of_threads]
7+
8+
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:
9+
10+
```java
11+
RestClientBuilder builder = RestClient.builder(
12+
new HttpHost("localhost", 9200))
13+
.setHttpClientConfigCallback(new HttpClientConfigCallback() {
14+
@Override
15+
public HttpAsyncClientBuilder customizeHttpClient(
16+
HttpAsyncClientBuilder httpClientBuilder) {
17+
return httpClientBuilder.setDefaultIOReactorConfig(
18+
IOReactorConfig.custom()
19+
.setIoThreadCount(1)
20+
.build());
21+
}
22+
});
23+
```
24+

‎docs/reference/_other_authentication_methods.md

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
---
2+
mapped_pages:
3+
- https://www.elastic.co/guide/en/elasticsearch/client/java-api-client/current/_other_authentication_methods.html
4+
---
5+
6+
# Other authentication methods [_other_authentication_methods]
7+
8+
## Elasticsearch Token Service tokens [_elasticsearch_token_service_tokens]
9+
10+
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:
11+
12+
```java
13+
RestClientBuilder builder = RestClient.builder(
14+
new HttpHost("localhost", 9200, "http"));
15+
Header[] defaultHeaders =
16+
new Header[]{new BasicHeader("Authorization",
17+
"Bearer u6iuAxZ0RG1Kcm5jVFI4eU4tZU9aVFEwT2F3")};
18+
builder.setDefaultHeaders(defaultHeaders);
19+
```
20+
21+
22+
## Elasticsearch API keys [_elasticsearch_api_keys]
23+
24+
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:
25+
26+
```java
27+
String apiKeyId = "uqlEyn8B_gQ_jlvwDIvM";
28+
String apiKeySecret = "HxHWk2m4RN-V_qg9cDpuX";
29+
String apiKeyAuth =
30+
Base64.getEncoder().encodeToString(
31+
(apiKeyId + ":" + apiKeySecret)
32+
.getBytes(StandardCharsets.UTF_8));
33+
RestClientBuilder builder = RestClient.builder(
34+
new HttpHost("localhost", 9200, "http"));
35+
Header[] defaultHeaders =
36+
new Header[]{new BasicHeader("Authorization",
37+
"ApiKey " + apiKeyAuth)};
38+
builder.setDefaultHeaders(defaultHeaders);
39+
```
40+
41+

‎docs/reference/_others.md

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
mapped_pages:
3+
- https://www.elastic.co/guide/en/elasticsearch/client/java-api-client/current/_others.html
4+
---
5+
6+
# Others [_others]
7+
8+
For any other required configuration needed, the Apache HttpAsyncClient docs should be consulted: [https://hc.apache.org/httpcomponents-asyncclient-4.1.x/](https://hc.apache.org/httpcomponents-asyncclient-4.1.x/) .
9+
10+
::::{note}
11+
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 [`networkaddress.cache.ttl=<timeout>`](https://docs.oracle.com/javase/8/docs/technotes/guides/net/properties.md) and [`networkaddress.cache.negative.ttl=<timeout>`](https://docs.oracle.com/javase/8/docs/technotes/guides/net/properties.md) to your [Java security policy](https://docs.oracle.com/javase/8/docs/technotes/guides/security/PolicyFiles.md).
12+
::::
13+
14+

‎docs/reference/_timeouts.md

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
mapped_pages:
3+
- https://www.elastic.co/guide/en/elasticsearch/client/java-api-client/current/_timeouts.html
4+
---
5+
6+
# Timeouts [_timeouts]
7+
8+
Configuring requests timeouts can be done by providing an instance of `RequestConfigCallback` while building the `RestClient` through its builder. The interface has one method that receives an instance of [`org.apache.http.client.config.RequestConfig.Builder`](https://hc.apache.org/httpcomponents-client-4.5.x/current/httpclient/apidocs/org/apache/http/client/config/RequestConfig.Builder.md) 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 connect timeout (defaults to 1 second) and the socket timeout (defaults to 30 seconds).
9+
10+
```java
11+
RestClientBuilder builder = RestClient.builder(
12+
new HttpHost("localhost", 9200))
13+
.setRequestConfigCallback(
14+
new RestClientBuilder.RequestConfigCallback() {
15+
@Override
16+
public RequestConfig.Builder customizeRequestConfig(
17+
RequestConfig.Builder requestConfigBuilder) {
18+
return requestConfigBuilder
19+
.setConnectTimeout(5000)
20+
.setSocketTimeout(60000);
21+
}
22+
});
23+
```
24+
25+
Timeouts also can be set per request with RequestOptions, which overrides RestClient customizeRequestConfig.
26+
27+
```java
28+
RequestConfig requestConfig = RequestConfig.custom()
29+
.setConnectTimeout(5000)
30+
.setSocketTimeout(60000)
31+
.build();
32+
RequestOptions options = RequestOptions.DEFAULT.toBuilder()
33+
.setRequestConfig(requestConfig)
34+
.build();
35+
```
36+

0 commit comments

Comments
 (0)