CHAPTER 12

Integrating Grails

So far, you've explored a number of the core concepts that underpin Grails. From controllers to GORM and services, you should now have a pretty good understanding of what makes Grails tick. In this chapter, you'll learn how you can fit Grails into your existing ecosystem. We hope what you'll get from this chapter is a good understanding of how to go about including Grails into your build system, development tools, reporting setup, and server environment.

There is a lot of ground to cover, so let's get started by taking a closer look at configuration in Grails.

Grails and Configuration

Using Convention over Configuration (CoC), Grails significantly reduces the amount of configuration you need to do. Crucially, however, it is convention over configuration, not instead of it. There are still a number of different ways you can configure Grails.

Most configuration can be done using Grails' central configuration mechanism. The file grails-app/conf/Config.groovy contains any global configuration for the application. You've already seen this file being used at various points throughout the book. In the following sections, we'll be taking a closer look at how configuration is done with Config.groovy and what configuration options are available to you.

Configuration Basics

The Config.groovy file is a Groovy script that is similar to a regular Java properties file. You can set properties using the dot dereference operator:

grails.mime.file.extensions = true

Since it's a Groovy script, all the type information is retained. So, in the previous example, a boolean property called grails.mime.file.extensions is set to true. To access this setting, you can use the config property of the grailsApplication object available in controllers and views:

assert grailsApplication.config.grails.mime.file.extensions == true

As well as supporting settings specified on a single line, like the grails.mime.file. extensions setting, you can also group settings using blocks, as shown in Listing 12-1.

The example in Listing 12-1 will produce two entries in config: grails.mime.file. extensions and grails.mime.types. You can also configure settings on a per-environment basis, which we'll cover in the next section.

Environment-Specific Configuration

As you discovered in Chapter 2, the grails-app/conf/DataSource.groovy file can be configured in an environment-specific way. This is because Grails uses the same mechanism to configure the DataSource as Config.groovy uses for the rest of the application.

Like with DataSource.groovy, by using Config.groovy you can specify environment-specific settings using the environments block, as shown in Listing 12-2.

As Listing 12-2 demonstrates, you can use the environments block to specify a different grails.serverURL setting for production and development environments. The grails. serverURL setting is one of a number of built-in settings that you'll be discovering through the course of this book.

Configuring Logging

Grails uses the popular Log4j (http://logging.apache.org/log4j/) library to configure logging. Traditionally, Log4j has been configured with either a properties file format or XML. Grails, however, provides a specific DSL for configuring logging. Within the Config.groovy script, you can set a property called log4j using a Groovy closure.

Within this closure, you can use the Log4j DSL to configure logging. Listing 12-3 shows the default Log4j configuration in Grails that sets up logging for a bunch of packages internal to Grails.

As you can see from Listing 12-3, inside the body of the log4j closure there is an error method invoked that is passed a number of packages as arguments. The error method sets up the specified packages at the error debug level. The following debug levels are available going from least to most verbose:

• off:No logging at all.
• fatal:Log only fatal errors, which are typically errors that would cause an application to abort.
• error:Log all errors that occur but still allow the application to continue running.
• warn:Log scenarios that could be potentially harmful.
• info:Log informational messages that describe the progress of the application.
• debug:Log information that is used to debug an application.
• trace:The trace level is for even finer-grained events than the debug level.
• all:Log all messages that occur.

Sources within your own application can also be configured for logging. In Chapter 4 you learned about the log property available in every controller, tag library, or service. The output of this log property by default will use the root logging level of error. However, you can use the name of the class, starting with grails.app, to configure different logging behavior. For example, if you want to see output from all log statements in the UserController and AlbumArtService classes at the debug level, you could use the configuration in Listing 12-4.

Using sensible defaults, Grails will automatically configure a console appender that logs to standard out, while the root logger is set to the error level. You can also create your own custom Log4j appenders. For example, the code in Listing 12-5 sets up an additional file appender that writes the log to a file.

The example in Listing 12-5 uses a rollingFile appender, which is an org.apache. log4j.RollingFileAppender instance internally. Each named argument is a property of the org.apache.log4j.RollingFileAppender class, so to understand the configuration options, you just have to look at the Log4j APIs. The following is a list of the available Log4j appenders:

• jdbc:The org.apache.log4j.jdbc.JDBCAppender logs to a database connection.
• null:The org.apache.log4j.varia.NullAppender does nothing!
• console:The org.apache.log4j.ConsoleAppender logs to standard out.
• file:This is an org.apache.log4j.FileAppender that logs to a single file.
• rollingFile: This is an org.apache.log4j.RollingFileAppender that logs to a file that gets automatically backed up and re-created when a maximum size is hit.

You can also use the Log4j API yourself to create an appender programmatically and then simply call the appender method, passing your appender, to add your own appender. Notice also that Listing 12-5 uses the pattern method to define the layout property of the appender. This translates into an org.apache.log4j.PatternLayout instance. You can use a number of other layout styles, including the following:

• xml:An org.apache.log4j.xml.XMLLayout instance that outputs the log file in XML format.
• html:An org.apache.log4j.HTMLLayout instance that outputs the logs in HTML.
• simple:An org.apache.log4j.SimpleLayout instance that outputs to a preconfigured text format.
• pattern:An org.apache.log4j.PatternLayout instance that allows you to configure the output from Log4j. See the javadoc API for details.

Once you have an appender, you have to tell Log4j which packages need to be logged to that appender. Listing 12-6 shows an example of logging Hibernate output to the rollingFile appender defined earlier at the trace level.

Notice that you reference the appender by the name given to it using the name argument. Finally, there is one special logger for stack traces, which we'll discuss in the next section.

Stack Trace Filtering

Whenever an exception is thrown in Grails, the exception's stack trace will be filtered of all Groovy and Grails internals before it is logged. This is very useful because it allows you to narrow the problem down to how it relates to your code. Otherwise, you could be sifting through a rather large stack trace because all the internal layers of Grails are exposed.

Normally, when an exception is thrown in development, you can work out from the filtered trace what the problem is. On a rare occasion, you may want to inspect the full nonfiltered stack trace. Grails, by default, sets up a special logger to which it will log the full stack trace. This logger writes to a file called stacktrace.log in the root of your project.

However, you can quite easily override this default behavior to provide your own custom logger for unfiltered stack traces. Listing 12-7 shows an example configuration that logs all unfiltered stack traces to a rolling file appender.

You can also disable this functionality completely by passing the grails.full.stacktrace argument at the command line of your container or as an argument to the run-app command:

grails -Dgrails.full.stacktrace=true run-app

Externalized Configuration

During deployment, the Config.groovy file is compiled into a class and packaged into the WAR. Although this has its advantages, you may want to keep all configuration outside the main WAR file. For example, say you wanted to allow logging to be configured outside the application; to achieve this, you can use Grails' externalized configuration mechanism.

Essentially, within Config.groovy you can specify the grails.config.locations setting to contain a list of locations that need to be merged into the main configuration. Taking the logging example, Listing 12-8 shows how you could externalize the logging configuration to a file in the USER_HOME directory.

You can even allow the DataSource to be configured externally using this mechanism. Although DataSource.groovy and Config.groovy are separate files on the file system, Grails merges them into a single logical configuration object. Hence, you can externalize not just logging, or any configuration, but also the DataSource, as shown in Listing 12-9.

If you prefer to use static properties files in externalized configuration, you can do this too. Just use the extension. properties when referring to the files, and use regular java.util. Properties file semantics for configuration.

Understanding Grails' Build System

Grails' build system is powered by the Gant (http://gant.codehaus.org) build tool. Gant is a thin wrapper around Apache Ant (http://ant.apache.org), the ever-popular Java build system. Unlike Ant, which uses an XML format to describe a build, Gant uses a Groovy DSL. The benefit here is that you can easily mix build logic with scripting in Groovy code. Listing 12-10 shows a typical example of a Gant build script.

Notice how the example in Listing 12-10 defines a number of targets by calling the target method. These are equivalent to Ant's <target> tag. Also, as you can see, you can specify dependencies between targets using the depends method:

depends(compile, jar)

If you install Gant outside of Grails, Gant includes its own command-line interface via the gant command. The gant command will search for a file called build.gant, the same way Ant looks for build.xml, and attempt to call it if found. Using the gant command, you can call an individual target or chain them, as shown here:

$ gant clean jar

It's at this point that you'll begin to realize the differences between vanilla Gant and Grails. Although Gant behaves much like Ant, Grails wraps Gant in its own grails command—the same one you've been using throughout the book. The grails command uses conventions within a Grails project to try to automatically figure out which script to execute. For example, when you run the following command:

$ grails create-app

Grails will search the following directories for a Gant script called CreateApp.groovy to execute:

• PROJECT_HOME/scripts:The scripts directory of the current project.
• GRAILS_HOME/scripts:The scripts directory of the location where you installed Grails.
• PLUGINS_HOME/*/scripts:Each installed plugin's scripts directory.
• USER_HOME/.grails/scripts:The scripts directory within the .grails directory of the current user's home directory. The location of this is operating system dependent.

If a matching Gant script is found, the grails command will execute the default target of the Gant script. In contrast to the gant command, the grails command is optimized for Grails' project layout, for the plugin system, and for the easy use of passing arguments.

Creating Gant Scripts

To help you understand this better, let's take a look at a simple "Hello World"–style example. Using the grails create-script command, create a new script called HelloWorld.groovy:

$ grails create-script hello-world

As expected, you'll end up with a new Gant script in the called HelloWorld.groovy in the scripts directory of your project. Figure 12-1 shows the script sitting snugly in place.

Figure 12-1. The HelloWorld.groovy Gant script

Grails uses lowercase names separated by hyphens—for example, hello-world—when referencing scripts but transforms the name into camel case for the script name. Listing 12-11 shows the contents of the generated HelloWorld.groovy script from Figure 12-1.

As you can see, the template pulls in some existing functionality from a script called Init.groovy in the scripts directory of the location where you installed Grails. It then defines a single target, the default target, called main. To complete the "Hello World" example, you could use just a println statement or the echo target provided by Ant:

target(main: "The description of the script goes here!") {
    echo "Hello World!"
}

Now to run the hello-world script, all you need to do is run the following command using the grails executable:

---

$ grails hello-world
Welcome to Grails 1.1-SNAPSHOT - http://grails.org/
Licensed under Apache Standard License 2.0
...
Running script /Developer/grails-dev/book/dgg/code/ch12/scripts/HelloWorld.groovy
...
     [echo] Hello World!

---

Grails will perform a search of all the directories mentioned previously and find the HelloWorld.groovy script. Since the main target is the default target, Grails will execute it, which results in the "Hello World!" message being printed.

Of course, you have the entire Ant API at your disposal, which allows you to do a lot more than just print messages. Ant, and its plugins, provides access to targets that allow you to manipulate the file system, compile Java or Groovy code, perform XSLT transformations, and do just about anything you could dream of from the command line.

---

Tip It may be useful, if you aren't already familiar with it as most Java developers are, to take a look at the Apache Ant manual (http://ant.apache.org/manual/). It provides comprehensive information about what you can do with Ant.

---

Command-Line Variables

The Init.groovy script that was imported by HelloWorld.groovy in Listing 12-11 provides a bunch of useful variables and targets. These are some of the variables you may find useful:

• grailsVersion:The version of Grails you're using
• grailsEnv:The environment Grails is executing in
• basedir:A String representing the base directory that the script is executing from
• baseFile:Similar to basedir, but a java.io.File representation
• userHome:The current user's home directory as a String
• pluginsHome:The location where plugins are installed
• classesDir:The location where classes are compiled to

The grailsEnv variable deserves special mention. If you recall from Chapter 2, you can tell Grails to run within the context of development, test, or production environments. As a recap, the following command will execute the run-app command using the production settings:

$ grails prod run-app

Your scripts can be equally environment-aware using the grailsEnv variable. For example, if you want a Gant script to run only in the development environment, you can write code like this:

if(grailsEnv == 'development') {
    // do something
}

Some of the other variables, such as the pluginsHome and classesDir variables, are automatically constructed by Grails. By default, Grails stores plugins and compiled resources in your USER_HOME directory under a special path. For example, you can find the gTunes application's compiled classes in the directory USER_HOME/.grails/1.1/projects/gTunes/classes. Figure 12-2 describes some of the tokens that make up this path.

Figure 12-2. Grails compilation paths

As you can see from Figure 12-2, Grails takes the Grails version number and the project name to formulate a path within the USER_HOME directory. If you are not happy with this location, then you can tell Grails to use a different path by passing the grails.work.dir argument at the command line:

$ grails -Dgrails.work.dir=/tmp run-app

In fact, you can pass a whole load of different command-line arguments to customize the different locations that Grails uses:

• grails.work.dir:The base location where all Grails work occurs, including the test and source compilation directories
• grails.project.classes.dir:The location where project sources are compiled to
• grails.project.resource.dir:The location where project static resources (such as web.xml) are generated to
• grails.project.test.class.dir:The location where test sources are compiled to
• grails.plugins.dir:The location where plugins are installed
• grails.global.plugins.dir:The location where global plugins are installed

Parsing Command-Line Arguments

Unlike raw Gant, the grails command doesn't support chaining of targets, instead favoring the easy passing of command-line arguments. One useful target to depend on that is provided by the Init.groovy script is called the parseArguments target. The parseArguments target will read any command-line arguments and produce a variable called argsMap containing the values of the arguments in a more accessible form.

For example, say you wanted to enable the HelloWorld.groovy script to be able to print the name of the person to say hello to in either uppercase or lowercase. You could allow the name to be passed as a command-line argument and whether to print in uppercase or not as a command-line flag, as follows:

$ grails hello-world John -uppercase

Implementing the handling of these arguments manually would be somewhat tricky. Luckily, if you depend on the parseArguments target, all the heavily lifting is done for you. Listing 12-12 shows an updated HelloWorld.groovy Gant script that gracefully handles these arguments.

Notice that command-line flags (the arguments that start with - or --) are placed as boolean values into the argsMap. The example in Listing 12-12 shows how the -uppercase flag ends up as a boolean value with the key uppercase inside the argsMap. You can also have flags with values: for example, if you passed -uppercase=yes, then the value would be a String with the value yes in the argsMap.

All other arguments that are not flags are placed in the params key as a List that retains the order in which they were passed.

Documenting Your Scripts

You may have noticed from the script template in Listing 12-11 that the main target has a place holder for the description of the target:

target(main: "The description of the script goes here!") {

You can provide additional information about a target so that others understand better how to go about using your script. For example, to give information about the hello-world script, you could modify this as follows:

target(main: "Prints 'hello world' to System.out") {

Then whenever another user of your script needs to get help on how to use the script, they can use the help command provided by Grails, as shown in Listing 12-13.

---

If one line of help is insufficient, you can take advantage of Groovy multiline strings to provide more detailed help, an example of which is shown in Listing 12-14.

Reusing More of Grails

The inclusion of the Init.groovy script shown in Listing 12-11 is just one example of including an existing Grails script. You can in fact include a whole array of different scripts that provide different features. For example, say you want to make sure the tests run before your script is executed. You can include the TestApp.groovy script and depend on the testApp target, as shown in Listing 12-15.

Alternatively, if you want to make sure that the container is up and running, maybe in order to perform some kind of automated functional tests, you can use the RunApp.groovy script. This script is the same one used when you type grails run-app at the command line, and it provides a target called runApp that you can use to load Grails' embedded Jetty container. As an extension to this, in the next section you'll look at how you can load Grails without even needing a container.

Bootstrapping Grails from the Command Line

If you need access to the Grails environment from the command line, you can load Grails using the GRAILS_HOME/scripts/Bootstrap.groovy script. This will enable you to, for example, use GORM from the command line for batch processing.

To get started, you need to include the Bootstrap.groovy script as follows:

includeTargets << grailsScript("Bootstrap")

and then call the bootstrap target:

bootstrap()

Once this is done, a number of new variables will be created including the following:

• grailsApp:A reference to the org.codehaus.groovy.grails.commons.GrailsApplication class that allows you to inspect the conventions in a running Grails application.
• appCtx:The Spring ApplicationContext instance that contains the bean definitions for the Grails application, as found at runtime.
• servletContext:A mock implementation of the ServletContext, usable from the command line.
• pluginManager:A reference to the org.codehaus.groovy.grails.plugins. GrailsPluginManager instance that allows you to inspect the currently installed plugins.

The most commonly used of these is the appCtx variable that allows access to all the beans contained within the Spring ApplicationContext. For example, if you need to obtain the Hibernate SessionFactory and/or SQL DataSource, you can easily do so using the appCtx:

DataSource dataSource = appCtx.getBean("dataSource")
SessionFactory sessionFactory = appCtx.getBean("sessionFactory")

With the basics out of the way, let's see a couple of examples of using Gant to boost your command-line productivity.

Gant in Action

Printing "Hello World!" to the command window is fun and all, but ultimately it not very useful. In the following sections, you'll be looking at a couple of real-world Gant scripts. The first is a script that will allow you to quickly deploy to Tomcat.

Automated Deployment to Tomcat

Writing a Tomcat deployment script in Ant is pretty trivial thanks to the targets that ship with Tomcat (see http://tomcat.apache.org/tomcat-6.0-doc/manager-howto.html). However, before you can start this example, you need to make sure you have Tomcat installed and TOMCAT_HOME set to the location where you installed it. Then run the grails create-script command as follows:

$ grails create-script tomcat-deploy

With that done, you should have a TomcatDeploy.groovy file in the scripts directory of your project, as shown in Figure 12-3.

Figure 12-3. The TomcatDeploy.groovy script

The TomcatDeploy.groovy script template will look identical to the HelloWorld.groovy template you saw earlier. To begin with, you're going to need to figure out the path to the Tomcat installation directory. Inspecting the TOMCAT_HOME environment variable can help you achieve this:

grailsHome = ant.project.properties."environment.GRAILS_HOME"
tomcatHome = ant.project.properties."environment.TOMCAT_HOME"

With knowledge of the Tomcat directory in hand, the next thing to do is include the War.groovy script available in GRAILS_HOME/scripts. The War.groovy template contains targets that allow you to construct a valid WAR file:

includeTargets << grailsScript("War")

To take advantage of the Tomcat Ant tasks, you have to define them by calling the taskdef method. This method relates to the <taskdef> target of Ant, so defining Ant tasks in Gant is pretty much identical to doing so in pure Ant—minus the angle brackets:

ant.path(id:"tomcat.lib.path") {
    fileset(dir:"${tomcatHome}/server/lib",includes:"*.jar")
}
ant.taskdef(name:"deploy",
            classname:"org.apache.catalina.ant.DeployTask",
            classpathref:"tomcat.lib.path")

As you can see, the only tricky part is ensuring that all the JAR files for the DeployTask class are placed onto the classpath appropriately using the JAR files available in your Tomcat installation directory. This is done using the classpathref named argument and a predefined Ant path called tomcat.lib.path.

Moving onto the main target of the TomcatDeploy.groovy script, you can change it to depend on the war target, which will ensure a valid WAR file is constructed before the rest of the code runs:

target(main: "Deploys the Grails application to Tomcat") {
    depends(parseArguments, war)     ...
}

Once that is done, you need to establish the destination to publish the WAR to. You could, for example, accept the destination as the first argument to the command and otherwise default to localhost:

def dest = argsMap.params ? argsMap.params[0] : "http://localhost:8080/manager"

Once that is done, the rest is left to the deploy target supplied by the org.apache.catalina.ant.DeployTask class:

deploy(war:warName,
       url:dest,
       path:serverContextPath,
       username:"deployer",
       password:"secret")

The warName and serverContextPath variables are set up by the War.groovy script, which you can reuse here. The deploy target also requires that you pass username and password arguments whenever deploying to Tomcat. Given that you have a running instance of Tomcat locally, if you run the tomcat-deploy target now, you'll probably get a 401 error such as the following:

---

java.io.IOException: Server returned HTTP response code: 401 for URL:
http://localhost:8080/manager/deploy?path=%2FgTunes

---

The reason is that currently Tomcat doesn't have a user called deployer with a password of secret registered with it. To do so, you need to edit the TOMCAT_HOME/conf/tomcat-users.xml file and add a user who has access to the Tomcat manager application, as shown in Listing 12-16.

Once you have added the necessary Tomcat user, when you run the tomcat-deploy script, Grails will successfully deploy your application to Tomcat, as demonstrated in Listing 12-17.

---

You can of course take this further and write another tomcat-undeploy script or even combine them into two scripts. Nevertheless, Listing 12-18 shows the full code for the TomcatDeploy. groovy scripts.

Exporting Data to XML

Another fairly common use of command-line scripts is to allow the migration of data. You could do this by performing a SQL dump of the database, but maybe you want to offer the ability to export all the content held in the database as XML as some web applications such as Atlassian Confluence and JIRA do.

---

Note Although Grails, as of this writing, doesn't ship with a general-purpose migration solution for performing database migrations, you may want to take a look at the LiquiBase plugin (http://www.liquibase.org/manual/grails) and/or the DBMigrate plugin (http://code.google.com/p/dbmigrate/wiki/Grails), which both offer solutions to this problem.

---

Let's start by considering how you would write an export script that dumped all the relevant data from the gTunes application into a single parseable XML document. First you'll need to create a new Gant script called export-library-to-xml:

grails create-script export-library-to-xml

With that done, you're going to need to take advantage of the GRAILS_HOME/scripts/ Bootstrap.groovy script we discussed earlier. To do so, simply change the import of the Init.groovy script to Bootstrap.groovy:

includeTargets << grailsScript("Bootstrap")

Inside the main target, you then need to depend on the parseArguments and bootstrap targets:

depends(parseArguments, bootstrap)

First, using the mechanics of the parseArguments target, you can work out the file to export to by either taking the first argument or creating a name programmatically:

def file = argsMap.params ?
               new File(argsMap.params[0]) :
               new File("./gtunes-data-${System.currentTimeMillis()}.xml")

As mentioned previously, the bootstrap target will set up a grailsApp variable that holds a reference to the GrailsApplication instance. The GrailsApplication instance can be used to dynamically load classes using the classLoader property. You need to do this because Gant scripts cannot directly reference the classes in your application, because they can't know whether those classes have been compiled yet. Luckily, it is pretty trivial to obtain a reference to any class using the classLoader:

def Artist = grailsApp.classLoader.loadClass("com.g2one.gtunes.Artist")

Unlike Java, with Groovy you can invoke any static method using a reference to java. lang.Class; hence, you can use regular GORM methods easily even with a dynamically loaded class reference. The first example of this is using the static count() method to figure out how many artists there are:

def artistCount = Artist.count()

Now it's time to create the XML. To do so, you're going to use Groovy's StreamingMarkupBuilder class. Listing 12-19 shows how to construct and use StreamingMarkupBuilder.

Builders in Groovy allow you to construct hierarchies of nodes, a concept that fits nicely into the construction of XML. In this case, the music method will become the root element <music> of the XML document. In the next step, you initiate a transaction using the withTransaction method first discussed in Chapter 10.

The reason for using a transaction here is so that a common Hibernate Session is shared for the remainder of the code, hence avoiding a LazyInitializationException occurring when accessing uninitialized associations. Unlike in the server environment, Grails does not do any management of the Hibernate Session for you in scripts, but using withTransaction you can circumvent that:

Artist.withTransaction {
    ...
}

As well as withTransaction, you're going to take advantage of the withSession method to obtain a reference to the Hibernate Session object used. As discussed in Chapter 10, when reading a large amount of data into the Hibernate Session, you may run out of memory if you don't periodically clear the Session, and since you don't exactly know how much data is in the database, you're going to be doing that here:

Artist.withSession { session ->
    ...
}

The next step, if you'll excuse the pun, is to use the step method using the previously obtained artistCount variable to perform pagination of records. With this technique, you can obtain, say, ten Artist instances, including associations; manipulate them in some way; and then clear the Session before loading the next ten. Listing 12-20 shows the code in action.

With a list of Artist instances in hand, now it's just a matter of iterating over each one to create a bunch of <artist> XML elements:

for(currentArtist in artistList) {
    artist(name:currentArtist.name) {
        ...
    }
}

Finally, you also need to include all the Album instances associated with each Artist and all the Song instances associated with each Album. You can achieve this with a couple more nested loops:

for(currentAlbum in currentArtist.albums) {
    album(currentAlbum.properties['title', 'year', 'genre', 'price']) {
        for(currentSong in currentAlbum.songs) {
            song(currentSong.properties['title', 'duration'])
        }
    }
}

Notice how you can reference a subset of each Album instance's property values using the subscript operator and a List of property names:

currentAlbum.properties['title', 'year', 'genre', 'price']

And with that, the export-library-to-xml script is complete. Listing 12-21 shows the full code listing for the export-library-to-xml Gant script.

As you can see from the full code in Listing 12-21, you can also add a couple of println statements just to inform the user what is going on. You can now run the export-library-to-xml script using the grails command, and out will pop an XML document, as shown in Listing 12-22.

---

As you can see in this example, the script produces a file called gtunes-data-122224970.xml. The contents of this file contain the XML built by StreamingMarkBuilder; Listing 12-23 shows an example.

---

Integration with Apache Ant

As discussed already, Grails' build system Gant builds on Ant. However, it may be a requirement for your organization to support a pure Ant build. If so, you have a number of options at your disposal. The first, and simplest, option is to use the build.xml file that is present in the root of every Grails project. This build.xml file simply delegates to Grails commands and hence relies on a copy of Grails being installed. Listing 12-24 shows an example of running the test target and the tests failing!

---

As you can see from Listing 12-24, the build.xml file uses the Ant <exec> target to simply delegate responsibility to the grails command. Another approach to integrating Ant and Grails is to use the GRAILS_HOME/src/grails/grails-macros.xml file, which defines a <grails> macro target for calling Grails commands.

You can include the grails-macros.xml file in any normal Ant build using an Ant <import>:

<property environment="env" />
<import file="${env.GRAILS_HOME}/src/grails/grails-macros.xml"/>

In this example, you're using the location within GRAILS_HOME, but you could copy it to a more convenient location in your build if necessary. With that done, you can now use the new <grails> macro target to call Grails commands:

<grails command="test-app" />

The <grails> command works by looking up the appropriate classes from GRAILS_HOME. If the build environment you're working with doesn't have a GRAILS_HOME, then you'll need to use the <extend-classpath> element to tell the <grails> target where to look for the Grails JARs, as shown in Listing 12-25.

If you need to pass arguments to the <grails> command, you can use the args attribute. For example, the following usage will use Grails' test-app command to run the UserControllerTests unit test:

<grails command="test-app" args="UserController" />

Finally, if you need to pass system properties to the Grails command, such as to change the server port, you can do so with the <sysprops> element, as shown in Listing 12-26.

Dependency Resolution with Ivy

Apache Ivy is a dependency manager for Ant. With Ivy you can specify the JAR dependencies of your project in XML format. Your build then automatically downloads these dependencies. You can integrate Ivy into Grails in a couple of ways. One way is to just use the Ant build.xml file and integrate Ivy using the standard way described on the Ivy web site at http://ant.apache.org/ivy/history/latest-milestone/tutorial/start.html.

However, there is also a plugin for Grails that quickly integrates Ivy with Grails. To get started, you need to run the install-plugin command as follows:

grails install-plugin ivy

This installs Ivy for you locally without you having to download the Ivy distribution yourself. It will also automatically create the ivy.xml and ivyconf.xml files, both of which are necessary for transitive dependency resolution with Ivy. Figure 12-4 shows the two files nestled within the root directory of the target project.

Figure 12-4. The Ivy configuration files

The ivyconf.xml file allows you to specify one or more resolvers to resolve dependencies. Typically you can leave this file alone, because you'll need to modify it only if you plan to configure additional repositories or even host your own repositories. The ivy.xml file is used to define the actual dependencies. Currently, the gTunes application defines a few dependencies that are contained in the lib directory, as shown in Figure 12-5.

Figure 12-5. Current JAR dependencies

Some of these, like the Amazon JAR, won't necessarily be available in the repositories that Ivy scans. As mentioned, to make these available somewhere, you could host your own repositories and configure ivyconf.xml appropriately. Nevertheless, Listing 12-27 shows an example of configuring ivy.xml to resolve dependencies in the gTunes application.

Ivy has the ability to use Maven repositories to resolve dependencies, and as you can see, you can use a similar format to the Maven pom.xml file to specify dependencies on the ivy.xml file. With the ivy.xml file configured, you can then download dependencies using the get-dependencies command:

grails get-dependencies

Listing 12-28 shows the output from Ivy as it automatically resolves and downloads the necessary dependencies.

---

Now we'll cover how to integrate code coverage reporting into a Grails application.

Code Coverage with Cobertura

Even if you are an avid Test-Driven Development (TDD) practitioner, writing unit tests without knowing what code is covered by tests and what is not is a bit like shooting in the dark. Code coverage reports are incredibly useful because they will tell you what lines of code are covered by your unit tests and help you make an informed decision on what test you should be writing next. You'll often hear agile teams talking about improving their coverage. This decision is based on the analysis of coverage reports.

Out of the box, Grails does not produce code coverage reports, but thanks to the code-coverage plugin, it is easy to integrate the generation of code coverage reports into your application. To get started, as usual run the install-plugin command to install the code-coverage plugin:

$ grails install-plugin code-coverage

With that done, you can then run the test-app-cobertura command, which uses Cobertura (http://cobertura.sourceforge.net/), a code coverage tool for Java, to produce coverage reports. Cobertura uses byte code instrumentations and hence will slow down the running of your tests, but it will produce a nice set of reports in the test/reports/cobertura directory for you. Figure 12-6 shows an example.

Figure 12-6. A Cobertura coverage report

You can click any of the class names in the report in Figure 12-6 to get line-by-line coverage information. As you can see, you still have some work to do to improve the coverage of the gTunes application. However, it is important to note that you may have 100 percent coverage and still have holes in your unit tests. Code coverage should be used to show the areas of code that need testing, not as a sign of test completeness.

Since coverage reports may take a while to produce, you don't want to have to create them every time you run your test suite. It may be better to delegate this responsibility to a build server. In the next section, we'll cover how to set up continuous integration to achieve this.

Continuous Integration with Hudson

Agile and test-driven philosophies have been debated endlessly and are a subject beyond the scope of this book. Nevertheless, if there is one agile practice that would bring immediate benefits to any project, whether "traditional" or agile, it is continuous integration.

Continuous integration involves setting up a server that continuously (either on a schedule or through monitoring for changes) builds the latest code, runs any tests, and produces a snapshot of the code for distribution. The continuous integration server can perform all manner of additional tasks from producing coverage reports to creating the latest documentation and even sending e-mails or SMS messages to notify of build failures.

In this section, we'll demonstrate how to use Hudson, an open source continuous integration server available at https://hudson.dev.java.net/. To get started, you need to download the hudson.war distribution of Hudson and deploy it to a container such as Apache Tomcat. Deployment with Tomcat is a simple matter of dropping the WAR into the TOMCAT_HOME/ webapps directory and firing up Tomcat.

Then you can go to http://localhost:8080/hudson, assuming Tomcat is up and running on port 8080, and you'll be presented with the Hudson Dashboard shown in Figure 12-7.

Figure 12-7. The Hudson Dashboard

The next step is to install the Grails plugin for Hudson. From the main Dashboard screen, click the "Manage Hudson" link, and then click the "Manage Plugins" link. On the Available tab, select the check box next to the Grails plugin, and click the "Install" button at the bottom of the page. Once you have installed the plugin, you'll need to restart Hudson.

Once the Grails plugin is installed, the next step is to configure your Grails installations in Hudson. The plugin does not come with its own version of Grails. The plugin uses a version of Grails that must be installed on the system separately from Hudson. The plugin allows you to configure as many different versions of Grails as you like. This is useful if you are building multiple Grails projects in the same Hudson instance and not all of those Grails projects are built with the same version of Grails.

To configure your Grails installations in Hudson, click the "Manage Hudson" link on the main Dashboard screen, and then click the "Configure System" link. Figure 12-8 shows the part of this screen that is used to configure your Grails installations.

Figure 12-8. Configuring Grails installations in Hudson

You can see that each Grails installation has a name and a GRAILS_HOME. The name is simply an identifier that will help you select a particular version of Grails later when configuring jobs. The value of GRAILS_HOME must point to a specific Grails installation directory. Notice that there is validation built in to let you know whether the directory you have entered does not exist. The validation is not activated until you tab out of the text field.

Once you have configured all your Grails installations, make sure you scroll all the way to the bottom of the page and click the "Save" button.

With at least one Grails installation configured in Hudson, you are ready to create a job for a Grails project. You create a job for a Grails project in the same way you would for any other project in Hudson. From the main Dashboard screen, click the "New Job" link. Most often you will be creating a job for a so-called free-style software project, so you will select that radio button on the form to create a new job. See Figure 12-9.

Figure 12-9. Creating a new free-style job

Once you click the "OK" button, you will be taken to the page where you configure all the details for how this build will be carried out. This page allows you to define which version control system you are using, paths to the project, a schedule for building the project, and so on. Near the bottom of the page is where you will configure the actual build steps. Once the Grails plugin is installed, a new build step should show up labeled "Build With Grails," as shown in Figure 12-10.

Figure 12-10. The "Build With Grails" build step

When you select the "Build With Grails" build step, the page will be updated with a form, which lets you configure the Grails build. This will include at a minimum specifying a version of Grails to use and which Grails targets to execute. A typical target to execute is the test-app target, but you can configure your job to execute whichever targets make sense. Figure 12-11 shows the details of a Grails build.

The "Grails Installation" drop-down will include all the Grails installations you configured earlier. Select the version of Grails that this job should be built with.

The "Targets" field lets you specify as many targets as you would like to be executed as part of this build. The targets will be executed in the order that they are specified in this text box. If any arguments are to be passed to any particular target, then the target name and the arguments should be surrounded by double quotes so the plugin knows to group them as one command.

There are fields for specifying the grails.work.dir and project.work.dir system properties.

The "Project Base Directory" field will typically be left blank but is important if the Grails project is not at the root of the job's working directory. For example, if your Grails project is in your SCM system at a path like /projects/development/code/grails/gTunes/ and for some reason you need to configure this job to check out everything under /projects/development/code/ grails/gTunes/, then you will need to specify a value for the "Project Base Directory" field. The problem here is that the job root is /projects/development/code/grails/gTunes/, so the plugin will execute all Grails commands from that directory. Since that isn't the root of the Grails project itself, all the Grails commands will fail. To support this scenario, the "Project Base Directory" field should be given a value of /projects/development/code/grails/gTunes/, which is a relative path from the job root directory down to the root of the Grails project. With that in place, all of the Grails commands will be executed from the /projects/development/ code/grails/gTunes/ directory.

Figure 12-11. Configuring a Grails build

All other aspects of configuring a Grails job in Hudson are no different than they are for any other type of project.

Adding Support to Your Favorite IDE

Java developers in general have become particularly reliant on the comfort of modern integrated development environments (IDEs). This is largely because of the strictness of the Java language. From its static typing rules to quirks like its insistence on semicolons at the end of each line of code, it is hard to write anything in Java without a little nagging from the compiler. Fortunately, modern IDEs such as Eclipse and IntelliJ have made life a lot easier. In fact, they've done more than that. With the advent of refactoring tools, Java has become one of the most maintainable languages out there.

The tools in the dynamic language space are in general nowhere near as advanced as those available for Java. On the other hand, many developers create entire applications in simple text editors such as TextMate and jEdit, preferring their speed and efficiency to the relative clunkiness and slowness of a robust, richly featured IDE. This is possible because of the simplicity of frameworks such as Grails and the relatively forgiving Groovy grammar. It is our view that you can certainly get away with using the simpler tools during the early days of an application's life cycle.

However, as the application grows and enters the maintenance phase, the need for an IDE will also grow—particularly for refactoring and maintenance. Fortunately, although the tooling is much younger, you do have options available to you, which we will be covering in the following sections.

IntelliJ

By far the most complete IDE for Grails available at the moment is JetBrains' IntelliJ IDEA with the JetGroovy plugin installed. JetBrains worked closely with the Groovy team to make it the best possible environment to develop Groovy and Grails applications. In addition, although IntelliJ is a commercial IDE, JetBrains embraced the open source nature of Groovy by contributing back to the community. The joint compiler built into Groovy that allows Java and Groovy classes to be compiled together was contributed to Groovy during the development of JetGroovy.

JetGroovy contains the most complete support for code completion available for Groovy, performing completion on all statically typed references. Using type inference, JetGroovy can even sense completions on many dynamically typed references. JetGroovy also includes full circular refactoring, so if you rename a method in a Java source, it's picked up on the Groovy side. Likewise, if you rename a method in a Groovy source, all the Java code referencing that method changes accordingly.

JetGroovy will also complete all the dynamic methods added by Groovy at runtime, and you get many of the inspectors and quick fixes Java developers have come to expect. We recommend you take a look at the excellent marketing material JetBrains has put together on JetGroovy, which describes the features available in detail, at http://www.jetbrains.com/idea/features/groovy_grails.html. You can find even more documentation on JetGroovy on the Grails web site at http://www.grails.org/IDEA+Integration. Figure 12-12 shows the IntelliJ IDEA with JetGroovy in action.

Figure 12-12. IntelliJ IDEA with the JetGroovy plugin