To embed Groovy scripts into your Java code base, first of all, you need to add groovy-all-2.x.x.jar library to your class path. Or if you are using Java 7 and want to take advantage of the invokedynamic optimization, you should add groovy-all-2.x.x-indy.jar instead (see also the Running Groovy with invokedynamic support recipe in Chapter 1, Getting Started with Groovy).

These libraries are located inside the Groovy distribution archive under the embeddable folder. Another way to get those JAR files is from Maven Central Repository at http://search.maven.org/.

The groovy-all artifact contains all the required classes to run Groovy code. It also includes dependencies such as Antlr, ASM, and Apache Commons inside the archive to be able to run Groovy with only single JAR on the class path. However, you shouldn't worry about class version conflicts if you use one of these libraries because all foreign classes are placed under special packages inside the groovy-all library.

There are several ways in which a Groovy script can be invoked from your Java application, but the recommended one—and also the simplest—is using the GroovyShell class.

In the Java class example, the GroovyShell object is instantiated using the default constructor.

In step 1, the Groovy code passed to the evaluate method calculates the result of the simple arithmetical expression. No return statement is used, but still the expression evaluates correctly. The reason is that in Groovy, the return statement is optional, and an expression will always return the value of the last statement. The mathematical expression's result type is java.lang.Double as we only operate with floating numbers; this is why we can safely cast it.

Furthermore, the expression refers to a constant defined in the java.lang.Math class, without explicitly importing it. This is possible due to the fact that Groovy imports all java.lang.* classes automatically, just like Java.

There is also a comment at the end of the expression, which is safely ignored. Similar to Java, comments can appear anywhere in Groovy code.

The GroovyShell object supports defining global variables, which can be re-used by evaluated scripts, by using the setVariable method, as displayed in step 2.

The variable name is set and then used inside a script evaluated later. The variable will be available to all the scripts executed throughout the lifetime of the GroovyShell object.

The variable's value can also be changed during script execution and retrieved later using the getVariable method.

In step 3, we can observe another useful feature of the integration of Groovy with Java; the possibility of executing external Groovy scripts from Java by passing a java.io.File object to the evaluate method.

You can also create individual Script objects for repeated executions:

Script script = shell.parse(new File("HelloWorld2.groovy"));
script.run(); // run first time
script.run(); // run second time

In this case, the script code will be compiled by the parse method and the script execution will be faster than if we do repeated calls of the evaluate method.

Steps 6 and 7 show how you can also execute individual methods if they are defined by the code located in an external script. Once the script is successfully compiled, the invokeMethod can be used to call any function declared in the external script.

If you are familiar with JSR-223, which provides the specification for the Java SE scripting API, you can also use it with Groovy. JSR-223 is recommended over the GroovyShell approach if you want to be able to switch to a different scripting language at any point. The next example shows how to get started with the scripting API:

import javax.script.ScriptEngine;
import javax.script.ScriptEngineManager;
import javax.script.ScriptException;

public class CallGroovyUsingJSR223 {

  public static void main(String[] args)
    throws ScriptException {

    ScriptEngineManager manager = new ScriptEngineManager();
    ScriptEngine engine = manager.getEngineByName("groovy");
    // Expression evalution.
    System.out
        .println(engine.eval("(4/3) * Math.PI * 6370 " +"// Earth volume in cubic killometeres "));

    // Variable binding.
    engine.put("name", "Andrew");
    engine.eval("println "My name is ${name}"");

  }

}

The key to start using Groovy with JSR-233 is again to add the groovy-all artifact to the classpath. Adding the jar will automatically bind the Groovy script engine into JVM, which can be retrieved by a call to manager.getEngineByName("groovy") as shown in the previous example. Please note that the JSR-233 specification is only available from Java 6.

Another way to dynamically embed Groovy into Java code is by defining the Groovy classes and parsing them with GroovyClassLoader. For example, let's assume we have the following TimePrinter.groovy file:

class TimePrinter implements Runnable {
  void run() {
    (1..10).each {
      println Calendar.instance.time
      Thread.sleep(1000)
    }
  }
}

As you can see, it defines the TimePrinter class, which implements the Runnable interface. The method run prints the current time and then sleeps for one second, and it repeats that operation 10 times. This code also shows one way of looping in Groovy: the (1..10) expression under the hood creates an object of type groovy.lang.IntRange. This class implements the java.lang.Iterable interface, which in Groovy has an extension method called each. This takes a code block (groovy.lang.Closure) as an input parameter and executes it for every element of java.lang.Iterable. For more information about Groovy Ranges, please refer to http://groovy.codehaus.org/api/groovy/lang/Range.html.

In order to use the TimePrinter class dynamically at runtime, we need to create an instance of GroovyClassLoader and call the parseClass method on it in order to get the new class definition:

// Create class loader.
GroovyClassLoader gcl = new GroovyClassLoader();

// Parse and load class.
@SuppressWarnings("unchecked")
Class<? extends Runnable> runnableClass =gcl.parseClass(new File("TimePrinter.groovy"));

Then, by using the Java Reflection API and specifically the newInstance method, we can create an instance of our dynamically loaded class and use it inside our normal Java code:

// Create and use class instance.
new Thread(runnableClass.newInstance()).start();

In this way, you can define classes on the fly to change or enhance your application functionality.

To get even more configuration options and more control over security setup, you can also make use of the GroovyScriptEngine class, which is not in the scope of this recipe.