The Power of Groovy DSLs

By James Kleeh, OCI Software Engineer

November 2016

In this article, I will show you what a DSL is, how it works, and how you can create your own DSL to improve your productivity.

DSL stands for Domain Specific Language. It is not a new concept; people have been creating DSLs for a long time now. The reason I am writing this article is to hopefully show you a couple tricks that you may not be aware of.

What is a DSL?

There is a larger definition of a domain specific language, however in the context of Groovy code, a DSL is a way of creating APIs that leverages Groovy's closures to create an easy way to build complex data. To understand how a DSL works, you must understand how closures work.

Closures

If you are familiar with Groovy at all, then you are also likely familiar with closures. Closures are the gateway to functional programming in Groovy. They represent executable pieces of code that may be passed as arguments to other methods.

void someMethod(Closure c) {
    println "Inside someMethod"
    c.call()
}
Closure closure = {
    println "I'm inside a closure"
}
someMethod(closure)
 
//The following will be output to the console
Inside someMethod
I'm inside a closure

Closures also have a couple other properties that are essential to building DSLs. The first is the delegate. You can assign an instance of a class to be the "delegate" of the closure. What that means is that, by default, if you attempt to execute a method inside the closure, and it is not found, then it will look for that method in the delegate. In this next example, the append method will be called on the instance of StringBuilder that we have assigned to be the closure's delegate, because we don't have an append method defined in the scope of the closure.

Closure closure = {
    append("I'm inside a closure")
}
StringBuilder sb = new StringBuilder()
closure.delegate = sb
closure.call()
 
assert sb.toString == "I'm inside a closure"

If a method called append does exist, that method will instead be called.

void append(String text) {
    println text
}
Closure closure = {
    append("I'm inside a closure")
}
StringBuilder sb = new StringBuilder()
closure.delegate = sb
closure.call()
 
assert sb.toString == ""
//The following will be output to the console
I'm inside a closure

Fortunately, we have control over that behavior. We can tell the closure what order it should look for methods to execute. We do that with the resolveStrategy property of the closure.

void append(String text) {
    println text
}
Closure closure = {
    append("I'm inside a closure")
}
StringBuilder sb = new StringBuilder()
closure.delegate = sb
closure.resolveStrategy = Closure.DELEGATE_FIRST
closure.call()
 
assert sb.toString == "I'm inside a closure"

In the above example, we set the resolve strategy of our closure to tell Groovy we would like to search for methods on our delegate, before the owner of our closure.

Possible resolve strategies include:

OWNER_FIRST (default)
OWNER_ONLY
DELEGATE_FIRST
DELEGATE_ONLY

A closure combined with a delegate and resolve strategy is the cornerstone of the type of DSL this article discusses.

Creating a DSL

For many of the examples here, I refer to creating an Excel document. I have recently created a great DSL to build Excel documents with support for many things including merged cells, formulas, and cell styling. It is a perfect example because it took a complicated API, the Apache POI library, and converted it into something that may be learned in a few minutes for most use cases. Take a look at my Excel Builder library to see if it is something that may be useful to you!

I would also like to highlight another fantastic library created by Craig Burke that allows you to build PDFs and word documents using a DSL: Document Builder

To understand why creating a DSL may be beneficial, take a look at the simplest example possible to create a workbook, sheet, row, and cell in Apache POI.

import org.apache.poi.xssf.usermodel.XSSFWorkbook
import org.apache.poi.xssf.usermodel.XSSFSheet
import org.apache.poi.xssf.usermodel.XSSFRow
import org.apache.poi.xssf.usermodel.XSSFCell
 
XSSFWorkbook wb = new XSSFWorkbook()
XSSFSheet sheet = wb.createSheet()
XSSFRow row = sheet.createRow(0)
XSSFCell cell = row.createCell(0)
cell.setCellValue("A1")

The power of a Groovy DSL transforms that into this:

import com.jameskleeh.excel.ExcelBuilder
 
ExcelBuilder.build {
    sheet {
        row {
            cell("First Cell")
        }
    }
}

With this new code, it is no longer necessary to understand the Apache POI API or keep track of our row and cell indexes. In addition, I believe the DSL made our code much easier to understand, especially to someone who is not familiar with Apache POI. Let's take a look at how this was done.

class ExcelBuilder {
    static XSSFWorkbook build(Closure callable) {
        XSSFWorkbook wb = new XSSFWorkbook()
        callable.resolveStrategy = Closure.DELEGATE_FIRST
        callable.delegate = new Workbook(wb)
        callable.call()
        wb
    }
}
 
class Workbook {
    private final XSSFWorkbook wb
 
    Workbook(XSSFWorkbook wb) {
        this.wb = wb
    }
 
    XSSFSheet sheet(Closure callable) {
        XSSFSheet sheet = wb.createSheet()
        callable.resolveStrategy = Closure.DELEGATE_FIRST
        callable.delegate = new Sheet(sheet)
        callable.call()
        sheet
    }
}
 
class Sheet {
    private final XSSFSheet sheet
    private int rowIdx
 
    Sheet(XSSFSheet sheet) {
        this.sheet = sheet
        this.rowIdx = 0
    }
 
     XSSFRow row(Closure callable) {
        XSSFRow row = sheet.createRow(rowIdx)
        callable.resolveStrategy = Closure.DELEGATE_FIRST
        callable.delegate = new Row(row)
        callable.call()
        rowIdx++
        row
    }
}
 
class Row {
    private final XSSFRow row
    private int cellIdx
 
    Row(XSSFRow row) {
        this.row = row
        this.cellIdx = 0
    }
 
    XSSFCell cell(Object value) {
        XSSFCell cell = row.createCell(cellIdx)
        cellIdx++
        cell.setCellValue(value.toString())
        cell
    }
}

The above classes are an extremely simplified version of the actual implementation; however, it is enough to demonstrate the basic usage. The above classes abstract away Apache POI and manage for us the row and cell indexes. With some reference documentation, any developer should be able to create extremely simple excel documents within minutes.

Problems

Using DSLs comes with a couple of drawbacks of which you should be aware.

One of the major problems with DSLs created in the past (and some created today) is that it is often difficult or impossible for the IDE to know about what methods are available to be executed. The IDE has no idea what class will be assigned to the closures delegate. Because of that, you are often left with reading the documentation to discover the different method signatures that a given method has.

In addition to IDE support, performance may also be a concern if you are doing processor intensive tasks. Groovy code is typically slower than Java and that may be a factor in deciding how to write your code in some cases. A common solution is to annotate your class with @CompileStatic. However, if you are using a DSL like the above, it will not compile, because the compiler doesn't know which delegate will be assigned in the future.

The following class will fail compilation in Groovy 2.4.7:

@CompileStatic
class Bar {
 
    void foo(Closure x) {
        x.delegate = new StringBuilder()
        x.call()
    }
 
    void doIt() {
        foo({
            append('u')
        })
    }
 
}
 
new Bar().doIt()

The Solution

Groovy 2.1 included an annotation to assist with all of the problems described above. The DelegatesTo annotation may be added to the Closure parameter to denote what class will be assigned to the delegate. Adding that annotation will allow your code to statically compile, as well as allow your IDE (if it has good Groovy support) to auto complete methods. Here is what that looks like:

@CompileStatic
class Bar {
 
    void foo(@DelegatesTo(StringBuilder) Closure x) {
        x.delegate = new StringBuilder()
        x.call()
    }
 
    void doIt() {
        foo({
            append('u')
        })
    }
 
}
 
new Bar().doIt()

Now our example code will compile just fine and will perform essentially the same as regular Java code.

I hope this article has introduced you to some pretty cool features of Groovy, and that you will use this new knowledge to create tools to improve the productivity of your team!

Software Engineering Tech Trends (SETT) is a regular publication featuring emerging trends in software engineering.