Metaprogramming

If you only need to decorate an existing metaclass the DelegatingMetaClass simplifies that use case. The old metaclass implementation is still accessible via super making it easy to apply pretransformations to the inputs, routing to other methods and postprocessing the outputs.

It is possible to change the metaclass at startup time by giving the metaclass a specially crafted (magic) class name and package name. In order to change the metaclass for java.lang.Integer it’s enough to put a class groovy.runtime.metaclass.java.lang.IntegerMetaClass in the classpath. This is useful, for example, when working with frameworks if you want to do metaclass changes before your code is executed by the framework. The general form of the magic package is groovy.runtime.metaclass.[package].[class]MetaClass. In the example below the [package] is java.lang and the [class] is Integer:

By compiling the above file with groovyc IntegerMetaClass.groovy a ./groovy/runtime/metaclass/java/lang/IntegerMetaClass.class will be generated. The example below will use this new metaclass:

By running that file with groovy -cp . testInteger.groovy the IntegerMetaClass will be in the classpath and therefore it will become the metaclass for java.lang.Integer intercepting the method calls to isBiggerThan*() methods.

Once the ExpandoMetaClass is accessed by calling the metaClass property, methods can be added by using either the left shift << or the = operator.

The operators are applied on a non-existent property of metaClass passing an instance of a Closure code block.

The example above shows how a new method can be added to a class by accessing the metaClass property and using the << or = operator to assign a Closure code block. The Closure parameters are interpreted as method parameters. Parameterless methods can be added by using the {→ …​} syntax.

ExpandoMetaClass supports two mechanisms for adding or overriding properties.

Firstly, it has support for declaring a mutable property by simply assigning a value to a property of metaClass:

Another way is to add getter and/or setter methods by using the standard mechanisms for adding instance methods.

In the source code example above the property is dictated by the closure and is a read-only property. It is feasible to add an equivalent setter method but then the property value needs to be stored for later usage. This could be done as shown in the following example.

This is not the only technique however. For example in a servlet container one way might be to store the values in the currently executing request as request attributes (as is done in some cases in Grails).

Constructors can be added by using a special constructor property. Either the << or = operator can be used to assign a Closure code block. The Closure arguments will become the constructor arguments when the code is executed at runtime.

Static methods can be added using the same technique as instance methods with the addition of the static qualifier before the method name.

With ExpandoMetaClass it is possible to use Groovy’s method pointer syntax to borrow methods from other classes.

Since Groovy allows you to use Strings as property names this in turns allows you to dynamically create method and property names at runtime. To create a method with a dynamic name simply use the language feature of reference property names as strings.

The same concept can be applied to static methods and properties.

One application of dynamic method names can be found in the Grails web application framework. The concept of "dynamic codecs" is implemented by using dynamic method names.

The example above shows a codec implementation. Grails comes with various codec implementations each defined in a single class. At runtime there will be multiple codec classes in the application classpath. At application startup the framework adds a encodeXXX and a decodeXXX method to certain metaclasses where XXX is the first part of the codec class name (e.g. encodeHTML). This mechanism is in the following shown in some Groovy pseudocode:

At runtime it is often useful to know what other methods or properties exist at the time the method is executed. ExpandoMetaClass provides the following methods as of this writing:

Why can’t you just use reflection? Well because Groovy is different, it has the methods that are "real" methods and methods that are available only at runtime. These are sometimes (but not always) represented as MetaMethods. The MetaMethods tell you what methods are available at runtime, thus your code can adapt.

This is of particular use when overriding invokeMethod, getProperty and/or setProperty.

Another feature of ExpandoMetaClass is that it allows to override the methods invokeMethod, getProperty and setProperty, all of them can be found in the groovy.lang.GroovyObject class.

The following example shows how to override invokeMethod:

The first step in the Closure code is to look up the MetaMethod for the given name and arguments. If the method can be found everything is fine and it is delegated to. If not, a dummy value is returned.

The same logic can be used to override setProperty or getProperty.

The important thing to note here is that instead of a MetaMethod a MetaProperty instance is looked up. If that exists the getProperty method of the MetaProperty is called, passing the delegate.

ExpandoMetaClass even allows for overriding static method with a special invokeMethod syntax.

The logic that is used for overriding the static method is the same as we’ve seen before for overriding instance methods. The only difference is the access to the metaClass.static property and the call to getStaticMethodName for retrieving the static MetaMethod instance.

It is possible to add methods onto interfaces with ExpandoMetaClass. To do this however, it must be enabled globally using the ExpandoMetaClass.enableGlobally() method before application start-up.

The @ToString AST transformation generates a human-readable toString representation of the class. For example, annotating the Person class like below will automatically generate the toString method for you:

With this definition, then the following assertion passes, meaning that a toString method taking the field values from the class and printing them out has been generated:

The @ToString annotation accepts several parameters which are summarized in the following table:

The @EqualsAndHashCode AST transformation aims at generating equals and hashCode methods for you. The generated hashcode follows the best practices as described in Effective Java by Josh Bloch:

There are several options available to tweak the behavior of @EqualsAndHashCode:

The @TupleConstructor annotation aims at eliminating boilerplate code by generating constructors for you. A tuple constructor is created having a parameter for each property (and possibly each field). Each parameter has a default value (using the initial value of the property if present or otherwise Java’s default value according to the properties type).

Normally you don’t need to understand the implementation details of the generated constructor(s); you just use them in the normal way. However, if you want to add multiple constructors, understand Java integration options or meet requirements of some dependency injection frameworks, then some details are useful.

As previously mentioned, the generated constructor has default values applied. In later compilation phases, the Groovy compiler’s standard default value processing behavior is then applied. The end result is that multiple constructors are placed within the bytecode of your class. This provides a well understood semantics and is also useful for Java integration purposes. As an example, the following code will generate 3 constructors:

The first constructor is a no-arg constructor which allows the traditional map-style construction so long as you don’t have final properties. Groovy calls the no-arg constructor and then the relevant setters under the covers. It is worth noting that if the first property (or field) has type LinkedHashMap or if there is a single Map, AbstractMap or HashMap property (or field), then the map-style named arguments won’t be available.

The other constructors are generated by taking the properties in the order they are defined. Groovy will generate as many constructors as there are properties (or fields, depending on the options).

Setting the defaults attribute (see the available configuration options table) to false, disables the normal default values behavior which means:

This attribute is normally only used in situations where another Java framework is expecting exactly one constructor, e.g. injection frameworks or JUnit parameterized runners.

If the @PropertyOptions annotation is also found on the class with the @TupleConstructor annotation, then the generated constructor may contain custom property handling logic. The propertyHandler attribute on the @PropertyOptions annotation could for instance be set to ImmutablePropertyHandler which will result in the addition of the necessary logic for immutable classes (defensive copy in, cloning, etc.). This normally would happen automatically behind the scenes when you use the @Immutable meta-annotation. Some of the annotation attributes might not be supported by all property handlers.

The @TupleConstructor AST transformation accepts several annotation attributes:

Setting the defaults annotation attribute to false and the force annotation attribute to true allows multiple tuple constructors to be created by using different customization options for the different cases (provided each case has a different type signature) as shown in the following example:

Similarly, here is another example using different options for includes:

The @MapConstructor annotation aims at eliminating boilerplate code by generating a map constructor for you. A map constructor is created such that each property in the class is set based on the value in the supplied map having the key with the name of the property. Usage is as shown in this example:

The generated constructor will be roughly like this:

The @Canonical meta-annotation combines the @ToString, @EqualsAndHashCode and @TupleConstructor annotations:

A similar immutable class can be generated using the @Immutable meta-annotation instead. The @Canonical meta-annotation supports the configuration options found in the annotations it aggregates. See those annotations for more details.

The @Canonical meta-annotation can be used in conjunction with an explicit use one or more of its component annotations, like this:

Any applicable annotation attributes from @Canonical are passed along to the explicit annotation but attributes already existing in the explicit annotation take precedence.

The @InheritConstructor AST transformation aims at generating constructors matching super constructors for you. This is in particular useful when overriding exception classes:

The @InheritConstructor AST transformation supports the following configuration options:

The @Category AST transformation simplifies the creation of Groovy categories. Historically, a Groovy category was written like this:

The @Category transformation lets you write the same using an instance-style class, rather than a static class style. This removes the need for having the first argument of each method being the receiver. The category can be written like this:

Note that the mixed in class can be referenced using this instead. It’s also worth noting that using instance fields in a category class is inherently unsafe: categories are not stateful (like traits).

The @IndexedProperty annotation aims at generating indexed getters/setters for properties of list/array types. This is in particular useful if you want to use a Groovy class from Java. While Groovy supports GPath to access properties, this is not available from Java. The @IndexedProperty annotation will generate indexed properties of the following form:

The @Lazy AST transformation implements lazy initialization of fields. For example, the following code:

will produce the following code:

The default value which is used to initialize the field is the default constructor of the declaration type. It is possible to define a default value by using a closure on the right hand side of the property assignment, as in the following example:

In that case, the generated code looks like the following:

If the field is declared volatile then initialization will be synchronized using the double-checked locking pattern.

Using the soft=true parameter, the helper field will use a SoftReference instead, providing a simple way to implement caching. In that case, if the garbage collector decides to collect the reference, initialization will occur the next time the field is accessed.

The @Newify AST transformation is used to bring alternative syntaxes to construct objects:

The Ruby version can be disabled by setting the auto flag to false.

The @Sortable AST transformation is used to help write classes that are Comparable and easily sorted typically by numerous properties. It is easy to use as shown in the following example where we annotate the Person class:

The generated class has the following properties:

The generated compareTo method will look like this:

As an example of the generated comparators, the comparatorByFirst comparator will have a compare method that looks like this:

The Person class can be used wherever a Comparable is expected and the generated comparators wherever a Comparator is expected as shown by these examples:

Normally, all properties are used in the generated compareTo method in the priority order in which they are defined. You can include or exclude certain properties from the generated compareTo method by giving a list of property names in the includes or excludes annotation attributes. If using includes, the order of the property names given will determine the priority of properties when comparing. To illustrate, consider the following Person class definition:

It will have two comparator methods comparatorByFirst and comparatorByBorn and the generated compareTo method will look like this:

This Person class can be used as follows:

The behavior of the @Sortable AST transformation can be further changed using the following additional parameters:

The @Builder AST transformation is used to help write classes that can be created using fluent api calls. The transform supports multiple building strategies to cover a range of cases and there are a number of configuration options to customize the building process. If you’re an AST hacker, you can also define your own strategy class. The following table lists the available strategies that are bundled with Groovy and the configuration options each strategy supports.

To use the SimpleStrategy, annotate your Groovy class using the @Builder annotation, and specify the strategy as shown in this example:

Then, just call the setters in a chained fashion as shown here:

For each property, a generated setter will be created which looks like this:

You can specify a prefix as shown in this example:

And calling the chained setters would look like this:

You can use the SimpleStrategy in conjunction with @TupleConstructor. If your @Builder annotation doesn’t have explicit includes or excludes annotation attributes but your @TupleConstructor annotation does, the ones from @TupleConstructor will be re-used for @Builder. The same applies for any annotation aliases which combine @TupleConstructor such as @Canonical.

The annotation attribute useSetters can be used if you have a setter which you want called as part of the construction process. See the JavaDoc for details.

The annotation attributes builderClassName, buildMethodName, builderMethodName, forClass and includeSuperProperties are not supported for this strategy.

To use the ExternalStrategy, create and annotate a Groovy builder class using the @Builder annotation, specify the class the builder is for using forClass and indicate use of the ExternalStrategy. Suppose you have the following class you would like a builder for:

you explicitly create and use your builder class as follows:

Note that the (normally empty) builder class you provide will be filled in with appropriate setters and a build method. The generated build method will look something like:

The class you are creating the builder for can be any Java or Groovy class following the normal JavaBean conventions, e.g. a no-arg constructor and setters for the properties. Here is an example using a Java class:

The generated builder can be customised using the prefix, includes, excludes and buildMethodName annotation attributes. Here is an example illustrating various customisations:

The builderMethodName and builderClassName annotation attributes for @Builder aren’t applicable for this strategy.

You can use the ExternalStrategy in conjunction with @TupleConstructor. If your @Builder annotation doesn’t have explicit includes or excludes annotation attributes but the @TupleConstructor annotation of the class you are creating the builder for does, the ones from @TupleConstructor will be re-used for @Builder. The same applies for any annotation aliases which combine @TupleConstructor such as @Canonical.

To use the DefaultStrategy, annotate your Groovy class using the @Builder annotation as shown in this example:

If you want, you can customize various aspects of the building process using the builderClassName, buildMethodName, builderMethodName, prefix, includes and excludes annotation attributes, some of which are used in the example here:

This strategy also supports annotating static methods and constructors. In this case, the static method or constructor parameters become the properties to use for building purposes and in the case of static methods, the return type of the method becomes the target class being built. If you have more than one @Builder annotation used within a class (at either the class, method or constructor positions) then it is up to you to ensure that the generated helper classes and factory methods have unique names (i.e. no more than one can use the default name values). Here is an example highlighting method and constructor usage (and also illustrating the renaming required for unique names).

The forClass annotation attribute is not supported for this strategy.

To use the InitializerStrategy, annotate your Groovy class using the @Builder annotation, and specify the strategy as shown in this example:

Your class will be locked down to have a single public constructor taking a "fully set" initializer. It will also have a factory method to create the initializer. These are used as follows:

Any attempt to use the initializer which doesn’t involve setting all the properties (though order is not important) will result in a compilation error. If you don’t need this level of strictness, you don’t need to use @CompileStatic.

You can use the InitializerStrategy in conjunction with @Canonical and @Immutable. If your @Builder annotation doesn’t have explicit includes or excludes annotation attributes but your @Canonical annotation does, the ones from @Canonical will be re-used for @Builder. Here is an example using @Builder with @Immutable:

The annotation attribute useSetters can be used if you have a setter which you want called as part of the construction process. See the JavaDoc for details.

This strategy also supports annotating static methods and constructors. In this case, the static method or constructor parameters become the properties to use for building purposes and in the case of static methods, the return type of the method becomes the target class being built. If you have more than one @Builder annotation used within a class (at either the class, method or constructor positions) then it is up to you to ensure that the generated helper classes and factory methods have unique names (i.e. no more than one can use the default name values). For an example of method and constructor usage but using the DefaultStrategy strategy, consult that strategy’s documentation.

The annotation attribute forClass is not supported for this strategy.

The @AutoImplement AST transformation supplies dummy implementations for any found abstract methods from superclasses or interfaces. The dummy implementation is the same for all abstract methods found and can be:

The first example illustrates the default case. Our class is annotated with @AutoImplement, has a superclass and a single interface as can be seen here:

A void close() method from the Closeable interface is supplied and left empty. Implementations are also supplied for the three abstract methods from the super class. The get, addAll and size methods have return types of String, boolean and int respectively with default values null, false and 0. We can use our class (and check the expected return type for one of the methods) using the following code:

It is also worthwhile examining the equivalent generated code:

The second example illustrates the simplest exception case. Our class is annotated with @AutoImplement, has a superclass and an annotation attribute indicates that an IOException should be thrown if any of our "dummy" methods are called. Here is the class definition:

We can use the class (and check the expected exception is thrown for one of the methods) using the following code:

It is also worthwhile examining the equivalent generated code where three void methods have been provided all of which throw the supplied exception:

The third example illustrates the exception case with a supplied message. Our class is annotated with @AutoImplement, implements an interface, and has annotation attributes to indicate that an UnsupportedOperationException with Not supported by MyIterator as the message should be thrown for any supplied methods. Here is the class definition:

We can use the class (and check the expected exception is thrown and has the correct message for one of the methods) using the following code:

It is also worthwhile examining the equivalent generated code where three void methods have been provided all of which throw the supplied exception:

The fourth example illustrates the case of user supplied code. Our class is annotated with @AutoImplement, implements an interface, has an explicitly overridden hasNext method, and has an annotation attribute containing the supplied code for any supplied methods. Here is the class definition:

We can use the class (and check the expected exception is thrown and has a message of the expected form) using the following code:

It is also worthwhile examining the equivalent generated code where the next method has been supplied:

The @NullCheck AST transformation adds null-check guard statements to constructors and methods which cause those methods to fail early when supplied with null arguments. It can be seen as a form of defensive programming. The annotation can be added to individual methods or constructors, or to the class in which case it will apply to all methods/constructors.

@BaseScript is used within scripts to indicate that the script should extend from a custom script base class rather than groovy.lang.Script. See the documentation for domain specific languages for further details.

The @Delegate AST transformation aims at implementing the delegation design pattern. In the following class:

The when property is annotated with @Delegate, meaning that the Event class will delegate calls to Date methods to the when property. In this case, the generated code looks like this:

Then you can call the before method, for example, directly on the Event class:

Instead of annotating a property (or field), you can also annotate a method. In this case, the method can be thought of as a getter or factory method for the delegate. As an example, here is a class which (rather unusually) has a pool of delegates which are accessed in a round-robin fashion:

Here is an example usage of that class:

Using a standard list in this round-robin fashion would violate many expected properties of lists, so don’t expect the above class to do anything useful beyond this trivial example.

The behavior of the @Delegate AST transformation can be changed using the following parameters:

The @Immutable meta-annotation combines the following annotations:

The @Immutable meta-annotation simplifies the creation of immutable classes. Immutable classes are useful since they are often easier to reason about and are inherently thread-safe. See Effective Java, Minimize Mutability for all the details about how to achieve immutable classes in Java. The @Immutable meta-annotation does most of the things described in Effective Java for you automatically. To use the meta-annotation, all you have to do is annotate the class like in the following example:

One of the requirements for immutable classes is that there is no way to modify any state information within the class. One requirement to achieve this is to use immutable classes for each property or alternatively perform special coding such as defensive copy in and defensive copy out for any mutable properties within the constructors and property getters. Between @ImmutableBase, @MapConstructor and @TupleConstructor properties are either identified as immutable or the special coding for numerous known cases is handled automatically. Various mechanisms are provided for you to extend the handled property types which are allowed. See @ImmutableOptions and @KnownImmutable for details.

The results of applying @Immutable to a class are pretty similar to those of applying the @Canonical meta-annotation but the generated class will have extra logic to handle immutability. You will observe this by, for instance, trying to modify a property which will result in a ReadOnlyPropertyException being thrown since the backing field for the property will have been automatically made final.

The @Immutable meta-annotation supports the configuration options found in the annotations it aggregates. See those annotations for more details.

Immutable classes generated with @ImmutableBase are automatically made final. Also, the type of each property is checked and various checks are made on the class, for example, public instance fields currently aren’t allowed. It also generates a copyWith constructor if desired.

The following annotation attribute is supported:

This annotation allows you to specify a custom property handler to be used by transformations during class construction. It is ignored by the main Groovy compiler but is referenced by other transformations like @TupleConstructor, @MapConstructor, and @ImmutableBase. It is frequently used behind the scenes by the @Immutable meta-annotation.

This annotation allows you to specify a custom visibility for a construct generated by another transformation. It is ignored by the main Groovy compiler but is referenced by other transformations like @TupleConstructor, @MapConstructor, and @NamedVariant.

Groovy’s immutability support relies on a predefined list of known immutable classes (like java.net.URI or java.lang.String and fails if you use a type which is not in that list, you are allowed to add to the list of known immutable types thanks to the following annotation attributes of the @ImmutableOptions annotation:

If you deem a type as immutable and it isn’t one of the ones automatically handled, then it is up to you to correctly code that class to ensure immutability.

The @KnownImmutable annotation isn’t actually one that triggers any AST transformations. It is simply a marker annotation. You can annotate your classes with the annotation (including Java classes) and they will be recognized as acceptable types for members within an immutable class. This saves you having to explicitly use the knownImmutables or knownImmutableClasses annotation attributes from @ImmutableOptions.

The @Memoized AST transformations simplifies the implementation of caching by allowing the result of method calls to be cached just by annotating the method with @Memoized. Let’s imagine the following method:

This emulates a long computation, based on the actual parameters of the method. Without @Memoized, each method call would take several seconds plus it would return a random result:

Adding @Memoized changes the semantics of the method by adding caching, based on the parameters:

The size of the cache can be configured using two optional parameters:

By default, the size of the cache is unlimited and no cache result is protected from garbage collection. Setting a protectedCacheSize>0 would create an unlimited cache with some results protected. Setting maxCacheSize>0 would create a limited cache but without any protection from garbage protection. Setting both would create a limited, protected cache.

The @TailRecursive annotation can be used to automatically transform a recursive call at the end of a method into an equivalent iterative version of the same code. This avoids stack overflow due to too many recursive calls. Below is an example of use when calculating factorial:

Currently, the annotation will only work for self-recursive method calls, i.e. a single recursive call to the exact same method again. Consider using Closures and trampoline() if you have a scenario involving simple mutual recursion. Also note that only non-void methods are currently handled (void calls will result in a compilation error).

The @Singleton annotation can be used to implement the singleton design pattern on a class. The singleton instance is defined eagerly by default, using class initialization, or lazily, in which case the field is initialized using double-checked locking.

By default, the singleton is created eagerly when the class is initialized and available through the instance property. It is possible to change the name of the singleton using the property parameter:

And it is also possible to make initialization lazy using the lazy parameter:

In this example, we also set the strict parameter to false, which allows us to define our own constructor.

Deprecated. Consider using traits instead.

The first logging AST transformation available is the @Log annotation which relies on the JDK logging framework. Writing:

is equivalent to writing:

Groovy supports the Apache Commons Logging framework using the @Commons annotation. Writing:

is equivalent to writing:

You still need to add the appropriate commons-logging jar to your classpath.

Groovy supports the Apache Log4j 1.x framework using the @Log4j annotation. Writing:

is equivalent to writing:

You still need to add the appropriate log4j jar to your classpath. This annotation can also be used with the compatible reload4j log4j drop-in replacement, just use the jar from that project instead of a log4j jar.

Groovy supports the Apache Log4j 2.x framework using the @Log4j2 annotation. Writing:

is equivalent to writing:

You still need to add the appropriate log4j2 jar to your classpath.

Groovy supports the Simple Logging Facade for Java (SLF4J) framework using the @Slf4j annotation. Writing:

is equivalent to writing:

You still need to add the appropriate slf4j jar(s) to your classpath.

Groovy supports the Java Platform Logging API and Service framework using the @PlatformLog annotation. Writing:

is equivalent to writing:

You need to be using JDK 9+ to use this capability.

The @Synchronized AST transformations works in a similar way to the synchronized keyword but locks on different objects for safer concurrency. It can be applied on any method or static method:

Writing this is equivalent to creating a lock object and wrapping the whole method into a synchronized block:

By default, @Synchronized creates a field named $lock (or $LOCK for a static method) but you can make it use any field you want by specifying the value attribute, like in the following example:

The @WithReadLock AST transformation works in conjunction with the @WithWriteLock transformation to provide read/write synchronization using the ReentrantReadWriteLock facility that the JDK provides. The annotation can be added to a method or a static method. It will transparently create a $reentrantLock final field (or $REENTRANTLOCK for a static method) and proper synchronization code will be added. For example, the following code:

is equivalent to this:

Both @WithReadLock and @WithWriteLock support specifying an alternative lock object. In that case, the referenced field must be declared by the user, like in the following alternative:

For details

The @AutoClone annotation is aimed at implementing the @java.lang.Cloneable interface using various strategies, thanks to the style parameter:

Each of those strategies have pros and cons which are discussed in the Javadoc for groovy.transform.AutoClone and groovy.transform.AutoCloneStyle .

For example, the following example:

is equivalent to this:

Note that the String properties aren’t explicitly handled because Strings are immutable and the clone() method from Object will copy the String references. The same would apply to primitive fields and most of the concrete subclasses of java.lang.Number.

In addition to cloning styles, @AutoClone supports multiple options:

The @AutoExternalize AST transformation will assist in the creation of java.io.Externalizable classes. It will automatically add the interface to the class and generate the writeExternal and readExternal methods. For example, this code:

will be converted into:

The @AutoExternalize annotation supports two parameters which will let you slightly customize its behavior:

One complicated situation in the JVM world is when a thread can’t be stopped. The Thread#stop method exists but is deprecated (and isn’t reliable) so your only chance lies in Thread#interrupt. Calling the latter will set the interrupt flag on the thread, but it will not stop the execution of the thread. This is problematic because it’s the responsibility of the code executing in the thread to check the interrupt flag and properly exit. This makes sense when you, as a developer, know that the code you are executing is meant to be run in an independent thread, but in general, you don’t know it. It’s even worse with user scripts, who might not even know what a thread is (think of DSLs).

@ThreadInterrupt simplifies this by adding thread interruption checks at critical places in the code:

Let’s imagine the following user script:

This is an obvious infinite loop. If this code executes in its own thread, interrupting wouldn’t help: if you join on the thread, then the calling code would be able to continue, but the thread would still be alive, running in background without any ability for you to stop it, slowly causing thread starvation.

One possibility to work around this is to set up your shell this way:

The shell is then configured to automatically apply the @ThreadInterrupt AST transformations on all scripts. This allows you to execute user scripts this way:

The transformation automatically modified user code like this:

The check which is introduced inside the loop guarantees that if the interrupt flag is set on the current thread, an exception will be thrown, interrupting the execution of the thread.

@ThreadInterrupt supports multiple options that will let you further customize the behavior of the transformation:

The @TimedInterrupt AST transformation tries to solve a slightly different problem from @groovy.transform.ThreadInterrupt: instead of checking the interrupt flag of the thread, it will automatically throw an exception if the thread has been running for too long.

Imagine the following user code:

The implementation of the famous Fibonacci number computation here is far from optimized. If it is called with a high n value, it can take minutes to answer. With @TimedInterrupt, you can choose how long a script is allowed to run. The following setup code will allow the user script to run for 1 second at max:

This code is equivalent to annotating a class with @TimedInterrupt like this:

@TimedInterrupt supports multiple options that will let you further customize the behavior of the transformation:

The last annotation for safer scripting is the base annotation when you want to interrupt a script using a custom strategy. In particular, this is the annotation of choice if you want to use resource management (limit the number of calls to an API, …​). In the following example, user code is using an infinite loop, but @ConditionalInterrupt will allow us to check a quota manager and interrupt automatically the script:

The quota checking is very basic here, but it can be any code:

We can make sure @ConditionalInterrupt works properly using this test code:

Of course, in practice, it is unlikely that @ConditionalInterrupt will be itself added by hand on user code. It can be injected in a similar manner as the example shown in the ThreadInterrupt section, using the org.codehaus.groovy.control.customizers.ASTTransformationCustomizer :

@ConditionalInterrupt supports multiple options that will let you further customize the behavior of the transformation:

The @Field annotation only makes sense in the context of a script and aims at solving a common scoping error with scripts. The following example will for example fail at runtime:

The error that is thrown may be difficult to interpret: groovy.lang.MissingPropertyException: No such property: x. The reason is that scripts are compiled to classes and the script body is itself compiled as a single run() method. Methods which are defined in the scripts are independent, so the code above is equivalent to this:

So def x is effectively interpreted as a local variable, outside of the scope of the line method. The @Field AST transformation aims at fixing this by changing the scope of the variable to a field of the enclosing script:

The resulting, equivalent, code is now:

By default, Groovy visibility rules imply that if you create a field without specifying a modifier, then the field is interpreted as a property:

Should you want to create a package private field instead of a property (private field+getter/setter), then annotate your field with @PackageScope:

The @PackageScope annotation can also be used for classes, methods and constructors. In addition, by specifying a list of PackageScopeTarget values as the annotation attribute at the class level, all members within that class that don’t have an explicit modifier and match the provided PackageScopeTarget will remain package protected. For example to apply to fields within a class use the following annotation:

The @PackageScope annotation is seldom used as part of normal Groovy conventions but is sometimes useful for factory methods that should be visible internally within a package or for methods or constructors provided for testing purposes, or when integrating with third-party libraries which require such visibility conventions.

@Final is essentially an alias for the final modifier. The intention is that you would almost never use the @Final annotation directly (just use final). However, when creating meta-annotations that should apply the final modifier to the node being annotated, you can mix in @Final, e.g..

The @AutoFinal annotation instructs the compiler to automatically insert the final modifier in numerous places within the annotated node. If applied on a method (or constructor), the parameters for that method (or constructor) will be marked as final. If applied on a class definition, the same treatment will occur for all declared methods and constructors within that class.

It is often considered bad practice to reassign parameters of a method or constructor with its body. By adding the final modifier to all parameter declarations you can avoid this practice entirely. Some programmers feel that adding final everywhere increases the amount of boilerplate code and makes the method signatures somewhat noisy. An alternative might instead be to use a code review process or apply a codenarc rule to give warnings if that practice is observed but these alternatives might lead to delayed feedback during quality checking rather than within the IDE or during compilation. The @AutoFinal annotation aims to maximise compiler/IDE feedback while retaining succinct code with minimum boilerplate noise.

The following example illustrates applying the annotation at the class level:

In this example, the two parameters for the constructor and the single parameter for both the fullname and greeting methods will be final. Attempts to modify those parameters within the constructor or method bodies will be flagged by the compiler.

The following example illustrates applying the annotation at the method level:

Here, the add method will have final parameters but the mult method will remain unchanged.

@AnnotationCollector allows the creation of meta-annotations, which are described in a dedicated section.

@TypeChecked activates compile-time type checking on your Groovy code. See section on type checking for details.

@CompileStatic activates static compilation on your Groovy code. See section on type checking for details.

@CompileDynamic disables static compilation on parts of your Groovy code. See section on type checking for details.

@DelegatesTo is not, technically speaking, an AST transformation. It is aimed at documenting code and helping the compiler in case you are using type checking or static compilation. The annotation is described thoroughly in the DSL section of this guide.

@SelfType is not an AST transformation but rather a marker interface used with traits. See the traits documentation for further details.

@Bindable is an AST transformation that transforms a regular property into a bound property (according to the JavaBeans specification). The @Bindable annotation can be placed on a property or a class. To convert all properties of a class into bound properties, on can annotate the class like in this example:

This is equivalent to writing this:

@Bindable therefore removes a lot of boilerplate from your class, dramatically increasing readability. If the annotation is put on a single property, only that property is bound:

The @ListenerList AST transformation generates code for adding, removing and getting the list of listeners to a class, just by annotating a collection property:

The transform will generate the appropriate add/remove methods based on the generic type of the list. In addition, it will also create fireXXX methods based on the public methods declared on the class:

@Bindable supports multiple options that will let you further customize the behavior of the transformation:

The @Vetoable annotation works in a similar manner to @Bindable but generates constrained property according to the JavaBeans specification, instead of bound properties. The annotation can be placed on a class, meaning that all properties will be converted to constrained properties, or on a single property. For example, annotating this class with @Vetoable:

is equivalent to writing this:

If the annotation is put on a single property, only that property is made vetoable:

@NotYetImplemented is used to invert the result of a JUnit 3/4 test case. It is in particular useful if a feature is not yet implemented but the test is. In that case, it is expected that the test fails. Marking it with @NotYetImplemented will inverse the result of the test, like in this example:

Another advantage of using this technique is that you can write test cases for bugs before knowing how to fix them. If some time in the future, a modification in the code fixes a bug by side effect, you’ll be notified because a test which was expected to fail passed.

@ASTTest is a special AST transformation meant to help debugging other AST transformations or the Groovy compiler itself. It will let the developer "explore" the AST during compilation and perform assertions on the AST rather than on the result of compilation. This means that this AST transformations gives access to the AST before the bytecode is produced. @ASTTest can be placed on any annotable node and requires two parameters:

value is a closure expression which has access to a special variable node corresponding to the annotated node, and a helper lookup method which will be discussed here. For example, you can annotate a class node like this:

One interesting feature of @ASTTest is that if an assertion fails, then compilation will fail. Now imagine that we want to check the behavior of an AST transformation at compile time. We will take @PackageScope here, and we will want to verify that a property annotated with @PackageScope becomes a package private field. For this, we have to know at which phase the transform runs, which can be found in org.codehaus.groovy.transform.PackageScopeASTTransformation : semantic analysis. Then a test can be written like this:

The @ASTTest annotation can only be placed wherever the grammar allows it. Sometimes, you would like to test the contents of an AST node which is not annotable. In this case, @ASTTest provides a convenient lookup method which will search the AST for nodes which are labelled with a special token:

Imagine, for example, that you want to test the declared type of a for loop variable. Then you can do it like this:

@ASTTest also exposes those variables inside the test closure:

The latter is interesting if you don’t specify the phase attribute. In that case, the closure will be executed after each compile phase after (and including) SEMANTIC_ANALYSIS. The context of the transformation is kept after each phase, giving you a chance to check what changed between two phases.

As an example, here is how you could dump the list of AST transformations registered on a class node:

And here is how you can memorize variables for testing between two phases:

Grape is a dependency management engine embedded into Groovy, relying on several annotations which are described thoroughly in this section of the guide.

While you have seen that you can directly implement the ASTTransformation interface, in almost all cases you will not do this but extend the org.codehaus.groovy.transform.AbstractASTTransformation class. This class provides several utility methods that make AST transformations easier to write. Almost all AST transformations included in Groovy extend this class.

It is a common use case to be able to transform an expression into another. Groovy provides a class which makes it very easy to do this: org.codehaus.groovy.ast.ClassCodeExpressionTransformer

To illustrate this, let’s create a @Shout transformation that will transform all String constants in method call arguments into their uppercase version. For example:

should print:

Then the code for the transformation can use the ClassCodeExpressionTransformer to make this easier:

Classes of the Abstract Syntax Tree belong to the org.codehaus.groovy.ast package. It is recommended to the reader to use the Groovy Console, in particular the AST browser tool, to gain knowledge about those classes. However, a good resource for learning is the AST Builder test suite.

Until version 2.5.0, when developing AST transformations, developers should have a deep knowledge about how the AST (Abstract Syntax Tree) was built by the compiler in order to know how to add new expressions or statements during compile time.

Although the use of org.codehaus.groovy.ast.tool.GeneralUtils static methods could mitigate the burden of creating expressions and statements, it’s still a low-level way of writing those AST nodes directly. We needed something to abstract us from writing the AST directly and that’s exactly what Groovy macros were made for. They allow you to directly add code during compilation, without having to translate the code you had in mind to the org.codehaus.groovy.ast.* node related classes.

Let’s see an example, lets create a local AST transformation: @AddMessageMethod. When applied to a given class it will add a new method called getMessage to that class. The method will return "42". The annotation is pretty straight forward:

What would the AST transformation look like without the use of a macro ? Something like this:

If you’re not used to the AST API, that definitely doesn’t look like the code you had in mind. Now look how the previous code simplifies with the use of macros.

Although the macro method is used in this example to create a statement the macro method could also be used to create expressions as well, it depends on which macro signature you use:

Sometimes we could be only interested in creating a given expression, not the whole statement, in order to do that we should use any of the macro invocations with a boolean parameter:

Macros are great but we can’t create anything useful or reusable if our macros couldn’t receive parameters or resolve surrounding variables.

In the following example we’re creating an AST transformation @MD5 that when applied to a given String field will add a method returning the MD5 value of that field.

And the transformation:

As we mentioned earlier, the macro method is only capable of producing statements and expressions. But what if we want to produce other types of nodes, such as a method, a field and so on?

org.codehaus.groovy.macro.transform.MacroClass can be used to create classes (ClassNode instances) in our transformations the same way we created statements and expressions with the macro method before.

The next example is a local transformation @Statistics. When applied to a given class, it will add two methods getMethodCount() and getFieldCount() which return how many methods and fields within the class respectively. Here is the marker annotation.

And the AST transformation:

Basically we’ve created the Statistics class as a template to avoid writing low level AST API, then we copied methods created in the template class to their final destination.

You have seen that by using macro you can save yourself a lot of work but you might wonder where that method came from. You didn’t declare it or static import it. You can think of it as a special global method (or if you prefer, a method on every Object). This is much like how the println extension method is defined. But unlike println which becomes a method selected for execution later in the compilation process, macro expansion is done early in the compilation process. The declaration of macro as one of the available methods for this early expansion is done by annotating a macro method definition with the @Macro annotation and making that method available using a similar mechanism for extension modules. Such methods are known as macro methods and the good news is you can define your own.

To define your own macro method, create a class in a similar way to an extension module and add a method such as:

Now you would register this as an extension module using a org.codehaus.groovy.runtime.ExtensionModule file within the META-INF/groovy directory.

Now, assuming that the class and meta info file are on your classpath, you can use the macro method in the following way:

This section is about good practices in regard to testing AST transformations. Previous sections highlighted the fact that to be able to execute an AST transformation, it has to be precompiled. It might sound obvious but a lot of people get caught on this, trying to use an AST transformation in the same source tree as where it is defined.

The first tip for testing AST transformation is therefore to separate test sources from the sources of the transform. Again, this is nothing but best practices, but you must make sure that your build too does actually compile them separately. This is the case by default with both Apache Maven and Gradle.

It is very handy to be able to put a breakpoint in an AST transformation, so that you can debug your code in the IDE. However, you might be surprised to see that your IDE doesn’t stop on the breakpoint. The reason is actually simple: if your IDE uses the Groovy compiler to compile the unit tests for your AST transformation, then the compilation is triggered from the IDE, but the process which will compile the files doesn’t have debugging options. It’s only when the test case is executed that the debugging options are set on the virtual machine. In short: it is too late, the class has been compiled already, and your transformation is already applied.

A very easy workaround is to use the GroovyTestCase class which provides an assertScript method. This means that instead of writing this in a test case:

You should write:

The difference is that when you use assertScript, the code in the assertScript block is compiled when the unit test is executed. That is to say that this time, the Subject class will be compiled with debugging active, and the breakpoint is going to be hit.

Sometimes you may want to make assertions over AST nodes; perhaps to filter the nodes, or to make sure a given transformation has built the expected AST node.

Filtering nodes

For instance if you would like to apply a given transformation only to a specific set of AST nodes, you could use ASTMatcher to filter these nodes. The following example shows how to transform a given expression to another. Using ASTMatcher it looks for a specific expression 1 + 1 and it transforms it to 3. That’s why we called it the @Joking example.

First we create the @Joking annotation that only can be applied to methods:

Then the transformation, that only applies an instance of org.codehaus.groovy.ast.ClassCodeExpressionTransformer to all the expressions within the method code block.

And this is when the ASTMatcher is used to apply the transformation only to those expressions matching the expression 1 + 1.

Then you could test the implementation as follows:

Unit testing AST transforms

Normally we test AST transformations just checking that the final use of the transformation does what we expect. But it would be great if we could have an easy way to check, for example, that the nodes the transformation adds are what we expected from the beginning.

The following transformation adds a new method giveMeTwo to an annotated class.

Now instead of creating a test executing the transformation over a given sample code. I would like to check that the construction of the binary expression is done properly:

Of course you can/should always check the actual execution:

Last but not least, testing an AST transformation is also about testing the state of the AST during compilation. Groovy provides a tool named @ASTTest for this: it is an annotation that will let you add assertions on an abstract syntax tree. Please check the documentation for ASTTest for more details.