Groovy 2 Cookbook

The requirement for installing Groovy 2.0 is JDK 1.5 and higher. We assume that you have JDK installed and know how to use Java. In case you use JDK 7 or later, then you can take advantage of the dynamic language optimization present in that version. For instance, the invokedynamic bytecode instruction (see the Running Groovy with invokedynamic support recipe).

To install Groovy on Windows, you need to download the ZIP distribution from http://groovy.codehaus.org/Download.

The latest major version at the time of writing is 2.1.6. The latest minor version is 2.0.8. Since v2.0, Groovy has changed the release version numbering, so the next major version of Groovy will be 3.0 and the next minor versions will have the second digit increased (2.1, 2.2, 2.3, and so on).

Alternatively, you can build Groovy from the source distribution which is described in the Building Groovy from source recipe.

After downloading the zipped distribution, you need to unzip the archive to a directory of your choice and carry out the following steps to install Groovy on Windows:

If you get the output displayed as in the previous screenshot, your Groovy installation is complete.

As an alternative to the zipped archive, Windows users can also download a one-click installer (you can find the link on the same download page under the Download Windows-Installer link). Execute the installer and follow the instructions to get a fully functional Groovy installation.

As a starter, download the Groovy 2.0 binaries as described in the Installing Groovy on Windows recipe and perform the following steps to install Groovy on Linux and OS X:

The output should display the installed Groovy version and the JDK in use.

Using the symbolic link called current, which we created in step 2, makes it very easy to upgrade to a newer version of Groovy by changing the folder to which the symbolic link points to.

Most *nix-based operating systems (such as Linux or Mac OS X) have package manager systems that allow you to install Groovy by simply typing a command in the terminal.

In Ubuntu, Groovy can be installed by simply typing:

sudo apt-get install groovy

The version installed by the Ubuntu package manager is quite old (1.7.10), so you may want to install Groovy manually as described in this recipe.

In OS X, you can use Homebrew as follows:

brew install groovy

If you are happy with running a stable version of Groovy, but possibly not the most recent one, a package manager is the recommended way to get Groovy quickly and easily. If you want to install a beta version of Groovy or a version that is not yet available on the package manager system used by your OS, install the binaries from the website.

Let's start with the most abused example in programming books, printing Hello, World!:

In step 1, the actual Groovy code resides in the double quotes (") and uses the predefined println method to print a Hello, World! string. But to explain where the println method actually comes from, we need to give a bit more details on Groovy internals.

Every script in Groovy (a command-line parameter or a standalone script file) is compiled on the fly into a class that extends the groovy.lang.Script class (Javadoc for this class can be found at http://groovy.codehaus.org/api/groovy/lang/Script.html).

Naturally, a Script class is eventually inherited from java.lang.Object, which is the base class for all classes in both Java and Groovy. But since Groovy adds its own extension methods to many standard JDK classes (see the Adding a functionality to the existing Java/Groovy classes recipe in Chapter 3, Using Groovy Language Features for Information on Custom Extension Modules), java.lang.Object is enriched with many useful methods including println (the relevant Java documentation can be found at http://groovy.codehaus.org/groovy-jdk/java/lang/Object.html#println(java.lang.Object)).

In fact, the groovy command has several other useful command-line options. If you type groovy --help, you can get a full list of them as shown in the following screenshot:

Let's go through some of those options to get a better overview of the possibilities.

First of all, -classpath, --classpath, and -cp options work in a very similar way to the java command. You just specify a list of the *.jar files or list of directories with the *.class files. The only peculiarity is that -classpath must come as the first parameter in the command line; otherwise Groovy will not recognize it.

Another parameter that is common with the java command is -D, which allows to pass the system properties to your script in the following way:

groovy -Dmessage=world-e "println 'Hello, ' + System.getProperty('message')"

One of the strengths of Groovy (as opposed to Java) is its conciseness. This rule is also applied to what Groovy prints out if an exception occurs in your script:

groovy -e "throw new Exception()"
Caught: java.lang.Exception
java.lang.Exception at script_from_command_line.run(script_from_command_line:1)

To print the conventional full Java stack trace, you can use the -d or -debug options (some stack trace lines are omitted for brevity):

groovy -d -e "throw new Exception()"
Caught: java.lang.Exception
java.lang.Exception
    at sun.reflect.Native...
    ...
    at script_from_command_line.run(script_from_command_line:1)
    ...
    at org.codehaus.groovy.tools.GroovyStarter.main(...)

For additional command-line features, please refer to the following recipes:

For more information on the Groovy script structure and Groovy additions, go to:

Assume that you have a file, data.txt, which contains five lines with numbers from 1 to 5:

Due to the fact that we are using the -n option, the code in double quotes is applied to each line read from the datafile specified as the last parameter in the command line. The line variable is predefined by Groovy, and you can use it to access, filter, or modify the line's content.

If you add the -i option to the previous command, then it will actually modify the input file, with output values as follows:

groovy -i -n -p -e "line.toLong() * 2" data.txt

Adding a suffix .bak to the -i option will save the original input file data.txt under data.txt.bak:

groovy -i .bak -n -p -e "line.toLong() * 2" data.txt

You can use the -n and -p options to filter the input stream of other operating system commands. For example, if you want to filter the output of a directory listing command (dir) to show only the *.jar files, on Windows you can use the following command:

dir | groovy -n -e "if (line.contains('.jar')) println line"

Or on *nix-based operating systems, you can use the following command:

ls -la | groovy -n -e "if (line.contains('.jar')) println line"

Of course, the result of the previous commands can be easily achieved by more efficient operating system instructions. However, these examples are given to demonstrate that you can actually leverage the full power of the Groovy and Java programming languages to implement more complex processing rules.

The command-line option that we are going to use for this purpose is -l:

In this way, you can quite easily organize communication channels for ad hoc notifications on different hosts.

The invokedynamic support is a compile-time and runtime feature only. In other words, a developer cannot use it from within the source code. What invokedynamic brings to Groovy 2.0 (and even more to 2.1) is basically improved runtime performance.

As explained in the introduction, Java 7 is the required version of the JVM to compile Groovy code that leverages the invokedynamic instruction:

It is important to note that if the --indy flag is omitted, the code will be compiled without the invokedynamic support, even if Java 7 is used and the Groovy JAR files have been replaced.

The performance gain introduced by the new JVM instruction greatly varies depending on a numbers of factors, including the actual JVM version and the type of code that is optimized. JVM support for the invokedynamic instruction improves at each version. The upcoming Java 8 will use invokedynamic to support lambda functions, so it is very likely that newer JVMs will offer even greater optimization. Given the current state of things, some benchmarks that we have run have shown an improvement of around 20 percent when given the same code compiled with the invokedynamic instruction enabled.

Like many of today's open source projects, Groovy source is maintained on GitHub. GitHub is a website that provides a Git hosting service. You have probably heard of Git, the version control system started by the Linux creator, Linus Torvalds.

In order to build Groovy, you need a local copy of the source code that must be fetched from GitHub via Git. If you are running a Linux or OS X operating system, chances are that you already have Git installed on your box.

For Windows, there are several ways to install Git. You may want to use Cygwin (http://www.cygwin.com/) or the officially released version available on the Git website (http://git-scm.com/download/win).

For this recipe, we assume that a recent version of Git is available in your shell. To test that Git is indeed available, open a shell and type the following command:

git --version

Assuming that git is installed and operational, we can proceed with the following steps to build Groovy from source:

The git clone command in the first step fetches the Groovy repository, around 125 MB, so be patient if you are on a slow connection. Groovy has switched to the Gradle build tool from Ant. The gradlew command is a convenient wrapper for Gradle that takes care of downloading all the required dependencies and triggering the build. Chapter 2, Using Groovy Ecosystem, has a whole recipe dedicated to Gradle, so you may want to take a look at the Integrating Groovy into the build process using Gradle recipe to know more about this awesome tool. Furthermore, several recipes in this book will make use of Gradle to build the code examples.

The build process will download the required dependencies and compile the code. Upon successful compilation, the build will generate a ZIP file named groovy-binary-2.x.x-SNAPSHOT.zip that contains the binaries, under /target/distributions. Install the binaries in the same way as explained in the Installing Groovy on Windows and Installing Groovy on Linux and OS X recipes.

Note how two types of Groovy binaries are generated: a normal version and an indy version. The indy version will leverage the invokedynamic feature (see also the Running Groovy with invokedynamic support recipe).

Use the package manager available on your Linux distribution to install curl, unzip, and java on your machine. For example, on Ubuntu it can be achieved with the following command sequence:

sudo apt-get update
sudo apt-get install curl
sudo apt-get install zip
sudo apt-get install openjdk-6-jdk

The GVM installation script will not work without those packages. You can skip the OpenJDK package in case you have Java 5 or later distribution already installed.

Then you need to fetch the installation script from GVM's website (http://get.gvmtool.net) and pass it to bash using the following command:

curl -s get.gvmtool.net | bash

It will start the set up process as shown in the following screenshot:

To finalize the installation, open a new terminal and run the following command:

source ~/.gvm/bin/gvm-init.sh

As soon as GVM is installed and running, you can start putting it to use:

The reason the directorySize() method (steps 9 and 10) didn't work for v1.8.6 of Groovy is simply because this method was only introduced in v2.

As we already mentioned, GVM manages the values of environment variables to direct your Groovy commands to the proper distribution. It also downloads, unpacks, and caches Groovy installation archives under the ~/.gvm/var directory.

GVM also can manage other popular Groovy-based products; for example, Gradle (to build a framework that we are going to discuss in the Integrating Groovy into the build process using Gradle recipe in Chapter 2, Using Groovy Ecosystem), Grails (a web application framework), Griffon (a desktop application framework), and so on in a similar way.

This recipe can also be applied to a Mac running OS X. You can enjoy GVM on Windows too, but you need to install and run Cygwin (a Linux environment simulation for Windows).

Additional useful information can be found on the following product's home pages:

The groovysh command is a command-line tool available with the standard Groovy distribution. Install Groovy as described in one of the installation recipes (see the Installing Groovy on Windows recipe and Installing Groovy on Linux and OS X recipe) and you'll get the groovysh command available in your shell:

The groovysh command compiles and executes completed statements as soon as we press the Enter key. It then prints the result of that statement execution along with any output from the execution.

Autocompletion is supported through the JLine library that can be found at http://jline.sourceforge.net/. Pressing the Tab key automatically completes keywords and methods as we type:

groovy:000> string = "I'm a String!"
===> I'm a String!
groovy:000> string.
Display all 159 possibilities? (y or n)
groovy:000> string.toU

toURI()         toURL()         toUpperCase(    toUpperCase()

In step 2, the evaluated statement returned null. This is normal as groovysh is informing us that the last statement didn't return any value—hence null.

In step 4, we can see how groovysh supports code that spawns multiple lines. Note how the counter on the left of each statement increases at each line. The up and down arrows key will display the history of the typed commands. The history is preserved even across sessions so you can safely exit groovysh and you will still be able to access the history.

You may have noticed that in the previous examples, we didn't use any typed variables.A variable declared with def or a data type is not stored in the session and will be lost as soon as the command is issued:

groovy:000> def name = "Oscar"
===> Oscar
groovy:000> println name
ERROR groovy.lang.MissingPropertyException:
No such property: name for class: groovysh_evaluate
      at groovysh_evaluate.run (groovysh_evaluate:2)

This is a small gotcha you should remember when using groovysh.

groovysh has a number of commands, which can be listed by typing help as shown in the following screenshot:

The import behaves like the standard import keyword in Groovy and Java. It allows to import packages from the JDK or the GDK:

groovy:000> import groovy.swing.SwingBuilder
===> [import groovy.swing.SwingBuilder]
groovy:000> swing = new SwingBuilder()
===> groovy.swing.SwingBuilder@6df59ac1
groovy:000> frame = swing.frame(title:'Frame') {
groovy:000>   textlabel = label(text:'hello world!')
groovy:000> }
===> javax.swing.JFrame[...]
groovy:000> frame.show()
===> null

The display command shows the current buffer and save allows to save it to a file:

groovy:000> display
Buffer is empty
groovy:000> class Person {
groovy:001> display

With clear, the buffer can be reset, in case you mistyped something.

The record command acts as a flying recorder. It saves the typed commands to a file as we type. Use record start and record stop to control the recording. It is preferable to specify a file to which you want the recorded commands to be stored:

groovy:000> record start Session1.txt
Recording session to: Session1.txt
===> Session1.txt
groovy:000> println 'hello world!'
hello world!
===> null
groovy:000> class Person {
groovy:001> String name
groovy:002> }
===> true
groovy:000> record stop
Recording stopped; session saved as: Session1.txt (202 bytes)
===> Session1.txt

A very useful feature of the Groovy shell is the inspect command that displays the content of the last evaluated expression inside a GUI application, named Groovy Object Browser.

The Groovy Object Browser shows a good deal of information about the latest stored object, such as the class name, the implemented interfaces, and all the methods exposed by the object. The following screenshot shows some of the methods visible in the java.lang.String class:

groovy:000> name = "Oscar"
===> Oscar
inspect

Open your shell and let's dive in:

The GroovyConsole tool comes with a handy Object Browser that graphically shows the fields and methods available for a given class.

Press Ctrl + I (CMD + I on a Mac) to launch the browser and display the last evaluated expression. The following simple class would appear like in the following screenshot:

class Person {
  String name
  String lastName
}

p = new Person()

By pressing Ctrl + J (CMD + J on a Mac), we can display another view of the Object Browser, this time focused on the variables visible from within the script.

The steps in the following section have been tested against Eclipse Indigo 3.7, but are very similar when using previous or later versions of Eclipse. For information on different Eclipse versions, you can always check http://groovy.codehaus.org/Eclipse+Plugin.

The plugin installation in Eclipse usually starts with opening the Install New Software... menu item under the Help menu. Perform the following steps to configure Groovy support in Eclipse:

The code shown in the previous section is actually Groovy code (even though it looks very much like Java) since we omitted semicolons and used the println method. The reasons for that method to be available were described in the Executing Groovy code from the command line recipe.

With the Eclipse plugin for Groovy, you also get the possibility to execute Groovy code right from your IDE. For that, you need to use the Run as... menu item from the Context Menu, as shown in the following screenshot:

By running the example code with either the Groovy Script executor or Java Application executor, you should get the following output in Eclipse's Console view:

Groovy can be used to write standard classes. But as we have seen in the previous recipes, Groovy is also a scripting language, and the Eclipse IDE plugin supports this feature as well.

To define a Groovy script in your project, simply create a plain empty text file with the *.groovy extension anywhere in your project. The new file is a Groovy script, so you can start by typing the line of code, as shown in the following screenshot:

When you run your script (HelloWorld2.groovy) with the Groovy Script executor, you will get the same output as the previously mentioned Groovy source file (HelloWorld.groovy).

Conversely, if you run your Groovy script (HelloWorld2.groovy) using the Java Application executor, it will complain about a missing class, as shown in the following screenshot:

The reason for the exception lies in how Groovy distinguishes between script files and classes. If you look at the way Groovy script and Groovy classes are compiled in the Eclipse Navigator view, you can also see that even though the script source file resides in the package folder org.test under the src directory, that information is erased when the actual script is compiled into a class file:

You can also spot the difference between scripts and classes by looking at the list of the class generated methods by activating Package Explorer view, as shown in the following screenshot:

As you can see, the Groovy script class has additional constructors as well as the main and run methods. The Groovy class has only the methods that were defined by the class definition.

This distinction makes Groovy a very powerful addition to a Java tool set. Groovy allows you to use an alternative and more concise syntax to extend your existing Java applications, as well as writing short and concise scripts that leverage the richness of the Java platform.

To get started with this recipe, you need v12 of IntelliJ IDEA. The IDE comes in two versions, Community Edition and Ultimate. JetBrains, the company behind IDEA, offers the Community Edition for free, while it charges for the Ultimate version. The good news is that Groovy support is available in the free version of the IDE so you can start using it straight away. Download IntelliJ IDEA from http://www.jetbrains.com.

You also need to install Java and a Groovy distribution. Refer to the installation recipes from earlier in this chapter.

Let's start with the project creation:

Several refactoring goodies are also available, including Extract Parameter that also works for closures (see the Defining code as data in Groovy recipe in Chapter 3, Using Groovy Language Features), as shown in the following screenshot:

The result of the refactoring will be as shown in the following screenshot: