Package org.elasticsearch.client

Class RestClient

java.lang.Object

org.elasticsearch.client.RestClient

All Implemented Interfaces:

java.io.Closeable, java.lang.AutoCloseable

public class RestClient
extends java.lang.Object
implements java.io.Closeable

Client that connects to an Elasticsearch cluster through HTTP.

Must be created using RestClientBuilder, which allows to set all the different options or just rely on defaults. The hosts that are part of the cluster need to be provided at creation time, but can also be replaced later by calling setHosts(HttpHost...).

The method performRequest(String, String, Map, HttpEntity, Header...) allows to send a request to the cluster. When sending a request, a host gets selected out of the provided ones in a round-robin fashion. Failing hosts are marked dead and retried after a certain amount of time (minimum 1 minute, maximum 30 minutes), depending on how many times they previously failed (the more failures, the later they will be retried). In case of failures all of the alive nodes (or dead nodes that deserve a retry) are retried until one responds or none of them does, in which case an IOException will be thrown.

Requests can be either synchronous or asynchronous. The asynchronous variants all end with Async.

Requests can be traced by enabling trace logging for "tracer". The trace logger outputs requests and responses in curl format.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	RestClient.FailureListener	Listener that allows to be notified whenever a failure happens.

Method Summary

Modifier and Type	Method	Description
static RestClientBuilder	builder(org.apache.http.HttpHost... hosts)	Returns a new RestClientBuilder to help with RestClient creation.
void	close()
Response	performRequest(java.lang.String method, java.lang.String endpoint, java.util.Map<java.lang.String,java.lang.String> params, org.apache.http.Header... headers)	Sends a request to the Elasticsearch cluster that the client points to and waits for the corresponding response to be returned.
Response	performRequest(java.lang.String method, java.lang.String endpoint, java.util.Map<java.lang.String,java.lang.String> params, org.apache.http.HttpEntity entity, org.apache.http.Header... headers)	Sends a request to the Elasticsearch cluster that the client points to and waits for the corresponding response to be returned.
Response	performRequest(java.lang.String method, java.lang.String endpoint, java.util.Map<java.lang.String,java.lang.String> params, org.apache.http.HttpEntity entity, HttpAsyncResponseConsumerFactory httpAsyncResponseConsumerFactory, org.apache.http.Header... headers)	Sends a request to the Elasticsearch cluster that the client points to.
Response	performRequest(java.lang.String method, java.lang.String endpoint, org.apache.http.Header... headers)	Sends a request to the Elasticsearch cluster that the client points to and waits for the corresponding response to be returned.
void	performRequestAsync(java.lang.String method, java.lang.String endpoint, java.util.Map<java.lang.String,java.lang.String> params, org.apache.http.HttpEntity entity, HttpAsyncResponseConsumerFactory httpAsyncResponseConsumerFactory, ResponseListener responseListener, org.apache.http.Header... headers)	Sends a request to the Elasticsearch cluster that the client points to.
void	performRequestAsync(java.lang.String method, java.lang.String endpoint, java.util.Map<java.lang.String,java.lang.String> params, org.apache.http.HttpEntity entity, ResponseListener responseListener, org.apache.http.Header... headers)	Sends a request to the Elasticsearch cluster that the client points to.
void	performRequestAsync(java.lang.String method, java.lang.String endpoint, java.util.Map<java.lang.String,java.lang.String> params, ResponseListener responseListener, org.apache.http.Header... headers)	Sends a request to the Elasticsearch cluster that the client points to.
void	performRequestAsync(java.lang.String method, java.lang.String endpoint, ResponseListener responseListener, org.apache.http.Header... headers)	Sends a request to the Elasticsearch cluster that the client points to.
void	setHosts(org.apache.http.HttpHost... hosts)	Replaces the hosts that the client communicates with.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

builder

public static RestClientBuilder builder(org.apache.http.HttpHost... hosts)

Returns a new RestClientBuilder to help with RestClient creation. Creates a new builder instance and sets the hosts that the client will send requests to.

setHosts

public void setHosts(org.apache.http.HttpHost... hosts)

Replaces the hosts that the client communicates with.

See Also:

HttpHost

performRequest

public Response performRequest(java.lang.String method,
                               java.lang.String endpoint,
                               org.apache.http.Header... headers)
                        throws java.io.IOException

Sends a request to the Elasticsearch cluster that the client points to and waits for the corresponding response to be returned. Shortcut to performRequest(String, String, Map, HttpEntity, Header...) but without parameters and request body.

Parameters:

method - the http method

endpoint - the path of the request (without host and port)

headers - the optional request headers

Returns:

the response returned by Elasticsearch

Throws:

java.io.IOException - in case of a problem or the connection was aborted

org.apache.http.client.ClientProtocolException - in case of an http protocol error

ResponseException - in case Elasticsearch responded with a status code that indicated an error

performRequest

public Response performRequest(java.lang.String method,
                               java.lang.String endpoint,
                               java.util.Map<java.lang.String,java.lang.String> params,
                               org.apache.http.Header... headers)
                        throws java.io.IOException

Sends a request to the Elasticsearch cluster that the client points to and waits for the corresponding response to be returned. Shortcut to performRequest(String, String, Map, HttpEntity, Header...) but without request body.

Parameters:

method - the http method

endpoint - the path of the request (without host and port)

params - the query_string parameters

headers - the optional request headers

Returns:

the response returned by Elasticsearch

Throws:

java.io.IOException - in case of a problem or the connection was aborted

org.apache.http.client.ClientProtocolException - in case of an http protocol error

ResponseException - in case Elasticsearch responded with a status code that indicated an error

performRequest

public Response performRequest(java.lang.String method,
                               java.lang.String endpoint,
                               java.util.Map<java.lang.String,java.lang.String> params,
                               org.apache.http.HttpEntity entity,
                               org.apache.http.Header... headers)
                        throws java.io.IOException

Sends a request to the Elasticsearch cluster that the client points to and waits for the corresponding response to be returned. Shortcut to performRequest(String, String, Map, HttpEntity, HttpAsyncResponseConsumerFactory, Header...) which doesn't require specifying an HttpAsyncResponseConsumerFactory instance, HttpAsyncResponseConsumerFactory will be used to create the needed instances of HttpAsyncResponseConsumer.

Parameters:

method - the http method

endpoint - the path of the request (without host and port)

params - the query_string parameters

entity - the body of the request, null if not applicable

headers - the optional request headers

Returns:

the response returned by Elasticsearch

Throws:

java.io.IOException - in case of a problem or the connection was aborted

org.apache.http.client.ClientProtocolException - in case of an http protocol error

ResponseException - in case Elasticsearch responded with a status code that indicated an error

performRequest

public Response performRequest(java.lang.String method,
                               java.lang.String endpoint,
                               java.util.Map<java.lang.String,java.lang.String> params,
                               org.apache.http.HttpEntity entity,
                               HttpAsyncResponseConsumerFactory httpAsyncResponseConsumerFactory,
                               org.apache.http.Header... headers)
                        throws java.io.IOException

Sends a request to the Elasticsearch cluster that the client points to. Blocks until the request is completed and returns its response or fails by throwing an exception. Selects a host out of the provided ones in a round-robin fashion. Failing hosts are marked dead and retried after a certain amount of time (minimum 1 minute, maximum 30 minutes), depending on how many times they previously failed (the more failures, the later they will be retried). In case of failures all of the alive nodes (or dead nodes that deserve a retry) are retried until one responds or none of them does, in which case an IOException will be thrown.

Parameters:

method - the http method

endpoint - the path of the request (without host and port)

params - the query_string parameters

entity - the body of the request, null if not applicable

httpAsyncResponseConsumerFactory - the HttpAsyncResponseConsumerFactory used to create one HttpAsyncResponseConsumer callback per retry. Controls how the response body gets streamed from a non-blocking HTTP connection on the client side.

headers - the optional request headers

Returns:

the response returned by Elasticsearch

Throws:

java.io.IOException - in case of a problem or the connection was aborted

org.apache.http.client.ClientProtocolException - in case of an http protocol error

ResponseException - in case Elasticsearch responded with a status code that indicated an error

performRequestAsync

public void performRequestAsync(java.lang.String method,
                                java.lang.String endpoint,
                                ResponseListener responseListener,
                                org.apache.http.Header... headers)

Sends a request to the Elasticsearch cluster that the client points to. Doesn't wait for the response, instead the provided ResponseListener will be notified upon completion or failure. Shortcut to performRequestAsync(String, String, Map, HttpEntity, ResponseListener, Header...) but without parameters and request body.

Parameters:

method - the http method

endpoint - the path of the request (without host and port)

responseListener - the ResponseListener to notify when the request is completed or fails

headers - the optional request headers

performRequestAsync

public void performRequestAsync(java.lang.String method,
                                java.lang.String endpoint,
                                java.util.Map<java.lang.String,java.lang.String> params,
                                ResponseListener responseListener,
                                org.apache.http.Header... headers)

Sends a request to the Elasticsearch cluster that the client points to. Doesn't wait for the response, instead the provided ResponseListener will be notified upon completion or failure. Shortcut to performRequestAsync(String, String, Map, HttpEntity, ResponseListener, Header...) but without request body.

Parameters:

method - the http method

endpoint - the path of the request (without host and port)

params - the query_string parameters

responseListener - the ResponseListener to notify when the request is completed or fails

headers - the optional request headers

performRequestAsync

public void performRequestAsync(java.lang.String method,
                                java.lang.String endpoint,
                                java.util.Map<java.lang.String,java.lang.String> params,
                                org.apache.http.HttpEntity entity,
                                ResponseListener responseListener,
                                org.apache.http.Header... headers)

Sends a request to the Elasticsearch cluster that the client points to. Doesn't wait for the response, instead the provided ResponseListener will be notified upon completion or failure. Shortcut to performRequestAsync(String, String, Map, HttpEntity, HttpAsyncResponseConsumerFactory, ResponseListener, Header...) which doesn't require specifying an HttpAsyncResponseConsumerFactory instance, HttpAsyncResponseConsumerFactory will be used to create the needed instances of HttpAsyncResponseConsumer.

Parameters:

method - the http method

endpoint - the path of the request (without host and port)

params - the query_string parameters

entity - the body of the request, null if not applicable

responseListener - the ResponseListener to notify when the request is completed or fails

headers - the optional request headers

performRequestAsync

public void performRequestAsync(java.lang.String method,
                                java.lang.String endpoint,
                                java.util.Map<java.lang.String,java.lang.String> params,
                                org.apache.http.HttpEntity entity,
                                HttpAsyncResponseConsumerFactory httpAsyncResponseConsumerFactory,
                                ResponseListener responseListener,
                                org.apache.http.Header... headers)

Sends a request to the Elasticsearch cluster that the client points to. The request is executed asynchronously and the provided ResponseListener gets notified upon request completion or failure. Selects a host out of the provided ones in a round-robin fashion. Failing hosts are marked dead and retried after a certain amount of time (minimum 1 minute, maximum 30 minutes), depending on how many times they previously failed (the more failures, the later they will be retried). In case of failures all of the alive nodes (or dead nodes that deserve a retry) are retried until one responds or none of them does, in which case an IOException will be thrown.

Parameters:

method - the http method

endpoint - the path of the request (without host and port)

params - the query_string parameters

entity - the body of the request, null if not applicable

httpAsyncResponseConsumerFactory - the HttpAsyncResponseConsumerFactory used to create one HttpAsyncResponseConsumer callback per retry. Controls how the response body gets streamed from a non-blocking HTTP connection on the client side.

responseListener - the ResponseListener to notify when the request is completed or fails

headers - the optional request headers

close

public void close()
           throws java.io.IOException

Specified by:

close in interface java.lang.AutoCloseable

Specified by:

close in interface java.io.Closeable

Throws:

java.io.IOException