Introduction to Java Clients for Elasticsearch

Submitted by heartin on Sat, 05/26/2018 - 10:45

Java programmers had two choices when communicating with Elasticsearch: they could use either the REST API over HTTP, or the internal Java API (aka transport client), which is used by Elasticsearch itself for node-to-node communication. When using the HTTP rest client, Elasticsearch parses the JSON to Java objects and then use the internal Java API, and when we use the internal Java API we use those internal Java objects directly.

Though using internal Java API directly may have some performance advantage, it has many disadvantages:

Backward compatibility issues
1. While breaking changes to the HTTP rest client is made only with major releases, breaking changes to the internal Java API may be made more frequently.
2. While upgrading cluster, upgrading all nodes and Java API clients (internal) to have the same version simultaneously is harder. The REST interface is much more stable and can be upgraded out of step with the Elasticsearch cluster.
JVM compatibility issues.
Using the internal Java API make you depend on the whole Elasticsearch.
Securing HTTP end points are more easier than Java APIs designed for internal node-to-node-communication.

A few good open source clients such as the Jest client tried to solve this problem, and is widely used. Elasticsearch also came up with an official low level Java client API first and then finally an official high level client api.

Low-level Java REST client

The first official Java REST Client was released with version 5.0.0. The first release only included what we call a low-level client, which has the following features:

compatibility with any Elasticsearch version
load balancing across all available nodes
failover in case of node failures and upon specific response codes
failed connection penalization
persistent connections
trace logging of requests and responses
optional automatic discovery of cluster nodes (also known as sniffing)

Maven Dependency

<dependency>
<groupId>org.elasticsearch.client</groupId>
<artifactId>elasticsearch-rest-client</artifactId>
<version>6.2.4</version>
</dependency>

High-level Java REST client

With the low-level client, Java users still had to build requests or to parse responses. It handles path and query-string construction for requests, but it treats JSON request and response bodies as opaque byte arrays which have to be handled by the user.

Therefore, Elasticsearch came up with a high-level client that accepts proper request objects, takes care of their marshalling, and returns parsed response objects. The initial version of the high level Java REST client still depend on Elasticsearch, like the Java API. This will be changed in future.

Initial version of the high level client also had some limitations in feature set and Elasticsearch is adding more features with each release. It already support ndex, get, delete, update, bulk, search, scroll and clear scroll. Meanwhile, it is possible to use the low-level REST client to perform requests that are not yet supported by the high-level one.

The Java REST client is the future for Java users of Elasticsearch as per an Elasticsearch blog post. As soon as the REST client is feature complete and is mature enough to replace the Java API entirely, Elasticsearch will deprecate and finally remove the transport client and the Java API.

Maven Dependency

<dependency>
<groupId>org.elasticsearch.client</groupId>
<artifactId>elasticsearch-rest-high-level-client</artifactId>
<version>6.2.4</version>
</dependency>

Elasticsearch Jest Client

ElasticSearch Java REST client (Jest Apache HC Jar) is an open course rest client for Elasticsearch.

Its home page is github.com/searchbox-io/Jest. Read the readme for more details.

Maven Dependency

<dependency>
<groupId>io.searchbox</groupId>
<artifactId>jest</artifactId>
<version>5.3.3</version>
</dependency>

Note: Latest Maven dependency can be found at: https://mvnrepository.com/artifact/io.searchbox/jest