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(Request) 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)

      • 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

      • 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