Awesome
Groovy Client for Elasticsearch
IMPORTANT: The Groovy Client is deprecated as of Elasticsearch v6.0.0 and is no longer actively maintained.
The Elasticsearch Groovy client project helps you to use Elasticsearch in Groovy projects. This Groovy client inherently supports 100% of the Elasticsearch API for the supported version by using Groovy extension modules with the Java client. Literally anything possible in the same version of the Java client is possible with the Groovy client, plus some Groovy-friendly extensions.
You can use the Java client code from any Java client example that you find online with the benefit of the Groovy extensions.
TransportClient client = TransportClient.builder().settings(Settings.settingsBuilder {
client.transport.sniff = true
cluster.name = "your-cluster-name"
}).build()
// identical to the Java client:
client.addTransportAddress( ... )
String userId = "some-user-id"
// asynchronously fetch the results
ListenableActionFuture<SearchResponse> future = client.searchAsync {
indices "your-index"
types "your-type"
source {
query {
match {
user.id = userId
}
}
}
}
// block until the response is retrieved (you could alternatively use listeners)
SearchResponse response = future.actionGet()
Besides the usage of Closure
s, the above example should look very familiar to any existing Java client users, as well
as those familiar with the Elasticsearch DSL (Domain Specific Language used for indexing and querying).
Versions
You need to install a version matching your Elasticsearch version:
Elasticsearch | Groovy Client | Java | Groovy |
---|---|---|---|
master [5.0] | Build from source [5.0] | 8 or later | 2.4.5 |
2.1 - 2.4 | 2.1 | 7u60 or later | 2.4.4 |
2.0 | 2.0 | 7u60 or later | 2.4.4 |
1.7 | 1.7 | 7u60 or later | 2.4.4 |
1.6 | 1.6 | 7u60 or later | 2.4.4 |
1.5 | 1.5 | 7u60 or later | 2.4.1* |
1.4 | 1.4 | 7u60 or later | 2.3.7* |
Please read documentation relative to the version that you are using!
To build a SNAPSHOT version, you need to build it with Gradle (see below for further details):
$ gradle clean installDist
Groovy Warning
Groovy released Groovy 2.4.4 to fix a vulnerability with CVE-2015-3253.
You are considered vulnerable just by having an earlier version of Groovy on your classpath! All users should upgrade to Groovy 2.4.4, or later, as a result.
JVM Warning
Both Elasticsearch and the Elasticsearch Groovy client require at least Java 7. In addition, the Groovy client is
compiled with indy
support enabled, which means that it theoretically could cause issues if you are running with Java
7u22 to 7u55 due to a bug in the JVM related to invokedynamic
. This is reported directly from the Groovy
developers and it is strongly suggested that you run Java 7u60 or
later.
JVM Release | Groovy Client Support | invokedynamic Support |
---|---|---|
Java 5 | Unsupported | None |
Java 6 | Unsupported | None |
Java 7u22 to 7u55 | Unsupported | Buggy |
Java 7u60 or later | Supported [1.x, 2.x] | Supported |
Java 8 | Supported [1.x or later] | Supported |
Groovy is supported on any JDK supported by Elasticsearch, which currently includes Oracle JDK and OpenJDK.
Adding to your Groovy projects
Gradle
repositories {
mavenCentral()
}
dependencies {
compile 'org.elasticsearch:elasticsearch-groovy:2.1.2'
}
Maven
<dependencies>
<dependency>
<groupId>org.elasticsearch</groupId>
<artifactId>elasticsearch-groovy</artifactId>
<version>2.1.2</version>
<scope>compile</scope>
</dependency>
</dependencies>
Grails 2.x
Out-of-the-box support for Grails is limited to Grails 2.4.4 or later. To use with earlier versions, you must follow the instructions found in GRAILS-10652 to load Groovy extension modules.
repositories {
mavenCentral()
}
dependencies {
// You may be able to use the 'runtime' scope
compile group: 'org.elasticsearch', name: 'elasticsearch-groovy', version: '2.1.2', classifier: 'grails'
}
Grails 3.x has overhauled their build system to use Gradle, which makes it easy for you to select the
version of Groovy to use with it, including the use of invokedynamic
. However, Grails 2.x did not
make it easy. A part of not being easy, Grails 2.x does not use the invokedynamic
-compatible Groovy
jar, which means that any Grails 2.x project requires a jar that is not compiled with invokedynamic
.
With the release of Elasticsearch Groovy 1.4.3, we have introduced a secondary jar with a new grails
classifier that can be used by Grails users. All other users are strongly recommended to use
the invokedynamic
-compatible versions described above (it's both faster and slightly smaller!).
Support for this is intended to assist the Grails community to use the Elasticsearch Groovy client
prior to the release of Grails 3.0. If you are using Grails 3.0 or later, then you should use the
invokedynamic
version of Groovy and the Gradle dependency above.
Compiling Groovy Client
To compile this code on your own, then run:
$ gradle clean installDist
This will skip all tests and place the compiled jar in
./build/install/elasticsearch-groovy/elasticsearch-groovy-{version}.jar
. It will package all dependencies (e.g.,
elasticsearch-{version}.jar
) into ./build/install/elasticsearch-groovy/lib
.
Testing Groovy Client
The Groovy client makes use of the Randomized Testing framework used by Elasticsearch itself. The unit tests and integration tests that this uses can be invoked with the same command:
$ gradle clean test
The various tests.*
and es.*
system properties that are used by Elasticsearch are also used by the Gradle build
script. As a result, any recommendation that suggests running mvn clean test -DsystemProp=xyz
can be replaced with
gradle clean test -DsystemProp=xyz
(the only change was from mvn
to gradle
). This only applies to the Groovy
client.
Testing with IntelliJ
By default, IntelliJ will place all of the compile
-time dependencies above the testCompile
dependencies. In the case
of the test frameworks used, this presents issues that occasionally trigger test failures (that tell you to fix your
classpath with respect to "test-framework.jar"). To fix this behavior, put your test dependencies above any non-test
dependencies within IntelliJ.
- Open
Project Structure
- Select
Modules
Suggested Groovy Settings
Since the release of Java 7 (aka Java 1.7), higher level languages like Groovy have had access to the invokedynamic
JVM instruction. This avoids the need for some runtime code
generation (e.g., $callSiteArray
s) and it theoretically speeds up all Groovy code. In the Groovy world, there is still
support for Java 5 and Java 6, which means that invokedynamic
cannot be enabled by default.
Compiling Groovy with invokedynamic
support
To support invokedynamic
in your own Groovy project(s), at a minimum, you must include the invokedynamic
-compiled
Groovy jar, which the Groovy developers call the indy
(in
vokedy
namic) jar.
Gradle
repositories {
mavenCentral()
}
dependencies {
compile 'org.codehaus.groovy:groovy-all:2.4.5:indy'
}
Maven
<dependencies>
<dependency>
<groupId>org.codehaus.groovy</groupId>
<artifactId>groovy-all</artifactId>
<version>2.4.5</version>
<classifier>indy</classifier>
<scope>compile</scope>
</dependency>
</dependencies>
Using invokedynamic
in your Groovy code
After including the indy
jar, you now only have an invokedynamic
-compatible Groovy runtime. All internal Groovy
calls will use invokedynamic
, as will any other Groovy code compiled with invokedynamic
support (e.g., the
Groovy client), but your code must also be compiled with invokedynamic
support to gain the benefits within your
compiled jar(s).
Gradle
apply plugin: 'groovy'
// ...
/**
* Customize Groovy compilation.
*/
tasks.withType(GroovyCompile) {
groovyOptions.optimizationOptions.indy = true
}
Maven
Maven has numerous ways to do this, and it largely depends on how you compile your Groovy code. If you are wrapping the
Ant task, then add indy="true"
to the Groovy compilation. Otherwise check your plugin's documentation.
IntelliJ
When allowing IntelliJ to control the compilation of your project, then you must enable Invoke dynamic support
within
the preferences for the Groovy Compiler
.
To change this setting:
- Open
Preferences
- Select
Compiler
- Select
Groovy Compiler
- Check
Invoke dynamic support
With IntelliJ 13, I have noticed that it is sometimes necessary to manually rebuild the project because it loses track of the resource files. This happens infrequently, but it will cause practically every test to fail when it does happen.
License
This software is licensed under the Apache 2 license, quoted below.
Copyright 2009-2015 Elastic <http://www.elastic.co>
Licensed under the Apache License, Version 2.0 (the "License"); you may not
use this file except in compliance with the License. You may obtain a copy of
the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations under
the License.