Package org.elasticsearch.client

Class 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 setNodes(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 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.

    • Method Detail

      • builder

        public static RestClientBuilder builder​(Node... nodes)
        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.

        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 new RestClientBuilder to help with RestClient 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.
        prefer setNodes(Collection) because it allows you to set metadata for use with NodeSelectors
        Replaces 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 an IOException 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 from Throwable.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 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​(Request request,
                                ResponseListener responseListener)
        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:
        request - the request to perform
        responseListener - the ResponseListener 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.
        prefer performRequest(Request)
        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

        @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.
        prefer performRequest(Request)
        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

        @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.
        prefer performRequest(Request)
        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

        @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.
        prefer performRequest(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 an IOException 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 from Throwable.getCause().
        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

        @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.
        prefer performRequestAsync(Request, ResponseListener)
        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

        @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.
        prefer performRequestAsync(Request, ResponseListener)
        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