Readers would be pleased to know that we have teamed up with Packt Publishing to organize a giveaway of our book, Groovy 2 Cookbook.

And three lucky winners stand a chance to win 3 digital copies of this book. Keep reading to find out how you can be one of the lucky winners.

Book overview

• Simple and more advanced recipes to cover a broad number of topics and challenges
• With scores of practical examples, this book will help you to build efficient, flexible, and well-integrated systems
• Solve everyday programming problems with the elegance and simplicity of Groovy 2

How to enter?

All you need to do is head on over to the main page of this website, look through the product description of the book and related blog posts, and fill in the following form to let us know what interests you the most about this book. It's that simple.

Winners will get an e-copy of the book.

Deadline

The contest will close on 28th of February, 2014. Winners will be contacted by email, so be sure to use your real email address when you comment!

• version control-friendly source files
• automated testing and validation
• continuous integration

Markdown format

We were asked by Packt, our publisher, to write the drafts in Microsoft Word and use the styles dictated by their templates.

From the very beginning, we realised that this was not a very convenient way to work as a distributed team of two writers.

Word is an excellent format for solo writing, but it's a nightmare to store Word documents in any version control system. We knew it was going to lead us to a lot of frustration. So, we decided to take a simpler, saner approach: Markdown and text files. No more DOCX files that can only be edited from the over-bloated interface of a modern word processor.

The book is completely written in the Markdown format, which is easy to read, write and automate. To keep our publisher happy, we still had to produce Word documents out of the Markdown files. We ended up writing a Markdown to Word converter in Groovy, leveraging the excellent libraries available in Java (e.g. pegdown for parsing Markdown syntax and docx4j for creating Word documents).

The first version of the converter was just using default Word styles, and, obviously, publisher complained about it, but we quickly adjusted the generation process to match their Word template.

Markdown, after all, is just text files, and we enjoyed the same benefits that we normally get when working with source code. The most important of them being the easiness of merging file, which allowed us to work at the same time on the same content. Furthermore, now we could use any text editor on any device (even on a smart-phone) to edit the book. It felt much more natural (and cheaper!) than being dependent on a legal copy of Microsoft Word to be installed on our laptops.

Naturally, Markdown does not offer the multitude of features of a modern Word processor, but we found the zen-like simplicity of Markdown more than enough for our needs. In addition, Markdown (and the pegdown library that we used for parsing it) is easily extensible with additional styles. By the time the book was close to its final shape, we had extended the converter to support the complex Packt formatting styles, such as notice and information boxes, screen texts and keywords.

Quality control

Markdown, thanks to its straightforwardness, is easier to automate. For example, inside our Markdown-to-Word converter, we've implemented several validators and rules, which are close to impossible to implement in Word. Here are some examples of those rules:

• Each recipe should contain at least How it works... section.
• Each recipe should only contain allowed headers ( Getting ready..., How to do it..., How it works... etc.).
• There should be at least 1 paragraph of text between headers, code blocks or images.
• Introduction section should contain "in this recipe"-like phrase.
• and many more other rules...

Also, there were some very Groovy-specific rule sets that we applied to the code snippets appearing in the book:

• Each Groovy snippet was compiled upon build to catch any complication errors.
• Each Groovy snippet was passed through CodeNarc - Groovy static code analysis tool - to find any standard Groovy code styling and naming issues (we also talk about that tool in the book).

Additionally, text of the book was checked for spelling and grammar problems with the help of existing Java libraries.

Continuous integration

The conversion from Markdown to .DOCX and the quality control tasks mentioned above have been organised into a build process (driven by Gradle) and automated via our favorite continuous integration server - Jenkins.

On each chapter build, all the rule violations were collected into a report that was visible to both of us, so that we could see the current state of the chapter and the book as a whole. Once again, we have capitalised on our experience as developers and brought some software development best practices to the book editing and publishing world. This process resulted in blazing fast feedback for, us, the authors and a laser-accurate status for the publisher.

The above report is another example of the kind of quality control that we applied to the book. The report was generated with the help of Jenkins Warnings Plugin, which was configured to catch book specific warnings from the build output.

To keep tracks of the many TODOs in the book's drafts, we collected and monitored them with the help of the Jenkins Task Scanner Plugin.

Conclusion

We hope you enjoyed this "behind the scenes" report of the process that brought us to create a brand new strategy for editing and controlling the quality of a book.

Jenkins is a popular open source continuous integration server. It is used by many organizations to control their software quality. In this recipe, we are not going to look into how to build Groovy code with Jenkins, since Jenkins already has support for Ant, Maven and Gradle build tools through its plugin system. We already looked at how Groovy source code can be built with those tools in recipes Integrating Groovy into build process using Ant, Integrating Groovy into build process using Maven and Integrating Groovy into build process using Gradle from Chapter 2, Using Groovy Ecosystem. Jenkins can invoke those tools directly to execute the build logic.

This recipe looks into how to extend Jenkins jobs with Groovy code.

Getting ready...

We assume that the reader has some knowledge of Jenkins, knows how to create basic jobs and how to install plugins. If not the case, some very instructive tutorials can be found at:

• https://wiki.jenkins-ci.org/display/JENKINS/Building+a+software+project
• https://wiki.jenkins-ci.org/display/JENKINS/Plugins#Plugins-Howtoinstallplugins

There's also an assumption that Jenkins is running on your local machine on port 8080. So, that http://localhost:8080 gives you access to the default Jenkins console. To start Jenkins locally, download the latest jenkins.war from http://jenkins-ci.org/ and launch the following command from your shell:

java -jar jenkins.war

The two main components that will help us with our recipe are:

• Jenkins Groovy plugin
• Jenkins Groovy Postbuild plugin

The first one is used to execute Groovy code within a job's "body". Basically it allows adding custom build steps to your build process. The second plugin is used to influence the build result display (e.g. add informative label or icon depending on the parameters) or simply execute additional code (e.g. send HTTP post request) of your choice upon build completion: be it success or failure.

Before proceeding you need to install those 2 plugins and restart the Jenkins server to ensure they are fully initialized. Just go to http://localhost:8080/pluginManager/available:

Another action that you need to execute after the plugins are activated is to install the Groovy distribution inside Jenkins. For that you need to go to the system configuration page (http://localhost:8080/configure), locate "Groovy" section, click "Add Groovy" button and specify your Groovy SDK location or make Jenkins download it from the Internet:

How to do it...

Jenkins is running, plugins are installed and Groovy distribution is set up, you are now ready to proceed with the recipe's steps.

First of all, open Jenkins web interface in the browser and select "New Job" link or just type http://localhost:8080/newJob in the address bar.

After that select "Build a free-style software project" job type and type job's name to be GROOVY_JOB and press "OK" button, that will lead to job's configuration screen.

In the configuration page, in the "Build" section click the "Add build step" button and select "Execute Groovy script" option.

This will let you to add a Groovy script as a build step inside the job. The script we want to add is a simple weather data download, which is explained in more details later:

import groovy.time.TimeCategory

def weatherFile  = new File('weather.xml')
def lastUpdate   = new Date(weatherFile.lastModified())
def now          = new Date()
def weatherSvc   = 'http://www.yr.no/place/'
def weatherQuery = 'Switzerland/Vaud/Lausanne/varsel.xml'
def weatherLink  = "${weatherSvc}${weatherQuery}"
def age          = TimeCategory.minus(now, lastUpdate)

if (age.minutes > 10) {
  println 'WEATHER DATA IS OUTDATED. UPDATING...'
  println 'Weather forecast from yr.no,'
  println ' delivered by'
  println ' the Norwegian Meteorological Institute'
  println ' and the NRK'
  println weatherLink
  weatherFile.text = new URL(weatherLink).text
  println 'DONE.'
} else {
  println 'WEATHER DATA IS UP-TO-DATE'
}

The configuration screen should look like this:

After that go to "Post-build Actions" section of the configuration page, click "Add post-build action".

Type in another script, that transforms weather data into build label information:

def workspace   = manager.build.workspace.getRemote()
def weatherFile = new File(workspace, 'weather.xml')
def weatherData = new XmlParser().parse(weatherFile)
def temperature = weatherData.forecast
                               .tabular.time[2]
                               .temperature.@value[0]
def mood        = weatherData.forecast
                               .tabular.time[2]
                               .symbol.@name[0]
manager.addShortText("$temperature *C")
manager.addShortText(mood,
                   'grey', 'white',
                   '0px', 'white')

The action's configuration should look similar to this:

Run the job several times by clicking the "Build Now" link.

The "Build History" widget should display weather information approximately in the following way:

How it works...

The first script uses public weather data provided by the Norwegian Meteorological Institute. Since data is freely available, there are some restrictions on how often you can actually call the remote service. That's why there is a check on how old the potentially existing data file is. If it's older than 10 minutes or does not exist, then script makes a new service call. To calculate time difference we use minus method of the groovy.time.TimeCategory class, which returns an instance of the groovy.time.TimeDuration class. The TimeDuration has a minutes property that can be queried to determine the total duration in minutes.

For reading service data, the java.net.URL class with Groovy extensions is used. We will discuss how Groovy can extend existing classes in recipe Adding functionality to existing Java/Groovy classes from Chapter 3, Using Groovy Language Features. You can also read more about the URL data downloading in recipe Downloading content from the Internet from Chapter 8, Working with Web Services in Groovy.

For writing data into the weather.xml file, an instance of the java.io.File class on Groovy "steroids" is utilized. We are going to discuss file manipulation in Chapter 4, Working with Files in Groovy, specifically in Writing to a file. Magically, reading and writing happens in one line. Groovy shines here! The script is executed from within the job's work space directory. That's where the weather.xml will be eventually stored.

The second script reads the weather forecast data from the saved weather.xml file and adds short text blocks to the build result. The manager object is injected by the Jenkins Groovy Postbuild plugin and gives access to plugin's (e.g. the addShortText method) and Jenkins (e.g. manager.build) core functionality. This script is executed in a different context from Jenkins point of view, that's why in the beginning we need to pass job's work space directory path for constructing weather.xml file location.

To parse and extract weather data we use Groovy's XmlParser class and GPath expressions. Both are discussed in more details in recipes Reading XML using XmlParser and Searching in XML with GPath in Chapter 5, Working with XML in Groovy. We will omit those details in this recipe because we are focused on a different goal. More information about the manager object capabilities can be found on the plugin's home page.

There's more...

Groovy is integrated into Jenkins not only through the above mentioned plugins and build tools. Jenkins also has a command line interface, which allows running Groovy scripts remotely to manage Jenkins configuration, retrieve monitoring data and control job execution. You can find a list of available commands on the http://localhost:8080/cli page. That page also allows you to download jenkins-cli.jar for your specific Jenkins installation.

For example, the following print.groovy script will list all the installed Jenkins plugins and their versions:

jenkins.model.Jenkins.instance.pluginManager.plugins.each {
    println "${it.shortName} v${it.version}"
}

To execute this script against your local Jenkins server, you need to put jenkins-cli.jar as well as print.groovy into your current directory and type the following command:

java -jar jenkins-cli.jar -s http://localhost:8080/ groovy print.groovy

This will approximately print:

mailer v1.5
external-monitor-job v1.1
ldap v1.2
pam-auth v1.0
...
groovy-postbuild v1.8
groovy v1.14
...

In this way, Groovy lets you fully automate the management of your Jenkins server(s)!

See also

• Jenkins Ant plugin
• Jenkins Maven plugin
• Jenkins Gradle plugin
• Jenkins Groovy plugin
• Jenkins Groovy Postbuild plugin
• Jenkins command line interface description