Change docs on "node client" to not use an in-memory node
Currently we suggesting users create a Node (using NodeBuilder in 2.x) to have a client that is capable of keeping up-to-date information. This is generally a bad idea as it means elasticsearch has no control over eg max heap size or gc settings, and is also problematic for users because they must deal with dependency collisions (and in 2.x+ dependencies of elasticsearch itself). A better alternative, and what we should document, is to run a local elasticsearch server using bin/elasticsearch, and then use the transport client to connect to that local node. This local connection is virtually free, and allows the client code to be completely isolated from the elasticsearch process. Plugins are then also easy to deal with: just install them in elasticsearch as usual. Closes #15383
This commit is contained in:
David Pilato
parent
1e1645d22b
commit
b83b9d69c9
|
|
@ -7,21 +7,12 @@ You can use the *Java client* in multiple ways:
|
|||
<<java-docs-delete,delete>> and <<java-search,search>> operations on an
|
||||
existing cluster
|
||||
* Perform administrative tasks on a running cluster
|
||||
* Start full nodes when you want to run Elasticsearch embedded in your
|
||||
own application or when you want to launch unit or integration tests
|
||||
|
||||
Obtaining an elasticsearch `Client` is simple. The most common way to
|
||||
get a client is by:
|
||||
|
||||
1. Creating an embedded <<node-client,`Node`>> that acts as a node
|
||||
within a cluster.
|
||||
2. Requesting a `Client` from your embedded `Node`.
|
||||
|
||||
Another manner is by creating a <<transport-client,`TransportClient`>>
|
||||
get a client is by creating a <<transport-client,`TransportClient`>>
|
||||
that connects to a cluster.
|
||||
|
||||
*Important:*
|
||||
|
||||
______________________________________________________________________________________________________________________________________________________________
|
||||
Please note that you are encouraged to use the same version on client
|
||||
and cluster sides. You may hit some incompatibility issues when mixing
|
||||
|
|
@ -29,111 +20,6 @@ major versions.
|
|||
______________________________________________________________________________________________________________________________________________________________
|
||||
|
||||
|
||||
[[node-client]]
|
||||
=== Node Client
|
||||
|
||||
Instantiating a node based client is the simplest way to get a `Client`
|
||||
that can execute operations against elasticsearch.
|
||||
|
||||
[source,java]
|
||||
--------------------------------------------------
|
||||
|
||||
// on startup
|
||||
|
||||
Node node = new Node(Settings.EMPTY).start();
|
||||
Client client = node.client();
|
||||
|
||||
// on shutdown
|
||||
|
||||
node.close();
|
||||
--------------------------------------------------
|
||||
|
||||
When you start a `Node`, it joins an elasticsearch cluster. You can have
|
||||
different clusters by simply setting the `cluster.name` setting, or
|
||||
explicitly using the `clusterName` method on the builder.
|
||||
|
||||
You can define `cluster.name` in the `/src/main/resources/elasticsearch.yml`
|
||||
file in your project. As long as `elasticsearch.yml` is present in the
|
||||
classpath, it will be used when you start your node.
|
||||
|
||||
[source,yaml]
|
||||
--------------------------------------------------
|
||||
cluster.name: yourclustername
|
||||
--------------------------------------------------
|
||||
|
||||
Or in Java:
|
||||
|
||||
[source,java]
|
||||
--------------------------------------------------
|
||||
Node node = nodeBuilder().clusterName("yourclustername").node();
|
||||
Client client = node.client();
|
||||
--------------------------------------------------
|
||||
|
||||
The benefit of using the `Client` is the fact that operations are
|
||||
automatically routed to the node(s) the operations need to be executed
|
||||
on, without performing a "double hop". For example, the index operation
|
||||
will automatically be executed on the shard that it will end up existing
|
||||
at.
|
||||
|
||||
When you start a `Node`, the most important decision is whether it
|
||||
should hold data or not. In other words, should indices and shards be
|
||||
allocated to it. Many times we would like to have the clients just be
|
||||
clients, without shards being allocated to them. This is simple to
|
||||
configure by setting either `node.data` setting to `false` or
|
||||
`node.client` to `true` (the `NodeBuilder` respective helper methods on
|
||||
it):
|
||||
|
||||
[source,java]
|
||||
--------------------------------------------------
|
||||
|
||||
// on startup
|
||||
|
||||
// Embedded node clients behave just like standalone nodes,
|
||||
// which means that they will leave the HTTP port open!
|
||||
Node node = new Node(Settings.settingsBuilder()
|
||||
.put("http.enabled", false)
|
||||
.put("node.client", true).build())
|
||||
.start();
|
||||
|
||||
Client client = node.client();
|
||||
|
||||
// on shutdown
|
||||
|
||||
node.close();
|
||||
--------------------------------------------------
|
||||
|
||||
Another common usage is to start the `Node` and use the `Client` in
|
||||
unit/integration tests. In such a case, we would like to start a "local"
|
||||
`Node` (with a "local" discovery and transport). Again, this is just a
|
||||
matter of a simple setting when starting the `Node`. Note, "local" here
|
||||
means local on the JVM (well, actually class loader) level, meaning that
|
||||
two *local* servers started within the same JVM will discover themselves
|
||||
and form a cluster.
|
||||
|
||||
[source,java]
|
||||
--------------------------------------------------
|
||||
|
||||
// on startup
|
||||
|
||||
Node node = new Node(Settings.builder().put("node.local", true).build()).start();
|
||||
Client client = node.client();
|
||||
|
||||
// on shutdown
|
||||
|
||||
node.close();
|
||||
--------------------------------------------------
|
||||
|
||||
[[node-client-downsides]]
|
||||
==== Node Client Downsides
|
||||
|
||||
Embedding a node client into your application is the easiest way to connect
|
||||
to an Elasticsearch cluster, but it carries some downsides.
|
||||
|
||||
- Frequently starting and stopping one or more node clients creates unnecessary
|
||||
noise across the cluster.
|
||||
- Embedded node client will respond to outside requests, just like any other client.
|
||||
** You almost always want to disable HTTP for an _embedded_ node client.
|
||||
|
||||
[[transport-client]]
|
||||
=== Transport Client
|
||||
|
||||
|
|
@ -194,3 +80,12 @@ 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).
|
||||
|
|
|
|||
Loading…
Reference in New Issue