You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
116 lines
5.4 KiB
Plaintext
116 lines
5.4 KiB
Plaintext
# Elasticsearch Clients
|
|
|
|
image:https://api.travis-ci.org/xbib/content.svg[title="Build status", link="https://travis-ci.org/jprante/elasticsearch-extras-client/"]
|
|
image:https://img.shields.io/sonar/http/nemo.sonarqube.com/org.xbib%3Aelasticsearch-extras-client/coverage.svg?style=flat-square[title="Coverage", link="https://sonarqube.com/dashboard/index?id=org.xbib%3Aelasticsearch-extras-client"]
|
|
image:https://maven-badges.herokuapp.com/maven-central/org.xbib/elasticsearch-extras-client/badge.svg[title="Maven Central", link="http://search.maven.org/#search%7Cga%7C1%7Cxbib%20elasticsearch-extras-client"]
|
|
image:https://img.shields.io/badge/License-Apache%202.0-blue.svg[title="Apache License 2.0", link="https://opensource.org/licenses/Apache-2.0"]
|
|
|
|
This Java library extends the Elasticsearch Java Client classes for better convenience.
|
|
|
|
It is not a plugin for Elasticsearch. Use it by importing the jar from Maven Central into your project.
|
|
|
|
The Elasticsearch node client and transport client APIs are unified in a `ClientMethods` interface. This interface uses
|
|
bulk services and index management under the hood, like index creation, alias managent, and retention policies.
|
|
|
|
Two classes `BulkNodeClient` and `BulkTransportClient` combine the client methods with the `BulkProcessor`,
|
|
provide some logging convenience, and still offer the `Client` interface of Elasticsearch by using the `client()` method.
|
|
|
|
A `MockTransportClient` implements the `BulkTransportClient` API but does not need a running Elasticsearch node
|
|
to connect to. This is useful for unit testing.
|
|
|
|
The client classes are enriched by metrics that can measure document count, size, and speed.
|
|
|
|
A `ClientBuilder` helps to build client instances. For example
|
|
|
|
[source,java]
|
|
----
|
|
ClientBuilder clientBuilder = ClientBuilder.builder()
|
|
.put(elasticsearchSettings)
|
|
.put("client.transport.ping_timeout", settings.get("timeout", "30s"))
|
|
.put(ClientBuilder.MAX_ACTIONS_PER_REQUEST, settings.getAsInt("maxbulkactions", 1000))
|
|
.put(ClientBuilder.MAX_CONCURRENT_REQUESTS, settings.getAsInt("maxconcurrentbulkrequests",
|
|
Runtime.getRuntime().availableProcessors()))
|
|
.setMetric(new SimpleBulkMetric())
|
|
.setControl(new SimpleBulkControl());
|
|
BulkTransportClient client = clientBuilder.toBulkTransportClient();
|
|
----
|
|
|
|
For more examples, consult the integration etsts at `src/integration-test/java`.
|
|
|
|
A re-implemented `BulkProcessor` allows flushing of documents before closing.
|
|
|
|
Also, a light-weight re-implementation of the `TransportClient` class is provided with the following differences to the original `TransportClient`:
|
|
|
|
- no retry mechanism, no exponential back off, if an error or exception is encountered, the client fails fast
|
|
|
|
- no _sniffing_, that means, no additional nodes are detected during runtime
|
|
|
|
- methods of `TransportClient`, `TransportClientNodesServce`, `TransportClientProxy` classes are merged into one class
|
|
|
|
- configurable ping timeout
|
|
|
|
#### Some interesting methods
|
|
|
|
Here are some methods from the `ClientMethods` API, these are not all methods, but maybe
|
|
some of which can demonstrate the convenience.
|
|
|
|
Create new index, use settings and mappings from input streams.
|
|
----
|
|
ClientMethods newIndex(String index, String type, InputStream settings, InputStream mappings) throws IOException
|
|
----
|
|
|
|
Switch an index to bulk mode - disable replicas, set refresh interval.
|
|
----
|
|
ClientMethods startBulk(String index, long startRefreshIntervalSeconds, long stopRefreshIntervalSeconds) throws IOException
|
|
----
|
|
|
|
Index document, use bulk mode automatically.
|
|
----
|
|
ClientMethods index(String index, String type, String id, String source);
|
|
----
|
|
|
|
Wait for outstanding bulk responsed from the cluster.
|
|
----
|
|
ClientMethods waitForResponses(TimeValue maxWait) throws InterruptedException, ExecutionException;
|
|
----
|
|
|
|
Update replica level on an index.
|
|
----
|
|
int updateReplicaLevel(String index, int level) throws IOException;
|
|
----
|
|
|
|
Switch aliases from a previously created index with a timestamp to a current index under the common base name `index`.
|
|
|
|
----
|
|
void switchAliases(String index, String concreteIndex, List<String> extraAliases, IndexAliasAdder adder);
|
|
----
|
|
|
|
Retention policy for an index. All indices before `timestampdiff` should be deleted,
|
|
but `mintokeep` indices must be kept.
|
|
|
|
----
|
|
void performRetentionPolicy(String index, String concreteIndex, int timestampdiff, int mintokeep);
|
|
----
|
|
|
|
## Prerequisites
|
|
|
|
You will need Java 8, although Elasticsearch 2.x requires Java 7. Java 7 is not supported.
|
|
|
|
## Dependencies
|
|
|
|
This project depends only on https://github.com/xbib/metrics which is a slim version of Coda Hale's metrics library,
|
|
Elasticsearch, and Log4j2 API.
|
|
|
|
## How to decode the Elasticsearch version
|
|
|
|
This project uses semantic versioning to determine the Elasticsearch upstream version it is built against.
|
|
|
|
The first three version numbers are the corresponding Elasticsearch version. The last version number is
|
|
an incrementing number, the version of this project.
|
|
|
|
Please use exactly the Elasticsearch version which is declared in the project's version.
|
|
Other Elasticsearch versions do not work and will never work, it is not worth to try it.
|
|
This is by design of the Elasticsearch project because the internal node communication protocol depends on the
|
|
exact same API implementation. Also, the exact same version of Java virtual machine is remoonded on server
|
|
and client side.
|