A cache is often used to store the results of an expensive operation. Typically, a somewhat simple (and unsafe code) would look like the following code snippet:

def cacheMap = [:]
def expensiveMethod(Long a) {
  def cached = cacheMap.get(a)
  if (!cached) {

    // Very expensive operation
    Long res = service.veryLongCall(a)

    cacheMap.put(a, res)
    cached = res

  }
  cached
}

The code simply checks if the argument of the function is a key of the Map, and it executes the expensive code if the key is missing. Otherwise, it returns the value associated to the key.

A more elegant and more idiomatic variation of the previous code can be expressed by using a closure:

def cacheMap = [:]
Long expensiveMethod( Long a ) {
  withCache (a) {
    // Very expensive operation
    ...
  }
}

def withCache = { key, Closure operation ->
  if (!cacheMap.containsKey(key)) {
    cacheMap[key] = operation()
  }
  cacheMap.get(key)
}

The caching AST transformation will be based on the less elegant code, except that it will be implemented as an annotation. Furthermore, in this recipe, we show different ways to manipulate the AST.

Before we begin, we will create a simple Gradle build (see the Integrating Groovy into the build process using Gradle recipe in Chapter 2, Using Groovy Ecosystem) to hold our code together and help with the test. In a new folder, touch a build.gradle file and add the following content:

apply plugin: 'groovy'

repositories { mavenCentral() }

dependencies {
  compile localGroovy()
  testCompile 'junit:junit:4.+'
}

Create the following folder structure in the same folder where the build file resides:

src/main/groovy/org/groovy/cookbook/

src/test/groovy/org/groovy/cookbook/

Groovy local AST transformations are based on Java annotations. The first step is to write the code for an annotation that we will use on any method for which the return value is cached:

From the output, it is clearly visible how the first method took almost four seconds to execute, while the second and third invocations executed instantaneously thanks to the caching annotation.

Let's start by taking a look at the annotation declared in step 1. The RetentionPolicy is set to SOURCE, which means that the compiler will discard the annotation; after all it is not needed at runtime. This annotation can be only used at the METHOD level because we want only certain methods to cache the result and not the whole class.

The last annotation's attribute is @GroovyASTTransformationClass. The value is set to the actual source code of the transformation we wish to implement.

The code for the AST transformation in step 2 is not very easy to follow, and we are going to analyze it step-by-step. The CacheableTransformation class used in this recipe uses two different styles of abstract syntax tree modification:

An AST transformation class must implement ASTTransformation. The class itself must also be annotated with the @GroovyASTTransformation.

Following the class declaration, we find some sanity checks, which will exit the transformation if some conditions are true. This should never happen, but it is better to exercise some defensive programming style with AST transformations. The expression assigned to a cacheField variable does create a private Map variable named after the annotated method. For example, consider the following snippet:

@Cacheable
Long veryExpensive(Long a) { ... }

The cacheField variable will be named cache_veryExpensive, as the annotated method is named veryExpensive.

As you can notice, the AST API expression, which is required to create a statement as simple as private Map cache_veryExpensive = [:], is indeed quite complex, and it requires a deep knowledge of the org.codehaus.groovy.ast package. Imagine what the statement would look like for something more complex. There is no abstraction over the AST, and the code to create the AST doesn't remotely resemble the Groovy code we are trying to execute.

In order to facilitate manually writing AST code, we can take a little shortcut in the shape of groovyConsole. Let's fire up groovyConsole and type into the main window:

class MyClass {
  private final Map m = [:]
}

Select the Script menu and click on Inspect AST. A new window should pop-up. Then select Semantic Analysis phase in the drop-down list and expand the Fields node and its sub-elements to show the classes required to define the Map variable using AST.

The AST inspector can be used as a guide to instantiate the right classes. Even with the help of the AST inspector, building AST code by hand is not trivial, and the resulting code is not easy to maintain.

Let's move on to the next statements:

Statement oldReturnStatement = methodCode.statements.last()
def ex = oldReturnStatement.expression

These two lines are required to extract the return statement in the annotated function. We are going to need it later.

def stats = """
  def cached = cache_${cachedFieldName}.get(${parameterName})
  if (cached) {
    return cached
  }
"""
List<ASTNode> checkMap = new AstBuilder().
                           buildFromString(
                             CompilePhase.SEMANTIC_ANALYSIS,
                             true,
                             stats
                           )

The second style of AST manipulation uses the org.code.codehaus.groovy.ast.builder.AstBuilder class, written by Hamlet D'Arcy, to ease the pain of creating an AST. The class provides three ways of building an AST. The three methodologies allow you to create Groovy code:

In the previous code snippet, the buildFromString method is used. With this approach, you can use any string containing valid Groovy code to build an AST. Alternatively, with buildFromCode, you can pass the Groovy source code directly, instead of a string. The buildFromCode method approach has some strengths and weaknesses. The code is automatically validated by the compiler when it is passed as a closure.

On the other hand, certain operations that are available by using buildFromString are not possible with buildFromCode; for example, creating a new class or binding data from the enclosing context. The stats variable contains the first part of the code that we want to add to an annotated method before the method body is invoked. The buildFromString method takes three arguments:

The second part of our caching transformation uses the buildFromSpec method approach to finalize the caching behavior. The buildFromSpec method uses a thin DSL on top of the ASTNode API. The reason we switched from buildFromString to buildFromSpec is the following code statement:

expression {
  declaration {
    variable "localCalculated_$cachedFieldName"
    token '='
    { -> delegate.expression << ex }()
  }
}

This DSL entry assigns the body of the return statement (the ex variable declared earlier) to a local variable named localCalculated_$cachedFieldName. This would be impossible to achieve using buildFromString because the ex variable would not be accessible from within the string.

The last lines of the transformation are used to assign the newly created statements to the function's body.

The statements in the last part of the visit function are used to:

Let's look at how a function annotated with the @Cacheable annotation gets modified. Here, is the original function:

@Cacheable
Long veryExpensive(Long a) {
  callVerySlowMethod(a)
}

Here is the modified one:

private Map cache = [:]
Long veryExpensive(Long a) {
  def cached = cache.get(a)
  if (cached) {
    return cached
  }
  localCalculated = callVerySlowMethod(a)
  localCalculated.put(localCalculated)
  localCalculated
}

The caching done by the transformation is not very sophisticated, but for the sake of brevity and to alleviate an already intricate topic, we have simplified the code a bit.