114 lines
4.7 KiB
Plaintext
114 lines
4.7 KiB
Plaintext
[[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 functionality may not
|
|
be supported. Ideally, the client should have the same version as the
|
|
cluster.
|
|
|
|
==============================
|
|
|
|
WARNING: The `TransportClient` is aimed to be replaced by the Java High Level REST
|
|
Client, which executes HTTP requests instead of serialized Java requests. The
|
|
`TransportClient` will be deprecated in upcoming versions of Elasticsearch and it
|
|
is advised to use the Java High Level REST Client instead.
|
|
|
|
[[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
|
|
|
|
TransportClient client = new PreBuiltTransportClient(Settings.EMPTY)
|
|
.addTransportAddress(new TransportAddress(InetAddress.getByName("host1"), 9300))
|
|
.addTransportAddress(new TransportAddress(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.builder()
|
|
.put("cluster.name", "myClusterName").build();
|
|
TransportClient client = new PreBuiltTransportClient(settings);
|
|
//Add transport addresses and do something with the client...
|
|
--------------------------------------------------
|
|
|
|
The Transport client comes with a cluster sniffing feature which
|
|
allows it to dynamically add new hosts and remove old ones.
|
|
When sniffing is enabled, the transport client will connect to the nodes in its
|
|
internal node list, which is built via calls to `addTransportAddress`.
|
|
After this, the client will call the internal cluster state API on those nodes
|
|
to discover available data nodes. The internal node list of the client will
|
|
be replaced with those data nodes only. This list is refreshed every five seconds by default.
|
|
Note that the IP addresses the sniffer connects to are the ones declared as the 'publish'
|
|
address in those node's Elasticsearch config.
|
|
|
|
Keep in mind that the list might possibly not include the original node it connected to
|
|
if that node is not a data node. If, for instance, you initially connect to a
|
|
master node, after sniffing, no further requests will go to that master node,
|
|
but rather to any data nodes instead. The reason the transport client excludes non-data
|
|
nodes is to avoid sending search traffic to master only nodes.
|
|
|
|
In order to enable sniffing, set `client.transport.sniff` to `true`:
|
|
|
|
[source,java]
|
|
--------------------------------------------------
|
|
Settings settings = Settings.builder()
|
|
.put("client.transport.sniff", true).build();
|
|
TransportClient client = new PreBuiltTransportClient(settings);
|
|
--------------------------------------------------
|
|
|
|
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 Coordinating Only Node
|
|
|
|
You can start locally a {ref}/modules-node.html#coordinating-only-node[Coordinating Only Node]
|
|
and then simply create a <<transport-client,`TransportClient`>> in your
|
|
application which connects to this Coordinating Only Node.
|
|
|
|
This way, the coordinating only node will be able to load whatever plugin you
|
|
need (think about discovery plugins for example).
|