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 callingsetNodes(Collection)
.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 anIOException
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 newRestClientBuilder
to help withRestClient
creation.static RestClientBuilder
builder(Node... nodes)
Returns a newRestClientBuilder
to help withRestClient
creation.void
close()
java.util.List<Node>
getNodes()
Get the list of nodes that the client knows about.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)
Deprecated.preferperformRequest(Request)
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)
Deprecated.preferperformRequest(Request)
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)
Deprecated.preferperformRequest(Request)
Response
performRequest(java.lang.String method, java.lang.String endpoint, org.apache.http.Header... headers)
Deprecated.preferperformRequest(Request)
Response
performRequest(Request request)
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, HttpAsyncResponseConsumerFactory httpAsyncResponseConsumerFactory, ResponseListener responseListener, org.apache.http.Header... headers)
Deprecated.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)
Deprecated.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)
Deprecated.void
performRequestAsync(java.lang.String method, java.lang.String endpoint, ResponseListener responseListener, org.apache.http.Header... headers)
Deprecated.void
performRequestAsync(Request request, ResponseListener responseListener)
Sends a request to the Elasticsearch cluster that the client points to.void
setHosts(org.apache.http.HttpHost... hosts)
Deprecated.prefersetNodes(Collection)
because it allows you to set metadata for use withNodeSelector
svoid
setNodes(java.util.Collection<Node> nodes)
Replaces the nodes with which the client communicates.
-
-
-
Method Detail
-
builder
public static RestClientBuilder builder(Node... nodes)
Returns a newRestClientBuilder
to help withRestClient
creation. Creates a new builder instance and sets the hosts that the client will send requests to.Prefer this to
builder(HttpHost...)
if you have metadata up front about the nodes. If you don't either one is fine.
-
builder
public static RestClientBuilder builder(org.apache.http.HttpHost... hosts)
Returns a newRestClientBuilder
to help withRestClient
creation. Creates a new builder instance and sets the nodes that the client will send requests to.You can use this if you do not have metadata up front about the nodes. If you do, prefer
builder(Node...)
.- See Also:
Node(HttpHost)
-
setHosts
@Deprecated public void setHosts(org.apache.http.HttpHost... hosts)
Deprecated.prefersetNodes(Collection)
because it allows you to set metadata for use withNodeSelector
sReplaces the hosts with which the client communicates.
-
setNodes
public void setNodes(java.util.Collection<Node> nodes)
Replaces the nodes with which the client communicates.
-
getNodes
public java.util.List<Node> getNodes()
Get the list of nodes that the client knows about. The list is unmodifiable.
-
performRequest
public Response performRequest(Request request) 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 anIOException
will be thrown. This method works by performing an asynchronous call and waiting for the result. If the asynchronous call throws an exception we wrap it and rethrow it so that the stack trace attached to the exception contains the call site. While we attempt to preserve the original exception this isn't always possible and likely haven't covered all of the cases. You can get the original exception fromThrowable.getCause()
.- Parameters:
request
- the request to perform- Returns:
- the response returned by Elasticsearch
- Throws:
java.io.IOException
- in case of a problem or the connection was abortedorg.apache.http.client.ClientProtocolException
- in case of an http protocol errorResponseException
- in case Elasticsearch responded with a status code that indicated an error
-
performRequestAsync
public void performRequestAsync(Request request, ResponseListener responseListener)
Sends a request to the Elasticsearch cluster that the client points to. The request is executed asynchronously and the providedResponseListener
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 anIOException
will be thrown.- Parameters:
request
- the request to performresponseListener
- theResponseListener
to notify when the request is completed or fails
-
performRequest
@Deprecated public Response performRequest(java.lang.String method, java.lang.String endpoint, org.apache.http.Header... headers) throws java.io.IOException
Deprecated.preferperformRequest(Request)
Sends a request to the Elasticsearch cluster that the client points to and waits for the corresponding response to be returned. Shortcut toperformRequest(String, String, Map, HttpEntity, Header...)
but without parameters and request body.- Parameters:
method
- the http methodendpoint
- 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 abortedorg.apache.http.client.ClientProtocolException
- in case of an http protocol errorResponseException
- in case Elasticsearch responded with a status code that indicated an error
-
performRequest
@Deprecated 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
Deprecated.preferperformRequest(Request)
Sends a request to the Elasticsearch cluster that the client points to and waits for the corresponding response to be returned. Shortcut toperformRequest(String, String, Map, HttpEntity, Header...)
but without request body.- Parameters:
method
- the http methodendpoint
- the path of the request (without host and port)params
- the query_string parametersheaders
- the optional request headers- Returns:
- the response returned by Elasticsearch
- Throws:
java.io.IOException
- in case of a problem or the connection was abortedorg.apache.http.client.ClientProtocolException
- in case of an http protocol errorResponseException
- in case Elasticsearch responded with a status code that indicated an error
-
performRequest
@Deprecated 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
Deprecated.preferperformRequest(Request)
Sends a request to the Elasticsearch cluster that the client points to and waits for the corresponding response to be returned. Shortcut toperformRequest(String, String, Map, HttpEntity, HttpAsyncResponseConsumerFactory, Header...)
which doesn't require specifying anHttpAsyncResponseConsumerFactory
instance,HttpAsyncResponseConsumerFactory
will be used to create the needed instances ofHttpAsyncResponseConsumer
.- Parameters:
method
- the http methodendpoint
- the path of the request (without host and port)params
- the query_string parametersentity
- the body of the request, null if not applicableheaders
- the optional request headers- Returns:
- the response returned by Elasticsearch
- Throws:
java.io.IOException
- in case of a problem or the connection was abortedorg.apache.http.client.ClientProtocolException
- in case of an http protocol errorResponseException
- in case Elasticsearch responded with a status code that indicated an error
-
performRequest
@Deprecated 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
Deprecated.preferperformRequest(Request)
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 anIOException
will be thrown. This method works by performing an asynchronous call and waiting for the result. If the asynchronous call throws an exception we wrap it and rethrow it so that the stack trace attached to the exception contains the call site. While we attempt to preserve the original exception this isn't always possible and likely haven't covered all of the cases. You can get the original exception fromThrowable.getCause()
.- Parameters:
method
- the http methodendpoint
- the path of the request (without host and port)params
- the query_string parametersentity
- the body of the request, null if not applicablehttpAsyncResponseConsumerFactory
- theHttpAsyncResponseConsumerFactory
used to create oneHttpAsyncResponseConsumer
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 abortedorg.apache.http.client.ClientProtocolException
- in case of an http protocol errorResponseException
- in case Elasticsearch responded with a status code that indicated an error
-
performRequestAsync
@Deprecated public void performRequestAsync(java.lang.String method, java.lang.String endpoint, ResponseListener responseListener, org.apache.http.Header... headers)
Deprecated.Sends a request to the Elasticsearch cluster that the client points to. Doesn't wait for the response, instead the providedResponseListener
will be notified upon completion or failure. Shortcut toperformRequestAsync(String, String, Map, HttpEntity, ResponseListener, Header...)
but without parameters and request body.- Parameters:
method
- the http methodendpoint
- the path of the request (without host and port)responseListener
- theResponseListener
to notify when the request is completed or failsheaders
- the optional request headers
-
performRequestAsync
@Deprecated 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)
Deprecated.Sends a request to the Elasticsearch cluster that the client points to. Doesn't wait for the response, instead the providedResponseListener
will be notified upon completion or failure. Shortcut toperformRequestAsync(String, String, Map, HttpEntity, ResponseListener, Header...)
but without request body.- Parameters:
method
- the http methodendpoint
- the path of the request (without host and port)params
- the query_string parametersresponseListener
- theResponseListener
to notify when the request is completed or failsheaders
- the optional request headers
-
performRequestAsync
@Deprecated 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)
Deprecated.Sends a request to the Elasticsearch cluster that the client points to. Doesn't wait for the response, instead the providedResponseListener
will be notified upon completion or failure. Shortcut toperformRequestAsync(String, String, Map, HttpEntity, HttpAsyncResponseConsumerFactory, ResponseListener, Header...)
which doesn't require specifying anHttpAsyncResponseConsumerFactory
instance,HttpAsyncResponseConsumerFactory
will be used to create the needed instances ofHttpAsyncResponseConsumer
.- Parameters:
method
- the http methodendpoint
- the path of the request (without host and port)params
- the query_string parametersentity
- the body of the request, null if not applicableresponseListener
- theResponseListener
to notify when the request is completed or failsheaders
- the optional request headers
-
performRequestAsync
@Deprecated 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)
Deprecated.Sends a request to the Elasticsearch cluster that the client points to. The request is executed asynchronously and the providedResponseListener
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 anIOException
will be thrown.- Parameters:
method
- the http methodendpoint
- the path of the request (without host and port)params
- the query_string parametersentity
- the body of the request, null if not applicablehttpAsyncResponseConsumerFactory
- theHttpAsyncResponseConsumerFactory
used to create oneHttpAsyncResponseConsumer
callback per retry. Controls how the response body gets streamed from a non-blocking HTTP connection on the client side.responseListener
- theResponseListener
to notify when the request is completed or failsheaders
- the optional request headers
-
close
public void close() throws java.io.IOException
- Specified by:
close
in interfacejava.lang.AutoCloseable
- Specified by:
close
in interfacejava.io.Closeable
- Throws:
java.io.IOException
-
-