Groovy Client for Elasticsearch

The Elasticsearch Groovy client project helps you to use Elasticsearch in Groovy projects. This Groovy client is different from previous releases in that it inherently supports 100% of the Elasticsearch API for the supported version by using the Groovy extension feature 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.

In much earlier versions of the client, you would run code like this:

GClient client = new GNodeBuilder().settings { ... }.node().client
GActionFuture future = client.index { ... }.gexecute()

This would provide a GClient from a GNodeBuilder, which was meant to provide the same features as the Java client's Client and NodeBuilder. However, because they had to be written to support every new feature of the Java client, it was missing some method variants.

In this release, all of the G-prefixed classes have been replaced by extensions, which means that you can now use the Java client code from any Java client example that you find online with the benefit of the Groovy extensions.

Client client = nodeBuilder().settings { ... }.node().client
ListenableActionFuture<IndexResponse> future = client.index { ... }

Besides the usage of Closures, the above example should look very familiar to existing Java client users.

Versions

You need to install a version matching your Elasticsearch version:

Elasticsearch	Groovy Client	Java	Groovy
master	Build from source	See below	2.4.3
1.x	Build from source	7u60 or later	2.4.3
1.6	1.6	7u60 or later	2.4.3
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

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	Supported
Java 8	Supported	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:1.6.0'
}

Maven

<dependencies>
  <dependency>
    <groupId>org.elasticsearch</groupId>
    <artifactId>elasticsearch-groovy</artifactId>
    <version>1.6.0</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: '1.6.0', 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., $callSiteArrays) 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 (invokedynamic) jar.

Gradle

repositories {
  mavenCentral()
}

dependencies {
  compile 'org.codehaus.groovy:groovy-all:2.4.3:indy'
}

Maven

<dependencies>
  <dependency>
    <groupId>org.codehaus.groovy</groupId>
    <artifactId>groovy-all</artifactId>
    <version>2.4.3</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-2014 Elasticsearch <http://www.elasticsearch.org>

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.

noamt/elasticsearch-groovy

Groovy Client for Elasticsearch

Versions

JVM Warning

Adding to your Groovy projects

Gradle

Maven

Grails 2.x

Compiling Groovy Client

Testing Groovy Client

Testing with IntelliJ

Suggested Groovy Settings

Compiling Groovy with invokedynamic support

Gradle

Maven

Using invokedynamic in your Groovy code

Gradle

Maven

IntelliJ

License

Compiling Groovy with `invokedynamic` support

Using `invokedynamic` in your Groovy code