groovy multiple variable assignment

Told you, we love sharing!

Multiple Variable Assignment in Groovy

• Application Security
• Automation Testing
• Cloud Managed Services
• Connected TV
• Data & Analytics
• Digital Analytics
• Digital Engineering
• Digital Marketing
• Digital Transformation
• DM – Analytics
• Experience Design
• Front End Development
• Industry Buzz
• Manual Testing
• Marketing Automation
• Mobile Automation Testing
• Product Engineering
• Software development
• User Experience
• Video Solutions
• Web Content Management

In one of my project, I was in need to return multiple variables from a method. I searched and found very good Groovy way for ‘Multiple Assignment’, This allows us to assign multiple variables at once.

[groovy]def (str1,str2,str3) = [‘Groovy’,’and’,’Grails’] assert str1 == ‘Groovy’ && str2 == ‘and’ && str3 == ‘Grails'[/groovy]

We can have types as part of the declaration [groovy] def (int a,String b) = [10,’someString’] [/groovy]

With method calls [groovy] def someMethod(){ [5,’Hello’] } def (int a,String b) = someMethod() [/groovy]

For more information see Multiple Assignments.

Ankur [email protected]

Grails 3.0- What’s New?

comments (1 “Multiple Variable Assignment in Groovy”)

great article

Leave a Reply Cancel reply

Your email address will not be published. Required fields are marked *

Save my name, email, and website in this browser for the next time I comment.

YOU MAY ALSO LIKE

• Closure Delegate using Groovy “with” Method and decorating code with multiple assignments
• StringJoiner in Java 8
• Groovier way of sorting over multiple fields in a list of maps in groovy

Get latest articles straight to your inbox

• CloudKeeper
• DevOps as a Service
• DevOps on AWS
• DevOps Tools
• DevOps Team
• Python Development
• Node.js Development
• Grails Development
• Java Development
• MEAN Development
• Grails Team
• Node.js Team
• Email Marketing
• Search Engine Optimization
• Social Listening
• Web Analytics
• Influencer Marketing
• Content Marketing
• Social Media Marketing
• Creative Strategy
• Digital Campaigns and Activations
• Media planning and buying
• Search Marketing
• Digital Strategy
• AEM Development
• Drupal Development
• iOS App Development
• Android Development
• Smart TV App Development
• Hybrid Application Development
• Mobility Team
• AngularJS Development
• React Native Development
• React js Development
• Software Product Engineering
• Video Managed Services
• Multiscreen Solutions
• Offshore Software Development
• Outsourced Software Product Development
• Custom Software Development
• Bespoke Software Development
• Custom Web Application Development
• Outsource Web Application Development
• Offshore Development Center

Tips for writing a blog

Learn how to write a caption.

Groovy Language Documentation

Single-line comment, multiline comment, groovydoc comment, shebang line, 1.1.2. keywords, normal identifiers, quoted identifiers, single-quoted string, string concatenation, escaping special characters, unicode escape sequence, string interpolation, special case of interpolating closure expressions, interoperability with java, gstring and string hashcodes, triple-double-quoted string, special cases, dollar slashy string, string summary table.

• Binary literal
• Octal literal
• Hexadecimal literal

Decimal literals

Underscore in literals, number type suffixes, the case of the division operator, the case of the power operator, 1.1.6. booleans, 1.1.7. lists, java-style array initialization, 1.1.9. maps, normal arithmetic operators, unary operators, assignment arithmetic operators, 1.2.2. relational operators, short-circuiting, bitwise operators, bit shift operators, not operator, ternary operator, elvis operator, elvis assignment operator, safe navigation operator, direct field access operator, method pointer operator, method reference operator, pattern operator, find operator, match operator, comparing find vs match operators, spreading method arguments, spread list elements, spread map elements, range operator, spaceship operator, subscript operator, safe index operator, membership operator, identity operator, coercion operator, diamond operator, call operator, 1.2.9. operator precedence, 1.2.10. operator overloading, 1.3.1. package names, default imports, simple import, star import, static import, static import aliasing, static star import, import aliasing, public static void main vs script, script class, primitive types, reference types, normal class, anonymous inner class, abstract class, inheritance, superclasses, positional parameters, named parameters, method definition.

• Mixing named and positional parameters

Default arguments

Method selection algorithm, exception declaration.

• Property naming conventions
• Modifiers on a property
• Annotations on a property
• Split property definition with an explicit backing field
• Explicit accessor methods

Annotation placement

Annotation member values, retention policy, closure annotation parameters, declaring meta-annotations, behavior of meta-annotations, meta-annotation parameters, handling duplicate annotations in meta-annotations, custom meta-annotation processors, public methods, abstract methods, private methods, final methods, the meaning of this, private fields, public fields, composition of behaviors, overriding default methods, simple inheritance, multiple inheritance, dynamic code, dynamic methods in a trait, default conflict resolution, user conflict resolution, implementing a trait at runtime, implementing multiple traits at once, semantics of super inside a trait, sam type coercion, differences with java 8 default methods, differences with mixins, static methods, properties and fields, inheritance of state gotchas, type constraints on traits, the @selftype annotation, differences with sealed annotation (incubating), compatibility with ast transformations, prefix and postfix operations, compact constructor, serializability, argument defaults, declarative tostring customization, obtaining a list of the record component values, obtaining a map of the record component values, obtaining the number of components in a record, obtaining the n th component from a record, deep immutability, obtaining the components of a record as a typed tuple, other differences to java, differences to java, defining a closure, closures as an object, calling a closure, normal parameters, implicit parameter, groovy closures vs lambda expressions, owner of a closure, delegate of a closure, delegation strategy, delegation strategy in the presence of metaprogramming, 1.5.4. closures in gstrings, 1.5.5. closure coercion, left currying, right currying, index based currying, memoization, composition, method pointers, variable definition, multiple assignment, overflow and underflow, object destructuring with multiple assignment.

• switch / case
• Classic for loop
• Enhanced classic Java-style for loop
• Multi-assignment in combination with for loop
• for in loop
• do/while loop

Exception handling

Try / catch / finally, multi-catch, arm try with resources, power assertion, labeled statements, object navigation, expression deconstruction, gpath for xml navigation, number promotion, assigning a closure to a sam type, calling a method accepting a sam type with a closure, closure to arbitrary type coercion, map to type coercion, string to enum coercion, custom type coercion, class literals vs variables and the as operator, optional parentheses, optional semicolons, optional return keyword, optional public keyword, boolean expressions, collections and arrays, iterators and enumerations, object references, customizing the truth with asboolean() methods, optional typing.

• Activating type checking at compile time
• Skipping sections

Type checking assignments

List and map constructors, method resolution.

• Variables vs fields in type inference
• Collection literal type inference
• Least upper bound
• instanceof inference
• Flow typing
• Advanced type inference
• Return type inference
• Explicit closure parameters
• Parameters inferred from single-abstract method types
• The @ClosureParams annotation

@DelegatesTo

Dynamic vs static, the @compilestatic annotation, key benefits, towards a smarter type checker, the extensions attribute, a dsl for type checking.

• Support classes
• Class nodes
• Helping the type checker
• Throwing an error
• isXXXExpression
• Virtual methods

Other useful methods

Precompiled type checking extensions, using @grab in a type checking extension, sharing or packaging type checking extensions, global type checking extensions, type checking extensions and @compilestatic, mixed mode compilation, transforming the ast in an extension, 2.1.1. groovy, the groovy command, 2.2.1. groovyc, the groovy compiler, 2.2.2. ant task, 2.2.3. gant, 2.2.4. gradle, the groovy eclipse maven plugin, 2.2.6. joint compilation, 2.2.7. android support, command-line options and arguments, simple expressions, evaluation result.

• Define a Class
• Use the Class
• interpreterMode
• show-last-result
• sanitize-stack-trace

Setting a Preference

Listing preferences, clearing preferences (i.e. resetting to defaults).

• $HOME/.groovy/groovysh.profile
• $HOME/.groovy/groovysh.rc
• $HOME/.groovy/groovysh.history

Custom commands

• Problems loading the JLine DLL
• Problems with Cygwin on Windows

2.3.2. GMavenPlus Maven Plugin

2.3.3. gradle groovysh plugin, 2.4.1. groovy : groovy console, 2.4.2. basics, running scripts, editing files, history and results, interrupting a script, 2.4.4. embedding the console, 2.4.5. visualizing script output results, 2.4.6. advanced debugging: ast browser, 2.4.7. advanced debugging: cst browser, 2.5.1. the groovydoc command line tool, required taskdef, <groovydoc> attributes, example #1 - <groovydoc> ant task, example #2 - executing <groovydoc> from groovy, custom groovydoc class, using the custom groovydoc task, 2.5.3. gmavenplus maven plugin, 2.6. ide integration, prerequisites, 3.1.2. maven repository, 3.1.3. sdkman (the software development kit manager), installation on windows, other distributions, source code, 3.1.5. install binary, 3.2.1. default imports, 3.2.2. multi-methods, 3.2.3. array initializers, 3.2.4. package scope visibility, 3.2.5. arm blocks, static inner classes, anonymous inner classes, creating instances of non-static inner classes, 3.2.7. lambda expressions and the method reference operator, 3.2.8. gstrings, 3.2.9. string and character literals, 3.2.10. behaviour of ==, numeric primitive optimisation with @compilestatic, positive/negative zero edge case, 3.2.12. conversions, 3.2.13. extra keywords, reading files, writing files, traversing file trees, data and objects, executing external processes, list literals, list as a boolean expression, iterating on a list.

• Filtering and searching
• Adding or removing elements
• Set operations
• Duplicating elements

Map literals

Map property notation, iterating on maps.

• Keys, values and entries

GPath support

Spread operator, the star-dot `*.' operator, slicing with the subscript operator, enhanced collection methods, array literals, 3.3.4. working with legacy date/calendar types, formatting and parsing, addition and subtraction, multiplication and division, incrementing and decrementing, property notation, ranges, upto , and downto, combining date/time values, creating periods and durations, converting between legacy and jsr 310 types, configslurper, observable list, map and set, invokemethod, get/setproperty, get/setmetaclass, get/setattribute, methodmissing, propertymissing, static methodmissing, static propertymissing, groovyinterceptable, the default metaclass metaclassimpl.

• Delegating metaclass
• Magic package

Per instance metaclass

Constructors.

• Static Methods
• Borrowing Methods
• Dynamic Method Names
• Runtime Discovery
• GroovyObject Methods
• Overriding Static invokeMethod
• Extending Interfaces

Extending existing classes

Instance methods, static methods, module descriptor, extension modules and classpath, compatibility with type checking.

• @groovy.transform.ToString
• @groovy.transform.EqualsAndHashCode
• @groovy.transform.TupleConstructor
• Implementation Details
• Immutability support
• Customization options
• @groovy.transform.MapConstructor
• @groovy.transform.Canonical
• @groovy.transform.InheritConstructors
• @groovy.lang.Category
• @groovy.transform.IndexedProperty
• @groovy.lang.Lazy
• @groovy.lang.Newify
• @groovy.transform.Sortable
• @groovy.transform.builder.Builder
• @groovy.transform.AutoImplement
• @groovy.transform.NullCheck
• @groovy.transform.BaseScript
• @groovy.lang.Delegate
• @groovy.transform.Immutable
• @groovy.transform.ImmutableBase
• @groovy.transform.PropertyOptions
• @groovy.transform.VisibilityOptions
• @groovy.transform.ImmutableOptions
• @groovy.transform.KnownImmutable
• @groovy.transform.Memoized
• @groovy.transform.TailRecursive
• @groovy.lang.Singleton
• @groovy.lang.Mixin
• @groovy.util.logging.Log
• @groovy.util.logging.Commons
• @groovy.util.logging.Log4j
• @groovy.util.logging.Log4j2
• @groovy.util.logging.Slf4j
• @groovy.util.logging.PlatformLog
• @groovy.transform.Synchronized
• @groovy.transform.WithReadLock and @groovy.transform.WithWriteLock
• @groovy.transform.AutoClone
• @groovy.transform.AutoExternalize
• @groovy.transform.ThreadInterrupt
• @groovy.transform.TimedInterrupt
• @groovy.transform.ConditionalInterrupt
• @groovy.transform.Field
• @groovy.transform.PackageScope
• @groovy.transform.Final
• @groovy.transform.AutoFinal
• @groovy.transform.AnnotationCollector
• @groovy.transform.TypeChecked
• @groovy.transform.CompileStatic
• @groovy.transform.CompileDynamic
• @groovy.lang.DelegatesTo
• @groovy.transform.SelfType
• @groovy.beans.Bindable
• @groovy.beans.ListenerList
• @groovy.beans.Vetoable
• @groovy.test.NotYetImplemented
• @groovy.transform.ASTTest
• @groovy.lang.Grab
• @groovy.lang.GrabConfig
• @groovy.lang.GrabExclude
• @groovy.lang.GrabResolver
• @groovy.lang.Grapes

Compilation phases guide

Local transformations, global transformations.

• AbstractASTTransformation
• ClassCodeExpressionTransformer

Introduction

• Statements and expressions
• Variable substitution
• @Macro methods
• Separating source trees
• Debugging AST transformations

External references

Add a dependency, specify additional repositories, maven classifiers, excluding transitive dependencies, jdbc drivers, using grape from the groovy shell, proxy settings, 3.5.2. detail, multiple grape annotations, grab(hashmap) parameters, arguments map arguments, command line tool, repository directory, customize ivy settings, more examples, 3.6.1. introduction, power assertions, map coercion, closure coercion, mockfor and stubfor, expando meta-class (emc), iterable#combinations, iterable#eachcombination, test code coverage, assertion methods, shouldfail methods, notyetimplemented method, specifications, a geb script, 3.7. tune parsing performance of parrot parser, parser variants, formatted output, connecting with a datasource, connecting using @grab, creating tables, creating/inserting data, reading rows, updating rows, deleting rows, working with transactions, using batches, performing pagination, fetching metadata, named and named-ordinal parameters, stored procedures, 3.9.5. using datasets.

• Iterable Data Source
• Stream Data Source
• Array Data Source
• GINQ Result Set Data Source
• Aggregate Functions
• Nested GINQ in from clause
• Nested GINQ in where clause
• Nested GINQ in select clause
• rank , denseRank , percentRank , cumeDist and ntile
• lead and lag
• firstValue , lastValue and nthValue
• min , max , count , sum , avg , median , stdev , stdevp , var , varp and agg

List Comprehension

Query & update, alternative for with clause, alternative for case-when, parallel querying, customize ginq, optimize ginq, generate multiplication table, more examples, xmlparser and xmlslurper, domcategory, simply traversing the tree, flexible navigation with children (*), depthfirst (**) and breadthfirst, markupbuilder, streamingmarkupbuilder, markupbuilderhelper, domtogroovy, adding nodes, modifying / removing nodes, 3.14.1. applying @invariant, @requires and @ensures, 3.14.2. more features, 3.14.3. the stack example, 3.15. scripting ant tasks, 3.16.1. <groovy>, 3.16.2. required taskdef, 3.16.3. <groovy> attributes, <classpath>, <arg>, 3.16.5. available bindings, 3.16.6. examples, description, <groovyc> attributes, <groovyc> nested elements, joint compilation, 3.18.1. introduction, 3.18.2. template framework, advanced usage note, 3.18.4. streamingtemplateengine, 3.18.5. gstringtemplateengine, 3.18.6. xmltemplateengine, support methods, creation of a template engine, configuration options, automatic formatting, automatic escaping.

• Strings containing markup

Internationalization

Custom template classes, optional type checking, alternative declaration of types, performance of type checked templates, 3.18.8. other solutions, 3.19.1. implicit variables, 3.19.2. setting up groovlets, multiple sources, sharing data between a script and the application, custom script class, groovyclassloader, groovyscriptengine, compilationunit, 3.20.2. jsr 223 javax.script api, 3.21.1. command chains, 3.21.2. operator overloading, the script class, the @basescript annotation, alternate abstract method, 3.21.4. adding properties to numbers, explaining delegation strategy at compile time, simple delegation, delegate to parameter, multiple closures, delegating to a generic type, delegating to an arbitrary type, import customizer, ast transformation customizer, secure ast customizer, source aware customizer, inlining a customizer, multiple customizers, configscript example: static compilation by default, configscript example: setting system properties, ast transformations, 3.21.7. custom type checking extensions, staxbuilder, nodebuilder, jsonbuilder, streamingjsonbuilder, swingbuilder.

• Using Annotations and an interface
• Using Annotations and an instance
• Using Annotations and a script
• Options with arguments
• Specifying a type
• Custom parsing of the argument String
• Options with multiple arguments
• Types and multiple arguments
• Setting a default value
• Use with TypeChecked
• Apache Commons CLI

ObjectGraphBuilder

Filetreebuilder, buildersupport, factorybuildersupport, 3.22.1. introduction, 3.22.2. monitoring the jvm, 3.22.3. monitoring tomcat, 3.22.4. oc4j example, 3.22.5. weblogic example, 3.22.6. spring example, java.lang.securityexception, instantiating jmxbuilder, connector server, connector client, implicit vs explicit descriptors, the jmxbuilder.export() node, jmxbuilder.export() syntax, integration with groovymbean class.

• JConsole view of Exported Bean

JmxBuilder.bean() Syntax

Bean() node - specifying mbean objectname, export all attributes with wildcard "*", export attribute list, export attribute with explicit descriptors, export all constructors with "*", export constructors using parameter descriptor, export constructor with explicit descriptors, export all operations with "*", export operation list, export operations by signature, export operations with explicit descriptors, embedding descriptor, timer node syntax, exporting a timer, timer period.

• Parameterless
• With Event Parameter

Handling Attribute onChange Event

Attribute onchange event object, handling operation oncall event, operation oncall event object, listening to jmx events, listener node syntax, emitter syntax, declare the emitter, broadcast event, sending event objects, 3.22.9. further jmx information, 3.23. creating swing uis, 3.24. security, delegation example, inheritance example, adapting using closures, adapting using the expandometaclass, null checking example, validation example, example using traditional classes, example using simplifying strategies, when not to use, going further, example with traditional classes, simplifying variations, traditional example, simplifying with closures or lambdas, a touch of dynamic behaviour, runtime behaviour embellishment, more dynamic decorating, decorating with an interceptor, decorating with java.lang.reflect.proxy, decorating with spring, asynchronous decorators using gpars, implement delegation pattern using expandometaclass, implement delegation pattern using @delegate annotation, iterator pattern, a touch of formalism, benefits of monoids, working with non-monoids, simple example, tree example, @bindable and @vetoable, example: the classic java singleton, example: singleton via metaprogramming, guice example, spring example, further information, variation 1: leveraging interface-oriented design, variation 2: extract state pattern logic, variation 3: bring on the dsl, example using traditional class hierarchy, example using closures, example using lambdas, example with simplifying strategies.

• When to use this
• What happens if we add a new type?
• What if we want to have different iteration patterns?
• Make it Groovy

Further Information

3.25.2. references, 4.1. contributors, 4.2. license.

Groovy…​

is an agile and dynamic language for the Java Virtual Machine

builds upon the strengths of Java but has additional power features inspired by languages like Python, Ruby and Smalltalk

makes modern programming features available to Java developers with almost-zero learning curve

provides the ability to statically type check and statically compile your code for robustness and performance

supports Domain-Specific Languages and other compact syntax so your code becomes easy to read and maintain

makes writing shell and build scripts easy with its powerful processing primitives, OO abilities and an Ant DSL

increases developer productivity by reducing scaffolding code when developing web, GUI, database or console applications

simplifies testing by supporting unit testing and mocking out-of-the-box

seamlessly integrates with all existing Java classes and libraries

compiles straight to Java bytecode so you can use it anywhere you can use Java

1. Groovy Language Specification

1.1. syntax.

This chapter covers the syntax of the Groovy programming language. The grammar of the language derives from the Java grammar, but enhances it with specific constructs for Groovy, and allows certain simplifications.

1.1.1. Comments

Single-line comments start with // and can be found at any position in the line. The characters following // , until the end of the line, are considered part of the comment.

A multiline comment starts with /* and can be found at any position in the line. The characters following /* will be considered part of the comment, including new line characters, up to the first */ closing the comment. Multiline comments can thus be put at the end of a statement, or even inside a statement.

Similarly to multiline comments, Groovydoc comments are multiline, but start with /** and end with */ . Lines following the first Groovydoc comment line can optionally start with a star * . Those comments are associated with:

type definitions (classes, interfaces, enums, annotations),

fields and properties definitions

methods definitions

Although the compiler will not complain about Groovydoc comments not being associated with the above language elements, you should prepend those constructs with the comment right before it.

Groovydoc follows the same conventions as Java’s own Javadoc. So you’ll be able to use the same tags as with Javadoc.

In addition, Groovy supports Runtime Groovydoc since 3.0.0, i.e. Groovydoc can be retained at runtime.

The Runtime Groovydoc starts with /**@ and ends with */ , for example:

Beside the single-line comment, there is a special line comment, often called the shebang line understood by UNIX systems which allows scripts to be run directly from the command-line, provided you have installed the Groovy distribution and the groovy command is available on the PATH .

Groovy has the following reserved keywords:

Of these, const , goto , strictfp , and threadsafe are not currently in use.

The reserved keywords can’t in general be used for variable, field and method names.

A trick allows methods to be defined having the same name as a keyword by surrounding the name in quotes as shown in the following example:

Using such names might be confusing and is often best to avoid. The trick is primarily intended to enable certain Java integration scenarios and certain DSL scenarios where having "verbs" and "nouns" with the same name as keywords may be desirable.

In addition, Groovy has the following contextual keywords:

These words are only keywords in certain contexts and can be more freely used in some places, in particular for variables, fields and method names.

This extra lenience allows using method or variable names that were not keywords in earlier versions of Groovy or are not keywords in Java. Examples are shown here:

Groovy programmers familiar with these contextual keywords may still wish to avoid using those names unless there is a good reason to use such a name.

The restrictions on reserved keywords also apply for the primitive types, the boolean literals and the null literal (all of which are discussed later):

While not recommended, the same trick as for reserved keywords can be used:

Using such words as method names is potentially confusing and is often best to avoid, however, it might be useful for certain kinds of DSLs .

1.1.3. Identifiers

Identifiers start with a letter, a dollar or an underscore. They cannot start with a number.

A letter can be in the following ranges:

'a' to 'z' (lowercase ascii letter)

'A' to 'Z' (uppercase ascii letter)

'\u00C0' to '\u00D6'

'\u00D8' to '\u00F6'

'\u00F8' to '\u00FF'

'\u0100' to '\uFFFE'

Then following characters can contain letters and numbers.

Here are a few examples of valid identifiers (here, variable names):

But the following ones are invalid identifiers:

All keywords are also valid identifiers when following a dot:

Quoted identifiers appear after the dot of a dotted expression. For instance, the name part of the person.name expression can be quoted with person."name" or person.'name' . This is particularly interesting when certain identifiers contain illegal characters that are forbidden by the Java Language Specification, but which are allowed by Groovy when quoted. For example, characters like a dash, a space, an exclamation mark, etc.

As we shall see in the following section on strings , Groovy provides different string literals. All kind of strings are actually allowed after the dot:

There’s a difference between plain character strings and Groovy’s GStrings (interpolated strings), as in that the latter case, the interpolated values are inserted in the final string for evaluating the whole identifier:

1.1.4. Strings

Text literals are represented in the form of chain of characters called strings. Groovy lets you instantiate java.lang.String objects, as well as GStrings ( groovy.lang.GString ) which are also called interpolated strings in other programming languages.

Single-quoted strings are a series of characters surrounded by single quotes:

All the Groovy strings can be concatenated with the + operator:

Triple-single-quoted string

Triple-single-quoted strings are a series of characters surrounded by triplets of single quotes:

Triple-single-quoted strings may span multiple lines. The content of the string can cross line boundaries without the need to split the string in several pieces and without concatenation or newline escape characters:

If your code is indented, for example in the body of the method of a class, your string will contain the whitespace of the indentation. The Groovy Development Kit contains methods for stripping out the indentation with the String#stripIndent() method, and with the String#stripMargin() method that takes a delimiter character to identify the text to remove from the beginning of a string.

When creating a string as follows:

You will notice that the resulting string contains a newline character as first character. It is possible to strip that character by escaping the newline with a backslash:

You can escape single quotes with the backslash character to avoid terminating the string literal:

And you can escape the escape character itself with a double backslash:

Some special characters also use the backslash as escape character:

We’ll see some more escaping details when it comes to other types of strings discussed later.

For characters that are not present on your keyboard, you can use unicode escape sequences: a backslash, followed by 'u', then 4 hexadecimal digits.

For example, the Euro currency symbol can be represented with:

Double-quoted string

Double-quoted strings are a series of characters surrounded by double quotes:

Any Groovy expression can be interpolated in all string literals, apart from single and triple-single-quoted strings. Interpolation is the act of replacing a placeholder in the string with its value upon evaluation of the string. The placeholder expressions are surrounded by ${} . The curly braces may be omitted for unambiguous dotted expressions, i.e. we can use just a $ prefix in those cases. If the GString is ever passed to a method taking a String, the expression value inside the placeholder is evaluated to its string representation (by calling toString() on that expression) and the resulting String is passed to the method.

Here, we have a string with a placeholder referencing a local variable:

Any Groovy expression is valid, as we can see in this example with an arithmetic expression:

In addition to ${} placeholders, we can also use a lone $ sign prefixing a dotted expression:

But only dotted expressions of the form a.b , a.b.c , etc, are valid. Expressions containing parentheses like method calls, curly braces for closures, dots which aren’t part of a property expression or arithmetic operators would be invalid. Given the following variable definition of a number:

The following statement will throw a groovy.lang.MissingPropertyException because Groovy believes you’re trying to access the toString property of that number, which doesn’t exist:

Similarly, if the expression is ambiguous, you need to keep the curly braces:

If you need to escape the $ or ${} placeholders in a GString so they appear as is without interpolation, you just need to use a \ backslash character to escape the dollar sign:

So far, we’ve seen we could interpolate arbitrary expressions inside the ${} placeholder, but there is a special case and notation for closure expressions. When the placeholder contains an arrow, ${→} , the expression is actually a closure expression — you can think of it as a closure with a dollar prepended in front of it:

In appearance, it looks like a more verbose way of defining expressions to be interpolated, but closures have an interesting advantage over mere expressions: lazy evaluation.

Let’s consider the following sample:

When a method (whether implemented in Java or Groovy) expects a java.lang.String , but we pass a groovy.lang.GString instance, the toString() method of the GString is automatically and transparently called.

Although interpolated strings can be used in lieu of plain Java strings, they differ with strings in a particular way: their hashCodes are different. Plain Java strings are immutable, whereas the resulting String representation of a GString can vary, depending on its interpolated values. Even for the same resulting string, GStrings and Strings don’t have the same hashCode.

GString and Strings having different hashCode values, using GString as Map keys should be avoided, especially if we try to retrieve an associated value with a String instead of a GString.

Triple-double-quoted strings behave like double-quoted strings, with the addition that they are multiline, like the triple-single-quoted strings.

Slashy string

Beyond the usual quoted strings, Groovy offers slashy strings, which use / as the opening and closing delimiter. Slashy strings are particularly useful for defining regular expressions and patterns, as there is no need to escape backslashes.

Example of a slashy string:

Only forward slashes need to be escaped with a backslash:

Slashy strings are multiline:

Slashy strings can be thought of as just another way to define a GString but with different escaping rules. They hence support interpolation:

An empty slashy string cannot be represented with a double forward slash, as it’s understood by the Groovy parser as a line comment. That’s why the following assert would actually not compile as it would look like a non-terminated statement:

As slashy strings were mostly designed to make regexp easier so a few things that are errors in GStrings like $() or $5 will work with slashy strings.

Remember that escaping backslashes is not required. An alternative way of thinking of this is that in fact escaping is not supported. The slashy string /\t/ won’t contain a tab but instead a backslash followed by the character 't'. Escaping is only allowed for the slash character, i.e. /\/folder/ will be a slashy string containing '/folder' . A consequence of slash escaping is that a slashy string can’t end with a backslash. Otherwise that will escape the slashy string terminator. You can instead use a special trick, /ends with slash ${'\'}/ . But best just avoid using a slashy string in such a case.

Dollar slashy strings are multiline GStrings delimited with an opening $/ and a closing /$ . The escaping character is the dollar sign, and it can escape another dollar, or a forward slash. Escaping for the dollar and forward slash characters is only needed where conflicts arise with the special use of those characters. The characters $foo would normally indicate a GString placeholder, so those four characters can be entered into a dollar slashy string by escaping the dollar, i.e. $$foo . Similarly, you will need to escape a dollar slashy closing delimiter if you want it to appear in your string.

Here are a few examples:

It was created to overcome some of the limitations of the slashy string escaping rules. Use it when its escaping rules suit your string contents (typically if it has some slashes you don’t want to escape).

Unlike Java, Groovy doesn’t have an explicit character literal. However, you can be explicit about making a Groovy string an actual character, by three different means:

1.1.5. Numbers

Groovy supports different kinds of integral literals and decimal literals, backed by the usual Number types of Java.

Integral literals

The integral literal types are the same as in Java:

java.math.BigInteger

You can create integral numbers of those types with the following declarations:

If you use optional typing by using the def keyword, the type of the integral number will vary: it’ll adapt to the capacity of the type that can hold that number.

For positive numbers:

As well as for negative numbers:

Alternative non-base 10 representations

Numbers can also be represented in binary, octal, hexadecimal and decimal bases.

Binary numbers start with a 0b prefix:

Octal numbers are specified in the typical format of 0 followed by octal digits.

Hexadecimal numbers are specified in the typical format of 0x followed by hex digits.

The decimal literal types are the same as in Java:

java.math.BigDecimal

You can create decimal numbers of those types with the following declarations:

Decimals can use exponents, with the e or E exponent letter, followed by an optional sign, and an integral number representing the exponent:

Conveniently for exact decimal number calculations, Groovy chooses java.math.BigDecimal as its decimal number type. In addition, both float and double are supported, but require an explicit type declaration, type coercion or suffix. Even if BigDecimal is the default for decimal numbers, such literals are accepted in methods or closures taking float or double as parameter types.

When writing long literal numbers, it’s harder on the eye to figure out how some numbers are grouped together, for example with groups of thousands, of words, etc. By allowing you to place underscore in number literals, it’s easier to spot those groups:

We can force a number (including binary, octals and hexadecimals) to have a specific type by giving a suffix (see table below), either uppercase or lowercase.

Math operations

Although operators are covered in more detail elsewhere, it’s important to discuss the behavior of math operations and what their resulting types are.

Division and power binary operations aside (covered below),

binary operations between byte , char , short and int result in int

binary operations involving long with byte , char , short and int result in long

binary operations involving BigInteger and any other integral type result in BigInteger

binary operations involving BigDecimal with byte , char , short , int and BigInteger result in BigDecimal

binary operations between float , double and BigDecimal result in double

binary operations between two BigDecimal result in BigDecimal

The following table summarizes those rules:

The division operators / (and /= for division and assignment) produce a double result if either operand is a float or double , and a BigDecimal result otherwise (when both operands are any combination of an integral type short , char , byte , int , long , BigInteger or BigDecimal ).

BigDecimal division is performed with the divide() method if the division is exact (i.e. yielding a result that can be represented within the bounds of the same precision and scale), or using a MathContext with a precision of the maximum of the two operands' precision plus an extra precision of 10, and a scale of the maximum of 10 and the maximum of the operands' scale.

The power operation is represented by the ** operator, with two parameters: the base and the exponent. The result of the power operation depends on its operands, and the result of the operation (in particular if the result can be represented as an integral value).

The following rules are used by Groovy’s power operation to determine the resulting type:

If the exponent is a decimal value

if the result can be represented as an Integer , then return an Integer

else if the result can be represented as a Long , then return a Long

otherwise return a Double

If the exponent is an integral value

if the exponent is strictly negative, then return an Integer , Long or Double if the result value fits in that type

if the exponent is positive or zero

if the base is a BigDecimal , then return a BigDecimal result value

if the base is a BigInteger , then return a BigInteger result value

if the base is an Integer , then return an Integer if the result value fits in it, otherwise a BigInteger

if the base is a Long , then return a Long if the result value fits in it, otherwise a BigInteger

We can illustrate those rules with a few examples:

Boolean is a special data type that is used to represent truth values: true and false . Use this data type for simple flags that track true/false conditions .

Boolean values can be stored in variables, assigned into fields, just like any other data type:

true and false are the only two primitive boolean values. But more complex boolean expressions can be represented using logical operators .

In addition, Groovy has special rules (often referred to as Groovy Truth ) for coercing non-boolean objects to a boolean value.

Groovy uses a comma-separated list of values, surrounded by square brackets, to denote lists. Groovy lists are plain JDK java.util.List , as Groovy doesn’t define its own collection classes. The concrete list implementation used when defining list literals are java.util.ArrayList by default, unless you decide to specify otherwise, as we shall see later on.

In the above example, we used a homogeneous list, but you can also create lists containing values of heterogeneous types:

We mentioned that by default, list literals are actually instances of java.util.ArrayList , but it is possible to use a different backing type for our lists, thanks to using type coercion with the as operator, or with explicit type declaration for your variables:

You can access elements of the list with the [] subscript operator (both for reading and setting values) with positive indices or negative indices to access elements from the end of the list, as well as with ranges, and use the << leftShift operator to append elements to a list:

As lists can be heterogeneous in nature, lists can also contain other lists to create multidimensional lists:

1.1.8. Arrays

Groovy reuses the list notation for arrays, but to make such literals arrays, you need to explicitly define the type of the array through coercion or type declaration.

You can also create multi-dimensional arrays:

Access to elements of an array follows the same notation as for lists:

Groovy has always supported literal list/array definitions using square brackets and has avoided Java-style curly braces so as not to conflict with closure definitions. In the case where the curly braces come immediately after an array type declaration however, there is no ambiguity with closure definitions, so Groovy 3 and above support that variant of the Java array initialization expression.

Sometimes called dictionaries or associative arrays in other languages, Groovy features maps. Maps associate keys to values, separating keys and values with colons, and each key/value pairs with commas, and the whole keys and values surrounded by square brackets.

If you try to access a key which is not present in the map:

You will retrieve a null result.

In the examples above, we used string keys, but you can also use values of other types as keys:

Here, we used numbers as keys, as numbers can unambiguously be recognized as numbers, so Groovy will not create a string key like in our previous examples. But consider the case you want to pass a variable in lieu of the key, to have the value of that variable become the key:

When you need to pass variable values as keys in your map definitions, you must surround the variable or expression with parentheses:

1.2. Operators

This chapter covers the operators of the Groovy programming language.

1.2.1. Arithmetic operators

Groovy supports the usual familiar arithmetic operators you find in mathematics and in other programming languages like Java. All the Java arithmetic operators are supported. Let’s go through them in the following examples.

The following binary arithmetic operators are available in Groovy:

Here are a few examples of usage of those operators:

The + and - operators are also available as unary operators:

In terms of unary arithmetics operators, the ++ (increment) and -- (decrement) operators are available, both in prefix and postfix notation:

For the unary not operator on Booleans, see Conditional operators .

The binary arithmetic operators we have seen above are also available in an assignment form:

Let’s see them in action:

Relational operators allow comparisons between objects, to know if two objects are the same or different, or if one is greater than, less than, or equal to the other.

The following operators are available:

Here are some examples of simple number comparisons using these operators:

Both === and !== are supported which are the same as calling the is() method, and negating a call to the is() method respectively.

1.2.3. Logical operators

Groovy offers three logical operators for boolean expressions:

&& : logical "and"

|| : logical "or"

! : logical "not"

Let’s illustrate them with the following examples:

The logical "not" has a higher priority than the logical "and".

The logical "and" has a higher priority than the logical "or".

The logical || operator supports short-circuiting: if the left operand is true, it knows that the result will be true in any case, so it won’t evaluate the right operand. The right operand will be evaluated only if the left operand is false.

Likewise for the logical && operator: if the left operand is false, it knows that the result will be false in any case, so it won’t evaluate the right operand. The right operand will be evaluated only if the left operand is true.

1.2.4. Bitwise and bit shift operators

Groovy offers four bitwise operators:

& : bitwise "and"

| : bitwise "or"

^ : bitwise "xor" (exclusive "or")

~ : bitwise negation

Bitwise operators can be applied on arguments which are of type byte , short , int , long , or BigInteger . If one of the arguments is a BigInteger , the result will be of type BigInteger ; otherwise, if one of the arguments is a long , the result will be of type long ; otherwise, the result will be of type int :

It’s worth noting that the internal representation of primitive types follow the Java Language Specification . In particular, primitive types are signed, meaning that for a bitwise negation, it is always good to use a mask to retrieve only the necessary bits.

In Groovy, bitwise operators are overloadable , meaning that you can define the behavior of those operators for any kind of object.

Groovy offers three bit shift operators:

<< : left shift

>> : right shift

>>> : right shift unsigned

All three operators are applicable where the left argument is of type byte , short , int , or long . The first two operators can also be applied where the left argument is of type BigInteger . If the left argument is a BigInteger , the result will be of type BigInteger ; otherwise, if the left argument is a long , the result will be of type long ; otherwise, the result will be of type int :

In Groovy, bit shift operators are overloadable , meaning that you can define the behavior of those operators for any kind of object.

1.2.5. Conditional operators

The "not" operator is represented with an exclamation mark ( ! ) and inverts the result of the underlying boolean expression. In particular, it is possible to combine the not operator with the Groovy truth :

The ternary operator is a shortcut expression that is equivalent to an if/else branch assigning some value to a variable.

Instead of:

You can write:

The ternary operator is also compatible with the Groovy truth , so you can make it even simpler:

The "Elvis operator" is a shortening of the ternary operator. One instance of where this is handy is for returning a 'sensible default' value if an expression resolves to false -ish (as in Groovy truth ). A simple example might look like this:

Usage of the Elvis operator reduces the verbosity of your code and reduces the risks of errors in case of refactorings, by removing the need to duplicate the expression which is tested in both the condition and the positive return value.

Groovy 3.0.0 introduces the Elvis operator, for example:

1.2.6. Object operators

The Safe Navigation operator is used to avoid a NullPointerException . Typically when you have a reference to an object you might need to verify that it is not null before accessing methods or properties of the object. To avoid this, the safe navigation operator will simply return null instead of throwing an exception, like so:

Normally in Groovy, when you write code like this:

The user.name call triggers a call to the property of the same name, that is to say, here, to the getter for name . If you want to retrieve the field instead of calling the getter, you can use the direct field access operator:

The method pointer operator ( .& ) can be used to store a reference to a method in a variable, in order to call it later:

There are multiple advantages in using method pointers. First of all, the type of such a method pointer is a groovy.lang.Closure , so it can be used in any place a closure would be used. In particular, it is suitable to convert an existing method for the needs of the strategy pattern:

Method pointers are bound by the receiver and a method name. Arguments are resolved at runtime, meaning that if you have multiple methods with the same name, the syntax is not different, only resolution of the appropriate method to be called will be done at runtime:

To align with Java 8 method reference expectations, in Groovy 3 and above, you can use new as the method name to obtain a method pointer to the constructor:

Also in Groovy 3 and above, you can obtain a method pointer to an instance method of a class. This method pointer takes an additional parameter being the receiver instance to invoke the method on:

For backwards compatibility, any static methods that happen to have the correct parameters for the call will be given precedence over instance methods for this case.

The Parrot parser in Groovy 3+ supports the Java 8+ method reference operator. The method reference operator ( :: ) can be used to reference a method or constructor in contexts expecting a functional interface. This overlaps somewhat with the functionality provided by Groovy’s method pointer operator. Indeed, for dynamic Groovy, the method reference operator is just an alias for the method pointer operator. For static Groovy, the operator results in bytecode similar to the bytecode that Java would produce for the same context.

Some examples highlighting various supported method reference cases are shown in the following script:

Some examples highlighting various supported constructor reference cases are shown in the following script:

1.2.7. Regular expression operators

The pattern operator ( ~ ) provides a simple way to create a java.util.regex.Pattern instance:

while in general, you find the pattern operator with an expression in a slashy-string, it can be used with any kind of String in Groovy:

Alternatively to building a pattern, you can use the find operator =~ to directly create a java.util.regex.Matcher instance:

Since a Matcher coerces to a boolean by calling its find method, the =~ operator is consistent with the simple use of Perl’s =~ operator, when it appears as a predicate (in if , ?: , etc.). When the intent is to iterate over matches of the specified pattern (in while , etc.) call find() directly on the matcher or use the iterator DGM.

The match operator ( ==~ ) is a slight variation of the find operator, that does not return a Matcher but a boolean and requires a strict match of the input string:

Typically, the match operator is used when the pattern involves a single exact match, otherwise the find operator might be more useful.

1.2.8. Other operators

The Spread-dot Operator ( *. ), often abbreviated to just Spread Operator, is used to invoke an action on all items of an aggregate object. It is equivalent to calling the action on each item and collecting the result into a list:

The expression cars*.make is equivalent to cars.collect{ it.make } . Groovy’s GPath notation allows a short-cut when the referenced property isn’t a property of the containing list, in that case it is automatically spread. In the previously mentioned case, the expression cars.make can be used, though retaining the explicit spread-dot operator is often recommended.

The spread operator is null-safe, meaning that if an element of the collection is null, it will return null instead of throwing a NullPointerException :

The spread operator can be used on any class which implements the Iterable interface:

Use multiple invocations of the spread-dot operator (here cars*.models*.name ) when working with aggregates of data structures which themselves contain aggregates:

Consider using the collectNested DGM method instead of the spread-dot operator for collections of collections:

There may be situations when the arguments of a method call can be found in a list that you need to adapt to the method arguments. In such situations, you can use the spread operator to call the method. For example, imagine you have the following method signature:

then if you have the following list:

you can call the method without having to define intermediate variables:

It is even possible to mix normal arguments with spread ones:

When used inside a list literal, the spread operator acts as if the spread element contents were inlined into the list:

The spread map operator works in a similar manner as the spread list operator, but for maps. It allows you to inline the contents of a map into another map literal, like in the following example:

The position of the spread map operator is relevant, like illustrated in the following example:

Groovy supports the concept of ranges and provides a notation ( .. ) to create ranges of objects:

Ranges implementation is lightweight, meaning that only the lower and upper bounds are stored. You can create a range from any Comparable object that has next() and previous() methods to determine the next / previous item in the range. For example, you can create a range of characters this way:

The spaceship operator ( <=> ) delegates to the compareTo method:

The subscript operator is a shorthand notation for getAt or putAt , depending on whether you find it on the left hand side or the right hand side of an assignment:

The subscript operator, in combination with a custom implementation of getAt / putAt is a convenient way for destructuring objects:

Groovy 3.0.0 introduces safe indexing operator, i.e. ?[] , which is similar to ?. . For example:

The membership operator ( in ) is equivalent to calling the isCase method. In the context of a List , it is equivalent to calling contains , like in the following example:

In Groovy, using == to test equality is different from using the same operator in Java. In Groovy, it is calling equals . If you want to compare reference equality, you should use is like in the following example:

The coercion operator ( as ) is a variant of casting. Coercion converts object from one type to another without them being compatible for assignment. Let’s take an example:

This can be fixed by using coercion instead:

When an object is coerced into another, unless the target type is the same as the source type, coercion will return a new object. The rules of coercion differ depending on the source and target types, and coercion may fail if no conversion rules are found. Custom conversion rules may be implemented thanks to the asType method:

The diamond operator ( <> ) is a syntactic sugar only operator added to support compatibility with the operator of the same name in Java 7. It is used to indicate that generic types should be inferred from the declaration:

In dynamic Groovy, this is totally unused. In statically type checked Groovy, it is also optional since the Groovy type checker performs type inference whether this operator is present or not.

The call operator () is used to call a method named call implicitly. For any object which defines a call method, you can omit the .call part and use the call operator instead:

The table below lists all groovy operators in order of precedence.

Groovy allows you to overload the various operators so that they can be used with your own classes. Consider this simple class:

Just by implementing the plus() method, the Bucket class can now be used with the + operator like so:

All (non-comparator) Groovy operators have a corresponding method that you can implement in your own classes. The only requirements are that your method is public, has the correct name, and has the correct number of arguments. The argument types depend on what types you want to support on the right hand side of the operator. For example, you could support the statement

by implementing the plus() method with this signature:

Here is a complete list of the operators and their corresponding methods:

1.3. Program structure

This chapter covers the program structure of the Groovy programming language.

Package names play exactly the same role as in Java. They allow us to separate the code base without any conflicts. Groovy classes must specify their package before the class definition, else the default package is assumed.

Defining a package is very similar to Java:

To refer to some class Foo in the com.yoursite.com package you will need to use the fully qualified name com.yoursite.com.Foo , or else you can use an import statement as we’ll see below.

1.3.2. Imports

In order to refer to any class you need a qualified reference to its package. Groovy follows Java’s notion of allowing import statement to resolve class references.

For example, Groovy provides several builder classes, such as MarkupBuilder . MarkupBuilder is inside the package groovy.xml so in order to use this class, you need to import it as shown:

Default imports are the imports that Groovy language provides by default. For example look at the following code:

The same code in Java needs an import statement to Date class like this: import java.util.Date. Groovy by default imports these classes for you.

The below imports are added by groovy for you:

This is done because the classes from these packages are most commonly used. By importing these boilerplate code is reduced.

A simple import is an import statement where you fully define the class name along with the package. For example the import statement import groovy.xml.MarkupBuilder in the code below is a simple import which directly refers to a class inside a package.

Groovy, like Java, provides a special way to import all classes from a package using * , the so-called star import. MarkupBuilder is a class which is in package groovy.xml , alongside another class called StreamingMarkupBuilder . In case you need to use both classes, you can do:

That’s perfectly valid code. But with a * import, we can achieve the same effect with just one line. The star imports all the classes under package groovy.xml :

One problem with * imports is that they can clutter your local namespace. But with the kinds of aliasing provided by Groovy, this can be solved easily.

Groovy’s static import capability allows you to reference imported classes as if they were static methods in your own class:

This is similar to Java’s static import capability but is a more dynamic than Java in that it allows you to define methods with the same name as an imported method as long as you have different types:

If you have the same types, the imported class takes precedence.

Static imports with the as keyword provide an elegant solution to namespace problems. Suppose you want to get a Calendar instance, using its getInstance() method. It’s a static method, so we can use a static import. But instead of calling getInstance() every time, which can be misleading when separated from its class name, we can import it with an alias, to increase code readability:

Now, that’s clean!

A static star import is very similar to the regular star import. It will import all the static methods from the given class.

For example, lets say we need to calculate sines and cosines for our application. The class java.lang.Math has static methods named sin and cos which fit our need. With the help of a static star import, we can do:

As you can see, we were able to access the methods sin and cos directly, without the Math. prefix.

With type aliasing, we can refer to a fully qualified class name using a name of our choice. This can be done with the as keyword, as before.

For example we can import java.sql.Date as SQLDate and use it in the same file as java.util.Date without having to use the fully qualified name of either class:

1.3.3. Scripts versus classes

Groovy supports both scripts and classes. Take the following code for example:

This is typical code that you would find coming from Java, where code has to be embedded into a class to be executable. Groovy makes it easier, the following code is equivalent:

A script can be considered as a class without needing to declare it, with some differences.

A groovy.lang.Script is always compiled into a class. The Groovy compiler will compile the class for you, with the body of the script copied into a run method. The previous example is therefore compiled as if it was the following:

If the script is in a file, then the base name of the file is used to determine the name of the generated script class. In this example, if the name of the file is Main.groovy , then the script class is going to be Main .

It is possible to define methods into a script, as illustrated here:

You can also mix methods and code. The generated script class will carry all methods into the script class, and assemble all script bodies into the run method:

This code is internally converted into:

Variables in a script do not require a type definition. This means that this script:

will behave the same as:

However, there is a semantic difference between the two:

if the variable is declared as in the first example, it is a local variable . It will be declared in the run method that the compiler will generate and will not be visible outside of the script main body. In particular, such a variable will not be visible in other methods of the script

if the variable is undeclared, it goes into the groovy.lang.Script#getBinding() . The binding is visible from the methods, and is especially important if you use a script to interact with an application and need to share data between the script and the application. Readers might refer to the integration guide for more information.

1.4. Object orientation

This chapter covers the object-oriented aspects of the Groovy programming language.

1.4.1. Types

Groovy supports the same primitive types as defined by the Java Language Specification :

integral types: byte (8 bit), short (16 bit), int (32 bit) and long (64 bit)

floating-point types: float (32 bit) and double (64 bit)

the boolean type (one of true or false )

the char type (16 bit, usable as a numeric type, representing a UTF-16 code)

Also like Java, Groovy uses the respective wrapper classes when objects corresponding to any of the primitive types are required:

Automatic boxing and unboxing occur when, for instance, calling a method requiring the wrapper class and passing it a primitive variable as the parameter, or vice-versa. This is similar to Java but Groovy takes the idea further.

In most scenarios, you can treat a primitive just like it was the full object wrapper equivalent. For instance, you can call .toString() or .equals(other) on a primitive. Groovy autowraps and unwraps between references and primitives as needed.

Here’s an example using int which is declared as a static field in a class (discussed shortly):

Now you may be concerned that this means every time you use a mathematical operator on a reference to a primitive that you’ll incur the cost of unboxing and reboxing the primitive. But this is not the case, as Groovy will compile your operators into their method equivalents and uses those instead. Additionally, Groovy will automatically unbox to a primitive when calling a Java method that takes a primitive parameter and automatically box primitive method return values from Java. However, be aware there are some differences from Java’s method resolution.

Apart from primitives, everything else is an object and has an associated class defining its type. We’ll discuss classes, and class-related or class-like things like interfaces, traits and records shortly.

We might declare two variables, of type String and List, as follows:

Groovy carries across the same concepts with regard to generics as Java. When defining classes and methods, it is possible to use a type parameter and create a generic class, interface, method or constructor.

Usage of generic classes and methods, regardless of whether they are defined in Java or Groovy, may involve supplying a type argument.

We might declare a variable, of type "list of string" , as follows:

Java employs type erasure for backwards compatibility with earlier versions of Java. Dynamic Groovy can be thought of as more aggressively applying type erasure. In general, less generics type information will be checked at compile time. Groovy’s static nature employs similar checks to Java with regard to generics information.

1.4.2. Classes

Groovy classes are very similar to Java classes, and are compatible with Java ones at JVM level. They may have methods, fields and properties (think JavaBeans properties but with less boilerplate). Classes and class members can have the same modifiers (public, protected, private, static, etc.) as in Java with some minor differences at the source level which are explained shortly.

The key differences between Groovy classes and their Java counterparts are:

Classes or methods with no visibility modifier are automatically public (a special annotation can be used to achieve package private visibility).

Fields with no visibility modifier are turned into properties automatically, which results in less verbose code, since explicit getter and setter methods aren’t needed. More on this aspect will be covered in the fields and properties section .

Classes do not need to have the same base name as their source file definitions but it is highly recommended in most scenarios (see also the next point about scripts).

One source file may contain one or more classes (but if a file contains any code not in a class, it is considered a script). Scripts are just classes with some special conventions and will have the same name as their source file (so don’t include a class definition within a script having the same name as the script source file).

The following code presents an example class.

Normal classes refer to classes which are top level and concrete. This means they can be instantiated without restrictions from any other classes or scripts. This way, they can only be public (even though the public keyword may be suppressed). Classes are instantiated by calling their constructors, using the new keyword, as in the following snippet.

Inner class

Inner classes are defined within another classes. The enclosing class can use the inner class as usual. On the other side, an inner class can access members of its enclosing class, even if they are private. Classes other than the enclosing class are not allowed to access inner classes. Here is an example:

There are some reasons for using inner classes:

They increase encapsulation by hiding the inner class from other classes, which do not need to know about it. This also leads to cleaner packages and workspaces.

They provide a good organization, by grouping classes that are used by only one class.

They lead to more maintainable codes, since inner classes are near the classes that use them.

It is common for an inner class to be an implementation of some interface whose method(s) are needed by the outer class. The code below illustrates this typical usage pattern, here being used with threads.

Note that the class Inner2 is defined only to provide an implementation of the method run to class Outer2 . Anonymous inner classes help to eliminate verbosity in this case. That topic is covered shortly.

Groovy 3+ also supports Java syntax for non-static inner class instantiation, for example:

The earlier example of an inner class ( Inner2 ) can be simplified with an anonymous inner class. The same functionality can be achieved with the following code:

Thus, there was no need to define a new class to be used just once.

Abstract classes represent generic concepts, thus, they cannot be instantiated, being created to be subclassed. Their members include fields/properties and abstract or concrete methods. Abstract methods do not have implementation, and must be implemented by concrete subclasses.

Abstract classes are commonly compared to interfaces. There are at least two important differences of choosing one or another. First, while abstract classes may contain fields/properties and concrete methods, interfaces may contain only abstract methods (method signatures). Moreover, one class can implement several interfaces, whereas it can extend just one class, abstract or not.

Inheritance in Groovy resembles inheritance in Java. It provides a mechanism for a child class (or subclass) to reuse code or properties from a parent (or super class). Classes related through inheritance form an inheritance hierarchy. Common behavior and members are pushed up the hierarchy to reduce duplication. Specializations occur in child classes.

Different forms of inheritance are supported:

implementation inheritance where code (methods, fields or properties) from a superclass or from one or more traits is reused by a child class

contract inheritance where a class promises to provide particular abstract methods defined in a superclass , or defined in one or more traits or interfaces .

Parent classes share visible fields, properties or methods with child classes. A child class may have at most one parent class. The extends keyword is used immediately prior to giving the superclass type.

An interface defines a contract that a class needs to conform to. An interface only defines a list of methods that need to be implemented, but does not define the method’s implementation.

Methods of an interface are always public . It is an error to use protected or private methods in interfaces:

A class implements an interface if it defines the interface in its implements list or if any of its superclasses does:

An interface can extend another interface:

It is worth noting that for a class to be an instance of an interface, it has to be explicit. For example, the following class defines the greet method as it is declared in the Greeter interface, but does not declare Greeter in its interfaces:

In other words, Groovy does not define structural typing. It is however possible to make an instance of an object implement an interface at runtime, using the as coercion operator:

You can see that there are two distinct objects: one is the source object, a DefaultGreeter instance, which does not implement the interface. The other is an instance of Greeter that delegates to the coerced object.

1.4.3. Class members

Constructors are special methods used to initialize an object with a specific state. As with normal methods, it is possible for a class to declare more than one constructor, so long as each constructor has a unique type signature. If an object doesn’t require any parameters during construction, it may use a no-arg constructor. If no constructors are supplied, an empty no-arg constructor will be provided by the Groovy compiler.

Groovy supports two invocation styles:

positional parameters are used in a similar to how you would use Java constructors

named parameters allow you to specify parameter names when invoking the constructor.

To create an object by using positional parameters, the respective class needs to declare one or more constructors. In the case of multiple constructors, each must have a unique type signature. The constructors can also be added to the class using the groovy.transform.TupleConstructor annotation.

Typically, once at least one constructor is declared, the class can only be instantiated by having one of its constructors called. It is worth noting that, in this case, you can’t normally create the class with named parameters. Groovy does support named parameters so long as the class contains a no-arg constructor or provides a constructor which takes a Map argument as the first (and potentially only) argument - see the next section for details.

There are three forms of using a declared constructor. The first one is the normal Java way, with the new keyword. The others rely on coercion of lists into the desired types. In this case, it is possible to coerce with the as keyword and by statically typing the variable.

If no (or a no-arg) constructor is declared, it is possible to create objects by passing parameters in the form of a map (property/value pairs). This can be in handy in cases where one wants to allow several combinations of parameters. Otherwise, by using traditional positional parameters it would be necessary to declare all possible constructors. Having a constructor where the first (and perhaps only) argument is a Map argument is also supported - such a constructor may also be added using the groovy.transform.MapConstructor annotation.

It is important to highlight, however, that this approach gives more power to the constructor caller, while imposing an increased responsibility on the caller to get the names and value types correct. Thus, if greater control is desired, declaring constructors using positional parameters might be preferred.

While the example above supplied no constructor, you can also supply a no-arg constructor or a constructor where the first argument is a Map , most typically it’s the only argument.

When no (or a no-arg) constructor is declared, Groovy replaces the named constructor call by a call to the no-arg constructor followed by calls to the setter for each supplied named property.

When the first argument is a Map, Groovy combines all named parameters into a Map (regardless of ordering) and supplies the map as the first parameter. This can be a good approach if your properties are declared as final (since they will be set in the constructor rather than after the fact with setters).

You can support both named and positional construction by supply both positional constructors as well as a no-arg or Map constructor.

You can support hybrid construction by having a constructor where the first argument is a Map but there are also additional positional parameters. Use this style with caution.

Groovy methods are quite similar to other languages. Some peculiarities will be shown in the next subsections.

A method is defined with a return type or with the def keyword, to make the return type untyped. A method can also receive any number of arguments, which may not have their types explicitly declared. Java modifiers can be used normally, and if no visibility modifier is provided, the method is public.

Methods in Groovy always return some value. If no return statement is provided, the value evaluated in the last line executed will be returned. For instance, note that none of the following methods uses the return keyword.

Like constructors, normal methods can also be called with named parameters. To support this notation, a convention is used where the first argument to the method is a Map . In the method body, the parameter values can be accessed as in normal maps ( map.key ). If the method has just a single Map argument, all supplied parameters must be named.

Named parameters can be mixed with positional parameters. The same convention applies, in this case, in addition to the Map argument as the first argument, the method in question will have additional positional arguments as needed. Supplied positional parameters when calling the method must be in order. The named parameters can be in any position. They are grouped into the map and supplied as the first parameter automatically.

If we don’t have the Map as the first argument, then a Map must be supplied for that argument instead of named parameters. Failure to do so will lead to groovy.lang.MissingMethodException :

Above exception can be avoided if we replace named arguments with an explicit Map argument:

Default arguments make parameters optional. If the argument is not supplied, the method assumes a default value.

Parameters are dropped from the right, however mandatory parameters are never dropped.

The same rule applies to constructors as well as methods. If using @TupleConstructor , additional configuration options apply.

Groovy supports methods with a variable number of arguments. They are defined like this: def foo(p1, …​, pn, T…​ args) . Here foo supports n arguments by default, but also an unspecified number of further arguments exceeding n .

This example defines a method foo , that can take any number of arguments, including no arguments at all. args.length will return the number of arguments given. Groovy allows T[] as an alternative notation to T…​ . That means any method with an array as last parameter is seen by Groovy as a method that can take a variable number of arguments.

If a method with varargs is called with null as the vararg parameter, then the argument will be null and not an array of length one with null as the only element.

If a varargs method is called with an array as an argument, then the argument will be that array instead of an array of length one containing the given array as the only element.

Another important point are varargs in combination with method overloading. In case of method overloading Groovy will select the most specific method. For example if a method foo takes a varargs argument of type T and another method foo also takes one argument of type T , the second method is preferred.

Dynamic Groovy supports multiple dispatch (aka multimethods). When calling a method, the actual method invoked is determined dynamically based on the run-time type of methods arguments. First the method name and number of arguments will be considered (including allowance for varargs), and then the type of each argument. Consider the following method definitions:

Perhaps as expected, calling method with String and Integer parameters, invokes our third method definition.

Of more interest here is when the types are not known at compile time. Perhaps the arguments are declared to be of type Object (a list of such objects in our case). Java would determine that the method(Object, Object) variant would be selected in all cases (unless casts were used) but as can be seen in the following example, Groovy uses the runtime type and will invoke each of our methods once (and normally, no casting is needed):

For each of the first two of our three method invocations an exact match of argument types was found. For the third invocation, an exact match of method(Integer, Integer) wasn’t found but method(Object, Object) is still valid and will be selected.

Method selection then is about finding the closest fit from valid method candidates which have compatible parameter types. So, method(Object, Object) is also valid for the first two invocations but is not as close a match as the variants where types exactly match. To determine the closest fit, the runtime has a notion of the distance an actual argument type is away from the declared parameter type and tries to minimise the total distance across all parameters.

The following table illustrates some factors which affect the distance calculation.

In the case where two variants have exactly the same distance, this is deemed ambiguous and will cause a runtime exception:

Casting can be used to select the desired method:

Groovy automatically allows you to treat checked exceptions like unchecked exceptions. This means that you don’t need to declare any checked exceptions that a method may throw as shown in the following example which can throw a FileNotFoundException if the file isn’t found:

Nor will you be required to surround the call to the badRead method in the previous example within a try/catch block - though you are free to do so if you wish.

If you wish to declare any exceptions that your code might throw (checked or otherwise) you are free to do so. Adding exceptions won’t change how the code is used from any other Groovy code but can be seen as documentation for the human reader of your code. The exceptions will become part of the method declaration in the bytecode, so if your code might be called from Java, it might be useful to include them. Using an explicit checked exception declaration is illustrated in the following example:

Fields and Properties

A field is a member of a class, interface or trait which stores data. A field defined in a Groovy source file has:

a mandatory access modifier ( public , protected , or private )

one or more optional modifiers ( static , final , synchronized )

an optional type

a mandatory name

A field may be initialized directly at declaration:

It is possible to omit the type declaration of a field. This is however considered a bad practice and in general it is a good idea to use strong typing for fields:

The difference between the two is important if you want to use optional type checking later. It is also important as a way to document the class design. However, in some cases like scripting or if you want to rely on duck typing it may be useful to omit the type.

A property is an externally visible feature of a class. Rather than just using a public field to represent such features (which provides a more limited abstraction and would restrict refactoring possibilities), the typical approach in Java is to follow the conventions outlined in the JavaBeans Specification , i.e. represent the property using a combination of a private backing field and getters/setters. Groovy follows these same conventions but provides a simpler way to define the property. You can define a property with:

an absent access modifier (no public , protected or private )

Groovy will then generate the getters/setters appropriately. For example:

If a property is declared final , no setter is generated:

Properties are accessed by name and will call the getter or setter transparently, unless the code is in the class which defines the property:

It is worth noting that this behavior of accessing the backing field directly is done in order to prevent a stack overflow when using the property access syntax within a class that defines the property.

It is possible to list the properties of a class thanks to the meta properties field of an instance:

By convention, Groovy will recognize properties even if there is no backing field provided there are getters or setters that follow the Java Beans specification. For example:

This syntactic sugar is at the core of many DSLs written in Groovy.

It is generally recommended that the first two letters of a property name are lowercase and for multi-word properties that camel case is used. In those cases, generated getters and setters will have a name formed by capitalizing the property name and adding a get or set prefix (or optionally "is" for a boolean getter). So, getLength would be a getter for a length property and setFirstName a setter for a firstName property. isEmpty might be the getter method name for a property named empty .

The JavaBeans specification makes a special case for properties which typically might be acronyms. If the first two letters of a property name are uppercase, no capitalization is performed (or more importantly, no decapitalization is done if generating the property name from the accessor method name). So, getURL would be the getter for a URL property.

We have already seen that properties are defined by omitting the visibility modifier. In general, any other modifiers, e.g. transient would be copied across to the field. Two special cases are worth noting:

final , which we saw earlier is for read-only properties, is copied onto the backing field but also causes no setter to be defined

static is copied onto the backing field but also causes the accessor methods to be static

If you wish to have a modifier like final also carried over to the accessor methods, you can write your properties long hand or consider using a split property definition .

Annotations, including those associated with AST transforms, are copied on to the backing field for the property. This allows AST transforms which are applicable to fields to be applied to properties, e.g.:

Groovy’s property syntax is a convenient shorthand when your class design follows certain conventions which align with common JavaBean practice. If your class doesn’t exactly fit these conventions, you can certainly write the getter, setter and backing field long hand like you would in Java. However, Groovy does provide a split definition capability which still provides a shortened syntax while allowing slight adjustments to the conventions. For a split definition, you write a field and a property with the same name and type. Only one of the field or property may have an initial value.

For split properties, annotations on the field remain on the backing field for the property. Annotations on the property part of the definition are copied onto the getter and setter methods.

This mechanism allows a number of common variations that property users may wish to use if the standard property definition doesn’t exactly fit their needs. For example, if the backing field should be protected rather than private :

Or, the same example but with a package-private backing field:

As a final example, we may wish to apply method-related AST transforms, or in general, any annotation to the setters/getters, e.g. to have the accessors be synchronized:

The automatic generation of accessor methods doesn’t occur if there is an explicit definition of the getter or setter in the class. This allows you to modify the normal behavior of such a getter or setter if needed. Inherited accessor methods aren’t normally considered but if an inherited accessor method is marked final, that will also cause no generation of an additional accessor method to honor the final requirement of no subclassing of such methods.

1.4.4. Annotations

Annotation definition.

An annotation is a kind of special interface dedicated at annotating elements of the code. An annotation is a type which superinterface is the java.lang.annotation.Annotation interface. Annotations are declared in a very similar way to interfaces, using the @interface keyword:

An annotation may define members in the form of methods without bodies and an optional default value. The possible member types are limited to:

primitive types

java.lang.String

java.lang.Class

an java.lang.Enum

another java.lang.annotation.Annotation

or any array of the above

For example:

Unlike in the Java language, in Groovy, an annotation can be used to alter the semantics of the language. It is especially true of AST transformations which will generate code based on annotations.

An annotation can be applied on various elements of the code:

In order to limit the scope where an annotation can be applied, it is necessary to declare it on the annotation definition, using the java.lang.annotation.Target annotation. For example, here is how you would declare that an annotation can be applied to a class or a method:

The list of possible targets is available in the java.lang.annotation.ElementType .

When an annotation is used, it is required to set at least all members that do not have a default value. For example:

However it is possible to omit value= in the declaration of the value of an annotation if the member value is the only one being set:

The visibility of an annotation depends on its retention policy. The retention policy of an annotation is set using the java.lang.annotation.Retention annotation:

The list of possible retention targets and description is available in the java.lang.annotation.RetentionPolicy enumeration. The choice usually depends on whether you want an annotation to be visible at compile time or runtime.

An interesting feature of annotations in Groovy is that you can use a closure as an annotation value. Therefore annotations may be used with a wide variety of expressions and still have IDE support. For example, imagine a framework where you want to execute some methods based on environmental constraints like the JDK version or the OS. One could write the following code:

For the @OnlyIf annotation to accept a Closure as an argument, you only have to declare the value as a Class :

To complete the example, let’s write a sample runner that would use that information:

Then the runner can be used this way:

Meta-annotations

Meta-annotations, also known as annotation aliases are annotations that are replaced at compile time by other annotations (one meta-annotation is an alias for one or more annotations). Meta-annotations can be used to reduce the size of code involving multiple annotations.

Let’s start with a simple example. Imagine you have the  @Service and  @Transactional annotations and that you want to annotate a class with both:

Given the multiplication of annotations that you could add to the same class, a meta-annotation could help by reducing the two annotations with a single one having the very same semantics. For example, we might want to write this instead:

A meta-annotation is declared as a regular annotation but annotated with @AnnotationCollector and the list of annotations it is collecting. In our case, the @TransactionalService annotation can be written:

Groovy supports both precompiled and source form meta-annotations. This means that your meta-annotation  may be precompiled, or you can have it in the same source tree as the one you are currently compiling.

INFO: Meta-annotations are a Groovy-only feature. There is no chance for you to annotate a Java class with a meta-annotation and hope it will do the same as in Groovy. Likewise, you cannot write a meta-annotation in Java: both the meta-annotation definition  and usage have to be Groovy code. But you can happily collect Java annotations and Groovy annotations within your meta-annotation.

When the Groovy compiler encounters a class annotated with a meta-annotation, it  replaces it with the collected annotations. So, in our previous example, it will replace  @TransactionalService with  @Transactional and  @Service :

The conversion from a meta-annotation to the collected annotations is performed during the semantic analysis compilation phase. 

In addition to replacing the alias with the collected annotations, a meta-annotation is capable of processing them, including arguments.

Meta-annotations can collect annotations which have parameters. To illustrate this, we will imagine two annotations, each of them accepting one argument:

And suppose that you want to create a meta-annotation named  @Explosive :

By default, when the annotations are replaced, they will get the annotation parameter values as they were defined in the alias . More interesting, the meta-annotation supports overriding specific values:

If two annotations define the same parameter name, the default processor will copy the annotation value to all annotations that accept this parameter:

In the second case, the meta-annotation value was copied in both @Foo and @Bar annotations.

It is however possible to customize the behavior of meta-annotations and describe how collected annotations are expanded. We’ll look at how to do that shortly but first there is an advanced processing option to cover.

The @AnnotationCollector annotation supports a mode parameter which can be used to alter how the default processor handles annotation replacement in the presence of duplicate annotations.

INFO: Custom processors (discussed next) may or may not support this parameter.

As an example, suppose you create a meta-annotation containing the @ToString annotation and then place your meta-annotation on a class that already has an explicit @ToString annotation. Should this be an error? Should both annotations be applied? Does one take priority over the other? There is no correct answer. In some scenarios it might be quite appropriate for any of these answers to be correct. So, rather than trying to preempt one correct way to handle the duplicate annotation issue, Groovy lets you write your own custom meta-annotation processors (covered next) and lets you write whatever checking logic you like within AST transforms - which are a frequent target for aggregating. Having said that, by simply setting the mode , a number of commonly expected scenarios are handled automatically for you within any extra coding. The behavior of the mode parameter is determined by the AnnotationCollectorMode enum value chosen and is summarized in the following table.

A custom annotation processor will let you choose how to expand a meta-annotation into collected annotations. The behaviour of the meta-annotation is, in this case, totally up to you. To do this, you must:

create a meta-annotation processor, extending org.codehaus.groovy.transform.AnnotationCollectorTransform

declare the processor to be used in the meta-annotation declaration

To illustrate this, we are going to explore how the meta-annotation @CompileDynamic is implemented.

@CompileDynamic is a meta-annotation that expands itself to  @CompileStatic(TypeCheckingMode.SKIP) . The problem is that the default meta annotation processor doesn’t support enums and the annotation value TypeCheckingMode.SKIP is one.

The naive implementation here would not work:

Instead, we will define it like this:

The first thing you may notice is that our interface is no longer annotated with  @CompileStatic . The reason for this is that we rely on the processor parameter instead, that references a class which will  generate the annotation.

Here is how the custom processor is implemented:

In the example, the visit method is the only method which has to be overridden. It is meant to return a list of annotation nodes that will be added to the node annotated with the meta-annotation. In this example, we return a single one corresponding to @CompileStatic(TypeCheckingMode.SKIP) .

1.4.5. Traits

Traits are a structural construct of the language which allows:

composition of behaviors

runtime implementation of interfaces

behavior overriding

compatibility with static type checking/compilation

They can be seen as interfaces carrying both default implementations and state . A trait is defined using the trait keyword:

Then it can be used like a normal interface using the implements keyword:

Traits allow a wide range of capabilities, from simple composition to testing, which are described thoroughly in this section.

Declaring a method in a trait can be done like any regular method in a class:

In addition, traits may declare abstract methods too, which therefore need to be implemented in the class implementing the trait:

Then the trait can be used like this:

Traits may also define private methods. Those methods will not appear in the trait contract interface:

If we have a class implementing a trait, conceptually implementations from the trait methods are "inherited" into the class. But, in reality, there is no base class containing such implementations. Rather, they are woven directly into the class. A final modifier on a method just indicates what the modifier will be for the woven method. While it would likely be considered bad style to inherit and override or multiply inherit methods with the same signature but a mix of final and non-final variants, Groovy doesn’t prohibit this scenario. Normal method selection applies and the modifier used will be determined from the resulting method. You might consider creating a base class which implements the desired trait(s) if you want trait implementation methods that can’t be overridden.

this represents the implementing instance. Think of a trait as a superclass. This means that when you write:

then calling:

will return the same instance:

Traits may implement interfaces, in which case the interfaces are declared using the implements keyword:

A trait may define properties, like in the following example:

Since traits allow the use of private methods, it can also be interesting to use private fields to store state. Traits will let you do that:

Public fields work the same way as private fields, but in order to avoid the diamond problem , field names are remapped in the implementing class:

The name of the field depends on the fully qualified name of the trait. All dots ( . ) in package are replaced with an underscore ( _ ), and the final name includes a double underscore. So if the type of the field is String , the name of the package is my.package , the name of the trait is Foo and the name of the field is bar , in the implementing class, the public field will appear as:

Traits can be used to implement multiple inheritance in a controlled way. For example, we can have the following traits:

And a class implementing both traits:

Traits encourage the reuse of capabilities among objects, and the creation of new classes by the composition of existing behavior.

Traits provide default implementations for methods, but it is possible to override them in the implementing class. For example, we can slightly change the example above, by having a duck which quacks:

Extending traits

Traits may extend another trait, in which case you must use the extends keyword:

Alternatively, a trait may extend multiple traits. In that case, all super traits must be declared in the implements clause:

Duck typing and traits

Traits can call any dynamic code, like a normal Groovy class. This means that you can, in the body of a method, call methods which are supposed to exist in an implementing class, without having to explicitly declare them in an interface. This means that traits are fully compatible with duck typing:

It is also possible for a trait to implement MOP methods like methodMissing or propertyMissing , in which case implementing classes will inherit the behavior from the trait, like in this example:

Multiple inheritance conflicts

It is possible for a class to implement multiple traits. If some trait defines a method with the same signature as a method in another trait, we have a conflict:

In this case, the default behavior is that the method from the last declared trait in the implements clause wins. Here, B is declared after A so the method from B will be picked up:

In case this behavior is not the one you want, you can explicitly choose which method to call using the Trait.super.foo syntax. In the example above, we can ensure the method from trait A is invoked by writing this:

Runtime implementation of traits

Groovy also supports implementing traits dynamically at runtime. It allows you to "decorate" an existing object using a trait. As an example, let’s start with this trait and the following class:

Then if we do:

the call to extra would fail because Something is not implementing Extra . It is possible to do it at runtime with the following syntax:

Should you need to implement several traits at once, you can use the withTraits method instead of the as keyword:

Chaining behavior

Groovy supports the concept of stackable traits . The idea is to delegate from one trait to the other if the current trait is not capable of handling a message. To illustrate this, let’s imagine a message handler interface like this:

Then you can compose a message handler by applying small behaviors. For example, let’s define a default handler in the form of a trait:

Then any class can inherit the behavior of the default handler by implementing the trait:

Now what if you want to log all messages, in addition to the default handler? One option is to write this:

This works but this approach has drawbacks:

the logging logic is bound to a "concrete" handler

we have an explicit reference to DefaultHandler in the on method, meaning that if we happen to change the trait that our class implements, code will be broken

As an alternative, we can write another trait which responsibility is limited to logging:

Then our class can be rewritten as this:

which will print:

As the priority rules imply that LoggerHandler wins because it is declared last, then a call to on will use the implementation from LoggingHandler . But the latter has a call to super , which means the next trait in the chain. Here, the next trait is DefaultHandler so both will be called:

The interest of this approach becomes more evident if we add a third handler, which is responsible for handling messages that start with say :

Then our final handler looks like this:

Which means:

messages will first go through the logging handler

the logging handler calls super which will delegate to the next handler, which is the SayHandler

if the message starts with say , then the handler consumes the message

if not, the say handler delegates to the next handler in the chain

This approach is very powerful because it allows you to write handlers that do not know each other and yet let you combine them in the order you want. For example, if we execute the code, it will print:

but if we move the logging handler to be the second one in the chain, the output is different:

The reason is that now, since the SayHandler consumes the message without calling super , the logging handler is not called anymore.

If a class implements multiple traits and a call to an unqualified super is found, then:

if the class implements another trait, the call delegates to the next trait in the chain

if there isn’t any trait left in the chain, super refers to the super class of the implementing class ( this )

For example, it is possible to decorate final classes thanks to this behavior:

In this example, when super.append is encountered, there is no other trait implemented by the target object, so the method which is called is the original append method, that is to say the one from StringBuilder . The same trick is used for toString , so that the string representation of the proxy object which is generated delegates to the toString of the StringBuilder instance.

Advanced features

If a trait defines a single abstract method, it is candidate for SAM (Single Abstract Method) type coercion. For example, imagine the following trait:

Since getName is the single abstract method in the Greeter trait, you can write:

In Java 8, interfaces can have default implementations of methods. If a class implements an interface and does not provide an implementation for a default method, then the implementation from the interface is chosen. Traits behave the same but with a major difference: the implementation from the trait is always used if the class declares the trait in its interface list and that it doesn’t provide an implementation even if a super class does.

This feature can be used to compose behaviors in a very precise way, in case you want to override the behavior of an already implemented method.

To illustrate the concept, let’s start with this simple example:

In this example, we create a simple test case which uses two properties ( config and shell ) and uses those in multiple test methods. Now imagine that you want to test the same, but with another distinct compiler configuration. One option is to create a subclass of SomeTest :

It works, but what if you have actually multiple test classes, and that you want to test the new configuration for all those test classes? Then you would have to create a distinct subclass for each test class:

Then what you see is that the setup method of both tests is the same. The idea, then, is to create a trait:

Then use it in the subclasses:

It would allow us to dramatically reduce the boilerplate code, and reduces the risk of forgetting to change the setup code in case we decide to change it. Even if setup is already implemented in the super class, since the test class declares the trait in its interface list, the behavior will be borrowed from the trait implementation!

This feature is in particular useful when you don’t have access to the super class source code. It can be used to mock methods or force a particular implementation of a method in a subclass. It lets you refactor your code to keep the overridden logic in a single trait and inherit a new behavior just by implementing it. The alternative, of course, is to override the method in every place you would have used the new code.

There are several conceptual differences with mixins, as they are available in Groovy. Note that we are talking about runtime mixins, not the @Mixin annotation which is deprecated in favour of traits.

First of all, methods defined in a trait are visible in bytecode:

internally, the trait is represented as an interface (without default or static methods) and several helper classes

this means that an object implementing a trait effectively implements an interface

those methods are visible from Java

they are compatible with type checking and static compilation

Methods added through a mixin are, on the contrary, only visible at runtime:

The last point is actually a very important and illustrates a place where mixins have an advantage over traits: the instances are not modified, so if you mixin some class into another, there isn’t a third class generated, and methods which respond to A will continue responding to A even if mixed in.

It is possible to define static methods in a trait, but it comes with numerous limitations:

Traits with static methods cannot be compiled statically or type checked. All static methods, properties and field are accessed dynamically (it’s a limitation from the JVM).

Static methods do not appear within the generated interfaces for each trait.

The trait is interpreted as a template for the implementing class, which means that each implementing class will get its own static methods, properties and fields. So a static member declared on a trait doesn’t belong to the Trait , but to its implementing class.

You should typically not mix static and instance methods of the same signature. The normal rules for applying traits apply (including multiple inheritance conflict resolution). If the method chosen is static but some implemented trait has an instance variant, a compilation error will occur. If the method chosen is the instance variant, the static variant will be ignored (the behavior is similar to static methods in Java interfaces for this case).

Let’s start with a simple example:

As usual, it is not recommended to use public fields. Anyway, should you want this, you must understand that the following code would fail:

because there is no static field CALLED defined on the trait itself. Likewise, if you have two distinct implementing classes, each one gets a distinct static field:

We have seen that traits are stateful. It is possible for a trait to define fields or properties, but when a class implements a trait, it gets those fields/properties on a per-trait basis. So consider the following example:

The trait defines two properties, x and y , as well as a sum method. Now let’s create a class which implements the trait:

The result of calling f is 3 , because f delegates to sum in the trait, which has state. But what if we write this instead?

If you call elem.f() , what is the expected output? Actually it is:

The reason is that the sum method accesses the fields of the trait. So it is using the x and y values defined in the trait. If you want to use the values from the implementing class, then you need to dereference fields by using getters and setters, like in this last example:

Sometimes you will want to write a trait that can only be applied to some type. For example, you may want to apply a trait on a class that extends another class which is beyond your control, and still be able to call those methods. To illustrate this, let’s start with this example:

It is clear, here, that the Communicating trait can only apply to Device . However, there’s no explicit contract to indicate that, because traits cannot extend classes. However, the code compiles and runs perfectly fine, because id in the trait method will be resolved dynamically. The problem is that there is nothing that prevents the trait from being applied to any class which is not a Device . Any class which has an id would work, while any class that does not have an id property would cause a runtime error.

The problem is even more complex if you want to enable type checking or apply @CompileStatic on the trait: because the trait knows nothing about itself being a Device , the type checker will complain saying that it does not find the id property.

One possibility is to explicitly add a getId method in the trait, but it would not solve all issues. What if a method requires this as a parameter, and actually requires it to be a Device ?

If you want to be able to call this in the trait, then you will explicitly need to cast this into a Device . This can quickly become unreadable with explicit casts to this everywhere.

In order to make this contract explicit, and to make the type checker aware of the type of itself , Groovy provides a @SelfType annotation that will:

let you declare the types that a class that implements this trait must inherit or implement

throw a compile-time error if those type constraints are not satisfied

So in our previous example, we can fix the trait using the @groovy.transform.SelfType annotation:

Now if you try to implement this trait on a class that is not a device, a compile-time error will occur:

The error will be:

In conclusion, self types are a powerful way of declaring constraints on traits without having to declare the contract directly in the trait or having to use casts everywhere, maintaining separation of concerns as tight as it should be.

Both @Sealed and @SelfType restrict classes which use a trait but in orthogonal ways. Consider the following example:

For the degenerate case where a single class implements a trait, e.g.:

Then, either:

could express this constraint. Generally, the former of these is preferred.

Limitations

Within traits, prefix and postfix operations are not allowed if they update a field of the trait:

A workaround is to use the += operator instead.

1.4.6. Record classes (incubating)

Record classes, or records for short, are a special kind of class useful for modelling plain data aggregates. They provide a compact syntax with less ceremony than normal classes. Groovy already has AST transforms such as @Immutable and @Canonical which already dramatically reduce ceremony but records have been introduced in Java and record classes in Groovy are designed to align with Java record classes.

For example, suppose we want to create a Message record representing an email message. For the purposes of this example, let’s simplify such a message to contain just a from email address, a to email address, and a message body . We can define such a record as follows:

We’d use the record class in the same way as a normal class, as shown below:

The reduced ceremony saves us from defining explicit fields, getters and toString , equals and hashCode methods. In fact, it’s a shorthand for the following rough equivalent:

Note the special naming convention for record getters. They are the same name as the field (rather than the often common JavaBean convention of capitalized with a "get" prefix). Rather than referring to a record’s fields or properties, the term component is typically used for records. So our Message record has from , to , and body components.

Like in Java, you can override the normally implicitly supplied methods by writing your own:

You can also use generics with records in the normal way. For example, consider the following Coord record definition:

It can be used as follows:

Special record features

Records have an implicit constructor. This can be overridden in the normal way by providing your own constructor - you need to make sure you set all the fields if you do this. However, for succinctness, a compact constructor syntax can be used where the parameter declaration part of a normal constructor is elided. For this special case, the normal implicit constructor is still provided but is augmented by the supplied statements in the compact constructor definition:

Groovy native records follow the special conventions for serializability which apply to Java records. Groovy record-like classes (discussed below) follow normal Java class serializability conventions.

Groovy enhancements

Groovy supports default values for constructor arguments. This capability is also available for records as shown in the following record definition which has default values for y and color :

Arguments when left off (dropping one or more arguments from the right) are replaced with their defaults values as shown in the following example:

This processing follows normal Groovy conventions for default arguments for constructors, essentially automatically providing the constructors with the following signatures:

Named arguments may also be used (default values also apply here):

You can disable default argument processing as shown here:

This will produce a single constructor as per the default with Java. It will be an error if you drop off arguments in this scenario.

You can force all properties to have a default value as shown here:

Any property/field without an explicit initial value will be given the default value for the argument’s type (null, or zero/false for primitives).

We previously described a Message record and displayed it’s rough equivalent. Groovy in fact steps through an intermediate stage where the record keyword is replaced by the class keyword and an accompanying @RecordType annotation:

Then @RecordType itself is processed as a meta-annotation (annotation collector) and expanded into its constituent sub-annotations such as @TupleConstructor , @POJO , @RecordBase , and others. This is in some sense an implementation detail which can often be ignored. However, if you wish to customise or configure the record implementation, you may wish to drop back to the @RecordType style or augment your record class with one of the constituent sub-annotations.

As per Java, you can customize a record’s toString method by writing your own. If you prefer a more declarative style, you can alternatively use Groovy’s @ToString transform to override the default record toString . As an example, you can a three-dimensional point record as follows:

We customise the toString by including the package name (excluded by default for records) and by caching the toString value since it won’t change for this immutable record. We are also ignoring null values (the default value for z in our definition).

We can have a similar definition for a two-dimensional point:

We can see here that without the package name it would have the same toString as our previous example.

We can obtain the component values from a record as a list like so:

You can use @RecordOptions(toList=false) to disable this feature.

We can obtain the component values from a record as a map like so:

You can use @RecordOptions(toMap=false) to disable this feature.

We can obtain the number of components in a record like so:

You can use @RecordOptions(size=false) to disable this feature.

We can use Groovy’s normal positional indexing to obtain a particular component in a record like so:

You can use @RecordOptions(getAt=false) to disable this feature.

Optional Groovy features

It can be useful to make a copy of a record with some components changed. This can be done using an optional copyWith method which takes named arguments. Record components are set from the supplied arguments. For components not mentioned, a (shallow) copy of the original record component is used. Here is how you might use copyWith for the Fruit record:

The copyWith functionality can be disabled by setting the RecordOptions#copyWith annotation attribute to false .

As with Java, records by default offer shallow immutability. Groovy’s @Immutable transform performs defensive copying for a range of mutable data types. Records can make use of this defensive copying to gain deep immutability as follows:

These examples illustrate the principal behind Groovy’s record feature offering three levels of convenience:

Using the record keyword for maximum succinctness

Supporting low-ceremony customization using declarative annotations

Allowing normal method implementations when full control is required

You can obtain the components of a record as a typed tuple:

Groovy has a limited number of TupleN classes. If you have a large number of components in your record, you might not be able to use this feature.

Groovy supports creating record-like classes as well as native records. Record-like classes don’t extend Java’s Record class and such classes won’t be seen by Java as records but will otherwise have similar properties.

The @RecordOptions annotation (part of @RecordType ) supports a mode annotation attribute which can take one of three values (with AUTO being the default):

Produces a class similar to what Java would do. Produces an error when compiling on JDKs earlier than JDK16.

Produces a record-like class for all JDK versions.

Produces a native record for JDK16+ and emulates the record otherwise.

Whether you use the record keyword or the @RecordType annotation is independent of the mode.

1.4.7. Sealed hierarchies (incubating)

Sealed classes, interfaces and traits restrict which subclasses can extend/implement them. Prior to sealed classes, class hierarchy designers had two main options:

Make a class final to allow no extension.

Make the class public and non-final to allow extension by anyone.

Sealed classes provide a middle-ground compared to these all or nothing choices.

Sealed classes are also more flexible than other tricks previously used to try to achieve a middle-ground. For example, for class hierarchies, access modifiers like protected and package-private give some ability to restrict inheritance hierarchies but often at the expense of flexible use of those hierarchies.

Sealed hierarchies provide full inheritance within a known hierarchy of classes, interfaces and traits but disable or only provide controlled inheritance outside the hierarchy.

As an example, suppose we want to create a shape hierarchy containing only circles and squares. We also want a shape interface to be able to refer to instances in our hierarchy. We can create the hierarchy as follows:

Groovy also supports an alternative annotation syntax. We think the keyword style is nicer but you might choose the annotation style if your editor doesn’t yet have Groovy 4 support.

We can have a reference of type ShapeI which, thanks to the permits clause, can point to either a Circle or Square and, since our classes are final , we know no additional classes will be added to our hierarchy in the future. At least not without changing the permits clause and recompiling.

In general, we might want to have some parts of our class hierarchy immediately locked down like we have here, where we marked the subclasses as final but other times we might want to allow further controlled inheritance.

  In this example, our permitted subclasses for Shape are Circle , Polygon , and Rectangle . Circle is final and hence that part of the hierarchy cannot be extended. Polygon is implicitly non-sealed and RegularPolygon is explicitly marked as non-sealed . That means our hierarchy is open to any further extension by subclassing, as seen with Polygon → RegularPolygon and RegularPolygon → Hexagon . Rectangle is itself sealed which means that part of the hierarchy can be extended but only in a controlled way (only Square is permitted).

Sealed classes are useful for creating enum-like related classes which need to contain instance specific data. For instance, we might have the following enum:

but we now wish to also add weather specific instance data to weather forecasts. We can alter our abstraction as follows:

Sealed hierarchies are also useful when specifying Algebraic or Abstract Data Types (ADTs) as shown in the following example:

Sealed hierarchies work well with records as shown in the following example:

Java provides no default modifier for subclasses of sealed classes and requires that one of final , sealed or non-sealed be specified. Groovy defaults to non-sealed but you can still use non-sealed/@NonSealed if you wish. We anticipate the style checking tool CodeNarc will eventually have a rule that looks for the presence of non-sealed so developers wanting that stricter style will be able to use CodeNarc and that rule if they want.

Currently, Groovy doesn’t check that all classes mentioned in permittedSubclasses are available at compile-time and compiled along with the base sealed class. This may change in a future version of Groovy.

Groovy supports annotating classes as sealed as well as "native" sealed classes.

The @SealedOptions annotation supports a mode annotation attribute which can take one of three values (with AUTO being the default):

Produces a class similar to what Java would do. Produces an error when compiling on JDKs earlier than JDK17.

Indicates the class is sealed using the @Sealed annotation. This mechanism works with the Groovy compiler for JDK8+ but is not recognised by the Java compiler.

Produces a native record for JDK17+ and emulates the record otherwise.

Whether you use the sealed keyword or the @Sealed annotation is independent of the mode.

1.5. Closures

This chapter covers Groovy Closures. A closure in Groovy is an open, anonymous, block of code that can take arguments, return a value and be assigned to a variable. A closure may reference variables declared in its surrounding scope. In opposition to the formal definition of a closure, Closure in the Groovy language can also contain free variables which are defined outside of its surrounding scope. While breaking the formal concept of a closure, it offers a variety of advantages which are described in this chapter.

1.5.1. Syntax

A closure definition follows this syntax:

Where [closureParameters->] is an optional comma-delimited list of parameters, and statements are 0 or more Groovy statements. The parameters look similar to a method parameter list, and these parameters may be typed or untyped.

When a parameter list is specified, the -> character is required and serves to separate the arguments from the closure body. The statements portion consists of 0, 1, or many Groovy statements.

Some examples of valid closure definitions:

A closure is an instance of the groovy.lang.Closure class, making it assignable to a variable or a field as any other variable, despite being a block of code:

A closure, as an anonymous block of code, can be called like any other method. If you define a closure which takes no argument like this:

Then the code inside the closure will only be executed when you call the closure, which can be done by using the variable as if it was a regular method:

Alternatively, you can be explicit and use the call method:

The principle is the same if the closure accepts arguments:

Unlike a method, a closure always returns a value when called. The next section discusses how to declare closure arguments, when to use them and what is the implicit "it" parameter .

1.5.2. Parameters

Parameters of closures follow the same principle as parameters of regular methods:

an optional default value

Parameters are separated with commas:

When a closure does not explicitly define a parameter list (using -> ), a closure always defines an implicit parameter, named it . This means that this code:

is strictly equivalent to this one:

If you want to declare a closure which accepts no argument and must be restricted to calls without arguments, then you must declare it with an explicit empty argument list:

It is possible for a closure to declare variable arguments like any other method. Vargs methods are methods that can accept a variable number of arguments if the last parameter is of variable length (or an array) like in the next examples:

1.5.3. Delegation strategy

Groovy defines closures as instances of the Closure class . It makes it very different from lambda expressions in Java 8 . Delegation is a key concept in Groovy closures which has no equivalent in lambdas. The ability to change the delegate or change the delegation strategy of closures make it possible to design beautiful domain specific languages (DSLs) in Groovy.

Owner, delegate and this

To understand the concept of delegate, we must first explain the meaning of this inside a closure. A closure actually defines 3 distinct things:

this corresponds to the enclosing class where the closure is defined

owner corresponds to the enclosing object where the closure is defined, which may be either a class or a closure

delegate corresponds to a third party object where methods calls or properties are resolved whenever the receiver of the message is not defined

In a closure, calling getThisObject will return the enclosing class where the closure is defined. It is equivalent to using an explicit this :

It is of course possible to call methods from the enclosing class this way:

The owner of a closure is very similar to the definition of this in a closure with a subtle difference: it will return the direct enclosing object, be it a closure or a class:

The delegate of a closure can be accessed by using the delegate property or calling the getDelegate method. It is a powerful concept for building domain specific languages in Groovy. While this and owner refer to the lexical scope of a closure, the delegate is a user defined object that a closure will use. By default, the delegate is set to owner :

The delegate of a closure can be changed to any object . Let’s illustrate this by creating two classes which are not subclasses of each other but both define a property called name :

Then let’s define a closure which fetches the name property on the delegate:

Then by changing the delegate of the closure, you can see that the target object will change:

At this point, the behavior is not different from having a target variable defined in the lexical scope of the closure:

However, there are major differences:

in the last example, target is a local variable referenced from within the closure

the delegate can be used transparently, that is to say without prefixing method calls with delegate. as explained in the next paragraph.

Whenever, in a closure, a property is accessed without explicitly setting a receiver object, then a delegation strategy is involved:

The reason this code works is that the name property will be resolved transparently on the delegate object! This is a very powerful way to resolve properties or method calls inside closures. There’s no need to set an explicit delegate. receiver: the call will be made because the default delegation strategy of the closure makes it so. A closure actually defines multiple resolution strategies that you can choose:

Closure.OWNER_FIRST is the default strategy . If a property/method exists on the owner , then it will be called on the owner. If not, then the delegate is used.

Closure.DELEGATE_FIRST reverses the logic: the delegate is used first, then the owner

Closure.OWNER_ONLY will only resolve the property/method lookup on the owner: the delegate will be ignored.

Closure.DELEGATE_ONLY will only resolve the property/method lookup on the delegate: the owner will be ignored.

Closure.TO_SELF can be used by developers who need advanced meta-programming techniques and wish to implement a custom resolution strategy: the resolution will not be made on the owner or the delegate but only on the closure class itself. It makes only sense to use this if you implement your own subclass of Closure .

Let’s illustrate the default "owner first" strategy with this code:

However, it is possible to change the resolution strategy of the closure:

By changing the resolveStrategy , we are modifying the way Groovy will resolve the "implicit this" references: in this case, name will first be looked in the delegate, then if not found, on the owner. Since name is defined in the delegate, an instance of Thing , then this value is used.

The difference between "delegate first" and "delegate only" or "owner first" and "owner only" can be illustrated if one of the delegate (resp. owner) does not have such a method or property:

In this example, we define two classes which both have a name property but only the Person class declares an age . The Person class also declares a closure which references age . We can change the default resolution strategy from "owner first" to "delegate only". Since the owner of the closure is the Person class, then we can check that if the delegate is an instance of Person , calling the closure is successful, but if we call it with a delegate being an instance of Thing , it fails with a groovy.lang.MissingPropertyException . Despite the closure being defined inside the Person class, the owner is not used.

When describing the "owner first" delegation strategy we spoke about using a property/method from the owner if it " existed " otherwise using the respective property/method from the delegate. And a similar story for "delegate first" but in reverse. Instead of using the word " existed ", it would have been more accurate to use the wording " handled ". That means that for "owner first", if the property/method exists in the owner, or it has a propertyMissing/methodMissing hook, then the owner will handle the member access.

We can see this in action with a slightly altered version of our previous example:

In this example, even though our instance of the Thing class (our delegate for the last use of cl ) has no age property, the fact that it handles the missing property via its propertyMissing hook, means that age will be -1 .

Take the following code:

The code behaves as you would expect, but what happens if you add:

You will see that the assert fails! There are two reasons for this:

a GString only evaluates lazily the toString representation of values

the syntax ${x} in a GString does not represent a closure but an expression to $x , evaluated when the GString is created.

In our example, the GString is created with an expression referencing x . When the GString is created, the value of x is 1, so the GString is created with a value of 1. When the assert is triggered, the GString is evaluated and 1 is converted to a String using toString . When we change x to 2, we did change the value of x , but it is a different object, and the GString still references the old one.

If you need a real closure in a GString and for example enforce lazy evaluation of variables, you need to use the alternate syntax ${→ x} like in the fixed example:

And let’s illustrate how it differs from mutation with this code:

So if you don’t want to rely on mutating objects or wrapping objects, you must use closures in GString by explicitly declaring an empty argument list:

Closures can be converted into interfaces or single-abstract method types. Please refer to this section of the manual for a complete description.

1.5.6. Functional programming

Closures, like lambda expressions in Java 8 are at the core of the functional programming paradigm in Groovy. Some functional programming operations on functions are available directly on the Closure class, like illustrated in this section.

In Groovy, currying refers to the concept of partial application. It does not correspond to the real concept of currying in functional programming because of the different scoping rules that Groovy applies on closures. Currying in Groovy will let you set the value of one parameter of a closure, and it will return a new closure accepting one less argument.

Left currying is the fact of setting the left-most parameter of a closure, like in this example:

Similarly to left currying, it is possible to set the right-most parameter of a closure:

In case a closure accepts more than 2 parameters, it is possible to set an arbitrary parameter using ncurry :

Memoization allows the result of the call of a closure to be cached. It is interesting if the computation done by a function (closure) is slow, but you know that this function is going to be called often with the same arguments. A typical example is the Fibonacci suite. A naive implementation may look like this:

It is a naive implementation because 'fib' is often called recursively with the same arguments, leading to an exponential algorithm:

computing fib(15) requires the result of fib(14) and fib(13)

computing fib(14) requires the result of fib(13) and fib(12)

Since calls are recursive, you can already see that we will compute the same values again and again, although they could be cached. This naive implementation can be "fixed" by caching the result of calls using memoize :

The behavior of the cache can be tweaked using alternate methods:

memoizeAtMost will generate a new closure which caches at most n values

memoizeAtLeast will generate a new closure which caches at least n values

memoizeBetween will generate a new closure which caches at least n values and at most n values

The cache used in all memoize variants is an LRU cache.

Closure composition corresponds to the concept of function composition, that is to say creating a new function by composing two or more functions (chaining calls), as illustrated in this example:

Recursive algorithms are often restricted by a physical limit: the maximum stack height. For example, if you call a method that recursively calls itself too deep, you will eventually receive a StackOverflowException .

An approach that helps in those situations is by using Closure and its trampoline capability.

Closures are wrapped in a TrampolineClosure . Upon calling, a trampolined Closure will call the original Closure waiting for its result. If the outcome of the call is another instance of a TrampolineClosure , created perhaps as a result to a call to the trampoline() method, the Closure will again be invoked. This repetitive invocation of returned trampolined Closures instances will continue until a value other than a trampolined Closure is returned. That value will become the final result of the trampoline. That way, calls are made serially, rather than filling the stack.

Here’s an example of the use of trampoline() to implement the factorial function:

It is often practical to be able to use a regular method as a closure. For example, you might want to use the currying abilities of a closure, but those are not available to normal methods. In Groovy, you can obtain a closure from any method with the method pointer operator .

1.6. Semantics

This chapter covers the semantics of the Groovy programming language.

1.6.1. Statements

Variables can be defined using either their type (like String ) or by using the keyword def (or var ) followed by a variable name:

def and var act as a type placeholder, i.e. a replacement for the type name, when you do not want to give an explicit type. It could be that you don’t care about the type at compile time or are relying on type inference (with Groovy’s static nature). It is mandatory for variable definitions to have a type or placeholder. If left out, the type name will be deemed to refer to an existing variable (presumably declared earlier). For scripts, undeclared variables are assumed to come from the Script binding. In other cases, you will get a missing property (dynamic Groovy) or compile time error (static Groovy). If you think of def and var as an alias of Object , you will understand in an instant.

Variable definitions can provide an initial value, in which case it’s like having a declaration and assignment (which we cover next) all in one.

Variable assignment

You can assign values to variables for later use. Try the following:

Groovy supports multiple assignment, i.e. where multiple variables can be assigned at once, e.g.:

You can provide types as part of the declaration if you wish:

As well as used when declaring variables it also applies to existing variables:

The syntax works for arrays as well as lists, as well as methods that return either of these:

If the left hand side has too many variables, excess ones are filled with null’s:

If the right hand side has too many variables, the extra ones are ignored:

In the section describing Groovy’s operators, the case of the subscript operator has been covered, explaining how you can override the getAt() / putAt() method.

With this technique, we can combine multiple assignments and the subscript operator methods to implement object destructuring .

Consider the following immutable Coordinates class, containing a pair of longitude and latitude doubles, and notice our implementation of the getAt() method:

Now let’s instantiate this class and destructure its longitude and latitude:

Control structures

Conditional structures.

Groovy supports the usual if - else syntax from Java

Groovy also supports the normal Java "nested" if then else if syntax:

The switch statement in Groovy is backwards compatible with Java code; so you can fall through cases sharing the same code for multiple matches.

One difference though is that the Groovy switch statement can handle any kind of switch value and different kinds of matching can be performed.

Switch supports the following kinds of comparisons:

Class case values match if the switch value is an instance of the class

Regular expression case values match if the toString() representation of the switch value matches the regex

Collection case values match if the switch value is contained in the collection. This also includes ranges (since they are Lists)

Closure case values match if the calling the closure returns a result which is true according to the Groovy truth

If none of the above are used then the case value matches if the case value equals the switch value

Groovy also supports switch expressions as shown in the following example:

Looping structures

Groovy supports the standard Java / C for loop:

The more elaborate form of Java’s classic for loop with comma-separate expressions is now supported. Example:

Groovy has supported multi-assignment statements since Groovy 1.6:

These can now appear in for loops:

The for loop in Groovy is much simpler and works with any kind of array, collection, Map, etc.

Groovy supports the usual while {…​} loops like Java:

Java’s class do/while loop is now supported. Example:

Exception handling is the same as Java.

You can specify a complete try-catch-finally , a try-catch , or a try-finally set of blocks.

We can put code within a 'finally' clause following a matching 'try' clause, so that regardless of whether the code in the 'try' clause throws an exception, the code in the finally clause will always execute:

With the multi catch block (since Groovy 2.0), we’re able to define several exceptions to be catch and treated by the same catch block:

Groovy often provides better alternatives to Java 7’s try -with-resources statement for Automatic Resource Management (ARM). That syntax is now supported for Java programmers migrating to Groovy and still wanting to use the old style:

Which yields the following output:

Unlike Java with which Groovy shares the assert keyword, the latter in Groovy behaves very differently. First of all, an assertion in Groovy is always executed, independently of the -ea flag of the JVM. It makes this a first class choice for unit tests. The notion of "power asserts" is directly related to how the Groovy assert behaves.

A power assertion is decomposed into 3 parts:

The result of the assertion is very different from what you would get in Java. If the assertion is true, then nothing happens. If the assertion is false, then it provides a visual representation of the value of each sub-expressions of the expression being asserted. For example:

Will yield:

Power asserts become very interesting when the expressions are more complex, like in the next example:

Which will print the value for each sub-expression:

In case you don’t want a pretty printed error message like above, you can fall back to a custom error message by changing the optional message part of the assertion, like in this example:

Which will print the following error message:

Any statement can be associated with a label. Labels do not impact the semantics of the code and can be used to make the code easier to read like in the following example:

Despite not changing the semantics of the labelled statement, it is possible to use labels in the break instruction as a target for jump, as in the next example. However, even if this is allowed, this coding style is in general considered a bad practice:

It is important to understand that by default labels have no impact on the semantics of the code, however they belong to the abstract syntax tree (AST) so it is possible for an AST transformation to use that information to perform transformations over the code, hence leading to different semantics. This is in particular what the Spock Framework does to make testing easier.

1.6.2. Expressions

Expressions are the building blocks of Groovy programs that are used to reference existing values and execute code to create new ones.

Groovy supports many of the same kinds of expressions as Java, including:

Groovy also has some of its own special expressions:

Groovy also expands on the normal dot-notation used in Java for member access. Groovy provides special support for accessing hierarchical data structures by specifying the path in the hierarchy of some data of interest. These Groovy path expressions are known as GPath expressions.

GPath expressions

GPath is a path expression language integrated into Groovy which allows parts of nested structured data to be identified. In this sense, it has similar aims and scope as XPath does for XML. GPath is often used in the context of processing XML, but it really applies to any object graph. Where XPath uses a filesystem-like path notation, a tree hierarchy with parts separated by a slash / , GPath use a dot-object notation to perform object navigation.

As an example, you can specify a path to an object or element of interest:

a.b.c → for XML, yields all the c elements inside b inside a

a.b.c → for POJOs, yields the c properties for all the b properties of a (sort of like a.getB().getC() in JavaBeans)

In both cases, the GPath expression can be viewed as a query on an object graph. For POJOs, the object graph is most often built by the program being written through object instantiation and composition; for XML processing, the object graph is the result of parsing the XML text, most often with classes like XmlParser or XmlSlurper. See Processing XML for more in-depth details on consuming XML in Groovy.

Let’s see an example of a GPath expression on a simple object graph , the one obtained using java reflection. Suppose you are in a non-static method of a class having another method named aMethodFoo

the following GPath expression will get the name of that method:

More precisely , the above GPath expression produces a list of String, each being the name of an existing method on this where that name ends with Foo .

Now, given the following methods also defined in that class:

then the following GPath expression will get the names of (1) and (3) , but not (2) or (0) :

We can decompose the expression this.class.methods.name.grep(~/.*Bar/) to get an idea of how a GPath is evaluated:

property accessor, equivalent to this.getClass() in Java, yields a Class object.

property accessor, equivalent to this.getClass().getMethods() , yields an array of Method objects.

apply a property accessor on each element of an array and produce a list of the results.

call method grep on each element of the list yielded by this.class.methods.name and produce a list of the results.

One powerful feature of GPath expression is that property access on a collection is converted to a property access on each element of the collection with the results collected into a collection. Therefore, the expression this.class.methods.name could be expressed as follows in Java:

Array access notation can also be used in a GPath expression where a collection is present :

Here is an example with an XML document and various form of GPath expressions:

Further details about GPath expressions for XML are in the XML User Guide .

1.6.3. Promotion and coercion

The rules of number promotion are specified in the section on math operations .

Closure to type coercion

A SAM type is a type which defines a single abstract method. This includes:

Any closure can be converted into a SAM type using the as operator:

However, the as Type expression is optional since Groovy 2.2.0. You can omit it and simply write:

which means you are also allowed to use method pointers, as shown in the following example:

The second and probably more important use case for closure to SAM type coercion is calling a method which accepts a SAM type. Imagine the following method:

Then you can call it with a closure, without having to create an explicit implementation of the interface:

But since Groovy 2.2.0, you are also able to omit the explicit coercion and call the method as if it used a closure:

As you can see, this has the advantage of letting you use the closure syntax for method calls, that is to say put the closure outside the parenthesis, improving the readability of your code.

In addition to SAM types, a closure can be coerced to any type and in particular interfaces. Let’s define the following interface:

You can coerce a closure into the interface using the as keyword:

This produces a class for which all methods are implemented using the closure:

But it is also possible to coerce a closure to any class. For example, we can replace the interface that we defined with class without changing the assertions:

Usually using a single closure to implement an interface or a class with multiple methods is not the way to go. As an alternative, Groovy allows you to coerce a map into an interface or a class. In that case, keys of the map are interpreted as method names, while the values are the method implementation. The following example illustrates the coercion of a map into an Iterator :

Of course this is a rather contrived example, but illustrates the concept. You only need to implement those methods that are actually called, but if a method is called that doesn’t exist in the map a MissingMethodException or an UnsupportedOperationException is thrown, depending on the arguments passed to the call, as in the following example:

The type of the exception depends on the call itself:

MissingMethodException if the arguments of the call do not match those from the interface/class

UnsupportedOperationException if the arguments of the call match one of the overloaded methods of the interface/class

Groovy allows transparent String (or GString ) to enum values coercion. Imagine you define the following enum:

then you can assign a string to the enum without having to use an explicit as coercion:

It is also possible to use a GString as the value:

However, this would throw a runtime error ( IllegalArgumentException ):

Note that it is also possible to use implicit coercion in switch statements:

in particular, see how the case use string constants. But if you call a method that uses an enum with a String argument, you still have to use an explicit as coercion:

It is possible for a class to define custom coercion strategies by implementing the asType method. Custom coercion is invoked using the as operator and is never implicit. As an example, imagine you defined two classes, Polar and Cartesian , like in the following example:

And that you want to convert from polar coordinates to cartesian coordinates. One way of doing this is to define the asType method in the Polar class:

which allows you to use the as coercion operator:

Putting it all together, the Polar class looks like this:

but it is also possible to define asType outside of the Polar class, which can be practical if you want to define custom coercion strategies for "closed" classes or classes for which you don’t own the source code, for example using a metaclass:

Using the as keyword is only possible if you have a static reference to a class, like in the following code:

But what if you get the class by reflection, for example by calling Class.forName ?

Trying to use the reference to the class with the as keyword would fail:

It is failing because the as keyword only works with class literals. Instead, you need to call the asType method:

1.6.4. Optionality

Method calls can omit the parentheses if there is at least one parameter and there is no ambiguity:

Parentheses are required for method calls without parameters or ambiguous method calls:

In Groovy semicolons at the end of the line can be omitted, if the line contains only a single statement.

This means that:

can be more idiomatically written as:

Multiple statements in a line require semicolons to separate them:

In Groovy, the last expression evaluated in the body of a method or a closure is returned. This means that the return keyword is optional.

Can be shortened to:

By default, Groovy classes and methods are public . Therefore this class:

is identical to this class:

1.6.5. The Groovy Truth

Groovy decides whether an expression is true or false by applying the rules given below.

True if the corresponding Boolean value is true .

Non-empty Collections and arrays are true.

True if the Matcher has at least one match.

Iterators and Enumerations with further elements are coerced to true.

Non-empty Maps are evaluated to true.

Non-empty Strings, GStrings and CharSequences are coerced to true.

Non-zero numbers are true.

Non-null object references are coerced to true.

In order to customize whether groovy evaluates your object to true or false implement the asBoolean() method:

Groovy will call this method to coerce your object to a boolean value, e.g.:

1.6.6. Typing

Optional typing is the idea that a program can work even if you don’t put an explicit type on a variable. Being a dynamic language, Groovy naturally implements that feature, for example when you declare a variable:

Groovy will let you write this instead:

So it doesn’t matter that you use an explicit type here. It is in particular interesting when you combine this feature with static type checking , because the type checker performs type inference.

Likewise, Groovy doesn’t make it mandatory to declare the types of a parameter in a method:

can be rewritten using def as both return type and parameter types, in order to take advantage of duck typing, as illustrated in this example:

Eventually, the type can be removed altogether from both the return type and the descriptor. But if you want to remove it from the return type, you then need to add an explicit modifier for the method, so that the compiler can make a difference between a method declaration and a method call, like illustrated in this example:

Static type checking

By default, Groovy performs minimal type checking at compile time. Since it is primarily a dynamic language, most checks that a static compiler would normally do aren’t possible at compile time. A method added via runtime metaprogramming might alter a class or object’s runtime behavior. Let’s illustrate why in the following example:

It is quite common in dynamic languages for code such as the above example not to throw any error. How can this be? In Java, this would typically fail at compile time. However, in Groovy, it will not fail at compile time, and if coded correctly, will also not fail at runtime. In fact, to make this work at runtime, one possibility is to rely on runtime metaprogramming. So just adding this line after the declaration of the Person class is enough:

This means that in general, in Groovy, you can’t make any assumption about the type of an object beyond its declaration type, and even if you know it, you can’t determine at compile time what method will be called, or which property will be retrieved. It has a lot of interest, going from writing DSLs to testing, which is discussed in other sections of this manual.

However, if your program doesn’t rely on dynamic features and that you come from the static world (in particular, from a Java mindset), not catching such "errors" at compile time can be surprising. As we have seen in the previous example, the compiler cannot be sure this is an error. To make it aware that it is, you have to explicitly instruct the compiler that you are switching to a type checked mode. This can be done by annotating a class or a method with @groovy.transform.TypeChecked .

When type checking is activated, the compiler performs much more work:

type inference is activated, meaning that even if you use def on a local variable for example, the type checker will be able to infer the type of the variable from the assignments

method calls are resolved at compile time, meaning that if a method is not declared on a class, the compiler will throw an error

in general, all the compile time errors that you are used to find in a static language will appear: method not found, property not found, incompatible types for method calls, number precision errors, …​

In this section, we will describe the behavior of the type checker in various situations and explain the limits of using @TypeChecked on your code.

The @TypeChecked annotation

The groovy.transform.TypeChecked annotation enables type checking. It can be placed on a class:

Or on a method:

In the first case, all methods, properties, fields, inner classes, …​ of the annotated class will be type checked, whereas in the second case, only the method and potential closures or anonymous inner classes that it contains will be type checked.

The scope of type checking can be restricted. For example, if a class is type checked, you can instruct the type checker to skip a method by annotating it with @TypeChecked(TypeCheckingMode.SKIP) :

In the previous example, SentenceBuilder relies on dynamic code. There’s no real Hello method or property, so the type checker would normally complain and compilation would fail. Since the method that uses the builder is marked with TypeCheckingMode.SKIP , type checking is skipped for this method, so the code will compile, even if the rest of the class is type checked.

The following sections describe the semantics of type checking in Groovy.

An object o of type A can be assigned to a variable of type T if and only if:

or T is one of String , boolean , Boolean or Class

or o is null and T is not a primitive type

or T is an array and A is an array and the component type of A is assignable to the component type of T

or T is an array and A is a collection or stream and the component type of A is assignable to the component type of T

or T is a superclass of A

or T is an interface implemented by A

or T or A are a primitive type and their boxed types are assignable

or T extends groovy.lang.Closure and A is a SAM-type (single abstract method type)

or T and A derive from java.lang.Number and conform to the following table

In addition to the assignment rules above, if an assignment is deemed invalid, in type checked mode, a list literal or a map literal A can be assigned to a variable of type T if:

the assignment is a variable declaration and A is a list literal and T has a constructor whose parameters match the types of the elements in the list literal

the assignment is a variable declaration and A is a map literal and T has a no-arg constructor and a property for each of the map keys

For example, instead of writing:

You can use a "list constructor":

or a "map constructor":

If you use a map constructor, additional checks are done on the keys of the map to check if a property of the same name is defined. For example, the following will fail at compile time:

In type checked mode, methods are resolved at compile time. Resolution works by name and arguments. The return type is irrelevant to method selection. Types of arguments are matched against the types of the parameters following those rules:

An argument o of type A can be used for a parameter of type T if and only if:

or T is a String and A is a GString

or T and A derive from java.lang.Number and conform to the same rules as assignment of numbers

If a method with the appropriate name and arguments is not found at compile time, an error is thrown. The difference with "normal" Groovy is illustrated in the following example:

The example above shows a class that Groovy will be able to compile. However, if you try to create an instance of MyService and call the doSomething method, then it will fail at runtime , because printLine doesn’t exist. Of course, we already showed how Groovy could make this a perfectly valid call, for example by catching MethodMissingException or implementing a custom metaclass, but if you know you’re not in such a case, @TypeChecked comes handy:

Just adding @TypeChecked will trigger compile time method resolution. The type checker will try to find a method printLine accepting a String on the MyService class, but cannot find one. It will fail compilation with the following message:

Cannot find matching method MyService#printLine(java.lang.String)

There are possible workarounds, like introducing an interface, but basically, by activating type checking, you gain type safety but you loose some features of the language. Hopefully, Groovy introduces some features like flow typing to reduce the gap between type-checked and non type-checked Groovy.

Type inference

When code is annotated with @TypeChecked , the compiler performs type inference. It doesn’t simply rely on static types, but also uses various techniques to infer the types of variables, return types, literals, …​ so that the code remains as clean as possible even if you activate the type checker.

The simplest example is inferring the type of a variable:

The reason the call to toUpperCase works is because the type of message was inferred as being a String .

It is worth noting that although the compiler performs type inference on local variables, it does not perform any kind of type inference on fields, always falling back to the declared type of a field. To illustrate this, let’s take a look at this example:

Why such a difference? The reason is thread safety . At compile time, we can’t make any guarantee about the type of a field. Any thread can access any field at any time and between the moment a field is assigned a variable of some type in a method and the time is used the line after, another thread may have changed the contents of the field. This is not the case for local variables: we know if they "escape" or not, so we can make sure that the type of a variable is constant (or not) over time. Note that even if a field is final, the JVM makes no guarantee about it, so the type checker doesn’t behave differently if a field is final or not.

Groovy provides a syntax for various type literals. There are three native collection literals in Groovy:

lists, using the [] literal

maps, using the [:] literal

ranges, using from..to (inclusive), from..<to (right exclusive), from<..to (left exclusive) and from<..<to (full exclusive)

The inferred type of a literal depends on the elements of the literal, as illustrated in the following table:

As you can see, with the noticeable exception of the IntRange , the inferred type makes use of generics types to describe the contents of a collection. In case the collection contains elements of different types, the type checker still performs type inference of the components, but uses the notion of least upper bound .

In Groovy, the least upper bound of two types A and B is defined as a type which:

superclass corresponds to the common super class of A and B

interfaces correspond to the interfaces implemented by both A and B

if A or B is a primitive type and that A isn’t equal to B , the least upper bound of A and B is the least upper bound of their wrapper types

If A and B only have one (1) interface in common and that their common superclass is Object , then the LUB of both is the common interface.

The least upper bound represents the minimal type to which both A and B can be assigned. So for example, if A and B are both String , then the LUB (least upper bound) of both is also String .

In those examples, the LUB is always representable as a normal, JVM supported, type. But Groovy internally represents the LUB as a type which can be more complex, and that you wouldn’t be able to use to define a variable for example. To illustrate this, let’s continue with this example:

What is the least upper bound of Bottom and SerializableFooImpl ? They don’t have a common super class (apart from Object ), but they do share 2 interfaces ( Serializable and Foo ), so their least upper bound is a type which represents the union of two interfaces ( Serializable and Foo ). This type cannot be defined in the source code, yet Groovy knows about it.

In the context of collection type inference (and generic type inference in general), this becomes handy, because the type of the components is inferred as the least upper bound. We can illustrate why this is important in the following example:

The error message will look like:

which indicates that the exit method is neither defines on Greeter nor Salute , which are the two interfaces defined in the least upper bound of A and B .

In normal, non type checked, Groovy, you can write things like:

The method call works because of dynamic dispatch (the method is selected at runtime). The equivalent code in Java would require to cast o to a Greeter before calling the greeting method, because methods are selected at compile time:

However, in Groovy, even if you add @TypeChecked (and thus activate type checking) on the doSomething method, the cast is not necessary. The compiler embeds instanceof inference that makes the cast optional.

Flow typing is an important concept of Groovy in type checked mode and an extension of type inference. The idea is that the compiler is capable of inferring the type of variables in the flow of the code, not just at initialization:

So the type checker is aware of the fact that the concrete type of a variable is different over time. In particular, if you replace the last assignment with:

The type checker will now fail at compile time, because it knows that o is a double when toUpperCase is called, so it’s a type error.

It is important to understand that it is not the fact of declaring a variable with def that triggers type inference. Flow typing works for any variable of any type. Declaring a variable with an explicit type only constrains what you can assign to the variable:

You can also note that even if the variable is declared without generics information, the type checker knows what is the component type. Therefore, such code would fail compilation:

Fixing this requires adding an explicit generic type to the declaration:

Flow typing has been introduced to reduce the difference in semantics between classic and static Groovy. In particular, consider the behavior of this code in Java:

In Java, this code will output Nope , because method selection is done at compile time and based on the declared types. So even if o is a String at runtime, it is still the Object version which is called, because o has been declared as an Object . To be short, in Java, declared types are most important, be it variable types, parameter types or return types.

In Groovy, we could write:

But this time, it will return 6 , because the method which is chosen at runtime , based on the actual argument types. So at runtime, o is a String so the String variant is used. Note that this behavior has nothing to do with type checking, it’s the way Groovy works in general: dynamic dispatch.

In type checked Groovy, we want to make sure the type checker selects the same method at compile time , that the runtime would choose. It is not possible in general, due to the semantics of the language, but we can make things better with flow typing. With flow typing, o is inferred as a String when the compute method is called, so the version which takes a String and returns an int is chosen. This means that we can infer the return type of the method to be an int , and not a String . This is important for subsequent calls and type safety.

So in type checked Groovy, flow typing is a very important concept, which also implies that if @TypeChecked is applied, methods are selected based on the inferred types of the arguments, not on the declared types. This doesn’t ensure 100% type safety, because the type checker may select a wrong method, but it ensures the closest semantics to dynamic Groovy.

A combination of flow typing and least upper bound inference is used to perform advanced type inference and ensure type safety in multiple situations. In particular, program control structures are likely to alter the inferred type of a variable:

When the type checker visits an if/else control structure, it checks all variables which are assigned in if/else branches and computes the least upper bound of all assignments. This type is the type of the inferred variable after the if/else block, so in this example, o is assigned a Top in the if branch and a Bottom in the else branch. The LUB of those is a Top , so after the conditional branches, the compiler infers o as being a Top . Calling methodFromTop will therefore be allowed, but not methodFromBottom .

The same reasoning exists with closures and in particular closure shared variables. A closure shared variable is a variable which is defined outside of a closure, but used inside a closure, as in this example:

Groovy allows developers to use those variables without requiring them to be final. This means that a closure shared variable can be reassigned inside a closure:

The problem is that a closure is an independent block of code that can be executed (or not) at any time. In particular, doSomething may be asynchronous, for example. This means that the body of a closure doesn’t belong to the main control flow. For that reason, the type checker also computes, for each closure shared variable, the LUB of all assignments of the variable, and will use that LUB as the inferred type outside of the scope of the closure, like in this example:

Here, it is clear that when methodFromBottom is called, there’s no guarantee, at compile-time or runtime that the type of o will effectively be a Bottom . There are chances that it will be, but we can’t make sure, because it’s asynchronous. So the type checker will only allow calls on the least upper bound , which is here a Top .

Closures and type inference

The type checker performs special inference on closures, resulting on additional checks on one side and improved fluency on the other side.

The first thing that the type checker is capable of doing is inferring the return type of a closure. This is simply illustrated in the following example:

As you can see, unlike a method which declares its return type explicitly, there’s no need to declare the return type of a closure: its type is inferred from the body of the closure.

It’s worth noting that return type inference is only applicable to closures. While the type checker could do the same on a method, it is in practice not desirable: in general , methods can be overridden and it is not statically possible to make sure that the method which is called is not an overridden version. So flow typing would actually think that a method returns something, while in reality, it could return something else, like illustrated in the following example:

As you can see, if the type checker relied on the inferred return type of a method, with flow typing , the type checker could determine that it is ok to call toUpperCase . It is in fact an error , because a subclass can override compute and return a different object. Here, B#compute returns an int , so someone calling computeFully on an instance of B would see a runtime error. The compiler prevents this from happening by using the declared return type of methods instead of the inferred return type.

For consistency, this behavior is the same for every method, even if they are static or final.

In addition to the return type, it is possible for a closure to infer its parameter types from the context. There are two ways for the compiler to infer the parameter types:

through implicit SAM type coercion

through API metadata

To illustrate this, lets start with an example that will fail compilation due to the inability for the type checker to infer the parameter types:

In this example, the closure body contains it.age . With dynamic, not type checked code, this would work, because the type of it would be a Person at runtime. Unfortunately, at compile-time, there’s no way to know what is the type of it , just by reading the signature of inviteIf .

To be short, the type checker doesn’t have enough contextual information on the inviteIf method to determine statically the type of it . This means that the method call needs to be rewritten like this:

By explicitly declaring the type of the it variable, you can work around the problem and make this code statically checked.

For an API or framework designer, there are two ways to make this more elegant for users, so that they don’t have to declare an explicit type for the closure parameters. The first one, and easiest, is to replace the closure with a SAM type:

The original issue that needs to be solved when it comes to closure parameter type inference, that is to say, statically determining the types of the arguments of a closure without having to have them explicitly declared, is that the Groovy type system inherits the Java type system, which is insufficient to describe the types of the arguments.

Groovy provides an annotation, @ClosureParams which is aimed at completing type information. This annotation is primarily aimed at framework and API developers who want to extend the capabilities of the type checker by providing type inference metadata. This is important if your library makes use of closures and that you want the maximum level of tooling support too.

Let’s illustrate this by fixing the original example, introducing the @ClosureParams annotation:

The @ClosureParams annotation minimally accepts one argument, which is named a type hint . A type hint is a class which is responsible for completing type information at compile time for the closure. In this example, the type hint being used is groovy.transform.stc.FirstParam which indicated to the type checker that the closure will accept one parameter whose type is the type of the first parameter of the method. In this case, the first parameter of the method is Person , so it indicates to the type checker that the first parameter of the closure is in fact a Person .

A second optional argument is named options . Its semantics depend on the type hint class. Groovy comes with various bundled type hints, illustrated in the table below:

In short, the lack of the @ClosureParams annotation on a method accepting a Closure will not fail compilation. If present (and it can be present in Java sources as well as Groovy sources), then the type checker has more information and can perform additional type inference. This makes this feature particularly interesting for framework developers.

A third optional argument is named conflictResolutionStrategy . It can reference a class (extending from ClosureSignatureConflictResolver ) that can perform additional resolution of parameter types if more than one are found after initial inference calculations are complete. Groovy comes with a default type resolver which does nothing, and another which selects the first signature if multiple are found. The resolver is only invoked if more than one signature is found and is by design a post processor. Any statements which need injected typing information must pass one of the parameter signatures determined through type hints. The resolver then picks among the returned candidate signatures.

The @DelegatesTo annotation is used by the type checker to infer the type of the delegate. It allows the API designer to instruct the compiler what is the type of the delegate and the delegation strategy. The @DelegatesTo annotation is discussed in a specific section .

Static compilation

In the type checking section , we have seen that Groovy provides optional type checking thanks to the @TypeChecked annotation. The type checker runs at compile time and performs a static analysis of dynamic code. The program will behave exactly the same whether type checking has been enabled or not. This means that the @TypeChecked annotation is neutral in regard to the semantics of a program. Even though it may be necessary to add type information in the sources so that the program is considered type safe, in the end, the semantics of the program are the same.

While this may sound fine, there is actually one issue with this: type checking of dynamic code, done at compile time, is by definition only correct if no runtime specific behavior occurs. For example, the following program passes type checking:

There are two compute methods. One accepts a String and returns an int , the other accepts an int and returns a String . If you compile this, it is considered type safe: the inner compute('foobar') call will return an int , and calling compute on this int will in turn return a String .

Now, before calling test() , consider adding the following line:

Using runtime metaprogramming, we’re actually modifying the behavior of the compute(String) method, so that instead of returning the length of the provided argument, it will return a Date . If you execute the program, it will fail at runtime. Since this line can be added from anywhere, in any thread, there’s absolutely no way for the type checker to statically make sure that no such thing happens. In short, the type checker is vulnerable to monkey patching. This is just one example, but this illustrates the concept that doing static analysis of a dynamic program is inherently wrong.

The Groovy language provides an alternative annotation to @TypeChecked which will actually make sure that the methods which are inferred as being called will effectively be called at runtime. This annotation turns the Groovy compiler into a static compiler , where all method calls are resolved at compile time and the generated bytecode makes sure that this happens: the annotation is @groovy.transform.CompileStatic .

The @CompileStatic annotation can be added anywhere the @TypeChecked annotation can be used, that is to say on a class or a method. It is not necessary to add both @TypeChecked and @CompileStatic , as @CompileStatic performs everything @TypeChecked does, but in addition triggers static compilation.

Let’s take the example which failed , but this time let’s replace the @TypeChecked annotation with @CompileStatic :

This is the only difference. If we execute this program, this time, there is no runtime error. The test method became immune to monkey patching, because the compute methods which are called in its body are linked at compile time, so even if the metaclass of Computer changes, the program still behaves as expected by the type checker .

There are several benefits of using @CompileStatic on your code:

type safety

immunity to monkey patching

performance improvements

The performance improvements depend on the kind of program you are executing. If it is I/O bound, the difference between statically compiled code and dynamic code is barely noticeable. On highly CPU intensive code, since the bytecode which is generated is very close, if not equal, to the one that Java would produce for an equivalent program, the performance is greatly improved.

1.6.7. Type checking extensions

Writing a type checking extension.

Despite being a dynamic language, Groovy can be used with a static type checker at compile time, enabled using the @TypeChecked annotation. In this mode, the compiler becomes more verbose and throws errors for, example, typos, non-existent methods, etc. This comes with a few limitations though, most of them coming from the fact that Groovy remains inherently a dynamic language. For example, you wouldn’t be able to use type checking on code that uses the markup builder:

In the previous example, none of the html , head , body or p methods exist. However if you execute the code, it works because Groovy uses dynamic dispatch and converts those method calls at runtime. In this builder, there’s no limitation about the number of tags that you can use, nor the attributes, which means there is no chance for a type checker to know about all the possible methods (tags) at compile time, unless you create a builder dedicated to HTML for example.

Groovy is a platform of choice when it comes to implement internal DSLs. The flexible syntax, combined with runtime and compile-time metaprogramming capabilities make Groovy an interesting choice because it allows the programmer to focus on the DSL rather than on tooling or implementation. Since Groovy DSLs are Groovy code, it’s easy to have IDE support without having to write a dedicated plugin for example.

In a lot of cases, DSL engines are written in Groovy (or Java) then user code is executed as scripts, meaning that you have some kind of wrapper on top of user logic. The wrapper may consist, for example, in a GroovyShell or GroovyScriptEngine that performs some tasks transparently before running the script (adding imports, applying AST transforms, extending a base script,…). Often, user written scripts come to production without testing because the DSL logic comes to a point where  any user may write code using the DSL syntax. In the end, a user may just ignore that what they write is actually  code . This adds some challenges for the DSL implementer, such as securing execution of user code or, in this case, early reporting of errors.

For example, imagine a DSL which goal is to drive a rover on Mars remotely. Sending a message to the rover takes around 15 minutes. If the rover executes the script and fails with an error (say a typo), you have two problems:

first, feedback comes only after 30 minutes (the time needed for the rover to get the script and the time needed to receive the error)

second, some portion of the script has been executed and you may have to change the fixed script significantly (implying that you need to know the current state of the rover…)

Type checking extensions is a mechanism that will allow the developer of a DSL engine to make those scripts safer by applying the same kind of checks that static type checking allows on regular groovy classes.

The principle, here, is to fail early, that is to say fail compilation of scripts as soon as possible, and if possible provide feedback to the user (including nice error messages).

In short, the idea behind type checking extensions is to make the compiler aware of all the runtime metaprogramming tricks that the DSL uses, so that scripts can benefit the same level of compile-time checks as a verbose statically compiled code would have. We will see that you can go even further by performing checks that a normal type checker wouldn’t do, delivering powerful compile-time checks for your users.

The  @TypeChecked annotation supports an attribute named  extensions . This parameter takes an array of strings corresponding to a list of type checking extensions scripts . Those scripts are found at  compile time on classpath. For example, you would write:

In that case, the  foo methods would be type checked with the rules of the normal type checker completed by those found in the  myextension.groovy script. Note that while internally the type checker supports multiple mechanisms to implement type checking extensions (including plain old java code), the recommended way is to use those type checking extension scripts.

The idea behind type checking extensions is to use a DSL to extend the type checker capabilities. This DSL allows you to hook into the compilation process, more specifically the type checking phase, using an "event-driven" API. For example, when the type checker enters a method body, it throws a  beforeVisitMethod event that the extension can react to:

Imagine that you have this rover DSL at hand. A user would write:

If you have a class defined as such:

The script can be type checked before being executed using the following script:

Using the compiler configuration above, we can apply  @TypeChecked transparently to the script. In that case, it will fail at compile time:

Now, we will slightly update the configuration to include the ``extensions'' parameter:

Then add the following to your classpath:

Here, we’re telling the compiler that if an unresolved variable is found and that the name of the variable is  robot , then we can make sure that the type of this variable is Robot .

Type checking extensions API

The type checking API is a low level API, dealing with the Abstract Syntax Tree. You will have to know your AST well to develop extensions, even if the DSL makes it much easier than just dealing with AST code from plain Java or Groovy.

The type checker sends the following events, to which an extension script can react:

Of course, an extension script may consist of several blocks, and you can have multiple blocks responding to the same event. This makes the DSL look nicer and easier to write. However, reacting to events is far from sufficient. If you know you can react to events, you also need to deal with the errors, which implies several helper methods that will make things easier.

Working with extensions

The DSL relies on a support class called  org.codehaus.groovy.transform.stc.GroovyTypeCheckingExtensionSupport . This class itself extends  org.codehaus.groovy.transform.stc.TypeCheckingExtension . Those two classes define a number of helper methods that will make working with the AST easier, especially regarding type checking. One interesting thing to know is that you  have access to the type checker . This means that you can programmatically call methods of the type checker, including those that allow you to throw compilation errors .

The extension script delegates to the  org.codehaus.groovy.transform.stc.GroovyTypeCheckingExtensionSupport class, meaning that you have direct access to the following variables:

context : the type checker context, of type  org.codehaus.groovy.transform.stc.TypeCheckingContext

typeCheckingVisitor : the type checker itself, a  org.codehaus.groovy.transform.stc.StaticTypeCheckingVisitor instance

generatedMethods : a list of "generated methods", which is in fact the list of "dummy" methods that you can create inside a type checking extension using the  newMethod calls

The type checking context contains a lot of information that is useful in context for the type checker. For example, the current stack of enclosing method calls, binary expressions, closures, … This information is in particular important if you have to know where you are when an error occurs and that you want to handle it.

In addition to facilities provided by GroovyTypeCheckingExtensionSupport and StaticTypeCheckingVisitor , a type-checking DSL script imports static members from org.codehaus.groovy.ast.ClassHelper and org.codehaus.groovy.transform.stc.StaticTypeCheckingSupport granting access to common types via OBJECT_TYPE , STRING_TYPE , THROWABLE_TYPE , etc. and checks like missesGenericsTypes(ClassNode) , isClassClassNodeWrappingConcreteType(ClassNode) and so on.

Handling class nodes is something that needs particular attention when you work with a type checking extension. Compilation works with an abstract syntax tree (AST) and the tree may not be complete when you are type checking a class. This also means that when you refer to types, you must not use class literals such as  String or  HashSet , but to class nodes representing those types. This requires a certain level of abstraction and understanding how Groovy deals with class nodes. To make things easier, Groovy supplies several helper methods to deal with class nodes. For example, if you want to say "the type for String", you can write:

You would also note that there is a variant of  classNodeFor that takes a  String as an argument, instead of a  Class . In general, you should  not use that one, because it would create a class node for which the name is String , but without any method, any property, … defined on it. The first version returns a class node that is  resolved but the second one returns one that is  not . So the latter should be reserved for very special cases.

The second problem that you might encounter is referencing a type which is not yet compiled. This may happen more often than you think. For example, when you compile a set of files together. In that case, if you want to say "that variable is of type Foo" but Foo is not yet compiled, you can still refer to the Foo class node using  lookupClassNodeFor :

Say that you know that variable  foo is of type  Foo and you want to tell the type checker about it. Then you can use the  storeType method, which takes two arguments: the first one is the node for which you want to store the type and the second one is the type of the node. If you look at the implementation of  storeType , you would see that it delegates to the type checker equivalent method, which itself does a lot of work to store node metadata. You would also see that storing the type is not limited to variables: you can set the type of any expression.

Likewise, getting the type of an AST node is just a matter of calling  getType on that node. This would in general be what you want, but there’s something that you must understand:

getType returns the  inferred type of an expression. This means that it will not return, for a variable declared of type  Object the class node for  Object , but the inferred type of this variable  at this point of the code (flow typing)

if you want to access the origin type of a variable (or field/parameter), then you must call the appropriate method on the AST node

To throw a type checking error, you only have to call the addStaticTypeError method which takes two arguments:

a  message which is a string that will be displayed to the end user

an AST node responsible for the error. It’s better to provide the best suiting AST node because it will be used to retrieve the line and column numbers

It is often required to know the type of an AST node. For readability, the DSL provides a special isXXXExpression method that will delegate to x instance of XXXExpression . For example, instead of writing:

you can just write:

When you perform type checking of dynamic code, you may often face the case when you know that a method call is valid but there is no "real" method behind it. As an example, take the Grails dynamic finders. You can have a method call consisting of a method named  findByName(…) . As there’s no  findByName method defined in the bean, the type checker would complain. Yet, you would know that this method wouldn’t fail at runtime, and you can even tell what is the return type of this method. For this case, the DSL supports two special constructs that consist of phantom methods . This means that you will return a method node that doesn’t really exist but is defined in the context of type checking. Three methods exist:

newMethod(String name, Class returnType)

newMethod(String name, ClassNode returnType)

newMethod(String name, Callable<ClassNode> return Type)

All three variants do the same: they create a new method node which name is the supplied name and define the return type of this method. Moreover, the type checker would add those methods in the  generatedMethods list (see  isGenerated below). The reason why we only set a name and a return type is that it is only what you need in 90% of the cases. For example, in the  findByName example upper, the only thing you need to know is that  findByName wouldn’t fail at runtime, and that it returns a domain class. The  Callable version of return type is interesting because it defers the computation of the return type when the type checker actually needs it. This is interesting because in some circumstances, you may not know the actual return type when the type checker demands it, so you can use a closure that will be called each time  getReturnType is called by the type checker on this method node. If you combine this with deferred checks, you can achieve pretty complex type checking including handling of forward references.

Should you need more than the name and return type, you can always create a new  MethodNode by yourself.

Scoping is very important in DSL type checking and is one of the reasons why we couldn’t use a  pointcut based approach to DSL type checking. Basically, you must be able to define very precisely when your extension applies and when it does not. Moreover, you must be able to handle situations that a regular type checker would not be able to handle, such as forward references:

Say for example that you want to handle a builder:

Your extension, then, should only be active once you’ve entered the  foo method, and inactive outside this scope. But you could have complex situations like multiple builders in the same file or embedded builders (builders in builders). While you should not try to fix all this from start (you must accept limitations to type checking), the type checker does offer a nice mechanism to handle this: a scoping stack, using the  newScope and  scopeExit methods.

newScope creates a new scope and puts it on top of the stack

scopeExits pops a scope from the stack

A scope consists of:

a parent scope

a map of custom data

If you want to look at the implementation, it’s simply a LinkedHashMap ( org.codehaus.groovy.transform.stc.GroovyTypeCheckingExtensionSupport.TypeCheckingScope ), but it’s quite powerful. For example, you can use such a scope to store a list of closures to be executed when you exit the scope. This is how you would handle forward references: 

That is to say, that if at some point you are not able to determine the type of an expression, or that you are not able to check at this point that an assignment is valid or not, you can still make the check later… This is a very powerful feature. Now,  newScope and  scopeExit provide some interesting syntactic sugar:

At anytime in the DSL, you can access the current scope using  getCurrentScope() or more simply  currentScope :

The general schema would then be:

determine a pointcut where you push a new scope on stack and initialize custom variables within this scope

using the various events, you can use the information stored in your custom scope to perform checks, defer checks,…

determine a pointcut where you exit the scope, call  scopeExit and eventually perform additional checks

For the complete list of helper methods, please refer to the  org.codehaus.groovy.transform.stc.GroovyTypeCheckingExtensionSupport and  org.codehaus.groovy.transform.stc.TypeCheckingExtension classes. However, take special attention to those methods:

isDynamic : takes a VariableExpression as argument and returns true if the variable is a DynamicExpression, which means, in a script, that it wasn’t defined using a type or def .

isGenerated : takes a MethodNode as an argument and tells if the method is one that was generated by the type checker extension using the  newMethod method

isAnnotatedBy : takes an AST node and a Class (or ClassNode), and tells if the node is annotated with this class. For example: isAnnotatedBy(node, NotNull)

getTargetMethod : takes a method call as argument and returns the  MethodNode that the type checker has determined for it

delegatesTo : emulates the behaviour of the  @DelegatesTo annotation. It allows you to tell that the argument will delegate to a specific type (you can also specify the delegation strategy)

Advanced type checking extensions

All the examples above use type checking scripts. They are found in source form in classpath, meaning that:

a Groovy source file, corresponding to the type checking extension, is available on compilation classpath

this file is compiled by the Groovy compiler for each source unit being compiled (often, a source unit corresponds to a single file)

It is a very convenient way to develop type checking extensions, however it implies a slower compilation phase, because of the compilation of the extension itself for each file being compiled. For those reasons, it can be practical to rely on a precompiled extension. You have two options to do this:

write the extension in Groovy, compile it, then use a reference to the extension class instead of the source

write the extension in Java, compile it, then use a reference to the extension class

Writing a type checking extension in Groovy is the easiest path. Basically, the idea is that the type checking extension script becomes the body of the main method of a type checking extension class, as illustrated here:

Setting up the extension is very similar to using a source form extension:

The difference is that instead of using a path in classpath, you just specify the fully qualified class name of the precompiled extension.

In case you really want to write an extension in Java, then you will not benefit from the type checking extension DSL. The extension above can be rewritten in Java this way:

It is totally possible to use the @Grab annotation in a type checking extension. This means you can include libraries that would only be available at compile time. In that case, you must understand that you would increase the time of compilation significantly (at least, the first time it grabs the dependencies).

A type checking extension is just a script that need to be on classpath. As such, you can share it as is, or bundle it in a jar file that would be added to classpath.

While you can configure the compiler to transparently add type checking extensions to your script, there is currently no way to apply an extension transparently just by having it on classpath.

Type checking extensions are used with @TypeChecked but can also be used with @CompileStatic . However, you must be aware that:

a type checking extension used with @CompileStatic will in general not be sufficient to let the compiler know how to generate statically compilable code from "unsafe" code

it is possible to use a type checking extension with @CompileStatic just to enhance type checking, that is to say introduce more compilation errors, without actually dealing with dynamic code

Let’s explain the first point, which is that even if you use an extension, the compiler will not know how to compile your code statically: technically, even if you tell the type checker what is the type of a dynamic variable, for example, it would not know how to compile it. Is it getBinding('foo') , getProperty('foo') , delegate.getFoo() ,…? There’s absolutely no direct way to tell the static compiler how to compile such code even if you use a type checking extension (that would, again, only give hints about the type).

One possible solution for this particular example is to instruct the compiler to use mixed mode compilation . The more advanced one is to use AST transformations during type checking but it is far more complex.

Type checking extensions allow you to help the type checker where it fails, but it also allows you to fail where it doesn’t. In that context, it makes sense to support extensions for  @CompileStatic too. Imagine an extension that is capable of type checking SQL queries. In that case, the extension would be valid in both dynamic and static context, because without the extension, the code would still pass.

In the previous section, we highlighted the fact that you can activate type checking extensions with @CompileStatic . In that context, the type checker would not complain anymore about some unresolved variables or unknown method calls, but it would still wouldn’t know how to compile them statically.

Mixed mode compilation offers a third way, which is to instruct the compiler that whenever an unresolved variable or method call is found, then it should fall back to a dynamic mode. This is possible thanks to type checking extensions and a special makeDynamic call.

To illustrate this, let’s come back to the Robot example:

And let’s try to activate our type checking extension using @CompileStatic instead of @TypeChecked :

The script will run fine because the static compiler is told about the type of the robot variable, so it is capable of making a direct call to move . But before that, how did the compiler know how to get the robot variable? In fact by default, in a type checking extension, setting handled=true on an unresolved variable will automatically trigger a dynamic resolution, so in this case you don’t have anything special to make the compiler use a mixed mode. However, let’s slightly update our example, starting from the robot script:

Here you can notice that there is no reference to robot anymore. Our extension will not help then because we will not be able to instruct the compiler that move is done on a Robot instance. This example of code can be executed in a totally dynamic way thanks to the help of a groovy.util.DelegatingScript :

If we want this to pass with @CompileStatic , we have to use a type checking extension, so let’s update our configuration:

Then in the previous section we have learnt how to deal with unrecognized method calls, so we are able to write this extension:

If you try to execute this code, then you could be surprised that it actually fails at runtime:

The reason is very simple: while the type checking extension is sufficient for @TypeChecked , which does not involve static compilation, it is not enough for @CompileStatic which requires additional information. In this case, you told the compiler that the method existed, but you didn’t explain to it what method it is in reality, and what is the receiver of the message (the delegate).

Fixing this is very easy and just implies replacing the newMethod call with something else:

The makeDynamic call does 3 things:

it returns a virtual method just like newMethod

automatically sets the handled flag to true for you

but also marks the call to be done dynamically

So when the compiler will have to generate bytecode for the call to move , since it is now marked as a dynamic call, it will fall back to the dynamic compiler and let it handle the call. And since the extension tells us that the return type of the dynamic call is a Robot , subsequent calls will be done statically!

Some would wonder why the static compiler doesn’t do this by default without an extension. It is a design decision:

if the code is statically compiled, we normally want type safety and best performance

so if unrecognized variables/method calls are made dynamic, you loose type safety, but also all support for typos at compile time!

In short, if you want to have mixed mode compilation, it has to be explicit, through a type checking extension, so that the compiler, and the designer of the DSL, are totally aware of what they are doing.

makeDynamic can be used on 3 kind of AST nodes:

a method node ( MethodNode )

a variable ( VariableExpression )

a property expression ( PropertyExpression )

If that is not enough, then it means that static compilation cannot be done directly and that you have to rely on AST transformations.

Type checking extensions look very attractive from an AST transformation design point of view: extensions have access to context like inferred types, which is often nice to have. And an extension has a direct access to the abstract syntax tree. Since you have access to the AST, there is nothing in theory that prevents you from modifying the AST. However, we do not recommend you to do so, unless you are an advanced AST transformation designer and well aware of the compiler internals:

First of all, you would explicitly break the contract of type checking, which is to annotate, and only annotate the AST. Type checking should  not modify the AST tree because you wouldn’t be able to guarantee anymore that code without the  @TypeChecked annotation behaves the same without the annotation.

If your extension is meant to work with  @CompileStatic , then you  can modify the AST because this is indeed what  @CompileStatic will eventually do. Static compilation doesn’t guarantee the same semantics at dynamic Groovy so there is effectively a difference between code compiled with  @CompileStatic and code compiled with  @TypeChecked . It’s up to you to choose whatever strategy you want to update the AST, but probably using an AST transformation that runs before type checking is easier.

if you cannot rely on a transformation that kicks in before the type checker, then you must be very careful

Examples of real life type checking extensions are easy to find. You can download the source code for Groovy and take a look at the TypeCheckingExtensionsTest class which is linked to various extension scripts .

An example of a complex type checking extension can be found in the Markup Template Engine source code: this template engine relies on a type checking extension and AST transformations to transform templates into fully statically compiled code. Sources for this can be found here .

2.1. Running Groovy from the commandline

groovy invokes the Groovy command line processor. It allows you to run inline Groovy expressions, and scripts, tests or application within groovy files. It plays a similar role to java in the Java world but handles inline scripts and rather than invoking class files, it is normally called with scripts and will automatically call the Groovy compiler as needed.

The easiest way to run a Groovy script, test or application is to run the following command at your shell prompt:

The .groovy part is optional. The groovy command supports a number of command line switches:

2.2. Compiling Groovy

groovyc is the Groovy compiler command line tool. It allows you to compile Groovy sources into bytecode. It plays the same role as javac in the Java world. The easiest way to compile a Groovy script or class is to run the following command:

This will produce a MyClass.class file (as well as other .class files depending on the contents of the source). groovyc supports a number of command line switches:

Notes: * for a full description of joint compilation, see the joint compilation section .

See the groovyc Ant task documentation. It allows the Groovy compiler to be invoked from Apache Ant .

Gant is a tool for scripting Ant tasks using Groovy instead of XML to specify the logic. As such, it has exactly the same features as the Groovyc Ant task.

Gradle is a build tool that allows you to leverage the flexibility of Ant , while keeping the simplicity of convention over configuration that tools like Maven offer. Builds are specified using a Groovy DSL, which offers great flexibility and succinctness.

2.2.5. Maven integration

There are several approaches to compiling Groovy code in your Maven projects. GMavenPlus is the most flexible and feature rich, but like most Groovy compiler tools, it can have difficulties with joint Java-Groovy projects (for the same reason GMaven and Gradle can have issues). The Groovy-Eclipse compiler plugin for Maven sidesteps the joint compilation issues. Read this for a deeper discussion of the benefits and disadvantages of the two approaches.

A third approach is to use Maven’s Ant plugin to compile a groovy project. Note that the Ant plugin is bound to the compile and test-compile phases of the build in the example below. It will be invoked during these phases and the contained tasks will be carried out which runs the Groovy compiler over the source and test directories. The resulting Java classes will coexist with and be treated like any standard Java classes compiled from Java source and will appear no different to the JRE, or the JUnit runtime.

This assumes you have a Maven project setup with groovy subfolders as peers to the java src and test subfolders. You can use the java / jar archetype to set this up then rename the java folders to groovy or keep the java folders and just create groovy peer folders. There exists, also a groovy plugin which has not been tested or used in production. After defining the build section as in the above example, you can invoke the typical Maven build phases normally. For example, mvn test will execute the test phase, compiling Groovy source and Groovy test source and finally executing the unit tests. If you run mvn jar it will execute the jar phase bundling up all of your compiled production classes into a jar after all the unit tests pass. For more detail on Maven build phases consult the Maven2 documentation.

GMaven and GMavenPlus

GMaven is the original Maven plugin for Groovy, supporting both compiling and scripting Groovy.

You should be aware that GMaven is not supported anymore and can have difficulties with joint compilation . GMavenPlus can be a good replacement, but if you are having problems with joint compilation, you might consider the Groovy Eclipse maven plugin .

GMavenPlus is a rewrite of GMaven and is in active development. It supports most of the features of GMaven (a couple notable exceptions being mojo Javadoc tags and support for older Groovy versions). Its joint compilation uses stubs (which means it has the same potential issues as GMaven and Gradle ). The main advantages over its predecessor are that it supports recent Groovy versions, InvokeDynamic, Groovy on Android, GroovyDoc, and configuration scripts.

Unlike the name might seem to suggest, GMaven 2 is not aimed at replacing GMaven . In fact, it removes the non-scripting features of the GMaven plugin. It has not yet had any release and appears to be inactive currently.

Groovy-Eclipse provides a compiler plugin for Maven. Using the compiler plugin, it is possible to compile your maven projects using the Groovy-Eclipse compiler. One feature unavailable elsewhere is stubless joint compilation.

Joint compilation means that the Groovy compiler will parse the Groovy source files, create stubs for all of them, invoke the Java compiler to compile the stubs along with Java sources, and then continue compilation in the normal Groovy compiler way. This allows mixing of Java and Groovy files without constraint.

Joint compilation can be enabled using the -j flag with the command-line compiler, or using a nested tag and all the attributes and further nested tags as required for the Ant task.

It is important to know that if you don’t enable joint compilation and try to compile Java source files with the Groovy compiler, the Java source files will be compiled as if they were Groovy sources. In some situations, this might work since most of the Java syntax is compatible with Groovy, but there are a number of places where semantics could be different.

It is possible to write an Android application in Groovy. However this requires a special version of the compiler, meaning that you cannot use the regular groovyc tool to target Android bytecode. In particular, Groovy provides specific JAR files for Android, which have a classifier of grooid . In order to make things easier, a Gradle plugin adds support for the Groovy language in the Android Gradle toolchain.

The plugin can be applied like this:

Then you will need to add a dependency on the grooid version of the Groovy compiler:

Note that if a Groovy jar does not provide a grooid classifier alternative, then it means that the jar is directly compatible with Android. In that case, you can add the dependency directly like this:

Note that the transitive=false parameter for groovy-json will let Gradle download the JSON support jar without adding a dependency onto the normal jar of Groovy.

Please make sure to go to the plugin homepage in order to find the latest documentation and version.

2.3. Groovysh, the Groovy shell

2.3.1. groovy : groovy shell.

The Groovy Shell, aka. groovysh is a command-line application which allows easy access to evaluate Groovy expressions, define classes and run simple experiments.

No need for go command to execute buffer.

Rich cross-platform edit-line editing, history and completion thanks to JLine2 .

ANSI colors (prompt, exception traces, etc).

Simple, yet robust, command system with online help, user alias support and more.

User profile support

The shell supports several options to control verbosity, ANSI coloring and other features.

Evaluating Expressions

When a complete expression is found, it is compiled and evaluated. The result of the evaluation is stored into the _ variable.

Multi-line Expressions

Multi-line/complex expressions (like closure or class definitions) may be defined over several lines. When the shell detects that it has a complete expression it will compile and evaluate it.

Shell variables are all untyped (i.e. no def or other type information).

This will set a shell variable:

But, this will evaluate a local variable and will not be saved to the shell’s environment:

This behavior can be changed by activating interpreter mode .

Functions can be defined in the shell, and will be saved for later use.

Defining a function is easy:

And then using it is as one might expect:

Internally the shell creates a closure to encapsulate the function and then binds the closure to a variable. So variables and functions share the same namespace.

The shell has a number of different commands, which provide rich access to the shell’s environment.

Commands all have a name and a shortcut (which is something like \h ). Commands may also have some predefined system aliases . Users may also create their own aliases.

Recognized Commands

Display the list of commands (and aliases) or the help text for specific command.

The Command List

Help for a Command

While in the interactive shell, you can ask for help for any command to get more details about its syntax or function. Here is an example of what happens when you ask for help for the help command:

Exit the shell.

This is the only way to exit the shell. Well, you can still CTRL-C , but the shell will complain about an abnormal shutdown of the JVM.

Add a custom import which will be included for all shell evaluations.

This command can be given at any time to add new imports.

Grab a dependency (Maven, Ivy, etc.) from Internet sources or cache, and add it to the Groovy Shell environment.

This command can be given at any time to add new dependencies.

Display the contents of the current buffer.

This only displays the buffer of an incomplete expression. Once the expression is complete, the buffer is reset. The prompt will update to show the size of the current buffer as well.

Clears the current buffer, resetting the prompt counter to 000. Can be used to recover from compilation errors.

Show variables, classes or preferences or imports.

show variables

show classes

show imports

show preferences

Opens the GUI object browser to inspect a variable or the result of the last evaluation.

Purges objects from the shell.

purge variables

purge classes

purge imports

purge preferences

Edit the current buffer in an external editor.

Currently only works on UNIX systems which have the EDITOR environment variable set, or have configured the editor preference.

Load one or more files (or urls) into the buffer.

Saves the buffer’s contents to a file.

Record the current session to a file.

record start

record stop

record status

Display, manage and recall edit-line history.

history show

history recall

history flush

history clear

Create an alias.

Opens a browser with documentation for the provided class.

For example, we can get both the Javadoc and GDK enhancements doc for java.util.List (shown running on JDK17):

This will print the documentation URLs found and open two windows (or tabs, depending on your browser):

one for the JDK documentation

one for the GDK documentation

By default, for Java classes, the java.base module is assumed. You can specify an optional module for other cases (shown running on JDK17):

For backwards compatibility, if no module is specified when searching for Java classes, and no class is found in the java.base module, an additional attempt is made to find documentation for the class in the JDK8 (pre-module) Javadoc:

To get the Groovydoc for groovy.ant.AntBuilder and groovy.xml.XmlSlurper :

To get both the Groovydoc and GDK enhancements doc for groovy.lang.Closure and groovy.sql.GroovyResultSet :

Documentation is also available for the GDK enhancements to primitive arrays and arrays of arrays:

Set or list preferences.

Preferences

Some aspects of groovysh behaviors can be customized by setting preferences. Preferences are set using the set command or the := shortcut.

Recognized Preferences

Allows the use of typed variables (i.e. def or other type information):

It’s especially useful for copy&pasting code from tutorials etc. into the running session.

Set the shell’s verbosity level. Expected to be one of:

Default is INFO .

If this preference is set to an invalid value, then the previous setting will be used, or if there is none, then the preference is removed and the default is used.

Set the shell’s use of colors.

Default is true .

Show the last result after an execution.

Sanitize (trim-down/filter) stack traces.

Configures the editor used by the edit command.

Default is the value of the system environment variable EDITOR .

To use TextEdit, the default text editor on macOS, configure: set editor /Applications/TextEdit.app/Contents/MacOS/TextEdit

To list the current set preferences (and their values):

Limitation: At the moment, there is no way to list all the known/available preferences to be set.

User Profile Scripts and State

Profile scripts.

This script, if it exists, is loaded when the shell starts up.

This script, if it exists, is loaded when the shell enters interactive mode.

Edit-line history is stored in this file.

The register command allows you to register custom commands in the shell. For example, writing the following will register the Stats command:

where the Stats class is a class extending the org.apache.groovy.groovysh.CommandSupport class. For example:

Then the command can be called using:

Note that the command class must be found on classpath: you cannot define a new command from within the shell.

Troubleshooting

Please report any problems you run into. Please be sure to mark the JIRA issue with the Groovysh component.

Platform Problems

On Windows, JLine2 (which is used for the fancy shell input/history/completion fluff), uses a tiny DLL file to trick the evil Windows faux-shell ( CMD.EXE or COMMAND.COM ) into providing Java with unbuffered input. In some rare cases, this might fail to load or initialize.

One solution is to disable the frills and use the unsupported terminal instance. You can do that on the command-line using the --terminal flag and set it to one of:

jline.UnsupportedTerminal

Some people have issues when running groovysh with cygwin. If you have troubles, the following may help:

GMavenPlus is a Maven plugin with goals that support launching a Groovy Shell or Groovy Console bound to a Maven project.

Gradle Groovysh Plugin is a Gradle plugin that provides gradle tasks to start a Groovy Shell bound to a Gradle project.

2.4. groovyConsole, the Groovy swing console

The Groovy Swing Console allows a user to enter and run Groovy scripts. This page documents the features of this user interface.

Groovy Console is launched via groovyConsole or groovyConsole.bat , both located in $GROOVY_HOME/bin

The Console has an input area and an output area.

You type a Groovy script in the input area.

When you select Run from the Actions menu, the console compiles the script and runs it.

Anything that would normally be printed on System.out is printed in the output area.

If the script returns a non-null result, that result is printed.

2.4.3. Features

The Groovy Console supports several options to control classpath and other features.

There are several shortcuts that you can use to run scripts or code snippets:

Ctrl+Enter and Ctrl+R are both shortcut keys for Run Script .

If you highlight just part of the text in the input area, then Groovy runs just that text.

The result of a script is the value of the last expression executed.

You can turn the System.out capture on and off by selecting Capture System.out from the Actions menu

You can open any text file, edit it, run it (as a Groovy Script) and then save it again when you are finished.

Select File > Open (shortcut key ctrl+O ) to open a file

Select File > Save (shortcut key ctrl+S ) to save a file

Select File > New File (shortcut key ctrl+Q ) to start again with a blank input area

You can pop up a gui inspector on the last (non-null) result by selecting Inspect Last from the Actions menu. The inspector is a convenient way to view lists and maps.

The console remembers the last ten script runs. You can scroll back and forth through the history by selecting Next and Previous from the Edit menu. Ctrl-N and ctrl-P are convenient shortcut keys.

The last (non-null) result is bound to a variable named _ (an underscore).

The last result (null and non-null) for every run in the history is bound into a list variable named (two underscores). The result of the last run is [-1] , the result of the second to last run is __[-2] and so forth.

The Groovy console is a very handy tool to develop scripts. Often, you will find yourself running a script multiple times until it works the way you want it to. However, what if your code takes too long to finish or worse, creates an infinite loop? Interrupting script execution can be achieved by clicking the interrupt button on the small dialog box that pops up when a script is executing or through the interrupt icon in the toolbar.

However, this may not be sufficient to interrupt a script: clicking the button will interrupt the execution thread, but if your code doesn’t handle the interrupt flag, the script is likely to keep running without you being able to effectively stop it. To avoid that, you have to make sure that the Script > Allow interruption menu item is flagged. This will automatically apply an AST transformation to your script which will take care of checking the interrupt flag ( @ThreadInterrupt ). This way, you guarantee that the script can be interrupted even if you don’t explicitly handle interruption, at the cost of extra execution time.

You can change the font size by selecting Smaller Font or Larger Font from the Actions menu

The console can be run as an Applet thanks to groovy.ui.ConsoleApplet

Code is auto indented when you hit return

You can drag’n’drop a Groovy script over the text area to open a file

You can modify the classpath with which the script in the console is being run by adding a new JAR or a directory to the classpath from the Script menu

Error hyperlinking from the output area when a compilation error is expected or when an exception is thrown

To embed a Swing console in your application, simply create the Console object, load some variables, and then launch it. The console can be embedded in either Java or Groovy code. The Java code for this is:

Once the console is launched, you can use the variable values in Groovy code.

You can customize the way script output results are visualized. Let’s see how we can customize this. For example, viewing a map result would show something like this:

What you see here is the usual textual representation of a Map. But, what if we enabled custom visualization of certain results? The Swing console allows you to do just that. First of all, you have to ensure that the visualization option is ticked: View → Visualize Script Results — for the record, all settings of the Groovy Console are stored and remembered thanks to the Preference API. There are a few result visualizations built-in: if the script returns a java.awt.Image , a javax.swing.Icon , or a java.awt.Component with no parent, the object is displayed instead of its toString() representation. Otherwise, everything else is still just represented as text. Now, create the following Groovy script in ~/.groovy/OutputTransforms.groovy :

The Groovy Swing console will execute that script on startup, injecting a transforms list in the binding of the script, so that you can add your own script results representations. In our case, we transform the Map into a nice-looking Swing JTable. We’re now able to visualize maps in a friendly and attractive fashion, as the screenshot below shows:

Groovy Console can visualize the AST (Abstract Syntax Tree) representing the currently edited script, as shown by the screenshot below. This is useful when you want to understand how an AST transformation is working and particularly handy if you are developing your own AST transform. In the example below, we have annotated our class with the @Immutable annotation and the Groovy compiler has generated a lot of boilerplate code for us. We can see the code for the generated equals method in the Source tab.

We can even examine the JVM bytecode generated by the compiler. In the image below we are looking at the bytecode for the Groovy expression LocalDate.parse('2020/02/10', 'yyyy/MM/dd') .

Groovy Console can visualize the CST (Concrete Syntax Tree) representing the initial parsing of the script. This is mainly useful for parsing gurus.

2.5. groovydoc, the Groovy & Java documentation generator

GroovyDoc is a tool responsible for generating documentation from your code. It acts like the Javadoc tool in the Java world but is capable of handling both groovy and java files. The distribution comes with two ways of generating documentation: from command line or from Apache Ant . Other build tools like Maven or Gradle also offer wrappers for Groovydoc.

The groovydoc command line can be invoked to generate groovydocs:

where options must be picked from the following table:

2.5.2. The groovydoc Ant task

The groovydoc Ant task allows generating groovydocs from an Ant build.

Assuming all the groovy jars you need are in my.classpath (this will be groovy-VERSION.jar , groovy-ant-VERSION.jar , groovy-groovydoc-VERSION.jar plus any modules and transitive dependencies you might be using) you will need to declare this task at some point in the build.xml prior to the groovydoc task being invoked.

<groovydoc> Nested Elements

Create link to groovydoc/javadoc output at the given URL.

Custom templates

The groovydoc Ant task supports custom templates, but it requires two steps:

A custom groovydoc class

A new groovydoc task definition

The first step requires you to extend the Groovydoc class, like in the following example:

You can override the following methods:

getClassTemplates for class-level templates

getPackageTemplates for package-level templates

getDocTemplates for top-level templates

You can find the list of default templates in the org.codehaus.groovy.tools.groovydoc.gstringTemplates.GroovyDocTemplateInfo class.

Once you’ve written the class, using it is just a matter of redefining the groovydoc task:

Please note that template customization is provided as is. APIs are subject to change, so you must consider this as a fragile feature.

GMavenPlus is a Maven plugin with goals that support GroovyDoc generation.

Many IDEs and text editors support the Groovy programming language.

3. User Guides

3.1. getting started, 3.1.1. download.

From the download page, you will be able to download the distribution (binary and source), the Windows installer (a community artifact) and the documentation for Groovy .

For a quick and effortless start on Mac OSX, Linux, WSL2 or Cygwin, you can use SDKMAN! (The Software Development Kit Manager) to download and configure any Groovy version of your choice. Basic instructions can be found below.

Download zip : Binary Release | Source Release

Download documentation : JavaDoc and zipped online documentation

Combined binary / source / documentation bundle : Distribution bundle

You can learn more about this version in the release notes or in the changelog .

If you plan on using invokedynamic support, read those notes .

For those who want to test the very latest versions of Groovy and live on the bleeding edge, you can use our snapshot builds . As soon as a build succeeds on our continuous integration server a snapshot is deployed to this repository. These snapshots are not official releases and are intended for integration testing by the development community prior to official versions being released. We welcome any feedback.

Groovy 4.0 requires Java 8+ with support for up to Java 16.

Various Groovy CI servers run the test suite (with more than 10000 tests) across numerous versions of Java. Those servers are also useful to look at to confirm supported Java versions for different Groovy releases.

If you wish to embed Groovy in your application, you may just prefer to point your build to your favourite maven repository or the Groovy artifactory instance . Please see the download page for available modules for each Groovy version.

This tool makes installing Groovy on any Bash platform (Mac OSX, Linux, Cygwin, Solaris or FreeBSD) very easy.

Simply open a new terminal and enter:

Follow the instructions on-screen to complete installation.

Open a new terminal or type the command:

Then install the latest stable Groovy:

After installation is complete and you’ve made it your default version, test it with:

That’s all there is to it!

3.1.4. Other ways to get Groovy

Installation on mac os x.

If you’re on macOS and have MacPorts installed, you can run:

If you’re on macOS and have Homebrew installed, you can run:

If you’re on Windows, you can also use the Windows installer .

You may download other distributions of Groovy from the ASF archive repository or from the Groovy artifactory instance (also includes pre-ASF versions).

If you prefer to live on the bleeding edge, you can also grab the source code from GitHub .

If you are an IDE user, you can just grab the latest IDE plugin and follow the plugin installation instructions.

These instructions describe how to install a binary distribution of Groovy :

Download a binary distribution of Groovy and unpack it into some folder on your local file system.

Set your GROOVY_HOME environment variable to the directory where you unpacked the distribution.

Add GROOVY_HOME/bin to your PATH environment variable.

Set your JAVA_HOME environment variable to point to your JDK. On OS X this is /Library/Java/Home , on other unixes its often /usr/java etc. If you’ve already installed tools like Ant or Maven you’ve probably already done this step.

You should now have Groovy installed properly. You can test this by typing the following in a command shell:

Which should create an interactive groovy shell where you can type Groovy statements. Or to run the Swing interactive console type:

To run a specific Groovy script type:

3.2. Differences with Java

Groovy tries to be as natural as possible for Java developers. We’ve tried to follow the principle of least surprise when designing Groovy, particularly for developers learning Groovy who’ve come from a Java background.

Here we list all the major differences between Java and Groovy.

All these packages and classes are imported by default, i.e. you do not have to use an explicit import statement to use them:

java.lang.*

java.util.*

groovy.lang.*

groovy.util.*

In Groovy, the methods which will be invoked are chosen at runtime. This is called runtime dispatch or multi-methods. It means that the method will be chosen based on the types of the arguments at runtime. In Java, this is the opposite: methods are chosen at compile time, based on the declared types.

The following code, written as Java code, can be compiled in both Java and Groovy, but it will behave differently:

In Java, you would have:

Whereas in Groovy:

That is because Java will use the static information type, which is that o is declared as an Object , whereas Groovy will choose at runtime, when the method is actually called. Since it is called with a String , then the String version is called.

In Java, array initializers take either of these two forms:

In Groovy, the { …​ } block is reserved for closures. That means that you cannot create array literals using Java’s array initializer shorthand syntax. You instead borrow Groovy’s literal list notation like this:

For Groovy 3+, you can optionally use the Java’s array initializer long syntax:

In Groovy, omitting a modifier on a field doesn’t result in a package-private field like in Java:

Instead, it is used to create a property , that is to say a private field , an associated getter and an associated setter .

It is possible to create a package-private field by annotating it with @PackageScope :

Java 7 introduced ARM (Automatic Resource Management) blocks (also know as try-with-resources) blocks like this:

Such blocks are supported from Groovy 3+. However, Groovy provides various methods relying on closures, which have the same effect while being more idiomatic. For example:

or, if you want a version closer to Java:

3.2.6. Inner classes

Here’s an example of static inner class:

The usage of static inner classes is the best supported one. If you absolutely need an inner class, you should make it a static one.

In Java you can do this:

Before 3.0.0, Groovy doesn’t support the y.new X() syntax. Instead, you have to write new X(y) , like in the code below:

Java 8+ supports lambda expressions and the method reference operator ( :: ):

Groovy 3 and above also support these within the Parrot parser. In earlier versions of Groovy you should use closures instead:

As double-quoted string literals are interpreted as GString values, Groovy may fail with compile error or produce subtly different code if a class with String literal containing a dollar character is compiled with Groovy and Java compiler.

While typically, Groovy will auto-cast between GString and String if an API declares the type of a parameter, beware of Java APIs that accept an Object parameter and then check the actual type.

Singly-quoted literals in Groovy are used for String , and double-quoted result in String or GString , depending whether there is interpolation in the literal.

Groovy will automatically cast a single-character String to char only when assigning to a variable of type char . When calling methods with arguments of type char we need to either cast explicitly or make sure the value has been cast in advance.

Groovy supports two styles of casting and in the case of casting to char there are subtle differences when casting a multi-char strings. The Groovy style cast is more lenient and will take the first character, while the C-style cast will fail with exception.

In Java, == means equality of primitive types or identity for objects. In Groovy, == means equality in all places. For non-primitives, it translates to a.compareTo(b) == 0 , when evaluating equality for Comparable objects, and a.equals(b) otherwise.

To check for identity (reference equality), use the is method: a.is(b) . From Groovy 3, you can also use the === operator (or negated version): a === b (or c !== d ).

3.2.11. Primitives and wrappers

In a pure object-oriented language, everything would be an object. Java takes the stance that primitive types, such as int, boolean and double, are used very frequently and worthy of special treatment. Primitives can be efficiently stored and manipulated but can’t be used in all contexts where an object could be used. Luckily, Java auto boxes and unboxes primitives when they are passed as parameters or used as return types:

Groovy does the same:

Groovy, also supports primitives and object types, however, it goes a little further in pushing OO purity; it tries hard to treat everything as an object. Any primitive typed variable or field can be treated like an object, and it will be auto-wrapped as needed. While primitive types might be used under the covers, their use should be indistinguishable from normal object use whenever possible, and they will be boxed/unboxed as needed.

Here is a little example using Java trying to (incorrectly for Java) dereference a primitive float :

The same example using Groovy compiles and runs successfully:

Because of Groovy’s additional use of un/boxing, it does not follow Java’s behavior of widening taking priority over boxing. Here’s an example using int

Since Groovy converts to wrapper classes in more places, you might wonder whether it produces less efficient bytecode for numeric expressions. Groovy has a highly optimised set of classes for doing math computations. When using @CompileStatic , expressions involving only primitives uses the same bytecode that Java would use.

Java float/double operations for both primitives and wrapper classes follow the IEEE 754 standard but there is an interesting edge case involving positive and negative zero. The standard supports distinguishing between these two cases and while in many scenarios programmers may not care about the difference, in some mathematical or data science scenarios it is important to cater for the distinction.

For primitives, Java maps down onto a special bytecode instruction when comparing such values which has the property that "Positive zero and negative zero are considered equal".

For the wrapper classes, e.g. java.base/java.lang.Float#equals(java.lang.Object) , the result is false for this same case.

Groovy on the one hand tries to follow Java behavior closely, but on the other switches automatically between primitives and wrapped equivalents in more places. To avoid confusion we recommend the following guidelines:

If you wish to distinguish between positive and negative zero, use the equals method directly or cast any primitives to their wrapper equivalent before using == .

If you wish to ignore the difference between positive and negative zero, use the equalsIgnoreZeroSign method directly or cast any non-primitives to their primitive equivalent before using == .

These guidelines are illustrated in the following example:

Java does automatic widening and narrowing conversions .

'Y' indicates a conversion Java can make

'C' indicates a conversion Java can make when there is an explicit cast

'T` indicates a conversion Java can make but data is truncated

'N' indicates a conversion Java can’t make

Groovy expands greatly on this.

'Y' indicates a conversion Groovy can make

'D' indicates a conversion Groovy can make when compiled dynamically or explicitly cast

'T' indicates a conversion Groovy can make but data is truncated

'B' indicates a boxing/unboxing operation

'N' indicates a conversion Groovy can’t make.

The truncation uses Groovy Truth when converting to boolean / Boolean . Converting from a number to a character casts the Number.intvalue() to char . Groovy constructs BigInteger and BigDecimal using Number.doubleValue() when converting from a Float or Double , otherwise it constructs using toString() . Other conversions have their behavior defined by java.lang.Number .

Groovy has many of the same keywords as Java and Groovy 3 and above also has the same var reserved type as Java. In addition, Groovy has the following keywords:

it // within closures

Groovy is less stringent than Java in that it allows some keywords to appear in places that would be illegal in Java, e.g. the following is valid: var var = [def: 1, as: 2, in: 3, trait: 4] . Never-the-less, you are discouraged from using the above keywords in places that might cause confusion even when the compiler might be happy. In particular, avoid using them for variable, method and class names, so our previous var var example would be considered poor style.

Additional documentation is available for keywords .

3.3. Groovy Development Kit

3.3.1. working with io.

Groovy provides a number of helper methods for working with I/O. While you could use standard Java code in Groovy to deal with those, Groovy provides much more convenient ways to handle files, streams, readers, …​

In particular, you should take a look at methods added to:

the java.io.File class : http://docs.groovy-lang.org/latest/html/groovy-jdk/java/io/File.html

the java.io.InputStream class: http://docs.groovy-lang.org/latest/html/groovy-jdk/java/io/InputStream.html

the java.io.OutputStream class: http://docs.groovy-lang.org/latest/html/groovy-jdk/java/io/OutputStream.html

the java.io.Reader class: http://docs.groovy-lang.org/latest/html/groovy-jdk/java/io/Reader.html

the java.io.Writer class: http://docs.groovy-lang.org/latest/html/groovy-jdk/java/io/Writer.html

the java.nio.file.Path class: http://docs.groovy-lang.org/latest/html/groovy-jdk/java/nio/file/Path.html

The following section focuses on sample idiomatic constructs using helper methods available above but is not meant to be a complete description of all available methods. For that, please read the GDK API .

As a first example, let’s see how you would print all lines of a text file in Groovy:

The eachLine method is a method added to the File class automatically by Groovy and has many variants, for example if you need to know the line number, you can use this variant:

If for whatever reason an exception is thrown in the eachLine body, the method makes sure that the resource is properly closed. This is true for all I/O resource methods that Groovy adds.

For example in some cases you will prefer to use a Reader , but still benefit from the automatic resource management from Groovy. In the next example, the reader will be closed even if the exception occurs:

Should you need to collect the lines of a text file into a list, you can do:

Or you can even leverage the as operator to get the contents of the file into an array of lines:

How many times did you have to get the contents of a file into a byte[] and how much code does it require? Groovy makes it very easy actually:

Working with I/O is not limited to dealing with files. In fact, a lot of operations rely on input/output streams, hence why Groovy adds a lot of support methods to those, as you can see in the documentation .

As an example, you can obtain an InputStream from a File very easily:

However you can see that it requires you to deal with closing the inputstream. In Groovy it is in general a better idea to use the withInputStream idiom that will take care of that for you:

Of course in some cases you won’t want to read but write a file. One of the options is to use a Writer :

But for such a simple example, using the << operator would have been enough:

Of course we do not always deal with text contents, so you could use the Writer or directly write bytes as in this example:

Of course you can also directly deal with output streams. For example, here is how you would create an output stream to write into a file:

However you can see that it requires you to deal with closing the output stream. Again it is in general a better idea to use the withOutputStream idiom that will handle the exceptions and close the stream in any case:

In scripting contexts it is a common task to traverse a file tree in order to find some specific files and do something with them. Groovy provides multiple methods to do this. For example you can perform something on all files of a directory:

Often you will have to deal with a deeper hierarchy of files, in which case you can use eachFileRecurse :

For more complex traversal techniques you can use the traverse method, which requires you to set a special flag indicating what to do with the traversal:

In Java it is not uncommon to serialize and deserialize data using the java.io.DataOutputStream and java.io.DataInputStream classes respectively. Groovy will make it even easier to deal with them. For example, you could serialize data into a file and deserialize it using this code:

And similarly, if the data you want to serialize implements the Serializable interface, you can proceed with an object output stream, as illustrated here:

The previous section described how easy it was to deal with files, readers or streams in Groovy. However in domains like system administration or devops it is often required to communicate with external processes.

Groovy provides a simple way to execute command line processes. Simply write the command line as a string and call the execute() method. E.g., on a *nix machine (or a Windows machine with appropriate *nix commands installed), you can execute this:

The execute() method returns a java.lang.Process instance which will subsequently allow the in/out/err streams to be processed and the exit value from the process to be inspected etc.

e.g. here is the same command as above but we will now process the resulting stream a line at a time:

It is worth noting that in corresponds to an input stream to the standard output of the command. out will refer to a stream where you can send data to the process (its standard input).

Remember that many commands are shell built-ins and need special handling. So if you want a listing of files in a directory on a Windows machine and write:

you will receive an IOException saying  Cannot run program "dir": CreateProcess error=2, The system cannot find the file specified.

This is because dir is built-in to the Windows shell ( cmd.exe ) and can’t be run as a simple executable. Instead, you will need to write:

Also, because this functionality currently makes use of java.lang.Process undercover, the deficiencies of that class must be taken into consideration. In particular, the javadoc for this class says:

Because some native platforms only provide limited buffer size for standard input and output streams, failure to promptly write the input stream or read the output stream of the subprocess may cause the subprocess to block, and even deadlock

Because of this, Groovy provides some additional helper methods which make stream handling for processes easier.

Here is how to gobble all of the output (including the error stream output) from your process:

There are also variations of consumeProcessOutput that make use of StringBuffer , InputStream , OutputStream etc…​ For a complete list, please read the GDK API for java.lang.Process

In addition, there is a pipeTo command (mapped to | to allow overloading) which lets the output stream of one process be fed into the input stream of another process.

Here are some examples of use:

3.3.2. Working with collections

Groovy provides native support for various collection types, including lists , maps or ranges . Most of those are based on the Java collection types and decorated with additional methods found in the Groovy development kit .

You can create lists as follows. Notice that [] is the empty list expression.

Each list expression creates an implementation of java.util.List .

Of course lists can be used as a source to construct another list:

A list is an ordered collection of objects:

Lists can be evaluated as a boolean value:

Iterating on elements of a list is usually done calling the each and eachWithIndex methods, which execute code on each item of a list:

In addition to iterating, it is often useful to create a new list by transforming each of its elements into something else. This operation, often called mapping, is done in Groovy thanks to the collect method:

Manipulating lists

The Groovy development kit contains a lot of methods on collections that enhance the standard collections with pragmatic methods, some of which are illustrated here:

And here is idiomatic Groovy code for finding the maximum and minimum in a collection:

In addition to closures, you can use a Comparator to define the comparison criteria:

We can use [] to assign a new empty list and << to append items to it:

We can add to a list in many ways:

It is however important that the + operator on a list is not mutating . Compared to << , it will create a new list, which is often not what you want and can lead to performance issues.

The Groovy development kit also contains methods allowing you to easily remove elements from a list by value:

It is also possible to remove an element by passing its index to the remove method, in which case the list is mutated:

In case you only want to remove the first element having the same value in a list, instead of removing all elements, you can call the remove method passing the value:

As you can see, there are two remove methods available. One that takes an integer and removes an element by its index, and another that will remove the first element that matches the passed value. So what should we do when we have a list of integers? In this case, you may wish to use removeAt to remove an element by its index, and removeElement to remove the first element that matches a value.

Of course, removeAt and removeElement will work with lists of any type.

Additionally, removing all the elements in a list can be done by calling the clear method:

The Groovy development kit also includes methods making it easy to reason on sets:

Working with collections often implies sorting. Groovy offers a variety of options to sort lists, from using closures to comparators, as in the following examples:

The Groovy development kit also takes advantage of operator overloading to provide methods allowing duplication of elements of a list:

In Groovy, maps (also known as associative arrays) can be created using the map literal syntax: [:] :

Map keys are strings by default: [a:1] is equivalent to ['a':1] . This can be confusing if you define a variable named a and that you want the value of a to be the key in your map. If this is the case, then you must escape the key by adding parenthesis, like in the following example:

In addition to map literals, it is possible, to get a new copy of a map, to clone it:

The resulting map is a shallow copy of the original one, as illustrated in the previous example.

Maps also act like beans so you can use the property notation to get/set items inside the Map as long as the keys are strings which are valid Groovy identifiers:

Note: by design map.foo will always look for the key foo in the map. This means foo.class will return null on a map that doesn’t contain the class key. Should you really want to know the class, then you must use getClass() :

As usual in the Groovy development kit , idiomatic iteration on maps makes use of the each and eachWithIndex methods. It’s worth noting that maps created using the map literal notation are ordered , that is to say that if you iterate on map entries, it is guaranteed that the entries will be returned in the same order they were added in the map.

Manipulating maps

Adding an element to a map can be done either using the put method, the subscript operator or using putAll :

Removing all the elements of a map can be done by calling the clear method:

Maps generated using the map literal syntax are using the object equals and hashcode methods. This means that you should never use an object which hash code is subject to change over time, or you wouldn’t be able to get the associated value back.

It is also worth noting that you should never use a GString as the key of a map, because the hash code of a GString is not the same as the hash code of an equivalent String :

We can inspect the keys, values, and entries in a view:

Mutating values returned by the view (be it a map entry, a key or a value) is highly discouraged because success of the operation directly depends on the type of the map being manipulated. In particular, Groovy relies on collections from the JDK that in general make no guarantee that a collection can safely be manipulated through keySet , entrySet , or values .

The Groovy development kit contains filtering, searching and collecting methods similar to those found for lists :

We can group a list into a map using some criteria:

Ranges allow you to create a list of sequential values. These can be used as List since Range extends java.util.List .

Ranges defined with the .. notation are inclusive (that is the list contains the from and to value).

Ranges defined with the ..< notation are half-open, they include the first value but not the last value.

Ranges defined with the <.. notation are also half-open, they include the last value but not the first value.

Ranges defined with the <..< notation are full-open, they do not include the first value nor the last value.

Note that int ranges are implemented efficiently, creating a lightweight Java object containing a from and to value.

Ranges can be used for any Java object which implements java.lang.Comparable for comparison and also have methods next() and previous() to return the next / previous item in the range. For example, you can create a range of String elements:

You can iterate on a range using a classic for loop:

but alternatively you can achieve the same effect in a more Groovy idiomatic style, by iterating a range with each method:

Ranges can be also used in the switch statement:

Syntax enhancements for collections

Thanks to the support of property notation for both lists and maps, Groovy provides syntactic sugar making it really easy to deal with nested collections, as illustrated in the following examples:

The spread operator can be used to "inline" a collection into another. It is syntactic sugar which often avoids calls to putAll and facilitates the realization of one-liners:

The "star-dot" operator is a shortcut operator allowing you to call a method or a property on all elements of a collection:

You can index into lists, arrays, maps using the subscript expression. It is interesting that strings are considered as special kinds of collections in that context:

Notice that you can use ranges to extract part of a collection:

The subscript operator can be used to update an existing collection (for collection type which are not immutable):

It is worth noting that negative indices are allowed, to extract more easily from the end of a collection:

You can use negative indices to count from the end of the List, array, String etc.

Eventually, if you use a backwards range (the starting index is greater than the end index), then the answer is reversed.

In addition to lists , maps or ranges , Groovy offers a lot of additional methods for filtering, collecting, grouping, counting, …​ which are directly available on either collections or more easily iterables.

In particular, we invite you to read the Groovy development kit API docs and specifically:

methods added to Iterable can be found here

methods added to Iterator can be found here

methods added to Collection can be found here

methods added to List can be found here

methods added to Map can be found here

3.3.3. Working with arrays

Groovy provides array support based on Java arrays with several extensions found in the Groovy development kit . The overall intention is that whether you are using an array or a collection, the code for working with the aggregate remains the same.

You can create arrays as follows. Notice that [] is also used as the empty array expression when given an explicit array type.

There are numerous other GDK methods for working with arrays. Just be a little careful to read the documentation. For collections, there are some mutating methods which alter the original collection and others which produce new collections, leaving the original untouched. Since arrays are of a fixed size, we wouldn’t expect mutating methods which altered an array’s size. Often instead, such methods return collections. Here are some interesting array GDK methods:

The groovy-dateutil module supports numerous extensions for working with Java’s classic Date and Calendar classes.

You can access the properties of a Date or Calendar using the normal array index notation with the constant field numbers from the Calendar class as shown in the following example:

Groovy supports arithmetic on and iteration between Date and Calendar instances as shown in the following example:

You can parse strings into dates and output dates into formatted strings:

You can also create a new Date or Calendar based on an existing one:

3.3.5. Working with Date/Time types

The groovy-datetime module supports numerous extensions for working with the Date/Time API introduced in Java 8. This documentation refers to the data types defined by this API as "JSR 310 types."

A common use case when working with date/time types is to convert them to Strings (formatting) and from Strings (parsing). Groovy provides these additional formatting methods:

For parsing, Groovy adds a static parse method to many of the JSR 310 types. The method takes two arguments: the value to be formatted and the pattern to use. The pattern is defined by the java.time.format.DateTimeFormatter API . As an example:

Note that these parse methods have a different argument ordering than the static parse method Groovy added to java.util.Date . This was done to be consistent with the existing parse methods of the Date/Time API.

Manipulating date/time

Temporal types have plus and minus methods for adding or subtracting a provided java.time.temporal.TemporalAmount argument. Because Groovy maps the + and - operators to single-argument methods of these names, a more natural expression syntax can be used to add and subtract.

Groovy provides additional plus and minus methods that accept an integer argument, enabling the above to be rewritten more succinctly:

The unit of these integers depends on the JSR 310 type operand. As evident above, integers used with ChronoLocalDate types like LocalDate have a unit of days . Integers used with Year and YearMonth have a unit of years and months , respectively. All other types have a unit of seconds , such as LocalTime , for instance:

The * operator can be used to multiply Period and Duration instances by an integer value; the / operator can be used to divide Duration instances by an integer value.

The ++ and -- operators can be used increment and decrement date/time values by one unit. Since the JSR 310 types are immutable, the operation will create a new instance with the incremented/decremented value and reassign it to the reference.

The Duration and Period types represent a negative or positive length of time. These can be negated with the unary - operator.

Interacting with date/time values

The getLong(TemporalField) method of TemporalAccessor types (e.g. LocalDate , LocalTime , ZonedDateTime , etc.) and the get(TemporalUnit) method of TemporalAmount types (namely Period and Duration ), can be invoked with Groovy’s property notation. For example:

The JSR 310 types can be used with the range operator . The following example iterates between today and the LocalDate six days from now, printing out the day of the week for each iteration. As both range bounds are inclusive, this prints all seven days of the week.

The upto method will accomplish the same as the range in the above example. The upto method iterates from the earlier start value (inclusive) to the later end value (also inclusive), calling the closure with the incremented next value once per iteration.

The downto method iterates in the opposite direction, from a later start value to an earlier end value.

The unit of iteration for upto , downto , and ranges is the same as the unit for addition and subtraction: LocalDate iterates by one day at a time, YearMonth iterates by one month, Year by one year, and everything else by one second. Both methods also support an optional a TemporalUnit argument to change the unit of iteration.

Consider the following example, where March 1st, 2018 is iterated up to March 2nd, 2018 using an iteration unit of months .

Since the start date is inclusive, the closure is called with a next date value of March 1st. The upto method then increments the date by one month, yielding the date, April 1st. Because this date is after the specified end date of March 2nd, the iteration stops immediately, having only called the closure once. This behavior is the same for the downto method except that the iteration will stop as soon as the value of next becomes earlier than the targeted end date.

In short, when iterating with the upto or downto methods with a custom unit of iteration, the current value of iteration will never exceed the end value.

The left-shift operator ( << ) can be used to combine two JSR 310 types into an aggregate type. For example, a LocalDate can be left-shifted into a LocalTime to produce a composite LocalDateTime instance.

The left-shift operator is reflexive; the order of the operands does not matter.

The right-shift operator ( >> ) produces a value representing the period or duration between the operands. For ChronoLocalDate , YearMonth , and Year , the operator yields a Period instance:

The operator produces a Duration for the time-aware JSR types:

If the value on the left-hand side of the operator is earlier than the value on the right-hand side, the result is positive. If the left-hand side is later than the right-hand side, the result is negative:

Despite the shortcomings of Date , Calendar , and TimeZone types in the java.util package they are fairly common in Java APIs (at least in those prior to Java 8). To accommodate use of such APIs, Groovy provides methods for converting between the JSR 310 types and legacy types.

Most JSR types have been fitted with toDate() and toCalendar() methods for converting to relatively equivalent java.util.Date and java.util.Calendar values. Both ZoneId and ZoneOffset have been given a toTimeZone() method for converting to java.util.TimeZone .

Note that when converting to a legacy type:

Nanosecond values are truncated to milliseconds. A LocalTime , for example, with a ChronoUnit.NANOS value of 999,999,999 nanoseconds translates to 999 milliseconds.

When converting the "local" types ( LocalDate , LocalTime , and LocalDateTime ), the time zone of the returned Date or Calendar will be the system default.

When converting a time-only type ( LocalTime or OffsetTime ), the year/month/day of the Date or Calendar is set to the current date.

When converting a date-only type ( LocalDate ), the time value of the Date or Calendar will be cleared, i.e. 00:00:00.000 .

When converting an OffsetDateTime to a Calendar , only the hours and minutes of the ZoneOffset convey into the corresponding TimeZone . Fortunately, Zone Offsets with non-zero seconds are rare.

Groovy has added a number of methods to Date and Calendar for converting into the various JSR 310 types:

3.3.6. Handy utilities

ConfigSlurper is a utility class for reading configuration files defined in the form of Groovy scripts. Like it is the case with Java *.properties files, ConfigSlurper allows a dot notation. But in addition, it allows for Closure scoped configuration values and arbitrary object types.

As can be seen in the above example, the parse method can be used to retrieve groovy.util.ConfigObject instances. The ConfigObject is a specialized java.util.Map implementation that either returns the configured value or a new ConfigObject instance but never null .

In the case of a dot being part of a configuration variable name, it can be escaped by using single or double quotes.

In addition, ConfigSlurper comes with support for environments . The environments method can be used to hand over a Closure instance that itself may consist of a several sections. Let’s say we wanted to create a particular configuration value for the development environment. When creating the ConfigSlurper instance we can use the ConfigSlurper(String) constructor to specify the target environment.

The environments method is built-in but the registerConditionalBlock method can be used to register other method names in addition to the environments name.

For Java integration purposes the toProperties method can be used to convert the ConfigObject to a java.util.Properties object that might be stored to a *.properties text file. Be aware though that the configuration values are converted to String instances during adding them to the newly created Properties instance.

The Expando class can be used to create a dynamically expandable object. Despite its name it does not use the ExpandoMetaClass underneath. Each Expando object represents a standalone, dynamically-crafted instance that can be extended with properties (or methods) at runtime.

A special case occurs when a dynamic property registers a Closure code block. Once being registered it can be invoked as it would be done with a method call.

Groovy comes with observable lists, maps and sets. Each of these collections trigger java.beans.PropertyChangeEvent events when elements are added, removed or changed. Note that a PropertyChangeEvent is not only signalling that a certain event has occurred, moreover, it holds information on the property name and the old/new value a certain property has been changed to.

Depending on the type of change that has happened, observable collections might fire more specialized PropertyChangeEvent types. For example, adding an element to an observable list fires an ObservableList.ElementAddedEvent event.

The ObservableList.ElementClearedEvent event type is another interesting one. Whenever multiple elements are removed, for example when calling clear() , it holds the elements being removed from the list.

To get an overview of all the supported event types the reader is encouraged to have a look at the JavaDoc documentation or the source code of the observable collection in use.

ObservableMap and ObservableSet come with the same concepts as we have seen for ObservableList in this section.

3.4. Metaprogramming

The Groovy language supports two flavors of metaprogramming: runtime and compile-time. The first allows altering the class model and the behavior of a program at runtime while the second only occurs at compile-time. Both have pros and cons that we will detail in this section.

3.4.1. Runtime metaprogramming

With runtime metaprogramming we can postpone to runtime the decision to intercept, inject and even synthesize methods of classes and interfaces. For a deep understanding of Groovy’s metaobject protocol (MOP) we need to understand Groovy objects and Groovy’s method handling. In Groovy we work with three kinds of objects: POJO, POGO and Groovy Interceptors. Groovy allows metaprogramming for all types of objects but in a different manner.

POJO - A regular Java object whose class can be written in Java or any other language for the JVM.

POGO - A Groovy object whose class is written in Groovy. It extends java.lang.Object and implements the groovy.lang.GroovyObject interface by default.

Groovy Interceptor - A Groovy object that implements the groovy.lang.GroovyInterceptable interface and has method-interception capability which is discussed in the GroovyInterceptable section.

For every method call Groovy checks whether the object is a POJO or a POGO. For POJOs, Groovy fetches its MetaClass from the groovy.lang.MetaClassRegistry and delegates method invocation to it. For POGOs, Groovy takes more steps, as illustrated in the following figure:

GroovyObject interface

groovy.lang.GroovyObject is the main interface in Groovy as the Object class is in Java. GroovyObject has a default implementation in the groovy.lang.GroovyObjectSupport class and it is responsible to transfer invocation to the groovy.lang.MetaClass object. The GroovyObject source looks like this:

This method is primarily intended to be used in conjunction with the GroovyInterceptable interface or an object’s MetaClass where it will intercept all method calls.

It is also invoked when the method called is not present on a Groovy object. Here is a simple example using an overridden invokeMethod() method:

However, the use of invokeMethod to intercept missing methods is discouraged. In cases where the intent is to only intercept method calls in the case of a failed method dispatch use methodMissing instead.

Every read access to a property can be intercepted by overriding the getProperty() method of the current object. Here is a simple example:

You can intercept write access to properties by overriding the setProperty() method:

You can access an object’s metaClass or set your own MetaClass implementation for changing the default interception mechanism. For example, you can write your own implementation of the MetaClass interface and assign it to objects in order to change the interception mechanism:

This functionality is related to the MetaClass implementation. In the default implementation you can access fields without invoking their getters and setters. The examples below demonstrates this approach:

Groovy supports the concept of methodMissing . This method differs from invokeMethod in that it is only invoked in the case of a failed method dispatch when no method can be found for the given name and/or the given arguments:

Typically when using methodMissing it is possible to cache the result for the next time the same method is called.

For example, consider dynamic finders in GORM. These are implemented in terms of methodMissing . The code resembles something like this:

Notice how, if we find a method to invoke, we then dynamically register a new method on the fly using ExpandoMetaClass . This is so that the next time the same method is called it is more efficient. This way of using methodMissing does not have the overhead of invokeMethod and is not expensive from the second call on.

Groovy supports the concept of propertyMissing for intercepting otherwise failing property resolution attempts. In the case of a getter method, propertyMissing takes a single String argument containing the property name:

The propertyMissing(String) method is only called when no getter method for the given property can be found by the Groovy runtime.

For setter methods a second propertyMissing definition can be added that takes an additional value argument:

As with methodMissing it is best practice to dynamically register new properties at runtime to improve the overall lookup performance.

Static variant of methodMissing method can be added via the ExpandoMetaClass or can be implemented at the class level with $static_methodMissing method.

Static variant of propertyMissing method can be added via the ExpandoMetaClass or can be implemented at the class level with $static_propertyMissing method.

The groovy.lang.GroovyInterceptable interface is marker interface that extends GroovyObject and is used to notify the Groovy runtime that all methods should be intercepted through the method dispatcher mechanism of the Groovy runtime.

When a Groovy object implements the GroovyInterceptable interface, its invokeMethod() is called for any method calls. Below you can see a simple example of an object of this type:

The next piece of code is a test which shows that both calls to existing and non-existing methods will return the same value.

If we want to intercept all method calls but do not want to implement the GroovyInterceptable interface we can implement invokeMethod() on an object’s MetaClass . This approach works for both POGOs and POJOs, as shown by this example:

There are situations where it is useful if a class not under control had additional methods. In order to enable this capability, Groovy implements a feature borrowed from Objective-C, called Categories .

Categories are implemented with so-called category classes . A category class is special in that it needs to meet certain pre-defined rules for defining extension methods.

There are a few categories that are included in the system for adding functionality to classes that make them more usable within the Groovy environment:

groovy.time.TimeCategory

groovy.servlet.ServletCategory

groovy.xml.dom.DOMCategory

Category classes aren’t enabled by default. To use the methods defined in a category class it is necessary to apply the scoped use method that is provided by the GDK and available from inside every Groovy object instance:

The use method takes the category class as its first parameter and a closure code block as second parameter. Inside the Closure access to the category methods is available. As can be seen in the example above even JDK classes like java.lang.Integer or java.util.Date can be enriched with user-defined methods.

A category needs not to be directly exposed to the user code, the following will also do:

When we have a look at the groovy.time.TimeCategory class we see that the extension methods are all declared as static methods. In fact, this is one of the requirements that must be met by category classes for its methods to be successfully added to a class inside the use code block:

Another requirement is the first argument of the static method must define the type the method is attached to once being activated. The other arguments are the normal arguments the method will take as parameters.

Because of the parameter and static method convention, category method definitions may be a bit less intuitive than normal method definitions. As an alternative Groovy comes with a @Category annotation that transforms annotated classes into category classes at compile-time.

Applying the @Category annotation has the advantage of being able to use instance methods without the target type as a first parameter. The target type class is given as an argument to the annotation instead.

Metaclasses

As explained earlier, Metaclasses play a central role in method resolution. For every method invocation from groovy code, Groovy will find the MetaClass for the given object and delegate the method resolution to the metaclass via groovy.lang.MetaClass#invokeMethod(java.lang.Class,java.lang.Object,java.lang.String,java.lang.Object,boolean,boolean) which should not be confused with groovy.lang.GroovyObject#invokeMethod(java.lang.String,java.lang.Object) which happens to be a method that the metaclass may eventually call.

By default, objects get an instance of MetaClassImpl that implements the default method lookup. This method lookup includes looking up of the method in the object class ("regular" method) but also if no method is found this way it will resort to calling methodMissing and ultimately groovy.lang.GroovyObject#invokeMethod(java.lang.String,java.lang.Object)

Custom metaclasses

You can change the metaclass of any object or class and replace it with a custom implementation of the MetaClass groovy.lang.MetaClass . Usually you will want to extend one of the existing metaclasses such as MetaClassImpl , DelegatingMetaClass , ExpandoMetaClass , or ProxyMetaClass ; otherwise you will need to implement the complete method lookup logic. Before using a new metaclass instance you should call groovy.lang.MetaClass#initialize() , otherwise the metaclass may or may not behave as expected.

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.

You can change the metaclass of individual objects separately, so it’s possible to have multiple object of the same class with different metaclasses.

ExpandoMetaClass

Groovy comes with a special MetaClass the so-called ExpandoMetaClass . It is special in that it allows for dynamically adding or changing methods, constructors, properties and even static methods by using a neat closure syntax.

Applying those modifications can be especially useful in mocking or stubbing scenarios as shown in the Testing Guide .

Every java.lang.Class is supplied by Groovy with a special metaClass property that will give you a reference to an ExpandoMetaClass instance. This instance can then be used to add methods or change the behaviour of already existing ones.

The following sections go into detail on how ExpandoMetaClass can be used in various scenarios.

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:

getMetaMethod

hasMetaMethod

getMetaProperty

hasMetaProperty

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.

Extension modules

An extension module allows you to add new methods to existing classes, including classes which are precompiled, like classes from the JDK. Those new methods, unlike those defined through a metaclass or using a category, are available globally. For example, when you write:

The getText method doesn’t exist on the File class. However, Groovy knows it because it is defined in a special class, ResourceGroovyMethods :

You may notice that the extension method is defined using a static method in a helper class (where various extension methods are defined). The first argument of the getText method corresponds to the receiver, while additional parameters correspond to the arguments of the extension method. So here, we are defining a method called getText on the File class (because the first argument is of type File ), which takes a single argument as a parameter (the encoding String ).

The process of creating an extension module is simple:

write an extension class like above

write a module descriptor file

Then you have to make the extension module visible to Groovy, which is as simple as having the extension module classes and descriptor available on classpath. This means that you have the choice:

either provide the classes and module descriptor directly on classpath

or bundle your extension module into a jar for reusability

An extension module may add two kind of methods to a class:

instance methods (to be called on an instance of a class)

static methods (to be called on the class itself)

To add an instance method to an existing class, you need to create an extension class. For example, let’s say you want to add a maxRetries method on Integer which accepts a closure and executes it at most n times until no exception is thrown. To do that, you only need to write the following:

Then, after having declared your extension class , you can call it this way:

It is also possible to add static methods to a class. In that case, the static method needs to be defined in its own file. Static and instance extension methods cannot be present in the same class.

In which case you can call it directly on the String class:

For Groovy to be able to load your extension methods, you must declare your extension helper classes. You must create a file named org.codehaus.groovy.runtime.ExtensionModule into the META-INF/groovy directory:

The module descriptor requires 4 keys:

moduleName : the name of your module

moduleVersion : the version of your module. Note that version number is only used to check that you don’t load the same module in two different versions.

extensionClasses : the list of extension helper classes for instance methods. You can provide several classes, given that they are comma separated.

staticExtensionClasses : the list of extension helper classes for static methods. You can provide several classes, given that they are comma separated.

Note that it is not required for a module to define both static helpers and instance helpers, and that you may add several classes to a single module. You can also extend different classes in a single module without problem. It is even possible to use different classes in a single extension class, but it is recommended to group extension methods into classes by feature set.

It’s worth noting that you can’t use an extension which is compiled at the same time as code using it. That means that to use an extension, it has to be available on classpath, as compiled classes, before the code using it gets compiled. Usually, this means that you can’t have the test classes in the same source unit as the extension class itself. Since in general, test sources are separated from normal sources and executed in another step of the build, this is not an issue.

Unlike categories, extension modules are compatible with type checking: if they are found on classpath, then the type checker is aware of the extension methods and will not complain when you call them. It is also compatible with static compilation.

3.4.2. Compile-time metaprogramming

Compile-time metaprogramming in Groovy allows code generation at compile-time. Those transformations are altering the Abstract Syntax Tree (AST) of a program, which is why in Groovy we call it AST transformations. AST transformations allow you to hook into the compilation process, modify the AST and continue the compilation process to generate regular bytecode. Compared to runtime metaprogramming, this has the advantage of making the changes visible in the class file itself (that is to say, in the bytecode). Making it visible in the bytecode is important for example if you want the transformations to be part of the class contract (implementing interfaces, extending abstract classes, …​) or even if you need your class to be callable from Java (or other JVM languages). For example, an AST transformation can add methods to a class. If you do it with runtime metaprogramming, the new method would only be visible from Groovy. If you do the same using compile-time metaprogramming, the method would be visible from Java too. Last but not least, performance would likely be better with compile-time metaprogramming (because no initialization phase is required).

In this section, we will start with explaining the various compile-time transformations that are bundled with the Groovy distribution. In a subsequent section, we will describe how you can implement your own AST transformations and what are the disadvantages of this technique.

Available AST transformations

Groovy comes with various AST transformations covering different needs: reducing boilerplate (code generation), implementing design patterns (delegation, …​), logging, declarative concurrency, cloning, safer scripting, tweaking the compilation, implementing Swing patterns, testing and eventually managing dependencies. If none of those AST transformations cover your needs, you can still implement your own, as show in section Developing your own AST transformations .

AST transformations can be separated into two categories:

global AST transformations are applied transparently, globally, as soon as they are found on compile classpath

local AST transformations are applied by annotating the source code with markers. Unlike global AST transformations, local AST transformations may support parameters.

Groovy doesn’t ship with any global AST transformation, but you can find a list of local AST transformations available for you to use in your code here:

Code generation transformations

This category of transformation includes AST transformations which help removing boilerplate code. This is typically code that you have to write but that does not carry any useful information. By autogenerating this boilerplate code, the code you have to write is left clean and concise and the chance of introducing an error by getting such boilerplate code incorrect is reduced.

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:

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 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: