elasticsearch/docs/java-api/client.asciidoc

[[client]]
== Client

You can use the *Java client* in multiple ways:

* Perform standard <<java-docs-index,index>>, <<java-docs-get,get>>,
  <<java-docs-delete,delete>> and <<java-search,search>> operations on an
  existing cluster
* Perform administrative tasks on a running cluster

Obtaining an elasticsearch `Client` is simple. The most common way to
get a client is by creating a <<transport-client,`TransportClient`>>
that connects to a cluster.

[IMPORTANT]
==============================

The client must have the same major version (e.g. `2.x`, or `5.x`) as the
nodes in the cluster. Clients may connect to clusters which have a different
minor version (e.g. `2.3.x`) but it is possible that new funcionality may not
be supported.  Ideally, the client should have the same version as the
cluster.

==============================


[[transport-client]]
=== Transport Client

The `TransportClient` connects remotely to an Elasticsearch cluster
using the transport module. It does not join the cluster, but simply
gets one or more initial transport addresses and communicates with them
in round robin fashion on each action (though most actions will probably
be "two hop" operations).

[source,java]
--------------------------------------------------
// on startup

Client client = TransportClient.builder().build()
        .addTransportAddress(new InetSocketTransportAddress(InetAddress.getByName("host1"), 9300))
        .addTransportAddress(new InetSocketTransportAddress(InetAddress.getByName("host2"), 9300));

// on shutdown

client.close();
--------------------------------------------------

Note that you have to set the cluster name if you use one different than
"elasticsearch":

[source,java]
--------------------------------------------------
Settings settings = Settings.settingsBuilder()
        .put("cluster.name", "myClusterName").build();
Client client = TransportClient.builder().settings(settings).build();
//Add transport addresses and do something with the client...
--------------------------------------------------

The client allows sniffing the rest of the cluster, which adds data nodes
into its list of machines to use. In this case, note that the IP addresses
used will be the ones that the other nodes were started with (the
"publish" address). In order to enable it, set the
`client.transport.sniff` to `true`:

[source,java]
--------------------------------------------------
Settings settings = Settings.settingsBuilder()
        .put("client.transport.sniff", true).build();
TransportClient client = TransportClient.builder().settings(settings).build();
--------------------------------------------------

Other transport client level settings include:

[cols="<,<",options="header",]
|=======================================================================
|Parameter |Description
|`client.transport.ignore_cluster_name` |Set to `true` to ignore cluster
name validation of connected nodes. (since 0.19.4)

|`client.transport.ping_timeout` |The time to wait for a ping response
from a node. Defaults to `5s`.

|`client.transport.nodes_sampler_interval` |How often to sample / ping
the nodes listed and connected. Defaults to `5s`.
|=======================================================================


[[client-connected-to-client-node]]
=== Connecting a Client to a Client Node

You can start locally a {ref}/modules-node.html#client-node[Client Node] and then simply create
a <<transport-client,`TransportClient`>> in your application which connects to this Client Node.

This way, the client node will be able to load whatever plugin you need (think about discovery plugins for example).