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 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 Details

    • builder

      public static RestClientBuilder builder​(java.lang.String cloudId)
      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.
      Parameters:
      cloudId - a valid elastic cloud cloudId that will route to a cluster. The cloudId is located in the user console https://cloud.elastic.co and will resemble a string like the following optionalHumanReadableName:dXMtZWFzdC0xLmF3cy5mb3VuZC5pbyRlbGFzdGljc2VhcmNoJGtpYmFuYQ==

    • 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 Cancellable 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