Performing requests

edit

Once the RestClient has been created, requests can be sent by calling one of the available performRequest or performRequestAsync method variants. The performRequest methods are synchronous and return the Response directly, meaning that the client will block and wait for a response to be returned. The performRequestAsync variants return void and accept an extra ResponseListener as an argument instead, meaning that they are executed asynchronously. The provided listener will be notified upon request completion or failure.

Response response = restClient.performRequest("GET", "/"); 

Send a request by providing only the verb and the endpoint, minimum set of required arguments

Map<String, String> params = Collections.singletonMap("pretty", "true");
Response response = restClient.performRequest("GET", "/", params); 

Send a request by providing the verb, the endpoint, and some querystring parameter

Map<String, String> params = Collections.emptyMap();
String jsonString = "{" +
            "\"user\":\"kimchy\"," +
            "\"postDate\":\"2013-01-30\"," +
            "\"message\":\"trying out Elasticsearch\"" +
        "}";
HttpEntity entity = new NStringEntity(jsonString, ContentType.APPLICATION_JSON);
Response response = restClient.performRequest("PUT", "/posts/doc/1", params, entity); 

Send a request by providing the verb, the endpoint, optional querystring parameters and the request body enclosed in an org.apache.http.HttpEntity object

The ContentType specified for the HttpEntity is important because it will be used to set the Content-Type header so that Elasticsearch can properly parse the content.

Map<String, String> params = Collections.emptyMap();
HttpAsyncResponseConsumerFactory.HeapBufferedResponseConsumerFactory consumerFactory =
        new HttpAsyncResponseConsumerFactory.HeapBufferedResponseConsumerFactory(30 * 1024 * 1024);
Response response = restClient.performRequest("GET", "/posts/_search", params, null, consumerFactory); 

Send a request by providing the verb, the endpoint, optional querystring parameters, optional request body and the optional factory that is used to create an org.apache.http.nio.protocol.HttpAsyncResponseConsumer callback instance per request attempt. Controls how the response body gets streamed from a non-blocking HTTP connection on the client side. When not provided, the default implementation is used which buffers the whole response body in heap memory, up to 100 MB.

ResponseListener responseListener = new ResponseListener() {
    @Override
    public void onSuccess(Response response) {
        
    }

    @Override
    public void onFailure(Exception exception) {
        
    }
};
restClient.performRequestAsync("GET", "/", responseListener); 

Define what needs to happen when the request is successfully performed

Define what needs to happen when the request fails, meaning whenever there’s a connection error or a response with error status code is returned.

Send an async request by providing only the verb, the endpoint, and the response listener to be notified once the request is completed, minimum set of required arguments

Map<String, String> params = Collections.singletonMap("pretty", "true");
restClient.performRequestAsync("GET", "/", params, responseListener); 

Send an async request by providing the verb, the endpoint, some querystring parameter and the response listener to be notified once the request is completed

String jsonString = "{" +
        "\"user\":\"kimchy\"," +
        "\"postDate\":\"2013-01-30\"," +
        "\"message\":\"trying out Elasticsearch\"" +
        "}";
HttpEntity entity = new NStringEntity(jsonString, ContentType.APPLICATION_JSON);
restClient.performRequestAsync("PUT", "/posts/doc/1", params, entity, responseListener); 

Send an async request by providing the verb, the endpoint, optional querystring parameters, the request body enclosed in an org.apache.http.HttpEntity object and the response listener to be notified once the request is completed

HttpAsyncResponseConsumerFactory.HeapBufferedResponseConsumerFactory consumerFactory =
        new HttpAsyncResponseConsumerFactory.HeapBufferedResponseConsumerFactory(30 * 1024 * 1024);
restClient.performRequestAsync("GET", "/posts/_search", params, null, consumerFactory, responseListener); 

Send an async request by providing the verb, the endpoint, optional querystring parameters, optional request body and the optional factory that is used to create an org.apache.http.nio.protocol.HttpAsyncResponseConsumer callback instance per request attempt. Controls how the response body gets streamed from a non-blocking HTTP connection on the client side. When not provided, the default implementation is used which buffers the whole response body in heap memory, up to 100 MB.

The following is a basic example of how async requests can be sent:

final CountDownLatch latch = new CountDownLatch(documents.length);
for (int i = 0; i < documents.length; i++) {
    restClient.performRequestAsync(
            "PUT",
            "/posts/doc/" + i,
            Collections.<String, String>emptyMap(),
            //let's assume that the documents are stored in an HttpEntity array
            documents[i],
            new ResponseListener() {
                @Override
                public void onSuccess(Response response) {
                    
                    latch.countDown();
                }

                @Override
                public void onFailure(Exception exception) {
                    
                    latch.countDown();
                }
            }
    );
}
latch.await();

Process the returned response

Handle the returned exception, due to communication error or a response with status code that indicates an error

Each of the above listed method supports sending headers along with the request through a Header varargs argument as in the following examples:

Response response = restClient.performRequest("GET", "/", new BasicHeader("header", "value"));
Header[] headers = {
        new BasicHeader("header1", "value1"),
        new BasicHeader("header2", "value2")
};
restClient.performRequestAsync("GET", "/", responseListener, headers);