class SomeGroovyClass {    def invokeMethod(String name, Object args) {        return "called invokeMethod $name $args"    }    def test() {        return 'method exists'    }}def someGroovyClass = new SomeGroovyClass()assert someGroovyClass.test() == 'method exists'assert someGroovyClass.someMethod() == 'called invokeMethod someMethod []'

class SomeGroovyClass {    def property1 = 'ha'    def field2 = 'ho'    def field4 = 'hu'    def getField1() {        return 'getHa'    }    def getProperty(String name) {        if (name != 'field3')            return metaClass.getProperty(this, name)(1)        else            return 'field3'    }}def someGroovyClass = new SomeGroovyClass()assert someGroovyClass.field1 == 'getHa'assert someGroovyClass.field2 == 'ho'assert someGroovyClass.field3 == 'field3'assert someGroovyClass.field4 == 'hu'

class POGO {    String property     void setProperty(String name, Object value) {        this.@"$name" = 'overridden'    }}def pogo = new POGO()pogo.property = 'a'assert pogo.property == 'overridden'

// getMetaclasssomeObject.metaClass// setMetaClasssomeObject.metaClass = new OwnMetaClassImplementation()

class Foo {}def f = new Foo()assert f.metaClass =~ /MetaClassImpl/

If you only need to decorate an existing metaclass theDelegatingMetaClass simplifies that use case.The old metaclass implementation is still accessible viasuper making it easy to applypretransformations 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 forjava.lang.Integer it’s enough to put a classgroovy.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 isgroovy.runtime.metaclass.[package].[class]MetaClass. In the example below the[package] isjava.lang and the[class] isInteger:

By compiling the above file withgroovyc 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 withgroovy -cp . testInteger.groovy theIntegerMetaClass will be in the classpath and therefore it will become the metaclass forjava.lang.Integer intercepting the method calls toisBiggerThan*() methods.

class Foo { def bar() { "bar" }}class FooMetaClass extends DelegatingMetaClass {  FooMetaClass(MetaClass metaClass) { super(metaClass) }  Object invokeMethod(Object object, String name, Object[] args) {      super.invokeMethod(object,name,args).toUpperCase()  }}def f1 = new Foo()def f2 = new Foo()f2.metaClass = new FooMetaClass(f2.metaClass)assert f1.bar() == "bar"assert f2.bar() == "BAR"assert f1.metaClass =~ /MetaClassImpl/assert f2.metaClass =~ /FooMetaClass/assert f1.class.toString() == "class Foo"assert f2.class.toString() == "class Foo"

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

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

The example above shows how a new method can be added to a class by accessing themetaClass property and using the<< or= operator to assign aClosure code block. TheClosure 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 amutable property by simply assigning a value to a property ofmetaClass:

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 addan equivalent setter method but then the property value needs to be stored for later usage. This could be done asshown 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 inthe currently executing request as request attributes (as is done in some cases in Grails).

Constructors can be added by using a specialconstructor property. Either the<< or= operator can be usedto assign aClosure code block. TheClosure arguments will become the constructor arguments when the code isexecuted at runtime.

Static methods can be added using the same technique as instance methods with the addition of thestatic qualifierbefore the method name.

WithExpandoMetaClass 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 andproperty names at runtime. To create a method with a dynamic name simply use the language feature of reference propertynames 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 "dynamiccodecs" 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 addsaencodeXXX and adecodeXXX method to certain metaclasses whereXXX 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.ExpandoMetaClassprovides the following methods as of this writing:

• getMetaMethod

• hasMetaMethod

• getMetaProperty

• hasMetaProperty

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

This is of particular use when overridinginvokeMethod,getProperty and/orsetProperty.

Another feature ofExpandoMetaClass is that it allows to override the methodsinvokeMethod,getProperty andsetProperty, all of them can be found in thegroovy.lang.GroovyObject class.

The following example shows how to overrideinvokeMethod:

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

The same logic can be used to overridesetProperty orgetProperty.

The important thing to note here is that instead of aMetaMethod aMetaProperty instance is looked up. If that existsthegetProperty method of theMetaProperty is called, passing the delegate.

ExpandoMetaClass even allows for overriding static method with a specialinvokeMethod syntax.

The logic that is used for overriding the static method is the same as we’ve seen before for overriding instance methods. Theonly difference is the access to themetaClass.static property and the call togetStaticMethodName for retrievingthe staticMetaMethod instance.

It is possible to add methods onto interfaces withExpandoMetaClass. To do this however, itmust be enabledglobally using theExpandoMetaClass.enableGlobally() method before application start-up.

def file = new File(...)def contents = file.getText('utf-8')

public static String getText(File file, String charset) throws IOException { return IOGroovyMethods.getText(newReader(file, charset));}

class MaxRetriesExtension {(1)    static void maxRetries(Integer self, Closure code) {(2)        assert self >= 0        int retries = self        Throwable e = null        while (retries > 0) {            try {                code.call()                break            } catch (Throwable err) {                e = err                retries--            }        }        if (retries == 0 && e) {            throw e        }    }}

int i=05.maxRetries {    i++}assert i == 1i=0try {    5.maxRetries {        i++        throw new RuntimeException("oops")    }} catch (RuntimeException e) {    assert i == 5}

class StaticStringExtension {(1)    static String greeting(String self) {(2)        'Hello, world!'    }}

assert String.greeting() == 'Hello, world!'

moduleName=Test module for specificationsmoduleVersion=1.0-testextensionClasses=support.MaxRetriesExtensionstaticExtensionClasses=support.StaticStringExtension

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

With this definition, then the following assertion passes, meaning that atoString method taking the field values fromthe 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 generatingequals andhashCode methods for you. The generatedhashcode follows the best practices as described inEffective Java byJosh 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 tupleconstructor 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 somedependency 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, thefollowing code will generate 3 constructors:

The first constructor is a no-arg constructor which allows the traditional map-style construction so long asyou 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 asmany constructors as there are properties (or fields, depending on the options).

Setting thedefaults attribute (see the available configuration options table) tofalse, disables the normal default values behavior which means:

• Exactly one constructor will be produced

• Attempting to use an initial value will produce an error

• Map-style named arguments won’t be available

This attribute is normally only used in situations where another Java framework isexpecting 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.ThepropertyHandler attribute on the@PropertyOptions annotation could for instance be set toImmutablePropertyHandler 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 usethe@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 thedefaults annotation attribute tofalse and theforce annotation attribute totrue allowsmultiple 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 forincludes:

The@MapConstructor annotation aims at eliminating boilerplate code by generating a map constructor for you. A mapconstructor is created such that each property in the class is set based on the value in the supplied maphaving 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@TupleConstructorannotations:

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

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

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

The@InheritConstructor AST transformation aims at generating constructors matching super constructors for you. Thisis 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 waswritten 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 likethis:

Note that the mixed in class can be referenced usingthis instead. It’s also worth noting that using instance fieldsin 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 followingform:

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 possibleto define a default value by using a closure on the right hand side of the property assignment, as in the followingexample:

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

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

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

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

• Using thePython style:

• or using theRuby style:

TheRuby version can be disabled by setting theauto flag tofalse.

The@Sortable AST transformation is used to help write classes that areComparable and easily sortedtypically by numerous properties. It is easy to use as shown in the following example where we annotatethePerson class:

The generated class has the following properties:

• it implements theComparable interface

• it contains acompareTo method with an implementation based on the natural ordering of thefirst,last andborn properties

• it has three methods returning comparators:comparatorByFirst,comparatorByLast andcomparatorByBorn.

The generatedcompareTo method will look like this:

As an example of the generated comparators, thecomparatorByFirst comparator will have acompare method that looks like this:

ThePerson class can be used wherever aComparable is expected and the generated comparatorswherever aComparator is expected as shown by these examples:

Normally, all properties are used in the generatedcompareTo method in the priority order in which they are defined.You can include or exclude certain properties from the generatedcompareTo method by giving a list of property namesin theincludes orexcludes annotation attributes. If usingincludes, the order of the property names given willdetermine the priority of properties when comparing. To illustrate, consider the followingPerson class definition:

It will have two comparator methodscomparatorByFirst andcomparatorByBorn and the generatedcompareTo method will look like this:

ThisPerson 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 usingfluent api calls.The transform supports multiple building strategies to cover a range of cases and there are a numberof configuration options to customize the building process. If you’re an AST hacker, you can also define your ownstrategy class. The following table lists the available strategies that are bundled with Groovy and theconfiguration options each strategy supports.

To use theSimpleStrategy, 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 theSimpleStrategy in conjunction with@TupleConstructor. If your@Builderannotation doesn’t have explicitincludes orexcludes annotation attributes but your@TupleConstructorannotation does, the ones from@TupleConstructor will be re-used for@Builder. The same applies for anyannotation aliases which combine@TupleConstructor such as@Canonical.

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

The annotation attributesbuilderClassName,buildMethodName,builderMethodName,forClass andincludeSuperProperties are not supported for this strategy.

To use theExternalStrategy, create and annotate a Groovy builder class using the@Builder annotation, specify theclass the builder is for usingforClass and indicate use of theExternalStrategy.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 theprefix,includes,excludes andbuildMethodName annotation attributes.Here is an example illustrating various customisations:

ThebuilderMethodName andbuilderClassName annotation attributes for@Builder aren’t applicable for this strategy.

You can use theExternalStrategy in conjunction with@TupleConstructor. If your@Builder annotation doesn’t haveexplicitincludes orexcludes annotation attributes but the@TupleConstructor annotation of the class you are creatingthe builder for does, the ones from@TupleConstructor will be re-used for@Builder. The same applies for anyannotation aliases which combine@TupleConstructor such as@Canonical.

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

If you want, you can customize various aspects of the building processusing thebuilderClassName,buildMethodName,builderMethodName,prefix,includes andexcludes 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 constructorparameters become the properties to use for building purposes and in the case of static methods, the return typeof the method becomes the target class being built. If you have more than one@Builder annotation used withina class (at either the class, method or constructor positions) then it is up to you to ensure that the generatedhelper 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).

TheforClass annotation attribute is not supported for this strategy.

To use theInitializerStrategy, 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 ina compilation error. If you don’t need this level of strictness, you don’t need to use@CompileStatic.

You can use theInitializerStrategy in conjunction with@Canonical and@Immutable. If your@Builder annotationdoesn’t have explicitincludes orexcludes annotation attributes but your@Canonical annotation does, the onesfrom@Canonical will be re-used for@Builder. Here is an example using@Builder with@Immutable:

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

This strategy also supports annotating static methods and constructors. In this case, the static method or constructorparameters become the properties to use for building purposes and in the case of static methods, the return typeof the method becomes the target class being built. If you have more than one@Builder annotation used withina class (at either the class, method or constructor positions) then it is up to you to ensure that the generatedhelper 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 theDefaultStrategy strategy, consult that strategy’sdocumentation.

The annotation attributeforClass is not supported for this strategy.

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

• essentially empty (exactly true for void methods and for methods with a return type, returns the default value forthat type)

• a statement that throws a specified exception (with optional message)

• some user supplied code

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:

Avoid close() method from theCloseable interface is supplied and left empty. Implementations are also suppliedfor the three abstract methods from the super class. Theget,addAll andsize methodshave return types ofString,boolean andint respectively with default valuesnull,false and0. We can use our class (and check the expected return type for oneof 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 anIOException should be thrown if any ofour "dummy" methods are called. Here is the class definition:

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

It is also worthwhile examining the equivalent generated code where three void methodshave 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 anUnsupportedOperationException withNot 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 messagefor one of the methods) using the following code:

It is also worthwhile examining the equivalent generated code where three void methodshave 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 overriddenhasNext method, and has an annotation attribute containing thesupplied 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 thenext method has been supplied:

The@NullCheck AST transformation adds null-check guard statements to constructors and methodswhich 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 classin which case it will apply to all methods/constructors.

@BaseScript is used within scripts to indicate that the script shouldextend from a custom script base class rather thangroovy.lang.Script.See the documentation fordomain specific languages for further details.

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

Thewhen property is annotated with@Delegate, meaning that theEvent class will delegate calls toDate methodsto thewhen property. In this case, the generated code looks like this:

Then you can call thebefore method, for example, directly on theEvent 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 areaccessed 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, sodon’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:

• @ToString

• @EqualsAndHashCode

• @TupleConstructor

• @MapConstructor

• @Final

• @ImmutableBase

• @ImmutableOptions

• @PropertyOptions

• @KnownImmutable

The@Immutable meta-annotation simplifies the creation of immutable classes. Immutable classes are usefulsince they are often easier to reason about and are inherently thread-safe.SeeEffective Java, Minimize Mutability for all the detailsabout how to achieve immutable classes in Java. The@Immutable meta-annotation does most of the things describedinEffective 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 codingsuch as defensive copy in and defensive copy out for any mutable properties within the constructorsand property getters. Between@ImmutableBase,@MapConstructor and@TupleConstructor propertiesare 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 ofapplying the@Canonical meta-annotation but the generated class will have extralogic to handle immutability. You will observe this by, for instance, trying to modify a propertywhich will result in aReadOnlyPropertyException being thrown since the backing field for the propertywill have been automatically made final.

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

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

The following annotation attribute is supported:

This annotation allows you to specify a custom property handler to be used by transformationsduring class construction. It is ignored by the main Groovy compiler but is referenced by other transformationslike@TupleConstructor,@MapConstructor, and@ImmutableBase. It is frequently used behind thescenes 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 transformationslike@TupleConstructor,@MapConstructor, and@NamedVariant.

Groovy’s immutability support relies on a predefined list of known immutable classes (likejava.net.URI orjava.lang.Stringand fails if you use a type which is not in that list, you are allowed to add to the list of known immutable typesthanks 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 youto correctly code that class to ensure immutability.

The@KnownImmutable annotation isn’t actually one that triggers any AST transformations. It is simplya marker annotation. You can annotate your classes with the annotation (including Java classes) and theywill be recognized as acceptable types for members within an immutable class. This saves you having toexplicitly use theknownImmutables orknownImmutableClasses annotation attributes from@ImmutableOptions.

The@Memoized AST transformations simplifies the implementation of caching by allowing the result of method callsto 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 callwould 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:

• protectedCacheSize: the number of results which are guaranteed not to be cleared after garbage collection

• maxCacheSize: the maximum number of results that can be kept in memory

By default, the size of the cache is unlimited and no cache result is protected from garbage collection. Setting aprotectedCacheSize>0 would create an unlimited cache with some results protected. SettingmaxCacheSize>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 methodinto 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 andtrampoline() 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 instanceis defined eagerly by default, using class initialization, or lazily, in which case the field is initialized usingdouble-checked locking.

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

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

In this example, we also set thestrict 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 theApache 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 theApache 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 compatiblereload4j log4jdrop-in replacement, just use the jar from that project instead of a log4j jar.

Groovy supports theApache 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 theSimple 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 theJava Platform Logging API and Serviceframework 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 thesynchronized keyword but locks on differentobjects 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 anyfield you want by specifying the value attribute, like in the following example:

The@WithReadLock AST transformation works in conjunction with the@WithWriteLock transformationto provide read/write synchronization using theReentrantReadWriteLock facility that the JDK provides. The annotationcan 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

• See Javadoc forgroovy.transform.WithReadLock

• See Javadoc forgroovy.transform.WithWriteLock

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

• the defaultAutoCloneStyle.CLONE strategy callssuper.clone() first thenclone() on each cloneable property

• theAutoCloneStyle.SIMPLE strategy uses a regular constructor call and copies properties from the source to the clone

• theAutoCloneStyle.COPY_CONSTRUCTOR strategy creates and uses a copy constructor

• theAutoCloneStyle.SERIALIZATION strategy uses serialization (or externalization) to clone the object

Each of those strategies have pros and cons which are discussed in the Javadoc forgroovy.transform.AutoClone andgroovy.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 theclone() method fromObject will copy the String references. The same would apply to primitive fields and most of the concrete subclasses ofjava.lang.Number.

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

The@AutoExternalize AST transformation will assist in the creation ofjava.io.Externalizable classes. It willautomatically add the interface to the class and generate thewriteExternal andreadExternal methods. For example, thiscode:

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. TheThread#stop method exists but isdeprecated (and isn’t reliable) so your only chance lies inThread#interrupt. Calling the latter will set theinterrupt flag on the thread, but it willnot stop the execution of the thread. This is problematic because it’s theresponsibility of the code executing in the thread to check the interrupt flag and properly exit. This makes sense whenyou, 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:

• loops (for, while)

• first instruction of a method

• first instruction of a closure body

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 youjoin onthe thread, then the calling code would be able to continue, but the thread would still be alive, running in backgroundwithout 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 allowsyou 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 theinterrupt flag is set on the current thread, anexception 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 theinterrupt flag of the thread, it will automaticallythrow 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 highn value, it can take minutes to answer. With@TimedInterrupt, you canchoose 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 youwant 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 usto 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 theThreadInterrupt section, using theorg.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 withscripts. 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 compiledto classes and the script body is itself compiled as a singlerun() method. Methods which are defined in the scripts are independent, so the code above isequivalent to this:

Sodef x is effectively interpreted as a local variable, outside of the scope of theline method. The@Field AST transformation aims at fixing thisby 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 listofPackageScopeTarget values as the annotation attribute at the class level, all members within that class that don’thave an explicit modifier and match the providedPackageScopeTarget will remain package protected. For example to applyto fields within a class use the following annotation:

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

@Final is essentially an alias for thefinal modifier.The intention is that you would almost never use the@Final annotation directly (just usefinal).However, when creating meta-annotations that should applythe 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 modifierin numerous places within the annotated node. If applied on a method (or constructor), the parametersfor that method (or constructor) will be marked as final. If applied on a class definition, the sametreatment 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 themethod signatures somewhat noisy. An alternative might instead be to use a code review process or applyacodenarcruleto give warnings if that practice is observed but these alternatives might lead to delayed feedback duringquality checking rather than within the IDE or during compilation. The@AutoFinal annotation aims tomaximise 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 forboth thefullname andgreeting methods will be final. Attempts to modify those parameters within theconstructor or method bodies will be flagged by the compiler.

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

Here, theadd method will have final parameters but themult method will remain unchanged.

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

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

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

@CompileDynamic disables static compilation on parts of your Groovy code. Seesection 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 areusingtype checking orstatic compilation. The annotation is described thoroughly in theDSL section of this guide.

@SelfType is not an AST transformation but rather a marker interface usedwith traits. See thetraits documentation for further details.

@Bindable is an AST transformation that transforms a regular property into a bound property (according to theJavaBeans 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 createfireXXX 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 annotationcan 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 expectedthat 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 andperform 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 beplaced on any annotable node and requires two parameters:

• phase: sets at which phase at which@ASTTest will be triggered. The test code will work on the AST tree at the end of this phase.

• value: the code which will be executed once the phase is reached, on the annotated node

value is a closure expression which has access to a special variablenode corresponding to the annotated node, and a helperlookup method which will be discussedhere.For example, you can annotate a class node like this:

One interesting feature of@ASTTest is that if an assertion fails, thencompilation 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 thetransform runs, which can be found inorg.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 convenientlookup 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:

• node corresponds to the annotated node, as usual

• compilationUnit gives access to the currentorg.codehaus.groovy.control.CompilationUnit

• compilePhase returns the current compile phase (org.codehaus.groovy.control.CompilePhase)

The latter is interesting if you don’t specify thephase attribute. In that case, the closure will be executed aftereach 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 describedthoroughly in thissection of the guide.

@WithLoggingdef greet() {    println "Hello World"}greet()

import org.codehaus.groovy.transform.GroovyASTTransformationClassimport java.lang.annotation.ElementTypeimport java.lang.annotation.Retentionimport java.lang.annotation.RetentionPolicyimport java.lang.annotation.Target@Retention(RetentionPolicy.SOURCE)@Target([ElementType.METHOD])@GroovyASTTransformationClass(["gep.WithLoggingASTTransformation"])public @interface WithLogging {}

@CompileStatic(1)@GroovyASTTransformation(phase=CompilePhase.SEMANTIC_ANALYSIS)(2)class WithLoggingASTTransformation implements ASTTransformation {(3)    @Override    void visit(ASTNode[] nodes, SourceUnit sourceUnit) {(4)        MethodNode method = (MethodNode) nodes[1](5)        def startMessage = createPrintlnAst("Starting $method.name")(6)        def endMessage = createPrintlnAst("Ending $method.name")(7)        def existingStatements = ((BlockStatement)method.code).statements(8)        existingStatements.add(0, startMessage)(9)        existingStatements.add(endMessage)(10)    }    private static Statement createPrintlnAst(String message) {(11)        new ExpressionStatement(            new MethodCallExpression(                new VariableExpression("this"),                new ConstantExpression("println"),                new ArgumentListExpression(                    new ConstantExpression(message)                )            )        )    }}

@WithLoggingdef greet() {    println "Hello World"}greet()

Starting greetHello WorldEnding greet

def greet() {    println "Hello World"}greet()

gep.WithLoggingASTTransformation

@CompileStatic(1)@GroovyASTTransformation(phase=CompilePhase.SEMANTIC_ANALYSIS)(2)class WithLoggingASTTransformation implements ASTTransformation {(3)    @Override    void visit(ASTNode[] nodes, SourceUnit sourceUnit) {(4)        def methods = sourceUnit.AST.methods(5)        methods.each { method ->(6)            def startMessage = createPrintlnAst("Starting $method.name")(7)            def endMessage = createPrintlnAst("Ending $method.name")(8)            def existingStatements = ((BlockStatement)method.code).statements(9)            existingStatements.add(0, startMessage)(10)            existingStatements.add(endMessage)(11)        }    }    private static Statement createPrintlnAst(String message) {(12)        new ExpressionStatement(            new MethodCallExpression(                new VariableExpression("this"),                new ConstantExpression("println"),                new ArgumentListExpression(                    new ConstantExpression(message)                )            )        )    }}

While you have seen that you can directly implement theASTTransformation interface, in almost all cases you will notdo this but extend theorg.codehaus.groovy.transform.AbstractASTTransformation class. This class provides severalutility methods that make AST transformations easier to write. Almost all AST transformations included in Groovyextend this class.

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

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

should print:

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

Classes of the Abstract Syntax Tree belong to theorg.codehaus.groovy.ast package. It is recommended to the readerto use the Groovy Console, in particular the AST browser tool, to gain knowledge about those classes.Another resource for learning is theAST Buildertest 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 duringcompile time.

Although the use oforg.codehaus.groovy.ast.tool.GeneralUtils static methods could mitigate the burden of creatingexpressions 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 theorg.codehaus.groovy.ast.* node related classes.

Let’s see an example, lets create a local AST transformation:@AddMessageMethod. When applied to a given class itwill add a new method calledgetMessage to that class. The method will return "42". The annotation is prettystraight 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 theprevious code simplifies with the use of macros.

Although themacro method is used in this example to create astatement themacro method could also be used to createexpressions as well, it depends on whichmacro signature you use:

• macro(Closure): Create a given statement with the code inside the closure.

• macro(Boolean,Closure): iftrue wrap expressions inside the closure inside a statement, iffalse then returnan expression

• macro(CompilePhase, Closure): Create a given statement with the code inside the closure in a specific compile phase

• macro(CompilePhase, Boolean, Closure): Create a statement or an expression (true == statement, false == expression)in a specific compilation phase.

Sometimes we could be only interested in creating a given expression, not the whole statement, in order to do that weshould use any of themacro 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 resolvesurrounding variables.

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

And the transformation:

As we mentioned earlier, themacro method is only capable of producingstatements andexpressions. But what if wewant 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 createclasses (ClassNode instances) in ourtransformations the same way we created statements and expressions with themacro method before.

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

And the AST transformation:

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

You have seen that by usingmacro you can save yourself a lot of work but you might wonder wherethat method came from. You didn’t declare it or static import it. You can think of it as a specialglobal method (or if you prefer, a method on everyObject). This is much like how theprintlnextension method is defined. But unlikeprintln which becomes a method selected for executionlater in the compilation process,macro expansion is done early in the compilation process.The declaration ofmacro as one of the available methods for this early expansion is doneby annotating amacro method definition with the@Macro annotation and making that methodavailable using a similar mechanism for extension modules. Such methods are known asmacro methodsand 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 andadd a method such as:

Now you would register this as an extension module using aorg.codehaus.groovy.runtime.ExtensionModulefile within theMETA-INF/groovy directory.

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

This section is about good practices in regard to testing AST transformations. Previous sections highlighted the factthat to be able to execute an AST transformation, it has to be precompiled. It might sound obvious but a lot of peopleget 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 bothApache Maven andGradle.

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: ifyour IDE uses the Groovy compiler to compile the unit tests for your AST transformation, then the compilation is triggeredfrom the IDE, but the process which will compile the files doesn’t have debugging options. It’s only when the test caseis executed that the debugging options are set on the virtual machine. In short: it is too late, the class has been compiledalready, and your transformation is already applied.

A very easy workaround is to use theGroovyTestCase class which provides anassertScript method. This means thatinstead of writing this in a test case:

You should write:

The difference is that when you useassertScript, the code in theassertScript block is compiledwhen theunit test is executed. That is to say that this time, theSubject class will be compiled with debugging active, andthe 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 giventransformation 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 coulduseASTMatcher to filter these nodes. The following example shows how to transform a given expression toanother. UsingASTMatcher it looks for a specific expression1 + 1 and it transforms it to3. That’s whywe 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 oforg.codehaus.groovy.ast.ClassCodeExpressionTransformerto all the expressions within the method code block.

And this is when theASTMatcher is used to apply the transformation only to those expressions matchingthe expression1 + 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. Butit would be great if we could have an easy way to check, for example, that the nodes the transformation adds are whatwe expected from the beginning.

The following transformation adds a new methodgiveMeTwo to an annotated class.

Now instead of creating a test executing the transformation over a given sample code. I would like to check thatthe 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 ASTduring compilation. Groovyprovides a tool named@ASTTest for this: it is an annotation that will let you add assertions on an abstract syntaxtree. Please check thedocumentation for ASTTest for more details.