Groovy Language Documentation
Uploaded by
osama helalGroovy Language Documentation
Uploaded by
osama helal1/6/2019 Groovy Language Documentation
Groovy Language Documentation
Version 2.5.5
Table of Contents
Introduction
1. Groovy Language Speci cation
1.1. Syntax
1.1.1. Comments
Single line comment
Multiline comment
GroovyDoc comment
Shebang line
1.1.2. Keywords
1.1.3. Identi ers
Normal identi ers
Quoted identi ers
1.1.4. Strings
Single quoted string
String concatenation
Triple single quoted string
Escaping special characters
Unicode escape sequence
Double quoted string
String interpolation
Special case of interpolating closure expressions
Interoperability with Java
GString and String hashCodes
Triple double quoted string
Slashy string
Dollar slashy string
String summary table
Characters
1.1.5. Numbers
Integral literals
Alternative non-base 10 representations
Binary literal
Octal literal
Hexadecimal literal
Decimal literals
Underscore in literals
Number type su xes
Math operations
The case of the division operator
The case of the power operator
1.1.6. Booleans
1.1.7. Lists
1.1.8. Arrays
http://docs.groovy-lang.org/latest/html/documentation/ 1/502
1/6/2019 1.1.9. Maps Groovy Language Documentation
1.2. Operators
1.2.1. Arithmetic operators
Normal arithmetic operators
Unary operators
Assignment arithmetic operators
1.2.2. Relational operators
1.2.3. Logical operators
Precedence
Short-circuiting
1.2.4. Bitwise operators
1.2.5. Conditional operators
Not operator
Ternary operator
Elvis operator
1.2.6. Object operators
Safe navigation operator
Direct eld access operator
Method pointer operator
1.2.7. Regular expression operators
Pattern operator
Find operator
Match operator
1.2.8. Other operators
Spread operator
Spreading method arguments
Spread list elements
Spread map elements
Range operator
Spaceship operator
Subscript operator
Membership operator
Identity operator
Coercion operator
Diamond operator
Call operator
1.2.9. Operator precedence
1.2.10. Operator overloading
1.3. Program structure
1.3.1. Package names
1.3.2. Imports
Default imports
Simple import
Star import
Static import
Static import aliasing
Static star import
http://docs.groovy-lang.org/latest/html/documentation/ 2/502
1/6/2019 Import aliasing Groovy Language Documentation
1.3.3. Scripts versus classes
public static void main vs script
Script class
Methods
Variables
1.4. Object orientation
1.4.1. Types
Primitive types
Class
Normal class
Inner class
Anonymous inner class
Abstract class
Interface
Constructors
Positional parameters
Named parameters
Methods
Method de nition
Named parameters
Mixing named and positional parameters
Default arguments
Varargs
Method selection algorithm
Exception declaration
Fields and properties
Fields
Properties
Annotation
Annotation de nition
Annotation placement
Annotation member values
Retention policy
Closure annotation parameters
Meta-annotations
Declaring meta-annotations
Behavior of meta-annotations
Meta-annotation parameters
Handling duplicate annotations
Custom annotation processors
Inheritance
Generics
1.4.2. Traits
Methods
Public methods
Abstract methods
http://docs.groovy-lang.org/latest/html/documentation/ 3/502
1/6/2019 Private methods Groovy Language Documentation
Final methods
The meaning of this
Interfaces
Properties
Fields
Private elds
Public elds
Composition of behaviors
Overriding default methods
Extending traits
Simple inheritance
Multiple inheritance
Duck typing and traits
Dynamic code
Dynamic methods in a trait
Multiple inheritance con icts
Default con ict resolution
User con ict resolution
Runtime implementation of traits
Implementing a trait at runtime
Implementing multiple traits at once
Chaining behavior
Semantics of super inside a trait
Advanced features
SAM type coercion
Di erences with Java 8 default methods
Di erences with mixins
Static methods, properties and elds
Inheritance of state gotchas
Self types
Type constraints on traits
The @SelfType annotation
Limitations
Compatibility with AST transformations
Pre x and post x operations
1.5. Closures
1.5.1. Syntax
De ning a closure
Closures as an object
Calling a closure
1.5.2. Parameters
Normal parameters
Implicit parameter
Varargs
1.5.3. Delegation strategy
Groovy closures vs lambda expressions
http://docs.groovy-lang.org/latest/html/documentation/ 4/502
1/6/2019 Owner, delegate and this Groovy Language Documentation
The meaning of this
Owner of a closure
Delegate of a closure
Delegation strategy
1.5.4. Closures in GStrings
1.5.5. Closure coercion
1.5.6. Functional programming
Currying
Left currying
Right currying
Index based currying
Memoization
Composition
Trampoline
Method pointers
1.6. Semantics
1.6.1. Statements
Variable de nition
Variable assignment
Multiple assignment
Over ow and Under ow
Object destructuring with multiple assignment
Control structures
Conditional structures
if / else
switch / case
Looping structures
Classic for loop
for in loop
while loop
Exception handling
try / catch / nally
Multi-catch
Power assertion
Labeled statements
1.6.2. Expressions
GPath expressions
Object navigation
Expression Deconstruction
GPath for XML navigation
1.6.3. Promotion and coercion
Number promotion
Closure to type coercion
Assigning a closure to a SAM type
Calling a method accepting a SAM type with a closure
Closure to arbitrary type coercion
http://docs.groovy-lang.org/latest/html/documentation/ 5/502
1/6/2019 Map to type coercion Groovy Language Documentation
String to enum coercion
Custom type coercion
Class literals vs variables and the as operator
1.6.4. Optionality
Optional parentheses
Optional semicolons
Optional return keyword
Optional public keyword
1.6.5. The Groovy Truth
Boolean expressions
Collections and Arrays
Matchers
Iterators and Enumerations
Maps
Strings
Numbers
Object References
Customizing the truth with asBoolean() methods
1.6.6. Typing
Optional typing
Static type checking
The @TypeChecked annotation
Activating type checking at compile time
Skipping sections
Type checking assignments
List and map constructors
Method resolution
Type inference
Principles
Variables vs elds in type inference
Collection literal type inference
Least upper bound
instanceof inference
Flow typing
Advanced type inference
Closures and type inference
Return type inference
Parameter type inference
Explicit closure parameters
Parameters inferred from single-abstract method types
The @ClosureParams annotation
@DelegatesTo
Static compilation
Dynamic vs static
The @CompileStatic annotation
Key bene ts
http://docs.groovy-lang.org/latest/html/documentation/ 6/502
1/6/2019 1.6.7. Type checking extensions Groovy Language Documentation
Writing a type checking extension
Towards a smarter type checker
The extensions attribute
A DSL for type checking
Type checking extensions API
AST
Events
Working with extensions
Support classes
Class nodes
Helping the type checker
Throwing an error
isXXXExpression
Virtual methods
Scoping
Other useful methods
Advanced type checking extensions
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
Examples
2. Tools
2.1. Running Groovy from the commandline
2.1.1. groovy, the Groovy command
2.2. Compiling Groovy
2.2.1. groovyc, the Groovy compiler
2.2.2. Ant task
<groovyc>
Description
Required taskdef
<groovyc> Attributes
<groovyc> Nested Elements
Joint Compilation
2.2.3. Gant
2.2.4. Gradle
2.2.5. Maven integration
GMaven and GMavenPlus
GMaven
GMavenPlus
GMaven 2
The Groovy Eclipse Maven plugin
2.2.6. Joint compilation
http://docs.groovy-lang.org/latest/html/documentation/ 7/502
1/6/2019 2.2.7. Android support Groovy Language Documentation
2.3. Groovysh, the Groovy shell
2.3.1. Groovy : Groovy Shell
Features
Command-line Options and Arguments
Evaluating Expressions
Simple Expressions
Evaluation Result
Multi-line Expressions
De ne a Class
Use the Class
Variables
Functions
Commands
Recognized Commands
help
exit
import
grab
display
clear
show
inspect
purge
edit
load
save
record
history
alias
doc
set
Preferences
Recognized Preferences
interpreterMode
verbosity
colors
show-last-result
sanitize-stack-trace
editor
Setting a Preference
Listing Preferences
Clearing Preferences (i.e. Resetting to Defaults)
User Pro le Scripts and State
Pro le Scripts
$HOME/.groovy/groovysh.profile
$HOME/.groovy/groovysh.rc
http://docs.groovy-lang.org/latest/html/documentation/ 8/502
1/6/2019 State Groovy Language Documentation
$HOME/.groovy/groovysh.history
Custom commands
Troubleshooting
Platform Problems
Problems loading the JLine DLL
Problems with Cygwin on Windows
2.3.2. GMavenPlus Maven Plugin
2.3.3. Gradle Groovysh Plugin
2.4. groovyConsole, the Groovy swing console
2.4.1. Groovy : Groovy Console
2.4.2. Basics
2.4.3. Features
Command-line Options and Arguments
Running Scripts
Editing Files
History and results
Interrupting a script
And more
2.4.4. Embedding the Console
2.4.5. Visualizing script output results
2.4.6. AST browser
2.5. groovydoc, the Groovy & Java documentation generator
2.5.1. The groovydoc command line tool
2.5.2. The groovydoc Ant task
Required taskdef
<groovydoc> Attributes
<groovydoc> Nested Elements
link
Example #1 - <groovydoc> Ant task
Example #2 - Executing <groovydoc> from Groovy
Custom templates
Custom Groovydoc class
Using the custom groovydoc task
2.5.3. GMavenPlus Maven Plugin
2.6. IDE integration
3. User Guides
3.1. Getting started
3.1.1. Download
Stable
Snapshots
Prerequisites
3.1.2. Maven Repository
Stable Release
3.1.3. SDKMAN! (The Software Development Kit Manager)
3.1.4. Other ways to get Groovy
Installation on Mac OS X
http://docs.groovy-lang.org/latest/html/documentation/ 9/502
1/6/2019 MacPorts Groovy Language Documentation
Homebrew
Installation on Windows
Other Distributions
Source Code
IDE plugin
3.1.5. Install Binary
3.2. Di erences with Java
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
3.2.6. Inner classes
Static inner classes
Anonymous Inner Classes
Creating Instances of Non-Static Inner Classes
3.2.7. Lambdas
3.2.8. GStrings
3.2.9. String and Character literals
3.2.10. Primitives and wrappers
3.2.11. Behaviour of ==
3.2.12. Conversions
3.2.13. Extra keywords
3.3. Groovy Development Kit
3.3.1. Working with IO
Reading les
Writing les
Traversing le trees
Data and objects
Executing External Processes
3.3.2. Working with collections
Lists
List literals
List as a boolean expression
Iterating on a list
Manipulating lists
Filtering and searching
Adding or removing elements
Set operations
Sorting
Duplicating elements
Maps
Map literals
Map property notation
Iterating on maps
Manipulating maps
http://docs.groovy-lang.org/latest/html/documentation/ 10/502
1/6/2019 Adding or removing elements Groovy Language Documentation
Keys, values and entries
Filtering and searching
Grouping
Ranges
Syntax enhancements for collections
GPath support
Spread operator
The star-dot `*.' operator
Slicing with the subscript operator
Enhanced Collection Methods
3.3.3. Working with legacy Date/Calendar types
3.3.4. Working with Date/Time types
Formatting and parsing
Manipulating date/time
Addition and subtraction
Multiplication and division
Incrementing and decrementing
Negation
Interacting with date/time values
Property notation
Ranges, upto , and downto
Combining date/time values
Creating periods and durations
Converting between legacy and JSR 310 types
3.3.5. Handy utilities
Con gSlurper
Expando
Observable list, map and set
3.4. Metaprogramming
3.4.1. Runtime metaprogramming
GroovyObject interface
invokeMethod
get/setProperty
get/setMetaClass
get/setAttribute
methodMissing
propertyMissing
static methodMissing
static propertyMissing
GroovyInterceptable
Categories
Metaclasses
The default metaclass MetaClassImpl
Custom metaclasses
Delegating metaclass
Magic package
http://docs.groovy-lang.org/latest/html/documentation/ 11/502
1/6/2019 Per instance metaclass Groovy Language Documentation
ExpandoMetaClass
Methods
Properties
Constructors
Static Methods
Borrowing Methods
Dynamic Method Names
Runtime Discovery
GroovyObject Methods
Overriding Static invokeMethod
Extending Interfaces
Extension modules
Extending existing classes
Instance methods
Static methods
Module descriptor
Extension modules and classpath
Compatibility with type checking
3.4.2. Compile-time metaprogramming
Available AST transformations
Code generation transformations
@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
Class design annotations
@groovy.transform.BaseScript
@groovy.lang.Delegate
@groovy.transform.Immutable
@groovy.transform.ImmutableBase
@groovy.transform.PropertyOptions
@groovy.transform.VisibilityOptions
@groovy.transform.ImmutableOptions
@groovy.transform.KnownImmutable
http://docs.groovy-lang.org/latest/html/documentation/ 12/502
1/6/2019 @groovy.transform.Memoized Groovy Language Documentation
@groovy.transform.TailRecursive
@groovy.lang.Singleton
@groovy.lang.Mixin
Logging improvements
@groovy.util.logging.Log
@groovy.util.logging.Commons
@groovy.util.logging.Log4j
@groovy.util.logging.Log4j2
@groovy.util.logging.Slf4j
Declarative concurrency
@groovy.transform.Synchronized
@groovy.transform.WithReadLock and @groovy.transform.WithWriteLock
Easier cloning and externalizing
@groovy.transform.AutoClone
@groovy.transform.AutoExternalize
Safer scripting
@groovy.transform.ThreadInterrupt
@groovy.transform.TimedInterrupt
@groovy.transform.ConditionalInterrupt
Compiler directives
@groovy.transform.Field
@groovy.transform.PackageScope
@groovy.transform.AutoFinal
@groovy.transform.AnnotationCollector
@groovy.transform.TypeChecked
@groovy.transform.CompileStatic
@groovy.transform.CompileDynamic
@groovy.lang.DelegatesTo
@groovy.transform.SelfType
Swing patterns
@groovy.beans.Bindable
@groovy.beans.ListenerList
@groovy.beans.Vetoable
Test assistance
@groovy.transform.NotYetImplemented
@groovy.transform.ASTTest
Grape handling
@groovy.lang.Grab
@groovy.lang.GrabConfig
@groovy.lang.GrabExclude
@groovy.lang.GrabResolver
@groovy.lang.Grapes
Developing AST transformations
Compilation phases guide
Local transformations
http://docs.groovy-lang.org/latest/html/documentation/ 13/502
1/6/2019 Global transformations Groovy Language Documentation
AST API guide
AbstractASTTransformation
ClassCodeExpressionTransformer
AST Nodes
Macros
Introduction
Statements and expressions
Variable substitution
MacroClass
@Macro methods
Testing AST transformations
Separating source trees
Debugging AST transformations
ASTMatcher
ASTTest
External references
3.5. Dependency management with Grape
3.5.1. Quick start
Add a Dependency
Specify Additional Repositories
Maven Classi ers
Excluding Transitive Dependencies
JDBC Drivers
Using Grape From the Groovy Shell
Proxy settings
Logging
3.5.2. Detail
3.5.3. Usage
Annotation
Multiple Grape Annotations
Method call
grab(HashMap) Parameters
Arguments Map arguments
Command Line Tool
Advanced con guration
Repository Directory
Customize Ivy settings
More Examples
3.6. Testing Guide
3.6.1. Introduction
3.6.2. Language Features
Power Assertions
Mocking and Stubbing
Map Coercion
Closure Coercion
MockFor and StubFor
http://docs.groovy-lang.org/latest/html/documentation/ 14/502
1/6/2019 Expando Meta-Class (EMC) Groovy Language Documentation
GDK Methods
Iterable#combinations
Iterable#eachCombination
Tool Support
Test Code Coverage
3.6.3. Testing with JUnit
JUnit 3
Assertion Methods
shouldFail Methods
notYetImplemented Method
JUnit 4
JUnit 5
3.6.4. Testing with Spock
Speci cations
More Spock
3.6.5. Functional Tests with Geb
A Geb Script
More Geb
3.7. Processing JSON
3.7.1. JsonSlurper
Parser Variants
3.7.2. JsonOutput
Customizing Output
Formatted Output
Builders
3.8. Interacting with a SQL database
3.8.1. Connecting to the database
Connecting with a DataSource
Connecting using @Grab
3.8.2. Executing SQL
Creating tables
3.8.3. Basic CRUD operations
Creating/Inserting data
Reading rows
Updating rows
Deleting rows
3.8.4. Advanced SQL operations
Working with transactions
Using batches
Performing pagination
Fetching metadata
Named and named-ordinal parameters
Stored procedures
3.8.5. Using DataSets
3.9. Processing XML
3.9.1. Parsing XML
http://docs.groovy-lang.org/latest/html/documentation/ 15/502
1/6/2019 XmlParser and XmlSlurper Groovy Language Documentation
DOMCategory
3.9.2. GPath
Simply traversing the tree
Flexible navigation with children (*), depthFirst (**) and breadthFirst
3.9.3. Creating XML
MarkupBuilder
StreamingMarkupBuilder
MarkupBuilderHelper
DOMToGroovy
3.9.4. Manipulating XML
Adding nodes
Modifying / Removing nodes
Printing XML
XmlUtil
3.10. Scripting Ant tasks
3.11. The <groovy> Ant Task
3.11.1. Required taskdef
3.11.2. <groovy> attributes
3.11.3. Parameters speci ed as nested elements
<classpath>
<arg>
3.11.4. Available bindings
3.11.5. Examples
3.12. Template engines
3.12.1. Introduction
3.12.2. Template framework
3.12.3. SimpleTemplateEngine
Advanced Usage Note
3.12.4. StreamingTemplateEngine
3.12.5. GStringTemplateEngine
3.12.6. XmlTemplateEngine
3.12.7. The MarkupTemplateEngine
The template format
Basics
Support methods
Includes
Fragments
Layouts
Rendering contents
Creation of a template engine
Con guration options
Automatic formatting
Automatic escaping
Common gotchas
Strings containing markup
Internationalization
http://docs.groovy-lang.org/latest/html/documentation/ 16/502
1/6/2019 Custom template classes Groovy Language Documentation
Type checked templates
Optional type checking
Alternative declaration of types
Performance of type checked templates
3.12.8. Other solutions
3.13. Servlet support
3.13.1. Implicit variables
3.13.2. Setting up groovylets
3.14. Integrating Groovy in a Java application
3.14.1. Groovy integration mechanisms
Eval
GroovyShell
Multiple sources
Sharing data between a script and the application
Custom script class
GroovyClassLoader
GroovyScriptEngine
CompilationUnit
3.14.2. Bean Scripting Framework
Getting started
Passing in variables
Other calling options
Access to the scripting engine
3.14.3. JSR 223 javax.script API
3.15. Domain-Speci c Languages
3.15.1. Command chains
3.15.2. Operator overloading
3.15.3. Script base classes
The Script class
The @BaseScript annotation
Alternate abstract method
3.15.4. Adding properties to numbers
3.15.5. @DelegatesTo
Explaining delegation strategy at compile time
@DelegatesTo
DelegatesTo modes
Simple delegation
Delegation strategy
Delegate to parameter
Multiple closures
Delegating to a generic type
Delegating to an arbitrary type
3.15.6. Compilation customizers
Introduction
Import customizer
AST transformation customizer
http://docs.groovy-lang.org/latest/html/documentation/ 17/502
1/6/2019 Secure AST customizer Groovy Language Documentation
Source aware customizer
Customizer builder
Import customizer
AST transformation customizer
Secure AST customizer
Source aware customizer
Inlining a customizer
Multiple customizers
Con g script ag
Static compilation by default
AST transformations
3.15.7. Custom type checking extensions
3.15.8. Builders
Creating a builder
BuilderSupport
FactoryBuilderSupport
Existing builders
MarkupBuilder
StreamingMarkupBuilder
SaxBuilder
StaxBuilder
DOMBuilder
NodeBuilder
JsonBuilder
StreamingJsonBuilder
SwingBuilder
AntBuilder
CliBuilder
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
Advanced CLI Usage
Apache Commons CLI
Picocli
ObjectGraphBuilder
JmxBuilder
FileTreeBuilder
3.16. Working with JMX
3.16.1. Introduction
http://docs.groovy-lang.org/latest/html/documentation/ 18/502
1/6/2019 3.16.2. Monitoring the JVM Groovy Language Documentation
3.16.3. Monitoring Tomcat
3.16.4. OC4J Example
3.16.5. WebLogic Example
3.16.6. Spring Example
3.16.7. Troubleshooting
java.lang.SecurityException
3.16.8. JmxBuilder
Instantiating JmxBuilder
JMX Connectors
Connector Server
Connector Client
JmxBuilder MBean Export
Implicit vs Explicit Descriptors
The JmxBuilder.export() Node
JmxBuilder.export() Syntax
Integration with GroovyMBean Class
MBean Registration with JmxBuilder.bean()
Implicit Export
JConsole view of Exported Bean
JmxBuilder.bean() Syntax
Bean() Node - Specifying MBean ObjectName
Bean() Node - Attribute Export
Export All Attributes with Wildcard "*"
Export Attribute List
Export Attribute with Explicit Descriptors
Bean() Node - Constructor Export
Export all Constructors with "*"
Export Constructors using Parameter Descriptor
Export Constructor with Explicit Descriptors
Bean() Node - Operation Export
Export All Operations with "*"
Export Operation List
Export Operations by Signature
Export Operations with Explicit Descriptors
Embedding Descriptor
Timer Export
Timer Node Syntax
Exporting a Timer
Timer Period
JmxBuilder and Events
Event Handling Closures
Parameterless
With Event Parameter
Handling Attribute onChange Event
Attribute onChange Event Object
Handling Operation onCall Event
http://docs.groovy-lang.org/latest/html/documentation/ 19/502
1/6/2019 Operation onCall Event Object Groovy Language Documentation
Listener MBean
Listening to JMX Events
Listener Node Syntax
Emitting JMX Events
Emitter Syntax
Declare the Emitter
Broadcast Event
Sending Event Objects
3.16.9. Further JMX Information
3.17. Creating Swing UIs
3.18. Security
3.19. Design patterns in Groovy
3.19.1. Patterns
Abstract Factory Pattern
Example
Adapter Pattern
Delegation Example
Inheritance Example
Adapting using Closures
Adapting using the ExpandoMetaClass
Bouncer Pattern
Null Checking Example
Validation Example
Chain of Responsibility Pattern
Example
Composite Pattern
Example
Decorator Pattern
Traditional Example
A touch of dynamic behaviour
Runtime behaviour embellishment
More dynamic decorating
Decorating with an Interceptor
Decorating with java.lang.re ect.Proxy
Decorating with Spring
Asynchronous Decorators using GPars
Delegation Pattern
Implement Delegation Pattern using ExpandoMetaClass
Implement Delegation Pattern using @Delegate annotation
Flyweight Pattern
Example
Iterator Pattern
Loan my Resource Pattern
Example
Null Object Pattern
Simple Example
http://docs.groovy-lang.org/latest/html/documentation/ 20/502
1/6/2019 Tree Example Groovy Language Documentation
Pimp my Library Pattern
Example
Proxy Pattern
Example
Singleton Pattern
Example: The Classic Java Singleton
Example: Singleton via MetaProgramming
Guice Example
Spring Example
Further information
State Pattern
Example
Variation 1: Leveraging Interface-Oriented Design
Variation 2: Extract State Pattern Logic
Variation 3: Bring on the DSL
Strategy Pattern
Example
Template Method Pattern
Example
Visitor Pattern
Simple Example
Advanced Example
Why to use this
What happens if we add a new type?
What if we want to have di erent iteration patterns?
Make it Groovy
Summary
Further Information
3.19.2. References
4. Acknowledgements
4.1. Contributors
4.2. License
Introduction
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-Speci c 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 sca olding code when developing web, GUI, database or console applications
http://docs.groovy-lang.org/latest/html/documentation/ 21/502
1/6/2019 simpli es testing by supporting unit testing and mocking out-of-the-box
Groovy Language Documentation
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 Speci cation
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 speci c constructs for Groovy, and allows certain simpli cations.
1.1.1. Comments
Single line comment
Single line comments start with // and can be found at any position in the line. The characters following // , till the end of the
line, are considered part of the comment.
// a standalone single line comment
println "hello" // a comment till the end of the line
Multiline 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 rst */ closing the comment. Multiline comments can thus be put
at the end of a statement, or even inside a statement.
/* a standalone multiline comment
spanning two lines */
println "hello" /* a multiline comment starting
at the end of a statement */
println 1 /* one */ + 2 /* two */
GroovyDoc comment
Similarly to multiline comments, GroovyDoc comments are multiline, but start with /** and end with */ . Lines following the rst
GroovyDoc comment line can optionally start with a star * . Those comments are associated with:
type de nitions (classes, interfaces, enums, annotations),
elds and properties de nitions
methods de nitions
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.
/**
* A Class description
*/
{
/** the name of the person */
name
/**
* Creates a greeting method for a certain person.
*
* @param otherPerson the person to greet
* @return a greeting message
*/
greet( otherPerson) {
"Hello ${otherPerson}"
}
}
GroovyDoc follows the same conventions as Java’s own JavaDoc. So you’ll be able to use the same tags as with JavaDoc.
http://docs.groovy-lang.org/latest/html/documentation/ 22/502
1/6/2019 Shebang line Groovy Language Documentation
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 .
#!/usr/bin/env groovy
println "Hello from the shebang line"
The # character must be the rst character of the le. Any indentation would yield a compilation error.
1.1.2. Keywords
The following list represents all the keywords of the Groovy language:
Table 1. Keywords
as assert break case
catch class const continue
def default do else
enum extends false nally
for goto if implements
import in instanceof interface
new null package return
super switch this throw
throws trait true try
while
1.1.3. Identi ers
Normal identi ers
Identi ers 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 identi ers (here, variable names):
name
item3
with_underscore
$dollarStart
But the following ones are invalid identi ers:
http://docs.groovy-lang.org/latest/html/documentation/ 23/502
1/6/2019 Groovy Language Documentation
3tier
a+b
a#b
All keywords are also valid identi ers when following a dot:
foo.
foo.
foo.
foo.
foo.
Quoted identi ers
Quoted identi ers 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 identi ers contain illegal
characters that are forbidden by the Java Language Speci cation, but which are allowed by Groovy when quoted. For example,
characters like a dash, a space, an exclamation mark, etc.
map = [:]
map."an identifier with a space and double quotes" = "ALLOWED"
map.'with-dash-signs-and-single-quotes' = "ALLOWED"
map."an identifier with a space and double quotes" == "ALLOWED"
map.'with-dash-signs-and-single-quotes' == "ALLOWED"
As we shall see in the following section on strings, Groovy provides di erent string literals. All kind of strings are actually allowed
after the dot:
map.'single quote'
map."double quote"
map.'''triple single quote'''
map."""triple double quote"""
map./slashy /
map.$/dollar slashy /$
There’s a di erence between plain character strings and Groovy’s GStrings (interpolated strings), as in that the latter case, the
interpolated values are inserted in the nal string for evaluating the whole identi er:
firstname = "Homer"
map."Simpson-${firstname}" = "Homer Simpson"
map.'Simpson-Homer' == "Homer Simpson"
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 string
Single quoted strings are a series of characters surrounded by single quotes:
'a single quoted string'
Single quoted strings are plain java.lang.String and don’t support interpolation.
String concatenation
All the Groovy strings can be concatenated with the + operator:
http://docs.groovy-lang.org/latest/html/documentation/ 24/502
1/6/2019 Groovy Language Documentation
'ab' == 'a' + 'b'
Triple single quoted string
Triple single quoted strings are a series of characters surrounded by triplets of single quotes:
'''a triple single quoted string'''
Triple single quoted strings are plain java.lang.String and don’t support interpolation.
Triple single quoted strings are multiline. You can span the content of the string across line boundaries without the need to split
the string in several pieces, without contatenation or newline escape characters:
aMultilineString = '''line one
line two
line three'''
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:
startingAndEndingWithANewline = '''
line one
line two
line three
'''
You will notice that the resulting string contains a newline character as rst character. It is possible to strip that character by
escaping the newline with a backslash:
strippedFirstNewline = '''\
line one
line two
line three
'''
!strippedFirstNewline.startsWith('\n')
Escaping special characters
You can escape single quotes with the the backslash character to avoid terminating the string literal:
'an escaped single quote: \' needs a backslash'
And you can escape the escape character itself with a double backslash:
'an escaped escape character: \\ needs a double backslash'
Some special characters also use the backslash as escape character:
Escape sequence Character
'\t' tabulation
'\b' backspace
'\n' newline
http://docs.groovy-lang.org/latest/html/documentation/ 25/502
1/6/2019 Groovy Language Documentation
Escape sequence Character
'\r' carriage return
'\f' formfeed
'\\' backslash
'\'' single quote (for single quoted and triple single quoted strings)
'\"' double quote (for double quoted and triple double quoted
strings)
Unicode escape sequence
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:
'The Euro currency symbol: \u20AC'
Double quoted string
Double quoted strings are a series of characters surrounded by double quotes:
"a double quoted string"
Double quoted strings are plain java.lang.String if there’s no interpolated expression, but are
groovy.lang.GString instances if interpolation is present.
To escape a double quote, you can use the backslash character: "A double quote: \"".
String interpolation
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 ${} or pre xed with $ for dotted expressions. The expression value inside the placeholder is evaluated to its
string representation when the GString is passed to a method taking a String as argument by calling toString() on that
expression.
Here, we have a string with a placeholder referencing a local variable:
name = 'Guillaume' // a plain string
greeting = "Hello ${name}"
greeting.toString() == 'Hello Guillaume'
But any Groovy expression is valid, as we can see in this example with an arithmetic expression:
sum = "The sum of 2 and 3 equals ${2 + 3}"
sum.toString() == 'The sum of 2 and 3 equals 5'
Not only are expressions allowed in between the ${} placeholder, but so are statements. However, a statement’s
value is just null . So if several statements are inserted in that placeholder, the last one should somehow return
a meaningful value to be inserted. For instance, "The sum of 1 and 2 is equal to ${def a = 1; def b = 2; a + b}" is
supported and works as expected but a good practice is usually to stick to simple expressions inside GString
placeholders.
In addition to ${} placeholders, we can also use a lone $ sign pre xing a dotted expression:
http://docs.groovy-lang.org/latest/html/documentation/ 26/502
1/6/2019 Groovy Language Documentation
person = [name: 'Guillaume', age: 36]
"$person.name is $person.age years old" == 'Guillaume is 36 years old'
But only dotted expressions of the form a.b , a.b.c , etc, are valid, but expressions that would contain parentheses like method
calls, curly braces for closures, or arithmetic operators would be invalid. Given the following variable de nition of a number:
number = 3.14
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:
shouldFail( ) {
println "$number.toString()"
}
You can think of "$number.toString()" as being interpreted by the parser as "${number.toString}()" .
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:
'${name}' == "\${name}"
Special case of interpolating closure expressions
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:
sParameterLessClosure = "1 + 2 == ${-> 3}" 1
sParameterLessClosure == '1 + 2 == 3'
sOneParamClosure = "1 + 2 == ${ w -> w << 3}" 2
sOneParamClosure == '1 + 2 == 3'
1 The closure is a parameterless closure which doesn’t take arguments.
Here, the closure takes a single java.io.StringWriter argument, to which you can append content with the << leftShift
2
operator. In either case, both placeholders are embedded closures.
In appearance, it looks like a more verbose way of de ning expressions to be interpolated, but closures have an interesting
advantage over mere expressions: lazy evaluation.
Let’s consider the following sample:
number = 1 1
eagerGString = "value == ${number}"
lazyGString = "value == ${ -> number }"
eagerGString == "value == 1" 2
lazyGString == "value == 1" 3
number = 2 4
eagerGString == "value == 1" 5
lazyGString == "value == 2" 6
We de ne a number variable containing 1 that we then interpolate within two GStrings, as an expression in
1
eagerGString and as a closure in lazyGString .
2 We expect the resulting string to contain the same string value of 1 for eagerGString .
3 Similarly for lazyGString
4 Then we change the value of the variable to a new number
http://docs.groovy-lang.org/latest/html/documentation/ 27/502
1/6/2019 5 With a plain interpolated expression, the value was Groovy
actuallyLanguage
bound atDocumentation
the time of creation of the GString.
But with a closure expression, the closure is called upon each coercion of the GString into String, resulting in an updated
6
string containing the new number value.
An embedded closure expression taking more than one parameter will generate an exception at runtime. Only
closures with zero or one parameters are allowed.
Interoperability with Java
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.
takeString( message) { 4
message 5
message
}
message = "The message is ${'hello'}" 1
message 2
result = takeString(message) 3
result
result == 'The message is hello'
1 We create a GString variable
2 We double check it’s an instance of the GString
3 We then pass that GString to a method taking a String as parameter
4 The signature of the takeString() method explicitly says its sole parameter is a String
5 We also verify that the parameter is indeed a String and not a GString.
GString and String hashCodes
Although interpolated strings can be used in lieu of plain Java strings, they di er with strings in a particular way: their hashCodes
are di erent. 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.
"one: ${1}".hashCode() != "one: 1".hashCode()
GString and Strings having di erent 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.
key = "a"
m = ["${key}": "letter ${key}"] 1
m["a"] == 2
1 The map is created with an initial pair whose key is a GString
2 When we try to fetch the value with a String key, we will not nd it, as Strings and GString have di erent hashCode values
Triple double quoted string
Triple double quoted strings behave like double quoted strings, with the addition that they are multiline, like the triple single
quoted strings.
http://docs.groovy-lang.org/latest/html/documentation/ 28/502
1/6/2019 Groovy Language Documentation
name = 'Groovy'
= """
Dear Mr ${name},
You're the winner of the lottery!
Yours sincerly,
Dave
"""
.toString().contains('Groovy')
Neither double quotes nor single quotes need be escaped in triple double quoted strings.
Slashy string
Beyond the usual quoted strings, Groovy o ers slashy strings, which use / as delimiters. Slashy strings are particularly useful for
de ning regular expressions and patterns, as there is no need to escape backslashes.
Example of a slashy string:
fooPattern = /.*foo.*/
fooPattern == '.*foo.*'
Only forward slashes need to be escaped with a backslash:
escapeSlash = /The character \/ is a forward slash/
escapeSlash == 'The character / is a forward slash'
Slashy strings are multiline:
multilineSlashy = /one
two
three/
multilineSlashy.contains('\n')
Slashy strings can also be interpolated (ie. a GString):
color = 'blue'
interpolatedSlashy = /a ${color} car/
interpolatedSlashy == 'a blue car'
There are a few gotchas to be aware of.
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 $()
will work with slashy strings.
Dollar slashy string
Dollar slashy strings are multiline GStrings delimited with an opening $/ and and a closing /$ . The escaping character is the
dollar sign, and it can escape another dollar, or a forward slash. But both dollar and forward slashes don’t need to be escaped,
except to escape the dollar of a string subsequence that would start like a GString placeholder sequence, or if you need to escape
a sequence that would start like a closing dollar slashy string delimiter.
http://docs.groovy-lang.org/latest/html/documentation/ 29/502
1/6/2019 Here’s an example: Groovy Language Documentation
name = "Guillaume"
date = "April, 1st"
dollarSlashy = $/
$name,
today we're ${date}.
$ dollar sign
$$ escaped dollar sign
\ backslash
/ forward slash
$/ escaped forward slash
$$$/ escaped opening dollar slashy
$/$$ escaped closing dollar slashy
/$
assert [
' ',
' , 1st',
'$ dollar sign',
'$ escaped dollar sign',
'\\ backslash',
'/ forward slash',
'/ escaped forward slash',
'$/ escaped opening dollar slashy',
'/$ escaped closing dollar slashy'
].every { dollarSlashy.contains(it) }
String summary table
String name String syntax Interpolated Multiline Escape character
Single quoted '…' \
Triple single quoted '''…''' \
Double quoted "…" \
Triple double quoted """…""" \
Slashy /…/ \
Dollar slashy $/…/$ $
Characters
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 di erent means:
c1 = 'A' 1
c1
c2 = 'B' 2
c2
c3 = ( )'C' 3
c3
1 by being explicit when declaring a variable holding the character by specifying the char type
2 by using type coercion with the as operator
3 by using a cast to char operation
http://docs.groovy-lang.org/latest/html/documentation/ 30/502
1/6/2019 Groovy Language Documentation
The rst option 1 is interesting when the character is held in a variable, while the other two ( 2 and 3 ) are more
interesting when a char value must be passed as argument of a method call.
1.1.5. Numbers
Groovy supports di erent 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:
byte
char
short
int
long
java.lang.BigInteger
You can create integral numbers of those types with the following declarations:
// primitive types
b = 1
c = 2
s = 3
i = 4
l = 5
// infinite precision
bi = 6
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:
a = 1
a
// Integer.MAX_VALUE
b = 2147483647
b
// Integer.MAX_VALUE + 1
c = 2147483648
c
// Long.MAX_VALUE
d = 9223372036854775807
d
// Long.MAX_VALUE + 1
e = 9223372036854775808
e
As well as for negative numbers:
http://docs.groovy-lang.org/latest/html/documentation/ 31/502
1/6/2019 Groovy Language Documentation
na = -1
na
// Integer.MIN_VALUE
nb = -2147483648
nb
// Integer.MIN_VALUE - 1
nc = -2147483649
nc
// Long.MIN_VALUE
nd = -9223372036854775808
nd
// Long.MIN_VALUE - 1
ne = -9223372036854775809
ne
Alternative non-base 10 representations
Numbers can also be represented in binary, octal, hexadecimal and decimal bases.
Binary literal
Binary numbers start with a 0b pre x:
xInt = 0b10101111
xInt == 175
xShort = 0b11001001
xShort == 201
xByte = 0b11
xByte == 3
xLong = 0b101101101101
xLong == 2925l
xBigInteger = 0b111100100001
xBigInteger == 3873g
xNegativeInt = -0b10101111
xNegativeInt == -175
Octal literal
Octal numbers are speci ed in the typical format of 0 followed by octal digits.
xInt = 077
xInt == 63
xShort = 011
xShort == 9
xByte = 032
xByte == 26
xLong = 0246
xLong == 166l
xBigInteger = 01111
xBigInteger == 585g
xNegativeInt = -077
xNegativeInt == -63
Hexadecimal literal
http://docs.groovy-lang.org/latest/html/documentation/ 32/502
1/6/2019 Hexadecimal numbers are speci ed in the typical format of 0x followed
Groovy LanguagebyDocumentation
hex digits.
xInt = 0x77
xInt == 119
xShort = 0xaa
xShort == 170
xByte = 0x3a
xByte == 58
xLong = 0xffff
xLong == 65535l
xBigInteger = 0xaaaa
xBigInteger == 43690g
xDouble = ('0x1.0p0')
xDouble == 1.0d
xNegativeInt = -0x77
xNegativeInt == -119
Decimal literals
The decimal literal types are the same as in Java:
float
double
java.lang.BigDecimal
You can create decimal numbers of those types with the following declarations:
// primitive types
f = 1.234
d = 2.345
// infinite precision
bd = 3.456
Decimals can use exponents, with the e or E exponent letter, followed by an optional sign, and a integral number representing
the exponent:
1e3 == 1_000.0
2E4 == 20_000.0
3e+1 == 30.0
4E-2 == 0.04
5e-1 == 0.5
Conveniently for exact decimal number calculations, Groovy choses java.lang.BigDecimal as its decimal number type. In
addition, both float and double are supported, but require an explicit type declaration, type coercion or su x. Even if
BigDecimal is the default for decimal numbers, such literals are accepted in methods or closures taking float or double as
parameter types.
Decimal numbers can’t be represented using a binary, octal or hexadecimal representation.
Underscore in literals
When writing long literal numbers, it’s harder on the eye to gure 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:
http://docs.groovy-lang.org/latest/html/documentation/ 33/502
1/6/2019 Groovy Language Documentation
creditCardNumber = 1234_5678_9012_3456L
socialSecurityNumbers = 999_99_9999L
monetaryAmount = 12_345_132.12
hexBytes = 0xFF_EC_DE_5E
hexWords = 0xFFEC_DE5E
maxLong = 0x7fff_ffff_ffff_ffffL
alsoMaxLong = 9_223_372_036_854_775_807L
bytes = 0b11010010_01101001_10010100_10010010
Number type su xes
We can force a number (including binary, octals and hexadecimals) to have a speci c type by giving a su x (see table below),
either uppercase or lowercase.
Type Su x
BigInteger G or g
Long L or l
Integer I or i
BigDecimal G or g
Double D or d
Float F or f
Examples:
42I == ('42')
42i == ('42') // lowercase i more readable
123L == ("123") // uppercase L more readable
2147483648 == ('2147483648') // Long type used, value too large for an Integer
456G == ('456')
456g == ('456')
123.45 == ('123.45') // default BigDecimal type used
1.200065D == ('1.200065')
1.234F == ('1.234')
1.23E23D == ('1.23E23')
0b1111L. == // binary
0xFFi. == // hexadecimal
034G. == // octal
Math operations
Although operators are covered later on, 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:
byte char short int long BigInteger oat double BigDecimal
http://docs.groovy-lang.org/latest/html/documentation/ 34/502
1/6/2019 Groovy Language Documentation
byte char short int long BigInteger oat double BigDecimal
byte int int int int long BigInteger double double BigDecimal
char int int int long BigInteger double double BigDecimal
short int int long BigInteger double double BigDecimal
int int long BigInteger double double BigDecimal
long long BigInteger double double BigDecimal
BigInteger BigInteger double double BigDecimal
oat double double double
double double double
BigDecimal BigDecimal
Thanks to Groovy’s operator overloading, the usual arithmetic operators work as well with BigInteger and
BigDecimal , unlike in Java where you have to use explicit methods for operating on those numbers.
The case of the division operator
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
(http://docs.oracle.com/javase/7/docs/api/java/math/BigDecimal.html#precision()) of the maximum of the two operands' precision
plus an extra precision of 10, and a scale (http://docs.oracle.com/javase/7/docs/api/java/math/BigDecimal.html#scale()) of the
maximum of 10 and the maximum of the operands' scale.
For integer division like in Java, you should use the intdiv() method, as Groovy doesn’t provide a dedicated
integer division operator symbol.
The case of the power operator
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 ts 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 ts in it, otherwise a BigInteger
if the base is a Long , then return a Long if the result value ts in it, otherwise a BigInteger
We can illustrate those rules with a few examples:
http://docs.groovy-lang.org/latest/html/documentation/ 35/502
1/6/2019 Groovy Language Documentation
// base and exponent are ints and the result can be represented by an Integer
2 ** 3 // 8
10 ** 9 // 1_000_000_000
// the base is a long, so fit the result in a Long
// (although it could have fit in an Integer)
5L ** 2 // 25
// the result can't be represented as an Integer or Long, so return a BigInteger
100 ** 10 // 10e20
1234 ** 123 // 170515806212727042875...
// the base is a BigDecimal and the exponent a negative int
// but the result can be represented as an Integer
0.5 ** -2 // 4
// the base is an int, and the exponent a negative float
// but again, the result can be represented as an Integer
1 ** -0.3f // 1
// the base is an int, and the exponent a negative int
// but the result will be calculated as a Double
// (both base and exponent are actually converted to doubles)
10 ** -1 // 0.1
// the base is a BigDecimal, and the exponent is an int, so return a BigDecimal
1.2 ** 10 // 6.1917364224
// the base is a float or double, and the exponent is an int
// but the result can only be represented as a Double value
3.4f ** 5 // 454.35430372146965
5.6d ** 2 // 31.359999999999996
// the exponent is a decimal value
// and the result can only be represented as a Double value
7.8 ** 1.9 // 49.542708423868476
2 ** 0.1f // 1.0717734636432956
1.1.6. Booleans
Boolean is a special data type that is used to represent truth values: true and false . Use this data type for simple ags that
track true/false conditions.
Boolean values can be stored in variables, assigned into elds, just like any other data type:
myBooleanVariable =
untypedBooleanVar =
booleanField =
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.
1.1.7. Lists
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 de ne its own collection classes. The concrete list implementation used when de ning list
literals are java.util.ArrayList by default, unless you decide to specify otherwise, as we shall see later on.
numbers = [1, 2, 3] 1
numbers 2
numbers.size() == 3 3
1 We de ne a list numbers delimited by commas and surrounded by square brackets, and we assign that list into a variable
http://docs.groovy-lang.org/latest/html/documentation/ 36/502
1/6/2019 2 Groovy Language Documentation
The list is an instance of Java’s java.util.List interface
3 The size of the list can be queried with the size() method, and shows our list contains 3 elements
In the above example, we used a homogeneous list, but you can also create lists containing values of heterogeneous types:
heterogeneous = [1, "a", ] 1
1 Our list here contains a number, a string and a boolean value
We mentioned that by default, list literals are actually instances of java.util.ArrayList , but it is possible to use a di erent
backing type for our lists, thanks to using type coercion with the as operator, or with explicit type declaration for your variables:
arrayList = [1, 2, 3]
arrayList java.util.
linkedList = [2, 3, 4] 1
linkedList java.util.
otherLinked = [3, 4, 5] 2
otherLinked java.util.
1 We use coercion with the as operator to explicitly request a java.util.LinkedList implementation
2 We can say that the variable holding the list literal is of type java.util.LinkedList
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:
letters = ['a', 'b', 'c', 'd']
letters[0] == 'a' 1
letters[1] == 'b'
letters[-1] == 'd' 2
letters[-2] == 'c'
letters[2] = 'C' 3
letters[2] == 'C'
letters << 'e' 4
letters[ 4] == 'e'
letters[-1] == 'e'
letters[1, 3] == ['b', 'd'] 5
letters[2..4] == ['C', 'd', 'e'] 6
1 Access the rst element of the list (zero-based counting)
2 Access the last element of the list with a negative index: -1 is the rst element from the end of the list
3 Use an assignment to set a new value for the third element of the list
4 Use the << leftShift operator to append an element at the end of the list
5 Access two elements at once, returning a new list containing those two elements
6 Use a range to access a range of values from the list, from a start to an end element position
As lists can be heterogeneous in nature, lists can also contain other lists to create multi-dimensional lists:
multi = [[0, 1], [2, 3]] 1
multi[1][0] == 2 2
1 De ne a list of list of numbers
http://docs.groovy-lang.org/latest/html/documentation/ 37/502
1/6/2019 2 Access the second element of the top-most list, andGroovy Language
the rst element Documentation
of the inner list
1.1.8. Arrays
Groovy reuses the list notation for arrays, but to make such literals arrays, you need to explicitely de ne the type of the array
through coercion or type declaration.
[] arrStr = ['Ananas', 'Banana', 'Kiwi'] 1
arrStr [] 2
!(arrStr )
numArr = [1, 2, 3] [] 3
numArr [] 4
numArr.size() == 3
1 De ne an array of strings using explicit variable type declaration
2 Assert that we created an array of strings
3 Create an array of ints with the as operator
4 Assert that we created an array of primitive ints
You can also create multi-dimensional arrays:
matrix3 = [3][3] 1
matrix3.size() == 3
[][] matrix2 2
matrix2 = [[1, 2], [3, 4]]
matrix2 [][]
1 You can de ne the bounds of a new array
2 Or declare an array without specifying its bounds
Access to elements of an array follows the same notation as for lists:
[] names = ['Cédric', 'Guillaume', 'Jochen', 'Paul']
names[0] == 'Cédric' 1
names[2] = 'Blackdrag' 2
names[2] == 'Blackdrag'
1 Retrieve the rst element of the array
2 Set the value of the third element of the array to a new value
Java’s array initializer notation is not supported by Groovy, as the curly braces can be misinterpreted with the
notation of Groovy closures.
1.1.9. Maps
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.
http://docs.groovy-lang.org/latest/html/documentation/ 38/502
1/6/2019 Groovy Language Documentation
colors = [red: '#FF0000', green: '#00FF00', blue: '#0000FF'] 1
colors['red'] == '#FF0000' 2
colors.green == '#00FF00' 3
colors['pink'] = '#FF00FF' 4
colors.yellow = '#FFFF00' 5
colors.pink == '#FF00FF'
colors['yellow'] == '#FFFF00'
colors java.util.
1 We de ne a map of string color names, associated with their hexadecimal-coded html colors
2 We use the subscript notation to check the content associated with the red key
3 We can also use the property notation to assert the color green’s hexadecimal representation
4 Similarly, we can use the subscript notation to add a new key/value pair
5 Or the property notation, to add the yellow color
When using names for the keys, we actually de ne string keys in the map.
Groovy creates maps that are actually instances of java.util.LinkedHashMap .
If you try to access a key which is not present in the map:
colors.unknown ==
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:
numbers = [1: 'one', 2: 'two']
numbers[1] == 'one'
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:
key = 'name'
person = [key: 'Guillaume'] 1
!person.containsKey('name') 2
person.containsKey('key') 3
The key associated with the 'Guillaume' name will actually be the "key" string, not the value associated with the key
1
variable
2 The map doesn’t contain the 'name' key
3 Instead, the map contains a 'key' key
You can also pass quoted strings as well as keys: ["name": "Guillaume"]. This is mandatory if your key string isn’t a
valid identi er, for example if you wanted to create a string key containing a hash like in: ["street-name": "Main
street"].
When you need to pass variable values as keys in your map de nitions, you must surround the variable or expression with
parentheses:
http://docs.groovy-lang.org/latest/html/documentation/ 39/502
1/6/2019 Groovy Language Documentation
person = [(key): 'Guillaume'] 1
person.containsKey('name') 2
!person.containsKey('key') 3
This time, we surround the key variable with parentheses, to instruct the parser we are passing a variable rather than
1
de ning a string key
2 The map does contain the name key
3 But the map doesn’t contain the key key as before
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 nd 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.
Normal arithmetic operators
The following binary arithmetic operators are available in Groovy:
Operator Purpose Remarks
+ addition
- subtraction
* multiplication
/ division Use intdiv() for integer division, and
see the section about integer division
for more information on the return type
of the division.
% remainder
** power See the section about the power
operation for more information on the
return type of the operation.
Here are a few examples of usage of those operators:
1 + 2 == 3
4 - 3 == 1
3 * 5 == 15
3 / 2 == 1.5
10 % 3 == 1
2 ** 3 == 8
Unary operators
The + and - operators are also available as unary operators:
+3 == 3
-4 == 0 - 4
-(-1) == 1 1
1 Note the usage of parentheses to surround an expression to apply the unary minus to that surrounded expression.
In terms of unary arithmetics operators, the ++ (increment) and -- (decrement) operators are available, both in pre x and
post x notation:
http://docs.groovy-lang.org/latest/html/documentation/ 40/502
1/6/2019 Groovy Language Documentation
a = 2
b = a++ * 3 1
a == 3 && b == 6
c = 3
d = c-- * 2 2
c == 2 && d == 6
e = 1
f = ++e + 3 3
e == 2 && f == 5
g = 4
h = --g + 1 4
g == 3 && h == 4
1 The post x increment will increment a after the expression has been evaluated and assigned into b
2 The post x decrement will decrement c after the expression has been evaluated and assigned into d
3 The pre x increment will increment e before the expression is evaluated and assigned into f
4 The pre x decrement will decrement g before the expression is evaluated and assigned into h
Assignment arithmetic operators
The binary arithmetic operators we have seen above are also available in an assignment form:
+=
-=
*=
/=
%=
**=
Let’s see them in action:
http://docs.groovy-lang.org/latest/html/documentation/ 41/502
1/6/2019 Groovy Language Documentation
a = 4
a += 3
a == 7
b = 5
b -= 3
b == 2
c = 5
c *= 3
c == 15
d = 10
d /= 2
d == 5
e = 10
e %= 3
e == 1
f = 3
f **= 2
f == 9
1.2.2. Relational operators
Relational operators allow comparisons between objects, to know if two objects are the same or di erent, or if one is greater
than, less than, or equal to the other.
The following operators are available:
Operator Purpose
== equal
!= di erent
< less than
<= less than or equal
> greater than
>= greater than or equal
Here are some examples of simple number comparisons using these operators:
1 + 2 == 3
3 != 4
-2 < 3
2 <= 2
3 <= 4
5 > 1
5 >= -2
1.2.3. Logical operators
Groovy o ers three logical operators for boolean expressions:
http://docs.groovy-lang.org/latest/html/documentation/ 42/502
1/6/2019 && : logical "and" Groovy Language Documentation
|| : logical "or"
! : logical "not"
Let’s illustrate them with the following examples:
! 1
&& 2
|| 3
1 "not" false is true
2 true "and" true is true
3 true "or" false is true
Precedence
The logical "not" has a higher priority than the logical "and".
(! && ) == 1
Here, the assertion is true (as the expression in parentheses is false), because "not" has a higher precedence than "and", so
1 it only applies to the rst "false" term; otherwise, it would have applied to the result of the "and", turned it into true, and the
assertion would have failed
The logical "and" has a higher priority than the logical "or".
|| && 1
Here, the assertion is true, because "and" has a higher precedence than "or", therefore the "or" is executed last and returns
1 true, having one true argument; otherwise, the "and" would have executed last and returned false, having one false
argument, and the assertion would have failed
Short-circuiting
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.
checkIfCalled() { 1
called =
}
called =
|| checkIfCalled()
!called 2
called =
|| checkIfCalled()
called 3
called =
&& checkIfCalled()
!called 4
called =
&& checkIfCalled()
called 5
1 We create a function that sets the called ag to true whenever it’s called
http://docs.groovy-lang.org/latest/html/documentation/ 43/502
1/6/2019 Groovy
In the rst case, after resetting the called ag, we con Language
rm that Documentation
if the left operand to || is true, the function is not called, as
2
|| short-circuits the evaluation of the right operand
3 In the second case, the left operand is false and so the function is called, as indicated by the fact our ag is now true
4 Likewise for && , we con rm that the function is not called with a false left operand
5 But the function is called with a true left operand
1.2.4. Bitwise operators
Groovy o ers 4 bitwise operators:
& : bitwise "and"
| : bitwise "or"
^ : bitwise "xor" (exclusive "or")
~ : bitwise negation
Bitwise operators can be applied on a byte or an int and return an int :
a = 0b00101010
a == 42
b = 0b00001000
b == 8
(a & a) == a 1
(a & b) == b 2
(a | a) == a 3
(a | b) == a 4
mask = 0b11111111 5
((a ^ a) & mask) == 0b00000000 6
((a ^ b) & mask) == 0b00100010 7
((~a) & mask) == 0b11010101 8
1 bitwise and
2 bitwise and returns common bits
3 bitwise or
4 bitwise or returns all '1' bits
5 setting a mask to check only the last 8 bits
6 bitwise exclusive or on self returns 0
7 bitwise exclusive or
8 bitwise negation
It’s worth noting that the internal representation of primitive types follow the Java Language Speci cation
(http://docs.oracle.com/javase/specs/jls/se8/html/jls-4.html). 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 have the particularity of being overloadable, meaning that you can de ne the behavior of those
operators for any kind of object.
1.2.5. Conditional operators
Not operator
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:
(! ) == 1
(!'foo') == 2
(!'') == 3
1 the negation of true is false
http://docs.groovy-lang.org/latest/html/documentation/ 44/502
1/6/2019 2 Groovy Language
'foo' is a non empty string, evaluating to true , so negation Documentation
returns false
3 '' is an empty string, evaluating to false , so negation returns true
Ternary operator
The ternary operator is a shortcut expression that is equivalent to an if/else branch assigning some value to a variable.
Instead of:
( != && .length()>0) {
result = 'Found'
} {
result = 'Not found'
}
You can write:
result = ( != && .length()>0) ? 'Found' : 'Not found'
The ternary operator is also compatible with the Groovy truth, so you can make it even simpler:
result = ? 'Found' : 'Not found'
Elvis operator
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:
displayName = user.name ? user.name : 'Anonymous' 1
displayName = user.name ?: 'Anonymous' 2
1 with the ternary operator, you have to repeat the value you want to assign
2 with the Elvis operator, the value, which is tested, is used if it is not false -ish
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.
1.2.6. Object operators
Safe navigation operator
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:
person = .find { it.id == 123 } 1
name = person?.name 2
name == 3
1 find will return a null instance
2 use of the null-safe operator prevents from a NullPointerException
3 result is null
Direct eld access operator
Normally in Groovy, when you write code like this:
http://docs.groovy-lang.org/latest/html/documentation/ 45/502
1/6/2019 Groovy Language Documentation
{
name 1
( name) { .name = name}
getName() { "Name: $name" } 2
}
user = ('Bob')
user.name == 'Name: Bob' 3
1 public eld name
2 a getter for name that returns a custom string
3 calls the getter
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 eld instead of calling the getter, you can use the direct eld access operator:
user.@name == 'Bob' 1
1 use of .@ forces usage of the eld instead of the getter
Method pointer operator
The method pointer operator ( .& ) call be used to store a reference to a method in a variable, in order to call it later:
str = 'example of method reference' 1
fun = str.&toUpperCase 2
upper = fun() 3
upper == str.toUpperCase() 4
1 the str variable contains a String
2 we store a reference to the toUpperCase method on the str instance inside a variable named fun
3 fun can be called like a regular method
4 we can check that the result is the same as if we had called it directly on str
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:
transform( elements, action) { 1
result = []
elements.each {
result << action(it)
}
result
}
describe( p) { 2
"$p.name is $p.age"
}
action = .&describe 3
list = [
(name: 'Bob', age: 42),
(name: 'Julia', age: 35)] 4
transform(list, action) == ['Bob is 42', 'Julia is 35'] 5
1 the transform method takes each element of the list and calls the action closure on them, returning a new list
2 we de ne a function that takes a Person and returns a String
3 we create a method pointer on that function
4 we create the list of elements we want to collect the descriptors
5 the method pointer can be used where a Closure was expected
http://docs.groovy-lang.org/latest/html/documentation/ 46/502
1/6/2019 Method pointers are bound by the receiver and a methodGroovy
name. Language
Arguments are resolved at runtime, meaning that if you have
Documentation
multiple methods with the same name, the syntax is not di erent, only resolution of the appropriate method to be called will be
done at runtime:
doSomething( str) { str.toUpperCase() } 1
doSomething( x) { 2*x } 2
reference = .&doSomething 3
reference('foo') == 'FOO' 4
reference(123) == 246 5
1 de ne an overloaded doSomething method accepting a String as an argument
2 de ne an overloaded doSomething method accepting an Integer as an argument
3 create a single method pointer on doSomething , without specifying argument types
4 using the method pointer with a String calls the String version of doSomething
5 using the method pointer with an Integer calls the Integer version of doSomething
1.2.7. Regular expression operators
Pattern operator
The pattern operator ( ~ ) provides a simple way to create a java.util.regex.Pattern instance:
p = ~/foo/
p
while in general, you nd the pattern operator with an expression in a slashy-string, it can be used with any kind of String in
Groovy:
p = ~'foo' 1
p = ~"foo" 2
p = ~$/dollar/slashy $ /$ 3
p = ~"${pattern}" 4
1 using single quote strings
2 using double quotes strings
3 the dollar-slashy string lets you use slashes and the dollar sign without having to escape them
4 you can also use a GString!
Find operator
Alternatively to building a pattern, you can directly use the nd operator =~ to build a java.util.regex.Matcher instance:
text = "some text to match"
m = text =~ /match/ 1
m 2
(!m) { 3
("Oops, text not found!")
}
1 =~ creates a matcher against the text variable, using the pattern on the right hand side
2 the return type of =~ is a Matcher
3 equivalent to calling if (!m.find())
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 , while , etc.).
Match operator
The match operator ( ==~ ) is a slight variation of the nd operator, that does not return a Matcher but a boolean and requires a
strict match of the input string:
http://docs.groovy-lang.org/latest/html/documentation/ 47/502
1/6/2019 Groovy Language Documentation
m = text ==~ /match/ 1
m 2
(m) { 3
("Should not reach that point!")
}
1 ==~ matches the subject with the regular expression, but match must be strict
2 the return type of ==~ is therefore a boolean
3 equivalent to calling if (text ==~ /match/)
1.2.8. Other operators
Spread operator
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:
{
make
model
}
cars = [
(make: 'Peugeot', model: '508'),
(make: 'Renault', model: 'Clio')] 1
makes = cars*.make 2
makes == ['Peugeot', 'Renault'] 3
1 build a list of Car items. The list is an aggregate of objects.
2 call the spread operator on the list, accessing the make property of each item
3 returns a list of strings corresponding to the collection of make items
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 :
cars = [
(make: 'Peugeot', model: '508'),
, 1
(make: 'Renault', model: 'Clio')]
cars*.make == ['Peugeot', , 'Renault'] 2
*.make == 3
1 build a list for which of of the elements is null
2 using the spread operator will not throw a NullPointerException
3 the receiver might also be null, in which case the return value is null
The spread operator can be used on any class which implements the Iterable interface:
http://docs.groovy-lang.org/latest/html/documentation/ 48/502
1/6/2019 Groovy Language Documentation
{
id
name
}
< > {
components = [
(id: 1, name: 'Foo'),
(id: 2, name: 'Bar')]
@Override
< > iterator() {
components.iterator()
}
}
composite = ()
composite*.id == [1,2]
composite*.name == ['Foo','Bar']
Use multiple invocations of the spread-dot operator (here cars*.models*.name ) when working with aggregates of data
structures which themselves contain aggregates:
{
name
< > models
}
@Canonical
{
name
}
cars = [
(name: 'Peugeot',
models: [ ('408'), ('508')]),
(name: 'Renault',
models: [ ('Clio'), ('Captur')])
]
makes = cars*.name
makes == ['Peugeot', 'Renault']
models = cars*.models*.name
models == [['408', '508'], ['Clio', 'Captur']]
models.sum() == ['408', '508', 'Clio', 'Captur'] // flatten one level
models.flatten() == ['408', '508', 'Clio', 'Captur'] // flatten all levels (one in this
case)
Consider using the collectNested DGM method instead of the spread-dot operator for collections of collections:
{
make
model
}
cars = [
[
(make: 'Peugeot', model: '408'),
(make: 'Peugeot', model: '508')
], [
(make: 'Renault', model: 'Clio'),
(make: 'Renault', model: 'Captur')
]
]
models = cars.collectNested{ it.model }
models == [['408', '508'], ['Clio', 'Captur']]
http://docs.groovy-lang.org/latest/html/documentation/ 49/502
1/6/2019 Spreading method arguments Groovy Language Documentation
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:
( x, y, z) {
x*y+z
}
then if you have the following list:
args = [4,5,6]
you can call the method without having to de ne intermediate variables:
(*args) == 26
It is even possible to mix normal arguments with spread ones:
args = [4]
(*args,5,6) == 26
Spread list elements
When used inside a list literal, the spread operator acts as if the spread element contents were inlined into the list:
items = [4,5] 1
list = [1,2,3,*items,6] 2
list == [1,2,3,4,5,6] 3
1 items is a list
2 we want to insert the contents of the items list directly into list without having to call addAll
3 the contents of items has been inlined into list
Spread map elements
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:
m1 = [c:3, d:4] 1
map = [a:1, b:2, *:m1] 2
map == [a:1, b:2, c:3, d:4] 3
1 m1 is the map that we want to inline
2 we use the *:m1 notation to spread the contents of m1 into map
3 map contains all the elements of m1
The position of the spread map operator is relevant, like illustrated in the following example:
m1 = [c:3, d:4] 1
map = [a:1, b:2, *:m1, d: 8] 2
map == [a:1, b:2, c:3, d:8] 3
1 m1 is the map that we want to inline
2 we use the *:m1 notation to spread the contents of m1 into map , but rede ne the key d after spreading
3 map contains all the expected keys, but d was rede ned
Range operator
Groovy supports the concept of ranges and provides a notation ( .. ) to create ranges of objects:
http://docs.groovy-lang.org/latest/html/documentation/ 50/502
1/6/2019 Groovy Language Documentation
range = 0..5 1
(0..5).collect() == [0, 1, 2, 3, 4, 5] 2
(0..<5).collect() == [0, 1, 2, 3, 4] 3
(0..5) 4
(0..5).size() == 6 5
1 a simple range of integers, stored into a local variable
2 an IntRange , with inclusive bounds
3 an IntRange , with exclusive upper bound
4 a groovy.lang.Range implements the List interface
5 meaning that you can call the size method on it
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:
('a'..'d').collect() == ['a','b','c','d']
Spaceship operator
The spaceship operator ( <=> ) delegates to the compareTo method:
(1 <=> 1) == 0
(1 <=> 2) == -1
(2 <=> 1) == 1
('a' <=> 'z') == -1
Subscript operator
The subscript operator is a short hand notation for getAt or putAt , depending on whether you nd it on the left hand side or
the right hand side of an assignment:
list = [0,1,2,3,4]
list[2] == 2 1
list[2] = 4 2
list[0..2] == [0,1,4] 3
list[0..2] = [6,6,6] 4
list == [6,6,6,3,4] 5
1 [2] can be used instead of getAt(2)
2 if on left hand side of an assignment, will call putAt
3 getAt also supports ranges
4 so does putAt
5 the list is mutated
The subscript operator, in combination with a custom implementation of getAt / putAt is a convenient way for destructuring
objects:
http://docs.groovy-lang.org/latest/html/documentation/ 51/502
1/6/2019 Groovy Language Documentation
{
id
name
getAt( i) { 1
(i) {
0: id
1: name
}
("No such element $i")
}
putAt( i, value) { 2
(i) {
0: id = value;
1: name = value;
}
("No such element $i")
}
}
user = (id: 1, name: 'Alex') 3
user[0] == 1 4
user[1] == 'Alex' 5
user[1] = 'Bob' 6
user.name == 'Bob' 7
1 the User class de nes a custom getAt implementation
2 the User class de nes a custom putAt implementation
3 create a sample user
4 using the subscript operator with index 0 allows retrieving the user id
5 using the subscript operator with index 1 allows retrieving the user name
6 we can use the subscript operator to write to a property thanks to the delegation to putAt
7 and check that it’s really the property name which was changed
Membership operator
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:
list = ['Grace','Rob','Emmy']
('Emmy' list) 1
1 equivalent to calling list.contains('Emmy') or list.isCase('Emmy')
Identity operator
In Groovy, using == to test equality is di erent 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:
list1 = ['Groovy 1.8','Groovy 2.0','Groovy 2.3'] 1
list2 = ['Groovy 1.8','Groovy 2.0','Groovy 2.3'] 2
list1 == list2 3
!list1. (list2) 4
1 Create a list of strings
2 Create another list of strings containing the same elements
3 using == , we test object equality
4 but using is , we can check that references are distinct
Coercion operator
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:
http://docs.groovy-lang.org/latest/html/documentation/ 52/502
1/6/2019 Groovy Language Documentation
x = 123
s = ( ) x 1
1 Integer is not assignable to a String , so it will produce a ClassCastException at runtime
This can be xed by using coercion instead:
x = 123
s = x 1
1 Integer is not assignable to a String , but use of as will coerce it to a String
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 di er 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:
{
name
}
{
id
name
asType( target) { 1
(target == ) {
(name: name)
}
("User cannot be coerced into $target")
}
}
u = (name: 'Xavier') 2
p = u 3
p 4
!(p ) 5
1 the User class de nes a custom conversion rule from User to Identifiable
2 we create an instance of User
3 we coerce the User instance into an Identifiable
4 the target is an instance of Identifiable
5 the target is not an instance of User anymore
Diamond operator
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:
< > strings = <>()
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.
Call operator
The call operator () is used to call a method named call implicitly. For any object which de nes a call method, you can omit
the .call part and use the call operator instead:
http://docs.groovy-lang.org/latest/html/documentation/ 53/502
1/6/2019 Groovy Language Documentation
{
call( x) { 1
2*x
}
}
mc = ()
mc.call(2) == 4 2
mc(2) == 4 3
1 MyCallable de nes a method named call . Note that it doesn’t need to implement java.util.concurrent.Callable
2 we can call the method using the classic method call syntax
3 or we can omit .call thanks to the call operator
1.2.9. Operator precedence
The table below lists all groovy operators in order of precedence.
Level Operator(s) Name(s)
1 new () object creation, explicit parentheses
() {} [] method call, closure, literal list/map
. .& .@ member access, method closure,
eld/attribute access
?. * *. *: safe dereferencing, spread, spread-dot,
spread-map
~ ! (type) bitwise negate/pattern, not, typecast
[] ++ -- list/map/array index, post
inc/decrement
2 ** power
3 ++ -- + - pre inc/decrement, unary plus, unary
minus
4 * / % multiply, div, remainder
5 + - addition, subtraction
6 << >> >>> .. ..< left/right (unsigned) shift,
inclusive/exclusive range
7 < <= > >= in instanceof less/greater than/or equal, in,
as instanceof, type coercion
8 == != <=> equals, not equals, compare to
=~ ==~ regex nd, regex match
9 & binary/bitwise and
10 ^ binary/bitwise xor
11 | binary/bitwise or
12 && logical and
13 || logical or
14 ? : ternary conditional
http://docs.groovy-lang.org/latest/html/documentation/ 54/502
1/6/2019 Groovy Language Documentation
Level Operator(s) Name(s)
?: elvis operator
15 = **= *= /= %= += -= various assignments
<<= >>= >>>= &= ^= |=
1.2.10. Operator overloading
Groovy allows you to overload the various operators so that they can be used with your own classes. Consider this simple class:
{
size
( size) { .size = size }
plus( other) { 1
( .size + other.size)
}
}
1 Bucket implements a special method called plus()
Just by implementing the plus() method, the Bucket class can now be used with the + operator like so:
b1 = (4)
b2 = (11)
(b1 + b2).size == 15 1
1 The two Bucket objects can be added together with the + operator
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
(b1 + 11).size == 15
by implementing the plus() method with this signature:
plus( capacity) {
( .size + capacity)
}
Here is a complete list of the operators and their corresponding methods:
Operator Method Operator Method
+ a.plus(b) a[b] a.getAt(b)
- a.minus(b) a[b] = c a.putAt(b, c)
* a.multiply(b) a in b b.isCase(a)
/ a.div(b) << a.leftShift(b)
% a.mod(b) >> a.rightShift(b)
** a.power(b) >>> a.rightShiftUnsigned(b)
| a.or(b) ++ a.next()
& a.and(b) -- a.previous()
http://docs.groovy-lang.org/latest/html/documentation/ 55/502
1/6/2019 Groovy Language Documentation
Operator Method Operator Method
^ a.xor(b) +a a.positive()
as a.asType(b) -a a.negative()
a() a.call() ~a a.bitwiseNegate()
1.3. Program structure
This chapter covers the program structure of the Groovy programming language.
1.3.1. Package names
Package names play exactly the same role as in Java. They allows us to separate the code base without any con icts. Groovy
classes must specify their package before the class de nition, else the default package is assumed.
De ning a package is very similar to Java:
// defining a package named com.yoursite
com.yoursite
To refer to some class Foo in the com.yoursite.com package you will need to use the fully quali ed 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 quali ed 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:
// importing the class MarkupBuilder
groovy.xml.
// using the imported class to create an object
xml = ()
xml !=
Default imports
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:
java.lang.*
java.util.*
java.io.*
java.net.*
groovy.lang.*
groovy.util.*
java.math.
java.math.
This is done because the classes from these packages are most commonly used. By importing these boilerplate code is reduced.
Simple import
http://docs.groovy-lang.org/latest/html/documentation/ 56/502
1/6/2019 A simple import is an import statement where you fully deGroovy
ne theLanguage
class name along with the package. For example the import
Documentation
statement import groovy.xml.MarkupBuilder in the code below is a simple import which directly refers to a class inside a package.
// importing the class MarkupBuilder
groovy.xml.
// using the imported class to create an object
xml = ()
xml !=
Star import
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:
groovy.xml.
groovy.xml.
markupBuilder = ()
markupBuilder !=
() !=
That’s perfectly valid code. But with a * import, we can achieve the same e ect with just one line. The star imports all the classes
under package groovy.xml :
groovy.xml.*
markupBuilder = ()
markupBuilder !=
() !=
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.
Static import
Groovy’s static import capability allows you to reference imported classes as if they were static methods in your own class:
.FALSE
!FALSE //use directly, without Boolean prefix!
This is similar to Java’s static import capability but is a more dynamic than Java in that it allows you to de ne methods with the
same name as an imported method as long as you have di erent types:
java.lang. .format 1
format( i) { 2
i.toString()
}
main( [] args) {
format('String') == 'String' 3
().format( .valueOf(1)) == '1'
}
}
http://docs.groovy-lang.org/latest/html/documentation/ 57/502
1/6/2019 1 static import of method Groovy Language Documentation
2 declaration of method with same name as method statically imported above, but with a di erent parameter type
3 compile error in java, but is valid groovy code
If you have the same types, the imported class takes precedence.
Static import aliasing
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:
.getInstance now
now(). == .getInstance().
Now, that’s clean!
Static star import
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 t our need. With the help of a static star import, we can do:
java.lang. .*
sin(0) == 0.0
cos(0) == 1.0
As you can see, we were able to access the methods sin and cos directly, without the Math. pre x.
Import aliasing
With type aliasing, we can refer to a fully quali ed 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 le as java.util.Date without having to use
the fully quali ed name of either class:
java.util.
java.sql.
utilDate = (1000L)
sqlDate = (1000L)
utilDate java.util.
sqlDate java.sql.
1.3.3. Scripts versus classes
public static void main vs script
Groovy supports both scripts and classes. Take the following code for example:
Main.groovy
{ 1
main( ... args) { 2
println 'Groovy world!' 3
}
}
1 de ne a Main class, the name is arbitrary
http://docs.groovy-lang.org/latest/html/documentation/ 58/502
1/6/2019 2 Groovy
the public static void main(String[]) method Language
is usable as theDocumentation
main method of the class
3 the main body of the method
This is typical code that you would nd coming from Java, where code has to be embedded into a class to be executable. Groovy
makes it easier, the following code is equivalent:
Main.groovy
println 'Groovy world!'
A script can be considered as a class without needing to declare it, with some di erences.
Script class
A script (http://docs.groovy-lang.org/2.5.5/html/gapi/index.html?groovy/lang/Script.html) 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:
Main.groovy
org.codehaus.groovy.runtime.
{ 1
run() { 2
println 'Groovy world!' 3
}
main( [] args) { 4
.runScript( , args) 5
}
}
1 The Main class extends the groovy.lang.Script class
2 groovy.lang.Script requires a run method returning a value
3 the script body goes into the run method
4 the main method is automatically generated
5 and delegates the execution of the script on the run method
If the script is in a le, then the base name of the le is used to determine the name of the generated script class. In this example,
if the name of the le is Main.groovy , then the script class is going to be Main .
Methods
It is possible to de ne methods into a script, as illustrated here:
fib( n) {
n < 2 ? 1 : fib(n-1) + fib(n-2)
}
fib(10)==89
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:
println 'Hello' 1
power( n) { 2**n } 2
println "2^6==${power(6)}" 3
1 script begins
2 a method is de ned within the script body
3 and script continues
This code is internally converted into:
http://docs.groovy-lang.org/latest/html/documentation/ 59/502
1/6/2019 Groovy Language Documentation
org.codehaus.groovy.runtime.
{
power( n) { 2** n} 1
run() {
println 'Hello' 2
println "2^6==${power(6)}" 3
}
main( [] args) {
.runScript( , args)
}
}
1 the power method is copied as is into the generated script class
2 rst statement is copied into the run method
3 second statement is copied into the run method
Even if Groovy creates a class from your script, it is totally transparent for the user. In particular, scripts are
compiled to bytecode, and line numbers are preserved. This implies that if an exception is thrown in a script, the
stack trace will show line numbers corresponding to the original script, not the generated code that we have
shown.
Variables
Variables in a script do not require a type de nition. This means that this script:
x = 1
y = 2
x+y == 3
will behave the same as:
x = 1
y = 2
x+y == 3
However there is a semantic di erence between the two:
if the variable is declared as in the rst 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 script binding (http://docs.groovy-lang.org/2.5.5/html/gapi/index.html?
groovy/lang/Script.html#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.
If you want a variable to become a eld of the class without going into the Binding , you can use the @Field
annotation.
1.4. Object orientation
This chapter covers the object orientation of the Groovy programming language.
1.4.1. Types
Primitive types
Groovy supports the same primitive types as those de ned by the Java Language Speci cation
(http://docs.oracle.com/javase/specs/jls/se8/html/):
integral types: byte (8 bit), short (16 bit), int (32 bit) and long (64 bit)
oating-point types: float (32 bit) and double (64 bit)
http://docs.groovy-lang.org/latest/html/documentation/ 60/502
1/6/2019 boolean type (exactly true or false ) Groovy Language Documentation
char type (16 bit, usable as a numeric type, representing an UTF-16 code)
While Groovy declares and stores primitive elds and variables as primitives, because it uses Objects for everything, it autowraps
references to primitives. Just like Java, the wrappers it uses are
Table 2. primitive wrappers
Primitive type Wrapper class
boolean Boolean
char Character
short Short
int Integer
long Long
oat Float
double Double
Here’s an example using int
{
i
}
. .getDeclaredField('i').type == .
.i. != . && .i. == .
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 (core-operators.html#_operator-overloading) 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 di erences (core-di erences-java.html#_primitives_and_wrappers) from
Java’s method resolution.
Class
Groovy classes are very similar to Java classes, and are compatible with Java ones at JVM level. They may have methods, elds and
properties (think JavaBean properties but with less boilerplate). Classes and class members can have the same modi ers (public,
protected, private, static, etc) as in Java with some minor di erences at the source level which are explained shortly.
The key di erences between Groovy classes and their Java counterparts are:
Classes or methods with no visibility modi er are automatically public (a special annotation can be used to achieve package
private visibility).
Fields with no visibility modi er 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 elds and properties section.
Classes do not need to have the same base name as their source le de nitions but it is highly recommended in most
scenarios (see also the next point about scripts).
One source le may contain one or more classes (but if a le 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 le (so don’t include a class
de nition within a script having the same name as the script source le).
The following code presents an example class.
http://docs.groovy-lang.org/latest/html/documentation/ 61/502
1/6/2019 Groovy Language Documentation
{ 1
name 2
age
increaseAge( years) { 3
.age += years
}
}
1 class beginning, with the name Person
2 string eld and property named name
3 method de nition
Normal 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.
p = ()
Inner class
Inner classes are de ned within another classes. The enclosing class can use the inner class as usual. On the other side, a 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:
{
privateStr
callInnerMethod() {
().methodA() 1
{ 2
methodA() {
println "${privateStr}." 3
}
}
}
1 the inner class is instantiated and its method gets called
2 inner class de nition, inside its enclosing class
3 even being private, a eld of the enclosing class is accessed by the inner class
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.
In several cases, inner classes are implementation of interfaces whose methods are needed by the outer class. The code below
illustrates this with the usage of threads, which are very common.
http://docs.groovy-lang.org/latest/html/documentation/ 62/502
1/6/2019 Groovy Language Documentation
{
privateStr = 'some string'
startThread() {
( ()).start()
}
{
run() {
println "${privateStr}."
}
}
}
Note that the class Inner2 is de ned only to provide an implementation of the method run to class Outer2 . Anonymous inner
classes help to eliminate verbosity in this case.
Anonymous inner class
The last example of inner class can be simpli ed with an anonymous inner class. The same functionality can be achieved with the
following code.
{
privateStr = 'some string'
startThread() {
( () { 1
run() {
println "${privateStr}."
}
}).start() 2
}
}
comparing with the last example of previous section, the new Inner2() was replaced by new Runnable() along with all
1
its implementation
2 the method start is invoked normally
Thus, there was no need to de ne a new class to be used just once.
Abstract class
Abstract classes represent generic concepts, thus, they cannot be instantiated, being created to be subclassed. Their members
include elds/properties and abstract or concrete methods. Abstract methods do not have implementation, and must be
implemented by concrete subclasses.
{ 1
name
abstractMethod() 2
concreteMethod() {
println 'concrete'
}
}
1 abstract classes must be declared with abstract keyword
2 abstract methods must also be declared with abstract keyword
Abstract classes are commonly compared to interfaces. But there are at least two important di erences of choosing one or
another. First, while abstract classes may contain elds/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.
Interface
http://docs.groovy-lang.org/latest/html/documentation/ 63/502
1/6/2019 An interface de nes a contract that a class needs to conform to. An
Groovy interface
Language only de nes a list of methods that need to be
Documentation
implemented, but does not de ne the methods implementation.
{ 1
greet( name) 2
1 an interface needs to be declared using the interface keyword
2 an interface only de nes method signatures
Methods of an interface are always public. It is an error to use protected or private methods in interfaces:
{
greet( name) 1
1 Using protected is a compile-time error
A class implements an interface if it de nes the interface in its implements list or if any of its superclasses does:
{ 1
greet( name) { 2
println "Hello $name"
}
}
greeter = ()
greeter 3
1 The SystemGreeter declares the Greeter interface using the implements keyword
2 Then implements the required greet method
3 Any instance of SystemGreeter is also an instance of the Greeter interface
An interface can extend another interface:
{ 1
sayBye( name)
}
1 the ExtendedGreeter interface extends the Greeter interface using the extends keyword
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 de nes the
greet method as it is declared in the Greeter interface, but does not declare Greeter in its interfaces:
{
greet( name) { println "Hello" }
}
greeter = ()
!(greeter )
In other words, Groovy does not de ne structural typing. It is however possible to make an instance of an object implement an
interface at runtime, using the as coercion operator:
greeter = () 1
coerced = greeter 2
coerced 3
1 create an instance of DefaultGreeter that does not implement the interface
2 coerce the instance into a Greeter at runtime
http://docs.groovy-lang.org/latest/html/documentation/ 64/502
1/6/2019 3 Groovy Language Documentation
the coerced instance implements the Greeter interface
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.
Groovy interfaces do not support default implementation like Java 8 interfaces. If you are looking for something
similar (but not equal), traits are close to interfaces, but allow default implementation as well as other important
features described in this manual.
Constructors
Constructors are special methods used to initialize an object with a speci c 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.
Positional parameters
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 added to the class using the
groovy.transform.TupleConstructor (http://docs.groovy-lang.org/2.5.5/html/gapi/index.html?
groovy/transform/TupleConstructor.html) 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 rst
(and potentially only) argument - see the next section for details.
There are three forms of using a declared constructor. The rst 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.
{
name
age
(name, age) { 1
.name = name
.age = age
}
}
person1 = ('Marie', 1) 2
person2 = ['Marie', 2] 3
person3 = ['Marie', 3] 4
1 Constructor declaration
2 Constructor invocation, classic Java way
3 Constructor usage, using coercion with as keyword
4 Constructor usage, using coercion in assignment
Named parameters
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
http://docs.groovy-lang.org/latest/html/documentation/ 65/502
1/6/2019 rst (and perhaps only) argument is a Map argument is also supported
Groovy - such
Language a constructor may also be added using the
Documentation
groovy.transform.MapConstructor (http://docs.groovy-lang.org/2.5.5/html/gapi/index.html?
groovy/transform/MapConstructor.html) annotation.
{ 1
name
age
}
person4 = () 2
person5 = (name: 'Marie') 3
person6 = (age: 1) 4
person7 = (name: 'Marie', age: 2) 5
1 No constructor declared
2 No parameters given in the instantiation
3 name parameter given in the instantiation
4 age parameter given in the instantiation
5 name and age parameters given in the instantiation
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.
Notes:
While the example above supplied no constructor, you can also supply a no-arg constructor or a constructor where the rst
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 rst argument is a Map, Groovy combines all named parameters into a Map (regardless of ordering) and supplies the
map as the rst 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 rst argument is a Map but there are also additional
positional parameters. Use this style with caution.
Methods
Groovy methods are quite similar to other languages. Some peculiarities will be shown in the next subsections.
Method de nition
A method is de ned 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 modi ers can be used normally, and if no visibility
modi er 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.
someMethod() { 'method called' } 1
anotherMethod() { 'another method called' } 2
thirdMethod(param1) { "$param1 passed" } 3
fourthMethod( param1) { "$param1 passed" } 4
1 Method with no return type declared and no parameter
2 Method with explicit return type and no parameter
3 Method with a parameter with no type de ned
4 Static method with a String parameter
http://docs.groovy-lang.org/latest/html/documentation/ 66/502
1/6/2019 Named parameters Groovy Language Documentation
Like constructors, normal methods can also be called with named parameters. To support this notation, a convention is used
where the rst 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.
foo( args) { "${args.name}: ${args.age}" }
foo(name: 'Marie', age: 1)
Mixing named and positional parameters
Named parameters can be mixed with positional parameters. The same convention applies, in this case, in addition to the Map
argument as the rst 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 rst parameter automatically.
foo( args, number) { "${args.name}: ${args.age}, and the number is ${number}" }
foo(name: 'Marie', age: 1, 23) 1
foo(23, name: 'Marie', age: 1) 2
1 Method call with additional number argument of Integer type
2 Method call with changed order of arguments
If we don’t have the Map as the rst argument, then a Map must be supplied for that argument instead of named parameters.
Failure to do so will lead to groovy.lang.MissingMethodException :
foo( number, args) { "${args.name}: ${args.age}, and the number is ${number}" }
foo(name: 'Marie', age: 1, 23) 1
Method call throws
1 groovy.lang.MissingMethodException: No signature of method: foo() is applicable for argument types: (LinkedHashMap
because the named argument Map parameter is not de ned as the rst argument
Above exception can be avoided if we replace named arguments with an explicit Map argument:
foo( number, args) { "${args.name}: ${args.age}, and the number is ${number}" }
foo(23, [name: 'Marie', age: 1]) 1
1 Explicit Map argument in place of named arguments makes invocation valid
Although Groovy allows you to mix named and positional parameters, it can lead to unnecessary confusion. Mix
named and positional arguments with caution.
Default arguments
Default arguments make parameters optional. If the argument is not supplied, the method assumes a default value.
foo( par1, par2 = 1) { [name: par1, age: par2] }
foo('Marie').age == 1
Note that no mandatory parameter can be de ned after a default parameter is present, only other default parameters.
Varargs
Groovy supports methods with a variable number of arguments. They are de ned like this: def foo(p1, …, pn, T… args) .
Here foo supports n arguments by default, but also an unspeci ed number of further arguments exceeding n .
foo( ... args) { args.length }
foo() == 0
foo(1) == 1
foo(1, 2) == 2
http://docs.groovy-lang.org/latest/html/documentation/ 67/502
1/6/2019 This example de nes a method foo , that can take any number
Groovyof arguments,
Language including no arguments at all. args.length will
Documentation
return the number of arguments given. Groovy allows T[] as a 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.
foo( [] args) { args.length }
foo() == 0
foo(1) == 1
foo(1, 2) == 2
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.
foo( ... args) { args }
foo( ) ==
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.
foo( ... args) { args }
[] ints = [1, 2]
foo(ints) == [1, 2]
Another important point are varargs in combination with method overloading. In case of method overloading Groovy will select
the most speci c 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.
foo( ... args) { 1 }
foo( x) { 2 }
foo() == 1
foo(1) == 2
foo(1, 2) == 1
Method selection algorithm
(TBD)
Exception declaration
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 le isn’t found:
badRead() {
('doesNotExist.txt').text
}
shouldFail( ) {
badRead()
}
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:
http://docs.groovy-lang.org/latest/html/documentation/ 68/502
1/6/2019 Groovy Language Documentation
badRead() {
('doesNotExist.txt').text
}
shouldFail( ) {
badRead()
}
Fields and properties
Fields
A eld is a member of a class or a trait which has:
a mandatory access modi er ( public , protected , or private )
one or more optional modi ers ( static , final , synchronized )
an optional type
a mandatory name
{
id 1
description 2
DEBUG = 3
1 a private eld named id , of type int
2 a protected eld named description , of type String
3 a public static final eld named DEBUG of type boolean
A eld may be initialized directly at declaration:
{
id = . () 1
// ...
}
1 the private eld id is initialized with IDGenerator.next()
It is possible to omit the type declaration of a eld. This is however considered a bad practice and in general it is a good idea to
use strong typing for elds:
{
mapping 1
}
{
< , > mapping 2
1 the eld mapping doesn’t declare a type
2 the eld mapping has a strong type
The di erence between the two is important if you want to use optional type checking later. It is also important for
documentation. However in some cases like scripting or if you want to rely on duck typing it may be interesting to omit the type.
Properties
A property is an externally visible feature of a class. Rather than just using a public eld to represent such features (which
provides a more limited abstraction and would restrict refactoring possibilities), the typical convention in Java is to follow JavaBean
conventions, i.e. represent the property using a combination of a private backing eld and getters/setters. Groovy follows these
same conventions but provides a simpler approach to de ning the property. You can de ne a property with:
an absent access modi er (no public , protected or private )
http://docs.groovy-lang.org/latest/html/documentation/ 69/502
1/6/2019 one or more optional modi ers ( static , final , synchronized )
Groovy Language Documentation
an optional type
a mandatory name
Groovy will then generate the getters/setters appropriately. For example:
{
name 1
age 2
1 creates a backing private String name eld, a getName and a setName method
2 creates a backing private int age eld, a getAge and a setAge method
If a property is declared final , no setter is generated:
{
name 1
age 2
( name, age) {
.name = name 3
.age = age 4
}
}
1 de nes a read-only property of type String
2 de nes a read-only property of type int
3 assigns the name parameter to the name eld
4 assigns the age parameter to the age eld
Properties are accessed by name and will call the getter or setter transparently, unless the code is in the class which de nes the
property:
{
name
name( name) {
.name = "Wonder$name" 1
}
wonder() {
.name 2
}
}
p = ()
p.name = 'Marge' 3
p.name == 'Marge' 4
p.name('Marge') 5
p.wonder() == 'WonderMarge' 6
1 this.name will directly access the eld because the property is accessed from within the class that de nes it
2 similarily a read access is done directly on the name eld
3 write access to the property is done outside of the Person class so it will implicitly call setName
4 read access to the property is done outside of the Person class so it will implicitly call getName
5 this will call the name method on Person which performs a direct access to the eld
6 this will call the wonder method on Person which performs a direct read access to the eld
It is worth noting that this behavior of accessing the backing eld directly is done in order to prevent a stack over ow when using
the property access syntax within a class that de nes the property.
It is possible to list the properties of a class thanks to the meta properties eld of an instance:
http://docs.groovy-lang.org/latest/html/documentation/ 70/502
1/6/2019 Groovy Language Documentation
{
name
age
}
p = ()
p.properties.keySet().containsAll(['name','age'])
By convention, Groovy will recognize properties even if there is no backing eld provided there are getters or setters that follow
the Java Beans speci cation. For example:
{
// a pseudo property "name"
setName( name) {}
getName() {}
// a pseudo read-only property "age"
getAge() { 42 }
// a pseudo write-only property "groovy"
setGroovy( groovy) { }
}
p = ()
p.name = 'Foo' 1
p.age == 42 2
p.groovy = 3
1 writing p.name is allowed because there is a pseudo-property name
2 reading p.age is allowed because there is a pseudo-readonly property age
3 writing p.groovy is allowed because there is a pseudo-writeonly property groovy
This syntactic sugar is at the core of many DSLs written in Groovy.
Annotation
Annotation de nition
An annotation is a kind of special interface dedicated at annotating elements of the code. An annotation is a type which
superinterface is the Annotation (http://docs.oracle.com/javase/8/docs/api/index.html?java/lang/annotation/Annotation.html)
interface. Annotations are declared in a very similar way to interfaces, using the @interface keyword:
@interface {}
An annotation may de ne members in the form of methods without bodies and an optional default value. The possible member
types are limited to:
primitive types
Strings (http://docs.oracle.com/javase/8/docs/api/index.html?java/lang/String.html)
Classes (http://docs.oracle.com/javase/8/docs/api/index.html?java/lang/Class.html)
an enumeration (http://docs.oracle.com/javase/8/docs/api/index.html?java/lang/Enum.html)
another annotation type (http://docs.oracle.com/javase/8/docs/api/index.html?java/lang/annotation/Annotation.html)
or any array of the above
For example:
http://docs.groovy-lang.org/latest/html/documentation/ 71/502
1/6/2019 Groovy Language Documentation
@interface {
value() 1
}
@interface {
value() 'something' 2
}
@interface {
step() 3
}
@interface {
appliesTo() 4
}
@interface {}
@interface {
[] value() 5
}
{ mon, tue, wed, thu, fri, sat, sun }
@interface {
dayOfWeek() 6
1 an annotation de ning a value member of type String
2 an annotation de ning a value member of type String with a default value of something
3 an annotation de ning a step member of type the primitive type int
4 an annotation de ning a appliesTo member of type Class
5 an annotation de ning a value member which type is an array of another annotation type
6 an annotation de ning a dayOfWeek member which type is the enumeration type DayOfWeek
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.
Annotation placement
An annotation can be applied on various elements of the code:
@SomeAnnotation 1
someMethod() {
// ...
}
@SomeAnnotation 2
{}
@SomeAnnotation 3
1 @SomeAnnotation applies to the someMethod method
2 @SomeAnnotation applies to the SomeClass class
3 @SomeAnnotation applies to the var variable
In order to limit the scope where an annotation can be applied, it is necessary to declare it on the annotation de nition, using the
Target (http://docs.oracle.com/javase/8/docs/api/index.html?java/lang/annotation/Target.html) annotation. For example, here is
how you would declare that an annotation can be applied to a class or a method:
java.lang.annotation.
java.lang.annotation.
@Target([ .METHOD, .TYPE]) 1
@interface {} 2
1 the @Target annotation is meant to annotate an annotation with a scope.
2 @SomeAnnotation will therefore only be allowed on TYPE or METHOD
http://docs.groovy-lang.org/latest/html/documentation/ 72/502
1/6/2019 The list of possible targets is available in the ElementTypeGroovy
enumeration (http://docs.oracle.com/javase/8/docs/api/index.html?
Language Documentation
java/lang/annotation/ElementType.html).
Groovy does not support the TYPE_PARAMETER (http://docs.oracle.com/javase/8/docs/api/index.html?
java/lang/annotation/ElementType.html#TYPE_PARAMETER) and TYPE_USE
(http://docs.oracle.com/javase/8/docs/api/index.html?java/lang/annotation/ElementType.html#TYPE_PARAMETER)
element types which were introduced in Java 8.
Annotation member values
When an annotation is used, it is required to set at least all members that do not have a default value. For example:
@interface {
statusCode()
}
@Page(statusCode=404)
notFound() {
// ...
}
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:
@interface {
value()
statusCode() 200
}
@Page(value='/home') 1
home() {
// ...
}
@Page('/users') 2
userList() {
// ...
}
@Page(value='error',statusCode=404) 3
notFound() {
// ...
}
1 we can omit the statusCode because it has a default value, but value needs to be set
2 since value is the only mandatory member without a default, we can omit value=
3 if both value and statusCode need to be set, it is required to use value= for the default value member
Retention policy
The visibility of an annotation depends on its retention policy. The retention policy of an annotation is set using the Retention
(http://docs.oracle.com/javase/8/docs/api/index.html?java/lang/annotation/Retention.html) annotation:
java.lang.annotation.
java.lang.annotation.
@Retention( .SOURCE) 1
@interface {} 2
1 the @Retention annotation annotates the @SomeAnnotation annotation
2 so @SomeAnnotation will have a SOURCE retention
http://docs.groovy-lang.org/latest/html/documentation/ 73/502
1/6/2019 The list of possible retention targets and description is available
Groovyin the RetentionPolicy
Language Documentation
(http://docs.oracle.com/javase/8/docs/api/index.html?java/lang/annotation/RetentionPolicy.html) enumeration. The choice usually
depends on whether you want an annotation to be visible at compile time or runtime.
Closure annotation parameters
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:
{
result = []
alwaysExecuted() {
result << 1
}
@OnlyIf({ jdk>=6 })
supportedOnlyInJDK6() {
result << 'JDK 6'
}
@OnlyIf({ jdk>=7 && windows })
requiresJDK7AndWindows() {
result << 'JDK 7 Windows'
}
}
For the @OnlyIf annotation to accept a Closure as an argument, you only have to declare the value as a Class :
@Retention( .RUNTIME)
@interface {
value() 1
To complete the example, let’s write a sample runner that would use that information:
{
<T> T run( <T> taskClass) {
tasks = taskClass.newInstance() 1
= [jdk:6, windows: ] 2
tasks. .declaredMethods.each { m -> 3
( .isPublic(m.modifiers) && m.parameterTypes.length == 0) { 4
onlyIf = m.getAnnotation( ) 5
(onlyIf) {
cl = onlyIf.value().newInstance(tasks,tasks) 6
cl. = 7
(cl()) { 8
m.invoke(tasks) 9
}
} {
m.invoke(tasks) 10
}
}
}
tasks 11
}
}
1 create a new instance of the class passed as an argument (the task class)
2 emulate an environment which is JDK 6 and not Windows
3 iterate on all declared methods of the task class
4 if the method is public and takes no-argument
5 try to nd the @OnlyIf annotation
6 if it is found get the value and create a new Closure out of it
http://docs.groovy-lang.org/latest/html/documentation/ 74/502
1/6/2019 7 Groovy
set the delegate of the closure to our environment Language Documentation
variable
8 call the closure, which is the annotation closure. It will return a boolean
9 if it is true , call the method
10 if the method is not annotated with @OnlyIf , execute the method anyway
11 after that, return the task object
Then the runner can be used this way:
tasks = .run( )
tasks.result == [1, 'JDK 6']
Meta-annotations
Declaring 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:
@Service
@Transactional
{}
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:
@TransactionalService 1
{}
1 @TransactionalService is a meta-annotation
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.transform.
@Service 1
@Transactional 2
@AnnotationCollector 3
@interface {
}
1 annotate the meta-annotation with @Service
2 annotate the meta-annotation with @Transactional
3 annotate the meta-annotation with @AnnotationCollector
Behavior of meta-annotations
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
de nition 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 :
http://docs.groovy-lang.org/latest/html/documentation/ 75/502
1/6/2019 Groovy Language Documentation
annotations = .annotations*.annotationType()
( annotations)
( annotations)
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-annotation parameters
Meta-annotations can collect annotations which have parameters. To illustrate this, we will imagine two annotations, each of them
accepting one argument:
@Timeout(after=3600)
@Dangerous(type='explosive')
And suppose that you want create a meta-annotation named @Explosive :
@Timeout(after=3600)
@Dangerous(type='explosive')
@AnnotationCollector
@interface {}
By default, when the annotations are replaced, they will get the annotation parameter values as they were de ned in the alias.
More interesting, the meta-annotation supports overriding speci c values:
@Explosive(after=0) 1
{}
1 the after value provided as a parameter to @Explosive overrides the one de ned in the @Timeout annotation
If two annotations de ne the same parameter name, the default processor will copy the annotation value to all annotations that
accept this parameter:
@Retention( .RUNTIME)
@interface {
value() 1
}
@Retention( .RUNTIME)
@interface {
value() 2
@Foo
@Bar
@AnnotationCollector
@interface {} 3
@Foo('a')
@Bar('b')
{} 4
.getAnnotation( ).value() == 'a' 5
println .getAnnotation( ).value() == 'b' 6
@FooBar('a')
{} 7
.getAnnotation( ).value() == 'a' 8
println .getAnnotation( ).value() == 'a' 9
1 the @Foo annotation de nes the value member of type String
http://docs.groovy-lang.org/latest/html/documentation/ 76/502
1/6/2019 2 Groovy
the @Bar annotation also de nes the value member Language
of type Documentation
String
3 the @FooBar meta-annotation aggregates @Foo and @Bar
4 class Bob is annotated with @Foo and @Bar
5 the value of the @Foo annotation on Bob is a
6 while the value of the @Bar annotation on Bob is b
7 class Joe is annotated with @FooBar
8 then the value of the @Foo annotation on Joe is a
9 and the value of the @Bar annotation on Joe is also a
In the second case, the meta-annotation value was copied in both @Foo and @Bar annotations.
It is a compile time error if the collected annotations de ne the same members with incompatible types. For
example if on the previous example @Foo de ned a value of type String but @Bar de ned a value of type int .
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 rst there is an advanced processing option to cover.
Handling duplicate annotations
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 let’s you write your own custom meta-annotation processors (covered next) and let’s 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.
Mode Description
DUPLICATE Annotations from the annotation collection will always be
inserted. After all transforms have been run, it will be an error
if multiple annotations (excluding those with SOURCE
retention) exist.
PREFER_COLLECTOR Annotations from the collector will be added and any existing
annotations with the same name will be removed.
PREFER_COLLECTOR_MERGED Annotations from the collector will be added and any existing
annotations with the same name will be removed but any
new parameters found within existing annotations will be
merged into the added annotation.
PREFER_EXPLICIT Annotations from the collector will be ignored if any existing
annotations with the same name are found.
PREFER_EXPLICIT_MERGED Annotations from the collector will be ignored if any existing
annotations with the same name are found but any new
parameters on the collector annotation will be added to
existing annotations.
Custom annotation processors
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:
http://docs.groovy-lang.org/latest/html/documentation/ 77/502
1/6/2019 create a meta-annotation processor, extending AnnotationCollectorTransform (http://docs.groovy-
Groovy Language Documentation
lang.org/2.5.5/html/gapi/index.html?org/codehaus/groovy/transform/AnnotationCollectorTransform.html)
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:
@CompileStatic( .SKIP)
@AnnotationCollector
@interface {}
Instead, we will de ne it like this:
@AnnotationCollector(processor = "org.codehaus.groovy.transform.CompileDynamicProcessor")
@interface {
}
The rst 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:
CompileDynamicProcessor.groovy
@CompileStatic 1
{ 2
CS_NODE = .make( ) 3
TC_NODE = .make( ) 4
< > visit( collector, 5
aliasAnnotationUsage, 6
aliasAnnotated, 7
source) { 8
node = (CS_NODE) 9
enumRef = (
(TC_NODE), "SKIP") 10
node.addMember("value", enumRef) 11
.singletonList(node) 12
}
}
1 our custom processor is written in Groovy, and for better compilation performance, we use static compilation
the custom processor has to extend AnnotationCollectorTransform (http://docs.groovy-lang.org/2.5.5/html/gapi/index.html?
2
org/codehaus/groovy/transform/AnnotationCollectorTransform.html)
3 create a class node representing the @CompileStatic annotation type
4 create a class node representing the TypeCheckingMode enum type
5 collector is the @AnnotationCollector node found in the meta-annotation. Usually unused.
6 aliasAnnotationUsage is the meta-annotation being expanded, here it is @CompileDynamic
7 aliasAnnotated is the node being annotated with the meta-annotation
8 sourceUnit is the SourceUnit being compiled
9 we create a new annotation node for @CompileStatic
10 we create an expression equivalent to TypeCheckingMode.SKIP
11 we add that expression to the annotation node, which is now @CompileStatic(TypeCheckingMode.SKIP)
12 return the generated annotation
http://docs.groovy-lang.org/latest/html/documentation/ 78/502
1/6/2019 In the example, the visit method is the only method which hasLanguage
Groovy to be overridden. It is meant to return a list of annotation nodes
Documentation
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) .
Inheritance
(TBD)
Generics
(TBD)
1.4.2. 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 de ned using the trait keyword:
trait { 1
fly() { "I'm flying!" } 2
1 declaration of a trait
2 declaration of a method inside a trait
Then it can be used like a normal interface using the implements keyword:
{} 1
b = () 2
b.fly() == "I'm flying!" 3
1 Adds the trait FlyingAbility to the Bird class capabilities
2 instantiate a new Bird
3 the Bird class automatically gets the behavior of the FlyingAbility trait
Traits allow a wide range of capabilities, from simple composition to testing, which are described thoroughly in this section.
Methods
Public methods
Declaring a method in a trait can be done like any regular method in a class:
trait { 1
fly() { "I'm flying!" } 2
1 declaration of a trait
2 declaration of a method inside a trait
Abstract methods
In addition, traits may declare abstract methods too, which therefore need to be implemented in the class implementing the trait:
trait {
name() 1
greeting() { "Hello, ${name()}!" } 2
http://docs.groovy-lang.org/latest/html/documentation/ 79/502
1/6/2019 1 Groovy Language Documentation
implementing class will have to declare the name method
2 can be mixed with a concrete method
Then the trait can be used like this:
{ 1
name() { 'Bob' } 2
p = ()
p.greeting() == 'Hello, Bob!' 3
1 implement the trait Greetable
2 since name was abstract, it is required to implement it
3 then greeting can be called
Private methods
Traits may also de ne private methods. Those methods will not appear in the trait contract interface:
trait {
greetingMessage() { 1
'Hello from a private method!'
}
greet() {
m = greetingMessage() 2
println m
m
}
}
{} 3
g = ()
g.greet() == "Hello from a private method!" 4
{
g.greetingMessage() 5
} ( e) {
println "greetingMessage is private in trait"
}
1 de ne a private method greetingMessage in the trait
2 the public greet message calls greetingMessage by default
3 create a class implementing the trait
4 greet can be called
5 but not greetingMessage
Traits only support public and private methods. Neither protected nor package private scopes are
supported.
Final methods
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 nal modi er on a
method just indicates what the modi er 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 nal and non- nal variants, Groovy doesn’t prohibit this
scenario. Normal method selection applies and the modi er 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.
The meaning of this
this represents the implementing instance. Think of a trait as a superclass. This means that when you write:
http://docs.groovy-lang.org/latest/html/documentation/ 80/502
1/6/2019 Groovy Language Documentation
trait {
whoAmI() { }
}
{}
foo = ()
then calling:
foo.whoAmI()
will return the same instance:
foo.whoAmI(). (foo)
Interfaces
Traits may implement interfaces, in which case the interfaces are declared using the implements keyword:
{ 1
name()
}
trait { 2
greeting() { "Hello, ${name()}!" }
}
{ 3
name() { 'Bob' } 4
p = ()
p.greeting() == 'Hello, Bob!' 5
p 6
p 7
1 declaration of a normal interface
2 add Named to the list of implemented interfaces
3 declare a class that implements the Greetable trait
4 implement the missing name method
5 the greeting implementation comes from the trait
6 make sure Person implements the Named interface
7 make sure Person implements the Greetable trait
Properties
A trait may de ne properties, like in the following example:
trait {
name 1
}
{} 2
p = (name: 'Bob') 3
p.name == 'Bob' 4
p.getName() == 'Bob' 5
1 declare a property name inside a trait
2 declare a class which implements the trait
3 the property is automatically made visible
4 it can be accessed using the regular property accessor
5 or using the regular getter syntax
Fields
http://docs.groovy-lang.org/latest/html/documentation/ 81/502
1/6/2019 Private elds Groovy Language Documentation
Since traits allow the use of private methods, it can also be interesting to use private elds to store state. Traits will let you do that:
trait {
count = 0 1
count() { count += 1; count } 2
}
{} 3
f = ()
f.count() == 1 4
f.count() == 2
1 declare a private eld count inside a trait
2 declare a public method count that increments the counter and returns it
3 declare a class that implements the Counter trait
4 the count method can use the private eld to keep state
This is a major di erence with Java 8 virtual extension methods
(http://docs.oracle.com/javase/tutorial/java/IandI/defaultmethods.html). While virtual extension methods do not
carry state, traits can. Moreover, traits in Groovy are supported starting with Java 6, because their implementation
does not rely on virtual extension methods. This means that even if a trait can be seen from a Java class as a
regular interface, that interface will not have default methods, only abstract ones.
Public elds
Public elds work the same way as private elds, but in order to avoid the diamond problem
(http://en.wikipedia.org/wiki/Multiple_inheritance#The_diamond_problem), eld names are remapped in the implementing class:
trait {
name 1
}
{} 2
p = () 3
p. = 'Bob' 4
1 declare a public eld inside the trait
2 declare a class implementing the trait
3 create an instance of that class
4 the public eld is available, but renamed
The name of the eld depends on the fully quali ed name of the trait. All dots ( . ) in package are replaced with an underscore
( _ ), and the nal name includes a double underscore. So if the type of the eld is String , the name of the package is
my.package , the name of the trait is Foo and the name of the eld is bar , in the implementing class, the public eld will appear
as:
my_package_Foo__bar
While traits support public elds, it is not recommended to use them and considered as a bad practice.
Composition of behaviors
Traits can be used to implement multiple inheritance in a controlled way. For example, we can have the following traits:
trait { 1
fly() { "I'm flying!" } 2
}
trait {
speak() { "I'm speaking!" }
}
http://docs.groovy-lang.org/latest/html/documentation/ 82/502
1/6/2019 And a class implementing both traits: Groovy Language Documentation
, {} 1
d = () 2
d.fly() == "I'm flying!" 3
d.speak() == "I'm speaking!" 4
1 the Duck class implements both FlyingAbility and SpeakingAbility
2 creates a new instance of Duck
3 we can call the method fly from FlyingAbility
4 but also the method speak from SpeakingAbility
Traits encourage the reuse of capabilities among objects, and the creation of new classes by the composition of existing behavior.
Overriding default methods
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:
, {
quack() { "Quack!" } 1
speak() { quack() } 2
d = ()
d.fly() == "I'm flying!" 3
d.quack() == "Quack!" 4
d.speak() == "Quack!" 5
1 de ne a method speci c to Duck , named quack
2 override the default implementation of speak so that we use quack instead
3 the duck is still ying, from the default implementation
4 quack comes from the Duck class
5 speak no longer uses the default implementation from SpeakingAbility
Extending traits
Simple inheritance
Traits may extend another trait, in which case you must use the extends keyword:
trait {
name 1
}
trait { 2
introduce() { "Hello, I am $name" } 3
}
{}
p = (name: 'Alice') 4
p.introduce() == 'Hello, I am Alice' 5
1 the Named trait de nes a single name property
2 the Polite trait extends the Named trait
3 Polite adds a new method which has access to the name property of the super-trait
4 the name property is visible from the Person class implementing Polite
5 as is the introduce method
Multiple inheritance
Alternatively, a trait may extend multiple traits. In that case, all super traits must be declared in the implements clause:
http://docs.groovy-lang.org/latest/html/documentation/ 83/502
1/6/2019 Groovy Language Documentation
trait { 1
id
}
trait { 2
name
}
trait , {} 3
1 WithId trait de nes the id property
2 WithName trait de nes the name property
3 Identified is a trait which inherits both WithId and WithName
Duck typing and traits
Dynamic code
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:
trait {
speak() { quack() } 1
}
{
methodMissing( name, args) {
"${name.capitalize()}!" 2
}
}
d = ()
d.speak() == 'Quack!' 3
1 the SpeakingDuck expects the quack method to be de ned
2 the Duck class does implement the method using methodMissing
3 calling the speak method triggers a call to quack which is handled by methodMissing
Dynamic methods in a trait
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:
trait { 1
props = [:]
methodMissing( name, args) {
name.toUpperCase()
}
propertyMissing( prop) {
props[prop]
}
setProperty( prop, value) {
props[prop] = value
}
}
{
existingProperty = 'ok' 2
existingMethod() { 'ok' } 3
}
d = ()
d.existingProperty == 'ok' 4
d.foo == 5
d.foo = 'bar' 6
d.foo == 'bar' 7
d.existingMethod() == 'ok' 8
d.someMethod() == 'SOMEMETHOD' 9
http://docs.groovy-lang.org/latest/html/documentation/ 84/502
1/6/2019 1 create a trait implementing several MOP methods Groovy Language Documentation
2 the Dynamic class de nes a property
3 the Dynamic class de nes a method
4 calling an existing property will call the method from Dynamic
5 calling an non-existing property will call the method from the trait
6 will call setProperty de ned on the trait
7 will call getProperty de ned on the trait
8 calling an existing method on Dynamic
9 but calling a non existing method thanks to the trait methodMissing
Multiple inheritance con icts
Default con ict resolution
It is possible for a class to implement multiple traits. If some trait de nes a method with the same signature as a method in
another trait, we have a con ict:
trait A {
() { 'A' } 1
}
trait B {
() { 'B' } 2
}
C A,B {} 3
1 trait A de nes a method named exec returning a String
2 trait B de nes the very same method
3 class C implements both traits
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:
c = C()
c. () == 'B'
User con ict resolution
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:
C A,B {
() { A. . () } 1
}
c = C()
c. () == 'A' 2
1 explicit call of exec from the trait A
2 calls the version from A instead of using the default resolution, which would be the one from B
Runtime implementation of traits
Implementing a trait at runtime
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:
http://docs.groovy-lang.org/latest/html/documentation/ 85/502
1/6/2019 Groovy Language Documentation
trait {
extra() { "I'm an extra method" } 1
}
{ 2
doSomething() { 'Something' } 3
1 the Extra trait de nes an extra method
2 the Something class does not implement the Extra trait
3 Something only de nes a method doSomething
Then if we do:
s = ()
s.extra()
the call to extra would fail because Something is not implementing Extra . It is possible to do it at runtime with the following
syntax:
s = () 1
s.extra() 2
s.doSomething() 3
1 use of the as keyword to coerce an object to a trait at runtime
2 then extra can be called on the object
3 and doSomething is still callable
When coercing an object to a trait, the result of the operation is not the same instance. It is guaranteed that the
coerced object will implement both the trait and the interfaces that the original object implements, but the result
will not be an instance of the original class.
Implementing multiple traits at once
Should you need to implement several traits at once, you can use the withTraits method instead of the as keyword:
trait A { methodFromA() {} }
trait B { methodFromB() {} }
C {}
c = C()
c.methodFromA() 1
c.methodFromB() 2
d = c.withTraits A, B 3
d.methodFromA() 4
d.methodFromB() 5
1 call to methodFromA will fail because C doesn’t implement A
2 call to methodFromB will fail because C doesn’t implement B
3 withTrait will wrap c into something which implements A and B
4 methodFromA will now pass because d implements A
5 methodFromB will now pass because d also implements B
When coercing an object to multiple traits, the result of the operation is not the same instance. It is guaranteed
that the coerced object will implement both the traits and the interfaces that the original object implements, but
the result will not be an instance of the original class.
Chaining behavior
http://docs.groovy-lang.org/latest/html/documentation/ 86/502
1/6/2019 Groovy supports the concept of stackable traits. The idea Groovy
is to delegate from
Language one trait to the other if the current trait is not
Documentation
capable of handling a message. To illustrate this, let’s imagine a message handler interface like this:
{
on( message, payload)
}
Then you can compose a message handler by applying small behaviors. For example, let’s de ne a default handler in the form of a
trait:
trait {
on( message, payload) {
println "Received $message with payload $payload"
}
}
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:
{
on( message, payload) { 1
println "Seeing $message with payload $payload" 2
. .on(message, payload) 3
}
}
1 explicitly implement the on method
2 perform logging
3 continue by delegating to the DefaultHandler trait
This works but this approach has drawbacks:
1. the logging logic is bound to a "concrete" handler
2. 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:
trait { 1
on( message, payload) {
println "Seeing $message with payload $payload" 2
.on(message, payload) 3
}
}
1 the logging handler is itself a handler
2 prints the message it receives
3 then super makes it delegate the call to the next trait in the chain
Then our class can be rewritten as this:
, {}
loggingHandler = ()
loggingHandler.on('test logging', [:])
which will print:
http://docs.groovy-lang.org/latest/html/documentation/ 87/502
1/6/2019 Groovy Language Documentation
Seeing test logging with payload [:]
Received test logging with payload [:]
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 :
trait {
on( message, payload) {
(message.startsWith("say")) { 1
println "I say ${message - 'say'}!"
} {
.on(message, payload) 2
}
}
}
1 a handler speci c precondition
2 if the precondition is not met, pass the message to the next handler in the chain
Then our nal handler looks like this:
, , {}
h = ()
h.on('foo', [:])
h.on('sayHello', [:])
Which means:
messages will rst 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:
Seeing foo with payload [:]
Received foo with payload [:]
Seeing sayHello with payload [:]
I say Hello!
but if we move the logging handler to be the second one in the chain, the output is di erent:
, , {}
h = ()
h.on('foo', [:])
h.on('sayHello', [:])
prints:
Seeing foo with payload [:]
Received foo with payload [:]
I say Hello!
The reason is that now, since the SayHandler consumes the message without calling super , the logging handler is not called
anymore.
http://docs.groovy-lang.org/latest/html/documentation/ 88/502
1/6/2019 Semantics of super inside a trait Groovy Language Documentation
If a class implements multiple traits and a call to an unquali ed super is found, then:
1. if the class implements another trait, the call delegates to the next trait in the chain
2. 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 nal classes thanks to this behavior:
trait { 1
append( str) { 2
subst = str.replace('o','') 3
.append(subst) 4
}
toString() { .toString() } 5
}
sb = ().withTraits 6
sb.append('Groovy')
sb.toString() == 'Grvy' 7
1 de ne a trait named Filtering , supposed to be applied on a StringBuilder at runtime
2 rede ne the append method
3 remove all 'o’s from the string
4 then delegate to super
5 in case toString is called, delegate to super.toString
6 runtime implementation of the Filtering trait on a StringBuilder instance
7 the string which has been appended no longer contains the letter o
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
SAM type coercion
If a trait de nes a single abstract method, it is candidate for SAM (Single Abstract Method) type coercion. For example, imagine the
following trait:
trait {
greet() { "Hello $name" } 1
getName() 2
1 the greet method is not abstract and calls the abstract method getName
2 getName is an abstract method
Since getName is the single abstract method in the Greeter trait, you can write:
greeter = { 'Alice' } 1
1 the closure "becomes" the implementation of the getName single abstract method
or even:
greet( g) { println g.greet() } 1
greet { 'Alice' } 2
1 the greet method accepts the SAM type Greeter as parameter
2 we can call it directly with a closure
http://docs.groovy-lang.org/latest/html/documentation/ 89/502
1/6/2019 Di erences with Java 8 default methods Groovy Language Documentation
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 di erence: 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 an 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:
groovy.transform.
org.codehaus.groovy.control.
org.codehaus.groovy.control.customizers.
org.codehaus.groovy.control.customizers.
{
config
shell
setup() {
config = ()
shell = (config)
}
testSomething() {
shell.evaluate('1+1') == 2
}
otherTest() { /* ... */ }
}
In this example, we create a simple test case which uses two properties (con g and shell) and uses those in multiple test methods.
Now imagine that you want to test the same, but with another distinct compiler con guration. One option is to create a subclass
of SomeTest :
{
setup() {
config = ()
config.addCompilationCustomizers( ... )
shell = (config)
}
}
It works, but what if you have actually multiple test classes, and that you want to test the new con guration for all those test
classes? Then you would have to create a distinct subclass for each test class:
{
setup() {
config = ()
config.addCompilationCustomizers( ... )
shell = (config)
}
}
Then what you see is that the setup method of both tests is the same. The idea, then, is to create a trait:
trait {
setup() {
config = ()
config.addCompilationCustomizers( ( ) )
shell = (config)
}
}
http://docs.groovy-lang.org/latest/html/documentation/ 90/502
1/6/2019 Then use it in the subclasses: Groovy Language Documentation
{}
{}
...
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.
It’s worth noting that if you use runtime traits, the methods from the trait are always preferred to those of the
proxied object:
{
name 1
}
trait {
getName() { 'Bob' } 2
p = (name: 'Alice')
p.name == 'Alice' 3
p2 = p 4
p2.name == 'Bob' 5
1 the Person class de nes a name property which results in a getName method
2 Bob is a trait which de nes getName as returning Bob
3 the default object will return Alice
4 p2 coerces p into Bob at runtime
5 getName returns Bob because getName is taken from the trait
Again, don’t forget that dynamic trait coercion returns a distinct object which only implements the original
interfaces, as well as the traits.
Di erences with mixins
There are several conceptual di erences 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 de ned 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 e ectively 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:
http://docs.groovy-lang.org/latest/html/documentation/ 91/502
1/6/2019 Groovy Language Documentation
A { methodFromA() { 'A' } } 1
B { methodFromB() { 'B' } } 2
A.metaClass.mixin B 3
o = A()
o.methodFromA() == 'A' 4
o.methodFromB() == 'B' 5
o A 6
!(o B) 7
1 class A de nes methodFromA
2 class B de nes methodFromB
3 mixin B into A
4 we can call methodFromA
5 we can also call methodFromB
6 the object is an instance of A
7 but it’s not an instanceof B
The last point is actually a very important and illustrates a place where mixins have an advantage over traits: the instances are not
modi ed, 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.
Static methods, properties and elds
The following instructions are subject to caution. Static member support is work in progress and still
experimental. The information below is valid for 2.5.5 only.
It is possible to de ne 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 eld 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 elds. So a static member declared on a trait doesn’t belong to the Trait , but to it’s
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 con ict 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:
trait {
CALLED = 1
init() { 2
CALLED = 3
}
}
{}
.init() 4
. 5
1 the static eld is declared in the trait
2 a static method is also declared in the trait
3 the static eld is updated within the trait
4 a static method init is made available to the implementing class
5 the static eld is remapped to avoid the diamond issue
http://docs.groovy-lang.org/latest/html/documentation/ 92/502
1/6/2019 As usual, it is not recommended to use public elds. Anyway, should
Groovy you want
Language this, you must understand that the following code
Documentation
would fail:
.CALLED =
because there is no static eld CALLED de ned on the trait itself. Likewise, if you have two distinct implementing classes, each one
gets a distinct static eld:
{} 1
{} 2
.init() 3
. 4
! . 5
1 class Bar implements the trait
2 class Baz also implements the trait
3 init is only called on Bar
4 the static eld CALLED on Bar is updated
5 but the static eld CALLED on Baz is not, because it is distinct
Inheritance of state gotchas
We have seen that traits are stateful. It is possible for a trait to de ne elds or properties, but when a class implements a trait, it
gets those elds/properties on a per-trait basis. So consider the following example:
trait {
x = 1
y = 2
sum() { x+y }
}
The trait de nes two properties, x and y , as well as a sum method. Now let’s create a class which implements the trait:
{
f() { sum() }
}
= ()
.f() == 3
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?
{
x = 3 1
y = 4 2
f() { sum() } 3
}
elem = ()
1 Override property x
2 Override property y
3 Call sum from trait
If you call elem.f() , what is the expected output? Actually it is:
elem.f() == 3
The reason is that the sum method accesses the elds of the trait. So it is using the x and y values de ned in the trait. If you
want to use the values from the implementing class, then you need to dereference elds by using getters and setters, like in this
last example:
http://docs.groovy-lang.org/latest/html/documentation/ 93/502
1/6/2019 Groovy Language Documentation
trait {
x = 1
y = 2
sum() { getX()+getY() }
}
{
x = 3
y = 4
f() { sum() }
}
elem = ()
elem.f() == 7
Self types
Type constraints on traits
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:
{
sendMessage( , to, message) { 1
println "$from sent [$message] to $to"
}
}
{ id } 2
trait {
sendMessage( to, message) {
.sendMessage(id, to.id, message) 3
}
}
{} 4
bob = (id:'Bob')
alice = (id:'Alice')
bob.sendMessage(alice,'secret') 5
1 A Service class, beyond your control (in a library, …) de nes a sendMessage method
2 A Device class, beyond your control (in a library, …)
3 De nes a communicating trait for devices that can call the service
4 De nes MyDevice as a communicating device
5 The method from the trait is called, and id is resolved
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 ne, 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 nd 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 ?
{
check( d) { (d.id== ) () }
}
http://docs.groovy-lang.org/latest/html/documentation/ 94/502
1/6/2019 If you want to be able to call this in the trait, then you will explicitly
Groovy need to
Language cast this into a Device . This can quickly become
Documentation
unreadable with explicit casts to this everywhere.
The @SelfType annotation
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 satis ed
So in our previous example, we can x the trait using the @groovy.transform.SelfType annotation:
@SelfType( )
@CompileStatic
trait {
sendMessage( to, message) {
.check( )
.sendMessage(id, to.id, message)
}
}
Now if you try to implement this trait on a class that is not a device, a compile-time error will occur:
{} // forgot to extend Device
The error will be:
class 'MyDevice' implements trait 'Communicating' but does not extend self type class 'Device'
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.
Limitations
Compatibility with AST transformations
Traits are not o cially compatible with AST transformations. Some of them, like @CompileStatic will be applied
on the trait itself (not on implementing classes), while others will apply on both the implementing class and the
trait. There is absolutely no guarantee that an AST transformation will run on a trait as it does on a regular class,
so use it at your own risk!
Pre x and post x operations
Within traits, pre x and post x operations are not allowed if they update a eld of the trait:
trait {
x
inc() {
x++ 1
}
dec() {
--x 2
}
}
{}
c = ()
c.inc()
1 x is de ned within the trait, post x increment is not allowed
2 x is de ned within the trait, pre x decrement is not allowed
A workaround is to use the += operator instead.
http://docs.groovy-lang.org/latest/html/documentation/ 95/502
1/6/2019 1.5. Closures Groovy Language Documentation
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 de nition of a closure, Closure in the Groovy language can also contain free variables which are de ned outside of its
surrounding scope. While breaking the formal concept of a closure, it o ers a variety of advantages which are described in this
chapter.
1.5.1. Syntax
De ning a closure
A closure de nition follows this syntax:
{ [closureParameters -> ] statements }
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 speci ed, 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 de nitions:
{ item++ } 1
{ -> item++ } 2
{ println it } 3
{ it -> println it } 4
{ name -> println name } 5
{ x, y -> 6
println "hey ${x} the value is ${y}"
}
{ reader -> 7
line = reader.readLine()
line.trim()
}
1 A closure referencing a variable named item
2 It is possible to explicitly separate closure parameters from code by adding an arrow ( -> )
3 A closure using an implicit parameter ( it )
4 An alternative version where it is an explicit parameter
5 In that case it is often better to use an explicit name for the parameter
6 A closure accepting two typed parameters
7 A closure can contain multiple statements
Closures as an object
A closure is an instance of the groovy.lang.Closure class, making it assignable to a variable or a eld as any other variable,
despite being a block of code:
listener = { e -> println "Clicked on $e.source" } 1
listener
callback = { println 'Done!' } 2
< > isTextFile = {
it -> it.name.endsWith('.txt') 3
http://docs.groovy-lang.org/latest/html/documentation/ 96/502
1/6/2019 1 Groovy Language
You can assign a closure to a variable, and it is an instance Documentation
of groovy.lang.Closure
2 If not using def , you can assign a closure to a variable of type groovy.lang.Closure
3 Optionally, you can specify the return type of the closure by using the generic type of groovy.lang.Closure
Calling a closure
A closure, as an anonymous block of code, can be called like any other method. If you de ne a closure which takes no argument
like this:
code = { 123 }
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:
code() == 123
Alternatively, you can be explicit and use the call method:
code.call() == 123
The principle is the same if the closure accepts arguments:
isOdd = { i -> i%2 != 0 } 1
isOdd(3) == 2
isOdd.call(2) == 3
isEven = { it%2 == 0 } 4
isEven(3) == 5
isEven.call(2) == 6
1 de ne a closure which accepts an int as a parameter
2 it can be called directly
3 or using the call method
4 same goes for a closure with an implicit argument ( it )
5 which can be called directly using (arg)
6 or using call
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
Normal parameters
Parameters of closures follow the same principle as parameters of regular methods:
an optional type
a name
an optional default value
Parameters are separated with commas:
http://docs.groovy-lang.org/latest/html/documentation/ 97/502
1/6/2019 Groovy Language Documentation
closureWithOneArg = { str -> str.toUpperCase() }
closureWithOneArg('groovy') == 'GROOVY'
closureWithOneArgAndExplicitType = { str -> str.toUpperCase() }
closureWithOneArgAndExplicitType('groovy') == 'GROOVY'
closureWithTwoArgs = { a,b -> a+b }
closureWithTwoArgs(1,2) == 3
closureWithTwoArgsAndExplicitTypes = { a, b -> a+b }
closureWithTwoArgsAndExplicitTypes(1,2) == 3
closureWithTwoArgsAndOptionalTypes = { a, b -> a+b }
closureWithTwoArgsAndOptionalTypes(1,2) == 3
closureWithTwoArgAndDefaultValue = { a, b=2 -> a+b }
closureWithTwoArgAndDefaultValue(1) == 3
Implicit parameter
When a closure does not explicitly de ne a parameter list (using -> ), a closure always de nes an implicit parameter, named it .
This means that this code:
greeting = { "Hello, $it!" }
greeting('Patrick') == 'Hello, Patrick!'
is stricly equivalent to this one:
greeting = { it -> "Hello, $it!" }
greeting('Patrick') == 'Hello, Patrick!'
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:
magicNumber = { -> 42 }
// this call will fail because the closure doesn't accept any argument
magicNumber(11)
Varargs
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:
concat1 = { ... args -> args.join('') } 1
concat1('abc','def') == 'abcdef' 2
concat2 = { [] args -> args.join('') } 3
concat2('abc', 'def') == 'abcdef'
multiConcat = { n, ... args -> 4
args.join('')*n
}
multiConcat(2, 'abc','def') == 'abcdefabcdef'
1 A closure accepting a variable number of strings as rst parameter
2 It may be called using any number of arguments without having to explicitly wrap them into an array
3 The same behavior is directly available if the args parameter is declared as an array
4 As long as the last parameter is an array or an explicit vargs type
1.5.3. Delegation strategy
Groovy closures vs lambda expressions
http://docs.groovy-lang.org/latest/html/documentation/ 98/502
1/6/2019 Groovy de nes closures as instances of the Closure class.Groovy
It makes it very diDocumentation
Language erent from lambda expressions in Java 8
(http://docs.oracle.com/javase/tutorial/java/javaOO/lambdaexpressions.html). 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 speci c languages (DSLs) in Groovy.
Owner, delegate and this
To understand the concept of delegate, we must rst explain the meaning of this inside a closure. A closure actually de nes 3
distinct things:
this corresponds to the enclosing class where the closure is de ned
owner corresponds to the enclosing object where the closure is de ned, 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 de ned
The meaning of this
In a closure, calling getThisObject will return the enclosing class where the closure is de ned. It is equivalent to using an explicit
this :
{
run() {
whatIsThisObject = { getThisObject() } 1
whatIsThisObject() == 2
whatIsThis = { } 3
whatIsThis() == 4
}
}
{
{
cl = { } 5
}
run() {
inner = ()
inner.cl() == inner 6
}
}
{
run() {
nestedClosures = {
cl = { } 7
cl()
}
nestedClosures() == 8
}
}
1 a closure is de ned inside the Enclosing class, and returns getThisObject
2 calling the closure will return the instance of Enclosing where the the closure is de ned
3 in general, you will just want to use the shortcut this notation
4 and it returns exactly the same object
5 if the closure is de ned in a inner class
6 this in the closure will return the inner class, not the top-level one
7 in case of nested closures, like here cl being de ned inside the scope of nestedClosures
8 then this corresponds to the closest outer class, not the enclosing closure!
It is of course possible to call methods from the enclosing class this way:
http://docs.groovy-lang.org/latest/html/documentation/ 99/502
1/6/2019 Groovy Language Documentation
{
name
age
toString() { "$name is $age years old" }
() {
cl = {
msg = .toString() 1
println msg
msg
}
cl()
}
}
p = (name:'Janice', age:74)
p. () == 'Janice is 74 years old'
the closure calls toString on this , which will actually call the toString method on the enclosing object, that is to say
1
the Person instance
Owner of a closure
The owner of a closure is very similar to the de nition of this in a closure with a subtle di erence: it will return the direct enclosing
object, be it a closure or a class:
{
run() {
whatIsOwnerMethod = { getOwner() } 1
whatIsOwnerMethod() == 2
whatIsOwner = { owner } 3
whatIsOwner() == 4
}
}
{
{
cl = { owner } 5
}
run() {
inner = ()
inner.cl() == inner 6
}
}
{
run() {
nestedClosures = {
cl = { owner } 7
cl()
}
nestedClosures() == nestedClosures 8
}
}
1 a closure is de ned inside the Enclosing class, and returns getOwner
2 calling the closure will return the instance of Enclosing where the the closure is de ned
3 in general, you will just want to use the shortcut owner notation
4 and it returns exactly the same object
5 if the closure is de ned in a inner class
6 owner in the closure will return the inner class, not the top-level one
7 but in case of nested closures, like here cl being de ned inside the scope of nestedClosures
8 then owner corresponds to the enclosing closure, hence a di erent object from this !
Delegate of a closure
http://docs.groovy-lang.org/latest/html/documentation/ 100/502
1/6/2019 The delegate of a closure can be accessed by using the delegate propertyDocumentation
Groovy Language or calling the getDelegate method. It is a powerful
concept for building domain speci c languages in Groovy. While closure-this and closure-owner refer to the lexical scope of a
closure, the delegate is a user de ned object that a closure will use. By default, the delegate is set to owner :
{
run() {
cl = { getDelegate() } 1
cl2 = { } 2
cl() == cl2() 3
cl() == 4
enclosed = {
{ -> }.call() 5
}
enclosed() == enclosed 6
}
}
1 you can get the delegate of a closure calling the getDelegate method
2 or using the delegate property
3 both return the same object
4 which is the enclosing class or closure
5 in particular in case of nested closures
6 delegate will correspond to the 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 de ne a property called name :
{
name
}
{
name
}
p = (name: 'Norman')
t = (name: 'Teapot')
Then let’s de ne a closure which fetches the name property on the delegate:
upperCasedName = { .name.toUpperCase() }
Then by changing the delegate of the closure, you can see that the target object will change:
upperCasedName. = p
upperCasedName() == 'NORMAN'
upperCasedName. = t
upperCasedName() == 'TEAPOT'
At this point, the behavior is not di erent from having a target variable de ned in the lexical scope of the closure:
target = p
upperCasedNameUsingVar = { target.name.toUpperCase() }
upperCasedNameUsingVar() == 'NORMAN'
However, there are major di erences:
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 pre xing method calls with delegate. as explained in the next
paragraph.
http://docs.groovy-lang.org/latest/html/documentation/ 101/502
1/6/2019 Delegation strategy Groovy Language Documentation
Whenever, in a closure, a property is accessed without explicitly setting a receiver object, then a delegation strategy is involved:
{
name
}
p = (name:'Igor')
cl = { name.toUpperCase() } 1
cl. = p 2
cl() == 'IGOR' 3
1 name is not referencing a variable in the lexical scope of the closure
2 we can change the delegate of the closure to be an instance of Person
3 and the method call will succeed
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 de nes 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 rst, 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 rst" strategy with this code:
{
name
pretty = { "My name is $name" } 1
toString() {
pretty()
}
}
{
name 2
p = (name: 'Sarah')
t = (name: 'Teapot')
p.toString() == 'My name is Sarah' 3
p.pretty. = t 4
p.toString() == 'My name is Sarah' 5
1 for the illustration, we de ne a closure member which references "name"
2 both the Person and the Thing class de ne a name property
3 Using the default strategy, the name property is resolved on the owner rst
4 so if we change the delegate to t which is an instance of Thing
5 there is no change in the result: name is rst resolved on the owner of the closure
However, it is possible to change the resolution strategy of the closure:
p.pretty.resolveStrategy = .DELEGATE_FIRST
p.toString() == 'My name is Teapot'
http://docs.groovy-lang.org/latest/html/documentation/ 102/502
1/6/2019 By changing the resolveStrategy , we are modifying theGroovy
way Groovy will resolve
Language the "implicit this" references: in this case, name
Documentation
will rst be looked in the delegate, then if not found, on the owner. Since name is de ned in the delegate, an instance of Thing ,
then this value is used.
The di erence between "delegate rst" and "delegate only" or "owner rst" and "owner only" can be illustrated if one of the
delegate (resp. owner) does not have such a method or property:
{
name
age
fetchAge = { age }
}
{
name
}
p = (name:'Jessica', age:42)
t = (name:'Printer')
cl = p.fetchAge
cl. = p
cl() == 42
cl. = t
cl() == 42
cl.resolveStrategy = .DELEGATE_ONLY
cl. = p
cl() == 42
cl. = t
{
cl()
} ( ex) {
// "age" is not defined on the delegate
}
In this example, we de ne 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 rst" 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 de ned inside the Person class, the owner is not used.
A comprehensive explanation about how to use this feature to develop DSLs can be found in a dedicated section
of the manual (core-domain-speci c-languages.html).
1.5.4. Closures in GStrings
Take the following code:
x = 1
gs = "x = ${x}"
gs == 'x = 1'
The code behaves as you would expect, but what happens if you add:
x = 2
gs == 'x = 2'
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.
http://docs.groovy-lang.org/latest/html/documentation/ 103/502
1/6/2019 In our example, the GString is created with an expression referencing
Groovy x . Documentation
Language 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 di erent object, and the GString still
references the old one.
A GString will only change its toString representation if the values it references are mutating. If the references
change, nothing will happen.
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 xed example:
x = 1
gs = "x = ${-> x}"
gs == 'x = 1'
x = 2
gs == 'x = 2'
And let’s illustrate how it di ers from mutation with this code:
{
name
toString() { name } 1
}
sam = (name:'Sam') 2
lucy = (name:'Lucy') 3
p = sam 4
gs = "Name: ${p}" 5
gs == 'Name: Sam' 6
p = lucy 7
gs == 'Name: Sam' 8
sam.name = 'Lucy' 9
gs == 'Name: Lucy' 10
1 the Person class has a toString method returning the name property
2 we create a rst Person named Sam
3 we create another Person named Lucy
4 the p variable is set to Sam
5 and a closure is created, referencing the value of p , that is to say Sam
6 so when we evaluate the string, it returns Sam
7 if we change p to Lucy
8 the string still evaluates to Sam because it was the value of p when the GString was created
9 so if we mutate Sam to change his name to Lucy
10 this time the GString is correctly mutated
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:
http://docs.groovy-lang.org/latest/html/documentation/ 104/502
1/6/2019 Groovy Language Documentation
{
name
toString() { name }
}
sam = (name:'Sam')
lucy = (name:'Lucy')
p = sam
// Create a GString with lazy evaluation of "p"
gs = "Name: ${-> p}"
gs == 'Name: Sam'
p = lucy
gs == 'Name: Lucy'
1.5.5. Closure coercion
Closures can be converted into interfaces or single-abstract method types. Please refer to this section of the manual (core-
semantics.html#closure-coercion) for a complete description.
1.5.6. Functional programming
Closures, like lambda expressions in Java 8 (http://docs.oracle.com/javase/tutorial/java/javaOO/lambdaexpressions.html) 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.
Currying
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 di erent 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
Left currying is the fact of setting the left-most parameter of a closure, like in this example:
nCopies = { n, str -> str*n } 1
twice = nCopies.curry(2) 2
twice('bla') == 'blabla' 3
twice('bla') == nCopies(2, 'bla') 4
1 the nCopies closure de nes two parameters
2 curry will set the rst parameter to 2 , creating a new closure (function) which accepts a single String
3 so the new function call be called with only a String
4 and it is equivalent to calling nCopies with two parameters
Right currying
Similarily to left currying, it is possible to set the right-most parameter of a closure:
nCopies = { n, str -> str*n } 1
blah = nCopies.rcurry('bla') 2
blah(2) == 'blabla' 3
blah(2) == nCopies(2, 'bla') 4
1 the nCopies closure de nes two parameters
2 rcurry will set the last parameter to bla , creating a new closure (function) which accepts a single int
3 so the new function call be called with only an int
4 and it is equivalent to calling nCopies with two parameters
Index based currying
In case a closure accepts more than 2 parameters, it is possible to set an arbitrary parameter using ncurry :
http://docs.groovy-lang.org/latest/html/documentation/ 105/502
1/6/2019 Groovy Language Documentation
volume = { l, w, h -> l*w*h } 1
fixedWidthVolume = volume.ncurry(1, 2d) 2
volume(3d, 2d, 4d) == fixedWidthVolume(3d, 4d) 3
fixedWidthAndHeight = volume.ncurry(1, 2d, 4d) 4
volume(3d, 2d, 4d) == fixedWidthAndHeight(3d) 5
1 the volume function de nes 3 parameters
2 ncurry will set the second parameter (index = 1) to 2d , creating a new volume function which accepts length and height
3 that function is equivalent to calling volume omitting the width
4 it is also possible to set multiple parameters, starting from the speci ed index
5 the resulting function accepts as many parameters as the initial one minus the number of parameters set by ncurry
Memoization
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:
fib
fib = { n -> n<2?n:fib(n-1)+fib(n-2) }
fib(15) == 610 // slow!
It is a naive implementation because ' b' 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 " xed" by caching the result of calls using memoize :
fib = { n -> n<2?n:fib(n-1)+fib(n-2) }.memoize()
fib(25) == 75025 // fast!
The cache works using the actual values of the arguments. This means that you should be very careful if you use
memoization with something else than primitive or boxed primitive types.
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 a LRU cache.
Composition
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:
http://docs.groovy-lang.org/latest/html/documentation/ 106/502
1/6/2019 Groovy Language Documentation
plus2 = { it + 2 }
times3 = { it * 3 }
times3plus2 = plus2 << times3
times3plus2(3) == 11
times3plus2(4) == plus2(times3(4))
plus2times3 = times3 << plus2
plus2times3(3) == 15
plus2times3(5) == times3(plus2(5))
// reverse composition
times3plus2(3) == (times3 >> plus2)(3)
Trampoline
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 nal result of the
trampoline. That way, calls are made serially, rather than lling the stack.
Here’s an example of the use of trampoline() to implement the factorial function:
factorial
factorial = { n, accu = 1G ->
(n < 2) accu
factorial.trampoline(n - 1, n * accu)
}
factorial = factorial.trampoline()
factorial(1) == 1
factorial(3) == 1 * 2 * 3
factorial(1000) // == 402387260.. plus another 2560 digits
Method pointers
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 (core-operators.html#method-pointer-operator).
1.6. Semantics
This chapter covers the semantics of the Groovy programming language.
1.6.1. Statements
Variable de nition
Variables can be de ned using either their type (like String ) or by using the keyword def :
x
o
def is a replacement for a type name. In variable de nitions it is used to indicate that you don’t care about the type. In variable
de nitions it is mandatory to either provide a type name explicitly or to use "def" in replacement. This is needed to make variable
de nitions detectable for the Groovy parser.
You can think of def as an alias of Object and you will understand it in an instant.
http://docs.groovy-lang.org/latest/html/documentation/ 107/502
1/6/2019 Groovy Language Documentation
Variable de nition types can be re ned by using generics, like in List<String> names . To learn more about the
generics support, please read the generics section.
Variable assignment
You can assign values to variables for later use. Try the following:
x = 1
println x
x = java.util. ()
println x
x = -3.1499392
println x
x =
println x
x = "Hi"
println x
Multiple assignment
Groovy supports multiple assignment, i.e. where multiple variables can be assigned at once, e.g.:
(a, b, c) = [10, 20, 'foo']
a == 10 && b == 20 && c == 'foo'
You can provide types as part of the declaration if you wish:
( i, j) = [10, 'foo']
i == 10 && j == 'foo'
As well as used when declaring variables it also applies to existing variables:
nums = [1, 3, 5]
a, b, c
(a, b, c) = nums
a == 1 && b == 3 && c == 5
The syntax works for arrays as well as lists, as well as methods that return either of these:
(_, month, year) = "18th June 2009".split()
"In $month of $year" == 'In June of 2009'
Over ow and Under ow
If the left hand side has too many variables, excess ones are lled with null’s:
(a, b, c) = [1, 2]
a == 1 && b == 2 && c ==
If the right hand side has too many variables, the extra ones are ignored:
(a, b) = [1, 2, 3]
a == 1 && b == 2
Object destructuring with multiple assignment
In the section describing the various Groovy operators, the case of the subscript operator has been covered, explaining how you
can override the getAt() / putAt() method.
http://docs.groovy-lang.org/latest/html/documentation/ 108/502
1/6/2019 With this technique, we can combine multiple assignments and the
Groovy subscript
Language operator methods to implement object
Documentation
destructuring.
Consider the following immutable Coordinates class, containing a pair of longitude and latitude doubles, and notice our
implementation of the getAt() method:
@Immutable
{
latitude
longitude
getAt( idx) {
(idx == 0) latitude
(idx == 1) longitude
("Wrong coordinate index, use 0 or 1")
}
}
Now let’s instantiate this class and destructure its longitude and latitude:
coordinates = (latitude: 43.23, longitude: 3.67) 1
(la, lo) = coordinates 2
la == 43.23 3
lo == 3.67
1 we create an instance of the Coordinates class
2 then, we use a multiple assignment to get the individual longitude and latitude values
3 and we can nally assert their values.
Control structures
Conditional structures
if / else
Groovy supports the usual if - else syntax from Java
x =
y =
( !x ) {
x =
}
x ==
( x ) {
x =
} {
y =
}
x == y
Groovy also supports the normal Java "nested" if then else if syntax:
( ... ) {
...
} (...) {
...
} {
...
}
http://docs.groovy-lang.org/latest/html/documentation/ 109/502
1/6/2019 switch / case Groovy Language Documentation
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 di erence though is that the Groovy switch statement can handle any kind of switch value and di erent kinds of matching
can be performed.
x = 1.23
result = ""
( x ) {
"foo":
result = "found foo"
// lets fall through
"bar":
result += "bar"
[4, 5, 6, 'inList']:
result = "list"
12..30:
result = "range"
:
result = "integer"
:
result = "number"
~/fo*/: // toString() representation of x matches the pattern?
result = "foo regex"
{ it < 0 }: // or { x < 0 }
result = "negative"
:
result = "default"
}
result == "number"
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
When using a closure case value, the default it parameter is actually the switch value (in our example, variable
x ).
Looping structures
Classic for loop
Groovy supports the standard Java / C for loop:
http://docs.groovy-lang.org/latest/html/documentation/ 110/502
1/6/2019 Groovy Language Documentation
message = ''
( i = 0; i < 5; i++) {
message += 'Hi '
}
message == 'Hi Hi Hi Hi Hi '
for in loop
The for loop in Groovy is much simpler and works with any kind of array, collection, Map, etc.
// iterate over a range
x = 0
( i 0..9 ) {
x += i
}
x == 45
// iterate over a list
x = 0
( i [0, 1, 2, 3, 4] ) {
x += i
}
x == 10
// iterate over an array
array = (0..4).toArray()
x = 0
( i array ) {
x += i
}
x == 10
// iterate over a map
map = ['abc':1, 'def':2, 'xyz':3]
x = 0
( e map ) {
x += e.value
}
x == 6
// iterate over values in a map
x = 0
( v map.values() ) {
x += v
}
x == 6
// iterate over the characters in a string
text = "abc"
list = []
(c text) {
list.add(c)
}
list == ["a", "b", "c"]
Groovy also supports the Java colon variation with colons: for (char c : text) {} , where the type of the
variable is mandatory.
while loop
Groovy supports the usual while {…} loops like Java:
http://docs.groovy-lang.org/latest/html/documentation/ 111/502
1/6/2019 Groovy Language Documentation
x = 0
y = 5
( y-- > 0 ) {
x++
}
x == 5
Exception handling
Exception handling is the same as Java.
try / catch / nally
You can specify a complete try-catch-finally , a try-catch , or a try-finally set of blocks.
Braces are required around each block’s body.
{
'moo'.toLong() // this will generate an exception
// asserting that this point should never be reached
} ( e ) {
e
}
We can put code within a ' nally' clause following a matching 'try' clause, so that regardless of whether the code in the 'try' clause
throws an exception, the code in the nally clause will always execute:
z
{
i = 7, j = 0
{
k = i / j
//never reached due to Exception in previous line
} {
z = 'reached here' //always executed even if Exception thrown
}
} ( e ) {
e
z == 'reached here'
}
Multi-catch
With the multi catch block (since Groovy 2.0), we’re able to de ne several exceptions to be catch and treated by the same catch
block:
{
/* ... */
} ( | e ) {
/* one block to handle 2 exceptions */
}
Power assertion
Unlike Java with which Groovy shares the assert keyword, the latter in Groovy behaves very di erently. First of all, an assertion
in Groovy is always executed, independently of the -ea ag of the JVM. It makes this a rst 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:
assert [left expression] == [right expression] : (optional message)
http://docs.groovy-lang.org/latest/html/documentation/ 112/502
1/6/2019 The result of the assertion is very di erent from what youGroovy
would Language
get in Java.Documentation
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:
1+1 == 3
Will yield:
Caught: Assertion failed:
assert 1+1 == 3
| |
2 false
Power asserts become very interesting when the expressions are more complex, like in the next example:
x = 2
y = 7
z = 5
calc = { a,b -> a*b+1 }
calc(x,y) == [x,z].sum()
Which will print the value for each sub-expression:
calc(x,y) == [x,z].sum()
| | | | | | |
15 2 7 | 2 5 7
In case you don’t want a pretty printed error message like above, you can fallback to a custom error message by changing the
optional message part of the assertion, like in this example:
x = 2
y = 7
z = 5
calc = { a,b -> a*b+1 }
calc(x,y) == z*z : 'Incorrect computation result'
Which will print the following error message:
computation result. : (calc.call(x, y) == (z * z)). : z = 5, z = 5
Labeled statements
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:
given:
x = 1
y = 2
:
z = x+y
:
z == 3
Despite not changing the semantics of the 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:
http://docs.groovy-lang.org/latest/html/documentation/ 113/502
1/6/2019 Groovy Language Documentation
( i=0;i<10;i++) {
( j=0;j<i;j++) {
println "j=$j"
(j == 5) {
}
}
: println "i=$i"
}
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 di erent semantics. This is in particular what the Spock Framework
(http://spockframework.github.io/spock/docs/current/index.html) does to make testing easier.
1.6.2. Expressions
(TBD)
GPath expressions
GPath is a path expression language integrated into Groovy which allows parts of nested structured data to be identi ed. 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 lesystem-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 (..\..\../subprojects/groovy-
xml/src/spec/doc/xml-userguide.html#Processing XML) for more in-depth details on consuming XML in Groovy.
When querying the object graph generated from XmlParser or XmlSlurper, a GPath expression can refer to
attributes de ned on elements with the @ notation:
a["@href"] → map-like notation : the href attribute of all the a elements
a.'@href' → property notation : an alternative way of expressing this
a.@href → direct notation : yet another alternative way of expressing this
Object navigation
Let’s see an example of a GPath expression on a simple object graph, the one obtained using java re ection. Suppose you are in a
non-static method of a class having another method named aMethodFoo
aMethodFoo() { println "This is aMethodFoo." } 0
the following GPath expression will get the name of that method:
['aMethodFoo'] == . .methods.name.grep(~/.*Foo/)
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 de ned in that class:
aMethodBar() { println "This is aMethodBar." } 1
anotherFooMethod() { println "This is anotherFooMethod." } 2
aSecondMethodBar() { println "This is aSecondMethodBar." } 3
http://docs.groovy-lang.org/latest/html/documentation/ 114/502
1/6/2019 then the following GPath expression will get the names ofGroovy
(1) andLanguage
(3), but not (2) or (0):
Documentation
['aMethodBar', 'aSecondMethodBar'] == . .methods.name.grep(~/.*Bar/)
Expression Deconstruction
We can decompose the expression this.class.methods.name.grep(~/.*Bar/) to get an idea of how a GPath is evaluated:
this.class
property accessor, equivalent to this.getClass() in Java, yields a Class object.
this.class.methods
property accessor, equivalent to this.getClass().getMethods() , yields an array of Method objects.
this.class.methods.name
apply a property accessor on each element of an array and produce a list of the results.
this.class.methods.name.grep(…)
call method grep on each element of the list yielded by this.class.methods.name and produce a list of the results.
A sub-expression like this.class.methods yields an array because this is what calling
this.getClass().getMethods() in Java would produce. GPath expressions do not have a convention where a
s means a list or anything like that.
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:
< > methodNames = < >();
( method : .getClass().getMethods()) {
methodNames.add(method.getName());
}
methodNames;
Array access notation can also be used in a GPath expression where a collection is present :
'aSecondMethodBar' == . .methods.name.grep(~/.*Bar/).sort()[1]
array access are zero-based in GPath expressions
GPath for XML navigation
Here is an example with a XML document and various form of GPath expressions:
http://docs.groovy-lang.org/latest/html/documentation/ 115/502
1/6/2019 Groovy Language Documentation
xmlText = """
| <root>
| <level>
| <sublevel id='1'>
| <keyVal>
| <key>mykey</key>
| <value>value 123</value>
| </keyVal>
| </sublevel>
| <sublevel id='2'>
| <keyVal>
| <key>anotherKey</key>
| <value>42</value>
| </keyVal>
| <keyVal>
| <key>mykey</key>
| <value>fizzbuzz</value>
| </keyVal>
| </sublevel>
| </level>
| </root>
"""
root = ().parseText(xmlText.stripMargin())
root.level.size() == 1 1
root.level.sublevel.size() == 2 2
root.level.sublevel.findAll { it.@id == 1 }.size() == 1 3
root.level.sublevel[1].keyVal[0].key.text() == 'anotherKey' 4
1 There is one level node under root
2 There are two sublevel nodes under root/level
3 There is one element sublevel having an attribute id with value 1
4 Text value of key element of rst keyVal element of second sublevel element under root/level is 'anotherKey'
1.6.3. Promotion and coercion
Number promotion
The rules of number promotion are speci ed in the section on math operations.
Closure to type coercion
Assigning a closure to a SAM type
A SAM type is a type which de nes a single abstract method. This includes:
Functional interfaces
<T> {
accept(T obj)
}
Abstract classes with single abstract method
{
getName()
greet() {
println "Hello, $name"
}
}
Any closure can be converted into a SAM type using the as operator:
http://docs.groovy-lang.org/latest/html/documentation/ 116/502
1/6/2019 Groovy Language Documentation
filter = { it.contains 'G' }
filter.accept('Groovy') ==
greeter = { 'Groovy' }
greeter.greet()
However, the as Type expression is optional since Groovy 2.2.0. You can omit it and simply write:
filter = { it.contains 'G' }
filter.accept('Groovy') ==
greeter = { 'Groovy' }
greeter.greet()
which means you are also allowed to use method pointers, as shown in the following example:
doFilter( s) { s.contains('G') }
filter = .&doFilter
filter.accept('Groovy') ==
greeter = .&getVersion
greeter.greet()
Calling a method accepting a SAM type with a closure
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:
<T> <T> filter( <T> source, <T> predicate) {
source.findAll { predicate.accept(it) }
}
Then you can call it with a closure, without having to create an explicit implementation of the interface:
filter(['Java','Groovy'], { it.contains 'G'} ) == ['Groovy']
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:
filter(['Java','Groovy']) { it.contains 'G'} == ['Groovy']
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
of the parenthesis, improving the readability of your code.
Closure to arbitrary type coercion
In addition to SAM types, a closure can be coerced to any type and in particular interfaces. Let’s de ne the following interface:
{
foo()
bar()
}
You can coerce a closure into the interface using the as keyword:
impl = { println 'ok'; 123 }
This produces a class for which all methods are implemented using the closure:
impl.foo() == 123
impl.bar()
http://docs.groovy-lang.org/latest/html/documentation/ 117/502
1/6/2019 But it is also possible to coerce a closure to any class. For Groovy
example, we can replace
Language the interface that we de ned with class
Documentation
without changing the assertions:
{
foo() { 1 }
bar() { println 'bar' }
}
impl = { println 'ok'; 123 }
impl.foo() == 123
impl.bar()
Map to type coercion
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 :
map
map = [
i: 10,
hasNext: { map.i > 0 },
: { map.i-- },
]
iter = map
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:
X {
f()
g( n)
h( s, n)
}
x = [ f: {println "f called"} ] X
x.f() // method exists
x.g() // MissingMethodException here
x.g(5) // UnsupportedOperationException here
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
String to enum coercion
Groovy allows transparent String (or GString ) to enum values coercion. Imagine you de ne the following enum:
{
up,
down
}
then you can assign a string to the enum without having to use an explicit as coercion:
st = 'up'
st == .up
It is also possible to use a GString as the value:
http://docs.groovy-lang.org/latest/html/documentation/ 118/502
1/6/2019 Groovy Language Documentation
val = "up"
st = "${val}"
st == .up
However, this would throw a runtime error ( IllegalArgumentException ):
st = 'not an enum value'
Note that it is also possible to use implicit coercion in switch statements:
switchState( st) {
(st) {
'up':
.down // explicit constant
'down':
'up' // implicit coercion for return types
}
}
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:
switchState('up' ) == .down
switchState( .down) == .up
Custom type coercion
It is possible for a class to de ne 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 de ned two classes, Polar and Cartesian , like in the
following example:
{
r
phi
}
{
x
y
}
And that you want to convert from polar coordinates to cartesian coordinates. One way of doing this is to de ne the asType
method in the Polar class:
asType( target) {
( ==target) {
(x: r*cos(phi), y: r*sin(phi))
}
}
which allows you to use the as coercion operator:
sigma = 1E-16
polar = (r:1.0,phi:PI/2)
cartesian = polar
abs(cartesian.x-sigma) < sigma
Putting it all together, the Polar class looks like this:
http://docs.groovy-lang.org/latest/html/documentation/ 119/502
1/6/2019 Groovy Language Documentation
{
r
phi
asType( target) {
( ==target) {
(x: r*cos(phi), y: r*sin(phi))
}
}
}
but it is also possible to de ne asType outside of the Polar class, which can be practical if you want to de ne custom coercion
strategies for "closed" classes or classes for which you don’t own the source code, for example using a metaclass:
.metaClass.asType = { target ->
( ==target) {
(x: r*cos(phi), y: r*sin(phi))
}
}
Class literals vs variables and the as operator
Using the as keyword is only possible if you have a static reference to a class, like in the following code:
{
greet()
}
greeter = { println 'Hello, Groovy!' } // Greeter is known statically
greeter.greet()
But what if you get the class by re ection, for example by calling Class.forName ?
clazz = .forName('Greeter')
Trying to use the reference to the class with the as keyword would fail:
greeter = { println 'Hello, Groovy!' } clazz
// throws:
// unable to resolve class clazz
// @ line 9, column 40.
// greeter = { println 'Hello, Groovy!' } as clazz
It is failing because the as keyword only works with class literals. Instead, you need to call the asType method:
greeter = { println 'Hello, Groovy!' }.asType(clazz)
greeter.greet()
1.6.4. Optionality
Optional parentheses
Method calls can omit the parentheses if there is at least one parameter and there is no ambiguity:
println 'Hello World'
maximum = .max 5, 10
Parentheses are required for method calls without parameters or ambiguous method calls:
println()
println( .max(5, 10))
Optional semicolons
In Groovy semicolons at the end of the line can be omitted, if the line contains only a single statement.
http://docs.groovy-lang.org/latest/html/documentation/ 120/502
1/6/2019 This means that: Groovy Language Documentation
can be more idiomatically written as:
Multiple statements in a line require semicolons to separate them:
a = ; a
Optional return keyword
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.
add( a, b) {
a+b
}
add(1, 2) == 3
Can be shortened to:
add( a, b) {
a+b
}
add(1, 2) == 3
Optional public keyword
By default, Groovy classes and methods are public . Therefore this class:
{
toString() { "a server" }
}
is identical to this class:
{
toString() { "a server" }
}
1.6.5. The Groovy Truth
Groovy decides whether a expression is true or false by applying the rules given below.
Boolean expressions
True if the corresponding Boolean value is true .
Collections and Arrays
Non-empty Collections and arrays are true.
[1, 2, 3]
![]
Matchers
http://docs.groovy-lang.org/latest/html/documentation/ 121/502
1/6/2019 True if the Matcher has at least one match. Groovy Language Documentation
('a' =~ /a/)
!('a' =~ /b/)
Iterators and Enumerations
Iterators and Enumerations with further elements are coerced to true.
[0].iterator()
![].iterator()
v = [0]
enumeration = v.elements()
enumeration
enumeration.nextElement()
!enumeration
Maps
Non-empty Maps are evaluated to true.
['one' : 1]
![:]
Strings
Non-empty Strings, GStrings and CharSequences are coerced to true.
'a'
!''
nonEmpty = 'a'
"$nonEmpty"
empty = ''
!"$empty"
Numbers
Non-zero numbers are true.
1
3.5
!0
Object References
Non-null object references are coerced to true.
()
!
Customizing the truth with asBoolean() methods
In order to customize whether groovy evaluates your object to true or false implement the asBoolean() method:
{
name
asBoolean(){
name == 'green' ? :
}
}
Groovy will call this method to coerce your object to a boolean value, e.g.:
http://docs.groovy-lang.org/latest/html/documentation/ 122/502
1/6/2019 Groovy Language Documentation
(name: 'green')
! (name: 'red')
1.6.6. Typing
Optional 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:
aString = 'foo' 1
aString.toUpperCase() 2
1 foo is declared using an explicit type, String
2 we can call the toUpperCase method on a String
Groovy will let you write this instead:
aString = 'foo' 1
aString.toUpperCase() 2
1 foo is declared using def
2 we can still call the toUpperCase method, because the type of aString is resolved at runtime
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:
concat( a, b) {
a+b
}
concat('foo','bar') == 'foobar'
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:
concat( a, b) { 1
a+b
}
concat('foo','bar') == 'foobar' 2
concat(1,2) == 3 3
1 both the return type and the parameter types use def
2 it makes it possible to use the method with String
3 but also with int since the plus method is de ned
Using the def keyword here is recommended to describe the intent of a method which is supposed to work on
any type, but technically, we could use Object instead and the result would be the same: def is, in Groovy,
strictly equivalent to using Object .
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 modi er for the method, so that the compiler can make a di erence between a
method declaration and a method call, like illustrated in this example:
concat(a,b) { 1
a+b
}
concat('foo','bar') == 'foobar' 2
concat(1,2) == 3
http://docs.groovy-lang.org/latest/html/documentation/
3
123/502
1/6/2019 1 if we want to omit the return type, an explicit modi Groovy Language
er has to be set. Documentation
2 it is still possible to use the method with String
3 and also with int
Omitting types is in general considered a bad practice in method parameters or method return types for public
APIs. While using def in a local variable is not really a problem because the visibility of the variable is limited to
the method itself, while set on a method parameter, def will be converted to Object in the method signature,
making it di cult for users to know which is the expected type of the arguments. This means that you should limit
this to cases where you are explicitly relying on duck typing.
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:
{ 1
firstName
lastName
}
p = (firstName: 'Raymond', lastName: 'Devos') 2
p.formattedName == 'Raymond Devos' 3
1 the Person class only de nes two properties, firstName and lastName
2 we can create an instance of Person
3 and call a method named formattedName
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:
.metaClass.getFormattedName = { "$delegate.firstName $delegate.lastName" }
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.lang.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 nd 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
Activating type checking at compile time
The groovy.lang.TypeChecked annotation enabled type checking. It can be placed on a class:
http://docs.groovy-lang.org/latest/html/documentation/ 124/502
1/6/2019 Groovy Language Documentation
@groovy.transform.
{
sum( x, y) { x+y }
}
Or on a method:
{
@groovy.transform.
sum( x, y) { x+y }
}
In the rst case, all methods, properties, elds, 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.
Skipping sections
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) :
groovy.transform.
groovy.transform.
@TypeChecked 1
{
greeting() { 2
doGreet()
}
@TypeChecked( .SKIP) 3
doGreet() {
b = ()
b. . .name. . 4
b
}
}
s = ()
s.greeting() == 'Hello my name is John'
1 the GreetingService class is marked as type checked
2 so the greeting method is automatically type checked
3 but doGreet is marked with SKIP
4 the type checker doesn’t complain about missing properties here
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.
Type checking assignments
An object o of type A can be assigned to a variable of type T if and only if:
T equals A
now = ()
or T is one of String , boolean , Boolean or Class
http://docs.groovy-lang.org/latest/html/documentation/ 125/502
1/6/2019 Groovy Language Documentation
s = () // implicit call to toString
boxed = 'some string' // Groovy truth
prim = 'some string' // Groovy truth
clazz = 'java.lang.String' // class coercion
or o is null and T is not a primitive type
s = // passes
i = // fails
or T is an array and A is an array and the component type of A is assignable to the component type of T
[] i = [4] // passes
[] i = [4] // fails
or T is an array and A is a list and the component type of A is assignable to the component type of T
[] i = [1,2,3] // passes
[] i = [1,2, ()] // fails
or T is a superclass of A
list = () // passes
list = () // fails
or T is an interface implemented by A
list = () // passes
list = () // fails
or T or A are a primitive type and their boxed types are assignable
i = 0
bi = 1
x = (123)
d = (5f)
or T extends groovy.lang.Closure and A is a SAM-type (single abstract method type)
http://docs.groovy-lang.org/latest/html/documentation/ 126/502
1/6/2019 Groovy Language Documentation
r = { println 'Hello' }
{
doSomething()
}
sam = { 123 }
sam.doSomething() == 123
{
calc() { 2* value() }
value()
}
c = { 123 }
c.calc() == 246
or T and A derive from java.lang.Number and conform to the following table
Table 3. Number types (java.lang.XXX)
T A Examples
Double Any but BigDecimal or
d1 = 4d
BigInteger
d2 = 4f
d3 = 4l
d4 = 4i
d5 = ( ) 4
d6 = ( ) 4
Float Any type but BigDecimal,
f1 = 4f
BigInteger or Double
f2 = 4l
f3 = 4i
f4 = ( ) 4
f5 = ( ) 4
Long Any type but BigDecimal,
l1 = 4l
BigInteger, Double or Float
l2 = 4i
l3 = ( ) 4
l4 = ( ) 4
Integer Any type but BigDecimal,
i1 = 4i
BigInteger, Double, Float or
i2 = ( ) 4
Long i3 = ( ) 4
Short Any type but BigDecimal,
s1 = ( ) 4
BigInteger, Double, Float,
s2 = ( ) 4
Long or Integer
Byte Byte
b1 = ( ) 4
List and map constructors
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
http://docs.groovy-lang.org/latest/html/documentation/ 127/502
1/6/2019 the assignment is a variable declaration and A is a map literalLanguage
Groovy and T has a no-arg constructor and a property for each of the
Documentation
map keys
For example, instead of writing:
@groovy.transform.
{
firstName
lastName
}
classic = ('Ada','Lovelace')
You can use a "list constructor":
list = ['Ada','Lovelace']
or a "map constructor":
map = [firstName:'Ada', lastName:'Lovelace']
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
de ned. For example, the following will fail at compile time:
@groovy.transform.
{
firstName
lastName
}
map = [firstName:'Ada', lastName:'Lovelace', age: 24] 1
1 The type checker will throw an error No such property: age for class: Person at compile time
Method resolution
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:
T equals A
sum( x, y) {
x+y
}
sum(3,4) == 7
or T is a String and A is a GString
format( str) {
"Result: $str"
}
format("${3+4}") == "Result: 7"
or o is null and T is not a primitive type
http://docs.groovy-lang.org/latest/html/documentation/ 128/502
1/6/2019 Groovy Language Documentation
format( value) {
"Result: $value"
}
format(7) == "Result: 7"
format( ) // fails
or T is an array and A is an array and the component type of A is assignable to the component type of T
format( [] values) {
"Result: ${values.join(' ')}"
}
format(['a','b'] []) == "Result: a b"
format([1,2] []) // fails
or T is a superclass of A
format( list) {
list.join(',')
}
format( ()) // passes
format( list) {
list.join(',')
}
format( ()) // fails
or T is an interface implemented by A
format( list) {
list.join(',')
}
format( ()) // passes
format( list) {
'foo'
}
format( ()) // fails
or T or A are a primitive type and their boxed types are assignable
sum( x, y) {
x+y
}
sum(3, (4)) == 7
sum( (3), 4) == 7
sum( (3), (4)) == 7
sum( (3), 4) == 7
or T extends groovy.lang.Closure and A is a SAM-type (single abstract method type)
http://docs.groovy-lang.org/latest/html/documentation/ 129/502
1/6/2019 Groovy Language Documentation
{
doSomething()
}
twice( sam) { 2*sam.doSomething() }
twice { 123 } == 246
{
calc() { 2* value() }
value()
}
eightTimes( sam) { 4*sam.calc() }
eightTimes { 123 } == 984
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 di erence with
"normal" Groovy is illustrated in the following example:
{
doSomething() {
printLine 'Do something' 1
}
}
1 printLine is an error, but since we’re in a dynamic mode, the error is not caught at compile time
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
meta-class, but if you know you’re not in such a case, @TypeChecked comes handy:
@groovy.transform.
{
doSomething() {
printLine 'Do something' 1
}
}
1 printLine is this time a compile-time error
Just adding @TypeChecked will trigger compile time method resolution. The type checker will try to nd a method printLine
accepting a String on the MyService class, but cannot nd one. It will fail compilation with the following message:
Cannot find matching method MyService#printLine(java.lang.String)
It is important to understand the logic behind the type checker: it is a compile-time check, so by de nition,
the type checker is not aware of any kind of runtime metaprogramming that you do. This means that code
which is perfectly valid without @TypeChecked will not compile anymore if you activate type checking. This
is in particular true if you think of duck typing:
http://docs.groovy-lang.org/latest/html/documentation/ 130/502
1/6/2019 Groovy Language Documentation
{
quack() { 1
println 'Quack!'
}
}
{
quack() { 2
println 'Quack!'
}
}
@groovy.transform.
accept(quacker) {
quacker.quack() 3
}
accept( ()) 4
1 we de ne a Duck class which de nes a quack method
2 we de ne another QuackingBird class which also de nes a quack method
3 quacker is loosely typed, so since the method is @TypeChecked , we will obtain a compile-time error
4 even if in non type-checked Groovy, this would have passed
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 ow typing to reduce the gap
between type-checked and non type-checked Groovy.
Type inference
Principles
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:
message = 'Welcome to Groovy!' 1
println message.toUpperCase() 2
println message.upper() // compile time error 3
1 a variable is declared using the def keyword
2 calling toUpperCase is allowed by the type checker
3 calling upper will fail at compile time
The reason the call to toUpperCase works is because the type of message was inferred as being a String .
Variables vs elds in type inference
It is worth noting that although the compiler performs type inference on local variables, it does not perform any kind of type
inference on elds, always falling back to the declared type of a eld. To illustrate this, let’s take a look at this example:
http://docs.groovy-lang.org/latest/html/documentation/ 131/502
1/6/2019 Groovy Language Documentation
{
someUntypedField 1
someTypedField 2
someMethod() {
someUntypedField = '123' 3
someUntypedField = someUntypedField.toUpperCase() // compile-time error 4
someSafeMethod() {
someTypedField = '123' 5
someTypedField = someTypedField.toUpperCase() 6
someMethodUsingLocalVariable() {
localVariable = '123' 7
someUntypedField = localVariable.toUpperCase() 8
}
}
1 someUntypedField uses def as a declaration type
2 someTypedField uses String as a declaration type
3 we can assign anything to someUntypedField
4 yet calling toUpperCase fails at compile time because the eld is not typed properly
5 we can assign a String to a eld of type String
6 and this time toUpperCase is allowed
7 if we assign a String to a local variable
8 then calling toUpperCase is allowed on the local variable
Why such a di erence? The reason is thread safety. At compile time, we can’t make any guarantee about the type of a eld. Any
thread can access any eld at any time and between the moment a eld is assigned a variable of some type in a method and the
time is is used the line after, another thread may have changed the contents of the eld. 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 eld
is nal, the JVM makes no guarantee about it, so the type checker doesn’t behave di erently if a eld is nal or not.
This is one of the reasons why we recommend to use typed elds. While using def for local variables is perfectly
ne thanks to type inference, this is not the case for elds, which also belong to the public API of a class, hence the
type is important.
Collection literal type inference
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) and from..<to (exclusive)
The inferred type of a literal depends on the elements of the literal, as illustrated in the following table:
Literal Inferred type
java.util.List
list = []
java.util.List<String>
list = ['foo','bar']
java.util.List<GString> be careful, a GString is not a String !
list = ["${foo}","${bar}"]
http://docs.groovy-lang.org/latest/html/documentation/ 132/502
1/6/2019 Groovy Language Documentation
Literal Inferred type
java.util.LinkedHashMap
map = [:]
java.util.LinkedHashMap<String,String>
map1 = [someKey: 'someValue']
map2 = ['someKey': 'someValue']
java.util.LinkedHashMap<GString,String> be careful, the key is a
map = ["${someKey}":
GString !
'someValue']
groovy.lang.IntRange
intRange = (0..10)
groovy.lang.Range<String> : uses the type of the bounds to infer the
charRange = ('a'..'z')
component type of the range
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 di erent types, the type checker still performs type inference
of the components, but uses the notion of least upper bound.
Least upper bound
In Groovy, the least upper bound of two types A and B is de ned 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 .
{}
{}
{}
leastUpperBound( , ) == 1
leastUpperBound( , ) == 2
leastUpperBound( , ) == 3
leastUpperBound( , ) == 4
leastUpperBound( , ) == 5
leastUpperBound( , ) == 6
1 the LUB of String and String is String
2 the LUB of ArrayList and LinkedList is their common super type, AbstractList
3 the LUB of ArrayList and List is their only common interface, List
4 the LUB of two identical interfaces is the interface itself
5 the LUB of Bottom1 and Bottom2 is their superclass Top
6 the LUB of two types which have nothing in common is Object
http://docs.groovy-lang.org/latest/html/documentation/ 133/502
1/6/2019 In those examples, the LUB is always representable as a normal,
Groovy JVM supported,
Language type. But Groovy internally represents the LUB as
Documentation
a type which can be more complex, and that you wouldn’t be able to use to de ne 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 de ned 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:
{ greet() } 1
{ salute() } 2
A , { 3
greet() { println "Hello, I'm A!" }
salute() { println "Bye from A!" }
}
B , { 4
greet() { println "Hello, I'm B!" }
salute() { println "Bye from B!" }
() { println 'No way!' } 5
}
list = [ A(), B()] 6
list.each {
it.greet() 7
it.salute() 8
it. () 9
1 the Greeter interface de nes a single method, greet
2 the Salute interface de nes a single method, salute
3 class A implements both Greeter and Salute but there’s no explicit interface extending both
4 same for B
5 but B de nes an additional exit method
6 the type of list is inferred as "list of the LUB of A and `B`"
7 so it is possible to call greet which is de ned on both A and B through the Greeter interface
8 and it is possible to call salute which is de ned on both A and B through the Salute interface
9 yet calling exit is a compile time error because it doesn’t belong to the LUB of A and B (only de ned in B )
The error message will look like:
[Static type checking] - Cannot find matching method Greeter or Salute#exit()
which indicates that the exit method is neither de nes on Greeter nor Salute , which are the two interfaces de ned in the
least upper bound of A and B .
instanceof inference
In normal, non type checked, Groovy, you can write things like:
http://docs.groovy-lang.org/latest/html/documentation/ 134/502
1/6/2019 Groovy Language Documentation
{
greeting() { 'Hello' }
}
doSomething( o) {
(o ) { 1
println o.greeting() 2
}
}
doSomething( ())
1 guard the method call with an instanceof check
2 make the call
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:
(o ) {
. .println((( )o).greeting());
}
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
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 ow of the code, not just at initialization:
@groovy.transform.
flowTyping() {
o = 'foo' 1
o = o.toUpperCase() 2
o = 9d 3
o = .sqrt(o) 4
1 rst, o is declared using def and assigned a String
2 the compiler inferred that o is a String , so calling toUpperCase is allowed
3 o is reassigned with a double
4 calling Math.sqrt passes compilation because the compiler knows that at this point, o is a double
So the type checker is aware of the fact that the concrete type of a variable is di erent over time. In particular, if you replace the
last assignment with:
o = 9d
o = o.toUpperCase()
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:
@groovy.transform.
flowTypingWithExplicitType() {
list = ['a','b','c'] 1
list = list*.toUpperCase() 2
list = 'foo' 3
}
http://docs.groovy-lang.org/latest/html/documentation/ 135/502
1/6/2019 1 Groovy
list is declared as an unchecked List and assigned Language
a list literal ofDocumentation
`String`s
2 this line passes compilation because of ow typing: the type checker knows that list is at this point a List<String>
3 but you can’t assign a String to a List so this is a type checking error
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:
@groovy.transform.
flowTypingWithExplicitType() {
list = ['a','b','c'] 1
list.add(1) 2
1 list is inferred as List<String>
2 so adding an int to a List<String> is a compile-time error
Fixing this requires adding an explicit generic type to the declaration:
@groovy.transform.
flowTypingWithExplicitType() {
<? > list = [] 1
list.addAll(['a','b','c']) 2
list.add(1) 3
1 list declared as List<? extends Serializable> and initialized with an empty list
2 elements added to the list conform to the declaration type of the list
3 so adding an int to a List<? extends Serializable> is allowed
Flow typing has been introduced to reduce the di erence in semantics between classic and static Groovy. In particular, consider
the behavior of this code in Java:
compute( str) {
str.length();
}
compute( o) {
"Nope";
}
// ...
string = "Some string"; 1
result = compute(string); 2
.out.println(result); 3
1 o is declared as an Object and assigned a String
2 we call the compute method with o
3 and print the result
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:
compute( ) { .length() }
compute( o) { "Nope" }
o = 'string'
result = compute(o)
println result
http://docs.groovy-lang.org/latest/html/documentation/ 136/502
1/6/2019 But this time, it will return 6 , because the method which Groovy
is chosen is chosen
Language at runtime, based on the actual argument types. So
Documentation
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 ow typing. With
ow 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, ow 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.
Advanced type inference
A combination of ow 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:
{
methodFromTop() {}
}
{
methodFromBottom() {}
}
o
(someCondition) {
o = () 1
} {
o = () 2
}
o.methodFromTop() 3
o.methodFromBottom() // compilation error 4
1 if someCondition is true, o is assigned a Top
2 if someCondition is false, o is assigned a Bottom
3 calling methodFromTop is safe
4 but calling methodFromBottom is not, so it’s a compile time error
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
de ned outside of a closure, but used inside a closure, as in this example:
text = 'Hello, world!' 1
closure = {
println text 2
1 a variable named text is declared
2 text is used from inside a closure. It is a closure shared variable.
Groovy allows developers to use those variables without requiring them to be nal. This means that a closure shared variable can
be reassigned inside a closure:
http://docs.groovy-lang.org/latest/html/documentation/ 137/502
1/6/2019 Groovy Language Documentation
result
doSomething { it ->
result = "Result: $it"
}
result = result?.toUpperCase()
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 ow.
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:
{
methodFromTop() {}
}
{
methodFromBottom() {}
}
o = () 1
.start {
o = () 2
}
o.methodFromTop() 3
o.methodFromBottom() // compilation error 4
1 a closure-shared variable is rst assigned a Top
2 inside the closure, it is assigned a Bottom
3 methodFromTop is allowed
4 methodFromBottom is a compilation error
Here, it is clear that when methodFromBottom is called, there’s no guarantee, at compile-time or runtime that the type of o will
e ectively 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 uency on the
other side.
Return type inference
The rst 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:
@groovy.transform.
testClosureReturnTypeInference( arg) {
cl = { "Arg: $arg" } 1
val = cl() 2
val.length() 3
1 a closure is de ned, and it returns a string (more precisely a GString )
2 we call the closure and assign the result to a variable
3 the type checker inferred that the closure would return a string, so calling length() is allowed
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.
Closures vs methods
http://docs.groovy-lang.org/latest/html/documentation/ 138/502
1/6/2019 It’s worth noting that return type inference is only applicable
GroovytoLanguage
closures.Documentation
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 ow typing would actually think that a method returns
something, while in reality, it could return something else, like illustrated in the following example:
@TypeChecked
A {
compute() { 'some string' } 1
computeFully() {
compute().toUpperCase() 2
}
}
@TypeChecked
B A {
compute() { 123 } 3
1 class A de nes a method compute which e ectively returns a String
2 this will fail compilation because the return type of compute is def (aka Object )
3 class B extends A and rede nes compute , this type returning an int
As you can see, if the type checker relied on the inferred return type of a method, with ow 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
di erent 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 nal.
Parameter type inference
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:
{
name
age
}
inviteIf( p, < > predicate) { 1
(predicate.call(p)) {
// send invite
// ...
}
}
@groovy.transform.
failCompilation() {
p = (name: 'Gerard', age: 55)
inviteIf(p) { 2
it.age >= 18 // No such property: age 3
}
}
1 the inviteIf method accepts a Person and a Closure
2 we call it with a Person and a Closure
http://docs.groovy-lang.org/latest/html/documentation/ 139/502
1/6/2019 3 Groovy
yet it is not statically known as being a Person and Language
compilation Documentation
fails
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 .
Explicit closure parameters
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:
inviteIf(p) { it -> 1
it.age >= 18
}
1 the type of it needs to be declared explicitly
By explicitly declaring the type of the it variable, you can workaround the problem and make this code statically checked.
Parameters inferred from single-abstract method types
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 rst one, and easiest, is to replace the closure with a SAM type:
< > { apply( e) } 1
inviteIf( p, < > predicate) { 2
(predicate.apply(p)) {
// send invite
// ...
}
}
@groovy.transform.
passesCompilation() {
p = (name: 'Gerard', age: 55)
inviteIf(p) { 3
it.age >= 18 4
}
}
1 declare a SAM interface with an apply method
2 inviteIf now uses a Predicate<Person> instead of a Closure<Boolean>
3 there’s no need to declare the type of the it variable anymore
4 it.age compiles properly, the type of it is inferred from the Predicate#apply method signature
By using this technique, we leverage the automatic coercion of closures to SAM types feature of Groovy. The
question whether you should use a SAM type or a Closure really depends on what you need to do. In a lot of
cases, using a SAM interface is enough, especially if you consider functional interfaces as they are found in Java 8.
However, closures provide features that are not accessible to functional interfaces. In particular, closures can have
a delegate, and owner and can be manipulated as objects (for example, cloned, serialized, curried, …) before being
called. They can also support multiple signatures (polymorphism). So if you need that kind of manipulation, it is
preferable to switch to the most advanced type inference annotations which are described below.
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 insu cient to describe the types of the arguments.
The @ClosureParams annotation
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.
http://docs.groovy-lang.org/latest/html/documentation/ 140/502
1/6/2019 Let’s illustrate this by xing the original example, introducing the Language
Groovy @ClosureParams annotation:
Documentation
groovy.transform.stc.
groovy.transform.stc.
inviteIf( p, @ClosureParams( ) < > predicate) { 1
(predicate.call(p)) {
// send invite
// ...
}
}
inviteIf(p) { 2
it.age >= 18
}
1 the closure parameter is annotated with @ClosureParams
2 it’s not necessary to use an explicit type for it , which is inferred
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 rst parameter of the method. In this case, the rst parameter of the method is Person , so it indicates to the
type checker that the rst parameter of the closure is in fact a Person .
A second optional argument is named options. It’s semantics depend on the type hint class. Groovy comes with various bundled
type hints, illustrated in the table below:
Table 4. Prede ned type hints
Type hint Polymorphic? Description and examples
FirstParam No The rst (resp. second, third) parameter type of the method
SecondParam
ThirdParam groovy.transform.stc.
doSomething( str, @ClosureParams( )
c) {
c(str)
}
doSomething('foo') { println it.toUpperCase() }
groovy.transform.stc.
withHash( str, seed,
@ClosureParams( ) c) {
c(31*str.hashCode()+seed)
}
withHash('foo', ( ) .currentTimeMillis()) {
mod = it%2
}
groovy.transform.stc.
format( prefix, postfix, o,
@ClosureParams( ) c) {
"$prefix${c(o)}$postfix"
}
format('foo', 'bar', 'baz') {
it.toUpperCase()
} == 'fooBAZbar'
http://docs.groovy-lang.org/latest/html/documentation/ 141/502
1/6/2019 Groovy Language Documentation
Type hint Polymorphic? Description and examples
FirstParam.FirstGenericType No The rst generic type of the rst (resp. second, third) parameter of the
SecondParam.FirstGenericType method
ThirdParam.FirstGenericType
groovy.transform.stc.
<T> doSomething( <T> strings,
@ClosureParams( . ) c) {
strings.each {
c(it)
}
}
doSomething(['foo','bar']) { println it.toUpperCase() }
doSomething([1,2,3]) { println(2*it) }
Variants for SecondGenericType and ThirdGenericType exist for all
FirstParam , SecondParam and ThirdParam type hints.
SimpleType No A type hint for which the type of closure parameters comes from the
options string.
groovy.transform.stc.
doSomething(@ClosureParams(value= ,options=
['java.lang.String','int']) c) {
c('foo',3)
}
doSomething { str, len ->
str.length() == len
}
This type hint supports a single signature and each of the parameter is
speci ed as a value of the options array using a fully-quali ed type name
or a primitive type.
MapEntryOrKeyValue Yes A dedicated type hint for closures that either work on a Map.Entry single
parameter, or two parameters corresponding to the key and the value.
groovy.transform.stc.
<K,V> doSomething( <K,V> map,
@ClosureParams( ) c) {
// ...
}
doSomething([a: 'A']) { k,v ->
k.toUpperCase() == v.toUpperCase()
}
doSomething([abc: 3]) { e ->
e.key.length() == e.value
}
This type hint requires that the rst argument is a Map type, and infers
the closure parameter types from the map actual key/value types.
http://docs.groovy-lang.org/latest/html/documentation/ 142/502
1/6/2019 Groovy Language Documentation
Type hint Polymorphic? Description and examples
FromAbstractTypeMethods Yes Infers closure parameter types from the abstract method of some type. A
signature is inferred for each abstract method.
groovy.transform.stc.
{
firstSignature( x, y)
secondSignature( str)
}
doSomething(@ClosureParams(value= ,
options=["Foo"]) cl) {
// ...
}
doSomething { a, b -> a+b }
doSomething { s -> s.toUpperCase() }
If there are multiple signatures like in the example above, the type
checker will only be able to infer the types of the arguments if the arity of
each method is di erent. In the example above, firstSignature takes 2
arguments and secondSignature takes 1 argument, so the type checker
can infer the argument types based on the number of arguments. But see
the optional resolver class attribute discussed next.
http://docs.groovy-lang.org/latest/html/documentation/ 143/502
1/6/2019 Groovy Language Documentation
Type hint Polymorphic? Description and examples
FromString Yes Infers the closure parameter types from the options argument. The
options argument consists of an array of comma-separated non-
primitive types. Each element of the array corresponds to a single
signature, and each comma in an element separate parameters of the
signature. In short, this is the most generic type hint, and each string of
the options map is parsed as if it was a signature literal. While being
very powerful, this type hint must be avoided if you can because it
increases the compilation times due to the necessity of parsing the type
signatures.
A single signature for a closure accepting a String :
groovy.transform.stc.
doSomething(@ClosureParams(value= ,
options=["String","String,Integer"]) cl) {
// ...
}
doSomething { s -> s.toUpperCase() }
doSomething { s,i -> s.toUpperCase()*i }
A polymorphic closure, accepting either a String or a
String, Integer :
groovy.transform.stc.
doSomething(@ClosureParams(value= ,
options=["String","String,Integer"]) cl) {
// ...
}
doSomething { s -> s.toUpperCase() }
doSomething { s,i -> s.toUpperCase()*i }
A polymorphic closure, accepting either a T or a pair T,T :
groovy.transform.stc.
<T> doSomething(T e,
@ClosureParams(value= , options=["T","T,T"])
cl) {
// ...
}
doSomething('foo') { s -> s.toUpperCase() }
doSomething('foo') { s1,s2 -> s1.toUpperCase()
== s2.toUpperCase() }
Even though you use FirstParam , SecondParam or ThirdParam as a type hint, it doesn’t strictly mean that the
argument which will be passed to the closure will be the rst (resp. second, third) argument of the method call. It
only means that the type of the parameter of the closure will be the same as the type of the rst (resp. second,
third) argument of the method call.
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 con ictResolutionStrategy. 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 the a default type resolver which does nothing, and another
which selects the rst 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.
http://docs.groovy-lang.org/latest/html/documentation/ 144/502
1/6/2019 @DelegatesTo Groovy Language Documentation
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 speci c
section (core-domain-speci c-languages.html#section-delegatesto).
Static compilation
Dynamic vs static
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 with regards 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 ne, there is actually one issue with this: type checking of dynamic code, done at compile time, is by
de nition only correct if no runtime speci c behavior occurs. For example, the following program passes type checking:
{
compute( str) {
str.length()
}
compute( x) {
.valueOf(x)
}
}
@groovy.transform.
test() {
computer = ()
computer. {
compute(compute('foobar')) =='6'
}
}
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:
.metaClass.compute = { str -> () }
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 e ectively 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
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 :
http://docs.groovy-lang.org/latest/html/documentation/ 145/502
1/6/2019 Groovy Language Documentation
{
compute( str) {
str.length()
}
compute( x) {
.valueOf(x)
}
}
@groovy.transform.
test() {
computer = ()
computer. {
compute(compute('foobar')) =='6'
}
}
.metaClass.compute = { str -> () }
test()
This is the only di erence. 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.
Key bene ts
There are several bene ts 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 di erence 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.
Using the invokedynamic version of Groovy, which is accessible to people using JDK 7 and above, the performance
of the dynamic code should be very close to the performance of statically compiled code. Sometimes, it can even
be faster! There is only one way to determine which version you should choose: measuring. The reason is that
depending on your program and the JVM that you use, the performance can be signi cantly di erent. In
particular, the invokedynamic version of Groovy is very sensitive to the JVM version in use.
1.6.7. Type checking extensions
Writing a type checking extension
Towards a smarter type checker
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,… 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:
builder = ( )
builder.html {
head {
// ...
}
body {
p 'Hello, world!'
}
}
http://docs.groovy-lang.org/latest/html/documentation/ 146/502
1/6/2019 In the previous example, none of the html , head , body Groovy
or p methods exist.
Language However if you execute the code, it works because
Documentation
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 exible 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 he writes 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:
rst, 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 xed script signi cantly (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 bene t 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 extensions attribute
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:
@TypeChecked(extensions='/path/to/myextension.groovy')
foo() { ...}
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.
A DSL for type checking
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 speci cally 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:
beforeVisitMethod { methodNode ->
println "Entering ${methodNode.name}"
}
Imagine that you have this rover DSL at hand. A user would write:
robot.move 100
http://docs.groovy-lang.org/latest/html/documentation/ 147/502
1/6/2019 If you have a class de ned as such: Groovy Language Documentation
{
move( qt) { }
}
The script can be type checked before being executed using the following script:
config = ()
config.addCompilationCustomizers(
( ) 1
)
shell = (config) 2
robot = ()
shell.setVariable('robot', robot)
shell.evaluate(script) 3
1 a compiler con guration adds the @TypeChecked annotation to all classes
2 use the con guration in a GroovyShell
3 so that scripts compiled using the shell are compiled with @TypeChecked without the user having to add it explicitly
Using the compiler con guration above, we can apply @TypeChecked transparently to the script. In that case, it will fail at compile
time:
[Static type checking] - The variable [robot] is undeclared.
Now, we will slightly update the con guration to include the ``extensions'' parameter:
config.addCompilationCustomizers(
(
,
extensions:['robotextension.groovy'])
)
Then add the following to your classpath:
robotextension.groovy
unresolvedVariable { ->
('robot'== .name) {
storeType( , classNodeFor( ))
handled =
}
}
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
AST
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.
Events
The type checker sends the following events, to which an extension script can react:
Event name setup
Called When Called after the type checker nished initialization
http://docs.groovy-lang.org/latest/html/documentation/ 148/502
1/6/2019 Groovy Language Documentation
Arguments none
Usage
setup {
// this is called before anything
else
}
Can be used to perform setup of your extension
Event name nish
Called When Called after the type checker completed type checking
Arguments none
Usage
finish {
// this is after completion
// of all type checking
}
Can be used to perform additional checks after the type checker has nished its
job.
Event name unresolvedVariable
Called When Called when the type checker nds an unresolved variable
Arguments VariableExpression var
Usage
unresolvedVariable { ->
('people' == .name) {
storeType( , classNodeFor( ))
handled =
}
}
Allows the developer to help the type checker with user-injected
variables.
Event name unresolvedProperty
Called When Called when the type checker cannot nd a property on the receiver
Arguments PropertyExpression pexp
http://docs.groovy-lang.org/latest/html/documentation/ 149/502
1/6/2019 Groovy Language Documentation
Usage
unresolvedProperty { pexp ->
('longueur'==pexp.propertyAsString &&
getType(pexp.objectExpression)==classNodeFor( )) {
storeType(pexp,classNodeFor( ))
handled =
}
}
Allows the developer to handle "dynamic" properties
Event name unresolvedAttribute
Called When Called when the type checker cannot nd an attribute on the receiver
Arguments AttributeExpression aex
Usage
unresolvedAttribute { aex ->
(getType(aex.objectExpression)==classNodeFor( )) {
storeType(aex,classNodeFor( ))
handled =
}
}
Allows the developer to handle missing attributes
Event name beforeMethodCall
Called When Called before the type checker starts type checking a method call
Arguments MethodCall call
Usage
beforeMethodCall { call ->
(isMethodCallExpression(call)
&& call.methodAsString=='toUpperCase') {
addStaticTypeError('Not allowed',call)
handled =
}
}
Allows you to intercept method calls before the type checker performs its own checks. This is
useful if you want to replace the default type checking with a custom one for a limited scope.
In that case, you must set the handled ag to true, so that the type checker skips its own
checks.
Event name afterMethodCall
Called When Called once the type checker has nished type checking a method call
Arguments MethodCall call
http://docs.groovy-lang.org/latest/html/documentation/ 150/502
1/6/2019 Groovy Language Documentation
Usage
afterMethodCall { call ->
(getTargetMethod(call).name=='toUpperCase') {
addStaticTypeError('Not allowed',call)
handled =
}
}
Allow you to perform additional checks after the type checker has done its own checks. This is
in particular useful if you want to perform the standard type checking tests but also want to
ensure additional type safety, for example checking the arguments against each other.Note
that afterMethodCall is called even if you did beforeMethodCall and set the handled ag
to true.
Event name onMethodSelection
Called When Called by the type checker when it nds a method appropriate for a method call
Arguments Expression expr, MethodNode node
Usage
onMethodSelection { expr, node ->
(node.declaringClass.name == 'java.lang.String') {
// calling a method on 'String'
// let’s perform additional checks!
(++count>2) {
addStaticTypeError("You can use only 2 calls on String in
your source code",expr)
}
}
}
The type checker works by inferring argument types of a method call, then chooses a target
method. If it nds one that corresponds, then it triggers this event. It is for example interesting
if you want to react on a speci c method call, such as entering the scope of a method that
takes a closure as argument (as in builders).Please note that this event may be thrown for
various types of expressions, not only method calls (binary expressions for example).
Event name methodNotFound
Called When Called by the type checker when it fails to nd an appropriate method for a method call
Arguments ClassNode receiver, String name, ArgumentListExpression argList, ClassNode[]
argTypes,MethodCall call
http://docs.groovy-lang.org/latest/html/documentation/ 151/502
1/6/2019 Groovy Language Documentation
Usage
methodNotFound { receiver, name, argList, argTypes, call ->
// receiver is the inferred type of the receiver
// name is the name of the called method
// argList is the list of arguments the method was called with
// argTypes is the array of inferred types for each argument
// call is the method call for which we couldn’t find a target
method
(receiver==classNodeFor( )
&& name=='longueur'
&& argList.size()==0) {
handled =
newMethod('longueur', classNodeFor( ))
}
}
Unlike onMethodSelection , this event is sent when the type checker cannot nd a target
method for a method call (instance or static). It gives you the chance to intercept the error
before it is sent to the user, but also set the target method.For this, you need to return a list of
MethodNode . In most situations, you would either return: an empty list, meaning that you
didn’t nd a corresponding method, a list with exactly one element, saying that there’s no
doubt about the target methodIf you return more than one MethodNode, then the compiler
would throw an error to the user stating that the method call is ambiguous, listing the
possible methods.For convenience, if you want to return only one method, you are allowed to
return it directly instead of wrapping it into a list.
Event name beforeVisitMethod
Called When Called by the type checker before type checking a method body
Arguments MethodNode node
Usage
beforeVisitMethod { methodNode ->
// tell the type checker we will handle the body by ourselves
handled = methodNode.name.startsWith('skip')
}
The type checker will call this method before starting to type check a method body. If you
want, for example, to perform type checking by yourself instead of letting the type checker do
it, you have to set the handled ag to true.This event can also be used to help de ning the
scope of your extension (for example, applying it only if you are inside method foo).
Event name afterVisitMethod
Called When Called by the type checker after type checking a method body
Arguments MethodNode node
http://docs.groovy-lang.org/latest/html/documentation/ 152/502
1/6/2019 Groovy Language Documentation
Usage
afterVisitMethod { methodNode ->
scopeExit {
(methods>2) {
addStaticTypeError("Method ${methodNode.name} contains
more than 2 method calls", methodNode)
}
}
}
Gives you the opportunity to perform additional checks after a method body is visited by the
type checker. This is useful if you collect information, for example, and want to perform
additional checks once everything has been collected.
Event name beforeVisitClass
Called When Called by the type checker before type checking a class
Arguments ClassNode node
Usage
beforeVisitClass { classNode ->
name = classNode.nameWithoutPackage
(!(name[0] 'A'..'Z')) {
addStaticTypeError("Class '${name}' doesn't start with an
uppercase letter",classNode)
}
}
If a class is type checked, then before visiting the class, this event will be sent. It is also the
case for inner classes de ned inside a class annotated with @TypeChecked . It can help you
de ne the scope of your extension, or you can even totally replace the visit of the type checker
with a custom type checking implementation. For that, you would have to set the handled
ag to true .
Event name afterVisitClass
Called When Called by the type checker after having nished the visit of a type checked class
Arguments ClassNode node
Usage
afterVisitClass { classNode ->
name = classNode.nameWithoutPackage
(!(name[0] 'A'..'Z')) {
addStaticTypeError("Class '${name}' doesn't start with an
uppercase letter",classNode)
}
}
Called for every class being type checked after the type checker nished its work. This includes
classes annotated with @TypeChecked and any inner/anonymous class de ned in the same
class with is not skipped.
Event name incompatibleAssignment
http://docs.groovy-lang.org/latest/html/documentation/ 153/502
1/6/2019 Groovy Language Documentation
Called When Called when the type checker thinks that an assignment is incorrect, meaning that the right
hand side of an assignment is incompatible with the left hand side
Arguments ClassNode lhsType, ClassNode rhsType, Expression assignment
Usage
incompatibleAssignment { lhsType, rhsType, expr ->
(isBinaryExpression(expr) && isAssignment(expr.operation.type))
{
(lhsType==classNodeFor( ) &&
rhsType==classNodeFor( )) {
handled =
}
}
}
Gives the developer the ability to handle incorrect assignments. This is for example useful if a
class overrides setProperty , because in that case it is possible that assigning a variable of
one type to a property of another type is handled through that runtime mechanism. In that
case, you can help the type checker just by telling it that the assignment is valid (using
handled set to true ).
Event name ambiguousMethods
Called When Called when the type checker cannot choose between several candidate methods
Arguments List<MethodNode> methods, Expression origin
Usage
ambiguousMethods { methods, origin ->
// choose the method which has an Integer as parameter type
methods.find { it.parameters.any { it.type == classNodeFor( )
} }
}
Gives the developer the ability to handle incorrect assignments. This is for example useful if a
class overrides setProperty , because in that case it is possible that assigning a variable of
one type to a property of another type is handled through that runtime mechanism. In that
case, you can help the type checker just by telling it that the assignment is valid (using
handled set to true ).
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 su cient. 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
Support classes
The DSL relies on a support class called org.codehaus.groovy.transform.stc.GroovyTypeCheckingExtensionSupport
(http://docs.groovy-lang.org/2.5.5/html/gapi/index.html?
org/codehaus/groovy/transform/stc/GroovyTypeCheckingExtensionSupport.html) . This class itself
extends org.codehaus.groovy.transform.stc.TypeCheckingExtension (http://docs.groovy-lang.org/2.5.5/html/gapi/index.html?
org/codehaus/groovy/transform/stc/TypeCheckingExtension.html) . Those two classes de ne 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.
http://docs.groovy-lang.org/latest/html/documentation/ 154/502
1/6/2019 The extension script delegates to the org.codehaus.groovy.transform.stc.GroovyTypeCheckingExtensionSupport
Groovy Language Documentation
(http://docs.groovy-lang.org/2.5.5/html/gapi/index.html?
org/codehaus/groovy/transform/stc/GroovyTypeCheckingExtensionSupport.html) class, meaning that you have direct access to
the following variables:
context: the type checker context, of type org.codehaus.groovy.transform.stc.TypeCheckingContext (http://docs.groovy-
lang.org/2.5.5/html/gapi/index.html?org/codehaus/groovy/transform/stc/TypeCheckingContext.html)
typeCheckingVisitor: the type checker itself, a org.codehaus.groovy.transform.stc.StaticTypeCheckingVisitor
(http://docs.groovy-lang.org/2.5.5/html/gapi/index.html?org/codehaus/groovy/transform/stc/StaticTypeCheckingVisitor.html)
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.
Class nodes
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:
classNodeFor( )
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, … de ned on it. The rst 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 les 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 :
lookupClassNodeFor('Foo')
Helping the type checker
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 rst 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 ( ow typing)
if you want to access the origin type of a variable (or eld/parameter), then you must call the appropriate method on the AST
node
Throwing an error
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
isXXXExpression
http://docs.groovy-lang.org/latest/html/documentation/ 155/502
1/6/2019 It is often required to know the type of an AST node. For readability, the DSLDocumentation
Groovy Language provides a special isXXXExpression method that will
delegate to x instance of XXXExpression . For example, instead of writing:
(node ) {
...
}
which requires you to import the BinaryExpression class, you can just write:
(isBinaryExpression(node)) {
...
}
Virtual methods
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 nders. You can have a method call consisting of a
method named ndByName(…). As there’s no ndByName method de ned 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 de ned 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 de ne 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.
newMethod(name) {
// each time getReturnType on this method node will be called, this closure will be called!
println 'Type checker called me!'
lookupClassNodeFor( ) // return type
}
Should you need more than the name and return type, you can always create a new MethodNode by yourself.
Scoping
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 de ne 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:
point a(1,1)
line a,b // b is referenced afterwards!
point b(5,2)
Say for example that you want to handle a builder:
builder.foo {
bar
baz(bar)
}
http://docs.groovy-lang.org/latest/html/documentation/ 156/502
1/6/2019 Your extension, then, should only be active once you’ve entered
Groovythe foo method,
Language and inactive outside of this scope. But you
Documentation
could have complex situations like multiple builders in the same le or embedded builders (builders in builders). While you should
not try to x all this from start (you must accept limitations to type checking), the type checker does o er 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 (http://docs.groovy-
lang.org/2.5.5/html/gapi/index.html?
org/codehaus/groovy/transform/stc/GroovyTypeCheckingExtensionSupport/TypeCheckingScope.html)), 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:
scope = newScope()
scope.secondPassChecks = []
//...
scope.secondPassChecks << { println 'executed later' }
// ...
scopeExit {
secondPassChecks*.run() // execute deferred checks
}
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:
newScope {
secondPassChecks = []
}
At anytime in the DSL, you can access the current scope using getCurrentScope() or more simply currentScope :
//...
currentScope.secondPassChecks << { println 'executed later' }
// ...
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
Other useful methods
For the complete list of helper methods, please refer to
the org.codehaus.groovy.transform.stc.GroovyTypeCheckingExtensionSupport (http://docs.groovy-
lang.org/2.5.5/html/gapi/index.html?org/codehaus/groovy/transform/stc/GroovyTypeCheckingExtensionSupport.html) and
org.codehaus.groovy.transform.stc.TypeCheckingExtension (http://docs.groovy-lang.org/2.5.5/html/gapi/index.html?
org/codehaus/groovy/transform/stc/TypeCheckingExtension.html) 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 de ned 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
http://docs.groovy-lang.org/latest/html/documentation/ 157/502
1/6/2019 isAnnotatedBy : takes an AST node and a Class (or ClassNode), and tellsDocumentation
Groovy Language 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 speci c type (you can also specify the delegation strategy)
Advanced type checking extensions
Precompiled type checking extensions
All the examples above use type checking scripts. They are found in source form in classpath, meaning that:
a Groovy source le, corresponding to the type checking extension, is available on compilation classpath
this le is compiled by the Groovy compiler for each source unit being compiled (often, a source unit corresponds to a single
le)
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 le 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:
org.codehaus.groovy.transform.stc.
. { 1
@Override
run() { 2
unresolvedVariable { ->
('robot'== .name) {
storeType( , classNodeFor( )) 3
handled =
}
}
}
}
1 extending the TypeCheckingDSL class is the easiest
2 then the extension code needs to go inside the run method
3 and you can use the very same events as an extension written in source form
Setting up the extension is very similar to using a source form extension:
config.addCompilationCustomizers(
(
,
extensions:['typing.PrecompiledExtension'])
)
The di erence is that instead of using a path in classpath, you just specify the fully quali ed class name of the precompiled
extension.
In case you really want to write an extension in Java, then you will not bene t from the type checking extension DSL. The extension
above can be rewritten in Java this way:
http://docs.groovy-lang.org/latest/html/documentation/ 158/502
1/6/2019 Groovy Language Documentation
org.codehaus.groovy.ast. ;
org.codehaus.groovy.ast.expr. ;
org.codehaus.groovy.transform.stc. ;
org.codehaus.groovy.transform.stc. ;
{ 1
( typeCheckingVisitor) {
(typeCheckingVisitor);
}
@Override
handleUnresolvedVariableExpression( vexp) { 2
("robot".equals(vexp.getName())) {
storeType(vexp, .make( . ));
setHandled( );
;
}
;
}
1 extend the AbstractTypeCheckingExtension class
2 then override the handleXXX methods as required
Using @Grab in a type checking extension
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 signi cantly
(at least, the rst time it grabs the dependencies).
Sharing or packaging type checking extensions
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 le that
would be added to classpath.
Global type checking extensions
While you can con gure 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 and @CompileStatic
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 su cient 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 rst 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 allow 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.
http://docs.groovy-lang.org/latest/html/documentation/ 159/502
1/6/2019 Mixed mode compilation Groovy Language Documentation
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 o ers 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:
robot.move 100
And let’s try to activate our type checking extension using @CompileStatic instead of @TypeChecked :
config = ()
config.addCompilationCustomizers(
(
, 1
extensions:['robotextension.groovy']) 2
)
shell = (config)
robot = ()
shell.setVariable('robot', robot)
shell.evaluate(script)
1 Apply @CompileStatic transparently
2 Activate the type checking extension
The script will run ne 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:
move 100
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 (http://docs.groovy-lang.org/2.5.5/html/gapi/index.html?
groovy/util/DelegatingScript.html):
config = ()
config.scriptBaseClass = 'groovy.util.DelegatingScript' 1
shell = (config)
runner = shell.parse(script) 2
runner.setDelegate( ()) 3
runner.run() 4
1 we con gure the compiler to use a DelegatingScript as the base class
2 the script source needs to be parsed and will return an instance of DelegatingScript
3 we can then call setDelegate to use a Robot as the delegate of the script
4 then execute the script. move will be directly executed on the delegate
If we want this to pass with @CompileStatic , we have to use a type checking extension, so let’s update our con guration:
http://docs.groovy-lang.org/latest/html/documentation/ 160/502
1/6/2019 Groovy Language Documentation
config.addCompilationCustomizers(
(
, 1
extensions:['robotextension2.groovy']) 2
1 apply @CompileStatic transparently
2 use an alternate type checking extension meant to recognize the call to move
Then in the previous section we have learnt how to deal with unrecognized method calls, so we are able to write this extension:
robotextension2.groovy
methodNotFound { receiver, name, argList, argTypes, call ->
(isMethodCallExpression(call) 1
&& call.implicitThis 2
&& 'move'==name 3
&& argTypes.length==1 4
&& argTypes[0] == classNodeFor( ) 5
) {
handled = 6
newMethod('move', classNodeFor( )) 7
}
}
1 if the call is a method call (not a static method call)
2 that this call is made on "implicit this" (no explicit this. )
3 that the method being called is move
4 and that the call is done with a single argument
5 and that argument is of type int
6 then tell the type checker that the call is valid
7 and that the return type of the call is Robot
If you try to execute this code, then you could be surprised that it actually fails at runtime:
java.lang.NoSuchMethodError: java.lang.Object.move()Ltyping/Robot;
The reason is very simple: while the type checking extension is su cient 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:
robotextension3.groovy
methodNotFound { receiver, name, argList, argTypes, call ->
(isMethodCallExpression(call)
&& call.implicitThis
&& 'move'==name
&& argTypes.length==1
&& argTypes[0] == classNodeFor( )
) {
makeDynamic(call, classNodeFor( )) 1
}
}
1 tell the compiler that the call should be make dynamic
The makeDynamic call does 3 things:
it returns a virtual method just like newMethod
http://docs.groovy-lang.org/latest/html/documentation/ 161/502
1/6/2019 automatically sets the handled ag to true for you Groovy Language Documentation
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 fallback
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.
Transforming the AST in an extension
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 e ectively a di erence 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
The type checking phase is the last phase running in the compiler before bytecode generation. All other AST
transformations run before that and the compiler does a very good job at " xing" incorrect AST generated before
the type checking phase. As soon as you perform a transformation during type checking, for example directly in a
type checking extension, then you have to do all this work of generating a 100% compiler compliant abstract
syntax tree by yourself, which can easily become complex. That’s why we do not recommend to go that way if you
are beginning with type checking extensions and AST transformations.
Examples
Examples of real life type checking extensions are easy to nd. You can download the source code for Groovy and take a look at
the TypeCheckingExtensionsTest
(https://github.com/apache/groovy/blob/master/src/test/groovy/transform/stc/TypeCheckingExtensionsTest.groovy) class which is
linked to various extension scripts (https://github.com/apache/groovy/tree/master/src/test-resources/groovy/transform/stc).
An example of a complex type checking extension can be found in the Markup Template Engine (markup-template-engine.html)
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 (https://github.com/apache/groovy/tree/master/subprojects/groovy-
templates/src/main/groovy/groovy/text/markup).
http://docs.groovy-lang.org/latest/html/documentation/ 162/502
1/6/2019 2. Tools Groovy Language Documentation
2.1. Running Groovy from the commandline
2.1.1. groovy, the Groovy command
groovy invokes the Groovy command line processor. It allows you to run inline Groovy expressions, and scripts, tests or
application within groovy les. It plays a similar role to java in the Java world but handles inline scripts and rather than invoking
class les, 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:
> groovy MyScript.groovy
The .groovy part is optional. The groovy command supports a number of command line switches:
Short version Long version Description Example
-a --autosplit <splitPattern> split lines using splitPattern
(default '\s') using implicit
'split' variable
-b --basescript <class> Base class name for scripts
(must derive from Script)
-c --encoding <charset> specify the encoding of the
les
-cp <path> -classpath <path> Specify the compilation groovy -cp lib/dep.jar
--classpath <path> classpath. Must be the rst MyScript
argument.
--con gscript <path> Advanced compiler groovy --con gscript
con guration script con g/con g.groovy
src/Person.groovy
-D --de ne <name=value> de ne a system property
-d --debug debug mode will print out full
stack traces
--disableopt <optlist> disables one or all
optimization elements.
optlist can be a comma
separated list with the
elements:
all (disables all
optimizations),
int (disable any int based
optimizations)
-e <script> specify an inline command groovy -e "println new Date()"
line script
-pa --parameters Generates metadata for groovy --parameters
re ection on method Person.groovy
parameter names on JDK 8
and above. Defaults to false.
http://docs.groovy-lang.org/latest/html/documentation/ 163/502
1/6/2019 Groovy Language Documentation
Short version Long version Description Example
-h --help Displays usage information groovy --help
for the command line groovy
command
-i <extension> modify les in place; create
backup if extension is given
(e.g. '.bak')
--indy Enables invokedynamic groovy --indy Person.groovy
support. Requires Java 7+
-l <port> listen on a port and process
inbound lines (default: 1960)
-n process les line by line using
implicit 'line' variable
-p process les line by line and
print result (see also -n)
-v --version display the Groovy and JVM groovy -v
versions
-pa --parameters Generates metadata for groovy --parameters
re ection on method Person.groovy
parameter names on JDK 8
and above. Defaults to false.
2.2. Compiling Groovy
2.2.1. groovyc, the Groovy compiler
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:
groovyc MyClass.groovy
This will produce a MyClass.class le (as well as other .class les depending on the contents of the source). groovyc supports
a number of command line switches:
Short version Long version Description Example
-cp -classpath, --classpath Specify the compilation groovyc -cp lib/dep.jar
classpath. Must be the rst MyClass.groovy
argument.
--sourcepath Directory where to nd
source les. Not used
anymore. Specifying this
parameter will have no
e ect.
--temp Temporary directory for the
compiler
--encoding Encoding of the source les groovyc --encoding utf-8
script.groovy
@arg le Read options and source les groovyc @conf/args
from speci ed le.
http://docs.groovy-lang.org/latest/html/documentation/ 164/502
1/6/2019 Groovy Language Documentation
Short version Long version Description Example
--help Displays help for the groovyc --help
command line groovyc tool
-d Specify where to place groovyc -d target
generated class les. Person.groovy
-v --version Displays the compiler version groovyc -v
-e --exception Displays the stack trace in groovyc -e script.groovy
case of compilation error
-j --jointCompilation* Enables joint compilation groovyc -j A.groovy B.java
-b --basescript Base class name for scripts
(must derive from Script)
-indy --indy Enables invokedynamic groovyc --indy Person.groovy
support. Requires Java 7+
--con gscript Advanced compiler groovyc --con gscript
con guration script con g/con g.groovy
src/Person.groovy
-Jproperty=value Properties to be passed to groovyc -j -Jtarget=1.6 -
javac if joint compilation is Jsource=1.6 A.groovy B.java
enabled
-F ag Flags to be passed to javac groovyc -j -Fnowarn A.groovy
if joint compilation is enabled B.java
-pa --parameters Generates metadata for groovyc --parameters
re ection on method Person.groovy
parameter names. Requires
Java 8+.
@arg le Read options and source les groovyc @conf/args
from speci ed le.
Notes: * for a full description of joint compilation, see the joint compilation section.
2.2.2. Ant task
<groovyc>
Description
Compiles Groovy source les and, if joint compilation option is used, Java source les.
Required taskdef
Assuming all the groovy jars you need are in my.classpath (this will be groovy-VERSION.jar , groovy-ant-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 groovyc task being invoked.
name="groovyc"
classname="org.codehaus.groovy.ant.Groovyc"
classpathref="my.classpath"
<groovyc> Attributes
Attribute Description Required
http://docs.groovy-lang.org/latest/html/documentation/ 165/502
1/6/2019 Groovy Language Documentation
Attribute Description Required
srcdir Location of the Groovy (and possibly Yes
Java) source les.
destdir Location to store the class les. Yes
classpath The classpath to use. No
classpathref The classpath to use given as a path No
references.
sourcepath The sourcepath to use. No
sourcepathref The sourcepath to use given as a path No
reference.
encoding Encoding of source les. No
verbose Asks the compiler for verbose output; No
defaults to no.
includeAntRuntime Whether to include the Ant run-time No
libraries in the classpath; defaults to
yes.
includeJavaRuntime Whether to include the default run-time No
libraries from the executing VM in the
classpath; defaults to no.
includeDestClasses This property controls whether to No
include the destination classes directory
in the classpath given to the compiler.
The default value is "true".
fork Whether to execute groovyc using a No
spawned instance of the JVM; defaults
to no.
memoryInitialSize The initial size of the memory for the No
underlying VM, if using fork mode;
ignored otherwise. Defaults to the
standard VM memory setting.
(Examples: 83886080, 81920k, or 80m)
memoryMaximumSize The maximum size of the memory for No
the underlying VM, if using fork mode;
ignored otherwise. Defaults to the
standard VM memory setting.
(Examples: 83886080, 81920k, or 80m)
failonerror Indicates whether compilation errors No
will fail the build; defaults to true.
proceed Inverse alias for failonerror. No
list les Indicates whether the source les to be No
compiled will be listed; defaults to no.
errorProperty The property to set on compilation No
failure. This property will be set if the
compilation fails.
http://docs.groovy-lang.org/latest/html/documentation/ 166/502
1/6/2019 Groovy Language Documentation
Attribute Description Required
stacktrace if true each compile error message will No
contain a stacktrace
indy Enable compilation with the ``invoke No
dynamic'' support when using Groovy
2.0 and beyond and running on JDK 7
scriptBaseClass Sets the base class for Groovy scripts No
stubdir Set the stub directory into which the No
Java source stub les should be
generated. The directory need not exist
and will not be deleted automatically -
though its contents will be cleared
unless 'keepStubs' is true. Ignored when
forked.
keepStubs Set the keepStubs ag. Defaults to false. No
Set to true for debugging. Ignored when
forked.
forceLookupUnnamedFiles The Groovyc Ant task is frequently used No
in the context of a build system that
knows the complete list of source les
to be compiled. In such a context, it is
wasteful for the Groovy compiler to go
searching the classpath when looking
for source les and hence by default the
Groovyc Ant task calls the compiler in a
special mode with such searching
turned o . If you wish the compiler to
search for source les then you need to
set this ag to true. Defaults to false.
con gscript Set the con guration le used to No
customize the compilation
con guration.
parameters Generates metadata for re ection on No
method parameter names on JDK 8 and
above. Defaults to false.
targetBytecode Sets the bytecode compatibility level. No
javahome Sets the java.home value to use, No
default is the current JDK’s home.
executable Sets the name of the java executable to No
use when invoking the compiler in
forked mode, ignored otherwise.
scriptExtension Set the extension to use when searching No
for Groovy source les. Accepts
extensions in the form *.groovy, .groovy
or groovy.
errorProperty The property to set on compilation No
failure. This property will be set if the
compilation fails.
http://docs.groovy-lang.org/latest/html/documentation/ 167/502
1/6/2019 Groovy Language Documentation
Attribute Description Required
updatedProperty The property to set on compilation No
success. This property will not be set if
the compilation fails, or if there are no
les to compile.
errorProperty The property to set on compilation No
failure. This property will be set if the
compilation fails.
Example:
srcdir="src" destdir="target/classes"
<groovyc> Nested Elements
element kind Required Replaces Attribute
src a path structure Yes (unless srcdir is used) srcdir
classpath a path structure No classpath
javac javac task No jointCompilationOptions
Notes:
For path structures see for example http://ant.apache.org/manual/using.html#path
(http://ant.apache.org/manual/using.html#path)
For usages of the javac task see https://ant.apache.org/manual/Tasks/javac.html
(https://ant.apache.org/manual/Tasks/javac.html)
The nested javac task behaves more or less as documented for the top-level javac task. srcdir , destdir , classpath ,
encoding for the nested javac task are taken from the enclosing groovyc task. If these attributes are speci ed then they
are added, they do not replace. In fact, you should not attempt to overwrite the destination. Other attributes and nested
elements are una ected, for example fork , memoryMaximumSize , etc. may be used freely.
Joint Compilation
Joint compilation is enabled by using an embedded javac element, as shown in the following example:
srcdir="${testSourceDirectory}" destdir="${testClassesDirectory}"
path="${mainClassesDirectory}"
path="${testClassesDirectory}"
refid="testPath"
source="1.7" target="1.7" debug="on"
It is rare to specify srcdir and destdir , the nested javac task is provided with the srcdir and destdir values from the
enclosing groovyc task, and it is invariable the right thing to do just to leave this as is. To restate: the javac task gets the
srcdir , destdir and classpath from the enclosing groovyc task.
More details about joint compilation can be found in the joint compilation section.
2.2.3. Gant
Gant (https://github.com/Gant/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.
2.2.4. Gradle
http://docs.groovy-lang.org/latest/html/documentation/ 168/502
1/6/2019 Gradle (http://www.gradle.org/) is a build tool that allows Groovy
you to leverage
Languagethe exibility of Ant (http://ant.apache.org/), while
Documentation
keeping the simplicity of convention over con guration that tools like Maven (http://maven.apache.org/) o er. Builds are speci ed
using a Groovy DSL, which o ers great exibility and succinctness.
2.2.5. Maven integration
There are several approaches to compiling Groovy code in your Maven projects. GMavenPlus is the most exible and feature rich,
but like most Groovy compiler tools, it can have di culties 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
(https://github.com/groovy/groovy-eclipse/wiki/Groovy-Eclipse-Maven-plugin#why-another-groovy-compiler-for-maven-what-
about-gmaven) for a deeper discussion of the bene ts 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 di erent to the JRE, or the JUnit runtime.
http://docs.groovy-lang.org/latest/html/documentation/ 169/502
1/6/2019 Groovy Language Documentation
xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-
instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-
v4_0_0.xsd"
4.0.0
com.mycomp.MyGroovy
MyGroovy
jar
1.0-SNAPSHOT
Maven Example building a Groovy project
junit
junit
3.8.1
test
org.codehaus.groovy
groovy-all
2.5.0
pom <!-- required JUST since Groovy 2.5.0 -->
maven-antrun-plugin
compile
compile
dir="${basedir}/src/main/groovy"
name="groovyc"
classname="org.codehaus.groovy.ant.Groovyc"
refid="maven.compile.classpath"
dir="${project.build.outputDirectory}"
destdir="${project.build.outputDirectory}"
srcdir="${basedir}/src/main/groovy/" listfiles="true"
refid="maven.compile.classpath"
run
test-compile
test-compile
dir="${basedir}/src/test/groovy"
name="groovyc"
classname="org.codehaus.groovy.ant.Groovyc"
refid="maven.test.classpath"
dir="${project.build.testOutputDirectory}"
destdir="${project.build.testOutputDirectory}"
srcdir="${basedir}/src/test/groovy/" listfiles="true"
refid="maven.test.classpath"
http://docs.groovy-lang.org/latest/html/documentation/ 170/502
1/6/2019 Groovy Language Documentation
run
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 de ning 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 nally 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 of the unit tests pass. For more detail on Maven
build phases consult the Maven2 documentation.
GMaven and GMavenPlus
GMaven
GMaven (https://github.com/groovy/gmaven) is the original Maven plugin for Groovy, supporting both compiling and scripting
Groovy.
Important:
You should be aware that GMaven is not supported anymore and can have di culties 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
GMavenPlus (https://github.com/groovy/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 (http://maven.apache.org/plugin-tools/maven-plugin-
tools-java/index.html) 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 con guration scripts.
GMaven 2
Unlike the name might seem to suggest, GMaven 2 (http://groovy.github.io/gmaven/) 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.
The Groovy Eclipse Maven plugin
Groovy-Eclipse (https://github.com/groovy/groovy-eclipse/wiki/Groovy-Eclipse-Maven-plugin) 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.
2.2.6. Joint compilation
Joint compilation means that the Groovy compiler will parse the Groovy source les, 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 les without constraint.
Joint compilation can be enabled using the -j ag with the command-line compiler, or using 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 les with the Groovy compiler, the
Java source les 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 semantics would be di erent.
2.2.7. Android support
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 speci c JAR les for Android, which
have a classi er of grooid . In order to make things easier, a Gradle plugin (https://github.com/groovy/groovy-android-gradle-
plugin) adds support for the Groovy language in the Android Gradle toolchain.
http://docs.groovy-lang.org/latest/html/documentation/ 171/502
1/6/2019 The plugin can be applied like this: Groovy Language Documentation
buildscript {
repositories {
jcenter()
}
dependencies {
classpath 'com.android.tools.build:gradle:2.1.2'
classpath 'org.codehaus.groovy:groovy-android-gradle-plugin:1.0.0'
}
}
apply plugin: 'groovyx.android'
Then you will need to add a dependency on the grooid version of the Groovy compiler:
dependencies {
compile 'org.codehaus.groovy:groovy:2.4.7:grooid'
}
Note that if a Groovy jar does not provide a grooid classi er alternative, then it means that the jar is directly compatible with
Android. In that case, you can add the dependency directly like this:
dependencies {
compile 'org.codehaus.groovy:groovy:2.4.7:grooid' // requires the grooid classifier
compile ('org.codehaus.groovy:groovy-json:2.4.7') { // no grooid version available
transitive = // so do not depend on non-grooid
version
}
}
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 (https://github.com/groovy/groovy-android-gradle-plugin) in order to nd 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, de ne
classes and run simple experiments.
Features
No need for go command to execute bu er.
Rich cross-platform edit-line editing, history and completion thanks to JLine2 (https://github.com/jline/jline2).
ANSI colors (prompt, exception traces, etc).
Simple, yet robust, command system with online help, user alias support and more.
User pro le support
Command-line Options and Arguments
The shell supports several options to control verbosity, ANSI coloring and other features.
http://docs.groovy-lang.org/latest/html/documentation/ 172/502
1/6/2019 Groovy Language Documentation
./bin/groovysh --help
: groovysh [options] [...]
, aka groovysh, a command-line application which allows easy
access to evaluate expressions, define classes run simple
experiments.
-C, --color[=<FLAG>] disable of ANSI colors
-cp, -classpath, --classpath
to find the files - must be first
argument
-d, --debug debug output
-D, --define=<name=value>
a system
-e, --evaluate=<CODE> the code first starting interactive session
-h, --help help message
-pa, --parameters metadata reflection on method parameter names
(jdk8+ only)
-q, --quiet superfluous output
-T, --terminal=<TYPE> the terminal TYPE to
-v, --verbose verbose output
-V, --version the version
Evaluating Expressions
Simple Expressions
println "Hello"
Evaluation Result
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 de nitions) may be de ned over several lines. When the shell detects that it
has a complete expression it will compile and evaluate it.
De ne a Class
{
bar() {
println "baz"
}
}
Use the Class
foo = ()
foo.bar()
Variables
Shell variables are all untyped (i.e. no def or other type information).
This will set a shell variable:
foo = "bar"
But, this will evaluate a local variable and will not be saved to the shell’s environment:
foo = "bar"
This behavior can be changed by activating interpreter mode.
Functions
Functions can be de ned in the shell, and will be saved for later use.
http://docs.groovy-lang.org/latest/html/documentation/ 173/502
1/6/2019 De ning a function is easy: Groovy Language Documentation
groovy:000> hello(name) {
groovy:001> println("Hello $name")
groovy:002> }
And then using it is as one might expect:
hello("Jason")
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.
Commands
The shell has a number of di erent 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 prede ned system
aliases. Users may also create their own aliases.
Recognized Commands
help
Display the list of commands (and aliases) or the help text for speci c command.
The Command List
groovy:000> :help
For information about Groovy, visit:
http://groovy-lang.org
Available commands:
:help (:h ) Display this help message
? (:? ) Alias to: :help
:exit (:x ) Exit the shell
:quit (:q ) Alias to: :exit
import (:i ) Import a class into the namespace
:display (:d ) Display the current buffer
:clear (:c ) Clear the buffer and reset the prompt counter
:show (:S ) Show variables, classes or imports
:inspect (:n ) Inspect a variable or the last result with the GUI object browser
:purge (:p ) Purge variables, classes, imports or preferences
:edit (:e ) Edit the current buffer
:load (:l ) Load a file or URL into the buffer
. (:. ) Alias to: :load
:save (:s ) Save the current buffer to a file
:record (:r ) Record the current session to a file
:history (:H ) Display, manage and recall edit-line history
:alias (:a ) Create an alias
:set (:= ) Set (or list) preferences
:grab (:g ) Add a dependency to the shell environment
:register (:rc) Register a new command with the shell
:doc (:D ) Open a browser window displaying the doc for the argument
For help on a specific command type:
:help <command>
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:
http://docs.groovy-lang.org/latest/html/documentation/ 174/502
1/6/2019 Groovy Language Documentation
groovy:000> :help :help
usage: :help [<command>]
Display the list of commands or the help text for <command>.
exit
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.
import
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
Grab a dependency (Maven, Ivy, etc.) from Internet sources or cache, and add it to the Groovy Shell environment.
groovy:000> :grab 'com.google.guava:guava:19.0'
groovy:000> import com.google.common.collect.BiMap
===> com.google.common.collect.BiMap
This command can be given at any time to add new dependencies.
display
Display the contents of the current bu er.
This only displays the bu er of an incomplete expression. Once the expression is complete, the bu er is rest. The prompt will
update to show the size of the current bu er as well.
Example
groovy:000> class Foo {
groovy:001> def bar
groovy:002> def baz() {
groovy:003> :display
001> class Foo {
002> def bar
003> def baz() {
clear
Clears the current bu er, resetting the prompt counter to 000. Can be used to recover from compilation errors.
show
Show variables, classes or preferences or imports.
show variables
groovy:000> :show variables
Variables:
_ = true
show classes
show imports
show preferences
show all
inspect
Opens the GUI object browser to inspect a variable or the result of the last evaluation.
http://docs.groovy-lang.org/latest/html/documentation/ 175/502
1/6/2019 purge Groovy Language Documentation
Purges objects from the shell.
purge variables
purge classes
purge imports
purge preferences
purge all
edit
Edit the current bu er in an external editor.
Currently only works on UNIX systems which have the EDITOR environment variable set, or have con gured the editor
preference.
load
Load one or more les (or urls) into the bu er.
save
Saves the bu er’s contents to a le.
record
Record the current session to a le.
record start
record stop
record status
history
Display, manage and recall edit-line history.
history show
history recall
history flush
history clear
alias
Create an alias.
doc
Opens a browser with documentation for the provided class. For example:
groovy:000> :doc java.util.List
http://docs.oracle.com/javase/7/docs/api/java/util/List.html
http://docs.groovy-lang.org/2.4.2-SNAPSHOT/html/groovy-jdk/java/util/List.html
will open two windows (or tabs, depending on your browser):
one for the JDK documentation
one for the GDK documentation
set
Set or list preferences.
Preferences
Some of aspects of groovysh behaviors can be customized by setting preferences. Preferences are set using the set command
or the := shortcut.
http://docs.groovy-lang.org/latest/html/documentation/ 176/502
1/6/2019 Recognized Preferences Groovy Language Documentation
interpreterMode
Allows the use of typed variables (i.e. def or other type information):
groovy:000> def x = 3
===> 3
groovy:000> x
===> 3
It’s especially useful for copy&pasting code from tutorials etc. into the running session.
verbosity
Set the shell’s verbosity level. Expected to be one of:
DEBUG
VERBOSE
INFO
QUIET
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.
colors
Set the shell’s use of colors.
Default is true .
show-last-result
Show the last result after an execution.
Default is true .
sanitize-stack-trace
Sanitize (trim-down/ lter) stack traces.
Default is true .
editor
Con gures the editor used by the edit command.
Default is the value of the system environment variable EDITOR .
Mac OS XTo use TextEdit, the default text editor on Mac OS X, con gure: set editor
/Applications/TextEdit.app/Contents/MacOS/TextEdit
Setting a Preference
groovy:000> :set verbosity DEBUG
Listing Preferences
To list the current set preferences (and their values):
groovy:000> :show preferences
Limitation: At the moment, there is no way to list all of the known/available preferences to be set.
Clearing Preferences (i.e. Resetting to Defaults)
groovy:000> :purge preferences
User Pro le Scripts and State
Pro le Scripts
http://docs.groovy-lang.org/latest/html/documentation/ 177/502
1/6/2019 $HOME/.groovy/groovysh.profile Groovy Language Documentation
This script, if it exists, is loaded when the shell starts up.
$HOME/.groovy/groovysh.rc
This script, if it exists, is loaded when the shell enters interactive mode.
State
$HOME/.groovy/groovysh.history
Edit-line history is stored in this le.
Custom commands
The register command allows you to register custom commands in the shell. For example, writing the following will register the
Stats command:
groovy:000> :register Stats
where the Stats class is a class extending the org.codehaus.groovy.tools.shell.CommandSupport class. For example:
org.codehaus.groovy.tools.shell.
org.codehaus.groovy.tools.shell.
{
( shell) {
(shell, 'stats', 'T')
}
execute( args) {
println "Free memory: ${Runtime.runtime.freeMemory()}"
}
Then the command can be called using:
groovy:000> :stats
stats
Free memory: 139474880
groovy:000>
Note that the command class must be found on classpath: you cannot de ne a new command from within the shell.
Troubleshooting
Please report (https://issues.apache.org/jira/browse/GROOVY) any problems you run into. Please be sure to mark the JIRA issue
with the Groovysh component.
Platform Problems
Problems loading the JLine DLL
On Windows, JLine2 (https://github.com/jline/jline2) (which is used for the fancy shell input/history/completion u ), uses a tiny
DLL le to trick the evil Windows faux-shell ( CMD.EXE or COMMAND.COM ) into providing Java with unbu ered 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 ag and set it to one of:
none
false
off
jline.UnsupportedTerminal
groovysh --terminal=none
http://docs.groovy-lang.org/latest/html/documentation/
Problems with Cygwin on Windows 178/502
1/6/2019 Some people have issues when running groovysh with cygwin.
GroovyIf you have troubles,
Language the following may help:
Documentation
stty -icanon min 1 -echo
groovysh --terminal=unix
stty icanon echo
2.3.2. GMavenPlus Maven Plugin
GMavenPlus (https://github.com/groovy/GMavenPlus) is a Maven plugin with goals that support launching a Groovy Shell or
Groovy Console bound to a Maven project.
2.3.3. Gradle Groovysh Plugin
Gradle Groovysh Plugin (https://github.com/tkruse/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
2.4.1. Groovy : Groovy Console
The Groovy Swing Console allows a user to enter and run Groovy scripts. This page documents the features of this user interface.
2.4.2. Basics
1. Groovy Console is launched via groovyConsole or groovyConsole.bat , both located in $GROOVY_HOME/bin
2. The Console has an input area and an output area.
3. You type a Groovy script in the input area.
4. When you select Run from the Actions menu, the console compiles the script and runs it.
5. Anything that would normally be printed on System.out is printed in the output area.
6. If the script returns a non-null result, that result is printed.
2.4.3. Features
Command-line Options and Arguments
The Groovy Console supports several options to control classpath and other features.
http://docs.groovy-lang.org/latest/html/documentation/ 179/502
1/6/2019 Groovy Language Documentation
./bin/groovyConsole --help
: groovyConsole [options] [filename]
allows a user to enter run scripts.
--configscript=PARAM A script tweaking the compiler configuration options
-cp, -classpath, --classpath
to find the files - must be first
argument
-D, --define=<name=value> a system
-h, --help help message
-i, --indy ( ) compilation scripts
-pa, --parameters metadata reflection on method parameter
names (jdk8+ only)
-V, --version the version
Running Scripts
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 the value of the last expression executed.
You can turn the System.out capture on and o by selecting Capture System.out from the Actions menu
Editing Files
You can open any text le, edit it, run it (as a Groovy Script) and then save it again when you are nished.
Select File > Open (shortcut key ctrl+O ) to open a le
Select File > Save (shortcut key ctrl+S ) to save a le
Select File > New File (shortcut key ctrl+Q ) to start again with a blank input area
History and results
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.
Interrupting a script
The Groovy console is a very handy tool to develop scripts. Often, you will nd yourself running a script multiple times until it
works the way you want it to. However, what if your code takes too long to nish or worse, creates an in nite 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 tool bar.
However, this may not be su cient to interrupt a script: clicking the button will interrupt the execution thread, but if your code
doesn’t handle the interrupt ag, the script is likely to keep running without you being able to e ectively stop it. To avoid that, you
have to make sure that the Script > Allow interruption menu item is agged. This will automatically apply an AST
transformation to your script which will take care of checking the interrupt ag ( @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.
And more
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 le
http://docs.groovy-lang.org/latest/html/documentation/ 180/502
1/6/2019 You can modify the classpath with which the script in the console
Groovy is being
Language run by adding a new JAR or a directory to the
Documentation
classpath from the Script menu
Error hyperlinking from the output area when a compilation error is expected or when an exception is thrown
You can enable InvokeDynamic (Indy) compilation mode by selecting Enable Indy Compilation from the Script menu
2.4.4. Embedding the Console
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:
groovy.ui. ;
...
console = ();
console.setVariable("var1", getValueOfVar1());
console.setVariable("var2", getValueOfVar2());
console.run();
...
Once the console is launched, you can use the variable values in Groovy code.
2.4.5. Visualizing script output results
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 :
javax.swing.*
transforms << { result ->
(result ) {
table = (
result.collect{ k, v ->
[k, v?.inspect()] []
} [][],
['Key', 'Value'] [])
table.preferredViewportSize = table.preferredSize
(table)
}
}
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. And we’re now
able to visualize maps in a friendly and attractive fashion, as the screenshot below shows:
http://docs.groovy-lang.org/latest/html/documentation/ 181/502
1/6/2019 Groovy Language Documentation
2.4.6. AST browser
Groovy Console can visualize the AST (Abstract Syntax Tree) representing the currently edited script, as shown by the screenshot
below. This is particularly handy when you want to develop AST transformations.
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 les. The distribution comes with two ways of generating documentation: from
command line or from Apache Ant. Other build tools like Maven or Gradle also o er wrappers for Groovydoc.
2.5.1. The groovydoc command line tool
The groovydoc command line can be invoked to generate groovydocs:
groovydoc [options] [packagenames] [sourcefiles]
where options must be picked from the following table:
Short version Long version Description
-author Include @author paragraphs (currently not used)
-windowtitle <text> Browser window title for the documentation
http://docs.groovy-lang.org/latest/html/documentation/ 182/502
1/6/2019 Groovy Language Documentation
Short version Long version Description
-charset <charset> Charset for cross-platform viewing of generated documentation
-classpath, -cp --classpath Specify where to nd the class les - must be rst argument
-d --destdir <dir> Destination directory for output les
--debug Enable debug output
-doctitle <html> Include title for the overview page
-exclude <pkglist> Specify a list of packages to exclude (separated by colons for all
operating systems)
- leEncoding <charset> Charset for generated documentation les
-footer <html> Include footer text for each page
-header <html> Include header text for each page
-help --help Display help message
-nomainforscripts Don’t include the implicit 'public static void main' method for scripts
-noscripts Don’t process Groovy Scripts
-notimestamp Don’t include timestamp within hidden comment in generated HTML
-noversionstamp Don’t include Groovy version within hidden comment in generated
HTML
-overview < le> Read overview documentation from HTML le
-package Show package/protected/public classes and members
-private Show all classes and members
-protected Show protected/public classes and members (default)
-public Show only public classes and members
-quiet Suppress super uous output
-sourcepath <pathlist> Specify where to nd source les (dirs separated by platform path
separator)
-stylesheet le <path> File to change style of the generated documentation
-verbose Enable verbose output
--version Display the version
-windowtitle <text> Browser window title for the documentation
2.5.2. The groovydoc Ant task
The groovydoc Ant task allows generating groovydocs from an Ant build.
Required taskdef
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.
http://docs.groovy-lang.org/latest/html/documentation/ 183/502
1/6/2019 Groovy Language Documentation
name = "groovydoc"
classname = "org.codehaus.groovy.ant.Groovydoc"
classpathref = "my.classpath"
<groovydoc> Attributes
Attribute Description Required
destdir Location to store the class les. Yes
sourcepath The sourcepath to use. No
packagenames Comma separated list of package les (with terminating No
wildcard).
use Create class and package usage pages. No
windowtitle Browser window title for the documentation (text). No
doctitle Include title for the package index( rst) page (html-code). No
header Include header text for each page (html-code). No
footer Include footer text for each page (html-code). No
overview Read overview documentation from HTML le. No
private Show all classes and members (i.e. including private ones) if No
set to ``true''.
<groovydoc> Nested Elements
link
Create link to groovydoc/javadoc output at the given URL.
Attribute Description Required
packages Comma separated list of package Yes
pre xes
href Base URL of external site Yes
Example #1 - <groovydoc> Ant task
http://docs.groovy-lang.org/latest/html/documentation/ 184/502
1/6/2019 Groovy Language Documentation
name = "groovydoc"
classname = "org.codehaus.groovy.ant.Groovydoc"
classpathref = "path_to_groovy_all"
destdir = "${docsDirectory}/gapi"
sourcepath = "${mainSourceDirectory}"
packagenames = "**.*"
use = "true"
windowtitle = "${title}"
doctitle = "${title}"
header = "${title}"
footer = "${docFooter}"
overview = "src/main/overview.html"
private = "false"
packages="java.,org.xml.,javax.,org.xml."
href="http://docs.oracle.com/javase/8/docs/api/"
packages="org.apache.tools.ant." href="http://docs.groovy-
lang.org/docs/ant/api/"
packages="org.junit.,junit.framework."
href="http://junit.org/junit4/javadoc/latest/"
packages="groovy.,org.codehaus.groovy." href="http://docs.groovy-
lang.org/latest/html/api/"
packages="org.codehaus.gmaven."
href="http://groovy.github.io/gmaven/apidocs/"
Example #2 - Executing <groovydoc> from Groovy
ant = ()
ant.taskdef(name: "groovydoc", classname: "org.codehaus.groovy.ant.Groovydoc")
ant.groovydoc(
destdir : "${docsDirectory}/gapi",
sourcepath : "${mainSourceDirectory}",
packagenames : "**.*",
: "true",
windowtitle : "${title}",
doctitle : "${title}",
header : "${title}",
footer : "${docFooter}",
overview : "src/main/overview.html",
: "false") {
link(packages:"java.,org.xml.,javax.,org.xml.",href:"http://docs.oracle.com/javase/8/docs/api/")
link(packages:"groovy.,org.codehaus.groovy.", href:"http://docs.groovy-
lang.org/latest/html/api/")
link(packages:"org.apache.tools.ant.", href:"http://docs.groovy-
lang.org/docs/ant/api/")
link(packages:"org.junit.,junit.framework.",
href:"http://junit.org/junit4/javadoc/latest/")
link(packages:"org.codehaus.gmaven.",
href:"http://groovy.github.io/gmaven/apidocs/")
}
Custom templates
The groovydoc Ant task supports custom templates, but it requires two steps:
1. A custom groovydoc class
2. A new groovydoc task de nition
Custom Groovydoc class
The rst step requires you to extend the Groovydoc class, like in the following example:
http://docs.groovy-lang.org/latest/html/documentation/ 185/502
1/6/2019 Groovy Language Documentation
org.codehaus.groovy.tools.groovydoc;
org.codehaus.groovy.ant. ;
/**
* Overrides GroovyDoc's default class template - for testing purpose only.
*
* @author Andre Steingress
*/
{
@Override
[] getClassTemplates() {
[]{"org/codehaus/groovy/tools/groovydoc/testfiles/classDocName.html"};
}
}
You can override the following methods:
getClassTemplates for class-level templates
getPackageTemplates for package-level templates
getDocTemplates for top-level templates
You can nd the list of default templates in the
org.codehaus.groovy.tools.groovydoc.gstringTemplates.GroovyDocTemplateInfo class.
Using the custom groovydoc task
Once you’ve written the class, using it is just a matter of rede ning the groovydoc task:
name = "groovydoc"
classname = "org.codehaus.groovy.ant.CustomGroovyDoc"
classpathref = "path_to_groovy_all"
Please note that template customization is provided as is. APIs are subject to change, so you must consider this as a fragile
feature.
2.5.3. GMavenPlus Maven Plugin
GMavenPlus (https://github.com/groovy/GMavenPlus) is a Maven plugin with goals that support GroovyDoc generation.
2.6. IDE integration
The Groovy language is supported by lots of IDEs and text editors.
Editor Syntax highlighting Code completion Refactoring
Groovy Eclipse Plugin Yes Yes Yes
(https://github.com/groovy/groovy-eclipse)
IntelliJ IDEA Yes Yes Yes
(http://www.jetbrains.com/idea/features/groovy.html)
Netbeans (https://netbeans.org/features/groovy/) Yes Yes Yes
Groovy Emacs Modes (https://github.com/Groovy- Yes No No
Emacs-Modes/groovy-emacs-modes)
TextMate Yes No No
(https://github.com/textmate/groovy.tmbundle)
vim (http://www.vim.org/) Yes No No
VSCode (https://code.visualstudio.com/) Yes No No
http://docs.groovy-lang.org/latest/html/documentation/ 186/502
1/6/2019 Groovy Language Documentation
Editor Syntax highlighting Code completion Refactoring
UltraEdit (http://www.ultraedit.com/) Yes No No
SlickEdit Yes No No
(https://www.slickedit.com/products/slickedit/419-
the-most-powerful-groovy-editor-in-the-world/)
EditRocket Yes No No
(https://editrocket.com/features/groovy_editor.html)
VSCode (https://code.visualstudio.com/) Yes No No
3. User Guides
3.1. Getting started
3.1.1. Download
In this download area, you will be able to download the distribution (binary and source), the Windows installer and the
documentation for Groovy.
For a quick and e ortless start on Mac OSX, Linux or Cygwin, you can use SDKMAN! (http://sdkman.io/) (The Software
Development Kit Manager) to download and con gure any Groovy version of your choice. Basic instructions can be found below.
Stable
Download zip: Binary Release (https://bintray.com/artifact/download/groovy/maven/apache-groovy-binary-2.5.5.zip) | Source
Release (https://bintray.com/artifact/download/groovy/maven/groovy-src-2.5.5.zip)
Download documentation: JavaDoc and zipped online documentation
(https://bintray.com/artifact/download/groovy/maven/apache-groovy-docs-2.5.5.zip)
Combined binary / source / documentation bundle: Distribution bundle
(https://bintray.com/artifact/download/groovy/maven/apache-groovy-sdk-2.5.5.zip)
You can learn more about this version in the release notes (http://groovy-lang.org/releasenotes/groovy-2.5.html) or in the
changelog (http://groovy-lang.org/changelogs/changelog-2.5.5.html).
If you plan on using invokedynamic support, read those notes (invokedynamic-support.html).
Snapshots
For those who want to test the very latest versions of Groovy and live on the bleeding edge, you can use our snapshot builds
(https://oss.jfrog.org/oss-snapshot-local/org/codehaus/groovy). As soon as a build succeeds on our continuous integration server
a snapshot is deployed to Artifactory’s OSS snapshot repository.
Prerequisites
Groovy 2.5 requires Java 6+ with full support up to Java 8. There are currently some known issues for some aspects when using
Java 9 snapshots. The groovy-nio module requires Java 7+. Using Groovy’s invokeDynamic features require Java 7+ but we
recommend Java 8.
The Groovy CI server is also useful to look at to con rm supported Java versions for di erent Groovy releases. The test suite
(getting close to 10000 tests) runs for the currently supported streams of Groovy across all the main versions of Java each stream
supports.
3.1.2. Maven Repository
If you wish to embed Groovy in your application, you may just prefer to point to your favourite maven repositories or the JCenter
maven repository (https://oss.jfrog.org/oss-release-local/org/codehaus/groovy).
Stable Release
Gradle Maven Explanation
http://docs.groovy-lang.org/latest/html/documentation/ 187/502
1/6/2019 Groovy Language Documentation
Gradle Maven Explanation
'org.codehaus.groovy:groovy:2.5.5' <groupId>org.codehaus.groovy</groupId> Just the core of groovy without
<artifactId>groovy</artifactId> the modules (see below).
<version>2.5.5</version>
'org.codehaus.groovy:groovy-$module:2.5.5' <groupId>org.codehaus.groovy</groupId> "$module" stands for the di erent
<artifactId>groovy-$module</artifactId> optional groovy modules "ant",
<version>2.5.5</version> "bsf", "console", "docgenerator",
"groovydoc", "groovysh", "jmx",
"json", "jsr223", "servlet", "sql",
"swing", "test", "testng" and "xml".
Example: <artifactId>groovy-
sql</artifactId>
'org.codehaus.groovy:groovy-all:2.5.5' <groupId>org.codehaus.groovy</groupId> The core plus all the modules.
<artifactId>groovy-all</artifactId> Optional dependencies are
<version>2.5.5</version> marked as optional. You may
need to include some of the
optional dependencies to use
some features of Groovy, e.g.
AntBuilder, GroovyMBeans, etc.
To use the InvokeDynamic (invokedynamic-support.html) version of the jars just append ':indy' for Gradle or
<classi er>indy</classi er> for Maven.
3.1.3. SDKMAN! (The Software Development Kit Manager)
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:
$ curl -s .sdkman.io | bash
Follow the instructions on-screen to complete installation.
Open a new terminal or type the command:
$ source "$HOME/.sdkman/bin/sdkman-init.sh"
Then install the latest stable Groovy:
$ sdk install groovy
After installation is complete and you’ve made it your default version, test it with:
$ groovy -version
That’s all there is to it!
3.1.4. Other ways to get Groovy
Installation on Mac OS X
MacPorts
If you’re on MacOS and have MacPorts (http://www.macports.org) installed, you can run:
sudo port install groovy
Homebrew
If you’re on MacOS and have Homebrew (http://mxcl.github.com/homebrew) installed, you can run:
http://docs.groovy-lang.org/latest/html/documentation/ 188/502
1/6/2019 Groovy Language Documentation
brew install groovy
Installation on Windows
If you’re on Windows, you can also use the NSIS Windows installer (TODO-Windows+NSIS-Installer).
Other Distributions
You may download other distributions of Groovy from this site (https://bintray.com/groovy/maven).
Source Code
If you prefer to live on the bleeding edge, you can also grab the source code from GitHub (https://github.com/apache/groovy).
IDE plugin
If you are an IDE user, you can just grab the latest IDE plugin (tools-ide.html) and follow the plugin installation instructions.
3.1.5. Install Binary
These instructions describe how to install a binary distribution of Groovy.
First, Download a binary distribution of Groovy and unpack it into some le on your local le system.
Set your GROOVY_HOME environment variable to the directory 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:
groovysh
Which should create an interactive groovy shell where you can type Groovy statements. Or to run the Swing interactive console
type:
groovyConsole
To run a speci c Groovy script type:
groovy
3.2. Di erences 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 di erences between Java and Groovy.
3.2.1. Default imports
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.io.*
java.lang.*
java.math.BigDecimal
java.math.BigInteger
java.net.*
java.util.*
groovy.lang.*
groovy.util.*
3.2.2. Multi-methods
http://docs.groovy-lang.org/latest/html/documentation/ 189/502
1/6/2019 In Groovy, the methods which will be invoked are chosen Groovy
at runtime. This isDocumentation
Language 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 di erently:
method( arg) {
1;
}
method( arg) {
2;
}
o = "Object";
result = method(o);
In Java, you would have:
assertEquals(2, result);
Whereas in Groovy:
assertEquals(1, result);
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.
3.2.3. Array initializers
In Groovy, the { … } block is reserved for closures. That means that you cannot create array literals with this syntax:
[] array = { 1, 2, 3}
You actually have to use:
[] array = [1,2,3]
3.2.4. Package scope visibility
In Groovy, omitting a modi er on a eld doesn’t result in a package-private eld like in Java:
{
name
}
Instead, it is used to create a property, that is to say a private eld, an associated getter and an associated setter.
It is possible to create a package-private eld by annotating it with @PackageScope :
{
@PackageScope name
}
3.2.5. ARM blocks
ARM (Automatic Resource Management) block from Java 7 are not supported in Groovy. Instead, Groovy provides various
methods relying on closures, which have the same e ect while being more idiomatic. For example:
http://docs.groovy-lang.org/latest/html/documentation/ 190/502
1/6/2019 Groovy Language Documentation
file = .get("/path/to/file");
charset = .forName("UTF-8");
( reader = .newBufferedReader(file, charset)) {
line;
((line = reader.readLine()) != ) {
.out.println(line);
}
} ( e) {
e.printStackTrace();
}
can be written like this:
('/path/to/file').eachLine('UTF-8') {
println it
}
or, if you want a version closer to Java:
('/path/to/file').withReader('UTF-8') { reader ->
reader.eachLine {
println it
}
}
3.2.6. Inner classes
The implementation of anonymous inner classes and nested classes follows the Java lead, but you should not take
out the Java Language Spec and keep shaking the head about things that are di erent. The implementation done
looks much like what we do for groovy.lang.Closure , with some bene ts and some di erences. Accessing
private elds and methods for example can become a problem, but on the other hand local variables don’t have
to be nal.
Static inner classes
Here’s an example of static inner class:
A {
B {}
}
A.B()
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.
Anonymous Inner Classes
java.util.concurrent.
java.util.concurrent.
called = (1)
timer = ()
timer.schedule( () {
run() {
called.countDown()
}
}, 0)
called.await(10, .SECONDS)
Creating Instances of Non-Static Inner Classes
http://docs.groovy-lang.org/latest/html/documentation/ 191/502
1/6/2019 In Java you can do this: Groovy Language Documentation
Y {
X {}
X foo() {
X();
}
X createX(Y y) {
y. X();
}
}
Groovy doesn’t support the y.new X() syntax. Instead, you have to write new X(y) , like in the code below:
Y {
X {}
X foo() {
X()
}
X createX(Y y) {
X(y)
}
}
Caution though, Groovy supports calling methods with one parameter without giving an argument. The parameter
will then have the value null. Basically the same rules apply to calling a constructor. There is a danger that you will
write new X() instead of new X(this) for example. Since this might also be the regular way we have not yet found a
good way to prevent this problem.
3.2.7. Lambdas
Java 8 supports lambdas and method references:
run = () -> . .println("Run");
list.forEach( . ::println);
Java 8 lambdas can be more or less considered as anonymous inner classes. Groovy doesn’t support that syntax, but has closures
instead:
run = { println 'run' }
list.each { println it } // or list.each(this.&println)
3.2.8. GStrings
As double-quoted string literals are interpreted as GString values, Groovy may fail with compile error or produce subtly di erent
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.
3.2.9. String and Character literals
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.
'c'.getClass()==
"c".getClass()==
"c${1}".getClass()
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.
http://docs.groovy-lang.org/latest/html/documentation/ 192/502
1/6/2019 Groovy Language Documentation
a='a'
.digit(a, 16)==10 : 'But Groovy does boxing'
.digit(( ) 'a', 16)==10
{
.digit('a', 16)==10
: 'Need explicit cast'
} ( e) {
}
Groovy supports two styles of casting and in the case of casting to char there are subtle di erences when casting a multi-char
strings. The Groovy style cast is more lenient and will take the rst character, while the C-style cast will fail with exception.
// for single char strings, both are the same
(( ) "c"). ==
("c" ). ==
// for multi char strings they are not
{
(( ) 'cx') == 'c'
: 'will fail - not castable'
} ( e) {
}
('cx' ) == 'c'
'cx'.asType( ) == 'c'
3.2.10. Primitives and wrappers
Because Groovy uses Objects for everything, it autowraps (core-object-orientation.html#_primitive_types) references to primitives.
Because of this, it does not follow Java’s behavior of widening taking priority over boxing. Here’s an example using int
i
m(i)
m( l) { 1
println "in m(long)"
}
m( i) { 2
println "in m(Integer)"
}
1 This is the method that Java would call, since widening has precedence over unboxing.
2 This is the method Groovy actually calls, since all primitive references use their wrapper class.
3.2.11. Behaviour of ==
In Java == means equality of primitive types or identity for objects. In Groovy == translates to a.compareTo(b)==0 , if they are
Comparable , and a.equals(b) otherwise. To check for identity, there is is . E.g. a.is(b) .
3.2.12. Conversions
Java does automatic widening and narrowing conversions (https://docs.oracle.com/javase/specs/jls/se7/html/jls-5.html).
Table 5. Java Conversions
Converts to
Converts from boolean byte short char int long oat double
boolean - N N N N N N N
http://docs.groovy-lang.org/latest/html/documentation/ 193/502
1/6/2019 Groovy Language Documentation
byte N - Y C Y Y Y Y
short N C - C Y Y Y Y
char N C C - Y Y Y Y
int N C C C - Y T Y
long N C C C C - T T
oat N C C C C C - Y
double N C C C C C C -
* '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.
Table 6. Groovy Conversions
Converts to
Converts boolean Boolean byte Byte short Short char Character int Integer long Long BigInteger oat
from
boolean - B N N N N N N N N N N N N
Boolean B - N N N N N N N N N N N N
byte T T - B Y Y Y D Y Y Y Y Y Y
Byte T T B - Y Y Y D Y Y Y Y Y Y
short T T D D - B Y D Y Y Y Y Y Y
Short T T D T B - Y D Y Y Y Y Y Y
char T T Y D Y D - D Y D Y D D Y
Character T T D D D D D - D D D D D D
int T T D D D D Y D - B Y Y Y Y
Integer T T D D D D Y D B - Y Y Y Y
long T T D D D D Y D D D - B Y T
Long T T D D D T Y D D T B - Y T
http://docs.groovy-lang.org/latest/html/documentation/ 194/502
1/6/2019 Groovy Language Documentation
BigInteger T T D D D D D D D D D D - D
oat T T D D D D T D D D D D D -
Float T T D T D T T D D T D T D B
double T T D D D D T D D D D D D D
Double T T D T D T T D D T D T D D
BigDecimal T T D D D D D D D D D D D T
*
'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 de ned
by java.lang.Number .
3.2.13. Extra keywords
There are a few more keywords in Groovy than in Java. Don’t use them for variable names etc.
as
def
in
trait
3.3. Groovy Development Kit
3.3.1. Working with IO
Groovy provides a number of helper methods (gdk.html) 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 les, 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 (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
(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
(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 (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 (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/ le/Path.html (http://docs.groovy-
lang.org/latest/html/groovy-jdk/java/nio/ le/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 (gdk.html).
Reading les
http://docs.groovy-lang.org/latest/html/documentation/ 195/502
1/6/2019 As a rst example, let’s see how you would print all lines of a text Language
Groovy le in Groovy:
Documentation
(baseDir, 'haiku.txt').eachLine { line ->
println line
}
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:
(baseDir, 'haiku.txt').eachLine { line, nb ->
println "Line $nb: $line"
}
If for whatever reason the 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 bene t from the automatic resource management from
Groovy. In the next example, the reader will be closed even if the exception occurs:
count = 0, MAXSIZE = 3
(baseDir,"haiku.txt").withReader { reader ->
(reader.readLine()) {
(++count > MAXSIZE) {
('Haiku should only have 3 verses')
}
}
}
Should you need to collect the lines of a text le into a list, you can do:
list = (baseDir, 'haiku.txt').collect {it}
Or you can even leverage the as operator to get the contents of the le into an array of lines:
array = (baseDir, 'haiku.txt') []
How many times did you have to get the contents of a le into a byte[] and how much code does it require? Groovy makes it
very easy actually:
[] contents = file.bytes
Working with I/O is not limited to dealing with les. 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 (http://docs.groovy-lang.org/latest/html/groovy-
jdk/java/io/InputStream.html).
As an example, you can obtain an InputStream from a File very easily:
= (baseDir,'haiku.txt').newInputStream()
// do something ...
.close()
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:
(baseDir,'haiku.txt').withInputStream { stream ->
// do something ...
}
Writing les
http://docs.groovy-lang.org/latest/html/documentation/ 196/502
1/6/2019 Of course in some cases you won’t want to read but writeGroovy
a le. One of the options
Language is to use a Writer :
Documentation
(baseDir,'haiku.txt').withWriter('utf-8') { writer ->
writer.writeLine 'Into the ancient pond'
writer.writeLine 'A frog jumps'
writer.writeLine 'Water’s sound!'
}
But for such a simple example, using the << operator would have been enough:
(baseDir,'haiku.txt') << '''Into the ancient pond
A frog jumps
Water’s sound!'''
Of course we do not always deal with text contents, so you could use the Writer or directly write bytes as in this example:
file.bytes = [66,22,11]
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 le:
os = (baseDir,'data.bin').newOutputStream()
// do something ...
os.close()
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:
(baseDir,'data.bin').withOutputStream { stream ->
// do something ...
}
Traversing le trees
In scripting contexts it is a common task to traverse a le tree in order to nd some speci c les and do something with them.
Groovy provides multiple methods to do this. For example you can perform something on all les of a directory:
dir.eachFile { file -> 1
println file.name
}
dir.eachFileMatch(~/.*\.txt/) { file -> 2
println file.name
}
1 executes the closure code on each le found in the directory
2 executes the closure code on les in the directory matching the speci ed pattern
Often you will have to deal with a deeper hierarchy of les, in which case you can use eachFileRecurse :
dir.eachFileRecurse { file -> 1
println file.name
}
dir.eachFileRecurse( .FILES) { file -> 2
println file.name
}
1 executes the closure code on each le or directory found in the directory, recursively
2 executes the closure code only on les, but recursively
http://docs.groovy-lang.org/latest/html/documentation/ 197/502
1/6/2019 For more complex traversal techniques you can use the traverse method,Documentation
Groovy Language which requires you to set a special ag indicating
what to do with the traversal:
dir.traverse { file ->
(file.directory && file.name=='bin') {
.TERMINATE 1
} {
println file.name
.CONTINUE 2
1 if the current le is a directory and its name is bin , stop the traversal
2 otherwise print the le name and continue
Data and objects
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 le and deserialize it using this code:
b =
message = 'Hello from Groovy'
// Serialize data into a file
file.withDataOutputStream { ->
.writeBoolean(b)
.writeUTF(message)
}
// ...
// Then read it back
file.withDataInputStream { input ->
input.readBoolean() == b
input.readUTF() == message
}
And similarily, if the data you want to serialize implements the Serializable interface, you can proceed with an object output
stream, as illustrated here:
p = (name:'Bob', age:76)
// Serialize data into a file
file.withObjectOutputStream { ->
.writeObject(p)
}
// ...
// Then read it back
file.withObjectInputStream { input ->
p2 = input.readObject()
p2.name == p.name
p2.age == p.age
}
Executing External Processes
The previous section described how easy it was to deal with les, 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:
process = "ls -l".execute() 1
println "Found text ${process.text}" 2
http://docs.groovy-lang.org/latest/html/documentation/ 198/502
1/6/2019 1 executes the ls command in an external process Groovy Language Documentation
2 consume the output of the command and retrieve the text
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:
process = "ls -l".execute() 1
process. .eachLine { line -> 2
println line 3
1 executes the ls command in an external process
2 for each line of the input stream of the process
3 print the line
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 les in a directory on a
Windows machine and write:
process = "dir".execute()
println "${process.text}"
you will receive an IOException saying Cannot run program "dir": CreateProcess error=2, The system cannot nd the le
speci ed.
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:
process = "cmd /c dir".execute()
println "${process.text}"
Also, because this functionality currently makes use of java.lang.Process undercover, the de ciencies of that class must be
taken into consideration. In particular, the javadoc for this class says:
Because some native platforms only provide limited bu er 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:
p = "rm -f foo.tmp".execute([], tmpDir)
p.consumeProcessOutput()
p.waitFor()
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 (http://docs.groovy-lang.org/latest/html/groovy-
jdk/java/lang/Process.html)
In addition, these 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:
Pipes in action
http://docs.groovy-lang.org/latest/html/documentation/ 199/502
1/6/2019 Groovy Language Documentation
proc1 = 'ls'.execute()
proc2 = 'tr -d o'.execute()
proc3 = 'tr -d e'.execute()
proc4 = 'tr -d i'.execute()
proc1 | proc2 | proc3 | proc4
proc4.waitFor()
(proc4.exitValue()) {
println proc4.err.text
} {
println proc4.text
}
Consuming errors
sout = ()
serr = ()
proc2 = 'tr -d o'.execute()
proc3 = 'tr -d e'.execute()
proc4 = 'tr -d i'.execute()
proc4.consumeProcessOutput(sout, serr)
proc2 | proc3 | proc4
[proc2, proc3].each { it.consumeProcessErrorStream(serr) }
proc2.withWriter { writer ->
writer << 'testfile.groovy'
}
proc4.waitForOrKill(1000)
println "Standard output: $sout"
println "Standard error: $serr"
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 (http://www.groovy-
lang.org/gdk.html).
Lists
List literals
You can create lists as follows. Notice that [] is the empty list expression.
list = [5, 6, 7, 8]
list. (2) == 7
list[2] == 7
list java.util.
emptyList = []
emptyList.size() == 0
emptyList.add(5)
emptyList.size() == 1
Each list expression creates an implementation of java.util.List (http://docs.oracle.com/javase/8/docs/api/java/util/List.html).
Of course lists can be used as a source to construct another list:
list1 = ['a', 'b', 'c']
//construct a new list, seeded with the same items as in list1
list2 = < >(list1)
list2 == list1 // == checks that each corresponding element is the same
// clone() can also be called
list3 = list1.clone()
list3 == list1
A list is an ordered collection of objects:
http://docs.groovy-lang.org/latest/html/documentation/ 200/502
1/6/2019 Groovy Language Documentation
list = [5, 6, 7, 8]
list.size() == 4
list.getClass() == // the specific kind of list being used
list[2] == 7 // indexing starts at 0
list.getAt(2) == 7 // equivalent method to subscript operator []
list. (2) == 7 // alternative method
list[2] = 9
list == [5, 6, 9, 8,] // trailing comma OK
list.putAt(2, 10) // equivalent method to [] when value being changed
list == [5, 6, 10, 8]
list. (2, 11) == 10 // alternative method that returns old value
list == [5, 6, 11, 8]
['a', 1, 'a', 'a', 2.5, 2.5f, 2.5d, 'hello', 7g, , 9 ]
//objects can be of different types; duplicates allowed
[1, 2, 3, 4, 5][-1] == 5 // use negative indices to count from the end
[1, 2, 3, 4, 5][-2] == 4
[1, 2, 3, 4, 5].getAt(-2) == 4 // getAt() available with negative index...
{
[1, 2, 3, 4, 5]. (-2) // but negative index not allowed with get()
} (e) {
e
}
List as a boolean expression
Lists can be evaluated as a boolean value:
![] // an empty list evaluates as false
//all other lists, irrespective of contents, evaluate as true
[1] && ['a'] && [0] && [0.0] && [ ] && [ ]
Iterating on a list
Iterating on elements of a list is usually done calling the each and eachWithIndex methods, which execute code on each item of
a list:
[1, 2, 3].each {
println "Item: $it" // `it` is an implicit parameter corresponding to the current element
}
['a', 'b', 'c'].eachWithIndex { it, i -> // `it` is the current element, while `i` is the index
println "$i: $it"
}
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:
[1, 2, 3].collect { it * 2 } == [2, 4, 6]
// shortcut syntax instead of collect
[1, 2, 3]*.multiply(2) == [1, 2, 3].collect { it.multiply(2) }
list = [0]
// it is possible to give `collect` the list which collects the elements
[1, 2, 3].collect(list) { it * 2 } == [0, 2, 4, 6]
list == [0, 2, 4, 6]
Manipulating lists
Filtering and searching
http://docs.groovy-lang.org/latest/html/documentation/ 201/502
1/6/2019 The Groovy development kit (http://www.groovy-lang.org/gdk.html) contains
Groovy Language a lot of methods on collections that enhance the
Documentation
standard collections with pragmatic methods, some of which are illustrated here:
[1, 2, 3].find { it > 1 } == 2 // find 1st element matching criteria
[1, 2, 3].findAll { it > 1 } == [2, 3] // find all elements matching critieria
['a', 'b', 'c', 'd', 'e'].findIndexOf { // find index of 1st element matching criteria
it ['c', 'e', 'g']
} == 2
['a', 'b', 'c', 'd', 'c'].indexOf('c') == 2 // index returned
['a', 'b', 'c', 'd', 'c'].indexOf('z') == -1 // index -1 means value not in list
['a', 'b', 'c', 'd', 'c'].lastIndexOf('c') == 4
[1, 2, 3].every { it < 5 } // returns true if all elements match the predicate
![1, 2, 3].every { it < 3 }
[1, 2, 3].any { it > 2 } // returns true if any element matches the
predicate
![1, 2, 3].any { it > 3 }
[1, 2, 3, 4, 5, 6].sum() == 21 // sum anything with a plus() method
['a', 'b', 'c', 'd', 'e'].sum {
it == 'a' ? 1 : it == 'b' ? 2 : it == 'c' ? 3 : it == 'd' ? 4 : it == 'e' ? 5 : 0
// custom value to use in sum
} == 15
['a', 'b', 'c', 'd', 'e'].sum { (( ) it) - (( ) 'a') } == 10
['a', 'b', 'c', 'd', 'e'].sum() == 'abcde'
[['a', 'b'], ['c', 'd']].sum() == ['a', 'b', 'c', 'd']
// an initial value can be provided
[].sum(1000) == 1000
[1, 2, 3].sum(1000) == 1006
[1, 2, 3].join('-') == '1-2-3' // String joining
[1, 2, 3].inject('counting: ') {
str, item -> str + item // reduce operation
} == 'counting: 123'
[1, 2, 3].inject(0) { count, item ->
count + item
} == 6
And here is idiomatic Groovy code for nding the maximum and minimum in a collection:
list = [9, 4, 2, 10, 5]
list.max() == 10
list.min() == 2
// we can also compare single characters, as anything comparable
['x', 'y', 'a', 'z'].min() == 'a'
// we can use a closure to specify the sorting behaviour
list2 = ['abc', 'z', 'xyzuvw', 'Hello', '321']
list2.max { it.size() } == 'xyzuvw'
list2.min { it.size() } == 'z'
In addition to closures, you can use a Comparator to de ne the comparison criteria:
http://docs.groovy-lang.org/latest/html/documentation/ 202/502
1/6/2019 Groovy Language Documentation
mc = { a, b -> a == b ? 0 : (a < b ? -1 : 1) }
list = [7, 4, 9, -6, -1, 11, 2, 3, -9, 5, -13]
list.max(mc) == 11
list.min(mc) == -13
mc2 = { a, b -> a == b ? 0 : ( .abs(a) < .abs(b)) ? -1 : 1 }
list.max(mc2) == -13
list.min(mc2) == -1
list.max { a, b -> a.equals(b) ? 0 : .abs(a) < .abs(b) ? -1 : 1 } == -13
list.min { a, b -> a.equals(b) ? 0 : .abs(a) < .abs(b) ? -1 : 1 } == -1
Adding or removing elements
We can use [] to assign a new empty list and << to append items to it:
list = []
list.empty
list << 5
list.size() == 1
list << 7 << 'i' << 11
list == [5, 7, 'i', 11]
list << ['m', 'o']
list == [5, 7, 'i', 11, ['m', 'o']]
//first item in chain of << is target list
([1, 2] << 3 << [4, 5] << 6) == [1, 2, 3, [4, 5], 6]
//using leftShift is equivalent to using <<
([1, 2, 3] << 4) == ([1, 2, 3].leftShift(4))
We can add to a list in many ways:
http://docs.groovy-lang.org/latest/html/documentation/ 203/502
1/6/2019 Groovy Language Documentation
[1, 2] + 3 + [4, 5] + 6 == [1, 2, 3, 4, 5, 6]
// equivalent to calling the `plus` method
[1, 2].plus(3).plus([4, 5]).plus(6) == [1, 2, 3, 4, 5, 6]
a = [1, 2, 3]
a += 4 // creates a new list and assigns it to `a`
a += [5, 6]
a == [1, 2, 3, 4, 5, 6]
[1, *[222, 333], 456] == [1, 222, 333, 456]
[*[1, 2, 3]] == [1, 2, 3]
[1, [2, 3, [4, 5], 6], 7, [8, 9]].flatten() == [1, 2, 3, 4, 5, 6, 7, 8, 9]
list = [1, 2]
list.add(3)
list.addAll([5, 4])
list == [1, 2, 3, 5, 4]
list = [1, 2]
list.add(1, 3) // add 3 just before index 1
list == [1, 3, 2]
list.addAll(2, [5, 4]) //add [5,4] just before index 2
list == [1, 3, 5, 4, 2]
list = ['a', 'b', 'z', 'e', 'u', 'v', 'g']
list[8] = 'x' // the [] operator is growing the list as needed
// nulls inserted if required
list == ['a', 'b', 'z', 'e', 'u', 'v', 'g', , 'x']
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 (http://www.groovy-lang.org/gdk.html) also contains methods allowing you to easily remove
elements from a list by value:
['a','b','c','b','b'] - 'c' == ['a','b','b','b']
['a','b','c','b','b'] - 'b' == ['a','c']
['a','b','c','b','b'] - ['b','c'] == ['a']
list = [1,2,3,4,3,2,1]
list -= 3 // creates a new list by removing `3` from the original one
list == [1,2,4,2,1]
( list -= [2,4] ) == [1,1]
It is also possible to remove an element by passing its index to the remove method, in which case the list is mutated:
list = ['a','b','c','d','e','f','b','b','a']
list.remove(2) == 'c' // remove the third element, and return it
list == ['a','b','d','e','f','b','b','a']
In case you only want to remove the rst element having the same value in a list, instead of removing all elements, you can call
the remove method passing the value:
list= ['a','b','c','b','b']
list.remove('c') // remove 'c', and return true because element removed
list.remove('b') // remove first 'b', and return true because element removed
! list.remove('z') // return false because no elements removed
list == ['a','b','b']
http://docs.groovy-lang.org/latest/html/documentation/ 204/502
1/6/2019 As you can see, there are two remove methods available.Groovy
One that takes anDocumentation
Language integer and removes an element by its index, and
another that will remove the rst 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 rst element
that matches a value.
list = [1,2,3,4,5,6,2,2,1]
list.remove(2) == 3 // this removes the element at index 2, and returns it
list == [1,2,4,5,6,2,2,1]
list.removeElement(2) // remove first 2 and return true
list == [1,4,5,6,2,2,1]
! list.removeElement(8) // return false because 8 is not in the list
list == [1,4,5,6,2,2,1]
list.removeAt(1) == 4 // remove element at index 1, and return it
list == [1,5,6,2,2,1]
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:
list= ['a',2,'c',4]
list.clear()
list == []
Set operations
The Groovy development kit (http://www.groovy-lang.org/gdk.html) also includes methods making it easy to reason on sets:
'a' ['a','b','c'] // returns true if an element belongs to the list
['a','b','c'].contains('a') // equivalent to the `contains` method in Java
[1,3,4].containsAll([1,4]) // `containsAll` will check that all elements are found
[1,2,3,3,3,3,4,5].count(3) == 4 // count the number of elements which have some value
[1,2,3,3,3,3,4,5].count {
it%2==0 // count the number of elements which match the predicate
} == 2
[1,2,4,6,8,10,12].intersect([1,3,6,9,12]) == [1,6,12]
[1,2,3].disjoint( [4,6,9] )
![1,2,3].disjoint( [2,4,6] )
Sorting
Working with collections often implies sorting. Groovy o ers a variety of options to sort lists, from using closures to comparators,
as in the following examples:
http://docs.groovy-lang.org/latest/html/documentation/ 205/502
1/6/2019 Groovy Language Documentation
[6, 3, 9, 2, 7, 1, 5].sort() == [1, 2, 3, 5, 6, 7, 9]
list = ['abc', 'z', 'xyzuvw', 'Hello', '321']
list.sort {
it.size()
} == ['z', 'abc', '321', 'Hello', 'xyzuvw']
list2 = [7, 4, -6, -1, 11, 2, 3, -9, 5, -13]
list2.sort { a, b -> a == b ? 0 : .abs(a) < .abs(b) ? -1 : 1 } ==
[-1, 2, 3, 4, 5, -6, 7, -9, 11, -13]
mc = { a, b -> a == b ? 0 : .abs(a) < .abs(b) ? -1 : 1 }
// JDK 8+ only
// list2.sort(mc)
// assert list2 == [-1, 2, 3, 4, 5, -6, 7, -9, 11, -13]
list3 = [6, -3, 9, 2, -7, 1, 5]
.sort(list3)
list3 == [-7, -3, 1, 2, 5, 6, 9]
.sort(list3, mc)
list3 == [1, 2, -3, 5, 6, -7, 9]
Duplicating elements
The Groovy development kit (http://www.groovy-lang.org/gdk.html) also takes advantage of operator overloading to provide
methods allowing duplication of elements of a list:
[1, 2, 3] * 3 == [1, 2, 3, 1, 2, 3, 1, 2, 3]
[1, 2, 3].multiply(2) == [1, 2, 3, 1, 2, 3]
.nCopies(3, 'b') == ['b', 'b', 'b']
// nCopies from the JDK has different semantics than multiply for lists
.nCopies(2, [1, 2]) == [[1, 2], [1, 2]] //not [1,2,1,2]
Maps
Map literals
In Groovy, maps (also known as associative arrays) can be created using the map literal syntax: [:] :
map = [name: 'Gromit', likes: 'cheese', id: 1234]
map. ('name') == 'Gromit'
map. ('id') == 1234
map['name'] == 'Gromit'
map['id'] == 1234
map java.util.
emptyMap = [:]
emptyMap.size() == 0
emptyMap.put("foo", 5)
emptyMap.size() == 1
emptyMap. ("foo") == 5
Map keys are strings by default: [a:1] is equivalent to ['a':1] . This can be confusing if you de ne 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:
http://docs.groovy-lang.org/latest/html/documentation/ 206/502
1/6/2019 Groovy Language Documentation
a = 'Bob'
ages = [a: 43]
ages['Bob'] == // `Bob` is not found
ages['a'] == 43 // because `a` is a literal!
ages = [(a): 43] // now we escape `a` by using parenthesis
ages['Bob'] == 43 // and the value is found!
In addition to map literals, it is possible, to get a new copy of a map, to clone it:
map = [
simple : 123,
complex: [a: 1, b: 2]
]
map2 = map.clone()
map2. ('simple') == map. ('simple')
map2. ('complex') == map. ('complex')
map2. ('complex').put('c', 3)
map. ('complex'). ('c') == 3
The resulting map is a shallow copy of the original one, as illustrated in the previous example.
Map property notation
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 identi ers:
map = [name: 'Gromit', likes: 'cheese', id: 1234]
map.name == 'Gromit' // can be used instead of map.get('name')
map.id == 1234
emptyMap = [:]
emptyMap.size() == 0
emptyMap.foo = 5
emptyMap.size() == 1
emptyMap.foo == 5
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() :
map = [name: 'Gromit', likes: 'cheese', id: 1234]
map. ==
map. ('class') ==
map.getClass() == // this is probably what you want
map = [1 : 'a',
( ) : 'p',
( ): 'q',
( ) : 'x',
'null' : 'z']
map.containsKey(1) // 1 is not an identifier so used as is
map. ==
map. ==
map. ( ) == 'p'
map. ( ) == 'q'
map. == 'z'
map. ( ) == 'x'
Iterating on maps
As usual in the Groovy development kit (http://www.groovy-lang.org/gdk.html), 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.
http://docs.groovy-lang.org/latest/html/documentation/ 207/502
1/6/2019 Groovy Language Documentation
map = [
: 42,
: 54,
: 33
]
// `entry` is a map entry
map.each { entry ->
println "Name: $entry.key Age: $entry.value"
}
// `entry` is a map entry, `i` the index in the map
map.eachWithIndex { entry, i ->
println "$i - Name: $entry.key Age: $entry.value"
}
// Alternatively you can use key and value directly
map.each { key, value ->
println "Name: $key Age: $value"
}
// Key, value and i as the index in the map
map.eachWithIndex { key, value, i ->
println "$i - Name: $key Age: $value"
}
Manipulating maps
Adding or removing elements
Adding an element to a map can be done either using the put method, the subscript operator or using putAll :
defaults = [1: 'a', 2: 'b', 3: 'c', 4: 'd']
overrides = [2: 'z', 5: 'x', 13: 'x']
result = (defaults)
result.put(15, 't')
result[17] = 'u'
result.putAll(overrides)
result == [1: 'a', 2: 'z', 3: 'c', 4: 'd', 5: 'x', 13: 'x', 15: 't', 17: 'u']
Removing all the elements of a map can be done by calling the clear method:
m = [1:'a', 2:'b']
m. (1) == 'a'
m.clear()
m == [:]
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 :
key = 'some key'
map = [:]
gstringKey = "${key.toUpperCase()}"
map.put(gstringKey,'value')
map. ('SOME KEY') ==
Keys, values and entries
We can inspect the keys, values, and entries in a view:
http://docs.groovy-lang.org/latest/html/documentation/ 208/502
1/6/2019 Groovy Language Documentation
map = [1:'a', 2:'b', 3:'c']
entries = map.entrySet()
entries.each { entry ->
entry.key [1,2,3]
entry.value ['a','b','c']
}
keys = map.keySet()
keys == [1,2,3]
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 .
Filtering and searching
The Groovy development kit (http://www.groovy-lang.org/gdk.html) contains ltering, searching and collecting methods similar to
those found for lists:
people = [
1: [name:'Bob', age: 32, gender: 'M'],
2: [name:'Johnny', age: 36, gender: 'M'],
3: [name:'Claire', age: 21, gender: 'F'],
4: [name:'Amy', age: 54, gender:'F']
]
bob = people.find { it.value.name == 'Bob' } // find a single entry
females = people.findAll { it.value.gender == 'F' }
// both return entries, but you can use collect to retrieve the ages for example
ageOfBob = bob.value.age
agesOfFemales = females.collect {
it.value.age
}
ageOfBob == 32
agesOfFemales == [21,54]
// but you could also use a key/pair value as the parameters of the closures
agesOfMales = people.findAll { id, person ->
person.gender == 'M'
}.collect { id, person ->
person.age
}
agesOfMales == [32, 36]
// `every` returns true if all entries match the predicate
people.every { id, person ->
person.age > 18
}
// `any` returns true if any entry matches the predicate
people.any { id, person ->
person.age == 54
}
Grouping
We can group a list into a map using some criteria:
http://docs.groovy-lang.org/latest/html/documentation/ 209/502
1/6/2019 Groovy Language Documentation
['a', 7, 'b', [2, 3]].groupBy {
it.
} == [( ) : ['a', 'b'],
( ) : [7],
( ): [[2, 3]]
]
[
[name: 'Clark', city: 'London'], [name: 'Sharma', city: 'London'],
[name: 'Maradona', city: 'LA'], [name: 'Zhang', city: 'HK'],
[name: 'Ali', city: 'HK'], [name: 'Liu', city: 'HK'],
].groupBy { it.city } == [
: [[name: 'Clark', city: 'London'],
[name: 'Sharma', city: 'London']],
LA : [[name: 'Maradona', city: 'LA']],
HK : [[name: 'Zhang', city: 'HK'],
[name: 'Ali', city: 'HK'],
[name: 'Liu', city: 'HK']],
]
Ranges
Ranges allow you to create a list of sequential values. These can be used as List since Range (http://docs.groovy-
lang.org/latest/html/api/groovy/lang/Range.html) extends java.util.List
(http://docs.oracle.com/javase/8/docs/api/java/util/List.html).
Ranges de ned with the .. notation are inclusive (that is the list contains the from and to value).
Ranges de ned with the ..< notation are half-open, they include the rst value but not the last value.
// an inclusive range
range = 5..8
range.size() == 4
range. (2) == 7
range[2] == 7
range java.util.
range.contains(5)
range.contains(8)
// lets use a half-open range
range = 5..<8
range.size() == 3
range. (2) == 7
range[2] == 7
range java.util.
range.contains(5)
!range.contains(8)
//get the end points of the range without using indexes
range = 1..10
range. == 1
range.to == 10
Note that int ranges are implemented e ciently, 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:
http://docs.groovy-lang.org/latest/html/documentation/ 210/502
1/6/2019 Groovy Language Documentation
// an inclusive range
range = 'a'..'d'
range.size() == 4
range. (2) == 'c'
range[2] == 'c'
range java.util.
range.contains('a')
range.contains('d')
!range.contains('e')
You can iterate on a range using a classic for loop:
(i 1..10) {
println "Hello ${i}"
}
but alternatively you can achieve the same e ect in a more Groovy idiomatic style, by iterating a range with each method:
(1..10).each { i ->
println "Hello ${i}"
}
Ranges can be also used in the switch statement:
(years) {
1..10: interestRate = 0.076; ;
11..25: interestRate = 0.052; ;
: interestRate = 0.037;
}
Syntax enhancements for collections
GPath support
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:
listOfMaps = [['a': 11, 'b': 12], ['a': 21, 'b': 22]]
listOfMaps.a == [11, 21] //GPath notation
listOfMaps*.a == [11, 21] //spread dot notation
listOfMaps = [['a': 11, 'b': 12], ['a': 21, 'b': 22], ]
listOfMaps*.a == [11, 21, ] // caters for null values
listOfMaps*.a == listOfMaps.collect { it?.a } //equivalent notation
// But this will only collect non-null values
listOfMaps.a == [11,21]
Spread operator
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:
http://docs.groovy-lang.org/latest/html/documentation/ 211/502
1/6/2019 Groovy Language Documentation
[ 'z': 900,
*: ['a': 100, 'b': 200], 'a': 300] == ['a': 300, 'b': 200, 'z': 900]
//spread map notation in map definition
[*: [3: 3, *: [5: 5]], 7: 7] == [3: 3, 5: 5, 7: 7]
f = { [1: 'u', 2: 'v', 3: 'w'] }
[*: f(), 10: 'zz'] == [1: 'u', 10: 'zz', 2: 'v', 3: 'w']
//spread map notation in function arguments
f = { map -> map.c }
f(*: ['a': 10, 'b': 20, 'c': 30], 'e': 50) == 30
f = { m, i, j, k -> [m, i, j, k] }
//using spread map notation with mixed unnamed and named arguments
f('e': 100, *[4, 5], *: ['a': 10, 'b': 20, 'c': 30], 6) ==
[["e": 100, "b": 20, "c": 30, "a": 10], 4, 5, 6]
The star-dot `*.' operator
The "star-dot" operator is a shortcut operator allowing you to call a method or a property on all elements of a collection:
[1, 3, 5] == ['a', 'few', 'words']*.size()
{
name
age
}
persons = [ (name:'Hugo', age:17), (name:'Sandra',age:19)]
[17, 19] == persons*.age
Slicing with the subscript operator
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:
text = 'nice cheese gromit!'
x = text[2]
x == 'c'
x. ==
= text[5..10]
== 'cheese'
list = [10, 11, 12, 13]
answer = list[2,3]
answer == [12,13]
Notice that you can use ranges to extract part of a collection:
list = 100..200
= list[1, 3, 20..25, 33]
== [101, 103, 120, 121, 122, 123, 124, 125, 133]
The subscript operator can be used to update an existing collection (for collection type which are not immutable):
list = ['a','x','x','d']
list[1..2] = ['b','c']
list == ['a','b','c','d']
It is worth noting that negative indices are allowed, to extract more easily from the end of a collection:
http://docs.groovy-lang.org/latest/html/documentation/ 212/502
1/6/2019 Groovy Language Documentation
text = "nice cheese gromit!"
x = text[-1]
x == "!"
You can use negative indices to count from the end of the List, array, String etc.
name = text[-7..-2]
name == "gromit"
Eventually, if you use a backwards range (the starting index is greater than the end index), then the answer is reversed.
text = "nice cheese gromit!"
name = text[3..1]
name == "eci"
Enhanced Collection Methods
In addition to lists, maps or ranges, Groovy o ers a lot of additional methods for ltering, 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 (http://www.groovy-lang.org/gdk.html) API docs and speci cally:
methods added to Iterable can be found here (http://docs.groovy-lang.org/latest/html/groovy-jdk/java/lang/Iterable.html)
methods added to Iterator can be found here (http://docs.groovy-lang.org/latest/html/groovy-jdk/java/util/Iterator.html)
methods added to Collection can be found here (http://docs.groovy-lang.org/latest/html/groovy-
jdk/java/util/Collection.html)
methods added to List can be found here (http://docs.groovy-lang.org/latest/html/groovy-jdk/java/util/List.html)
methods added to Map can be found here (http://docs.groovy-lang.org/latest/html/groovy-jdk/java/util/Map.html)
3.3.3. Working with legacy Date/Calendar types
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 eld numbers
from the Calendar class as shown in the following example:
java.util. .* 1
cal = .instance
cal[YEAR] = 2000 2
cal[MONTH] = JANUARY 2
cal[DAY_OF_MONTH] = 1 2
cal[DAY_OF_WEEK] == SATURDAY 3
1 Import the constants
2 Setting the calendar’s year, month and day of month
3 Accessing the calendar’s day of week
Groovy supports arithmetic on and iteration between Date and Calendar instances as shown in the following example:
http://docs.groovy-lang.org/latest/html/documentation/ 213/502
1/6/2019 Groovy Language Documentation
utc = .getTimeZone('UTC')
date = .parse("yyyy-MM-dd HH:mm", "2010-05-23 09:01", utc)
prev = date - 1
= date + 1
diffInDays = - prev
diffInDays == 2
count = 0
prev.upto( ) { count++ }
count == 3
You can parse strings into dates and output dates into formatted strings:
orig = '2000-01-01'
newYear = .parse('yyyy-MM-dd', orig)
newYear[DAY_OF_WEEK] == SATURDAY
newYear.format('yyyy-MM-dd') == orig
newYear.format('dd/MM/yyyy') == '01/01/2000'
You can also create a new Date or Calendar based on an existing one:
newYear = .parse('yyyy-MM-dd', '2000-01-01')
newYearsEve = newYear.copyWith(
year: 1999,
month: DECEMBER,
dayOfMonth: 31
)
newYearsEve[DAY_OF_WEEK] == FRIDAY
3.3.4. Working with Date/Time types
The groovy-datetime module supports numerous extensions for working with the Date/Time API
(http://www.oracle.com/technetwork/articles/java/jf14-date-time-2125367.html) introduced in Java 8. This documentation refers to
the data types de ned by this API as "JSR 310 types."
Formatting and parsing
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:
Method Description
getDateString() For LocalDate and LocalDateTime , formats with DateTimeFormatter.ISO_LOCAL_DATE
(https://docs.oracle.com/javase/8/docs/api/java/time/format/DateTimeFormatter.html#ISO_LOCAL_DATE)
For OffsetDateTime , formats with DateTimeFormatter.ISO_OFFSET_DATE
(https://docs.oracle.com/javase/8/docs/api/java/time/format/DateTimeFormatter.html#ISO_OFFSET_DATE)
For ZonedDateTime , formats with DateTimeFormatter.ISO_LOCAL_DATE
(https://docs.oracle.com/javase/8/docs/api/java/time/format/DateTimeFormatter.html#ISO_LOCAL_DATE) an
appends the ZoneId short name
getDateTimeString() For LocalDateTime , formats with DateTimeFormatter.ISO_LOCAL_DATE_TIME
(https://docs.oracle.com/javase/8/docs/api/java/time/format/DateTimeFormatter.html#ISO_LOCAL_DATE_TIM
For OffsetDateTime , formats with DateTimeFormatter.ISO_OFFSET_DATE_TIME
(https://docs.oracle.com/javase/8/docs/api/java/time/format/DateTimeFormatter.html#ISO_OFFSET_DATE_TI
For ZonedDateTime , formats with DateTimeFormatter.ISO_LOCAL_DATE_TIME
(https://docs.oracle.com/javase/8/docs/api/java/time/format/DateTimeFormatter.html#ISO_LOCAL_DATE_TIM
and appends the ZoneId short name
http://docs.groovy-lang.org/latest/html/documentation/ 214/502
1/6/2019 Groovy Language Documentation
Method Description
getTimeString() For LocalTime and LocalDateTime , formats with DateTimeFormatter.ISO_LOCAL_TIME
(https://docs.oracle.com/javase/8/docs/api/java/time/format/DateTimeFormatter.html#ISO_LOCAL_TIME)
For OffsetTime and OffsetDateTime , formats with DateTimeFormatter.ISO_OFFSET_TIME
(https://docs.oracle.com/javase/8/docs/api/java/time/format/DateTimeFormatter.html#ISO_OFFSET_TIME)
formatter
For ZonedDateTime , formats with DateTimeFormatter.ISO_LOCAL_TIME
(https://docs.oracle.com/javase/8/docs/api/java/time/format/DateTimeFormatter.html#ISO_LOCAL_TIME) an
appends the ZoneId short name
format(FormatStyle style) For LocalTime and OffsetTime , formats with DateTimeFormatter.ofLocalizedTime(style)
(https://docs.oracle.com/javase/8/docs/api/java/time/format/DateTimeFormatter.html#ofLocalizedTime-
java.time.format.FormatStyle-)
For LocalDate , formats with DateTimeFormatter.ofLocalizedDate(style)
(https://docs.oracle.com/javase/8/docs/api/java/time/format/DateTimeFormatter.html#ofLocalizedDate-
java.time.format.FormatStyle-)
For LocalDateTime , OffsetDateTime , and ZonedDateTime formats with
DateTimeFormatter.ofLocalizedDateTime(style)
(https://docs.oracle.com/javase/8/docs/api/java/time/format/DateTimeFormatter.html#ofLocalizedDateTime
java.time.format.FormatStyle-)
format(String pattern) Formats with DateTimeFormatter.ofPattern(pattern)
(https://docs.oracle.com/javase/8/docs/api/java/time/format/DateTimeFormatter.html#ofPattern-
java.lang.String-)
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 de ned by the java.time.format.DateTimeFormatter API
(https://docs.oracle.com/javase/8/docs/api/java/time/format/DateTimeFormatter.html). As an example:
date = .parse('Jun 3, 04', 'MMM d, yy')
date == .of(2004, .JUNE, 3)
time = .parse('4:45', 'H:mm')
time == .of(4, 45, 0)
offsetTime = .parse('09:47:51-1234', 'HH:mm:ssZ')
offsetTime == .of(9, 47, 51, 0, .ofHoursMinutes(-12, -34))
dateTime = .parse('2017/07/11 9:47PM Pacific Standard Time', 'yyyy/MM/dd h:mma
zzzz')
dateTime == .of(
.of(2017, 7, 11),
.of(21, 47, 0),
.of('America/Los_Angeles')
)
Note that these parse methods have a di erent 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
Addition and subtraction
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.
http://docs.groovy-lang.org/latest/html/documentation/ 215/502
1/6/2019 Groovy Language Documentation
aprilFools = .of(2018, .APRIL, 1)
nextAprilFools = aprilFools + .ofDays(365) // add 365 days
nextAprilFools.year == 2019
idesOfMarch = aprilFools - .ofDays(17) // subtract 17 days
idesOfMarch.dayOfMonth == 15
idesOfMarch.month == .MARCH
Groovy provides additional plus and minus methods that accept an integer argument, enabling the above to be rewritten more
succinctly:
nextAprilFools = aprilFools + 365 // add 365 days
idesOfMarch = aprilFools - 17 // subtract 17 days
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
(https://docs.oracle.com/javase/8/docs/api/java/time/temporal/ChronoUnit.html#DAYShttp://days). Integers used with Year and
YearMonth have a unit of years (https://docs.oracle.com/javase/8/docs/api/java/time/temporal/ChronoUnit.html#YEARS) and
months (https://docs.oracle.com/javase/8/docs/api/java/time/temporal/ChronoUnit.html#MONTHS), respectively. All other types
have a unit of seconds (https://docs.oracle.com/javase/8/docs/api/java/time/temporal/ChronoUnit.html#SECONDS), such as
LocalTime , for instance:
mars = .of(12, 34, 56) // 12:34:56 pm
thirtySecondsToMars = mars - 30 // go back 30 seconds
thirtySecondsToMars.second == 26
Multiplication and division
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.
period = .ofMonths(1) * 2 // a 1-month period times 2
period.months == 2
duration = .ofSeconds(10) / 5// a 10-second duration divided by 5
duration.seconds == 2
Incrementing and decrementing
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.
year = .of(2000)
--year // decrement by one year
year.value == 1999
offsetTime = .of(0, 0, 0, 0, .UTC) // 00:00:00.000 UTC
offsetTime++ // increment by one second
offsetTime.second == 1
Negation
The Duration and Period types represent a negative or positive length of time. These can be negated with the unary -
operator.
duration = .ofSeconds(-15)
negated = -duration
negated.seconds == 15
Interacting with date/time values
http://docs.groovy-lang.org/latest/html/documentation/ 216/502
1/6/2019 Property notation Groovy Language Documentation
The getLong(TemporalField) (https://docs.oracle.com/javase/8/docs/api/java/time/temporal/TemporalAccessor.html#getLong-
java.time.temporal.TemporalField-) method of TemporalAccessor types (e.g. LocalDate , LocalTime , ZonedDateTime , etc.)
and the get(TemporalUnit) (https://docs.oracle.com/javase/8/docs/api/java/time/temporal/TemporalAmount.html#get-
java.time.temporal.TemporalUnit-) method of TemporalAmount types (namely Period and Duration ), can be invoked with
Groovy’s property notation. For example:
date = .of(2018, .MARCH, 12)
date[ .YEAR] == 2018
date[ .MONTH_OF_YEAR] == .MARCH.value
date[ .DAY_OF_MONTH] == 12
date[ .DAY_OF_WEEK] == .MONDAY.value
period = .ofYears(2).withMonths(4).withDays(6)
period[ .YEARS] == 2
period[ .MONTHS] == 4
period[ .DAYS] == 6
Ranges, upto , and downto
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.
start = .now()
= start + 6 // 6 days later
(start.. ).each { date ->
println date.dayOfWeek
}
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 value once per iteration.
start = .now()
= start + 6 // 6 days later
start.upto( ) { date ->
println date.dayOfWeek
}
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
(https://docs.oracle.com/javase/8/docs/api/java/time/temporal/ChronoUnit.html#MONTHS).
start = .of(2018, .MARCH, 2)
= start + 1 // 1 day later
iterationCount = 0
start.upto( , .MONTHS) { date ->
println date
++iterationCount
}
iterationCount == 1
Since the start date is inclusive, the closure is called with date March 1st. The upto method then increments the date by one
month, yielding the date, April 1st. Because this date is after the speci ed 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 the value of end becomes earlier than the targeted end date.
http://docs.groovy-lang.org/latest/html/documentation/ 217/502
1/6/2019 In short, when iterating with the upto or downto methods with Language
Groovy a custom unit of iteration, the current value of iteration will never
Documentation
exceed the end value.
Combining date/time values
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.
monthDay = .JUNE << 3 // June 3rd
date = monthDay << .of(2015) // 3-Jun-2015
dateTime = date << .NOON // 3-Jun-2015 @ 12pm
offsetDateTime = dateTime << .ofHours(-5) // 3-Jun-2015 @ 12pm UTC-5
The left-shift operator is re exive; the order of the operands does not matter.
year = .of(2000)
month = .DECEMBER
a = year << month
b = month << year
a == b
Creating periods and durations
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:
newYears = .of(2018, .JANUARY, 1)
aprilFools = .of(2018, .APRIL, 1)
period = newYears >> aprilFools
period
period.months == 3
The operator produces a Duration for the time-aware JSR types:
duration = .NOON >> ( .NOON + 30)
duration
duration.seconds == 30
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:
decade = .of(2010) >> .of(2000)
decade.years == -10
Converting between legacy and JSR 310 types
Despite the shortcomings of Date , Calendar , and TimeZone types in the java.util package they are farily 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 tted 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 .
http://docs.groovy-lang.org/latest/html/documentation/ 218/502
1/6/2019 Groovy Language Documentation
// LocalDate to java.util.Date
valentines = .of(2018, .FEBRUARY, 14)
valentines.toDate().format('MMMM dd, yyyy') == 'February 14, 2018'
// LocalTime to java.util.Date
noon = .of(12, 0, 0)
noon.toDate().format('HH:mm:ss') == '12:00:00'
// ZoneId to java.util.TimeZone
newYork = .of('America/New_York')
newYork.toTimeZone() == .getTimeZone('America/New_York')
// ZonedDateTime to java.util.Calendar
valAtNoonInNY = .of(valentines, noon, newYork)
valAtNoonInNY.toCalendar().getTimeZone().toZoneId() == newYork
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 O sets 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:
legacy = .parse('yyyy-MM-dd HH:mm:ss.SSS', '2010-04-03 10:30:58.999')
legacy.toLocalDate() == .of(2010, 4, 3)
legacy.toLocalTime() == .of(10, 30, 58, 999_000_000) // 999M ns = 999ms
legacy.toOffsetTime().hour == 10
legacy.toYear() == .of(2010)
legacy.toMonth() == .APRIL
legacy.toDayOfWeek() == .SATURDAY
legacy.toMonthDay() == .of( .APRIL, 3)
legacy.toYearMonth() == .of(2010, .APRIL)
legacy.toLocalDateTime().year == 2010
legacy.toOffsetDateTime().dayOfMonth == 3
legacy.toZonedDateTime().zone == .systemDefault()
3.3.5. Handy utilities
Con gSlurper
ConfigSlurper is a utility class for reading con guration les de ned in the form of Groovy scripts. Like it is the case with Java
*.properties les, ConfigSlurper allows a dot notation. But in addition, it allows for Closure scoped con guration values and
arbitrary object types.
config = ().parse('''
app.date = new Date() 1
app.age = 42
app { 2
name = "Test${42}"
}
''')
config.app.date
config.app.age == 42
config.app.name == 'Test42'
http://docs.groovy-lang.org/latest/html/documentation/ 219/502
1/6/2019 1 Usage of the dot notation Groovy Language Documentation
2 Usage of Closure scopes as an alternative to the dot notation
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 con gured value or a new
ConfigObject instance but never null .
config = ().parse('''
app.date = new Date()
app.age = 42
app.name = "Test${42}"
''')
config.test != 1
1 config.test has not been speci ed yet it returns a ConfigObject when being called.
In the case of a dot being part of a con guration variable name, it can be escaped by using single or double quotes.
config = ().parse('''
app."person.age" = 42
''')
config.app."person.age" == 42
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 con guration value for the
development environment. When creating the ConfigSlurper instance we can use the ConfigSlurper(String) constructor to
specify the target environment.
config = ('development').parse('''
environments {
development {
app.port = 8080
}
test {
app.port = 8082
}
production {
app.port = 80
}
}
''')
config.app.port == 8080
The ConfigSlurper environments aren’t restricted to any particular environment names. It solely depends on
the ConfigSlurper client code what value are supported and interpreted accordingly.
The environments method is built-in but the registerConditionalBlock method can be used to register other method names
in addition to the environments name.
http://docs.groovy-lang.org/latest/html/documentation/ 220/502
1/6/2019 Groovy Language Documentation
slurper = ()
slurper.registerConditionalBlock('myProject', 'developers') 1
config = slurper.parse('''
sendMail = true
myProject {
developers {
sendMail = false
}
}
''')
!config.sendMail
1 Once the new block is registered ConfigSlurper can parse it.
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 le. Be aware though that the con guration values
are converted to String instances during adding them to the newly created Properties instance.
config = ().parse('''
app.date = new Date()
app.age = 42
app {
name = "Test${42}"
}
''')
properties = config.toProperties()
properties."app.date"
properties."app.age" == '42'
properties."app.name" == 'Test42'
Expando
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.
expando = ()
expando.name = 'John'
expando.name == 'John'
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.
expando = ()
expando.toString = { -> 'John' }
expando.say = { s -> "John says: ${s}" }
expando == 'John'
expando.say('Hi') == 'John says: Hi'
Observable list, map and set
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 re more specialized PropertyChangeEvent
types. For example, adding an element to an observable list res an ObservableList.ElementAddedEvent event.
http://docs.groovy-lang.org/latest/html/documentation/ 221/502
1/6/2019 Groovy Language Documentation
1
listener = {
(it . ) { 2
= it
}
}
observable = [1, 2, 3] 3
observable.addPropertyChangeListener(listener) 4
observable.add 42 5
elementAddedEvent = .
elementAddedEvent.changeType == . .ADDED
elementAddedEvent.index == 3
elementAddedEvent.oldValue ==
elementAddedEvent.newValue == 42
1 Declares a PropertyChangeEventListener that is capturing the red events
2 ObservableList.ElementEvent and its descendant types are relevant for this listener
3 Registers the listener
4 Creates an ObservableList from the given list
5 Triggers an ObservableList.ElementAddedEvent event
Be aware that adding an element in fact causes two events to be triggered. The rst is of type
ObservableList.ElementAddedEvent , the second is a plain PropertyChangeEvent that informs listeners about
the change of property size .
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.
listener = {
(it . ) {
= it
}
}
observable = [1, 2, 3]
observable.addPropertyChangeListener(listener)
observable.clear()
elementClearedEvent = .
elementClearedEvent.values == [1, 2, 3]
observable.size() == 0
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
http://docs.groovy-lang.org/latest/html/documentation/ 222/502
1/6/2019 The Groovy language supports two avors of metaprogramming: runtime and
Groovy Language compile-time. The rst allows altering the class
Documentation
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 di erent 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 (http://docs.groovy-lang.org/2.5.5/html/gapi/index.html?groovy/lang/GroovyObject.html) interface
by default.
Groovy Interceptor - A Groovy object that implements the groovy.lang.GroovyInterceptable (http://docs.groovy-
lang.org/2.5.5/html/gapi/index.html?groovy/lang/GroovyInterceptable.html) 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 (http://docs.groovy-lang.org/2.5.5/html/gapi/index.html?groovy/lang/MetaClassRegistry.html) and
delegates method invocation to it. For POGOs, Groovy takes more steps, as illustrated in the following gure:
Figure 1. Groovy interception mechanism
GroovyObject interface
groovy.lang.GroovyObject (http://docs.groovy-lang.org/2.5.5/html/gapi/index.html?groovy/lang/GroovyObject.html) is the main
interface in Groovy as the Object class is in Java. GroovyObject has a default implementation in the
groovy.lang.GroovyObjectSupport (http://docs.groovy-lang.org/2.5.5/html/gapi/index.html?
groovy/lang/GroovyObjectSupport.html) class and it is responsible to transfer invocation to the groovy.lang.MetaClass
(http://docs.groovy-lang.org/2.5.5/html/gapi/index.html?groovy/lang/MetaClass.html) object. The GroovyObject source looks like
this:
http://docs.groovy-lang.org/latest/html/documentation/ 223/502
1/6/2019 Groovy Language Documentation
groovy.lang;
invokeMethod( name, args);
getProperty( propertyName);
setProperty( propertyName, newValue);
getMetaClass();
setMetaClass( metaClass);
}
invokeMethod
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:
invokeMethod( name, args) {
"called invokeMethod $name $args"
}
test() {
'method exists'
}
}
someGroovyClass = ()
someGroovyClass.test() == 'method exists'
someGroovyClass.someMethod() == 'called invokeMethod someMethod []'
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.
get/setProperty
Every read access to a property can be intercepted by overriding the getProperty() method of the current object. Here is a
simple example:
http://docs.groovy-lang.org/latest/html/documentation/ 224/502
1/6/2019 Groovy Language Documentation
{
property1 = 'ha'
field2 = 'ho'
field4 = 'hu'
getField1() {
'getHa'
}
getProperty( name) {
(name != 'field3')
metaClass.getProperty( , name) 1
'field3'
}
}
someGroovyClass = ()
someGroovyClass.field1 == 'getHa'
someGroovyClass.field2 == 'ho'
someGroovyClass.field3 == 'field3'
someGroovyClass.field4 == 'hu'
1 Forwards the request to the getter for all properties except field3 .
You can intercept write access to properties by overriding the setProperty() method:
POGO {
setProperty( name, value) {
.@"$name" = 'overridden'
}
}
pogo = POGO()
pogo. = 'a'
pogo. == 'overridden'
get/setMetaClass
You can a 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:
// getMetaclass
someObject.metaClass
// setMetaClass
someObject.metaClass = ()
You can nd an additional example in the GroovyInterceptable topic.
get/setAttribute
This functionality is related to the MetaClass implementation. In the default implementation you can access elds without
invoking their getters and setters. The examples below demonstrates this approach:
http://docs.groovy-lang.org/latest/html/documentation/ 225/502
1/6/2019 Groovy Language Documentation
{
field1 = 'ha'
field2 = 'ho'
getField1() {
'getHa'
}
}
someGroovyClass = ()
someGroovyClass.metaClass.getAttribute(someGroovyClass, 'field1') == 'ha'
someGroovyClass.metaClass.getAttribute(someGroovyClass, 'field2') == 'ho'
POGO {
field
property1
setProperty1( property1) {
.property1 = "setProperty1"
}
}
pogo = POGO()
pogo.metaClass.setAttribute(pogo, 'field', 'ha')
pogo.metaClass.setAttribute(pogo, 'property1', 'ho')
pogo.field == 'ha'
pogo.property1 == 'ho'
methodMissing
Groovy supports the concept of methodMissing . This method di ers 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:
methodMissing( name, args) {
"this is me"
}
}
().someUnknownMethod(42l) == 'this is me'
Typically when using methodMissing it is possible to cache the result for the next time the same method is called.
For example, consider dynamic nders in GORM. These are implemented in terms of methodMissing . The code resembles
something like this:
http://docs.groovy-lang.org/latest/html/documentation/ 226/502
1/6/2019 Groovy Language Documentation
GORM {
dynamicMethods = [...] // an array of dynamic methods that use regex
methodMissing( name, args) {
method = dynamicMethods.find { it.match(name) }
(method) {
GORM.metaClass."$name" = { [] varArgs ->
method.invoke( , name, varArgs)
}
method.invoke( ,name, args)
}
(name, , args)
}
}
Notice how, if we nd a method to invoke, we then dynamically register a new method on the y using ExpandoMetaClass. This is
so that the next time the same method is called it is more e cient. This way of using methodMissing does not have the
overhead of invokeMethod and is not expensive from the second call on.
propertyMissing
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:
{
propertyMissing( name) { name }
}
().boo == 'boo'
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 de nition can be added that takes an additional value argument:
{
storage = [:]
propertyMissing( name, value) { storage[name] = value }
propertyMissing( name) { storage[name] }
}
f = ()
f.foo = "bar"
f.foo == "bar"
As with methodMissing it is best practice to dynamically register new properties at runtime to improve the overall lookup
performance.
static methodMissing
Static variant of methodMissing method can be added via the ExpandoMetaClass or can be implemented at the class level with
$static_methodMissing method.
{
$static_methodMissing( name, args) {
"Missing static method name is $name"
}
}
.bar() == 'Missing static method name is bar'
static propertyMissing
http://docs.groovy-lang.org/latest/html/documentation/ 227/502
1/6/2019 Static variant of propertyMissing method can be addedGroovy
via theLanguage
ExpandoMetaClass or can be implemented at the class level with
Documentation
$static_propertyMissing method.
{
$static_propertyMissing( name) {
"Missing static property name is $name"
}
}
.foobar == 'Missing static property name is foobar'
GroovyInterceptable
The groovy.lang.GroovyInterceptable (http://docs.groovy-lang.org/2.5.5/html/gapi/index.html?
groovy/lang/GroovyInterceptable.html) 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.
groovy.lang;
{
}
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:
definedMethod() { }
invokeMethod( name, args) {
'invokedMethod'
}
}
The next piece of code is a test which shows that both calls to existing and non-existing methods will return the same value.
testCheckInterception() {
interception = ()
interception.definedMethod() == 'invokedMethod'
interception.someMethod() == 'invokedMethod'
}
}
We cannot use default groovy methods like println because these methods are injected into all Groovy objects
so they will be intercepted too.
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:
http://docs.groovy-lang.org/latest/html/documentation/ 228/502
1/6/2019 Groovy Language Documentation
{
testPOJOMetaClassInterception() {
invoking = 'ha'
invoking.metaClass.invokeMethod = { name, args ->
'invoked'
}
invoking.length() == 'invoked'
invoking.someMethod() == 'invoked'
}
testPOGOMetaClassInterception() {
entity = ('Hello')
entity.metaClass.invokeMethod = { name, args ->
'invoked'
}
entity.build( ()) == 'invoked'
entity.someMethod() == 'invoked'
}
}
Additional information about MetaClass can be found in the MetaClasses section.
Categories
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-de ned
rules for de ning 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 (http://docs.groovy-lang.org/2.5.5/html/gapi/index.html?groovy/time/TimeCategory.html)
groovy.servlet.ServletCategory (http://docs.groovy-lang.org/2.5.5/html/gapi/index.html?groovy/servlet/ServletCategory.html)
groovy.xml.dom.DOMCategory (http://docs.groovy-lang.org/2.5.5/html/gapi/index.html?groovy/xml/dom/DOMCategory.html)
Category classes aren’t enabled by default. To use the methods de ned 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:
( ) {
println 1.minute. .now 1
println 10.hours.ago
someDate = () 2
println someDate - 3.months
}
1 TimeCategory adds methods to Integer
2 TimeCategory adds methods to Date
The use method takes the category class as its rst 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-de ned methods.
A category needs not to be directly exposed to the user code, the following will also do:
http://docs.groovy-lang.org/latest/html/documentation/ 229/502
1/6/2019 Groovy Language Documentation
{
// Let's enhance JPA EntityManager without getting into the JSR committee
persistAll( em , [] entities) { //add an interface to save all
entities?.each { em.persist(it) }
}
}
transactionContext = {
em, c ->
tx = em.transaction
{
tx. ()
( ) {
c()
}
tx.commit()
} (e) {
tx.rollback()
} {
//cleanup your resource here
}
}
// user code, they always forget to close resource in exception, some even forget to commit, let's
not rely on them.
em; //probably injected
transactionContext (em) {
em.persistAll(obj1, obj2, obj3)
// let's do some logics here to make the example sensible
em.persistAll(obj2, obj4, obj6)
}
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:
plus( date, duration) {
duration.plus(date);
}
minus( date, duration) {
cal = .getInstance();
cal.setTime(date);
cal.add( .YEAR, -duration.getYears());
cal.add( .MONTH, -duration.getMonths());
cal.add( .DAY_OF_YEAR, -duration.getDays());
cal.add( .HOUR_OF_DAY, -duration.getHours());
cal.add( .MINUTE, -duration.getMinutes());
cal.add( .SECOND, -duration.getSeconds());
cal.add( .MILLISECOND, -duration.getMillis());
cal.getTime();
}
// ...
Another requirement is the rst argument of the static method must de ne 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 de nitions may be a bit less intuitive than normal
method de nitions. As an alternative Groovy comes with a @Category annotation that transforms annotated classes into
category classes at compile-time.
http://docs.groovy-lang.org/latest/html/documentation/ 230/502
1/6/2019 Groovy Language Documentation
{
number
toString() { "${number}m" }
}
@Category( )
{
getMeters() {
(number: )
}
}
( ) {
42.meters.toString() == '42m'
}
Applying the @Category annotation has the advantage of being able to use instance methods without the target type as a rst
parameter. The target type class is given as an argument to the annotation instead.
There is a distinct section on @Category in the compile-time metaprogramming section.
Metaclasses
As explained earlier, Metaclasses play a central role in method resolution. For every method invocation from groovy code, Groovy
will nd the MetaClass for the given object and delegate the method resolution to the metaclass via MetaClass#invokeMethod
(http://docs.groovy-lang.org/2.5.5/html/gapi/groovy/lang/MetaClass.html#invokeMethod(java.lang.Class, java.lang.Object,
java.lang.String, java.lang.Object, boolean, boolean)) which should not be confused with GroovyObject#invokeMethod
(http://docs.groovy-lang.org/2.5.5/html/gapi/groovy/lang/GroovyObject.html#invokeMethod(java.lang.String, java.lang.Object))
which happens to be a method that the metaclass may eventually call.
The default metaclass MetaClassImpl
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 GroovyObject#invokeMethod (http://docs.groovy-
lang.org/2.5.5/html/gapi/groovy/lang/GroovyObject.html#invokeMethod(java.lang.String, java.lang.Object))
{}
f = ()
f.metaClass =~ / /
Custom metaclasses
You can change the metaclass of any object or class and replace with a custom implementation of the MetaClass interface
(http://docs.groovy-lang.org/2.5.5/html/gapi/index.html?groovy/lang/MetaClass.html). Usually you will want to subclass one of the
existing metaclasses MetaClassImpl , DelegatingMetaClass , ExpandoMetaClass , ProxyMetaClass , etc. otherwise you will
need to implement the complete method lookup logic. Before using a new metaclass instance you should call
groovy.lang.MetaClass#initialize() (http://docs.groovy-lang.org/2.5.5/html/gapi/groovy/lang/MetaClass.html#initialize()) otherwise
the metaclass may or may not behave as expected.
Delegating metaclass
If you only need to decorate an existing metaclass the DelegatingMetaClass simpli es that use case. The old metaclass
implementation is still accessible via super making easy to apply pretransformations to the inputs, routing to other methods and
postprocess the outputs.
http://docs.groovy-lang.org/latest/html/documentation/ 231/502
1/6/2019 Groovy Language Documentation
{ bar() { "bar" } }
{
( metaClass) { (metaClass) }
( theClass) { (theClass) }
invokeMethod( , methodName, [] args) {
result = .invokeMethod( ,methodName.toLowerCase(), args)
result.toUpperCase();
}
}
mc = ( .metaClass)
mc.initialize()
.metaClass = mc
f = ()
f.BAR() == "BAR" // the new metaclass routes .BAR() to .bar() and uppercases the result
Magic package
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 to 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 :
// file: IntegerMetaClass.groovy
groovy.runtime.metaclass.java.lang;
{
( metaClass) { (metaClass) }
( theClass) { (theClass) }
invokeMethod( , name, [] args) {
(name =~ /isBiggerThan/) {
other = name.split(/isBiggerThan/)[1].toInteger()
> other
} {
.invokeMethod( ,name, args);
}
}
}
By compiling the above le with groovyc IntegerMetaClass.groovy a
./groovy/runtime/metaclass/java/lang/IntegerMetaClass.class will be generated. The example below will use this new
metaclass:
// File testInteger.groovy
i = 10
i.isBiggerThan5()
!i.isBiggerThan15()
println i.isBiggerThan5()
By running that le 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.
Per instance metaclass
You can change the metaclass of individual objects separately, so it’s possible to have multiple object of the same class with
di erent metaclasses.
http://docs.groovy-lang.org/latest/html/documentation/ 232/502
1/6/2019 Groovy Language Documentation
{ bar() { "bar" }}
{
( metaClass) { (metaClass) }
invokeMethod( , name, [] args) {
.invokeMethod( ,name,args).toUpperCase()
}
}
f1 = ()
f2 = ()
f2.metaClass = (f2.metaClass)
f1.bar() == "bar"
f2.bar() == "BAR"
f1.metaClass =~ / /
f2.metaClass =~ / /
f1. .toString() == "class Foo"
f2. .toString() == "class Foo"
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 modi cations 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.
By default ExpandoMetaClass doesn’t do inheritance. To enable this you must call
ExpandoMetaClass#enableGlobally() before your app starts such as in the main method or servlet bootstrap.
The following sections go into detail on how ExpandoMetaClass can be used in various scenarios.
Methods
Once the ExpandoMetaClass is accessed by calling the metaClass property, methods can added by using either the left shift <<
or the = operator.
Note that the left shift operator is used to append a new method. If a public method with the same name and
parameter types is declared by the class or interface, including those inherited from superclasses and
superinterfaces but excluding those added to the metaClass at runtime, an exception will be thrown. If you want
to replace a method declared by the class or interface you can use the = operator.
The operators are applied on a non-existent property of metaClass passing an instance of a Closure code block.
{
title
}
.metaClass.titleInUpperCase << {-> title.toUpperCase() }
b = (title:"The Stand")
"THE STAND" == b.titleInUpperCase()
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.
Properties
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 :
http://docs.groovy-lang.org/latest/html/documentation/ 233/502
1/6/2019 Groovy Language Documentation
{
title
}
.metaClass.author = "Stephen King"
b = ()
"Stephen King" == b.author
Another way is to add getter and/or setter methods by using the standard mechanisms for adding instance methods.
{
title
}
.metaClass.getAuthor << {-> "Stephen King" }
b = ()
"Stephen King" == b.author
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.
{
title
}
properties = .synchronizedMap([:])
.metaClass.setAuthor = { value ->
properties[ .identityHashCode( ) + "author"] = value
}
.metaClass.getAuthor = {->
properties[ .identityHashCode( ) + "author"]
}
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
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.
{
title
}
.metaClass.constructor << { title -> (title:title) }
book = ('Groovy in Action - 2nd Edition')
book.title == 'Groovy in Action - 2nd Edition'
Be careful when adding constructors however, as it is very easy to get into stack over ow troubles.
Static Methods
Static methods can be added using the same technique as instance methods with the addition of the static quali er before the
method name.
http://docs.groovy-lang.org/latest/html/documentation/ 234/502
1/6/2019 Groovy Language Documentation
{
title
}
.metaClass. .create << { title -> (title:title) }
b = .create("The Stand")
Borrowing Methods
With ExpandoMetaClass it is possible to use Groovy’s method pointer syntax to borrow methods from other classes.
{
name
}
{
borrowMoney() {
"buy house"
}
}
lender = ()
.metaClass.buyHouse = lender.&borrowMoney
p = ()
"buy house" == p.buyHouse()
Dynamic Method Names
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.
{
name = "Fred"
}
methodName = "Bob"
.metaClass."changeNameTo${methodName}" = {-> .name = "Bob" }
p = ()
"Fred" == p.name
p.changeNameToBob()
"Bob" == p.name
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.
HTMLCodec Class
{
encode = { theTarget ->
.htmlEscape(theTarget.toString())
}
decode = { theTarget ->
.htmlUnescape(theTarget.toString())
}
}
http://docs.groovy-lang.org/latest/html/documentation/ 235/502
1/6/2019 The example above shows a codec implementation. GrailsGroovy
comesLanguage
with various codec implementations each de ned in a single
Documentation
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 meta-classes where XXX is the rst part of the codec class name (e.g.
encodeHTML ). This mechanism is in the following shown in some Groovy pseudo-code:
codecs = classes.findAll { it.name.endsWith('Codec') }
codecs.each { codec ->
.metaClass."encodeAs${codec.name-'Codec'}" = { codec.newInstance().encode( ) }
.metaClass."decodeFrom${codec.name-'Codec'}" = { codec.newInstance().decode( ) }
}
html = '<html><body>hello</body></html>'
'<html><body>hello</body></html>' == html.encodeAsHTML()
Runtime Discovery
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 re ection? Well because Groovy is di erent, 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 .
GroovyObject Methods
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 :
{
invokeMe() { "foo" }
}
.metaClass.invokeMethod = { name, args ->
metaMethod = .metaClass.getMetaMethod(name, args)
result
(metaMethod) result = metaMethod.invoke( ,args)
{
result = "bar"
}
result
}
stf = ()
"foo" == stf.invokeMe()
"bar" == stf.doStuff()
The rst step in the Closure code is to lookup the MetaMethod for the given name and arguments. If the method can be found
everything is ne and it is delegated to. If not, a dummy value is returned.
A MetaMethod is a method that is known to exist on the MetaClass whether added at runtime or at compile-
time.
http://docs.groovy-lang.org/latest/html/documentation/ 236/502
1/6/2019 The same logic can be used to override setProperty or Groovy
getProperty . Documentation
Language
{
name = "Fred"
}
.metaClass.getProperty = { name ->
metaProperty = .metaClass.getMetaProperty(name)
result
(metaProperty) result = metaProperty.getProperty( )
{
result = "Flintstone"
}
result
}
p = ()
"Fred" == p.name
"Flintstone" == p.other
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.
Overriding Static invokeMethod
ExpandoMetaClass even allows for overriding static method with a special invokeMethod syntax.
{
invokeMe() { "foo" }
}
.metaClass.'static'.invokeMethod = { name, args ->
metaMethod = .metaClass.getStaticMetaMethod(name, args)
result
(metaMethod) result = metaMethod.invoke( ,args)
{
result = "bar"
}
result
}
"foo" == .invokeMe()
"bar" == .doStuff()
The logic that is used for overriding the static method is the same as we’ve seen before for overriding instance methods. The only
di erence is the access to the metaClass.static property and the call to getStaticMethodName for retrieving the static
MetaMethod instance.
Extending Interfaces
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.
.metaClass.sizeDoubled = {-> .size() * 2 }
list = []
list << 1
list << 2
4 == list.sizeDoubled()
Extension modules
Extending existing classes
http://docs.groovy-lang.org/latest/html/documentation/ 237/502
1/6/2019 An extension module allows you to add new methods to existing classes, including
Groovy Language classes which are precompiled, like classes
Documentation
from the JDK. Those new methods, unlike those de ned through a metaclass or using a category, are available globally. For
example, when you write:
Standard extension method
file = (...)
contents = file.getText('utf-8')
The getText method doesn’t exist on the File class. However, Groovy knows it because it is de ned in a special class,
ResourceGroovyMethods :
ResourceGroovyMethods.java
getText( file, charset) {
.getText(newReader(file, charset));
}
You may notice that the extension method is de ned using a static method in a helper class (where various extension methods
are de ned). The rst argument of the getText method corresponds to the receiver, while additional parameters correspond to
the arguments of the extension method. So here, we are de ning a method called getText on the File class (because the rst
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 le
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)
Instance methods
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:
MaxRetriesExtension.groovy
http://docs.groovy-lang.org/latest/html/documentation/ 238/502
1/6/2019 Groovy Language Documentation
{ 1
maxRetries( , code) { 2
>= 0
retries =
e =
(retries > 0) {
{
code.call()
} ( err) {
e = err
retries--
}
}
(retries == 0 && e) {
e
}
}
}
1 The extension class
2 First argument of the static method corresponds to the receiver of the message, that is to say the extended instance
Then, after having declared your extension class, you can call it this way:
i=0
5.maxRetries {
i++
}
i == 1
i=0
{
5.maxRetries {
i++
("oops")
}
} ( e) {
i == 5
}
Static methods
It is also possible to add static methods to a class. In that case, the static method needs to be de ned in its own le. Static and
instance extension methods cannot be present in the same class.
StaticStringExtension.groovy
{ 1
greeting( ) { 2
'Hello, world!'
}
}
1 The static extension class
2 First argument of the static method corresponds to the class being extended and is unused
In which case you can call it directly on the String class:
.greeting() == 'Hello, world!'
Module descriptor
For Groovy to be able to load your extension methods, you must declare your extension helper classes. You must create a le
named org.codehaus.groovy.runtime.ExtensionModule into the META-INF/groovy directory:
http://docs.groovy-lang.org/latest/html/documentation/ 239/502
1/6/2019 org.codehaus.groovy.runtime.ExtensionModule Groovy Language Documentation
moduleName=Test module for specifications
moduleVersion=1.0-test
extensionClasses=support.MaxRetriesExtension
staticExtensionClasses=support.StaticStringExtension
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 di erent 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 de ne both static helpers and instance helpers, and that you may add several classes
to a single module. You can also extend di erent classes in a single module without problem. It is even possible to use di erent
classes in a single extension class, but it is recommended to group extension methods into classes by feature set.
Extension modules and classpath
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.
Compatibility with type checking
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 le 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 di erent 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 nd a list of local AST transformations available for you to
use in your code here:
http://docs.groovy-lang.org/latest/html/documentation/ 240/502
1/6/2019 Code generation transformations Groovy Language Documentation
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.
@groovy.transform.ToString
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:
groovy.transform.
@ToString
{
firstName
lastName
}
With this de nition, then the following assertion passes, meaning that a toString method taking the eld values from the class
and printing them out has been generated:
p = (firstName: 'Jack', lastName: 'Nicholson')
p.toString() == 'Person(Jack, Nicholson)'
The @ToString annotation accepts several parameters which are summarized in the following table:
Attribute Default value Description Example
excludes Empty list List of properties to exclude
@ToString(excludes=['firstName'])
from toString
{
firstName
lastName
}
p = (firstName: 'Jack',
lastName: 'Nicholson')
p.toString() ==
'Person(Nicholson)'
includes Unde ned List of elds to include in
@ToString(includes=['lastName'])
marker list toString
{
(indicates all firstName
elds) lastName
}
p = (firstName: 'Jack',
lastName: 'Nicholson')
p.toString() ==
'Person(Nicholson)'
http://docs.groovy-lang.org/latest/html/documentation/ 241/502
1/6/2019 Groovy Language Documentation
Attribute Default value Description Example
includeSuper False Should superclass be
@ToString
included in toString
{ id }
@ToString(includeSuper= )
{
firstName
lastName
}
p = (id:1, firstName:
'Jack', lastName: 'Nicholson')
p.toString() == 'Person(Jack,
Nicholson, Id(1))'
includeNames false Whether to include names of
@ToString(includeNames= )
properties in generated
{
toString. firstName
lastName
}
p = (firstName: 'Jack',
lastName: 'Nicholson')
p.toString() ==
'Person(firstName:Jack,
lastName:Nicholson)'
includeFields False Should elds be included in
@ToString(includeFields= )
toString, in addition to
{
properties firstName
lastName
age
test() {
age = 42
}
}
p = (firstName: 'Jack',
lastName: 'Nicholson')
p.test()
p.toString() == 'Person(Jack,
Nicholson, 42)'
includeSuperProperties False Should super properties be
{
included in toString
name
}
@ToString(includeSuperProperties =
, includeNames = )
{
bandName
}
bono = (name:'Bono',
bandName: 'U2').toString()
bono.toString() ==
'BandMember(bandName:U2, name:Bono)'
http://docs.groovy-lang.org/latest/html/documentation/ 242/502
1/6/2019 Groovy Language Documentation
Attribute Default value Description Example
includeSuperFields False Should visible super elds be
{
included in toString
name
}
@ToString(includeSuperFields = ,
includeNames = )
@MapConstructor(includeSuperFields =
)
{
bandName
}
bono = (name:'Bono',
bandName: 'U2').toString()
bono.toString() ==
'BandMember(bandName:U2, name:Bono)'
ignoreNulls False Should properties/ elds with
@ToString(ignoreNulls= )
null value be displayed
{
firstName
lastName
}
p = (firstName: 'Jack')
p.toString() == 'Person(Jack)'
includePackage True Use fully quali ed class name
@ToString(includePackage= )
instead of simple name in
{
toString firstName
lastName
}
p = (firstName: 'Jack',
lastName:'Nicholson')
p.toString() ==
'acme.Person(Jack, Nicholson)'
allProperties True Include all JavaBean
@ToString(includeNames= )
properties in toString
{
firstName
getLastName() {
'Nicholson' }
}
p = (firstName: 'Jack')
p.toString() ==
'acme.Person(firstName:Jack,
lastName:Nicholson)'
http://docs.groovy-lang.org/latest/html/documentation/ 243/502
1/6/2019 Groovy Language Documentation
Attribute Default value Description Example
cache False Cache the toString string.
@ToString(cache= )
Should only be set to true if
{
the class is immutable. firstName
lastName
}
p = (firstName: 'Jack',
lastName:'Nicholson')
s1 = p.toString()
s2 = p.toString()
s1 == s2
s1 == 'Person(Jack,
Nicholson)'
s1. (s2) // same instance
allNames False Should elds and/or
@ToString(allNames= )
properties with internal
{
names be included in the
$firstName
generated toString }
p = ($firstName: "Jack")
p.toString() ==
'acme.Person(Jack)'
@groovy.transform.EqualsAndHashCode
The @EqualsAndHashCode AST transformation aims at generating equals and hashCode methods for you. The generated
hashcode follows the best practices as described in E ective Java by Josh Bloch:
groovy.transform.
@EqualsAndHashCode
{
firstName
lastName
}
p1 = (firstName: 'Jack', lastName: 'Nicholson')
p2 = (firstName: 'Jack', lastName: 'Nicholson')
p1==p2
p1.hashCode() == p2.hashCode()
There are several options available to tweak the behavior of @EqualsAndHashCode :
Attribute Default value Description Example
http://docs.groovy-lang.org/latest/html/documentation/ 244/502
1/6/2019 Groovy Language Documentation
Attribute Default value Description Example
excludes Empty list List of properties to exclude from
equals/hashCode
groovy.transform.
@EqualsAndHashCode(excludes=
['firstName'])
{
firstName
lastName
}
p1 = (firstName: 'Jack',
lastName: 'Nicholson')
p2 = (firstName: 'Bob',
lastName: 'Nicholson')
p1==p2
p1.hashCode() == p2.hashCode()
includes Unde ned List of elds to include in
marker list equals/hashCode
groovy.transform.
(indicating all
elds) @EqualsAndHashCode(includes=
['lastName'])
{
firstName
lastName
}
p1 = (firstName: 'Jack',
lastName: 'Nicholson')
p2 = (firstName: 'Bob',
lastName: 'Nicholson')
p1==p2
p1.hashCode() == p2.hashCode()
http://docs.groovy-lang.org/latest/html/documentation/ 245/502
1/6/2019 Groovy Language Documentation
Attribute Default value Description Example
cache False Cache the hashCode
computation. Should only be set
groovy.transform.
to true if the class is immutable. groovy.transform.
@Immutable
{
hashCode() {
sleep 100
127
}
}
@EqualsAndHashCode(cache= )
@Immutable
{
slowHashCode =
()
}
p = ()
p.hashCode()
start = .currentTimeMillis()
p.hashCode()
.currentTimeMillis() -
start < 100
callSuper False Whether to include super in
equals and hashCode calculations
groovy.transform.
@EqualsAndHashCode
{
race
}
@EqualsAndHashCode(callSuper= )
{
firstName
lastName
}
p1 = (race:'Human',
firstName: 'Jack', lastName:
'Nicholson')
p2 = (race: 'Human
beeing', firstName: 'Jack', lastName:
'Nicholson')
p1!=p2
p1.hashCode() != p2.hashCode()
http://docs.groovy-lang.org/latest/html/documentation/ 246/502
1/6/2019 Groovy Language Documentation
Attribute Default value Description Example
includeFields False Should elds be included in
equals/hashCode, in addition to
groovy.transform.
properties
@EqualsAndHashCode(includeFields= )
{
firstName
( firstName) {
.firstName = firstName
}
}
p1 = ('Jack')
p2 = ('Jack')
p3 = ('Bob')
p1 == p2
p1 != p3
useCanEqual True Should equals call canEqual See
helper method. http://www.artima.com/lejava/articles/equality.html
(http://www.artima.com/lejava/articles/equality.html)
allProperties False Should JavaBean properties be
@EqualsAndHashCode(allProperties= ,
included in equals and hashCode
excludes='first, last')
calculations {
first,
getInitials() { first[0] +
[0] }
}
p1 = (first: 'Jack', :
'Smith')
p2 = (first: 'Jack', :
'Spratt')
p3 = (first: 'Bob', :
'Smith')
p1 == p2
p1.hashCode() == p2.hashCode()
p1 != p3
p1.hashCode() != p3.hashCode()
allNames False Should elds and/or properties
with internal names be included
groovy.transform.
in equals and hashCode
calculations @EqualsAndHashCode(allNames= )
{
$firstName
}
p1 = ($firstName: 'Jack')
p2 = ($firstName: 'Bob')
p1 != p2
p1.hashCode() != p2.hashCode()
@groovy.transform.TupleConstructor
http://docs.groovy-lang.org/latest/html/documentation/ 247/502
1/6/2019 The @TupleConstructor annotation aims at eliminating Groovy
boilerplate code by
Language generating constructors for you. A tuple constructor
Documentation
is created having a parameter for each property (and possibly each eld). 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).
Implementation Details
Normally you don’t need to understand the imp[ementation 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:
groovy.transform.
@TupleConstructor
{
firstName
lastName
}
// traditional map-style constructor
p1 = (firstName: 'Jack', lastName: 'Nicholson')
// generated tuple constructor
p2 = ('Jack', 'Nicholson')
// generated tuple constructor with default value for second property
p3 = ('Jack')
The rst constructor is a no-arg constructor which allows the traditional map-style construction so long as you don’t have nal
properties. Groovy calls the no-arg constructor and then the relevant setters under the covers. It is worth noting that if the rst
property (or eld) has type LinkedHashMap or if there is a single Map, AbstractMap or HashMap property (or eld), then the map-
style named arguments won’t be available.
The other constructors are generated by taking the properties in the order they are de ned. Groovy will generate as many
constructors as there are properties (or elds, depending on the options).
Setting the defaults attribute (see the available con guration 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.
Immutability support
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.
Customization options
The @TupleConstructor AST transformation accepts several annotation attributes:
Attribute Default Description Example
value
http://docs.groovy-lang.org/latest/html/documentation/ 248/502
1/6/2019 Groovy Language Documentation
Attribute Default Description Example
value
excludes Empty list List of properties to
groovy.transform.
exclude from tuple
constructor @TupleConstructor(excludes=['lastName'])
generation {
firstName
lastName
}
p1 = (firstName: 'Jack',
lastName: 'Nicholson')
p2 = ('Jack')
{
// will fail because the second property
is excluded
p3 = ('Jack', 'Nicholson')
} (e) {
e.message.contains ('Could not find
matching constructor')
}
includes Unde ned List of elds to
groovy.transform.
list include in tuple
(indicates constructor @TupleConstructor(includes=['firstName'])
all elds) generation {
firstName
lastName
}
p1 = (firstName: 'Jack',
lastName: 'Nicholson')
p2 = ('Jack')
{
// will fail because the second property
is not included
p3 = ('Jack', 'Nicholson')
} (e) {
e.message.contains ('Could not find
matching constructor')
}
includeProperties True Should properties
groovy.transform.
be included in tuple
constructor @TupleConstructor(includeProperties= )
generation {
firstName
lastName
}
p1 = (firstName: 'Jack',
lastName: 'Nicholson')
{
p2 = ('Jack', 'Nicholson')
} (e) {
// will fail because properties are not
included
}
http://docs.groovy-lang.org/latest/html/documentation/ 249/502
1/6/2019 Groovy Language Documentation
Attribute Default Description Example
value
includeFields False Should elds be
groovy.transform.
included in tuple
constructor @TupleConstructor(includeFields= )
generation, in {
addition to firstName
properties lastName
occupation
toString() {
"$firstName $lastName: $occupation"
}
}
p1 = (firstName: 'Jack',
lastName: 'Nicholson', occupation: 'Actor')
p2 = ('Jack', 'Nicholson',
'Actor')
p1.firstName == p2.firstName
p1.lastName == p2.lastName
p1.toString() == 'Jack Nicholson:
Actor'
p1.toString() == p2.toString()
includeSuperProperties True Should properties
groovy.transform.
from super classes
be included in tuple {
constructor occupation
generation }
@TupleConstructor(includeSuperProperties= )
{
firstName
lastName
toString() {
"$firstName $lastName: $occupation"
}
}
p1 = (firstName: 'Jack',
lastName: 'Nicholson')
p2 = ('Actor', 'Jack',
'Nicholson')
p1.firstName == p2.firstName
p1.lastName == p2.lastName
p1.toString() == 'Jack Nicholson: null'
p2.toString() == 'Jack Nicholson:
Actor'
http://docs.groovy-lang.org/latest/html/documentation/ 250/502
1/6/2019 Groovy Language Documentation
Attribute Default Description Example
value
includeSuperFields False Should elds from
groovy.transform.
super classes be
included in tuple {
constructor occupation
generation occupation() {
.occupation }
}
@TupleConstructor(includeSuperFields= )
{
firstName
lastName
toString() {
"$firstName $lastName:
${occupation()}"
}
}
p1 = (firstName: 'Jack',
lastName: 'Nicholson', occupation: 'Actor')
p2 = ('Actor', 'Jack',
'Nicholson')
p1.firstName == p2.firstName
p1.lastName == p2.lastName
p1.toString() == 'Jack Nicholson:
Actor'
p2.toString() == p1.toString()
callSuper False Should super
groovy.transform.
properties be called
within a call to the {
parent constructor occupation
rather than set as () {}
properties ( job) { occupation =
job?.toLowerCase() }
}
@TupleConstructor(includeSuperProperties =
, callSuper= )
{
firstName
lastName
toString() {
"$firstName $lastName: $occupation"
}
}
p1 = (firstName: 'Jack',
lastName: 'Nicholson')
p2 = ('ACTOR', 'Jack',
'Nicholson')
p1.firstName == p2.firstName
p1.lastName == p2.lastName
p1.toString() == 'Jack Nicholson: null'
p2.toString() == 'Jack Nicholson:
actor'
http://docs.groovy-lang.org/latest/html/documentation/ 251/502
1/6/2019 Groovy Language Documentation
Attribute Default Description Example
value
force False By default, the
groovy.transform.*
transformation will
do nothing if a @ToString @TupleConstructor(force= )
constructor is {
already de ned. name
Setting this attribute // explicit constructor would normally
to true, the disable tuple constructor
constructor will be ( first, ) {
generated and it’s ("$first $last") }
}
your responsibility
to ensure that no
('john smith').toString() ==
duplicate
'Person(john smith)'
constructor is ('john', 'smith').toString()
de ned. == 'Person(john smith)'
defaults True Indicates that
@ToString
default value
@TupleConstructor(defaults= )
processing is {
enabled for name
constructor instrument
parameters. Set to born
false to obtain }
exactly one
constructor but with ('Jimi', 'Guitar',
1942).toString() == 'Musician(Jimi, Guitar,
initial value support
1942)'
and named-
.constructors.size() == 1
arguments disabled.
useSetters False By default, the
groovy.transform.*
transformation will
directly set the @ToString @TupleConstructor(useSetters= )
backing eld of each {
property from its bar
corresponding setBar( bar) {
constructor .bar = bar?.toUpperCase() // null-
parameter. Setting safe
this attribute to true, }
}
the constructor will
instead call setters if
('cat').toString() == 'Foo(CAT)'
they exist. It’s
(bar: 'cat').toString() ==
usually deemed bad 'Foo(CAT)'
style from within a
constructor to call
setters that can be
overridden. It’s your
responsibility to
avoid such bad style.
http://docs.groovy-lang.org/latest/html/documentation/ 252/502
1/6/2019 Groovy Language Documentation
Attribute Default Description Example
value
allNames False Should elds and/or
groovy.transform.
properties with
internal names be @TupleConstructor(allNames= )
included within the {
constructor $firstName
}
p = ('Jack')
p.$firstName == 'Jack'
allProperties False Should JavaBean
@TupleConstructor(allProperties= )
properties be
{
included within the first
constructor
setLast( ) {
. =
}
getName() { "$first $last" }
}
('john', 'smith').name ==
'john smith'
pre empty A closure containing
groovy.transform.
statements to be
inserted at the start @TupleConstructor(pre={ first =
of the generated first?.toLowerCase() })
constructor(s) {
first
}
p = ('Jack')
p.first == 'jack'
post empty A closure containing
groovy.transform.
statements to be
inserted at the end
groovy.test. .shouldFail
of the generated
constructor(s) @TupleConstructor(post={ first })
{
first
}
jack = ('Jack')
shouldFail {
unknown = ()
}
Setting the defaults annotation attribute to false and the force annotation attribute to true allows multiple tuple
constructors to be created by using di erent customization options for the di erent cases (provided each case has a di erent
type signature) as shown in the following example:
http://docs.groovy-lang.org/latest/html/documentation/ 253/502
1/6/2019 Groovy Language Documentation
{
name
}
@ToString(includeSuperProperties= , ignoreNulls= , includeNames= , includeFields= )
@TupleConstructor(force= , defaults= )
@TupleConstructor(force= , defaults= , includeFields= )
@TupleConstructor(force= , defaults= , includeSuperProperties= )
{
published
fiction
() {}
}
("Regina", 2015).toString() == 'Book(published:2015, name:Regina)'
(2015, ).toString() == 'Book(published:2015, fiction:false)'
(2015).toString() == 'Book(published:2015)'
().toString() == 'Book()'
.constructors.size() == 4
Similarly, here is another example using di erent options for includes :
@ToString(includeSuperProperties= , ignoreNulls= , includeNames= , includeFields= )
@TupleConstructor(force= , defaults= , includes='name,year')
@TupleConstructor(force= , defaults= , includes='year,fiction')
@TupleConstructor(force= , defaults= , includes='name,fiction')
{
name
year
fiction
}
("Regina", 2015).toString() == 'Book(name:Regina, year:2015)'
(2015, ).toString() == 'Book(year:2015, fiction:false)'
("Regina", ).toString() == 'Book(name:Regina, fiction:false)'
.constructors.size() == 3
@groovy.transform.MapConstructor
The @MapConstructor annotation aims at eliminating boilerplate code by generating a map constructor for you. A map
constructor is created such that each property in the class is set based on the value in the supplied map having the key with the
name of the property. Usage is as shown in this example:
groovy.transform.*
@ToString
@MapConstructor
{
firstName
lastName
}
p1 = (firstName: 'Jack', lastName: 'Nicholson')
p1.toString() == 'Person(Jack, Nicholson)'
The generated constructor will be roughly like this:
http://docs.groovy-lang.org/latest/html/documentation/ 254/502
1/6/2019 Groovy Language Documentation
( args) {
(args.containsKey('firstName')) {
.firstName = args. ('firstName')
}
(args.containsKey('lastName')) {
.lastName = args. ('lastName')
}
}
@groovy.transform.Canonical
The @Canonical meta-annotation combines the @ToString, @EqualsAndHashCode and @TupleConstructor annotations:
groovy.transform.
@Canonical
{
firstName
lastName
}
p1 = (firstName: 'Jack', lastName: 'Nicholson')
p1.toString() == 'Person(Jack, Nicholson)' // Effect of @ToString
p2 = ('Jack','Nicholson') // Effect of @TupleConstructor
p2.toString() == 'Person(Jack, Nicholson)'
p1==p2 // Effect of @EqualsAndHashCode
p1.hashCode()==p2.hashCode() // Effect of @EqualsAndHashCode
A similar immutable class can be generated using the @Immutable meta-annotation instead. The @Canonical meta-annotation
supports the con guration options found in the annotations it aggregates. See those annotations for more details.
groovy.transform.
@Canonical(excludes=['lastName'])
{
firstName
lastName
}
p1 = (firstName: 'Jack', lastName: 'Nicholson')
p1.toString() == 'Person(Jack)' // Effect of @ToString(excludes=['lastName'])
p2 = ('Jack') // Effect of @TupleConstructor(excludes=['lastName'])
p2.toString() == 'Person(Jack)'
p1==p2 // Effect of @EqualsAndHashCode(excludes=['lastName'])
p1.hashCode()==p2.hashCode() // Effect of @EqualsAndHashCode(excludes=['lastName'])
The @Canonical meta-annotation can be used in conjunction with an explicit use one or more of its component annotations, like
this:
http://docs.groovy-lang.org/latest/html/documentation/ 255/502
1/6/2019 Groovy Language Documentation
groovy.transform.
@Canonical(excludes=['lastName'])
{
firstName
lastName
}
p1 = (firstName: 'Jack', lastName: 'Nicholson')
p1.toString() == 'Person(Jack)' // Effect of @ToString(excludes=['lastName'])
p2 = ('Jack') // Effect of @TupleConstructor(excludes=['lastName'])
p2.toString() == 'Person(Jack)'
p1==p2 // Effect of @EqualsAndHashCode(excludes=['lastName'])
p1.hashCode()==p2.hashCode() // Effect of @EqualsAndHashCode(excludes=['lastName'])
Any applicable annotation attributes from @Canonical are passed along to the explicit annotation but attributes already existing
in the explicit annotation take precedence.
@groovy.transform.InheritConstructors
The @InheritConstructor AST transformation aims at generating constructors matching super constructors for you. This is in
particular useful when overriding exception classes:
groovy.transform.
@InheritConstructors
{}
// all those are generated constructors
()
("A custom message")
("A custom message", ())
( ())
// Java 7 only
// new CustomException("A custom message", new RuntimeException(), false, true)
The @InheritConstructor AST transformation supports the following con guration options:
Attribute Default Description Example
value
constructorAnnotations False Whether to
@Retention( .RUNTIME)
carry over
@Target([ .CONSTRUCTOR])
annotations @interface {}
from the
constructor {
during @ConsAnno () {}
copying }
@InheritConstructors(constructorAnnotations= )
{}
.constructors[0].annotations[0].annotationType().name
== 'groovy.transform.Generated'
.constructors[0].annotations[1].annotationType().name
== 'ConsAnno'
http://docs.groovy-lang.org/latest/html/documentation/ 256/502
1/6/2019 Groovy Language Documentation
Attribute Default Description Example
value
parameterAnnotations False Whether to
@Retention( .RUNTIME)
carry over
@Target([ .PARAMETER])
annotations @interface {}
from the
constructor {
parameters (@ParamAnno name) {}
when }
copying the
constructor @InheritConstructors(parameterAnnotations= )
{}
.constructors[0].parameterAnnotations[0]
[0].annotationType().name == 'ParamAnno'
@groovy.lang.Category
The @Category AST transformation simpli es the creation of Groovy categories. Historically, a Groovy category was written like
this:
{
triple( ) {
3*
}
}
( ) {
9 == 3.triple()
}
The @Category transformation lets you write the same using an instance-style class, rather than a static class style. This removes
the need for having the rst argument of each method being the receiver. The category can be written like this:
@Category( )
{
triple() { 3* }
}
( ) {
9 == 3.triple()
}
Note that the mixed in class can be referenced using this instead. It’s also worth noting that using instance elds in a category
class is inherently unsafe: categories are not stateful (like traits).
@groovy.transform.IndexedProperty
The @IndexedProperty annotation aims at generating indexed getters/setters for properties of list/array types. This is in
particular useful if you want to use a Groovy class from Java. While Groovy supports GPath to access properties, this is not
available from Java. The @IndexedProperty annotation will generate indexed properties of the following form:
{
@IndexedProperty [] someArray = [2]
@IndexedProperty someList = []
}
bean = ()
bean.setSomeArray(0, 'value')
bean.setSomeList(0, 123)
bean.someArray[0] == 'value'
bean.someList == [123]
@groovy.lang.Lazy
http://docs.groovy-lang.org/latest/html/documentation/ 257/502
1/6/2019 The @Lazy AST transformation implements lazy initialization of Language
Groovy elds. For example, the following code:
Documentation
{
@Lazy myField
}
will produce the following code:
$myField
getMyField() {
($myField!= ) { $myField }
{
$myField = ()
$myField
}
}
The default value which is used to initialize the eld is the default constructor of the declaration type. It is possible to de ne a
default value by using a closure on the right hand side of the property assignment, as in the following example:
class SomeBean {
@Lazy LinkedList myField = { ['a','b','c']}()
}
In that case, the generated code looks like the following:
List $myField
List getMyField() {
if ($myField!=null) { return $myField }
else {
$myField = { ['a','b','c']}()
return $myField
}
}
If the eld is declared volatile then initialization will be synchronized using the double-checked locking
(http://en.wikipedia.org/wiki/Double-checked_locking) pattern.
Using the soft=true parameter, the helper eld will use a SoftReference instead, providing a simple way to implement
caching. In that case, if the garbage collector decides to collect the reference, initialization will occur the next time the eld is
accessed.
@groovy.lang.Newify
The @Newify AST transformation is used to bring alternative syntaxes to construct objects:
Using the Python style:
@Newify([Tree,Leaf])
class TreeBuilder {
Tree tree = Tree(Leaf('A'),Leaf('B'),Tree(Leaf('C')))
}
or using the Ruby style:
@Newify([Tree,Leaf])
class TreeBuilder {
Tree tree = Tree.new(Leaf.new('A'),Leaf.new('B'),Tree.new(Leaf.new('C')))
}
The Ruby version can be disabled by setting the auto ag to false .
@groovy.transform.Sortable
http://docs.groovy-lang.org/latest/html/documentation/ 258/502
1/6/2019 The @Sortable AST transformation is used to help write Groovy
classes Language
that are Comparable and easily sorted typically by numerous
Documentation
properties. It is easy to use as shown in the following example where we annotate the Person class:
groovy.transform.
@Sortable {
first
born
}
The generated class has the following properties:
it implements the Comparable interface
it contains a compareTo method with an implementation based on the natural ordering of the first , last and born
properties
it has three methods returning comparators: comparatorByFirst , comparatorByLast and comparatorByBorn .
The generated compareTo method will look like this:
compareTo(java.lang. obj) {
( . (obj)) {
0
}
(!(obj )) {
-1
}
java.lang. value = .first <=> obj.first
(value != 0) {
value
}
value = . <=> obj.
(value != 0) {
value
}
value = .born <=> obj.born
(value != 0) {
value
}
0
}
As an example of the generated comparators, the comparatorByFirst comparator will have a compare method that looks like
this:
compare(java.lang. arg0, java.lang. arg1) {
(arg0 == arg1) {
0
}
(arg0 != && arg1 == ) {
-1
}
(arg0 == && arg1 != ) {
1
}
arg0.first <=> arg1.first
}
The Person class can be used wherever a Comparable is expected and the generated comparators wherever a Comparator is
expected as shown by these examples:
http://docs.groovy-lang.org/latest/html/documentation/ 259/502
1/6/2019 Groovy Language Documentation
people = [
(first: 'Johnny', : 'Depp', born: 1963),
(first: 'Keira', : 'Knightley', born: 1985),
(first: 'Geoffrey', : 'Rush', born: 1951),
(first: 'Orlando', : 'Bloom', born: 1977)
]
people[0] > people[2]
people.sort()*. == ['Rush', 'Depp', 'Knightley', 'Bloom']
people.sort( , .comparatorByFirst())*.first == ['Geoffrey', 'Johnny', 'Keira',
'Orlando']
people.sort( , .comparatorByLast())*. == ['Bloom', 'Depp', 'Knightley', 'Rush']
people.sort( , .comparatorByBorn())*. == ['Rush', 'Depp', 'Bloom', 'Knightley']
Normally, all properties are used in the generated compareTo method in the priority order in which they are de ned. You can
include or exclude certain properties from the generated compareTo method by giving a list of property names in the includes
or excludes annotation attributes. If using includes , the order of the property names given will determine the priority of
properties when comparing. To illustrate, consider the following Person class de nition:
@Sortable(includes='first,born') {
born
first
}
It will have two comparator methods comparatorByFirst and comparatorByBorn and the generated compareTo method will
look like this:
compareTo(java.lang. obj) {
( . (obj)) {
0
}
(!(obj )) {
-1
}
java.lang. value = .first <=> obj.first
(value != 0) {
value
}
value = .born <=> obj.born
(value != 0) {
value
}
0
}
This Person class can be used as follows:
people = [
(first: 'Ben', : 'Affleck', born: 1972),
(first: 'Ben', : 'Stiller', born: 1965)
]
people.sort()*. == ['Stiller', 'Affleck']
The behavior of the @Sortable AST transformation can be further changed using the following additional parameters:
Attribute Default value Description Example
http://docs.groovy-lang.org/latest/html/documentation/ 260/502
1/6/2019 Groovy Language Documentation
Attribute Default value Description Example
allProperties True Should JavaBean properties
groovy.transform.*
(ordered after native
properties) be used @Canonical(includeFields = )
@Sortable(allProperties = ,
includes = 'nameSize')
{
name
getNameSize() { name.size() }
}
finalists = [
('Serena'),
('Venus'),
('CoCo'),
('Mirjana')
]
finalists.sort()*.name ==
['CoCo', 'Venus', 'Serena',
'Mirjana']
allNames False Should properties with
groovy.transform.*
"internal" names be used
@Canonical(allNames = )
@Sortable(allNames = )
{
$country
name
}
finalists = [
('USA', 'Serena'),
('USA', 'Venus'),
('USA', 'CoCo'),
('Croatian', 'Mirjana')
]
finalists.sort()*.name ==
['Mirjana', 'CoCo', 'Serena',
'Venus']
http://docs.groovy-lang.org/latest/html/documentation/ 261/502
1/6/2019 Groovy Language Documentation
Attribute Default value Description Example
includeSuperProperties False Should super properties also
{
be used (ordered rst)
name
}
@Canonical(includeSuperProperties =
)
@Sortable(includeSuperProperties =
)
{
country
}
people = [
('Bob', 'Italy'),
('Cathy', 'Hungary'),
('Cathy', 'Egypt'),
('Bob', 'Germany'),
('Alan', 'France')
]
people.sort()*.name ==
['Alan', 'Bob', 'Bob', 'Cathy',
'Cathy']
people.sort()*.country ==
['France', 'Germany', 'Italy',
'Egypt', 'Hungary']
@groovy.transform.builder.Builder
The @Builder AST transformation is used to help write classes that can be created using uent api calls. The transform supports
multiple building strategies to cover a range of cases and there are a number of con guration options to customize the building
process. If you’re an AST hacker, you can also de ne your own strategy class. The following table lists the available strategies that
are bundled with Groovy and the con guration options each strategy supports.
Strategy Description builderClassName builderMethodName buildMethodName pre x includes/excludes
SimpleStrategy chained n/a n/a n/a yes, yes
setters default
"set"
ExternalStrategy explicit n/a n/a yes, default "build" yes, yes
builder default
class, class ""
being built
untouched
DefaultStrategy creates a yes, default yes, default "builder" yes, default "build" yes, yes
nested <TypeName>Builder default
helper ""
class
InitializerStrategy creates a yes, default yes, default yes, default yes, yes
nested <TypeName>Initializer "createInitializer" "create" but default
helper usually only used ""
class internally
providing
type-safe
uent
creation
SimpleStrategy
http://docs.groovy-lang.org/latest/html/documentation/ 262/502
1/6/2019 To use the SimpleStrategy , annotate your Groovy classGroovy
using the @Builder
Language annotation, and specify the strategy as shown in
Documentation
this example:
groovy.transform.builder.*
@Builder(builderStrategy= )
{
first
born
}
Then, just call the setters in a chained fashion as shown here:
p1 = ().setFirst('Johnny').setLast('Depp').setBorn(1963)
"$p1.first $p1.last" == 'Johnny Depp'
For each property, a generated setter will be created which looks like this:
setFirst(java.lang. first) {
.first = first
You can specify a pre x as shown in this example:
groovy.transform.builder.*
@Builder(builderStrategy= , prefix="")
{
first
born
}
And calling the chained setters would look like this:
p = ().first('Johnny'). ('Depp').born(1963)
"$p.first $p.last" == 'Johnny Depp'
You can use the SimpleStrategy in conjunction with @TupleConstructor . If your @Builder annotation doesn’t have explicit
includes or excludes annotation attributes but your @TupleConstructor annotation does, the ones from
@TupleConstructor will be re-used for @Builder . The same applies for any annotation aliases which combine
@TupleConstructor such as @Canonical .
The annotation attribute useSetters can be used if you have a setter which you want called as part of the construction process.
See the JavaDoc for details.
The annotation attributes builderClassName , buildMethodName , builderMethodName , forClass and
includeSuperProperties are not supported for this strategy.
Groovy already has built-in building mechanisms. Don’t rush to using @Builder if the built-in mechanisms meet
your needs. Some examples:
p2 = (first: 'Keira', : 'Knightley', born: 1985)
p3 = (). {
first = 'Geoffrey'
= 'Rush'
born = 1951
}
http://docs.groovy-lang.org/latest/html/documentation/ 263/502
1/6/2019 ExternalStrategy Groovy Language Documentation
To use the ExternalStrategy , create and annotate a Groovy builder class using the @Builder annotation, specify the class the
builder is for using forClass and indicate use of the ExternalStrategy . Suppose you have the following class you would like a
builder for:
{
first
born
}
you explicitly create and use your builder class as follows:
groovy.transform.builder.*
@Builder(builderStrategy= , forClass= )
{ }
p = ().first('Johnny'). ('Depp').born(1963).build()
"$p.first $p.last" == 'Johnny Depp'
Note that the (normally empty) builder class you provide will be lled in with appropriate setters and a build method. The
generated build method will look something like:
build() {
_thePerson = ()
_thePerson.first = first
_thePerson. =
_thePerson.born = born
_thePerson
}
The class you are creating the builder for can be any Java or Groovy class following the normal JavaBean conventions, e.g. a no-arg
constructor and setters for the properties. Here is an example using a Java class:
groovy.transform.builder.*
@Builder(builderStrategy= , forClass=javax.swing. )
{}
model =
().enabled( ).pressed( ).armed( ).rollover( ).selected( ).build()
model.isArmed()
model.isPressed()
model.isEnabled()
model.isSelected()
model.isRollover()
The generated builder can be customised using the prefix , includes , excludes and buildMethodName annotation
attributes. Here is an example illustrating various customisations:
http://docs.groovy-lang.org/latest/html/documentation/ 264/502
1/6/2019 Groovy Language Documentation
groovy.transform.builder.*
groovy.transform.
@Canonical
{
first
born
}
@Builder(builderStrategy= , forClass= , includes=['first', 'last'],
buildMethodName='create', prefix='with')
{ }
p = ().withFirst('Johnny').withLast('Depp').create()
"$p.first $p.last" == 'Johnny Depp'
The builderMethodName and builderClassName annotation attributes for @Builder aren’t applicable for this strategy.
You can use the ExternalStrategy in conjunction with @TupleConstructor . If your @Builder annotation doesn’t have explicit
includes or excludes annotation attributes but the @TupleConstructor annotation of the class you are creating the builder
for does, the ones from @TupleConstructor will be re-used for @Builder . The same applies for any annotation aliases which
combine @TupleConstructor such as @Canonical .
DefaultStrategy
To use the DefaultStrategy , annotate your Groovy class using the @Builder annotation as shown in this example:
groovy.transform.builder.
@Builder
{
firstName
lastName
age
}
person = .builder().firstName("Robert").lastName("Lewandowski").age(21).build()
person.firstName == "Robert"
person.lastName == "Lewandowski"
person.age == 21
If you want, you can customize various aspects of the building process using the builderClassName , buildMethodName ,
builderMethodName , prefix , includes and excludes annotation attributes, some of which are used in the example here:
groovy.transform.builder.
@Builder(buildMethodName='make', builderMethodName='maker', prefix='with', excludes='age')
{
firstName
lastName
age
}
p = .maker().withFirstName("Robert").withLastName("Lewandowski").make()
"$p.firstName $p.lastName" == "Robert Lewandowski"
This strategy also supports annotating static methods and constructors. In this case, the static method or constructor parameters
become the properties to use for building purposes and in the case of static methods, the return type of the method becomes the
target class being built. If you have more than one @Builder annotation used within a class (at either the class, method or
constructor positions) then it is up to you to ensure that the generated helper classes and factory methods have unique names
(i.e. no more than one can use the default name values). Here is an example highlighting method and constructor usage (and also
illustrating the renaming required for unique names).
http://docs.groovy-lang.org/latest/html/documentation/ 265/502
1/6/2019 Groovy Language Documentation
groovy.transform.builder.*
groovy.transform.*
@ToString
@Builder
{
first,
born
(){}
@Builder(builderClassName='MovieBuilder', builderMethodName='byRoleBuilder')
( roleName) {
(roleName == 'Jack Sparrow') {
.first = 'Johnny'; . = 'Depp'; .born = 1963
}
}
@Builder(builderClassName='NameBuilder', builderMethodName='nameBuilder', prefix='having',
buildMethodName='fullName')
join( first, ) {
first + ' ' +
}
@Builder(builderClassName='SplitBuilder', builderMethodName='splitBuilder')
split( name, year) {
parts = name.split(' ')
(first: parts[0], : parts[1], born: year)
}
}
.splitBuilder().name("Johnny Depp").year(1963).build().toString() == 'Person(Johnny,
Depp, 1963)'
.byRoleBuilder().roleName("Jack Sparrow").build().toString() == 'Person(Johnny, Depp,
1963)'
.nameBuilder().havingFirst('Johnny').havingLast('Depp').fullName() == 'Johnny Depp'
.builder().first("Johnny"). ('Depp').born(1963).build().toString() ==
'Person(Johnny, Depp, 1963)'
The forClass annotation attribute is not supported for this strategy.
InitializerStrategy
To use the InitializerStrategy , annotate your Groovy class using the @Builder annotation, and specify the strategy as
shown in this example:
groovy.transform.builder.*
groovy.transform.*
@ToString
@Builder(builderStrategy= )
{
firstName
lastName
age
}
Your class will be locked down to have a single public constructor taking a "fully set" initializer. It will also have a factory method to
create the initializer. These are used as follows:
http://docs.groovy-lang.org/latest/html/documentation/ 266/502
1/6/2019 Groovy Language Documentation
@CompileStatic
firstLastAge() {
( .createInitializer().firstName("John").lastName("Smith").age(21)).toString() ==
'Person(John, Smith, 21)'
}
firstLastAge()
Any attempt to use the initializer which doesn’t involve setting all the properties (though order is not important) will result in a
compilation error. If you don’t need this level of strictness, you don’t need to use @CompileStatic .
You can use the InitializerStrategy in conjunction with @Canonical and @Immutable . If your @Builder annotation doesn’t
have explicit includes or excludes annotation attributes but your @Canonical annotation does, the ones from @Canonical
will be re-used for @Builder . Here is an example using @Builder with @Immutable :
groovy.transform.builder.*
groovy.transform.*
groovy.transform.options. .PRIVATE
@Builder(builderStrategy= )
@Immutable
@VisibilityOptions(PRIVATE)
{
first
born
}
publicCons = .constructors
publicCons.size() == 1
@CompileStatic
createFirstLastBorn() {
p = ( .createInitializer().first('Johnny'). ('Depp').born(1963))
"$p.first $p.last $p.born" == 'Johnny Depp 1963'
}
createFirstLastBorn()
The annotation attribute useSetters can be used if you have a setter which you want called as part of the construction process.
See the JavaDoc for details.
This strategy also supports annotating static methods and constructors. In this case, the static method or constructor parameters
become the properties to use for building purposes and in the case of static methods, the return type of the method becomes the
target class being built. If you have more than one @Builder annotation used within a class (at either the class, method or
constructor positions) then it is up to you to ensure that the generated helper classes and factory methods have unique names
(i.e. no more than one can use the default name values). For an example of method and constructor usage but using the
DefaultStrategy strategy, consult that strategy’s documentation.
The annotation attribute forClass is not supported for this strategy.
@groovy.transform.AutoImplement
The @AutoImplement AST transformation supplies dummy implementations for any found abstract methods from superclasses
or interfaces. The dummy implementation is the same for all abstract methods found and can be:
essentially empty (exactly true for void methods and for methods with a return type, returns the default value for that type)
a statement that throws a speci ed exception (with optional message)
some user supplied code
The rst example illustrates the default case. Our class is annotated with @AutoImplement , has a superclass and a single
interface as can be seen here:
http://docs.groovy-lang.org/latest/html/documentation/ 267/502
1/6/2019 Groovy Language Documentation
groovy.transform.
@AutoImplement
< > { }
A void close() method from the Closeable interface is supplied and left empty. Implementations are also supplied for the
three abstract methods from the super class. The get , addAll and size methods have return types of String , boolean and
int respectively with default values null , false and 0 . We can use our class (and check the expected return type for one of
the methods) using the following code:
().size() == 0
It is also worthwhile examining the equivalent generated code:
< > {
( param0) {
addAll( <? > param0) {
close() {
}
size() {
0
}
The second example illustrates the simplest exception case. Our class is annotated with @AutoImplement , has a superclass and
an annotation attribute indicates that an IOException should be thrown if any of our "dummy" methods are called. Here is the
class de nition:
@AutoImplement(exception= )
{ }
We can use the class (and check the expected exception is thrown for one of the methods) using the following code:
groovy.test. .shouldFail
shouldFail( ) {
().flush()
}
It is also worthwhile examining the equivalent generated code where three void methods have been provided all of which throw
the supplied exception:
http://docs.groovy-lang.org/latest/html/documentation/ 268/502
1/6/2019 Groovy Language Documentation
{
flush() {
()
}
write( [] param0, param1, param2) {
()
}
close() {
()
}
The third example illustrates the exception case with a supplied message. Our class is annotated with @AutoImplement ,
implements an interface, and has annotation attributes to indicate that an UnsupportedOperationException with
Not supported by MyIterator as the message should be thrown for any supplied methods. Here is the class de nition:
@AutoImplement(exception= , message='Not supported by MyIterator')
< > { }
We can use the class (and check the expected exception is thrown and has the correct message for one of the methods) using the
following code:
ex = shouldFail( ) {
().hasNext()
}
ex.message == 'Not supported by MyIterator'
It is also worthwhile examining the equivalent generated code where three void methods have been provided all of which throw
the supplied exception:
< > {
hasNext() {
('Not supported by MyIterator')
}
() {
('Not supported by MyIterator')
}
The fourth example illustrates the case of user supplied code. Our class is annotated with @AutoImplement , implements an
interface, has an explcitly overriden hasNext method, and has an annotation attribute containing the supplied code for any
supplied methods. Here is the class de nition:
@AutoImplement(code = { ('Should never be called but was
called on ' + ()) })
< > {
hasNext() { }
}
We can use the class (and check the expected exception is thrown and has a message of the expected form) using the following
code:
http://docs.groovy-lang.org/latest/html/documentation/ 269/502
1/6/2019 Groovy Language Documentation
ex = shouldFail( ) {
(). ()
}
ex.message.startsWith('Should never be called but was called on ')
It is also worthwhile examining the equivalent generated code where the next method has been supplied:
java.util. < > {
hasNext() {
() {
('Should never be called but was called on ' +
())
}
Class design annotations
This category of annotations are aimed at simplifying the implementation of well-known design patterns (delegation, singleton, …)
by using a declarative style.
@groovy.transform.BaseScript
@BaseScript is used within scripts to indicate that the script should extend fron a custom script base class rather than
groovy.lang.Script . See the documentation for domain speci c languages for further details.
@groovy.lang.Delegate
The @Delegate AST transformation aims at implementing the delegation design pattern. In the following class:
{
@Delegate
title
}
The when property is annotated with @Delegate , meaning that the Event class will delegate calls to Date methods to the
when property. In this case, the generated code looks like this:
title
before( other) {
.before(other)
}
// ...
}
Then you can call the before method, for example, directly on the Event class:
ev = (title:'Groovy keynote', : .parse('yyyy/MM/dd', '2013/09/10'))
now = ()
ev.before(now)
Instead of annotating a property (or eld), you can also annotate a method. In this case, the method can be thought of as a getter
or factory method for the delegate. As an example, here is a class which (rather unusually) has a pool of delegates which are
accessed in a round-robin fashion:
http://docs.groovy-lang.org/latest/html/documentation/ 270/502
1/6/2019 Groovy Language Documentation
{
robinCount = 0
< > items = [[0], [1], [2]]
@Delegate
getRoundRobinList() {
items[robinCount++ % items.size()]
}
checkItems( < > testValue) {
items == testValue
}
}
Here is an example usage of that class:
t = ()
t << 'fee'
t << 'fi'
t << 'fo'
t << 'fum'
t.checkItems([[0, 'fee', 'fum'], [1, 'fi'], [2, 'fo']])
Using a standard list in this round-robin fashion would violate many expected properties of lists, so don’t expect the above class to
do anything useful beyond this trivial example.
The behavior of the @Delegate AST transformation can be changed using the following parameters:
Attribute Default Description Example
value
interfaces True Should the
{ sayHello() }
interfaces
{ sayHello() { println 'Hel
implemented
by the eld be { // no explicit interface
implemented @Delegate greeter = ()
by the class too }
greeter = ()
greeter // interface was added transpare
deprecated false If true, also
{
delegates
@Deprecated
methods foo() {}
annotated with }
@Deprecated {
@Deprecated
bar() {}
}
{
@Delegate(deprecated= ) =
@Delegate without = ()
}
d = ()
d.foo() // passes thanks to deprecated=true
d.bar() // fails because of @Deprecated
http://docs.groovy-lang.org/latest/html/documentation/ 271/502
1/6/2019 Groovy Language Documentation
Attribute Default Description Example
value
methodAnnotations False Whether to
{
carry over
@Transactional
annotations method() {
from the }
methods of the }
delegate to {
your delegating @Delegate
method. }
{
@Delegate(methodAnnotations = )
}
d1 = ()
d2 = ()
d1. .getDeclaredMethod('method').annotations.length==1
d2. .getDeclaredMethod('method').annotations.length==2
parameterAnnotations False Whether to
{
carry over
method(@NotNull str) {
annotations }
from the }
method {
parameters of @Delegate
the delegate to }
your delegating {
method. @Delegate(parameterAnnotations = )
}
d1 = ()
d2 = ()
d1. .getDeclaredMethod('method', ).parameterAnnotations[
d2. .getDeclaredMethod('method', ).parameterAnnotations[
excludes Empty A list of
{
array methods to be
task1() {}
excluded from task2() {}
delegation. For }
more ne- {
grained control, @Delegate(excludes=['task2']) worker = ()
see also }
excludeTypes . d = ()
d.task1() // passes
d.task2() // fails because method is excluded
includes Unde ned A list of
{
marker methods to be
task1() {}
array included in task2() {}
(indicates delegation. For }
all more ne- {
methods) grained control, @Delegate(includes=['task1']) worker = ()
see also }
includeTypes . d = ()
d.task1() // passes
d.task2() // fails because method is not included
http://docs.groovy-lang.org/latest/html/documentation/ 272/502
1/6/2019 Groovy Language Documentation
Attribute Default Description Example
value
excludeTypes Empty A list of
{
array interfaces
append( str)
containing }
method {
signatures to be @Delegate(excludeTypes= )
excluded from sb1 = ()
delegation
@Delegate(includeTypes= )
sb2 = ()
toString() { sb1.toString() + sb2.toString().toUpperCa
}
usb = ()
usb.append(3.5d)
usb.append('hello')
usb.append( )
usb.toString() == '3.5trueHELLO'
includeTypes Unde ned A list of
{
marker interfaces
append( b)
array containing }
(indicates method {
no list be signatures to be append( b)
default) included in }
delegation {
@Delegate(includeTypes= , interfaces=
nums = ()
@Delegate(includeTypes=[ ], interfaces=
bools = ()
result() { "${nums.toString()} ~ ${bools.toString()}"
}
b = ()
b.append( )
b.append(3.14f)
b.append( )
b.append(0.0f)
b.result() == "truefalse ~ 3.140.0"
b.append(3.5d) // would fail because we didn't include append(do
allNames False Should the
{
delegate
task$() {}
pattern be also }
applied to {
methods with @Delegate(allNames= ) worker = ()
internal names }
d = ()
d.task$() //passes
@groovy.transform.Immutable
The @Immutable meta-annotation combines the following annotations:
@ToString
@EqualsAndHashCode
@TupleConstructor
@MapConstructor
@ImmutableBase
http://docs.groovy-lang.org/latest/html/documentation/ 273/502
1/6/2019 @ImmutableOptions Groovy Language Documentation
@PropertyOptions
@KnownImmutable
The @Immutable meta-annotation simpli es the creation of immutable classes. Immutable classes are useful since they are often
easier to reason about and are inherently thread-safe. See E ective Java, Minimize Mutability
(http://www.informit.com/store/e ective-java-9780134685991) for all the details about how to achieve immutable classes in Java.
The @Immutable meta-annotation does most of the things described in E ective Java for you automatically. To use the meta-
annotation, all you have to do is annotate the class like in the following example:
groovy.transform.
@Immutable
{
x
y
}
One of the requirements for immutable classes is that there is no way to modify any state information within the class. One
requirement to achieve this is to use immutable classes for each property or alternatively perform special coding such as
defensive copy in and defensive copy out for any mutable properties within the constructors and property getters. Between
@ImmutableBase , @MapConstructor and @TupleConstructor properties are either identi ed as immutable or the special
coding for numerous known cases is handled automatically. Various mechanisms are provided for you to extend the handled
property types which are allowed. See @ImmutableOptions and @KnownImmutable for details.
The results of applying @Immutable to a class are pretty similar to those of applying the @Canonical meta-annotation but the
generated class will have extra logic to handle immutability. You will observe this by, for instance, trying to modify a property
which will result in a ReadOnlyPropertyException being thrown since the backing eld for the property will have been
automatically made nal.
The @Immutable meta-annotation supports the con guration options found in the annotations it aggregates. See those
annotations for more details.
@groovy.transform.ImmutableBase
Immutable classes generated with @ImmutableBase are automatically made nal. Also, the type of each property is checked and
various checks are made on the class, for example, public instance elds currently aren’t allowed. It also generates a copyWith
constructor if desired.
The following annotation attribute is supported:
Attribute Default value Description Example
copyWith false A boolean whether to generate a
groovy.transform.
copyWith( Map ) method.
@Immutable( copyWith= )
{
name
age
}
bob = ( 'bob', 43 )
alice = bob.copyWith( name:'alice'
)
alice.name == 'alice'
alice.age == 43
@groovy.transform.PropertyOptions
This annotation allows you to specify a custom property handler to be used by transformations during class construction. It is
ignored by the main Groovy compiler but is referenced by other transformations like @TupleConstructor , @MapConstructor ,
and @ImmutableBase . It is frequently used behind the scenes by the @Immutable meta-annotation.
http://docs.groovy-lang.org/latest/html/documentation/ 274/502
1/6/2019 @groovy.transform.VisibilityOptions Groovy Language Documentation
This annotation allows you to specify a custom visibility for a construct generated by another transformation. It is ignored by the
main Groovy compiler but is referenced by other transformations like @TupleConstructor , @MapConstructor , and
@NamedVariant .
@groovy.transform.ImmutableOptions
Groovy’s immutability support relies on a prede ned list of known immutable classes (like java.net.URI or java.lang.String
and fails if you use a type which is not in that list, you are allowed to add to the list of known immutable types thanks to the
following annotation attributes of the @ImmutableOptions annotation:
Attribute Default Description Example
value
knownImmutableClasses Empty list A list of classes which are
groovy.transform.
deemed immutable.
groovy.transform.
@TupleConstructor
{
x
y
toString() { "
($x,$y)" }
}
@Immutable(knownImmutableClasses=
[ ])
{
a,b,c
}
knownImmutables Empty list A list of property names
groovy.transform.
which are deemed
immutable.
groovy.transform.
@TupleConstructor
{
x
y
toString() { "
($x,$y)" }
}
@Immutable(knownImmutables=
['a','b','c'])
{
a,b,c
}
If you deem a type as immutable and it isn’t one of the ones automatically handled, then it is up to you to correctly code that class
to ensure immutability.
@groovy.transform.KnownImmutable
The @KnownImmutable annotation isn’t actually one that triggers any AST transformations. It is simply a marker annotation. You
can annotate your classes with the annotation (including Java classes) and they will be recognized as acceptable types for
members within an immutable class. This saves you having to explicitly use the knownImmutables or knownImmutableClasses
annotation attributes from @ImmutableOptions .
@groovy.transform.Memoized
The @Memoized AST transformations simpli es the implementation of caching by allowing the result of method calls to be cached
just by annotating the method with @Memoized . Let’s imagine the following method:
http://docs.groovy-lang.org/latest/html/documentation/ 275/502
1/6/2019 Groovy Language Documentation
longComputation( seed) {
// slow computation
.sleep(100*seed)
.nanoTime()
}
This emulates a long computation, based on the actual parameters of the method. Without @Memoized , each method call would
take several seconds plus it would return a random result:
x = longComputation(1)
y = longComputation(1)
x!=y
Adding @Memoized changes the semantics of the method by adding caching, based on the parameters:
@Memoized
longComputation( seed) {
// slow computation
.sleep(100*seed)
.nanoTime()
}
x = longComputation(1) // returns after 100 milliseconds
y = longComputation(1) // returns immediatly
z = longComputation(2) // returns after 200 milliseconds
x==y
x!=z
The size of the cache can be con gured using two optional parameters:
protectedCacheSize: the number of results which are guaranteed not to be cleared after garbage collection
maxCacheSize: the maximum number of results that can be kept in memory
By default, the size of the cache is unlimited and no cache result is protected from garbage collection. Setting a
protectedCacheSize>0 would create an unlimited cache with some results protected. Setting maxCacheSize>0 would create a
limited cache but without any protection from garbage protection. Setting both would create a limited, protected cache.
@groovy.transform.TailRecursive
The @TailRecursive annotation can be used to automatically transform a recursive call at the end of a method into an
equivalent iterative version of the same code. This avoids stack over ow due to too many recursive calls. Below is an example of
use when calculating factorial:
groovy.transform.
groovy.transform.
@CompileStatic
{
@TailRecursive
factorial( i, product = 1) {
( i == 1) {
product
}
factorial(i-1, product*i)
}
}
.factorial(1) == 1
.factorial(3) == 6
.factorial(5) == 120
.factorial(50000).toString().size() == 213237 // Big number and no Stack Overflow
http://docs.groovy-lang.org/latest/html/documentation/ 276/502
1/6/2019 Currently, the annotation will only work for self-recursive Groovy
methodLanguage
calls, i.e. aDocumentation
single recursive call to the exact same method again.
Consider using Closures and trampoline() if you have a scenario involving simple mutual recursion. Also note that only non-
void methods are currently handled (void calls will result in a compilation error).
Currently, some forms of method overloading can trick the compiler, and some non-tail recursive calls are
erroneously treated as tail recursive.
@groovy.lang.Singleton
The @Singleton annotation can be used to implement the singleton design pattern on a class. The singleton instance is de ned
eagerly by default, using class initialization, or lazily, in which case the eld is initialized using double checked locking.
@Singleton
{
greeting( name) { "Hello, $name!" }
}
.instance.greeting('Bob') == 'Hello, Bob!'
By default, the singleton is created eagerly when the class is initialized and available through the instance property. It is possible
to change the name of the singleton using the property parameter:
@Singleton( ='theOne')
{
greeting( name) { "Hello, $name!" }
}
.theOne.greeting('Bob') == 'Hello, Bob!'
And it is also possible to make initialization lazy using the lazy parameter:
{
init =
}
@Singleton(lazy= ,strict= )
{
init() {}
() {
.init =
}
greeting( name) { "Hello, $name!" }
}
.init() // make sure class is initialized
.init ==
.instance
.init ==
.instance.greeting('Bob') == 'Hello, Bob!'
In this example, we also set the strict parameter to false, which allows us to de ne our own constructor.
@groovy.lang.Mixin
Deprecated. Consider using traits instead.
Logging improvements
Groovy provides AST transformation that helps integrating with the most widely used logging frameworks. It’s worth noting that
annotating a class with one of those annotations doesn’t prevent you from adding the appropriate logging framework on
classpath.
All transformations work in a similar way:
add static nal log eld corresponding to the logger
wrap all calls to log.level() into the appropriate log.isLevelEnabled guard, depending on the underlying framework
Those transformations support two parameters:
http://docs.groovy-lang.org/latest/html/documentation/ 277/502
1/6/2019 value (default log ) corresponds to the name of the Groovy
logger Language
eld Documentation
category (defaults to the class name) is the name of the logger category
@groovy.util.logging.Log
The rst logging AST transformation available is the @Log annotation which relies on the JDK logging framework. Writing:
@groovy.util.logging.
{
greet() {
log.info 'Called greeter'
println 'Hello, world!'
}
}
is equivalent to writing:
java.util.logging.
java.util.logging.
{
log = .getLogger( .name)
greet() {
(log.isLoggable( .INFO)) {
log.info 'Called greeter'
}
println 'Hello, world!'
}
}
@groovy.util.logging.Commons
Groovy supports the Apache Commons Logging (http://commons.apache.org/proper/commons-logging/) framework using to the
@Commons annotation. Writing:
@groovy.util.logging.
{
greet() {
log.debug 'Called greeter'
println 'Hello, world!'
}
}
is equivalent to writing:
org.apache.commons.logging.
org.apache.commons.logging.
{
log = .getLog( )
greet() {
(log.isDebugEnabled()) {
log.debug 'Called greeter'
}
println 'Hello, world!'
}
}
@groovy.util.logging.Log4j
Groovy supports the Apache Log4j 1.x (http://logging.apache.org/log4j/1.2/) framework using to the @Log4j annotation. Writing:
http://docs.groovy-lang.org/latest/html/documentation/ 278/502
1/6/2019 Groovy Language Documentation
@groovy.util.logging.
{
greet() {
log.debug 'Called greeter'
println 'Hello, world!'
}
}
is equivalent to writing:
org.apache.log4j.
{
log = .getLogger( )
greet() {
(log.isDebugEnabled()) {
log.debug 'Called greeter'
}
println 'Hello, world!'
}
}
@groovy.util.logging.Log4j2
Groovy supports the Apache Log4j 2.x (http://logging.apache.org/log4j/2.x/) framework using to the @Log4j2 annotation. Writing:
@groovy.util.logging.
{
greet() {
log.debug 'Called greeter'
println 'Hello, world!'
}
}
is equivalent to writing:
org.apache.logging.log4j.
org.apache.logging.log4j.
{
log = .getLogger( )
greet() {
(log.isDebugEnabled()) {
log.debug 'Called greeter'
}
println 'Hello, world!'
}
}
@groovy.util.logging.Slf4j
Groovy supports the Simple Logging Facade for Java (SLF4J) (http://www.slf4j.org/) framework using to the @Slf4j annotation.
Writing:
@groovy.util.logging.
{
greet() {
log.debug 'Called greeter'
println 'Hello, world!'
}
}
is equivalent to writing:
http://docs.groovy-lang.org/latest/html/documentation/ 279/502
1/6/2019 Groovy Language Documentation
org.slf4j.
org.slf4j.
{
log = .getLogger( )
greet() {
(log.isDebugEnabled()) {
log.debug 'Called greeter'
}
println 'Hello, world!'
}
}
Declarative concurrency
The Groovy language provides a set of annotations aimed at simplifying common concurrency patterns in a declarative approach.
@groovy.transform.Synchronized
The @Synchronized AST transformations works in a similar way to the synchronized keyword but locks on di erent objects for
safer concurrency. It can be applied on any method or static method:
groovy.transform.
java.util.concurrent.
java.util.concurrent.
{
cpt
@Synchronized
incrementAndGet() {
cpt++
}
() {
cpt
}
}
Writing this is equivalent to creating a lock object and wrapping the whole method into a synchronized block:
{
cpt
$lock = ()
incrementAndGet() {
($lock) {
cpt++
}
}
() {
cpt
}
By default, @Synchronized creates a eld named $lock (or $LOCK for a static method) but you can make it use any eld you
want by specifying the value attribute, like in the following example:
http://docs.groovy-lang.org/latest/html/documentation/ 280/502
1/6/2019 Groovy Language Documentation
groovy.transform.
java.util.concurrent.
java.util.concurrent.
{
cpt
myLock = ()
@Synchronized('myLock')
incrementAndGet() {
cpt++
}
() {
cpt
}
}
@groovy.transform.WithReadLock and @groovy.transform.WithWriteLock
The @WithReadLock AST transformation works in conjunction with the @WithWriteLock transformation to provide read/write
synchronization using the ReentrantReadWriteLock facility that the JDK provides. The annotation can be added to a method or
a static method. It will transparently create a $reentrantLock nal eld (or $REENTRANTLOCK for a static method) and proper
synchronization code will be added. For example, the following code:
groovy.transform.
groovy.transform.
{
< , > map = [:].withDefault { 0 }
@WithReadLock
( id) {
map. (id)
}
@WithWriteLock
add( id, num) {
.sleep(200) // emulate long computation
map.put(id, map. (id)+num)
}
}
is equivalent to this:
http://docs.groovy-lang.org/latest/html/documentation/ 281/502
1/6/2019 Groovy Language Documentation
groovy.transform.
groovy.transform.
< , > map
java.util.concurrent.locks. $reentrantlock
(java.lang. id) {
$reentrantlock.readLock(). ()
{
map. (id)
}
{
$reentrantlock.readLock().unlock()
}
}
add(java.lang. id, num) {
$reentrantlock.writeLock(). ()
{
java.lang. .sleep(200)
map.put(id, map. (id) + num )
}
{
$reentrantlock.writeLock().unlock()
}
}
}
Both @WithReadLock and @WithWriteLock support specifying an alternative lock object. In that case, the referenced eld must
be declared by the user, like in the following alternative:
groovy.transform.
groovy.transform.
java.util.concurrent.locks.
{
< , > map = [:].withDefault { 0 }
customLock = ()
@WithReadLock('customLock')
( id) {
map. (id)
}
@WithWriteLock('customLock')
add( id, num) {
.sleep(200) // emulate long computation
map.put(id, map. (id)+num)
}
}
For details
See Javadoc for groovy.transform.WithReadLock (http://docs.groovy-lang.org/2.5.5/html/gapi/index.html?
groovy/transform/WithReadLock.html)
See Javadoc for groovy.transform.WithWriteLock (http://docs.groovy-lang.org/2.5.5/html/gapi/index.html?
groovy/transform/WithWriteLock.html)
Easier cloning and externalizing
Groovy provides two annotations aimed at facilitating the implementation of Cloneable and Externalizable interfaces,
respectively named @AutoClone and @AutoExternalize .
http://docs.groovy-lang.org/latest/html/documentation/ 282/502
1/6/2019 @groovy.transform.AutoClone Groovy Language Documentation
The @AutoClone annotation is aimed at implementing the @java.lang.Cloneable interface using various strategies, thanks to
the style parameter:
the default AutoCloneStyle.CLONE strategy calls super.clone() rst then clone() on each cloneable property
the AutoCloneStyle.SIMPLE strategy uses a regular constructor call and copies properties from the source to the clone
the AutoCloneStyle.COPY_CONSTRUCTOR strategy creates and uses a copy constructor
the AutoCloneStyle.SERIALIZATION strategy uses serialization (or externalization) to clone the object
Each of those strategies have pros and cons which are discussed in the Javadoc for groovy.transform.AutoClone
(http://docs.groovy-lang.org/2.5.5/html/gapi/index.html?groovy/transform/AutoClone.html) and groovy.transform.AutoCloneStyle
(http://docs.groovy-lang.org/2.5.5/html/gapi/index.html?groovy/transform/AutoCloneStyle.html) .
For example, the following example:
groovy.transform.
@AutoClone
{
isbn
title
< > authors
publicationDate
}
is equivalent to this:
{
isbn
title
< > authors
publicationDate
clone() {
result = .clone()
result.authors = authors ? ( ) authors.clone() : authors
result.publicationDate = publicationDate.clone()
result
}
}
Note that the String properties aren’t explicitly handled because Strings are immutable and the clone() method from Object
will copy the String references. The same would apply to primitive elds and most of the concrete subclasses of
java.lang.Number .
In addition to cloning styles, @AutoClone supports multiple options:
Attribute Default Description Example
value
excludes Empty A list of property or eld names that need to
groovy.transform.
list be excluded from cloning. A string consisting
groovy.transform.
of a comma-separated eld/property names
is also allowed. See @AutoClone(style= .SIMPLE,excludes='auth
groovy.transform.AutoClone#excludes {
(http://docs.groovy- isbn
lang.org/2.5.5/html/gapi/index.html? title
groovy/transform/AutoClone.html#excludes) authors
for details publicationDate
}
http://docs.groovy-lang.org/latest/html/documentation/ 283/502
1/6/2019 Groovy Language Documentation
Attribute Default Description Example
value
includeFields false By default, only properties are cloned.
groovy.transform.
Setting this ag to true will also clone elds.
groovy.transform.
@AutoClone(style= .SIMPLE,includeFields=
{
isbn
title
authors
publicationDate
}
@groovy.transform.AutoExternalize
The @AutoExternalize AST transformation will assist in the creation of java.io.Externalizable classes. It will automatically
add the interface to the class and generate the writeExternal and readExternal methods. For example, this code:
groovy.transform.
@AutoExternalize
{
isbn
title
price
}
will be converted into:
java.io. {
isbn
title
price
writeExternal( ) {
.writeObject(isbn)
.writeObject(title)
.writeFloat( price )
}
readExternal( oin) {
isbn = ( ) oin.readObject()
title = ( ) oin.readObject()
price = oin.readFloat()
}
The @AutoExternalize annotation supports two parameters which will let you slightly customize its behavior:
Attribute Default Description Example
value
http://docs.groovy-lang.org/latest/html/documentation/ 284/502
1/6/2019 Groovy Language Documentation
Attribute Default Description Example
value
excludes Empty A list of property or eld names that need to be
list excluded from externalizing. A string consisting of
groovy.transform.
a comma-separated eld/property names is also
allowed. See @AutoExternalize(excludes='price')
groovy.transform.AutoExternalize#excludes {
(http://docs.groovy- isbn
lang.org/2.5.5/html/gapi/index.html? title
groovy/transform/AutoExternalize.html#excludes) price
for details }
includeFields false By default, only properties are externalized.
Setting this ag to true will also clone elds.
groovy.transform.
@AutoExternalize(includeFields= )
{
isbn
title
price
}
Safer scripting
The Groovy language makes it easy to execute user scripts at runtime (for example using groovy.lang.GroovyShell
(http://docs.groovy-lang.org/2.5.5/html/gapi/index.html?groovy/lang/GroovyShell.html)), but how do you make sure that a script
won’t eat all CPU (in nite loops) or that concurrent scripts won’t slowly consume all available threads of a thread pool? Groovy
provides several annotations which are aimed towards safer scripting, generating code which will for example allow you to
interrupt execution automatically.
@groovy.transform.ThreadInterrupt
One complicated situation in the JVM world is when a thread can’t be stopped. The Thread#stop method exists but is deprecated
(and isn’t reliable) so your only chance relies in Thread#interrupt . Calling the latter will set the interrupt ag on the thread,
but it will not stop the execution of the thread. This is problematic because it’s the responsibility of the code executing in the
thread to check the interrupt ag and properly exit. This makes sense when you, as a developer, know that the code you are
executing is meant to be run in an independent thread, but in general, you don’t know it. It’s even worse with user scripts, who
might not even know what a thread is (think of DSLs).
@ThreadInterrupt simpli es this by adding thread interruption checks at critical places in the code:
loops (for, while)
rst instruction of a method
rst instruction of a closure body
Let’s imagine the following user script:
( ) {
i++
}
This is an obvious in nite loop. If this code executes in its own thread, interrupting wouldn’t help: if you join on the thread, then
the calling code would be able to continue, but the thread would still be alive, running in background without any ability for you to
stop it, slowly causing thread starvation.
One possibility to work around this is to set up your shell this way:
http://docs.groovy-lang.org/latest/html/documentation/ 285/502
1/6/2019 Groovy Language Documentation
config = ()
config.addCompilationCustomizers(
( )
)
binding = (i:0)
shell = (binding,config)
The shell is then con gured to automatically apply the @ThreadInterrupt AST transformations on all scripts. This allows you to
execute user scripts this way:
t = .start {
shell.evaluate(userCode)
}
t.join(1000) // give at most 1000ms for the script to complete
(t.alive) {
t.interrupt()
}
The transformation automatically modi ed user code like this:
( ) {
( .currentThread().interrupted) {
('The current thread has been interrupted.')
}
i++
}
The check which is introduced inside the loop guarantees that if the interrupt ag is set on the current thread, an exception will
be thrown, interrupting the execution of the thread.
@ThreadInterrupt supports multiple options that will let you further customize the behavior of the transformation:
Attribute Default value Description Example
http://docs.groovy-lang.org/latest/html/documentation/ 286/502
1/6/2019 Groovy Language Documentation
Attribute Default value Description Example
thrown java.lang.InterruptedException Speci es the type of exception which is
thrown if the thread is interrupted.
( mes
}
}
config =
config.addCompilationCusto
(
)
)
binding = (i
shell =
( . .class
userCode = """
try {
while (true) {
i++
}
} catch (BadException e) {
i = -1
}
"""
t = .start {
shell.evaluate(userCod
}
t.join(1000) // give at mo
to complete
binding.i > 0
(t.alive) {
t.interrupt()
}
.sleep(500)
binding.i == -1'''
checkOnMethodStart true Should an interruption check be
@ThreadInterrupt(checkOnMe
inserted at the beginning of each
method body. See
groovy.transform.ThreadInterrupt
(http://docs.groovy-
lang.org/2.5.5/html/gapi/index.html?
groovy/transform/ThreadInterrupt.html)
for details.
applyToAllClasses true Should the transformation be applied
@ThreadInterrupt(applyToAl
on all classes of the same source unit (in
A { ... } // interru
the same source le). See B { ... } // no inte
groovy.transform.ThreadInterrupt
(http://docs.groovy-
lang.org/2.5.5/html/gapi/index.html?
groovy/transform/ThreadInterrupt.html)
for details.
http://docs.groovy-lang.org/latest/html/documentation/ 287/502
1/6/2019 Groovy Language Documentation
Attribute Default value Description Example
applyToAllMembers true Should the transformation be applied
A {
on all members of class. See
@ThreadInterrupt(apply
groovy.transform.ThreadInterrupt method1() { ... }
(http://docs.groovy- added
lang.org/2.5.5/html/gapi/index.html? method2() { ... }
groovy/transform/ThreadInterrupt.html) checks
for details. }
@groovy.transform.TimedInterrupt
The @TimedInterrupt AST transformation tries to solve a slightly di erent problem from
@groovy.transform.ThreadInterrupt : instead of checking the interrupt ag of the thread, it will automatically throw an
exception if the thread has been running for too long.
This annotation does not spawn a monitoring thread. Instead, it works in a similar manner as @ThreadInterrupt
by placing checks at appropriate places in the code. This means that if you have a thread blocked by I/O, it will not
be interrupted.
Imagine the following user code:
fib( n) { n<2?n:fib(n-1)+fib(n-2) }
result = fib(600)
The implementation of the famous Fibonacci number computation here is far from optimized. If it is called with a high n value, it
can take minutes to answer. With @TimedInterrupt , you can choose how long a script is allowed to run. The following setup
code will allow the user script to run for 1 second at max:
config = ()
config.addCompilationCustomizers(
(value:1, )
)
binding = (result:0)
shell = ( . .classLoader, binding,config)
This code is equivalent to annotating a class with @TimedInterrupt like this:
@TimedInterrupt(value=1, unit= .SECONDS)
{
fib( n) {
n<2?n:fib(n-1)+fib(n-2)
}
}
@TimedInterrupt supports multiple options that will let you further customize the behavior of the transformation:
Attribute Default value Description Example
http://docs.groovy-lang.org/latest/html/documentation/ 288/502
1/6/2019 Groovy Language Documentation
Attribute Default value Description Example
value Long.MAX_VALUE Used in combination with unit to
@TimedInterrupt(valu
specify after how long execution times
.MILLISECONDS
out. = )
{
fib(n) { n<2
}
}
result
t = .start
result =
}
t.join(5000)
result ==
!t.alive
unit TimeUnit.SECONDS Used in combination with value to
@TimedInterrupt(valu
specify after how long execution times
.MILLISECONDS
out. = )
{
fib(n) { n<2
}
}
result
t = .start
result =
}
t.join(5000)
result ==
!t.alive
thrown java.util.concurrent.TimeoutException Speci es the type of exception which is
@TimedInterrupt(thro
thrown if timeout is reached.
applyToAllClasses =
{
fib(n) {
n:fib(n-1)+fib(n-2)
}
result
t = .start
{
result =
} (
result = -1
}
}
t.join(5000)
result == -1
checkOnMethodStart true Should an interruption check be
@TimedInterrupt(chec
inserted at the beginning of each
method body. See
groovy.transform.TimedInterrupt
(http://docs.groovy-
lang.org/2.5.5/html/gapi/index.html?
groovy/transform/TimedInterrupt.html)
for details.
http://docs.groovy-lang.org/latest/html/documentation/ 289/502
1/6/2019 Groovy Language Documentation
Attribute Default value Description Example
applyToAllClasses true Should the transformation be applied
@TimedInterrupt(appl
on all classes of the same source unit
A { ... } // i
(in the same source le). See
B { ... } // n
groovy.transform.TimedInterrupt
(http://docs.groovy-
lang.org/2.5.5/html/gapi/index.html?
groovy/transform/TimedInterrupt.html)
for details.
applyToAllMembers true Should the transformation be applied
A {
on all members of class. See
groovy.transform.TimedInterrupt @TimedInterrupt(appl
(http://docs.groovy- method1() {
lang.org/2.5.5/html/gapi/index.html? checked added
groovy/transform/TimedInterrupt.html) method2() {
for details. interrupt checks
}
@TimedInterrupt is currently not compatible with static methods!
@groovy.transform.ConditionalInterrupt
The last annotation for safer scripting is the base annotation when you want to interrupt a script using a custom strategy. In
particular, this is the annotation of choice if you want to use resource management (limit the number of calls to an API, …). In the
following example, user code is using an in nite loop, but @ConditionalInterrupt will allow us to check a quota manager and
interrupt automatically the script:
@ConditionalInterrupt({ .disallow('user')})
{
doSomething() {
i=0
( ) {
println "Consuming resources ${++i}"
}
}
}
The quota checking is very basic here, but it can be any code:
{
quotas = [:].withDefault { 10 }
disallow( userName) {
println "Checking quota for $userName"
(quotas[userName]--)<0
}
}
We can make sure @ConditionalInterrupt works properly using this test code:
.quotas['user'] == 10
t = .start {
().doSomething()
}
t.join(5000)
!t.alive
.quotas['user'] < 0
http://docs.groovy-lang.org/latest/html/documentation/ 290/502
1/6/2019 Of course, in practice, it is unlikely that @ConditionalInterrupt will be itself
Groovy Language added by hand on user code. It can be injected in a
Documentation
similar manner as the example shown in the ThreadInterrupt section, using the
org.codehaus.groovy.control.customizers.ASTTransformationCustomizer (http://docs.groovy-lang.org/2.5.5/html/gapi/index.html?
org/codehaus/groovy/control/customizers/ASTTransformationCustomizer.html) :
config = ()
checkExpression = (
.EMPTY_ARRAY,
(
( ( .make( )), 'disallow',
('user'))
)
)
config.addCompilationCustomizers(
(value: checkExpression, )
)
shell = ( . .classLoader, (),config)
userCode = """
int i=0
while (true) {
println " resources \\${++i}"
}
"""
.quotas['user'] == 10
t = .start {
shell.evaluate(userCode)
}
t.join(5000)
!t.alive
.quotas['user'] < 0
@ConditionalInterrupt supports multiple options that will let you further customize the behavior of the transformation:
Attribute Default value Description Example
value The closure which will be called to check if
@ConditionalInterrupt(
execution is allowed. If the closure returns
false, execution is allowed. If it returns true,
then an exception will be thrown.
thrown java.lang.InterruptedException Speci es the type of exception which is
config.addCompilationC
thrown if execution should be aborted.
,v
)
)
.quotas['u
t = .start {
{
shell.evaluate
} (
.quotas['
exceeded'
}
}
t.join(5000)
!t.alive
.quotas['u
exceeded'
http://docs.groovy-lang.org/latest/html/documentation/ 291/502
1/6/2019 Groovy Language Documentation
Attribute Default value Description Example
checkOnMethodStart true Should an interruption check be inserted at
@ConditionalInterrupt(
the beginning of each method body. See
groovy.transform.ConditionalInterrupt
(http://docs.groovy-
lang.org/2.5.5/html/gapi/index.html?
groovy/transform/ConditionalInterrupt.html)
for details.
applyToAllClasses true Should the transformation be applied on all
@ConditionalInterrupt(
classes of the same source unit (in the same
A { ... } // inte
source le). See B { ... } // no i
groovy.transform.ConditionalInterrupt
(http://docs.groovy-
lang.org/2.5.5/html/gapi/index.html?
groovy/transform/ConditionalInterrupt.html)
for details.
applyToAllMembers true Should the transformation be applied on all
A {
members of class. See
groovy.transform.ConditionalInterrupt @ConditionalInterrupt(
(http://docs.groovy- method1() { ..
lang.org/2.5.5/html/gapi/index.html? checked added
groovy/transform/ConditionalInterrupt.html) method2() { ..
for details. checks
}
Compiler directives
This category of AST transformations groups annotations which have a direct impact on the semantics of the code, rather than
focusing on code generation. With that regards, they can be seen as compiler directives that either change the behavior of a
program at compile time or runtime.
@groovy.transform.Field
The @Field annotation only makes sense in the context of a script and aims at solving a common scoping error with scripts. The
following example will for example fail at runtime:
line() {
"="*x
}
x=3
"===" == line()
x=5
"=====" == line()
The error that is thrown may be di cult to interpret: groovy.lang.MissingPropertyException: No such property: x. The reason is
that scripts are compiled to classes and the script body is itself compiled as a single run() method. Methods which are de ned in
the scripts are independent, so the code above is equivalent to this:
http://docs.groovy-lang.org/latest/html/documentation/ 292/502
1/6/2019 Groovy Language Documentation
{
line() {
"="*x
}
run() {
x
x=3
"===" == line()
x=5
"=====" == line()
}
}
So def x is e ectively interpreted as a local variable, outside of the scope of the line method. The @Field AST transformation
aims at xing this by changing the scope of the variable to a eld of the enclosing script:
@Field x
line() {
"="*x
}
x=3
"===" == line()
x=5
"=====" == line()
The resulting, equivalent, code is now:
line() {
"="*x
}
run() {
x=3
"===" == line()
x=5
"=====" == line()
}
}
@groovy.transform.PackageScope
By default, Groovy visibility rules imply that if you create a eld without specifying a modi er, then the eld is interpreted as a
property:
{
name // this is a property
}
Should you want to create a package private eld instead of a property (private eld+getter/setter), then annotate your eld with
@PackageScope :
{
@PackageScope name // not a property anymore
}
http://docs.groovy-lang.org/latest/html/documentation/ 293/502
1/6/2019 The @PackageScope annotation can also be used for classes, methods
Groovy andDocumentation
Language constructors. In addition, by specifying a list of
PackageScopeTarget values as the annotation attribute at the class level, all members within that class that don’t have an
explicit modi er and match the provided PackageScopeTarget will remain package protected. For example to apply to elds
within a class use the following annotation:
groovy.transform. .FIELDS
@PackageScope(FIELDS)
{
name // not a property, package protected
dob // not a property, package protected
age // explicit modifier, so won't be touched
}
The @PackageScope annotation is seldom used as part of normal Groovy conventions but is sometimes useful for factory
methods that should be visible internally within a package or for methods or constructors provided for testing purposes, or when
integrating with third-party libraries which require such visibility conventions.
@groovy.transform.AutoFinal
The @AutoFinal annotation instructs the compiler to automatically insert the nal modi er in numerous places within the
annotated node. If applied on a method (or constructor), the parameters for that method (or constructor) will be marked as nal.
If applied on a class de nition, the same treatment will occur for all declared methods and constructors within that class.
It is often considered bad practice to reassign parameters of a method or constructor with its body. By adding the nal modi er to
all parameter declarations you can avoid this practice entirely. Some programmers feel that adding nal everywhere increases the
amount of boilerplate code and makes the method signatures somewhat noisy. An alternative might instead be to use a code
review process or apply a codenarc (http://codenarc.org) rule (http://codenarc.sourceforge.net/codenarc-rules-
convention.html#ParameterReassignment) to give warnings if that practice is observed but these alternatives might lead to
delayed feedback during quality checking rather than within the IDE or during compilation. The @AutoFinal annotation aims to
maximise compiler/IDE feedback while retaining succinct code with minimum boilerplate noise.
The following example illustrates applying the annotation at the class level:
groovy.transform.
@AutoFinal
{
first,
( first, ) {
.first = first
. =
}
fullName( separator) {
"$first$separator$last"
}
greeting( salutation) {
"$salutation, $first"
}
}
In this example, the two parameters for the constructor and the single parameter for both the fullname and greeting
methods will be nal. Attempts to modify those parameters within the constructor or method bodies will be agged by the
compiler.
The following example illustrates applying the annotation at the method level:
http://docs.groovy-lang.org/latest/html/documentation/ 294/502
1/6/2019 Groovy Language Documentation
{
@AutoFinal
add( a, b) { a + b }
mult( a, b) { a * b }
}
Here, the add method will have nal parameters but the mult method will remain unchanged.
@groovy.transform.AnnotationCollector
@AnnotationCollector allows the creation of meta-annotations, which are described in a dedicated section.
@groovy.transform.TypeChecked
@TypeChecked activates compile-time type checking on your Groovy code. See section on type checking for details.
@groovy.transform.CompileStatic
@CompileStatic activates static compilation on your Groovy code. See section on type checking for details.
@groovy.transform.CompileDynamic
@CompileDynamic disables static compilation on parts of your Groovy code. See section on type checking for details.
@groovy.lang.DelegatesTo
@DelegatesTo is not, technically speaking, an AST transformation. It is aimed at documenting code and helping the compiler in
case you are using type checking or static compilation. The annotation is described thoroughly in the DSL section of this guide.
@groovy.transform.SelfType
@SelfType is not an AST transformation but rather a marker interface used with traits. See the traits documentation for further
details.
Swing patterns
@groovy.beans.Bindable
@Bindable is an AST transformation that transforms a regular property into a bound property (according to the JavaBeans
speci cation (http://download.oracle.com/otndocs/jcp/7224-javabeans-1.01-fr-spec-oth-JSpec/)). The @Bindable annotation can
be placed on a property or a class. To convert all properties of a class into bound properties, on can annotate the class like in this
example:
groovy.beans.
@Bindable
{
name
age
}
This is equivalent to writing this:
http://docs.groovy-lang.org/latest/html/documentation/ 295/502
1/6/2019 Groovy Language Documentation
java.beans.
java.beans.
{
$propertyChangeSupport
name
age
addPropertyChangeListener( listener) {
$propertyChangeSupport.addPropertyChangeListener(listener)
}
addPropertyChangeListener( name, listener) {
$propertyChangeSupport.addPropertyChangeListener(name, listener)
}
removePropertyChangeListener( listener) {
$propertyChangeSupport.removePropertyChangeListener(listener)
}
removePropertyChangeListener( name, listener) {
$propertyChangeSupport.removePropertyChangeListener(name, listener)
}
firePropertyChange( name, oldValue, newValue) {
$propertyChangeSupport.firePropertyChange(name, oldValue, newValue)
}
[] getPropertyChangeListeners() {
$propertyChangeSupport.getPropertyChangeListeners()
}
[] getPropertyChangeListeners( name) {
$propertyChangeSupport.getPropertyChangeListeners(name)
}
}
@Bindable therefore removes a lot of boilerplate from your class, dramatically increasing readability. If the annotation is put on a
single property, only that property is bound:
groovy.beans.
{
name
@Bindable age
}
@groovy.beans.ListenerList
The @ListenerList AST transformation generates code for adding, removing and getting the list of listeners to a class, just by
annotating a collection property:
java.awt. .
groovy.beans.
{
@ListenerList
< > listeners;
}
The transform will generate the appropriate add/remove methods based on the generic type of the list. In addition, it will also
create fireXXX methods based on the public methods declared on the class:
http://docs.groovy-lang.org/latest/html/documentation/ 296/502
1/6/2019 Groovy Language Documentation
java.awt. .
java.awt. .
groovy.beans.
@ListenerList
< > listeners
addActionListener( listener) {
( listener == ) {
}
( listeners == ) {
listeners = []
}
listeners.add(listener)
}
removeActionListener( listener) {
( listener == ) {
}
( listeners == ) {
listeners = []
}
listeners.remove(listener)
}
[] getActionListeners() {
__result = []
( listeners != ) {
__result.addAll(listeners)
}
(( __result ) [])
}
fireActionPerformed( param0) {
( listeners != ) {
< > __list = < >(listeners)
( listener : __list ) {
listener.actionPerformed(param0)
}
}
}
}
@Bindable supports multiple options that will let you further customize the behavior of the transformation:
Attribute Default value Description Example
name Generic type By default, the su x which will be
{
name appended to add/remove/…
@ListenerList(name='item')
methods is the simple class name < > listeners;
of the generic type of the list. }
synchronize false If set to true, generated methods
{
will be synchronized
@ListenerList(synchronize = )
< > listeners;
}
@groovy.beans.Vetoable
http://docs.groovy-lang.org/latest/html/documentation/ 297/502
1/6/2019 The @Vetoable annotation works in a similar manner to Groovy
@Bindable but generates
Language constrained property according to the
Documentation
JavaBeans speci cation, instead of bound properties. The annotation can be placed on a class, meaning that all properties will be
converted to constrained properties, or on a single property. For example, annotating this class with @Vetoable :
groovy.beans.
java.beans.
java.beans.
@Vetoable
{
name
age
}
is equivalent to writing this:
name
age
java.beans. $vetoableChangeSupport
addVetoableChangeListener( listener) {
$vetoableChangeSupport.addVetoableChangeListener(listener)
}
addVetoableChangeListener( name, listener) {
$vetoableChangeSupport.addVetoableChangeListener(name, listener)
}
removeVetoableChangeListener( listener) {
$vetoableChangeSupport.removeVetoableChangeListener(listener)
}
removeVetoableChangeListener( name, listener) {
$vetoableChangeSupport.removeVetoableChangeListener(name, listener)
}
fireVetoableChange( name, oldValue, newValue)
{
$vetoableChangeSupport.fireVetoableChange(name, oldValue, newValue)
}
[] getVetoableChangeListeners() {
$vetoableChangeSupport.getVetoableChangeListeners()
}
[] getVetoableChangeListeners( name) {
$vetoableChangeSupport.getVetoableChangeListeners(name)
}
setName( value) {
.fireVetoableChange('name', name, value)
name = value
}
setAge( value) {
.fireVetoableChange('age', age, value)
age = value
}
}
If the annotation is put on a single property, only that property is made vetoable:
http://docs.groovy-lang.org/latest/html/documentation/ 298/502
1/6/2019 Groovy Language Documentation
groovy.beans.
{
name
@Vetoable age
}
Test assistance
@groovy.transform.NotYetImplemented
@NotYetImplemented is used to invert the result of a JUnit 3/4 test case. It is in particular useful if a feature is not yet
implemented but the test is. In that case, it is expected that the test fails. Marking it with @NotYetImplemented will inverse the
result of the test, like in this example:
groovy.transform.
{
fib( n) {
// todo: implement later
}
}
{
@NotYetImplemented
testFib() {
dataTable = [
1:1,
2:1,
3:2,
4:3,
5:5,
6:8,
7:13
]
dataTable.each { i, r ->
.fib(i) == r
}
}
}
Another advantage of using this technique is that you can write test cases for bugs before knowing how to x them. If some time
in the future, a modi cation in the code xes a bug by side e ect, you’ll be noti ed because a test which was expected to fail
passed.
@groovy.transform.ASTTest
@ASTTest is a special AST transformation meant to help debugging other AST transformations or the Groovy compiler itself. It will
let the developer "explore" the AST during compilation and perform assertions on the AST rather than on the result of
compilation. This means that this AST transformations gives access to the AST before the bytecode is produced. @ASTTest can be
placed on any annotable node and requires two parameters:
phase: sets at which phase at which @ASTTest will be triggered. The test code will work on the AST tree at the end of this
phase.
value: the code which will be executed once the phase is reached, on the annotated node
Compile phase has to be chosen from one of org.codehaus.groovy.control.CompilePhase (http://docs.groovy-
lang.org/2.5.5/html/gapi/index.html?org/codehaus/groovy/control/CompilePhase.html) . However, since it is not
possible to annotate a node twice with the same annotation, you will not be able to use @ASTTest on the same
node at two distinct compile phases.
value is a closure expression which has access to a special variable node corresponding to the annotated node, and a helper
lookup method which will be discussed here. For example, you can annotate a class node like this:
http://docs.groovy-lang.org/latest/html/documentation/ 299/502
1/6/2019 Groovy Language Documentation
groovy.transform.
org.codehaus.groovy.ast.
org.codehaus.groovy.control. .*
@ASTTest(phase=CONVERSION, value={ 1
node 2
node.name == 'Person' 3
})
{
1 we’re checking the state of the Abstract Syntax Tree after the CONVERSION phase
2 node refers to the AST node which is annotated by @ASTTest
3 it can be used to perform assertions at compile time
One interesting feature of @ASTTest is that if an assertion fails, then compilation will fail. Now imagine that we want to check the
behavior of an AST transformation at compile time. We will take @PackageScope here, and we will want to verify that a property
annotated with @PackageScope becomes a package private eld. For this, we have to know at which phase the transform runs,
which can be found in org.codehaus.groovy.transform.PackageScopeASTTransformation (http://docs.groovy-
lang.org/2.5.5/html/gapi/index.html?org/codehaus/groovy/transform/PackageScopeASTTransformation.html) : semantic analysis.
Then a test can be written like this:
groovy.transform.
groovy.transform.
org.codehaus.groovy.control. .*
@ASTTest(phase=SEMANTIC_ANALYSIS, value= {
nameNode = node.properties.find { it.name == 'name' }
ageNode = node.properties.find { it.name == 'age' }
nameNode
ageNode == // shouldn't be a property anymore
ageField = node.getDeclaredField 'age'
ageField.modifiers == 0
})
{
name
@PackageScope age
}
The @ASTTest annotation can only be placed wherever the grammar allows it. Sometimes, you would like to test the contents of
an AST node which is not annotable. In this case, @ASTTest provides a convenient lookup method which will search the AST for
nodes which are labelled with a special token:
list = lookup('anchor') 1
stmt = list[0] 2
1 returns the list of AST nodes which label is 'anchor'
2 it is always necessary to choose which element to process since lookup always returns a list
Imagine, for example, that you want to test the declared type of a for loop variable. Then you can do it like this:
http://docs.groovy-lang.org/latest/html/documentation/ 300/502
1/6/2019 Groovy Language Documentation
groovy.transform.
groovy.transform.
org.codehaus.groovy.ast.
org.codehaus.groovy.ast.expr.
org.codehaus.groovy.ast.stmt.
org.codehaus.groovy.control. .*
{
@ASTTest(phase=SEMANTIC_ANALYSIS, value= {
forLoop = lookup('anchor')[0]
forLoop
decl = forLoop.collectionExpression.expressions[0]
decl
decl.variableExpression.name == 'i'
decl.variableExpression.originType == .int_TYPE
})
someMethod() {
x = 1;
y = 10;
anchor: ( i=0; i<x+y; i++) {
println "$i"
}
}
}
@ASTTest also exposes those variables inside the test closure:
node corresponds to the annotated node, as usual
compilationUnit gives access to the current org.codehaus.groovy.control.CompilationUnit
compilePhase returns the current compile phase ( org.codehaus.groovy.control.CompilePhase )
The latter is interesting if you don’t specify the phase attribute. In that case, the closure will be executed after each compile phase
after (and including) SEMANTIC_ANALYSIS . The context of the transformation is kept after each phase, giving you a chance to
check what changed between two phases.
As an example, here is how you could dump the list of AST transformations registered on a class node:
groovy.transform.
groovy.transform.
groovy.transform.
org.codehaus.groovy.ast.
org.codehaus.groovy.control.
@ASTTest(value={
.err.println "Compile phase: $compilePhase"
cn = node
.err.println "Global AST xforms:
${compilationUnit?.ASTTransformationsContext?.globalTransformNames}"
.values().each {
transforms = cn.getTransforms(it)
(transforms) {
.err.println "Ast xforms for phase $it:"
transforms.each { map ->
.err.println(map)
}
}
}
})
@CompileStatic
@Immutable
{
}
http://docs.groovy-lang.org/latest/html/documentation/ 301/502
1/6/2019 And here is how you can memorize variables for testing between two phases:
Groovy Language Documentation
groovy.transform.
groovy.transform.
org.codehaus.groovy.ast.
org.codehaus.groovy.control.
@ASTTest(value={
(compilePhase== .INSTRUCTION_SELECTION) { 1
println "toString() was added at phase: ${added}"
added == .CANONICALIZATION 2
} {
(node.getDeclaredMethods('toString') && added== ) { 3
added = compilePhase 4
}
}
})
@ToString
{
name
}
1 if the current compile phase is instruction selection
2 then we want to make sure toString was added at CANONICALIZATION
3 otherwise, if toString exists and that the variable from the context, added is null
4 then it means that this compile phase is the one where toString was added
Grape handling
@groovy.lang.Grab
@groovy.lang.GrabConfig
@groovy.lang.GrabExclude
@groovy.lang.GrabResolver
@groovy.lang.Grapes
Grape is a dependency management engine embedded into Groovy, relying on several annotations which are described
thoroughly in this section of the guide.
Developing AST transformations
There are two kinds of transformations: global and local transformations.
Global transformations are applied to by the compiler on the code being compiled, wherever the transformation apply.
Compiled classes that implement global transformations are in a JAR added to the classpath of the compiler and contain
service locator le META-INF/services/org.codehaus.groovy.transform.ASTTransformation with a line with the name of
the transformation class. The transformation class must have a no-args constructor and implement the
org.codehaus.groovy.transform.ASTTransformation interface. It will be run against every source in the compilation, so
be sure to not create transformations which scan all the AST in an expansive and time-consuming manner, to keep the
compiler fast.
Local transformations are transformations applied locally by annotating code elements you want to transform. For this, we
reuse the annotation notation, and those annotations should implement
org.codehaus.groovy.transform.ASTTransformation . The compiler will discover them and apply the transformation on
these code elements.
Compilation phases guide
Groovy AST transformations must be performed in one of the nine de ned compilation phases
(org.codehaus.groovy.control.CompilePhase (http://docs.groovy-lang.org/2.5.5/html/gapi/index.html?
org/codehaus/groovy/control/CompilePhase.html)).
Global transformations may be applied in any phase, but local transformations may only be applied in the semantic analysis
phase or later. Brie y, the compiler phases are:
Initialization: source les are opened and environment con gured
Parsing: the grammar is used to to produce tree of tokens representing the source code
Conversion: An abstract syntax tree (AST) is created from token trees.
http://docs.groovy-lang.org/latest/html/documentation/ 302/502
1/6/2019 Semantic Analysis: Performs consistency and validity checks
Groovythat the grammar
Language can’t check for, and resolves classes.
Documentation
Canonicalization: Complete building the AST
Instruction Selection: instruction set is chosen, for example Java 6 or Java 7 bytecode level
Class Generation: creates the bytecode of the class in memory
Output: write the binary output to the le system
Finalization: Perform any last cleanup
Generally speaking, there is more type information available later in the phases. If your transformation is concerned with reading
the AST, then a later phase where information is more plentiful might be a good choice. If your transformation is concerned with
writing AST, then an earlier phase where the tree is more sparse might be more convenient.
Local transformations
Local AST transformations are relative to the context they are applied to. In most cases, the context is de ned by an annotation
that will de ne the scope of the transform. For example, annotating a eld would mean that the transformation applies to the
eld, while annotating the class would mean that the transformation applies to the whole class.
As a naive and simple example, consider wanting to write a @WithLogging transformation that would add console messages at
the start and end of a method invocation. So the following "Hello World" example would actually print "Hello World" along with a
start and stop message:
Poor man’s aspect oriented programming
@WithLogging
greet() {
println "Hello World"
}
greet()
A local AST transformation is an easy way to do this. It requires two things:
a de nition of the @WithLogging annotation
an implementation of org.codehaus.groovy.transform.ASTTransformation (http://docs.groovy-
lang.org/2.5.5/html/gapi/index.html?org/codehaus/groovy/transform/ASTTransformation.html) that adds the logging
expressions to the method
An ASTTransformation is a callback that gives you access to the org.codehaus.groovy.control.SourceUnit (http://docs.groovy-
lang.org/2.5.5/html/gapi/index.html?org/codehaus/groovy/control/SourceUnit.html), through which you can get a reference to the
org.codehaus.groovy.ast.ModuleNode (http://docs.groovy-lang.org/2.5.5/html/gapi/index.html?
org/codehaus/groovy/ast/ModuleNode.html) (AST).
The AST (Abstract Syntax Tree) is a tree structure consisting mostly of org.codehaus.groovy.ast.expr.Expression
(http://docs.groovy-lang.org/2.5.5/html/gapi/index.html?org/codehaus/groovy/ast/expr/Expression.html) (expressions) or
org.codehaus.groovy.ast.expr.Statement (http://docs.groovy-lang.org/2.5.5/html/gapi/index.html?
org/codehaus/groovy/ast/expr/Statement.html) (statements). An easy way to learn about the AST is to explore it in a debugger.
Once you have the AST, you can analyze it to nd out information about the code or rewrite it to add new functionality.
The local transformation annotation is the simple part. Here is the @WithLogging one:
org.codehaus.groovy.transform.
java.lang.annotation.
java.lang.annotation.
java.lang.annotation.
java.lang.annotation.
@Retention( .SOURCE)
@Target([ .METHOD])
@GroovyASTTransformationClass(["gep.WithLoggingASTTransformation"])
@interface {
}
http://docs.groovy-lang.org/latest/html/documentation/ 303/502
1/6/2019 The annotation retention can be SOURCE because you won’t needLanguage
Groovy the annotation past that. The element type here is METHOD , the
Documentation
@WithLogging because the annotation applies to methods.
But the most important part is the @GroovyASTTransformationClass annotation. This links the @WithLogging annotation to
the ASTTransformation class you will write. gep.WithLoggingASTTransformation is the fully quali ed class name of the
ASTTransformation we are going to write. This line wires the annotation to the transformation.
With this in place, the Groovy compiler is going to invoke gep.WithLoggingASTTransformation every time an @WithLogging is
found in a source unit. Any breakpoint set within LoggingASTTransformation will now be hit within the IDE when running the
sample script.
The ASTTransformation class is a little more complex. Here is the very simple, and very naive, transformation to add a method
start and stop message for @WithLogging :
@CompileStatic 1
@GroovyASTTransformation(phase= .SEMANTIC_ANALYSIS) 2
{ 3
@Override
visit( [] nodes, sourceUnit) { 4
method = ( ) nodes[1] 5
startMessage = createPrintlnAst("Starting $method.name") 6
endMessage = createPrintlnAst("Ending $method.name") 7
existingStatements = (( )method.code).statements 8
existingStatements.add(0, startMessage) 9
existingStatements.add(endMessage) 10
createPrintlnAst( message) { 11
(
(
("this"),
("println"),
(
(message)
)
)
)
}
}
even if not mandatory, if you write an AST transformation in Groovy, it is highly recommended to use CompileStatic
1
because it will improve performance of the compiler.
annotate with org.codehaus.groovy.transform.GroovyASTTransformation (http://docs.groovy-
2 lang.org/2.5.5/html/gapi/index.html?org/codehaus/groovy/transform/GroovyASTTransformation.html) to tell at which
compilation phase the transform needs to run. Here, it’s at the semantic analysis phase.
3 implement the ASTTransformation interface
4 which only has a single visit method
the nodes parameter is a 2 AST node array, for which the rst one is the annotation node ( @WithLogging ) and the second
5
one is the annotated node (the method node)
6 create a statement that will print a message when we enter the method
7 create a statement that will print a message when we exit the method
8 get the method body, which in this case is a BlockStatement
9 add the enter method message before the rst statement of existing code
10 append the exit method message after the last statement of existing code
11 creates an ExpressionStatement wrapping a MethodCallExpression corresponding to this.println("message")
http://docs.groovy-lang.org/latest/html/documentation/ 304/502
1/6/2019 It is important to notice that for the brevity of this example, we didn’t
Groovy make Documentation
Language the necessary checks, such as checking that the
annotated node is really a MethodNode , or that the method body is an instance of BlockStatement . This exercise is left to the
reader.
Note the creation of the new println statements in the createPrintlnAst(String) method. Creating AST for code is not always
simple. In this case we need to construct a new method call, passing in the receiver/variable, the name of the method, and an
argument list. When creating AST, it might be helpful to write the code you’re trying to create in a Groovy le and then inspect the
AST of that code in the debugger to learn what to create. Then write a function like createPrintlnAst using what you learned
through the debugger.
In the end:
@WithLogging
greet() {
println "Hello World"
}
greet()
Produces:
Starting greet
Hello World
Ending greet
It is important to note that an AST transformation participates directly in the compilation process. A common
error by beginners is to have the AST transformation code in the same source tree as a class that uses the
transformation. Being in the same source tree in general means that they are compiled at the same time. Since
the transformation itself is going to be compiled in phases and that each compile phase processes all les of the
same source unit before going to the next one, there’s a direct consequence: the transformation will not be
compiled before the class that uses it! In conclusion, AST transformations need to be precompiled before you can
use them. In general, it is as easy as having them in a separate source tree.
Global transformations
Global AST transformation are similar to local one with a major di erence: they do not need an annotation, meaning that they are
applied globally, that is to say on each class being compiled. It is therefore very important to limit their use to last resort, because
it can have a signi cant impact on the compiler performance.
Following the example of the local AST transformation, imagine that we would like to trace all methods, and not only those which
are annotated with @WithLogging . Basically, we need this code to behave the same as the one annotated with @WithLogging
before:
greet() {
println "Hello World"
}
greet()
To make this work, there are two steps:
1. create the org.codehaus.groovy.transform.ASTTransformation descriptor inside the META-INF/services directory
2. create the ASTTransformation implementation
The descriptor le is required and must be found on classpath. It will contain a single line:
META-INF/services/org.codehaus.groovy.transform.ASTTransformation
gep.
The code for the transformation looks similar to the local case, but instead of using the ASTNode[] parameter, we need to use
the SourceUnit instead:
http://docs.groovy-lang.org/latest/html/documentation/ 305/502
1/6/2019 gep/WithLoggingASTTransformation.groovy Groovy Language Documentation
@CompileStatic 1
@GroovyASTTransformation(phase= .SEMANTIC_ANALYSIS) 2
{ 3
@Override
visit( [] nodes, sourceUnit) { 4
methods = sourceUnit.AST.methods 5
methods.each { method -> 6
startMessage = createPrintlnAst("Starting $method.name") 7
endMessage = createPrintlnAst("Ending $method.name") 8
existingStatements = (( )method.code).statements 9
existingStatements.add(0, startMessage) 10
existingStatements.add(endMessage) 11
}
}
createPrintlnAst( message) { 12
(
(
("this"),
("println"),
(
(message)
)
)
)
}
}
even if not mandatory, if you write an AST transformation in Groovy, it is highly recommended to use CompileStatic
1
because it will improve performance of the compiler.
annotate with org.codehaus.groovy.transform.GroovyASTTransformation (http://docs.groovy-
2 lang.org/2.5.5/html/gapi/index.html?org/codehaus/groovy/transform/GroovyASTTransformation.html) to tell at which
compilation phase the transform needs to run. Here, it’s at the semantic analysis phase.
3 implement the ASTTransformation interface
4 which only has a single visit method
the sourceUnit parameter gives access to the source being compiled, so we get the AST of the current source and retrieve
5
the list of methods from this le
6 we iterate on each method from the source le
7 create a statement that will print a message when we enter the method
8 create a statement that will print a message when we exit the method
9 get the method body, which in this case is a BlockStatement
10 add the enter method message before the rst statement of existing code
11 append the exit method message after the last statement of existing code
12 creates an ExpressionStatement wrapping a MethodCallExpression corresponding to this.println("message")
AST API guide
AbstractASTTransformation
While you have seen that you can directly implement the ASTTransformation interface, in almost all cases you will not do this
but extend the org.codehaus.groovy.transform.AbstractASTTransformation (http://docs.groovy-
lang.org/2.5.5/html/gapi/index.html?org/codehaus/groovy/transform/AbstractASTTransformation.html) class. This class provides
several utility methods that make AST transformations easier to write. Almost all AST transformations included in Groovy extend
this class.
ClassCodeExpressionTransformer
It is a common use case to be able to transform an expression into another. Groovy provides a class which makes it very easy to
do this: org.codehaus.groovy.ast.ClassCodeExpressionTransformer (http://docs.groovy-lang.org/2.5.5/html/gapi/index.html?
org/codehaus/groovy/ast/ClassCodeExpressionTransformer.html)
http://docs.groovy-lang.org/latest/html/documentation/ 306/502
1/6/2019 To illustrate this, let’s create a @Shout transformation that will transform
Groovy Languageall String constants in method call arguments into
Documentation
their uppercase version. For example:
@Shout
greet() {
println "Hello World"
}
greet()
should print:
HELLO WORLD
Then the code for the transformation can use the ClassCodeExpressionTransformer to make this easier:
@CompileStatic
@GroovyASTTransformation(phase= .SEMANTIC_ANALYSIS)
{
@Override
visit( [] nodes, sourceUnit) {
trn = () { 1
inArgList =
@Override
getSourceUnit() {
sourceUnit 2
@Override
transform( exp) {
(exp ) {
inArgList =
} (inArgList &&
exp && exp.value ) {
(exp.value.toUpperCase()) 3
}
trn = .transform(exp)
inArgList =
trn
}
}
trn.visitMethod(( )nodes[1]) 4
}
}
1 Internally the transformation creates a ClassCodeExpressionTransformer
2 The transformer needs to return the source unit
3 if a constant expression of type string is detected inside an argument list, transform it into its upper case version
4 call the transformer on the method being annotated
AST Nodes
Writing an AST transformation requires a deep knowledge of the internal Groovy API. In particular it requires
knowledge about the AST classes. Since those classes are internal, there are chances that the API will change in
the future, meaning that your transformations could break. Despite that warning, the AST has been very stable
over time and such a thing rarely happens.
Classes of the Abstract Syntax Tree belong to the org.codehaus.groovy.ast package. It is recommended to the reader to use
the Groovy Console, in particular the AST browser tool, to gain knowledge about those classes. However, a good resource for
learning is the AST Builder (https://github.com/apache/groovy/tree/master/src/test/org/codehaus/groovy/ast/builder) test suite.
Macros
http://docs.groovy-lang.org/latest/html/documentation/ 307/502
1/6/2019 Introduction Groovy Language Documentation
Until version 2.5.0, when developing AST transformations, developers should have a deep knowledge about how the AST (Abstract
Syntax Tree) was built by the compiler in order to know how to add new expressions or statements during compile time.
Although the use of org.codehaus.groovy.ast.tool.GeneralUtils static methods could mitigate the burden of creating
expressions and statements, it’s still a low-level way of writing those AST nodes directly. We needed something to abstract us from
writing the AST directly and that’s exactly what Groovy macros were made for. They allow you to directly add code during
compilation, without having to translate the code you had in mind to the org.codehaus.groovy.ast.* node related classes.
Statements and expressions
Let’s see an example, lets create a local AST transformation: @AddMessageMethod . When applied to a given class it will add a new
method called getMessage to that class. The method will return "42". The annotation is pretty straight forward:
@Retention( .SOURCE)
@Target([ .TYPE])
@GroovyASTTransformationClass(["metaprogramming.AddMethodASTTransformation"])
@interface { }
What would the AST transformation look like without the use of a macro ? Something like this:
@GroovyASTTransformation(phase = .INSTRUCTION_SELECTION)
{
@Override
visit( [] nodes, source) {
classNode = ( ) nodes[1]
code =
( 1
("42")) 2
methodNode =
(
"getMessage",
ACC_PUBLIC,
.make( ),
[] [],
[] [],
code) 3
classNode.addMethod(methodNode) 4
}
}
1 Create a return statement
2 Create a constant expression "42"
3 Adding the code to the new method
4 Adding the new method to the annotated class
If you’re not used to the AST API, that de nitely doesn’t look like the code you had in mind. Now look how the previous code
simpli es with the use of macros.
http://docs.groovy-lang.org/latest/html/documentation/ 308/502
1/6/2019 Groovy Language Documentation
@GroovyASTTransformation(phase = .INSTRUCTION_SELECTION)
{
@Override
visit( [] nodes, source) {
classNode = ( ) nodes[1]
simplestCode = macro { "42" } 1
methodNode =
(
"getMessage",
ACC_PUBLIC,
.make( ),
[] [],
[] [],
simplestCode) 2
classNode.addMethod(methodNode) 3
}
}
Much simpler. You wanted to add a return statement that returned "42" and that’s exactly what you can read inside the
1
macro utility method. Your plain code will be translated for you to a org.codehaus.groovy.ast.stmt.ReturnStatement
2 Adding the return statement to the new method
3 Adding the new code to the annotated class
Although the macro method is used in this example to create a statement the macro method could also be used to create
expressions as well, it depends on which macro signature you use:
macro(Closure) : Create a given statement with the code inside the closure.
macro(Boolean,Closure) : if true wrap expressions inside the closure inside an statement, if false then return an expression
macro(CompilePhase, Closure) : Create a given statement with the code inside the closure in a speci c compile phase
macro(CompilePhase, Boolean, Closure) : Create an statement or an expression (true == statement, false == expression)
in a speci c compilation phase.
All these signatures can be found at org.codehaus.groovy.macro.runtime.MacroGroovyMethods
Sometimes we could be only interested in creating a given expression, not the whole statement, in order to do that we should use
any of the macro invocations with a boolean parameter:
http://docs.groovy-lang.org/latest/html/documentation/ 309/502
1/6/2019 Groovy Language Documentation
@GroovyASTTransformation(phase = .INSTRUCTION_SELECTION)
{
onePlusOne() {
macro( ) { 1 + 1 } 1
@Override
visit( [] nodes, source) {
classNode = nodes[1]
expression = onePlusOne() 2
returnStatement = .returnS(expression) 3
methodNode =
("getTwo",
ACC_PUBLIC,
. ,
[] [],
[] [],
returnStatement 4
classNode.addMethod(methodNode) 5
}
}
1 We’re telling macro not to wrap the expression in a statement, we’re only interested in the expression
2 Assigning the expression
3 Creating a ReturnStatement using a method from GeneralUtils and returning the expression
4 Adding the code to the new method
5 Adding the method to the class
Variable substitution
Macros are great but we can’t create anything useful or reusable if our macros couldn’t receive parameters or resolve surrounding
variables.
In the following example we’re creating an AST transformation @MD5 that when applied to a given String eld will add a method
returning the MD5 value of that eld.
@Retention( .SOURCE)
@Target([ .FIELD])
@GroovyASTTransformationClass(["metaprogramming.MD5ASTTransformation"])
@interface MD5 { }
And the transformation:
http://docs.groovy-lang.org/latest/html/documentation/ 310/502
1/6/2019 Groovy Language Documentation
@GroovyASTTransformation(phase = .CANONICALIZATION)
MD5ASTTransformation {
@Override
visit( [] nodes, source) {
fieldNode = nodes[1]
classNode = fieldNode.declaringClass
capitalizedName = fieldNode.name.capitalize()
methodNode = (
"get${capitalizedName}MD5",
ACC_PUBLIC,
.STRING_TYPE,
[] [],
[] [],
buildMD5MethodCode(fieldNode))
classNode.addMethod(methodNode)
}
buildMD5MethodCode( fieldNode) {
fieldVar = .varX(fieldNode.name) 1
macro( .SEMANTIC_ANALYSIS, ) { 2
java.security.
.getInstance('MD5')
.digest($v { fieldVar }.getBytes()) 3
.encodeHex()
.toString()
}
}
}
1 We need a reference to a variable expression
If using a class outside the standard packages we should add any needed imports or use the quali ed name. When using
the quali ed named of a given static method you need to make sure it’s resolved in the proper compile phase. In this
2
particular case we’re instructing the macro to resolve it at the SEMANTIC_ANALYSIS phase, which is the rst compile phase
with type information.
In order to substitute any expression inside the macro we need to use the $v method. $v receives a closure as an
3 argument, and the closure is only allowed to substitute expressions, meaning classes inheriting
org.codehaus.groovy.ast.expr.Expression .
MacroClass
As we mentioned earlier, the macro method is only capable of producing statements and expressions . But what if we want to
produce other types of nodes, such as a method, a eld and so on?
org.codehaus.groovy.macro.transform.MacroClass can be used to create classes (ClassNode instances) in our
transformations the same way we created statements and expressions with the macro method before.
The next example is a local transformation @Statistics . When applied to a given class, it will add two methods
getMethodCount() and getFieldCount() which return how many methods and elds within the class respectively. Here is the
marker annotation.
@Retention( .SOURCE)
@Target([ .TYPE])
@GroovyASTTransformationClass(["metaprogramming.StatisticsASTTransformation"])
@interface {}
And the AST transformation:
http://docs.groovy-lang.org/latest/html/documentation/ 311/502
1/6/2019 Groovy Language Documentation
@CompileStatic
@GroovyASTTransformation(phase = .INSTRUCTION_SELECTION)
{
@Override
visit( [] nodes, source) {
classNode = ( ) nodes[1]
templateClass = buildTemplateClass(classNode) 1
templateClass.methods.each { node -> 2
classNode.addMethod(node)
}
}
@CompileDynamic
buildTemplateClass( reference) { 3
methodCount = constX(reference.methods.size()) 4
fieldCount = constX(reference.fields.size()) 5
() {
{
java.lang. getMethodCount() { 6
$v { methodCount }
}
java.lang. getFieldCount() { 7
$v { fieldCount }
}
}
}
}
}
1 Creating a template class
2 Adding template class methods to the annotated class
3 Passing the reference class
4 Extracting reference class method count value expression
5 Extracting reference class eld count value expression
6 Building the getMethodCount() method using reference’s method count value expression
7 Building the getFieldCount() method using reference’s eld count value expression
Basically we’ve created the Statistics class as a template to avoid writing low level AST API, then we copied methods created in the
template class to their nal destination.
Types inside the MacroClass implementation should be resolved inside, that’s why we had to write
java.lang.Integer instead of simply writing Integer .
Notice that we’re using @CompileDynamic . That’s because the way we use MacroClass is like we were actually
implementing it. So if you were using @CompileStatic it will complain because an implementation of an abstract
class can’t be another di erent class.
@Macro methods
You have seen that by using macro you can save yourself a lot of work but you might wonder where that method came from. You
didn’t declare it or static import it. You can think of it as a special global method (or if you prefer, a method on every Object ). This
is much like how the println extension method is de ned. But unlike println which becomes a method selected for execution
later in the compilation process, macro expansion is done early in the compilation process. The declaration of macro as one of
the available methods for this early expansion is done by annotating a macro method de nition with the @Macro annotation and
making that method available using a similar mechanism for extension modules. Such methods are known as macro methods and
the good news is you can de ne your own.
To de ne your own macro method, create a class in a similar way to an extension module and add a method such as:
http://docs.groovy-lang.org/latest/html/documentation/ 312/502
1/6/2019 Groovy Language Documentation
{
@Macro
safe( macroContext, callExpression) {
ternaryX(
notNullX(callExpression.getObjectExpression()),
callExpression,
constX( )
);
}
...
}
Now you would register this as an extension module using a org.codehaus.groovy.runtime.ExtensionModule le within the
META-INF/groovy directory.
Now, assuming that the class and meta info le are on your classpath, you can use the macro method in the following way:
nullObject =
== safe(safe(nullObject.hashcode()).toString())
Testing AST transformations
Separating source trees
This section is about good practices with regards to testing AST transformations. Previous sections highlighted the fact that to be
able to execute an AST transformation, it has to be precompiled. It might sound obvious but a lot of people get caught on this,
trying to use an AST transformation in the same source tree as where it is de ned.
The rst tip for testing AST transformation is therefore to separate test sources from the sources of the transform. Again, this is
nothing but best practices, but you must make sure that your build too does actually compile them separately. This is the case by
default with both Apache Maven (http://maven.apache.org) and Gradle (http://gradle.org).
Debugging AST transformations
It is very handy to be able to put a breakpoint in an AST transformation, so that you can debug your code in the IDE. However, you
might be surprised to see that your IDE doesn’t stop on the breakpoint. The reason is actually simple: if your IDE uses the Groovy
compiler to compile the unit tests for your AST transformation, then the compilation is triggered from the IDE, but the process
which will compile the les doesn’t have debugging options. It’s only when the test case is executed that the debugging options
are set on the virtual machine. In short: it is too late, the class has been compiled already, and your transformation is already
applied.
A very easy workaround is to use the GroovyTestCase class which provides an assertScript method. This means that instead
of writing this in a test case:
{
@MyTransformToDebug
methodToBeTested() {}
}
testMyTransform() {
c = ()
c.methodToBeTested()
}
You should write:
http://docs.groovy-lang.org/latest/html/documentation/ 313/502
1/6/2019 Groovy Language Documentation
testMyTransformWithBreakpoint() {
assertScript '''
import metaprogramming.MyTransformToDebug
class Subject {
@MyTransformToDebug
void methodToBeTested() {}
}
def c = new Subject()
c.methodToBeTested()
'''
}
The di erence is that when you use assertScript , the code in the assertScript block is compiled when the unit test is
executed. That is to say that this time, the Subject class will be compiled with debugging active, and the breakpoint is going to
be hit.
ASTMatcher
Sometimes you may want to make assertions over AST nodes; perhaps to lter the nodes, or to make sure a given transformation
has built the expected AST node.
Filtering nodes
For instance if you would like to apply a given transformation only to a speci c set of AST nodes, you could use ASTMatcher to
lter these nodes. The following example shows how to transform a given expression to another. Using ASTMatcher it looks for a
speci c expression 1 + 1 and it transforms it to 3 . That’s why we called it the @Joking example.
First we create the @Joking annotation that only can be applied to methods:
@Retention( .SOURCE)
@Target([ .METHOD])
@GroovyASTTransformationClass(["metaprogramming.JokingASTTransformation"])
@interface { }
Then the transformation, that only applies an instance of org.codehaus.groovy.ast.ClassCodeExpressionTransformer to all
the expressions within the method code block.
@CompileStatic
@GroovyASTTransformation(phase = .INSTRUCTION_SELECTION)
{
@Override
visit( [] nodes, source) {
methodNode = ( ) nodes[1]
methodNode
.getCode()
.visit( (source)) 1
}
}
1 Get the method’s code statement and apply the expression transformer
And this is when the ASTMatcher is used to apply the transformation only to those expressions matching the expression 1 + 1 .
http://docs.groovy-lang.org/latest/html/documentation/ 314/502
1/6/2019 Groovy Language Documentation
{
sourceUnit
( sourceUnit) {
.sourceUnit = sourceUnit
}
@Override
transform( exp) {
= macro { 1 + 1 } 1
( .matches( , exp)) { 2
macro { 3 } 3
.transform(exp)
}
}
1 Builds the expression used as reference pattern
2 Checks the current expression evaluated matches the reference expression
3 If it matches then replaces the current expression with the expression built with macro
Then you could test the implementation as follows:
metaprogramming
{
@Joking
getResult() {
1 + 1
}
}
().result == 3
Unit testing AST transforms
Normally we test AST transformations just checking that the nal use of the transformation does what we expect. But it would be
great if we could have an easy way to check, for example, that the nodes the transformation adds are what we expected from the
beginning.
The following transformation adds a new method giveMeTwo to an annotated class.
http://docs.groovy-lang.org/latest/html/documentation/ 315/502
1/6/2019 Groovy Language Documentation
@GroovyASTTransformation(phase = .INSTRUCTION_SELECTION)
{
VAR_X = 'x'
@Override
visit( [] nodes, source) {
classNode = ( ) nodes[1]
giveMeTwo = getTemplateClass(sumExpression)
.getDeclaredMethods('giveMeTwo')
.first()
classNode.addMethod(giveMeTwo) 1
getSumExpression() { 2
macro {
$v{ varX(VAR_X) } +
$v{ varX(VAR_X) }
}
}
getTemplateClass( expression) { 3
() {
{
java.lang. giveMeTwo(java.lang. x) {
$v { expression }
}
}
}
}
}
1 Adding the method to the annotated class
Building a binary expression. The binary expression uses the same variable expression in both sides of the + token (check
2
varX method at org.codehaus.groovy.ast.tool.GeneralUtils).
3 Builds a new ClassNode with a method called giveMeTwo which returns the result of an expression passed as parameter.
Now instead of creating a test executing the transformation over a given sample code. I would like to check that the construction
of the binary expression is done properly:
testTestingSumExpression() {
( ) { 1
sample = ()
referenceNode = macro {
a + a 2
}.withConstraints { 3
placeholder 'a' 4
sample
.sumExpression
.matches(referenceNode) 5
}
}
1 Using ASTMatcher as a category
2 Build a template node
3 Apply some constraints to that template node
4 Tells compiler that a is a placeholder.
5 Asserts reference node and current node are equal
Of course you can/should always check the actual execution:
http://docs.groovy-lang.org/latest/html/documentation/ 316/502
1/6/2019 Groovy Language Documentation
testASTBehavior() {
assertScript '''
package metaprogramming
@Twice
class AAA {
assert new AAA().giveMeTwo(1) == 2
'''
}
ASTTest
Last but not least, testing an AST transformation is also about testing the state of the AST during compilation. Groovy provides a
tool named @ASTTest for this: it is an annotation that will let you add assertions on an abstract syntax tree. Please check the
documentation for ASTTest for more details.
External references
If you are interested in a step-by-step tutorial about writing AST transformations, you can follow this workshop
(http://melix.github.io/ast-workshop/).
3.5. Dependency management with Grape
3.5.1. Quick start
Add a Dependency
Grape is a JAR dependency manager embedded into Groovy. Grape lets you quickly add maven repository dependencies to your
classpath, making scripting even easier. The simplest use is as simple as adding an annotation to your script:
@Grab( ='org.springframework', ='spring-orm', version='3.2.5.RELEASE')
org.springframework.jdbc.core.
@Grab also supports a shorthand notation:
@Grab('org.springframework:spring-orm:3.2.5.RELEASE')
org.springframework.jdbc.core.
Note that we are using an annotated import here, which is the recommended way. You can also search for dependencies on
mvnrepository.com (http://mvnrepository.com) and it will provide you the @Grab annotation form of the pom.xml entry.
Specify Additional Repositories
Not all dependencies are in maven central. You can add new ones like this:
@GrabResolver(name='restlet', root='http://maven.restlet.org/')
@Grab( ='org.restlet', ='org.restlet', version='1.1.6')
Maven Classi ers
Some maven dependencies need classi ers in order to be able to resolve. You can x that like this:
@Grab( ='net.sf.json-lib', ='json-lib', version='2.2.3', classifier='jdk15')
Excluding Transitive Dependencies
Sometimes you will want to exclude transitive dependencies as you might be already using a slightly di erent but compatible
version of some artifact. You can do this as follows:
@Grab('net.sourceforge.htmlunit:htmlunit:2.8')
@GrabExclude('xml-apis:xml-apis')
JDBC Drivers
http://docs.groovy-lang.org/latest/html/documentation/ 317/502
1/6/2019 Because of the way JDBC drivers are loaded, you’ll need toGroovy
con gure Grape Documentation
Language to attach JDBC driver dependencies to the system class
loader. I.e:
@GrabConfig(systemClassLoader= )
@Grab( ='mysql', ='mysql-connector-java', version='5.1.6')
Using Grape From the Groovy Shell
From groovysh use the method call variant:
groovy.grape. .grab( :'org.springframework', :'spring', version:'2.5.6')
Proxy settings
If you are behind a rewall and/or need to use Groovy/Grape through a proxy server, you can specify those settings on the
command like via the http.proxyHost and http.proxyPort system properties:
groovy -Dhttp.proxyHost=yourproxy -Dhttp.proxyPort=8080 yourscript.groovy
Or you can make this system wide by adding these properties to your JAVA_OPTS environment variable:
JAVA_OPTS = -Dhttp.proxyHost=yourproxy -Dhttp.proxyPort=8080
Logging
If you want to see what Grape is doing set the system property groovy.grape.report.downloads to true (e.g. add
-Dgroovy.grape.report.downloads=true to invocation or JAVA_OPTS) and Grape will print the following infos to System.error:
Starting resolve of a dependency
Starting download of an artifact
Retrying download of an artifact
Download size and time for downloaded artifacts
To log with even more verbosity, increase the Ivy log level (defaults to -1 ). For example -Divy.message.logger.level=4 .
3.5.2. Detail
Grape (The Groovy Adaptable Packaging Engine or Groovy Advanced Packaging Engine) is the infrastructure enabling the grab()
calls in Groovy, a set of classes leveraging Ivy (http://ant.apache.org/ivy/) to allow for a repository driven module system for
Groovy. This allows a developer to write a script with an essentially arbitrary library requirement, and ship just the script. Grape
will, at runtime, download as needed and link the named libraries and all dependencies forming a transitive closure when the
script is run from existing repositories such as JCenter, Ibiblio and java.net.
Grape follows the Ivy conventions for module version identi cation, with naming change.
group - Which module group the module comes from. Translates directly to a Maven groupId or an Ivy Organization. Any
group matching /groovy[x][\..*]^/ is reserved and may have special meaning to the groovy endorsed modules.
module - The name of the module to load. Translated directly to a Maven artifactId or an Ivy artifact.
version - The version of the module to use. Either a literal version `1.1-RC3' or an Ivy Range `[2.2.1,)' meaning 2.2.1 or any
greater version).
classifier - The optional classi er to use (for example, jdk15)
The downloaded modules will be stored according to Ivy’s standard mechanism with a cache root of ~/.groovy/grapes
3.5.3. Usage
Annotation
One or more groovy.lang.Grab annotations can be added at any place that annotations are accepted to tell the compiler that
this code relies on the speci c library. This will have the e ect of adding the library to the classloader of the groovy compiler. This
annotation is detected and evaluated before any other resolution of classes in the script, so imported classes can be properly
resolved by a @Grab annotation.
http://docs.groovy-lang.org/latest/html/documentation/ 318/502
1/6/2019 Groovy Language Documentation
com.jidesoft.swing.
@Grab( ='com.jidesoft', ='jide-oss', version='[2.2.1,2.3.0)')
{
testMethod () {
. .name
}
}
An appropriate grab(…) call will be added to the static initializer of the class of the containing class (or script class in the case of
an annotated script element).
Multiple Grape Annotations
In early versions of Groovy, if you wanted to use a Grab annotation multiple times on the same node you had to use the @Grapes
annotation, e.g.:
@Grapes([
@Grab( ='commons-primitives', ='commons-primitives', version='1.0'),
@Grab( ='org.ccil.cowan.tagsoup', ='tagsoup', version='0.9.7')])
{
// ...
}
Otherwise you’d encounter the following error:
Cannot specify duplicate annotation on the same member
But in recent versions, @Grapes is purely optional.
Technical notes:
Originally, Groovy stored the Grab annotations for access at runtime and duplicates aren’t allowed in the bytecode. In current
versions, @Grab has only SOURCE retention, so the multiple occurrences aren’t an issue.
Future versions of Grape may support using the Grapes annotation to provide a level of structuring, e.g. allowing a
GrabExclude or GrabResolver annotation to apply to only a subset of the Grab annotations.
Method call
Typically a call to grab will occur early in the script or in class initialization. This is to insure that the libraries are made available to
the ClassLoader before the groovy code relies on the code. A couple of typical calls may appear as follows:
groovy.grape.
// random maven library
.grab( :'com.jidesoft', :'jide-oss', version:'[2.2.0,)')
.grab([ :'org.apache.ivy', :'ivy', version:'2.0.0-beta1', conf:['default',
'optional']],
[ :'org.apache.ant', :'ant', version:'1.7.0'])
Multiple calls to grab in the same context with the same parameters should be idempotent. However, if the same code is called
with a di erent ClassLoader context then resolution may be re-run.
If the args map passed into the grab call has an attribute noExceptions that evaluates true no exceptions will be thrown.
grab requires that a RootLoader or GroovyClassLoader be speci ed or be in the ClassLoader chain of the calling class.
By default failure to have such a ClassLoader available will result in module resolution and an exception being thrown
The ClassLoader passed in via the classLoader: argument and it’s parent classloaders.
The ClassLoader of the object passed in as the referenceObject: argument, and it’s parent classloaders.
The ClassLoader of the class issuing the call to grab
grab(HashMap) Parameters
group: - <String> - Which module group the module comes from. Translates directly to a Maven groupId. Any group matching
/groovy(|\..|x|x\..)/ is reserved and may have special meaning to the groovy endorsed modules.
http://docs.groovy-lang.org/latest/html/documentation/ 319/502
1/6/2019 module: - <String> - The name of the module to load.Groovy
Translated directly
Language to a Maven artifactId.
Documentation
version: - <String> and possibly <Range> - The version of the module to use. Either a literal version `1.1-RC3' or an Ivy Range
`[2.2.1,)' meaning 2.2.1 or any greater version).
classifier: - <String> - The Maven classi er to resolve by.
conf: - <String>, default
default' - The configuration or scope of the module to download. The default conf is `default: which
maps to the maven runtime and master scopes.
force: - <boolean>, defaults true - Used to indicate that this revision must be used in case of con icts, independently of
con icts manager
changing: - <boolean>, default false - Whether the artifact can change without it’s version designation changing.
transitive: - <boolean>, default true - Whether to resolve other dependencies this module has or not.
There are two principal variants of grab , one with a single Map and one with an arguments Map and multiple dependencies map.
A call to the single map grab is the same as calling grab with the same map passed in twice, so grab arguments and dependencies
can be mixed in the same map, and grab can be called as a single method with named parameters.
There are synonyms for these parameters. Submitting more than one is a runtime exception.
group: , groupId: , organisation: , organization: , org:
module: , artifactId: , artifact:
version: , revision: , rev:
conf: , scope: , configuration:
Arguments Map arguments
classLoader: - <GroovyClassLaoder> or <RootClassLoader> - The ClassLoader to add resolved Jars to
refObject: - <Object> - The closest parent ClassLoader for the object’s class will be treated as though it were passed in as
classLoader:
validate: - <boolean>, default false - Should poms or ivy les be validated (true), or should we trust the cache (false).
noExceptions: - <boolean>, default false - If ClassLoader resolution or repository querying fails, should we throw an
exception (false) or fail silently (true).
Command Line Tool
Grape added a command line executable `grape' that allows for the inspection and management of the local grape cache.
grape install [-hv] <group> <module> [<version>] [<classifier>]
This installs the speci ed groovy module or maven artifact. If a version is speci ed that speci c version will be installed, otherwise
the most recent version will be used (as if `*' we passed in).
grape list
Lists locally installed modules (with their full maven name in the case of groovy modules) and versions.
grape resolve [-adhisv] (<groupId> <artifactId> <version>)+
This returns the le locations of the jars representing the artifacts for the speci ed module(s) and the respective transitive
dependencies. You may optionally pass in -ant, -dos, or -shell to get the dependencies expressed in a format applicable for an ant
script, windows batch le, or unix shell script respectively. -ivy may be passed to see the dependencies expressed in an ivy like
format.
grape uninstall [-hv] <group> <module> <version>
This uninstalls a particular grape: it non-transitively removes the respective jar le from the grape cache.
Advanced con guration
http://docs.groovy-lang.org/latest/html/documentation/ 320/502
1/6/2019 Repository Directory Groovy Language Documentation
If you need to change the directory grape uses for downloading libraries you can specify the grape.root system property to
change the default (which is ~/.groovy/grapes)
groovy -Dgrape.root=/repo/grapes yourscript.groovy
Customize Ivy settings
You can customize the ivy settings that Grape uses by creating a ~/.groovy/grapeCon g.xml le. If no such le exists, here
(https://github.com/apache/groovy/blob/master/src/resources/groovy/grape/defaultGrapeCon g.xml) are the default settings
used by Grape.
For more information on how to customize these settings, please refer to the Ivy documentation
(https://ant.apache.org/ivy/history/latest-milestone/index.html).
More Examples
Using Apache Commons Collections:
// create and use a primitive array list
@Grab( ='commons-primitives', ='commons-primitives', version='1.0')
org.apache.commons.collections.primitives.
createEmptyInts() { () }
ints = createEmptyInts()
ints.add(0, 42)
ints.size() == 1
ints. (0) == 42
Using TagSoup:
// find the PDF links of the Java specifications
@Grab( ='org.ccil.cowan.tagsoup', ='tagsoup', version='1.2.1')
getHtml() {
parser = ( org.ccil.cowan.tagsoup. ())
parser.parse("https://docs.oracle.com/javase/specs/")
}
html.body.'**'[email protected](~/.*\.pdf/).each{ println it }
Using Google Collections:
com.google.common.collect.
@Grab( ='com.google.code.google-collections', ='google-collect', version='snapshot-
20080530')
getFruit() { [grape:'purple', lemon:'yellow', orange:'orange'] }
fruit.lemon == 'yellow'
fruit.inverse().yellow == 'lemon'
Launching a Jetty server to serve Groovy templates:
http://docs.groovy-lang.org/latest/html/documentation/ 321/502
1/6/2019 Groovy Language Documentation
@Grab('org.eclipse.jetty.aggregate:jetty-server:8.1.19.v20160209')
@Grab('org.eclipse.jetty.aggregate:jetty-servlet:8.1.19.v20160209')
@Grab('javax.servlet:javax.servlet-api:3.0.1')
org.eclipse.jetty.server.
org.eclipse.jetty.servlet.
groovy.servlet.
runServer(duration) {
server = (8080)
context = (server, "/", .SESSIONS)
context.resourceBase = "."
context.addServlet( , "*.gsp")
server.start()
sleep duration
server.stop()
}
runServer(10000)
Grape will download Jetty and its dependencies on rst launch of this script, and cache them. We create a new Jetty Server on port
8080, then expose Groovy’s TemplateServlet at the root of the context — Groovy comes with its own powerful template engine
mechanism. We start the server and let it run for a certain duration. Each time someone will hit
http://localhost:8080/somepage.gsp, it will display the somepage.gsp template to the user — those template pages should be
situated in the same directory as this server script.
3.6. Testing Guide
3.6.1. Introduction
The Groovy programming language comes with great support for writing tests. In addition to the language features and test
integration with state-of-the-art testing libraries and frameworks, the Groovy ecosystem has born a rich set of testing libraries and
frameworks.
This chapter will start with language speci c testing features and continue with a closer look at JUnit integration, Spock for
speci cations, and Geb for functional tests. Finally, we’ll do an overview of other testing libraries known to be working with
Groovy.
3.6.2. Language Features
Besides integrated support for JUnit, the Groovy programming language comes with features that have proven to be very valuable
for test-driven development. This section gives insight on them.
Power Assertions
Writing tests means formulating assumptions by using assertions. In Java this can be done by using the assert keyword that has
been added in J2SE 1.4. In Java, assert statements can be enabled via the JVM parameters -ea (or -enableassertions ) and
-da (or -disableassertions ). Assertion statements in Java are disabled by default.
Groovy comes with a rather powerful variant of assert also known as power assertion statement. Groovy’s power assert
di ers from the Java version in its output given the boolean expression validates to false :
x = 1
x == 2
// Output: 1
//
// Assertion failed:
// assert x == 2
// | |
// 1 false
1 This section shows the std-err output
The java.lang.AssertionError that is thrown whenever the assertion can not be validated successfully, contains an extended
version of the original exception message. The power assertion output shows evaluation results from the outer to the inner
expression.
http://docs.groovy-lang.org/latest/html/documentation/ 322/502
1/6/2019 The power assertion statements true power unleashes in Groovy
complex Boolean Documentation
Language statements, or statements with collections or other
toString -enabled classes:
x = [1,2,3,4,5]
(x << 6) == [6,7,8,9,10]
// Output:
//
// Assertion failed:
// assert (x << 6) == [6,7,8,9,10]
// | | |
// | | false
// | [1, 2, 3, 4, 5, 6]
// [1, 2, 3, 4, 5, 6]
Another important di erence from Java is that in Groovy assertions are enabled by default. It has been a language design decision
to remove the possibility to deactivate assertions. Or, as Bertrand Meyer stated,
it makes no sense to take off your swim ring if you put your feet into real water .
One thing to be aware of are methods with side-e ects inside Boolean expressions in power assertion statements. As the internal
error message construction mechanism does only store references to instances under target, it happens that the error message
text is invalid at rendering time in case of side-e ecting methods involved:
[[1,2,3,3,3,3,4]].first().unique() == [1,2,3]
// Output:
//
// Assertion failed:
// assert [[1,2,3,3,3,3,4]].first().unique() == [1,2,3]
// | | |
// | | false
// | [1, 2, 3, 4]
// [1, 2, 3, 4] 1
1 The error message shows the actual state of the collection, not the state before the unique method was applied
If you choose to provide a custom assertion error message this can be done by using the Java syntax
assert expression1 : expression2 where expression1 is the Boolean expression and expression2 is the
custom error message. Be aware though that this will disable the power assert and will fully fallback to custom
error messages on assertion errors.
Mocking and Stubbing
Groovy has excellent built-in support for a range of mocking and stubbing alternatives. When using Java, dynamic mocking
frameworks are very popular. A key reason for this is that it is hard work creating custom hand-crafted mocks using Java. Such
frameworks can be used easily with Groovy if you choose but creating custom mocks is much easier in Groovy. You can often get
away with simple maps or closures to build your custom mocks.
The following sections show ways to create mocks and stubs with Groovy language features only.
Map Coercion
By using maps or expandos, we can incorporate desired behaviour of a collaborator very easily as shown here:
{
convert( key) {
"test"
}
}
service = [convert: { key -> 'some text' }]
'some text' == service.convert('key.text')
http://docs.groovy-lang.org/latest/html/documentation/ 323/502
1/6/2019 The as operator can be used to coerce a map to a particular class.
Groovy The given
Language map keys are interpreted as method names and the
Documentation
values, being groovy.lang.Closure blocks, are interpreted as method code blocks.
Be aware that map coercion can get into the way if you deal with custom java.util.Map descendant classes in
combination with the as operator. The map coercion mechanism is targeted directly at certain collection classes,
it doesn’t take custom classes into account.
Closure Coercion
The 'as' operator can be used with closures in a neat way which is great for developer testing in simple scenarios. We haven’t
found this technique to be so powerful that we want to do away with dynamic mocking, but it can be very useful in simple cases
none-the-less.
Classes or interfaces holding a single method, including SAM (single abstract method) classes, can be used to coerce a closure
block to be an object of the given type. Be aware that for doing this, Groovy internally create a proxy object descending for the
given class. So the object will not be a direct instance of the given class. This important if, for example, the generated proxy
object’s meta-class is altered afterwards.
Let’s have an example on coercing a closure to be of a speci c type:
service = { key -> 'some text' }
'some text' == service.convert('key.text')
Groovy supports a feature called implicit SAM coercion. This means that the as operator is not necessary in situations where the
runtime can infer the target SAM type. This type of coercion might be useful in tests to mock entire SAM classes:
{
doSomething()
}
service = { -> println 'doing something' }
service.doSomething()
MockFor and StubFor
The Groovy mocking and stubbing classes can be found in the groovy.mock.interceptor package.
The MockFor class supports (typically unit) testing of classes in isolation by allowing a strictly ordered expectation of the behavior
of collaborators to be de ned. A typical test scenario involves a class under test and one or more collaborators. In such a scenario
it is often desirable to just test the business logic of the class under test. One strategy for doing that is to replace the collaborator
instances with simpli ed mock objects to help isolate out the logic in the test target. MockFor allows such mocks to be created
using meta-programming. The desired behavior of collaborators is de ned as a behavior speci cation. The behavior is enforced
and checked automatically.
Let’s assume our target classes looked like this:
{
first,
}
{
father, mother
nameOfMother() { "$mother.first $mother.last" }
}
With MockFor , a mock expectation is always sequence dependent and its use automatically ends with a call to verify :
http://docs.groovy-lang.org/latest/html/documentation/ 324/502
1/6/2019 Groovy Language Documentation
mock = ( ) 1
mock.demand.getFirst{ 'dummy' }
mock.demand.getLast{ 'name' }
mock. { 2
mary = (first:'Mary', :'Smith')
f = (mother:mary)
f.nameOfMother() == 'dummy name'
}
mock.expect.verify() 3
1 a new mock is created by a new instance of MockFor
2 a Closure is passed to use which enables the mocking functionality
3 a call to verify checks whether the sequence and number of method calls is as expected
The StubFor class supports (typically unit) testing of classes in isolation by allowing a loosely-ordered expectation of the behavior
of collaborators to be de ned. A typical test scenario involves a class under test and one or more collaborators. In such a scenario
it is often desirable to just test the business logic of the CUT. One strategy for doing that is to replace the collaborator instances
with simpli ed stub objects to help isolate out the logic in the target class. StubFor allows such stubs to be created using meta-
programming. The desired behavior of collaborators is de ned as a behavior speci cation.
In contrast to MockFor the stub expectation checked with verify is sequence independent and its use is optional:
stub = ( ) 1
stub.demand. { 2
getLast{ 'name' }
getFirst{ 'dummy' }
}
stub. { 3
john = (first:'John', :'Smith')
f = (father:john)
f.father.first == 'dummy'
f.father. == 'name'
}
stub.expect.verify() 4
1 a new stub is created by a new instance of StubFor
2 the with method is used for delegating all calls inside the closure to the StubFor instance
3 a Closure is passed to use which enables the stubbing functionality
4 a call to verify (optional) checks whether the number of method calls is as expected
MockFor and StubFor can not be used to test statically compiled classes e.g for Java classes or Groovy classes that make use of
@CompileStatic . To stub and/or mock these classes you can use Spock or one of the Java mocking libraries.
Expando Meta-Class (EMC)
Groovy includes a special MetaClass the so-called ExpandoMetaClass (EMC). It allows to dynamically add methods,
constructors, properties and static methods using a neat closure syntax.
Every java.lang.Class is supplied with a special metaClass property that will give a reference to an ExpandoMetaClass
instance. The expando meta-class is not restricted to custom classes, it can be used for JDK classes like for example
java.lang.String as well:
http://docs.groovy-lang.org/latest/html/documentation/ 325/502
1/6/2019 Groovy Language Documentation
.metaClass.swapCase = {->
sb = ()
.each {
sb << ( .isUpperCase(it ) ? .toLowerCase(it ) :
.toUpperCase(it ))
}
sb.toString()
}
s = "heLLo, worLD!"
s.swapCase() == 'HEllO, WORld!'
The ExpandoMetaClass is a rather good candidate for mocking functionality as it allows for more advanced stu like mocking
static methods
{
title
}
.metaClass. .create << { title -> (title:title) }
b = .create("The Stand")
b.title == 'The Stand'
or even constructors
.metaClass.constructor << { title -> (title:title) }
b = ("The Stand")
b.title == 'The Stand'
Mocking constructors might seem like a hack that’s better not even to be considered but even there might be valid
use cases. An example can be found in Grails where domain class constructors are added at run-time with the
help of ExpandoMetaClass . This lets the domain object register itself in the Spring application context and allows
for injection of services or other beans controlled by the dependency-injection container.
If you want to change the metaClass property on a per test method level you need to remove the changes that were done to the
meta-class, otherwise those changes would be persistent across test method calls. Changes are removed by replacing the meta-
class in the GroovyMetaClassRegistry :
.metaClassRegistry.setMetaClass(java.lang. , )
Another alternative is to register a MetaClassRegistryChangeEventListener , track the changed classes and remove the
changes in the cleanup method of your chosen testing runtime. A good example can be found in the Grails web development
framework (https://github.com/grails/grails-core/blob/master/grails-
bootstrap/src/main/groovy/grails/build/support/MetaClassRegistryCleaner.java).
Besides using the ExpandoMetaClass on a class-level, there is also support for using the meta-class on a per-object level:
b = (title: "The Stand")
b.metaClass.getTitle {-> 'My Title' }
b.title == 'My Title'
In this case the meta-class change is related to the instance only. Depending on the test scenario this might be a better t than the
global meta-class change.
GDK Methods
The following section gives a brief overview on GDK methods that can be leveraged in test case scenarios, for example for test
data generation.
http://docs.groovy-lang.org/latest/html/documentation/ 326/502
1/6/2019 Iterable#combinations Groovy Language Documentation
The combinations method that is added on java.lang.Iterable compliant classes can be used to get a list of combinations
from a list containing two or more sub-lists:
testCombinations() {
combinations = [[2, 3],[4, 5, 6]].combinations()
combinations == [[2, 4], [3, 4], [2, 5], [3, 5], [2, 6], [3, 6]]
}
The method could be used in test case scenarios to generate all possible argument combinations for a speci c method call.
Iterable#eachCombination
The eachCombination method that is added on java.lang.Iterable can be used to apply a function (or in this case a
groovy.lang.Closure ) to each if the combinations that has been built by the combinations method:
eachCombination is a GDK method that is added to all classes conforming to the java.lang.Iterable interface. It applies a
function on each combination of the input lists:
testEachCombination() {
[[2, 3],[4, 5, 6]].eachCombination { println it[0] + it[1] }
}
The method could be used in the testing context to call methods with each of the generated combinations.
Tool Support
Test Code Coverage
Code coverage is a useful measure of the e ectiveness of (unit) tests. A program with high code coverage has a lower chance to
hold critical bugs than a program with no or low coverage. To get code coverage metrics, the generated byte-code usually needs
to be instrumented before the tests are executed. One tool with Groovy support for this task is Cobertura
(http://cobertura.github.io/cobertura/).
Various frameworks and build tools come with Cobertura integration. For Grails, there is the code coverage plugin
(http://grails.org/plugin/code-coverage) based on Cobertura, for Gradle there is the gradle-cobertura plugin
(https://github.com/eriwen/gradle-cobertura-plugin), to name only two of them.
The following code listing shows an example on how to enable Cobertura test coverage reports in a Gradle build script from a
Groovy project:
http://docs.groovy-lang.org/latest/html/documentation/ 327/502
1/6/2019 Groovy Language Documentation
pluginVersion = '<plugin version>'
groovyVersion = '<groovy version>'
junitVersion = '<junit version>'
buildscript {
repositories {
mavenCentral()
}
dependencies {
classpath 'com.eriwen:gradle-cobertura-plugin:${pluginVersion}'
}
}
apply plugin: 'groovy'
apply plugin: 'cobertura'
repositories {
mavenCentral()
}
dependencies {
compile "org.codehaus.groovy:groovy-all:${groovyVersion}"
testCompile "junit:junit:${junitVersion}"
}
cobertura {
format = 'html'
includes = ['**/*.java', '**/*.groovy']
excludes = ['com/thirdparty/**/*.*']
}
Several output formats can be chosen for Cobertura coverage reports and test code coverage reports can be added to continuous
integration build tasks.
3.6.3. Testing with JUnit
Groovy simpli es JUnit testing in the following ways:
You use the same overall practices as you would when testing with Java but you can adopt much of Groovy’s concise syntax in
your tests making them succinct. You can even use the capabilities for writing testing domain speci c languages (DSLs) if you
feel so inclined.
There are numerous helper classes that simplify many testing activities. The details di er in some cases depending on the
version of JUnit you are using. We’ll cover those details shortly.
Groovy’s PowerAssert mechanism is wonderful to use in your tests
Groovy deems that tests are so important you should be able to run them as easily as scripts or classes. This is why Groovy
includes an automatic test runner when using the groovy command or the GroovyConsole. This gives you some additional
options over and above running your tests
In the following sections we will have a closer look at JUnit 3, 4 and 5 Groovy integration.
JUnit 3
Maybe one of the most prominent Groovy classes supporting JUnit 3 tests is the GroovyTestCase class. Being derived from
junit.framework.TestCase it o ers a bunch of additional methods that make testing in Groovy a breeze.
Although GroovyTestCase inherits from TestCase doesn’t mean you can’t use JUnit 4 features in your project.
In fact, the most recent Groovy versions come with a bundled JUnit 4 and that comes with a backwards compatible
TestCase implementation. There have been some discussion on the Groovy mailing-list on whether to use
GroovyTestCase or JUnit 4 with the result that it is mostly a matter of taste, but with GroovyTestCase you get a
bunch of methods for free that make certain types of tests easier to write.
In this section, we will have a look at some of the methods provided by GroovyTestCase . A full list of these can be found in the
JavaDoc documentation for groovy.util.GroovyTestCase (http://docs.groovy-lang.org/2.5.5/html/gapi/index.html?
groovy/util/GroovyTestCase.html) , don’t forget it is inherited from junit.framework.TestCase which inherits all the assert*
http://docs.groovy-lang.org/latest/html/documentation/ 328/502
1/6/2019 methods. Groovy Language Documentation
Assertion Methods
GroovyTestCase is inherited from junit.framework.TestCase therefore it inherits a large number of assertion methods being
available to be called in every test method:
testAssertions() {
assertTrue(1 == 1)
assertEquals("test", "test")
x = "42"
assertNotNull "x must not be null", x
assertNull
assertSame x, x
}
As can be seen above, in contrast to Java it is possible to leave out the parenthesis in most situations which leads to even more
readability of JUnit assertion method call expressions.
An interesting assertion method that is added by GroovyTestCase is assertScript . It ensures that the given Groovy code
string succeeds without any exception:
testScriptAssertions() {
assertScript '''
def x = 1
def y = 2
assert x + y == 3
'''
}
shouldFail Methods
shouldFail can be used to check whether the given code block fails or not. In case it fails, the assertion does hold, otherwise the
assertion fails:
testInvalidIndexAccess1() {
numbers = [1,2,3,4]
shouldFail {
numbers. (4)
}
}
The example above uses the basic shouldFail method interface that takes a groovy.lang.Closure as a single argument. The
Closure instance holds the code that is supposed to be breaking during run-time.
If we wanted to assert shouldFail on a speci c java.lang.Exception type we could have done so by using the shouldFail
implementation that takes the Exception class as rst argument and the Closure as second argument:
testInvalidIndexAccess2() {
numbers = [1,2,3,4]
shouldFail , {
numbers. (4)
}
}
If anything other than IndexOutOfBoundsException (or a descendant class of it) is thrown, the test case will fail.
http://docs.groovy-lang.org/latest/html/documentation/ 329/502
1/6/2019 A pretty nice feature of shouldFail hasn’t been visible so far: it Language
Groovy returns the exception message. This is really useful if you want to
Documentation
assert on the exception error message:
testInvalidIndexAccess3() {
numbers = [1,2,3,4]
msg = shouldFail , {
numbers. (4)
}
msg.contains('Index: 4, Size: 4') ||
msg.contains('Index 4 out-of-bounds for length 4') ||
msg.contains('Index 4 out of bounds for length 4')
}
notYetImplemented Method
The notYetImplemented method has been greatly in uenced by HtmlUnit. It allows to write a test method but mark it as not yet
implemented. As long as the test method fails and is marked with notYetImplemented the test goes green:
testNotYetImplemented1() {
(notYetImplemented()) 1
1 == 2 2
1 a call to notYetImplemented is necessary for GroovyTestCase to get the current method stack.
2 as long as the test evaluates to false the test execution will be successful.
An alternative to the notYetImplemented method is the @NotYetImplemented annotation. It allows for annotating a method as
not yet implemented, with the exact same behavior as GroovyTestCase#notYetImplemented but without the need for the
notYetImplemented method call:
@NotYetImplemented
testNotYetImplemented2() {
1 == 2
}
JUnit 4
Groovy can be used to write JUnit 4 test cases without any restrictions. The groovy.test.GroovyAssert holds various static
methods that can be used as replacement for the GroovyTestCase methods in JUnit 4 tests:
org.junit.
groovy.test. .shouldFail
@Test
indexOutOfBoundsAccess() {
numbers = [1,2,3,4]
shouldFail {
numbers. (4)
}
}
As can be seen in the example above, the static methods found in GroovyAssert are imported at the beginning of the class
de nition thus shouldFail can be used the same way it can be used in a GroovyTestCase .
http://docs.groovy-lang.org/latest/html/documentation/ 330/502
1/6/2019 Groovy Language Documentation
groovy.test.GroovyAssert descends from org.junit.Assert that means it inherits all JUnit assertion
methods. However, with the introduction of the power assertion statement, it turned out to be good practice to
rely on assertion statements instead of using the JUnit assertion methods with the improved message being the
main reason.
It is worth mentioning that GroovyAssert.shouldFail is not absolutely identical to GroovyTestCase.shouldFail . While
GroovyTestCase.shouldFail returns the exception message, GroovyAssert.shouldFail returns the exception itself. It takes
a few more keystrokes to get the message, but in return you can access other properties and methods of the exception:
@Test
shouldFailReturn() {
e = shouldFail {
('foo',
('bar'))
}
e
e.message == 'foo'
e.cause.message == 'bar'
}
JUnit 5
Much of the approach and helper classes described under JUnit4 apply when using JUnit5 however JUnit5 uses some slightly
di erent class annotations when writing your tests. See the JUnit5 (http://junit.org) documentation for more details.
Create your test classes as per normal JUnit5 guidelines as shown in this example:
{
@Test
streamSum() {
.of(1, 2, 3).mapToInt{ i -> i }.sum() > 5
}
@RepeatedTest(value=2, name = "{displayName} {currentRepetition}/{totalRepetitions}")
streamSumRepeated() {
.of(1, 2, 3).mapToInt{i -> i}.sum() == 6
}
isPalindrome(s) { s == s.reverse() }
@ParameterizedTest 1
@ValueSource(strings = [ "racecar", "radar", "able was I ere I saw elba" ])
palindromes( candidate) {
isPalindrome(candidate)
}
@TestFactory
dynamicTestCollection() {[
dynamicTest("Add test") { -> 1 + 1 == 2 },
dynamicTest("Multiply Test") { -> 2 * 3 == 6 }
]}
}
1 This test requires the additional org.junit.jupiter:junit-jupiter-params dependency if not already in your project.
You can run the tests in your IDE or build tool if it supports and is con gured for JUnit5. If you run the above test in the
GroovyConsole or via the groovy command, you will see a short text summary of the result of running the test:
JUnit5 launcher: passed=8, failed=0, skipped=0, time=246ms
More detailed information is available at the FINE logging level. You can con gure your logging to display such information or do
it programmatically as follows:
http://docs.groovy-lang.org/latest/html/documentation/ 331/502
1/6/2019 Groovy Language Documentation
@BeforeAll
init() {
logger = .getLogger( .name)
logger.level = .FINE
logger.addHandler( (level: .FINE))
}
3.6.4. Testing with Spock
Spock is a testing and speci cation framework for Java and Groovy applications. What makes it stand out from the crowd is its
beautiful and highly expressive speci cation DSL. In practice, Spock speci cations are written as Groovy classes. Although written
in Groovy they can be used to test Java classes. Spock can be used for unit, integration or BDD (behavior-driven-development)
testing, it doesn’t put itself into a speci c category of testing frameworks or libraries.
Beside these awesome features Spock is a good example on how to leverage advanced Groovy programming
language features in third party libraries, for example, by using Groovy AST transformations.
This section should not serve as detailed guide on how to use Spock, it should rather give an impression what
Spock is about and how it can be leveraged for unit, integration, functional or any other type of testing.
The next section we will have an rst look at the anatomy of a Spock speci cation. It should give a pretty good feeling on what
Spock is up to.
Speci cations
Spock lets you write speci cations that describe features (properties, aspects) exhibited by a system of interest. The "system" can
be anything between a single class and an entire application, a more advanced term for it is system under speci cation. The
feature description starts from a speci c snapshot of the system and its collaborators, this snapshot is called the feature’s xture.
Spock speci cation classes are derived from spock.lang.Specification . A concrete speci cation class might consist of elds,
xture methods, features methods and helper methods.
Let’s have a look at a simple speci cation with a single feature method for an imaginary Stack class:
"adding an element leads to size increase"() { 1
setup: "a new stack instance is created" 2
stack = ()
: 3
stack.push 42
: 4
stack.size() == 1
}
}
1 Feature method, is by convention named with a String literal.
2 Setup block, here is where any setup work for this feature needs to be done.
3 When block describes a stimulus, a certain action under target by this feature speci cation.
4 Then block any expressions that can be used to validate the result of the code that was triggered by the when block.
Spock feature speci cations are de ned as methods inside a spock.lang.Specification class. They describe the feature by
using a String literal instead of a method name.
A feature method holds multiple blocks, in our example we used setup , when and then . The setup block is special in that it is
optional and allows to con gure local variables visible inside the feature method. The when block de nes the stimulus and is a
companion of the then block which describes the response to the stimulus.
Note that the setup method in the StackSpec above additionally has a description String. Description Strings are optional and
can be added after block labels (like setup , when , then ).
http://docs.groovy-lang.org/latest/html/documentation/ 332/502
1/6/2019 More Spock Groovy Language Documentation
Spock provides much more features like data tables or advanced mocking capabilities. Feel free to consult the Spock GitHub page
(https://github.com/spockframework/spock) for more documentation and download information.
3.6.5. Functional Tests with Geb
Geb is a functional web testing and scraper library that integrates with JUnit and Spock. It is based upon the Selenium web drivers
and, like Spock, provides a Groovy DSL to write functional tests for web applications.
Geb has great features that make it a good t for a functional testing library:
DOM access via a JQuery-like $ function
implements the page pattern
support for modularization of certain web components (e.g. menu-bars, etc.) with modules
integration with JavaScript via the JS variable
This section should not serve as detailed guide on how to use Geb, it should rather give an impression what Geb is
about and how it can be leveraged functional testing.
The next section will give an example on how Geb can be used to write a functional test for a simple web page with a single search
eld.
A Geb Script
Although Geb can be used standalone in a Groovy script, in many scenarios it’s used in combination with other testing
frameworks. Geb comes with various base classes that can be used in JUnit 3, 4, TestNG or Spock tests. The base classes are part
of additional Geb modules that need to be added as a dependency.
For example, the following @Grab dependencies have to be used to run Geb with the Selenium Firefox driver in JUnit4 tests. The
module that is needed for JUnit 3/4 support is geb-junit :
@Grapes([
@Grab("org.gebish:geb-core:0.9.2"),
@Grab("org.gebish:geb-junit:0.9.2"),
@Grab("org.seleniumhq.selenium:selenium-firefox-driver:2.26.0"),
@Grab("org.seleniumhq.selenium:selenium-support:2.26.0")
])
The central class in Geb is the geb.Browser class. As its name implies it is used to browse pages and access DOM elements:
browser = (driver: (), baseUrl: 'http://myhost:8080/myapp') 1
browser.drive {
go "/login" 2
$("#username").text = 'John' 3
$("#password").text = 'Doe'
$("#loginButton").click()
title == "My Application - Dashboard"
}
1 A new Browser instance is created. In this case it uses the Selenium FirefoxDriver and sets the baseUrl .
2 go is used to navigate to an URL or relative URI
3 $ together with CSS selectors is used to access the username and password DOM elds.
The Browser class comes with a drive method that delegates all method/property calls to the current browser instance. The
Browser con guration must not be done inline, it can also be externalized in a GebConfig.groovy con guration le for
example. In practice, the usage of the Browser class is mostly hidden by Geb test base classes. They delegate all missing
properties and method calls to the current browser instance that exists in the background:
http://docs.groovy-lang.org/latest/html/documentation/ 333/502
1/6/2019 Groovy Language Documentation
geb.junit4. {
@Test
executeSeach() {
go 'http://somehost/mayapp/search' 1
$('#searchField').text = 'John Doe' 2
$('#searchButton').click() 3
$('.searchResult a').first().text() == 'Mr. John Doe' 4
}
}
1 Browser#go takes a relative or absolute link and calls the page.
2 Browser#$ is used to access DOM content. Any CSS selectors supported by the underlying Selenium drivers are allowed
3 click is used to click a button.
4 $ is used to get the rst link out of the searchResult block
The example above shows a simple Geb web test with the JUnit 4 base class geb.junit4.GebTest . Note that in this case the
Browser con guration is externalized. GebTest delegates methods like go and $ to the underlying browser instance.
More Geb
In the previous section we only scratched the surface of the available Geb features. More information on Geb can be found at the
project homepage (http://gebish.org).
3.7. Processing JSON
Groovy comes with integrated support for converting between Groovy objects and JSON. The classes dedicated to JSON
serialisation and parsing are found in the groovy.json package.
3.7.1. JsonSlurper
JsonSlurper is a class that parses JSON text or reader content into Groovy data structures (objects) such as maps, lists and
primitive types like Integer , Double , Boolean and String .
The class comes with a bunch of overloaded parse methods plus some special methods such as parseText , parseFile and
others. For the next example we will use the parseText method. It parses a JSON String and recursively converts it to a list or
map of objects. The other parse* methods are similar in that they return a JSON String but for di erent parameter types.
jsonSlurper = ()
= jsonSlurper.parseText('{ "name": "John Doe" } /* some comment */')
.name == 'John Doe'
Notice the result is a plain map and can be handled like a normal Groovy object instance. JsonSlurper parses the given JSON as
de ned by the ECMA-404 JSON Interchange Standard (http://www.ecma-international.org/publications/ les/ECMA-ST/ECMA-
404.pdf) plus support for JavaScript comments and dates.
In addition to maps JsonSlurper supports JSON arrays which are converted to lists.
jsonSlurper = ()
= jsonSlurper.parseText('{ "myList": [4, 8, 15, 16, 23, 42] }')
.myList
.myList == [4, 8, 15, 16, 23, 42]
The JSON standard supports the following primitive data types: string, number, object, true , false and null . JsonSlurper
converts these JSON types into corresponding Groovy types.
http://docs.groovy-lang.org/latest/html/documentation/ 334/502
1/6/2019 Groovy Language Documentation
jsonSlurper = ()
= jsonSlurper.parseText '''
{ "simple": 123,
"fraction": 123.66,
"exponential": 123e12
}'''
.simple. ==
.fraction. ==
.exponential. ==
As JsonSlurper is returning pure Groovy object instances without any special JSON classes in the back, its usage is transparent.
In fact, JsonSlurper results conform to GPath expressions. GPath is a powerful expression language that is supported by
multiple slurpers for di erent data formats ( XmlSlurper for XML being one example).
For more details please have a look at the section on GPath expressions.
The following table gives an overview of the JSON types and the corresponding Groovy data types:
JSON Groovy
string java.lang.String
number java.lang.BigDecimal or java.lang.Integer
object java.util.LinkedHashMap
array java.util.ArrayList
true true
false false
null null
date java.util.Date based on the yyyy-MM-dd’T’HH:mm:ssZ date
format
Whenever a value in JSON is null , JsonSlurper supplements it with the Groovy null value. This is in contrast
to other JSON parsers that represent a null value with a library-provided singleton object.
Parser Variants
JsonSlurper comes with a couple of parser implementations. Each parser ts di erent requirements, it could well be that for
certain scenarios the JsonSlurper default parser is not the best bet for all situations. Here is an overview of the shipped parser
implementations:
The JsonParserCharArray parser basically takes a JSON string and operates on the underlying character array. During value
conversion it copies character sub-arrays (a mechanism known as "chopping") and operates on them.
The JsonFastParser is a special variant of the JsonParserCharArray and is the fastest parser. However, it is not the default
parser for a reason. JsonFastParser is a so-called index-overlay parser. During parsing of the given JSON String it tries as
hard as possible to avoid creating new char arrays or String instances. It keeps pointers to the underlying original character
array only. In addition, it defers object creation as late as possible. If parsed maps are put into long-term caches care must be
taken as the map objects might not be created and still consist of pointer to the original char bu er only. However,
JsonFastParser comes with a special chop mode which dices up the char bu er early to keep a small copy of the original
bu er. Recommendation is to use the JsonFastParser for JSON bu ers under 2MB and keeping the long-term cache
restriction in mind.
The JsonParserLax is a special variant of the JsonParserCharArray parser. It has similar performance characteristics as
JsonFastParser but di ers in that it isn’t exclusively relying on the ECMA-404 JSON grammar. For example it allows for
comments, no quote strings etc.
http://docs.groovy-lang.org/latest/html/documentation/ 335/502
1/6/2019 The JsonParserUsingCharacterSource is a special parser
Groovyfor very large
Language les. It uses a technique called "character
Documentation
windowing" to parse large JSON les (large means les over 2MB size in this case) with constant performance characteristics.
The default parser implementation for JsonSlurper is JsonParserCharArray . The JsonParserType enumeration contains
constants for the parser implementations described above:
Implementation Constant
JsonParserCharArray JsonParserType#CHAR_BUFFER
JsonFastParser JsonParserType#INDEX_OVERLAY
JsonParserLax JsonParserType#LAX
JsonParserUsingCharacterSource JsonParserType#CHARACTER_SOURCE
Changing the parser implementation is as easy as setting the JsonParserType with a call to JsonSlurper#setType() .
jsonSlurper = (type: .INDEX_OVERLAY)
= jsonSlurper.parseText('{ "myList": [4, 8, 15, 16, 23, 42] }')
.myList
.myList == [4, 8, 15, 16, 23, 42]
3.7.2. JsonOutput
JsonOutput is responsible for serialising Groovy objects into JSON strings. It can be seen as companion object to JsonSlurper
(json-userguide.html#json_jsonslurper), being a JSON parser.
JsonOutput comes with overloaded, static toJson methods. Each toJson implementation takes a di erent parameter type.
The static methods can either be used directly or by importing the methods with a static import statement.
The result of a toJson call is a String containing the JSON code.
json = .toJson([name: 'John Doe', age: 42])
json == '{"name":"John Doe","age":42}'
JsonOutput does not only support primitive, maps or list data types to be serialized to JSON, it goes further and even has
support for serialising POGOs, that is, plain-old Groovy objects.
{ name }
json = .toJson([ (name: 'John'), (name: 'Max') ])
json == '[{"name":"John"},{"name":"Max"}]'
Customizing Output
If you need control over the serialized output you can use a JsonGenerator . The JsonGenerator.Options builder can be used
to create a customized generator. One or more options can be set on this builder in order to alter the resulting output. When you
are done setting the options simply call the build() method in order to get a fully con gured instance that will generate output
based on the options selected.
http://docs.groovy-lang.org/latest/html/documentation/ 336/502
1/6/2019 Groovy Language Documentation
{
name
title
age
password
dob
URL favoriteUrl
}
person = (name: 'John', title: , age: 21, password: 'secret',
dob: .parse('yyyy-MM-dd', '1984-12-15'),
favoriteUrl: URL('http://groovy-lang.org/'))
generator = . ()
.excludeNulls()
.dateFormat('yyyy@MM')
.excludeFieldsByName('age', 'password')
.excludeFieldsByType(URL)
.build()
generator.toJson(person) == '{"dob":"1984@12","name":"John"}'
A closure can be used to transform a type. These closure converters are registered for a given type and will be called any time that
type or a subtype is encountered. The rst parameter to the closure is an object matching the type for which the converter is
registered and this parameter is required. The closure may take an optional second String parameter and this will be set to the
key name if one is available.
{
name
URL favoriteUrl
}
person = (name: 'John', favoriteUrl: URL('http://groovy-
lang.org/json.html#_jsonoutput'))
generator = . ()
.addConverter(URL) { URL u, key ->
(key == 'favoriteUrl') {
u.getHost()
} {
u
}
}
.build()
generator.toJson(person) == '{"favoriteUrl":"groovy-lang.org","name":"John"}'
// No key available when generating a JSON Array
list = [ URL('http://groovy-lang.org/json.html#_jsonoutput')]
generator.toJson(list) == '["http://groovy-lang.org/json.html#_jsonoutput"]'
// First parameter to the converter must match the type for which it is registered
shouldFail( ) {
. ()
.addConverter( ) { cal -> }
}
Formatted Output
As we saw in previous examples, the JSON output is not pretty printed per default. However, the prettyPrint method in
JsonOutput comes to rescue for this task.
http://docs.groovy-lang.org/latest/html/documentation/ 337/502
1/6/2019 Groovy Language Documentation
json = .toJson([name: 'John Doe', age: 42])
json == '{"name":"John Doe","age":42}'
.prettyPrint(json) == '''\
{
"name": "John Doe",
"age": 42
}'''.stripIndent()
prettyPrint takes a String as single parameter; therefore, it can be applied on arbitrary JSON String instances, not only the
result of JsonOutput.toJson .
Builders
Another way to create JSON from Groovy is to use JsonBuilder or StreamingJsonBuilder . Both builders provide a DSL which
allows to formulate an object graph which is then converted to JSON.
For more details on builders, have a look at the builders chapter which covers both JsonBuilder and
StreamingJsonBuilder.
3.8. Interacting with a SQL database
Groovy’s groovy-sql module provides a higher-level abstraction over Java’s JDBC technology. JDBC itself provides a lower-level
but fairly comprehensive API which provides uniform access to a whole variety of supported relational database systems. We’ll use
HSQLDB in our examples here but you can alternatively use Oracle, SQL Server, MySQL and a host of others. The most frequently
used class within the groovy-sql module is the groovy.sql.Sql class which raises the JDBC abstractions up one level. We’ll
cover that rst.
3.8.1. Connecting to the database
Connecting to a database with Groovy’s Sql class requires four pieces of information:
The database uniform resource locator (URL)
Username
Password
The driver class name (which can be derived automatically in some situations)
For our HSQLDB database, the values will be something like that shown in the following table:
Property Value
url jdbc:hsqldb:mem:yourdb
user sa (or your username)
password yourPassword
driver org.hsqldb.jdbcDriver
Consult the documentation for the JDBC driver that you plan to use to determine the correct values for your situation.
The Sql class has a newInstance factory method which takes these parameters. You would typically use it as follows:
Connecting to HSQLDB
http://docs.groovy-lang.org/latest/html/documentation/ 338/502
1/6/2019 Groovy Language Documentation
groovy.sql.
url = 'jdbc:hsqldb:mem:yourDB'
user = 'sa'
password = ''
driver = 'org.hsqldb.jdbcDriver'
sql = .newInstance(url, user, password, driver)
// use 'sql' instance ...
sql.close()
If you don’t want to have to handle resource handling yourself (i.e. call close() manually) then you can use the withInstance
variation as shown here:
Connecting to HSQLDB ( withInstance variation)
.withInstance(url, user, password, driver) { sql ->
// use 'sql' instance ...
}
Connecting with a DataSource
It is often preferred to use a DataSource. You may have one available to you from a connection pool. Here we’ll use the one
provided as part of the HSQLDB driver jar as shown here:
Connecting to HSQLDB with a DataSource
groovy.sql.
org.hsqldb.jdbc.
dataSource = (
database: 'jdbc:hsqldb:mem:yourDB', user: 'sa', password: '')
sql = (dataSource)
// use then close 'sql' instance ...
If you have your own connection pooling, the details will be di erent, e.g. for Apache Commons DBCP:
Connecting to HSQLDB with a DataSource using Apache Commons DBCP
@Grab('commons-dbcp:commons-dbcp:1.4')
groovy.sql.
org.apache.commons.dbcp.
ds = (driverClassName: "org.hsqldb.jdbcDriver",
url: 'jdbc:hsqldb:mem:yourDB', username: 'sa', password: '')
sql = (ds)
// use then close 'sql' instance ...
Connecting using @Grab
The previous examples assume that the necessary database driver jar is already on your classpath. For a self-contained script you
can add @Grab statements to the top of the script to automatically download the necessary jar as shown here:
Connecting to HSQLDB using @Grab
@Grab('org.hsqldb:hsqldb:2.3.3')
@GrabConfig(systemClassLoader= )
// create, use, and then close sql instance ...
The @GrabConfig statement is necessary to make sure the system classloader is used. This ensures that the driver classes and
system classes like java.sql.DriverManager are in the same classloader.
3.8.2. Executing SQL
You can execute arbitrary SQL commands using the execute() method. Let’s have a look at using it to create a table.
http://docs.groovy-lang.org/latest/html/documentation/ 339/502
1/6/2019 Creating tables Groovy Language Documentation
The simplest way to execute SQL is to call the execute() method passing the SQL you wish to execute as a String as shown here:
Creating a table
// ... create 'sql' instance
sql.execute '''
CREATE TABLE Author (
id INTEGER GENERATED BY DEFAULT AS IDENTITY,
firstname VARCHAR(64),
lastname VARCHAR(64)
);
'''
// close 'sql' instance ...
There is a variant of this method which takes a GString and another with a list of parameters. There are also other variants with
similar names: executeInsert and executeUpdate . We’ll see examples of these variants in other examples in this section.
3.8.3. Basic CRUD operations
The basic operations on a database are Create, Read, Update and Delete (the so-called CRUD operations). We’ll examine each of
these in turn.
Creating/Inserting data
You can use the same execute() statement we saw earlier but to insert a row by using a SQL insert statement as follows:
Inserting a row
sql.execute "INSERT INTO Author (firstname, lastname) VALUES ('Dierk', 'Koenig')"
You can use a special executeInsert method instead of execute . This will return a list of all keys generated. Both the execute
and executeInsert methods allow you to place '?' placeholders into your SQL string and supply a list of parameters. In this case
a PreparedStatement is used which avoids any risk of SQL injection. The following example illustrates executeInsert using
placeholders and parameters:
Inserting a row using executeInsert with placeholders and parameters
insertSql = 'INSERT INTO Author (firstname, lastname) VALUES (?,?)'
= ['Jon', 'Skeet']
keys = sql.executeInsert insertSql,
keys[0] == [1]
In addition, both the execute and executeInsert methods allow you to use GStrings. Any '$' placeholders within the SQL are
assumed to be placeholders. An escaping mechanism exists if you want to supply part of the GString with a variable in a position
which isn’t where normal placeholders go within SQL. See the GroovyDoc for more details. Also, executeInsert allows you to
supply a list of key column names, when multiple keys are returned and you are only interested in some of them. Here is a
fragment illustrating key name speci cation and GStrings:
Inserting a row using executeInsert with a GString and specifying key names
first = 'Guillaume'
= 'Laforge'
myKeyNames = ['ID']
myKeys = sql.executeInsert """
INSERT INTO Author (firstname, lastname)
VALUES (${first}, ${last})
""", myKeyNames
myKeys[0] == [ID: 2]
Reading rows
Reading rows of data from the database is accomplished using one of several available methods: query , eachRow , firstRow
and rows .
Use the query method if you want to iterate through the ResultSet returned by the underlying JDBC API as shown here:
http://docs.groovy-lang.org/latest/html/documentation/ 340/502
1/6/2019 Reading data using query Groovy Language Documentation
expected = ['Dierk Koenig', 'Jon Skeet', 'Guillaume Laforge']
rowNum = 0
sql.query('SELECT firstname, lastname FROM Author') { resultSet ->
(resultSet. ()) {
first = resultSet.getString(1)
= resultSet.getString('lastname')
expected[rowNum++] == "$first $last"
}
}
Use the eachRow method if you want a slightly higher-level abstraction which provides a Groovy friendly map-like abstraction for
the ResultSet as shown here:
Reading data using eachRow
rowNum = 0
sql.eachRow('SELECT firstname, lastname FROM Author') { row ->
first = row[0]
= row.lastname
expected[rowNum++] == "$first $last"
}
Note that you can use Groovy list-style and map-style notations when accessing the row of data.
Use the firstRow method if you for similar functionality as eachRow but returning only one row of data as shown here:
Reading data using firstRow
first = sql.firstRow('SELECT lastname, firstname FROM Author')
first.values().sort().join(',') == 'Dierk,Koenig'
Use the rows method if you want to process a list of map-like data structures as shown here:
Reading data using rows
authors = sql.rows('SELECT firstname, lastname FROM Author')
authors.size() == 3
authors.collect { "$it.FIRSTNAME ${it[-1]}" } == expected
Note that the map-like abstraction has case-insensitive keys (hence we can use 'FIRSTNAME' or ' rstname' as the key) and also
that -ve indices (a standard Groovy feature) works when using an index value (to count column numbers from the right).
You can also use any of the above methods to return scalar values, though typically firstRow is all that is required in such cases.
An example returning the count of rows is shown here:
Reading scalar values
sql.firstRow('SELECT COUNT(*) AS num FROM Author').num == 3
Updating rows
Updating rows can again be done using the execute() method. Just use a SQL update statement as the argument to the
method. You can insert an author with just a lastname and then update the row to also have a rstname as follows:
Updating a row
sql.execute "INSERT INTO Author (lastname) VALUES ('Thorvaldsson')"
sql.execute "UPDATE Author SET firstname='Erik' where lastname='Thorvaldsson'"
There is also a special executeUpdate variant which returns the number of rows updated as a result of executing the SQL. For
example, you can change the lastname of an author as follows:
Using executeUpdate
http://docs.groovy-lang.org/latest/html/documentation/ 341/502
1/6/2019 Groovy Language Documentation
updateSql = "UPDATE Author SET lastname='Pragt' where lastname='Thorvaldsson'"
updateCount = sql.executeUpdate updateSql
updateCount == 1
row = sql.firstRow "SELECT * FROM Author where firstname = 'Erik'"
"${row.firstname} ${row.lastname}" == 'Erik Pragt'
Deleting rows
The execute method is also used for deleting rows as this example shows:
Deleting rows
sql.firstRow('SELECT COUNT(*) as num FROM Author').num == 3
sql.execute "DELETE FROM Author WHERE lastname = 'Skeet'"
sql.firstRow('SELECT COUNT(*) as num FROM Author').num == 2
3.8.4. Advanced SQL operations
Working with transactions
The easiest way to perform database operations within a transaction is to include the database operation within a
withTransaction closure as shown in the following example:
A successful transaction
sql.firstRow('SELECT COUNT(*) as num FROM Author').num == 0
sql.withTransaction {
sql.execute "INSERT INTO Author (firstname, lastname) VALUES ('Dierk', 'Koenig')"
sql.execute "INSERT INTO Author (firstname, lastname) VALUES ('Jon', 'Skeet')"
}
sql.firstRow('SELECT COUNT(*) as num FROM Author').num == 2
Here the database starts empty and has two rows after successful completion of the operation. Outside the scope of the
transaction, the database is never seen as having just one row.
If something goes wrong, any earlier operations within the withTransaction block are rolled back. We can see that in operation
in the following example where we use database metadata (more details coming up shortly) to nd the maximum allowable size
of the firstname column and then attempt to enter a rstname one larger than that maximum value as shown here:
A failed transaction will cause a rollback
maxFirstnameLength
metaClosure = { meta -> maxFirstnameLength = meta.getPrecision(1) }
rowClosure = {}
rowCountBefore = sql.firstRow('SELECT COUNT(*) as num FROM Author').num
{
sql.withTransaction {
sql.execute "INSERT INTO Author (firstname) VALUES ('Dierk')"
sql.eachRow "SELECT firstname FROM Author WHERE firstname = 'Dierk'", metaClosure, rowClosure
sql.execute "INSERT INTO Author (firstname) VALUES (?)", 'X' * (maxFirstnameLength + 1)
}
} (ignore) { println ignore.message }
rowCountAfter = sql.firstRow('SELECT COUNT(*) as num FROM Author').num
rowCountBefore == rowCountAfter
Even though the rst sql execute succeeds initially, it will be rolled back and the number of rows will remain the same.
Using batches
When dealing with large volumes of data, particularly when inserting such data, it can be more e cient to chunk the data into
batches. This is done using the withBatch statement as shown in the following example:
Batching SQL statements
http://docs.groovy-lang.org/latest/html/documentation/ 342/502
1/6/2019 Groovy Language Documentation
sql.withBatch(3) { stmt ->
stmt.addBatch "INSERT INTO Author (firstname, lastname) VALUES ('Dierk', 'Koenig')"
stmt.addBatch "INSERT INTO Author (firstname, lastname) VALUES ('Paul', 'King')"
stmt.addBatch "INSERT INTO Author (firstname, lastname) VALUES ('Guillaume', 'Laforge')"
stmt.addBatch "INSERT INTO Author (firstname, lastname) VALUES ('Hamlet', 'D''Arcy')"
stmt.addBatch "INSERT INTO Author (firstname, lastname) VALUES ('Cedric', 'Champeau')"
stmt.addBatch "INSERT INTO Author (firstname, lastname) VALUES ('Erik', 'Pragt')"
stmt.addBatch "INSERT INTO Author (firstname, lastname) VALUES ('Jon', 'Skeet')"
}
After executing these statements, there will be 7 new rows in the database. In fact, they will have been added in batches even
though you can’t easily tell that after that fact. If you want to con rm what is going on under the covers, you can add a little bit of
extra logging into your program. Add the following lines before the withBatch statement:
Logging additional SQL information
java.util.logging.*
// next line will add fine logging
.getLogger('groovy.sql').level = .FINE
// also adjust logging.properties file in JRE_HOME/lib to have:
// java.util.logging.ConsoleHandler.level = FINE
With this extra logging turned on, and the changes made as per the above comment for the logging.properties le, you should see
output such as:
SQL logging output with batching enable
FINE: executed batch 3 command(s)
19, 2015 8:38:42 PM groovy.sql. processResult
FINE: executed batch 3 command(s)
19, 2015 8:38:42 PM groovy.sql. processResult
FINE: executed batch 1 command(s)
19, 2015 8:38:42 PM groovy.sql. getStatement
We should also note, that any combination of SQL statements can be added to the batch. They don’t all have to be inserting a new
row to the same table.
We noted earlier that to avoid SQL injection, we encourage you to use prepared statements, this is achieved using the variants of
methods which take GStrings or a list of extra parameters. Prepared statements can be used in combination with batches as
shown in the following example:
Batching prepared statements
qry = 'INSERT INTO Author (firstname, lastname) VALUES (?,?)'
sql.withBatch(3, qry) { ps ->
ps.addBatch('Dierk', 'Koenig')
ps.addBatch('Paul', 'King')
ps.addBatch('Guillaume', 'Laforge')
ps.addBatch('Hamlet', "D'Arcy")
ps.addBatch('Cedric', 'Champeau')
ps.addBatch('Erik', 'Pragt')
ps.addBatch('Jon', 'Skeet')
}
This provides a much safer option if the data could come from a user such as via a script or a web form. Of course, given that a
prepared statement is being used, you are limited to a batch of the same SQL operation (insert in our example) to the one table.
Performing pagination
When presenting large tables of data to a user, it is often convenient to present information a page at a time. Many of Groovy’s
SQL retrieval methods have extra parameters which can be used to select a particular page of interest. The starting position and
page size are speci ed as integers as shown in the following example using rows :
http://docs.groovy-lang.org/latest/html/documentation/ 343/502
1/6/2019 Retrieving pages of data Groovy Language Documentation
qry = 'SELECT * FROM Author'
sql.rows(qry, 1, 3)*.firstname == ['Dierk', 'Paul', 'Guillaume']
sql.rows(qry, 4, 3)*.firstname == ['Hamlet', 'Cedric', 'Erik']
sql.rows(qry, 7, 3)*.firstname == ['Jon']
Fetching metadata
JDBC metadata can be retrieved in numerous ways. Perhaps the most basic approach is to extract the metadata from any row as
shown in the following example which examines the tablename, column names and column type names:
Using row metadata
sql.eachRow("SELECT * FROM Author WHERE firstname = 'Dierk'") { row ->
md = row.getMetaData()
md.getTableName(1) == 'AUTHOR'
(1..md.columnCount).collect{ md.getColumnName(it) } == ['ID', 'FIRSTNAME', 'LASTNAME']
(1..md.columnCount).collect{ md.getColumnTypeName(it) } == ['INTEGER', 'VARCHAR',
'VARCHAR']
}
And another slight variant to the previous example, this time also looking at the column label:
Also using row metadata
sql.eachRow("SELECT firstname AS first FROM Author WHERE firstname = 'Dierk'") { row ->
md = row.getMetaData()
md.getColumnName(1) == 'FIRSTNAME'
md.getColumnLabel(1) == 'FIRST'
}
Accessing metadata is quite common, so Groovy also provides variants to many of its methods that let you supply a closure that
will be called once with the row metadata in addition to the normal row closure which is called for each row. The following
example illustrates the two closure variant for eachRow :
Using row and metadata closures
metaClosure = { meta -> meta.getColumnName(1) == 'FIRSTNAME' }
rowClosure = { row -> row.FIRSTNAME == 'Dierk' }
sql.eachRow("SELECT firstname FROM Author WHERE firstname = 'Dierk'", metaClosure, rowClosure)
Note that our SQL query will only return one row, so we could have equally used firstRow for the previous example.
Finally, JDBC also provides metadata per connection (not just for rows). You can also access such metadata from Groovy as shown
in this example:
Using connection metadata
md = sql.connection.metaData
md.driverName == 'HSQL Database Engine Driver'
md.databaseProductVersion == '2.3.3'
['JDBCMajorVersion', 'JDBCMinorVersion'].collect{ md[it] } == [4, 0]
md.stringFunctions.tokenize(',').contains('CONCAT')
rs = md.getTables( , , 'AUTH%', )
rs. ()
rs.getString('TABLE_NAME') == 'AUTHOR'
Consult the JavaDoc for your driver to nd out what metadata information is available for you to access.
Named and named-ordinal parameters
Groovy supports some additional alternative placeholder syntax variants. The GString variants are typically preferred over these
alternatives but the alternatives are useful for Java integration purposes and sometimes in templating scenarios where GStrings
might already be in heavy use as part of a template. The named parameter variants are much like the String plus list of parameter
http://docs.groovy-lang.org/latest/html/documentation/ 344/502
1/6/2019 variants but instead of having a list of ? placeholders followed
GroovybyLanguage
a list of parameters, you have one or more placeholders having
Documentation
the form :propName or ?.propName and a single map, named arguments or a domain object as the parameter. The map or
domain object should have a property named propName corresponding to each supplied placeholder.
Here is an example using the colon form:
Named parameters (colon form)
sql.execute "INSERT INTO Author (firstname, lastname) VALUES (:first, :last)", first: 'Dierk',
: 'Koenig'
And another example using the question mark form:
Named parameters (question mark form)
sql.execute "INSERT INTO Author (firstname, lastname) VALUES (?.first, ?.last)", first: 'Jon',
: 'Skeet'
If the information you need to supply is spread across multiple maps or domain objects you can use the question mark form with
an additional ordinal index as shown here:
Named-ordinal parameters
{ first, }
pogo = (first: 'Paul', : 'McCartney')
map = [lion: 'King']
sql.execute "INSERT INTO Author (firstname, lastname) VALUES (?1.first, ?2.lion)", pogo, map
Stored procedures
The exact syntax for creating a stored procedure or function varies slightly between di erent databases. For the HSQLDB
database we are using, we can create a stored function which returns the initials of all authors in a table as follows:
Creating a stored function
sql.execute """
CREATE FUNCTION SELECT_AUTHOR_INITIALS()
RETURNS TABLE (firstInitial VARCHAR(1), lastInitial VARCHAR(1))
READS SQL DATA
RETURN TABLE (
SELECT LEFT(Author.firstname, 1) as firstInitial, LEFT(Author.lastname, 1) as lastInitial
FROM Author
)
"""
We can use a SQL CALL statement to invoke the function using Groovy’s normal SQL retrieval methods. Here is an example using
eachRow .
Creating a stored procedure or function
result = []
sql.eachRow('CALL SELECT_AUTHOR_INITIALS()') {
result << "$it.firstInitial$it.lastInitial"
}
result == ['DK', 'JS', 'GL']
Here is the code for creating another stored function, this one taking the lastname as a parameter:
Creating a stored function with a parameter
http://docs.groovy-lang.org/latest/html/documentation/ 345/502
1/6/2019 Groovy Language Documentation
sql.execute """
CREATE FUNCTION FULL_NAME (p_lastname VARCHAR(64))
RETURNS VARCHAR(100)
READS SQL DATA
BEGIN ATOMIC
DECLARE ans VARCHAR(100);
SELECT CONCAT(firstname, ' ', lastname) INTO ans
FROM Author WHERE lastname = p_lastname;
RETURN ans;
END
"""
We can use the placeholder syntax to specify where the parameter belongs and note the special placeholder position to indicate
the result:
Using a stored function with a parameter
result = sql.firstRow("{? = call FULL_NAME(?)}", ['Koenig'])
result[0] == 'Dierk Koenig'
Finally, here is a stored procedure with input and output parameters:
Creating a stored procedure with input and output parameters
sql.execute """
CREATE PROCEDURE CONCAT_NAME (OUT fullname VARCHAR(100),
IN first VARCHAR(50), IN last VARCHAR(50))
BEGIN ATOMIC
SET fullname = CONCAT(first, ' ', last);
END
"""
To use the CONCAT_NAME stored procedure parameter, we make use of a special call method. Any input parameters are simply
provided as parameters to the method call. For output parameters, the resulting type must be speci ed as shown here:
Using a stored procedure with input and output parameters
sql.call("{call CONCAT_NAME(?, ?, ?)}", [ .VARCHAR, 'Dierk', 'Koenig']) {
fullname -> fullname == 'Dierk Koenig'
}
3.8.5. Using DataSets
(TBD)
3.9. Processing XML
3.9.1. Parsing XML
XmlParser and XmlSlurper
The most commonly used approach for parsing XML with Groovy is to use one of:
groovy.util.XmlParser
groovy.util.XmlSlurper
Both have the same approach to parse an xml. Both come with a bunch of overloaded parse methods plus some special methods
such as parseText , parseFile and others. For the next example we will use the parseText method. It parses a XML String and
recursively converts it to a list or map of objects.
XmlSlurper
http://docs.groovy-lang.org/latest/html/documentation/ 346/502
1/6/2019 Groovy Language Documentation
text = '''
<list>
<technology>
<name>Groovy</name>
</technology>
</list>
'''
list = ().parseText(text) 1
list groovy.util.slurpersupport. 2
list.technology.name == 'Groovy' 3
1 Parsing the XML an returning the root node as a GPathResult
2 Checking we’re using a GPathResult
3 Traversing the tree in a GPath style
XmlParser
text = '''
<list>
<technology>
<name>Groovy</name>
</technology>
</list>
'''
list = ().parseText(text) 1
list groovy.util. 2
list.technology.name.text() == 'Groovy' 3
1 Parsing the XML an returning the root node as a Node
2 Checking we’re using a Node
3 Traversing the tree in a GPath style
Let’s see the similarities between XMLParser and XMLSlurper rst:
Both are based on SAX so they both are low memory footprint
Both can update/transform the XML
But they have key di erences:
XmlSlurper evaluates the structure lazily. So if you update the xml you’ll have to evaluate the whole tree again.
XmlSlurper returns GPathResult instances when parsing XML
XmlParser returns Node objects when parsing XML
When to use one or the another?
There is a discussion at StackOver ow (http://stackover ow.com/questions/7558019/groovy-xmlslurper-vs-
xmlparser). The conclusions written here are based partially on this entry.
If you want to transform an existing document to another then XmlSlurper will be the choice
If you want to update and read at the same time then XmlParser is the choice.
The rationale behind this is that every time you create a node with XmlSlurper it won’t be available until you parse the
document again with another XmlSlurper instance. Need to read just a few nodes XmlSlurper is for you ".
If you just have to read a few nodes XmlSlurper should be your choice, since it will not have to create a complete structure
in memory"
http://docs.groovy-lang.org/latest/html/documentation/ 347/502
1/6/2019 In general both classes perform similar way. Even the wayGroovy
of using GPath expressions
Language with them are the same (both use
Documentation
breadthFirst() and depthFirst() expressions). So I guess it depends on the write/read frequency.
DOMCategory
There is another way of parsing XML documents with Groovy with the used of groovy.xml.dom.DOMCategory which is a category
class which adds GPath style operations to Java’s DOM classes.
Java has in-built support for DOM processing of XML using classes representing the various parts of XML
documents, e.g. Document , Element , NodeList , Attr etc. For more information about these classes, refer to
the respective JavaDocs.
Having a XML like the following:
CAR_RECORDS = '''
<records>
<car name='HSV ' make=' ' year='2006'>
<country>Australia</country>
<record type='speed'>Production Pickup Truck with speed of 271kph</record>
</car>
<car name='P50' make=' ' year='1962'>
<country>Isle of Man</country>
<record type='size'>Smallest Street-Legal Car at 99cm wide and 59 kg in weight</record>
</car>
<car name=' ' make=' ' year='1931'>
<country>France</country>
<record type='price'>Most Valuable Car at $15 million</record>
</car>
</records>
'''
You can parse it using groovy.xml.DOMBuilder and groovy.xml.dom.DOMCategory .
reader = (CAR_RECORDS)
doc = .parse(reader) 1
records = doc.documentElement
( ) { 2
records.car.size() == 3
}
1 Parsing the XML
2 Creating DOMCategory scope to be able to use helper method calls
3.9.2. GPath
The most common way of querying XML in Groovy is using GPath :
GPath is a path expression language integrated into Groovy which allows parts of nested structured data to be identi ed. In this
sense, it has similar aims and scope as XPath does for XML. The two main places where you use GPath expressions is when
dealing with nested POJOs or when dealing with XML
It is similar to XPath (http://en.wikipedia.org/wiki/XPath) expressions and you can use it not only with XML but also with POJO
classes. 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 → all POJOs, yields the <c> properties for all the <b> properties of <a> (sort of like a.getB().getC() in JavaBeans)
For XML, you can also specify attributes, e.g.:
a["@href"] → the href attribute of all the a elements
a.'@href' → an alternative way of expressing this
a.@href → an alternative way of expressing this when using XmlSlurper
http://docs.groovy-lang.org/latest/html/documentation/ 348/502
1/6/2019 Let’s illustrate this with an example: Groovy Language Documentation
books = '''
<response version-api="2.0">
<value>
<books>
<book available="20" id="1">
<title>Don Xijote</title>
<author id="1">Manuel De Cervantes</author>
</book>
<book available="14" id="2">
<title>Catcher in the Rye</title>
<author id="2">JD Salinger</author>
</book>
<book available="13" id="3">
<title>Alice in Wonderland</title>
<author id="3">Lewis Carroll</author>
</book>
<book available="5" id="4">
<title>Don Xijote</title>
<author id="4">Manuel De Cervantes</author>
</book>
</books>
</value>
</response>
'''
Simply traversing the tree
First thing we could do is to get a value using POJO’s notation. Let’s get the rst book’s author’s name
Getting node value
response = ().parseText(books)
authorResult = response.value.books.book[0].author
authorResult.text() == 'Manuel De Cervantes'
First we parse the document with XmlSlurper and the we have to consider the returning value as the root of the XML document,
so in this case is "response".
That’s why we start traversing the document from response and then value.books.book[0].author . Note that in XPath the
node arrays starts in [1] instead of [0], but because GPath is Java-based it begins at index 0.
In the end we’ll have the instance of the author node and because we wanted the text inside that node we should be calling the
text() method. The author node is an instance of GPathResult type and text() a method giving us the content of that
node as a String.
When using GPath with an xml parsed with XmlSlurper we’ll have as a result a GPathResult object. GPathResult has many
other convenient methods to convert the text inside a node to any other type such as:
toInteger()
toFloat()
toBigInteger()
All these methods try to convert a String to the appropriate type.
If we were using a XML parsed with XmlParser we could be dealing with instances of type Node . But still all the actions applied
to GPathResult in these examples could be applied to a Node as well. Creators of both parsers took into account GPath
compatibility.
Next step is to get the some values from a given node’s attribute. In the following sample we want to get the rst book’s author’s
id. We’ll be using two di erent approaches. Let’s see the code rst:
http://docs.groovy-lang.org/latest/html/documentation/ 349/502
1/6/2019 Getting an attribute’s value Groovy Language Documentation
response = ().parseText(books)
book = response.value.books.book[0] 1
bookAuthorId1 = book.@id 2
bookAuthorId2 = book['@id'] 3
bookAuthorId1 == '1' 4
bookAuthorId1.toInteger() == 1 5
bookAuthorId1 == bookAuthorId2
1 Getting the rst book node
2 Getting the book’s id attribute @id
3 Getting the book’s id attribute with map notation ['@id']
4 Getting the value as a String
5 Getting the value of the attribute as an Integer
As you can see there are two types of notations to get attributes, the
direct notation with @nameoftheattribute
map notation using ['@nameoftheattribute']
Both of them are equally valid.
Flexible navigation with children (*), depthFirst (**) and breadthFirst
If you ever have used XPath, you may have used expressions like:
/following-sibling::othernode : Look for a node "othernode" in the same level
// : Look everywhere
More or less we have their counterparts in GPath with the shortcuts * (aka children() ) and ** (aka depthFirst() ).
The rst example shows a simple use of * , which only iterates over the direct children of the node.
Using *
response = ().parseText(books)
// .'*' could be replaced by .children()
catcherInTheRye = response.value.books.'*'.find { node->
// node.@id == 2 could be expressed as node['@id'] == 2
node.name() == 'book' && node.@id == '2'
}
catcherInTheRye.title.text() == 'Catcher in the Rye'
This test searches for any child nodes of the "books" node matching the given condition. In a bit more detail, the expression says:
Look for any node with a tag name equal to 'book' having an id with a value of '2' directly under the 'books' node.
This operation roughly corresponds to the breadthFirst() method, except that it only stops at one level instead of continuing
to the inner levels.
What if we would like to look for a given value without having to know exactly where it is. Let’s say that the only thing we know is
the id of the author "Lewis Carroll" . How are we going to be able to nd that book? Using ** is the solution:
Using **
http://docs.groovy-lang.org/latest/html/documentation/ 350/502
1/6/2019 Groovy Language Documentation
response = ().parseText(books)
// .'**' could be replaced by .depthFirst()
bookId = response.'**'.find { book->
book.author.text() == 'Lewis Carroll'
}.@id
bookId == 3
** is the same as looking for something everywhere in the tree from this point down. In this case, we’ve used the method
find(Closure cl) to nd just the rst occurrence.
What if we want to collect all book’s titles? That’s easy, just use findAll :
response = ().parseText(books)
titles = response.'**'.findAll{ node-> node.name() == 'title' }*.text()
titles.size() == 4
In the last two examples, ** is used as a shortcut for the depthFirst() method. It goes as far down the tree as it can while
navigating down the tree from a given node. The breadthFirst() method nishes o all nodes on a given level before
traversing down to the next level.
The following example shows the di erence between these two methods:
depthFirst() vs .breadthFirst
response = ().parseText(books)
nodeName = { node -> node.name() }
withId2or3 = { node -> node.@id [2, 3] }
['book', 'author', 'book', 'author'] ==
response.value.books.depthFirst().findAll(withId2or3).collect(nodeName)
['book', 'book', 'author', 'author'] ==
response.value.books.breadthFirst().findAll(withId2or3).collect(nodeName)
In this example, we search for any nodes with an id attribute with value 2 or 3. There are both book and author nodes that
match that criteria. The di erent traversal orders will nd the same nodes in each case but in di erent orders corresponding to
how the tree was traversed.
It is worth mentioning again that there are some useful methods converting a node’s value to an integer, oat, etc. Those methods
could be convenient when doing comparisons like this:
helpers
response = ().parseText(books)
titles = response.value.books.book.findAll{book->
/* You can use toInteger() over the GPathResult object */
[email protected]() > 2
}*.title
titles.size() == 2
In this case the number 2 has been hardcoded but imagine that value could have come from any other source (database… etc.).
3.9.3. Creating XML
The most commonly used approach for creating XML with Groovy is to use a builder, i.e. one of:
groovy.xml.MarkupBuilder
groovy.xml.StreamingMarkupBuilder
MarkupBuilder
http://docs.groovy-lang.org/latest/html/documentation/ 351/502
1/6/2019 Here is an example of using Groovy’s MarkupBuilder to create a new
Groovy XML Documentation
Language le:
Creating Xml with MarkupBuilder
writer = ()
xml = (writer) 1
xml.records() { 2
car(name:'HSV Maloo', make:'Holden', year:2006) {
country('Australia')
record(type:'speed', 'Production Pickup Truck with speed of 271kph')
}
car(name:'Royale', make:'Bugatti', year:1931) {
country('France')
record(type:'price', 'Most Valuable Car at $15 million')
}
}
records = ().parseText(writer.toString()) 3
records.car.first().name.text() == 'HSV Maloo'
records.car. ().name.text() == 'Royale'
1 Create an instance of MarkupBuilder
2 Start creating the XML tree
3 Create an instance of XmlSlurper to traverse and test the generated XML
Let’s take a look a little bit closer:
Creating XML elements
xmlString = "<movie>the godfather</movie>" 1
xmlWriter = () 2
xmlMarkup = (xmlWriter)
xmlMarkup.movie("the godfather") 3
xmlString == xmlWriter.toString() 4
1 We’re creating a reference string to compare against
2 The xmlWriter instance is used by MarkupBuilder to convert the xml representation to a String instance eventually
3 The xmlMarkup.movie(…) call will create a XML node with a tag called movie and with content the godfather .
Creating XML elements with attributes
xmlString = "<movie id='2'>the godfather</movie>"
xmlWriter = ()
xmlMarkup = (xmlWriter)
xmlMarkup.movie(id: "2", "the godfather") 1
xmlString == xmlWriter.toString()
This time in order to create both attributes and node content you can create as many map entries as you like and nally add
1
a value to set the node’s content
The value could be any Object , the value will be serialized to its String representation.
Creating XML nested elements
http://docs.groovy-lang.org/latest/html/documentation/ 352/502
1/6/2019 Groovy Language Documentation
xmlWriter = ()
xmlMarkup = (xmlWriter)
xmlMarkup.movie(id: 2) { 1
name("the godfather")
}
movie = ().parseText(xmlWriter.toString())
movie.@id == 2
movie.name.text() == 'the godfather'
A closure represents the children elements of a given node. Notice this time instead of using a String for the attribute we’re
1
using a number.
Sometimes you may want to use a speci c namespace in your xml documents:
Namespace aware
xmlWriter = ()
xmlMarkup = (xmlWriter)
xmlMarkup
.'x:movies'('xmlns:x':'http://www.groovy-lang.org') { 1
'x:movie'(id: 1, 'the godfather')
'x:movie'(id: 2, 'ronin')
}
movies =
() 2
.parseText(xmlWriter.toString())
.declareNamespace(x:'http://www.groovy-lang.org')
movies.'x:movie'. ().@id == 2
movies.'x:movie'. ().text() == 'ronin'
1 Creating a node with a given namespace xmlns:x
2 Creating a XmlSlurper registering the namespace to be able to test the XML we just created
What about having some more meaningful example. We may want to generate more elements, to have some logic when creating
our XML:
Mix code
xmlWriter = ()
xmlMarkup = (xmlWriter)
xmlMarkup
.'x:movies'('xmlns:x':'http://www.groovy-lang.org') {
(1..3).each { n -> 1
'x:movie'(id: n, "the godfather $n")
(n % 2 == 0) { 2
'x:movie'(id: n, "the godfather $n (Extended)")
}
}
}
movies =
()
.parseText(xmlWriter.toString())
.declareNamespace(x:'http://www.groovy-lang.org')
movies.'x:movie'.size() == 4
movies.'x:movie'*.text().every { name -> name.startsWith('the')}
1 Generating elements from a range
http://docs.groovy-lang.org/latest/html/documentation/ 353/502
1/6/2019 2 Using a conditional for creating a given element Groovy Language Documentation
Of course the instance of a builder can be passed as a parameter to refactor/modularize your code:
Mix code
xmlWriter = ()
xmlMarkup = (xmlWriter)
< > buildMovieList = { builder ->
(1..3).each { n ->
builder.'x:movie'(id: n, "the godfather $n")
(n % 2 == 0) {
builder.'x:movie'(id: n, "the godfather $n (Extended)")
}
}
builder
}
xmlMarkup.'x:movies'('xmlns:x':'http://www.groovy-lang.org') {
buildMovieList(xmlMarkup) 2
}
movies =
()
.parseText(xmlWriter.toString())
.declareNamespace(x:'http://www.groovy-lang.org')
movies.'x:movie'.size() == 4
movies.'x:movie'*.text().every { name -> name.startsWith('the')}
1 In this case we’ve created a Closure to handle the creation of a list of movies
2 Just using the buildMovieList function when necessary
StreamingMarkupBuilder
The class groovy.xml.StreamingMarkupBuilder is a builder class for creating XML markup. This implementation uses a
groovy.xml.streamingmarkupsupport.StreamingMarkupWriter to handle output.
Using StreamingMarkupBuilder
xml = ().bind { 1
records {
car(name:'HSV Maloo', make:'Holden', year:2006) { 2
country('Australia')
record(type:'speed', 'Production Pickup Truck with speed of 271kph')
}
car(name:'P50', make:'Peel', year:1962) {
country('Isle of Man')
record(type:'size', 'Smallest Street-Legal Car at 99cm wide and 59 kg in weight')
}
car(name:'Royale', make:'Bugatti', year:1931) {
country('France')
record(type:'price', 'Most Valuable Car at $15 million')
}
}
}
records = ().parseText(xml.toString()) 3
records.car.size() == 3
records.car.find { it.@name == 'P50' }.country.text() == 'Isle of Man'
Note that StreamingMarkupBuilder.bind returns a Writable instance that may be used to stream the markup to a
1
Writer
http://docs.groovy-lang.org/latest/html/documentation/ 354/502
1/6/2019 2 Groovy
We’re capturing the output in a String to parse it again Language
an check Documentation
the structure of the generated XML with XmlSlurper .
MarkupBuilderHelper
The groovy.xml.MarkupBuilderHelper is, as its name re ects, a helper for groovy.xml.MarkupBuilder .
This helper normally can be accessed from within an instance of class groovy.xml.MarkupBuilder or an instance of
groovy.xml.StreamingMarkupBuilder .
This helper could be handy in situations when you may want to:
Produce a comment in the output
Produce an XML processing instruction in the output
Produce an XML declaration in the output
Print data in the body of the current tag, escaping XML entities
Print data in the body of the current tag
In both MarkupBuilder and StreamingMarkupBuilder this helper is accessed by the property mkp :
Using MarkupBuilder’s 'mkp'
xmlWriter = ()
xmlMarkup = (xmlWriter).rules {
mkp.comment('THIS IS THE MAIN RULE') 1
rule(sentence: mkp. ('3 > n')) 2
}
xmlWriter.toString().contains('3 > n')
xmlWriter.toString().contains('<!-- THIS IS THE MAIN RULE -->')
1 Using mkp to create a comment in the XML
2 Using mkp to generate an escaped value
3 Checking both assumptions were true
Here is another example to show the use of mkp property accessible from within the bind method scope when using
StreamingMarkupBuilder :
Using StreamingMarkupBuilder’s 'mkp'
xml = ().bind {
records {
car(name: mkp. ('3 < 5')) 1
car(name: mkp.yieldUnescaped('1 < 3')) 2
}
}
xml.toString().contains('3 < 5')
xml.toString().contains('1 < 3')
1 If we want to generate a escaped value for the name attribute with mkp.yield
2 Checking the values later on with XmlSlurper
DOMToGroovy
Suppose we have an existing XML document and we want to automate generation of the markup without having to type it all in?
We just need to use org.codehaus.groovy.tools.xml.DOMToGroovy as shown in the following example:
Building MarkupBuilder from DOMToGroovy
http://docs.groovy-lang.org/latest/html/documentation/ 355/502
1/6/2019 Groovy Language Documentation
songs = """
<songs>
<song>
<title>Here I go</title>
<band>Whitesnake</band>
</song>
</songs>
"""
builder =
javax.xml.parsers. .newInstance().newDocumentBuilder()
inputStream = (songs.bytes)
document = builder.parse(inputStream)
output = ()
converter = ( (output)) 1
converter. (document) 2
xmlRecovered =
()
.evaluate("""
def writer = new StringWriter()
def builder = new groovy.xml.MarkupBuilder(writer)
builder.${output}
return writer.toString()
""") 3
().parseText(xmlRecovered).song.title.text() == 'Here I go' 4
1 Creating DOMToGroovy instance
2 Converts the XML to MarkupBuilder calls which are available in the output StringWriter
3 Using output variable to create the whole MarkupBuilder
4 Back to XML string
3.9.4. Manipulating XML
In this chapter you’ll see the di erent ways of adding / modifying / removing nodes using XmlSlurper or XmlParser . The xml we
are going to be handling is the following:
xml = """
<response version-api="2.0">
<value>
<books>
<book id="2">
<title>Don Xijote</title>
<author id="1">Manuel De Cervantes</author>
</book>
</books>
</value>
</response>
"""
Adding nodes
The main di erence between XmlSlurper and XmlParser is that when former creates the nodes they won’t be available until
the document’s been evaluated again, so you should parse the transformed document again in order to be able to see the new
nodes. So keep that in mind when choosing any of both approaches.
If you needed to see a node right after creating it then XmlParser should be your choice, but if you’re planning to do many
changes to the XML and send the result to another process maybe XmlSlurper would be more e cient.
You can’t create a new node directly using the XmlSlurper instance, but you can with XmlParser . The way of creating a new
node from XmlParser is through its method createNode(..)
http://docs.groovy-lang.org/latest/html/documentation/ 356/502
1/6/2019 Groovy Language Documentation
parser = ()
response = parser.parseText(xml)
numberOfResults = parser.createNode(
response,
("numberOfResults"),
[:]
)
numberOfResults.value = "1"
response.numberOfResults.text() == "1"
The createNode() method receives the following parameters:
parent node (could be null)
The quali ed name for the tag (In this case we only use the local part without any namespace). We’re using an instance of
groovy.xml.QName
A map with the tag’s attributes (None in this particular case)
Anyway you won’t normally be creating a node from the parser instance but from the parsed XML instance. That is from a Node
or a GPathResult instance.
Take a look at the next example. We are parsing the xml with XmlParser and then creating a new node from the parsed
document’s instance (Notice the method here is slightly di erent in the way it receives the parameters):
parser = ()
response = parser.parseText(xml)
response.appendNode(
("numberOfResults"),
[:],
"1"
)
response.numberOfResults.text() == "1"
When using XmlSlurper , GPathResult instances don’t have createNode() method.
Modifying / Removing nodes
We know how to parse the document, add new nodes, now I want to change a given node’s content. Let’s start using XmlParser
and Node . This example changes the rst book information to actually another book.
response = ().parseText(xml)
/* Use the same syntax as groovy.xml.MarkupBuilder */
response.value.books.book[0].replaceNode{ 1
book(id:"3"){
title("To Kill a Mockingbird")
author(id:"3","Harper Lee")
}
}
newNode = response.value.books.book[0]
newNode.name() == "book"
newNode.@id == "3"
newNode.title.text() == "To Kill a Mockingbird"
newNode.author.text() == "Harper Lee"
[email protected]() == "3"
When using replaceNode() the closure we pass as parameter should follow the same rules as if we were using
groovy.xml.MarkupBuilder :
Here’s the same example using XmlSlurper :
http://docs.groovy-lang.org/latest/html/documentation/ 357/502
1/6/2019 Groovy Language Documentation
response = ().parseText(books)
/* Use the same syntax as groovy.xml.MarkupBuilder */
response.value.books.book[0].replaceNode{
book(id:"3"){
title("To Kill a Mockingbird")
author(id:"3","Harper Lee")
}
}
response.value.books.book[0].title.text() == "Don Xijote"
/* That mkp is a special namespace used to escape away from the normal building mode
of the builder and get access to helper markup methods
'yield', 'pi', 'comment', 'out', 'namespaces', 'xmlDeclaration' and
'yieldUnescaped' */
result = ().bind { mkp. response }.toString()
changedResponse = ().parseText(result)
changedResponse.value.books.book[0].title.text() == "To Kill a Mockingbird"
Notice how using XmlSlurper we have to parse the transformed document again in order to nd the created nodes. In this
particular example could be a little bit annoying isn’t it?
Finally both parsers also use the same approach for adding a new attribute to a given attribute. This time again the di erence is
whether you want the new nodes to be available right away or not. First XmlParser :
parser = ()
response = parser.parseText(xml)
response.@numberOfResults = "1"
response.@numberOfResults == "1"
And XmlSlurper :
response = ().parseText(books)
response.@numberOfResults = "2"
response.@numberOfResults == "2"
When using XmlSlurper , adding a new attribute does not require you to perform a new evaluation.
Printing XML
XmlUtil
Sometimes is useful to get not only the value of a given node but the node itself (for instance to add this node to another XML).
For that you can use groovy.xml.XmlUtil class. It has several static methods to serialize the xml fragment from several type of
sources (Node, GPathResult, String…)
Getting a node as a string
response = ().parseText(xml)
nodeToSerialize = response.'**'.find {it.name() == 'author'}
nodeAsText = .serialize(nodeToSerialize)
nodeAsText ==
.serialize('<?xml version="1.0" encoding="UTF-8"?><author id="1">Manuel De
Cervantes</author>')
3.10. Scripting Ant tasks
Groovy integrates very well with Apache Ant (http://ant.apache.org) thanks to AntBuilder.
http://docs.groovy-lang.org/latest/html/documentation/ 358/502
1/6/2019 3.11. The <groovy> Ant Task Groovy Language Documentation
Executes a series of Groovy statements from Apache Ant (http://ant.apache.org/). Statements can either be read in from a text le
using the src attribute or from between the enclosing Groovy tags.
3.11.1. Required taskdef
Assuming all the groovy jars you need are in my.classpath (this will be groovy-VERSION.jar , groovy-ant-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 groovy task being invoked.
name="groovy"
classname="org.codehaus.groovy.ant.Groovy"
classpathref="my.classpath"
Now use the task like this:
src="..." otherAttributes="..."
Or this:
...
You might need to use the contextClassLoader attribute (see below) if any of your modules load services via the classpath, e.g.
groovy-json .
3.11.2. <groovy> attributes
Attribute Description Required
src File containing Groovy statements. The directory containing Yes, unless statements
the le is added to the classpath. enclosed within tags
classpath The classpath to use. No
classpathref The classpath to use, given as reference to a PATH de ned No
elsewhere.
output Set the output le; defaults to the Ant log. No
append If enabled and output is to a le, append to existing le rather No
than overwrite. Defaults to false.
fork If enabled the script will be executed in a forked JVM process No
(disabled by default).
scriptBaseClass The name of the base class for scripts. No
indy If enabled the script will be executed with invokedynamic No
(disabled by default).
parameters Generates metadata for re ection on method parameter No
names on JDK 8 and above. Defaults to false.
useGroovyShell If enabled a new GroovyShell is used to run the script. Special No
variables won’t be available but you don’t need Ant in the
classpath. Defaults to false.
contextClassLoader If enabled, the contextClassLoader to be set with the No
classLoader of the shell used to run the script. Not used if
fork is true.
http://docs.groovy-lang.org/latest/html/documentation/ 359/502
1/6/2019 Groovy Language Documentation
Attribute Description Required
includeAntRuntime If enabled the system classpath will be included on the No
classpath when forking. Defaults to true.
stacktrace If enabled a stacktrace will be reported if an error occurs No
during compilation. Defaults to false.
con gScript Sets the con guration script for the groovy compiler No
con guration.
contextClassLoader If enabled, the contextClassLoader to be set with the No
classLoader of the shell used to run the script. Not used if
fork is true.
3.11.3. Parameters speci ed as nested elements
<classpath>
Groovy’s classpath attribute is a PATH like structure and can also be set via a nested classpath element.
<arg>
Arguments can be set via one or more nested <arg> elements using the standard Ant command line conventions
(http://ant.apache.org/manual/using.html#arg).
3.11.4. Available bindings
A number of bindings are in scope for use within your Groovy statements.
Name Description
ant an instance of AntBuilder that knows about the current ant project
project the current ant project
properties a Map of ant properties
target the owning target that invoked this groovy script
task the wrapping task, can access anything needed in org.apache.tools.ant.Task
args command line arguments, if any
3.11.5. Examples
Hello world, version 1:
println "Hello World"
Hello world, version 2:
ant.echo "Hello World"
List all xml les in the current directory:
xmlfiles = new File(".").listFiles().findAll{ it =~ "\.xml$" }
xmlfiles.sort().each { println it.toString() }
List all xml les within a jar:
http://docs.groovy-lang.org/latest/html/documentation/ 360/502
1/6/2019 Groovy Language Documentation
id="found" src="foobar.jar"
includes="**/*.xml"
project.references.found.each {
println it.name
}
Run a script:
src="/some/directory/some/file.groovy"
location="/my/groovy/classes/directory"
Find all Builder classes having an org.* package within a directory of jars:
name="local.target" value="C:/Projects/GroovyExamples"
import java.util.jar.JarFile
def classes = []
def resourceNamePattern = /org\/.*\/.*Builder.class/
def jarNamePattern = /.*(beta|commons).*jar$/
def libdir = new File("${properties['local.target']}/lib")
libdir.listFiles().grep(~jarNamePattern).each { candidate ->
new JarFile(candidate).entries().each { entry ->
if (entry.name ==~ resourceNamePattern) classes += entry.name
}
}
properties["builder-classes"] = classes.join(' ')
message='${builder-classes}'
Which might result in something like:
org/apache/commons/cli/ . org/apache/commons/cli/ .
org/codehaus/groovy/tools/groovydoc/ .
org/custommonkey/xmlunit/ .
org/custommonkey/xmlunit/ .
FileScanner version of above (with a slight variation on collecting the names):
import java.util.jar.JarFile
def resourceNamePattern = /org\/.*\/.*Builder.class/
def candidates = ant.fileScanner {
fileset(dir: '${local.target}/lib') {
include(name: '*beta*.jar')
include(name: '*commons*.jar')
}
}
def classes = candidates.collect {
new JarFile(it).entries().collect { it.name }.findAll {
it ==~ resourceNamePattern
}
}.flatten()
properties["builder-classes"] = classes.join(' ')
Calling out to a web service from your Ant script:
http://docs.groovy-lang.org/latest/html/documentation/ 361/502
1/6/2019 Groovy Language Documentation
<?xml version="1.0" encoding="UTF-8"?>
name="SOAP example" default="main" basedir="."
environment="env"
name="celsius" value="0"
name="main"
name="groovy" classname="org.codehaus.groovy.ant.Groovy"
dir="${env.GROOVY_HOME}" includes="lib/groovy-*.jar,lib/ivy*.jar"
@Grab('org.codehaus.groovy.modules:groovyws:0.5.1')
import groovyx.net.ws.WSClient
def url = 'http://www.w3schools.com/webservices/tempconvert.asmx?WSDL'
def proxy = new WSClient(url, this.class.classLoader)
proxy.initialize()
ant.echo "I'm freezing at ${properties.celsius} degrees Celsius"
properties.result = proxy.CelsiusToFahrenheit(properties.celsius)
target="results"
name="results"
message="I'm freezing at ${result} degrees Fahrenheit"
Which will output the following (along with some informational messages):
main:
...
[echo] I'm freezing at 0 degrees Celsius
results:
[echo] I'm freezing at 32 degrees
BUILD SUCCESSFUL
Setting arguments:
name="run"
line="1 2 3"
value="4 5"
println args.size()
println args[2]
args.each{ ant.echo(message:it) }
Output:
: build.xml
run:
[groovy] 4
[groovy] 3
[echo] 1
[echo] 2
[echo] 3
[echo] 4 5
BUILD SUCCESSFUL
3.12. Template engines
http://docs.groovy-lang.org/latest/html/documentation/ 362/502
1/6/2019 3.12.1. Introduction Groovy Language Documentation
Groovy supports multiple ways to generate text dynamically including GStrings , printf and MarkupBuilder just to name a few.
In addition to these, there is a dedicated template framework which is well-suited to applications where the text to be generated
follows the form of a static template.
3.12.2. Template framework
The template framework in Groovy consists of a TemplateEngine abstract base class that engines must implement and a
Template interface that the resulting templates they generate must implement.
Included with Groovy are several template engines:
SimpleTemplateEngine - for basic templates
StreamingTemplateEngine - functionally equivalent to SimpleTemplateEngine , but can handle strings larger than 64k
GStringTemplateEngine - stores the template as writeable closures (useful for streaming scenarios)
XmlTemplateEngine - works well when the template and output are valid XML
MarkupTemplateEngine - a very complete, optimized, template engine
3.12.3. SimpleTemplateEngine
Shown here is the SimpleTemplateEngine that allows you to use JSP-like scriptlets (see example below), script, and EL
expressions in your template in order to generate parametrized text. Here is an example of using the system:
text = 'Dear "$firstname $lastname",\nSo nice to meet you in <% print city %>.\nSee you in
${month},\n${signed}'
binding = ["firstname":"Sam", "lastname":"Pullara", "city":"San Francisco",
"month":"December", "signed":"Groovy-Dev"]
engine = groovy.text. ()
= engine.createTemplate(text).make(binding)
result = 'Dear "Sam Pullara",\nSo nice to meet you in San Francisco.\nSee you in
December,\nGroovy-Dev'
result == .toString()
While it is generally not deemed good practice to mix processing logic in your template (or view), sometimes very simple logic can
be useful. E.g. in the example above, we could change this:
$firstname
to this (assuming we have set up a static import for capitalize inside the template):
${firstname.capitalize()}
or this:
<% city %>
to this:
<% city == "New York" ? "The Big Apple" : city %>
Advanced Usage Note
If you happen to be embedding your template directly in your script (as we did above) you have to be careful about backslash
escaping. Because the template string itself will be parsed by Groovy before it is passed to the the templating framework, you
have to escape any backslashes inside GString expressions or scriptlet 'code' that are entered as part of a Groovy program. E.g. if
we wanted quotes around The Big Apple above, we would use:
http://docs.groovy-lang.org/latest/html/documentation/ 363/502
1/6/2019 Groovy Language Documentation
<% city == "New York" ? "\\" \\"" : city %>
Similarly, if we wanted a newline, we would use:
\\n
in any GString expression or scriptlet 'code' that appears inside a Groovy script. A normal “\n” is ne within the static template text
itself or if the entire template itself is in an external template le. Similarly, to represent an actual backslash in your text you would
need
\\\\
in an external le or
\\\\
in any GString expression or scriptlet 'code'. (Note: the necessity to have this extra slash may go away in a future version of
Groovy if we can nd an easy way to support such a change.)
3.12.4. StreamingTemplateEngine
The StreamingTemplateEngine engine is functionally equivalent to the SimpleTemplateEngine , but creates the template using
writable closures making it more scalable for large templates. Speci cally this template engine can handle strings larger than 64k.
It uses JSP style <% %> script and <%= %> expression syntax or GString style expressions. The variable 'out' is bound to the writer
that the template is being written to.
Frequently, the template source will be a le but here we show a simple example providing the template as a string:
text = '''\
Dear <% out.print firstname %> ${lastname},
We <% if (accepted) out.print 'are pleased' else out.print 'regret' %> \
to inform you that your paper entitled
'$title' was ${ accepted ? 'accepted' : 'rejected' }.
The conference committee.'''
= groovy.text. ().createTemplate(text)
binding = [
firstname : "Grace",
lastname : "Hopper",
accepted : ,
title : 'Groovy for COBOL programmers'
]
response = .make(binding)
response == '''Dear Grace Hopper,
We are pleased to inform you that your paper entitled
' COBOL programmers' was accepted.
The conference committee.'''
3.12.5. GStringTemplateEngine
As an example of using the GStringTemplateEngine , here is the example above done again (with a few changes to show some
other options). First we will store the template in a le this time:
test.template
http://docs.groovy-lang.org/latest/html/documentation/ 364/502
1/6/2019 Groovy Language Documentation
"$firstname $lastname",
nice to meet you <% << (city == "New York" ? "\\" \\"" : city) %>.
you ${month},
${ }
Note that we used out instead of print to support the streaming nature of GStringTemplateEngine . Because we have the
template in a separate le, there is no need to escape the backslashes. Here is how we call it:
f = ('test.template')
engine = groovy.text. ()
= engine.createTemplate(f).make(binding)
println .toString()
and here is the output:
Dear "Sam Pullara",
So nice to meet you in "The Big Apple".
See you in December,
Groovy-Dev
3.12.6. XmlTemplateEngine
XmlTemplateEngine for use in templating scenarios where both the template source and the expected output are intended to be
XML. Templates may use the normal ${expression} and $variable notations to insert an arbitrary expression into the
template. In addition, support is also provided for special tags: <gsp:scriptlet> (for inserting code fragments) and
<gsp:expression> (for code fragments which produce output).
Comments and processing instructions will be removed as part of processing and special XML characters such as < , > , " and '
will be escaped using the respective XML notation. The output will also be indented using standard XML pretty printing.
The xmlns namespace de nition for gsp: tags will be removed but other namespace de nitions will be preserved (but may change
to an equivalent position within the XML tree).
Normally, the template source will be in a le but here is a simple example providing the XML template as a string:
binding = [firstname: 'Jochen', lastname: 'Theodorou', nickname: 'blackdrag', salutation:
'Dear']
engine = groovy.text. ()
text = '''\
<document xmlns:gsp='http://groovy.codehaus.org/2005/gsp' xmlns:foo='baz' type='letter'>
<gsp:scriptlet> greeting = "${salutation}est"</gsp:scriptlet>
<gsp:expression>greeting</gsp:expression>
<foo:to>$firstname "$nickname" $lastname</foo:to>
are you today?
</document>
'''
def template = engine.createTemplate(text).make(binding)
println template.toString()
This example will produce this output:
type='letter'
Dearest
xmlns:foo='baz'
Jochen "blackdrag" Theodorou
How are you today?
3.12.7. The MarkupTemplateEngine
http://docs.groovy-lang.org/latest/html/documentation/ 365/502
1/6/2019 This template engine is a template engine primarily aimedGroovy
at generating
LanguageXML-like markup (XML, XHTML, HTML5, …), but that can
Documentation
be used to generate any text based content. Unlike traditional template engines, this one relies on a DSL that uses the builder
syntax. Here is a sample template:
xmlDeclaration()
cars {
cars.each {
car(make: it.make, model: it.model)
}
}
If you feed it with the following model:
model = [cars: [ (make: 'Peugeot', model: '508'), (make: 'Toyota', model: 'Prius')]]
It would be rendered as:
<?xml version='1.0'?>
make='Peugeot' model='508' make='Toyota' model='Prius'
The key features of this template engine are:
a markup builder like syntax
templates are compiled into bytecode
fast rendering
optional type checking of the model
includes
internationalization support
fragments/layouts
The template format
Basics
Templates consist of Groovy code. Let’s explore the rst example more thoroughly:
xmlDeclaration() 1
cars { 2
cars.each { 3
car(make: it.make, model: it.model) 4
} 5
1 renders the XML declaration string.
2 opens a cars tag
3 cars is a variable found in the template model, which is a list of Car instances
4 for each item, we create a car tag with the attributes from the Car instance
5 closes the cars tag
As you can see, regular Groovy code can be used in the template. Here, we are calling each on a list (retrieved from the model),
allowing us to render one car tag per entry.
In a similar fashion, rendering HTML code is as simple as this:
http://docs.groovy-lang.org/latest/html/documentation/ 366/502
1/6/2019 Groovy Language Documentation
yieldUnescaped '<!DOCTYPE html>' 1
html(lang:'en') { 2
head { 3
meta('http-equiv':'"Content-Type" content="text/html; charset=utf-8"') 4
title('My page') 5
} 6
body { 7
p('This is an example of HTML contents') 8
} 9
} 10
1 renders the HTML doctype special tag
2 opens the html tag with an attribute
3 opens the head tag
4 renders a meta tag with one http-equiv attribute
5 renders the title tag
6 closes the head tag
7 opens the body tag
8 renders a p tag
9 closes the body tag
10 closes the html tag
The output is straightforward:
<!DOCTYPE html> lang='en' http-equiv='"Content-Type" content="text/html;
charset=utf-8"' My page This is an example of HTML contents
With some con guration, you can have the output pretty printed, with newlines and indent automatically added.
Support methods
In the previous example, the doctype declaration was rendered using the yieldUnescaped method. We have also seen the
xmlDeclaration method. The template engine provides several support methods that will help you render contents
appropriately:
Method Description Example
yield Renders contents, but escapes it before Template:
rendering
'Some text with <angle brackets>'
Output:
Some text with <angle brackets>
yieldUnescaped Renders raw contents. The argument is Template:
rendered as is, without escaping.
yieldUnescaped 'Some text with <angle
brackets>'
Output:
Some text with brackets
http://docs.groovy-lang.org/latest/html/documentation/ 367/502
1/6/2019 Groovy Language Documentation
Method Description Example
xmlDeclaration Renders an XML declaration String. If the Template:
encoding is speci ed in the con guration, it is
written in the declaration. xmlDeclaration()
Output:
<?xml version='1.0'?>
If TemplateConfiguration#getDeclarationEncoding
is not null:
Output:
<?xml version='1.0' encoding='UTF-8'?>
comment Renders raw contents inside an XML comment Template:
comment 'This is <a
href="foo.html">commented out</a>'
Output:
<!--This is <a href="foo.html">commented
out</a>-->
newLine Renders a new line. See also Template:
TemplateConfiguration#setAutoNewLine
and p('text')
TemplateConfiguration#setNewLineString . newLine()
p('text on new line')
Output:
text
text on new line
pi Renders an XML processing instruction. Template:
pi("xml-stylesheet":[href:"mystyle.css",
type:"text/css"])
Output:
<?xml-stylesheet href='mystyle.css'
type='text/css'?>
http://docs.groovy-lang.org/latest/html/documentation/ 368/502
1/6/2019 Groovy Language Documentation
Method Description Example
tryEscape Returns an escaped string for an object, if it is a Template:
String (or any type derived from
CharSequence ). Otherwise returns the object yieldUnescaped tryEscape('Some text with
itself. <angle brackets>')
Output:
Some text with <angle brackets>
Includes
The MarkupTemplateEngine supports inclusion of contents from another le. Included contents may be:
another template
raw contents
contents to be escaped
Including another template can be done using:
include : 'other_template.tpl'
Including a le as raw contents, without escaping it, can be done like this:
include unescaped: 'raw.txt'
Eventually, inclusion of text that should be escaped before rendering can be done using:
include escaped: 'to_be_escaped.txt'
Alternatively, you can use the following helper methods instead:
includeGroovy(<name>) to include another template
includeEscaped(<name>) to include another le with escaping
includeUnescaped(<name>) to include another le without escaping
Calling those methods instead of the include xxx: syntax can be useful if the name of the le to be included is dynamic (stored
in a variable for example). Files to be included (independently of their type, template or text) are found on classpath. This is one of
the reasons why the MarkupTemplateEngine takes an optional ClassLoader as constructor argument (the other reason being
that you can include code referencing other classes in a template).
If you don’t want your templates to be on classpath, the MarkupTemplateEngine accepts a convenient constructor that lets you
de ne the directory where templates are to be found.
Fragments
Fragments are nested templates. They can be used to provide improved composition in a single template. A fragment consists of a
string, the inner template, and a model, used to render this template. Consider the following template:
ul {
pages.each {
fragment "li(line)", line:it
}
}
The fragment element creates a nested template, and renders it with a model which is speci c to this template. Here, we have
the li(line) fragment, where line is bound to it . Since it corresponds to the iteration of pages , we will generate a single
li element for each page in our model:
http://docs.groovy-lang.org/latest/html/documentation/ 369/502
1/6/2019 Groovy Language Documentation
Page 1 Page 2
Fragments are interesting to factorize template elements. They come at the price of the compilation of a fragment per template,
and they cannot be externalized.
Layouts
Layouts, unlike fragments, refer to other templates. They can be used to compose templates and share common structures. This
is often interesting if you have, for example, a common HTML page setup, and that you only want to replace the body. This can be
done easily with a layout. First of all, you need to create a layout template:
layout-main.tpl
html {
head {
title(title) 1
}
body {
bodyContents() 2
}
}
1 the title variable (inside the title tag) is a layout variable
2 the bodyContents call will render the body
Then what you need is a template that includes the layout:
layout 'layout-main.tpl', 1
title: 'Layout example', 2
bodyContents: contents { p('This is the body') } 3
1 use the main-layout.tpl layout le
2 set the title variable
3 set the bodyContents
As you can see, bodyContents will be rendered inside the layout, thanks to the bodyContents() call in the layout le. As a
result, the template will be rendered as this:
Layout example This is the body
The call to the contents method is used to tell the template engine that the block of code is in fact a speci cation of a template,
instead of a helper function to be rendered directly. If you don’t add contents before your speci cation, then the contents would
be rendered, but you would also see a random string generated, corresponding to the result value of the block.
Layouts are a powerful way to share common elements across multiple templates, without having to rewrite everything or use
includes.
Layouts use, by default, a model which is independent from the model of the page where they are used. It is however possible to
make them inherit from the parent model. Imagine that the model is de ned like this:
model = < , >();
model.put('title','Title from main model');
and the following template:
layout 'layout-main.tpl', , 1
bodyContents: contents { p('This is the body') }
1 note the use of true to enable model inheritance
then it is not necessary to pass the title value to the layout as in the previous example. The result will be:
http://docs.groovy-lang.org/latest/html/documentation/ 370/502
1/6/2019 Groovy Language Documentation
Title from main model This is the body
But it is also possible to override a value from the parent model:
layout 'layout-main.tpl', , 1
title: 'overridden title', 2
bodyContents: contents { p('This is the body') }
1 true means inherit from the parent model
2 but title is overridden
then the output will be:
overridden title This is the body
Rendering contents
Creation of a template engine
On the server side, rendering templates require an instance of groovy.text.markup.MarkupTemplateEngine and a
groovy.text.markup.TemplateConfiguration :
config = (); 1
engine = (config); 2
template = engine.createTemplate("p('test template')"); 3
< , > model = <>(); 4
output = template.make(model); 5
output.writeTo(writer); 6
1 creates a template con guration
2 creates a template engine with this con guration
3 creates a template instance from a String
4 creates a model to be used in the template
5 bind the model to the template instance
6 render output
There are several possible options to parse templates:
from a String , using createTemplate(String)
from a Reader , using createTemplate(Reader)
from a URL , using createTemplate(URL)
given a template name, using createTemplateByPath(String)
The last version should in general be preferred:
= engine.createTemplateByPath("main.tpl");
output = .make(model);
output.writeTo(writer);
Con guration options
The behavior of the engine can be tweaked with several con guration options accessible through the TemplateConfiguration
class:
Option Default value Description Example
http://docs.groovy-lang.org/latest/html/documentation/ 371/502
1/6/2019 Groovy Language Documentation
Option Default value Description Example
declarationEncoding null Determines the Template:
value of the
encoding to be xmlDeclaration()
written when
xmlDeclaration
Output:
is called. It does
not in uence the
<?xml version='1.0'?>
writer you are
using as output.
If
TemplateConfiguration#getDeclarationEncoding
is not null:
Output:
<?xml version='1.0' encoding='UTF-8'?>
expandEmptyElements false If true, empty Template:
tags are rendered
in their expanded p()
form.
Output:
If expandEmptyElements is true:
Output:
useDoubleQuotes false If true, use Template:
double quotes for
attributes instead tag(attr:'value')
of simple quotes
Output:
attr='value'
If useDoubleQuotes is true:
Output:
attr="value"
http://docs.groovy-lang.org/latest/html/documentation/ 372/502
1/6/2019 Groovy Language Documentation
Option Default value Description Example
newLineString System default (system property Allows to choose Template:
line.separator ) what string is
used when a new p('foo')
line is rendered newLine()
p('baz')
If newLineString='BAR' :
Output:
foo BAR baz
autoEscape false If true, variables See the auto escape section
from models are
automatically
escaped before
rendering.
autoIndent false If true, performs See the auto formatting section
automatic
indentation after
new lines
autoIndentString four (4) spaces The string to be See the auto formatting section
used as indent.
autoNewLine false If true, performs See the auto formatting section
automatic
insertion of new
lines
baseTemplateClass groovy.text.markup.BaseTemplate Sets the super See the custom templates section
class of compiled
templates. This
can be used to
provide
application
speci c
templates.
locale Default locale Sets the default See the internationalization section
locale for
templates.
Once the template engine has been created, it is unsafe to change the con guration.
Automatic formatting
By default, the template engine will render output without any speci c formatting. Some con guration options can improve the
situation:
autoIndent is responsible for auto-indenting after a new line is inserted
autoNewLine is responsible for automatically inserting new lines based on the original formatting of the template source
In general, it is recommended to set both autoIndent and autoNewLine to true if you want human-readable, pretty printed,
output:
http://docs.groovy-lang.org/latest/html/documentation/ 373/502
1/6/2019 Groovy Language Documentation
config.setAutoNewLine( );
config.setAutoIndent( );
Using the following template:
html {
head {
title('Title')
}
}
The output will now be:
Title
We can slightly change the template so that the title instruction is found on the same line as the head one:
html {
head { title('Title')
}
}
And the output will re ect that:
Title
New lines are only inserted where curly braces for tags are found, and the insertion corresponds to where the nested content is
found. This means that tags in the body of another tag will not trigger new lines unless they use curly braces themselves:
html {
head {
meta(attr:'value') 1
title('Title') 2
newLine() 3
meta(attr:'value2') 4
}
}
1 a new line is inserted because meta is not on the same line as head
2 no new line is inserted, because we’re on the same depth as the previous tag
3 we can force rendering of a new line by explicitly calling newLine
4 and this tag will be rendered on a separate line
This time, the output will be:
attr='value' Title
attr='value2'
http://docs.groovy-lang.org/latest/html/documentation/ 374/502
1/6/2019 By default, the renderer uses four(4) spaces as indent, butGroovy
you can change itDocumentation
Language by setting the
TemplateConfiguration#autoIndentString property.
Automatic escaping
By default, contents which is read from the model is rendered as is. If this contents comes from user input, it can be sensible, and
you might want to escape it by default, for example to avoid XSS injection. For that, the template con guration provides an option
which will automatically escape objects from the model, as long as they inherit from CharSequence (typically, `String`s).
Let’s imagine the following setup:
config.setAutoEscape( );
model = < , >();
model.put("unsafeContents", "I am an <html> hacker.");
and the following template:
html {
body {
div(unsafeContents)
}
}
Then you wouldn’t want the HTML from unsafeContents to be rendered as is, because of potential security issues:
I am an hacker.
Automatic escaping will x this:
config.setAutoEscape( );
And now the output is properly escaped:
I am an <html> hacker.
Note that using automatic escaping doesn’t prevent you from including unescaped contents from the model. To do this, your
template should then explicitly mention that a model variable should not be escaped by pre xing it with unescaped. , like in this
example:
Explicit bypass of automatic escaping
html {
body {
div(unescaped.unsafeContents)
}
}
Common gotchas
Strings containing markup
Say that you want to generate a <p> tag which contains a string containing markup:
p {
"This is a "
a(href:'target.html', "link")
" to another page"
}
and generates:
This is a href='target.html' link to another page
http://docs.groovy-lang.org/latest/html/documentation/ 375/502
1/6/2019 Can’t this be written shorter? A naive alternative would be:Groovy Language Documentation
p {
"This is a ${a(href:'target.html', "link")} to another page"
}
but the result will not look as expected:
href='target.html' link This is a to another page
The reason is that the markup template engine is a streaming engine. In the original version, the rst yield call generates a
string which is streamed to the output, then the a link is generated and streamed, and then the last yield call is streamed,
leading in an execution in order. But with the string version above, the order of execution is di erent:
the yield call requires an argument, a string
that arguments needs to be evaluated before the yield call is generated
so evaluating the string leads to an execution of the a(href:…) call before yield is itself called. This is not what you want to do.
Instead, you want to generate a string which contains markup, which is then passed to the yield call. This can be done this way:
p("This is a ${stringOf {a(href:'target.html', "link")}} to another page")
Note the stringOf call, which basically tells the markup template engine that the underlying markup needs to be rendered
separately and exported as a string. Note that for simple expressions, stringOf can be replaced by an alternate tag notation that
starts with a dollar sign:
p("This is a ${$a(href:'target.html', "link")} to another page")
It is worth noting that using stringOf or the special $tag notation triggers the creation of a distinct string writer
which is then used to render the markup. It is slower than using the version with calls to yield which perform
direct streaming of the markup instead.
Internationalization
The template engine has native support for internationalization. For that, when you create the TemplateConfiguration , you can
provide a Locale which is the default locale to be used for templates. Each template may have di erent versions, one for each
locale. The name of the template makes the di erence:
file.tpl : default template le
file_fr_FR.tpl : french version of the template
file_en_US.tpl : american english version of the template
When a template is rendered or included, then:
if the template name or include name explicitly sets a locale, the speci c version is included, or the default version if not found
if the template name doesn’t include a locale, the version for the TemplateConfiguration locale is used, or the default
version if not found
For example, imagine the default locale is set to Locale.ENGLISH and that the main template includes:
Use an explicit locale in include
include : 'locale_include_fr_FR.tpl'
then the template is rendered using the speci c template:
Bypass the template con guration
Texte en français
http://docs.groovy-lang.org/latest/html/documentation/ 376/502
1/6/2019 Using an include without specifying a locale will make the Groovy
template engine look
Language for a template with the con gured locale, and if
Documentation
not, fallback to the default, like here:
Don’t use a locale in include
include : 'locale_include.tpl'
Fallback to the default template
Default text
However, changing the default locale of the template engine to Locale.FRANCE will change the output, because the template
engine will now look for a le with the fr_FR locale:
Don’t fallback to the default template because a locale speci c template was found
Texte en français
This strategy lets you translate your templates one by one, by relying on default templates, for which no locale is set in the le
name.
Custom template classes
By default, templates created inherit the groovy.text.markup.BaseTemplate class. It may be interesting for an application to
provide a di erent template class, for example to provide additional helper methods which are aware of the application, or
customized rendering primitives (for HTML, for example).
The template engine provides this ability by setting an alternative baseTemplateClass in the TemplateConfiguration :
config.setBaseTemplateClass( . );
The custom base class has to extend BaseClass like in this example:
{
< > modules
(
templateEngine,
model,
< , > modelTypes,
configuration) {
(templateEngine, model, modelTypes, configuration)
}
< > getModules() {
modules
}
setModules( < > modules) {
.modules = modules
}
hasModule( name) {
modules?.any { it.name == name }
}
}
This example shows a class which provides an additional method named hasModule , which can then be used directly in the
template:
(hasModule('foo')) {
p 'Found module [foo]'
} {
p 'Module [foo] not found'
}
http://docs.groovy-lang.org/latest/html/documentation/ 377/502
1/6/2019 Type checked templates Groovy Language Documentation
Optional type checking
Even if templates are not type checked, they are statically compiled. This means that once the templates are compiled,
performance should be very good. For some applications, it might be good to make sure that templates are valid before they are
actually rendered. This means failing template compilation, for example, if a method on a model variable doesn’t exist.
The MarkupTemplateEngine provides such a facility. Templates can be optionally type checked. For that, the developer must
provide additional information at template creation time, which is the types of the variables found in the model. Imagine a model
exposing a list of pages, where a page is de ned as:
Page.groovy
id
title
body
}
Then a list of pages can be exposed in the model, like this:
p = ();
p.setTitle("Sample page");
p.setBody("Page body");
< > pages = <>();
pages.add(p);
model = < , >();
model.put("pages", pages);
A template can use it easily:
pages.each { page -> 1
p("Page title: $page.title") 2
p(page.text) 3
1 iterate on pages from the model
2 page.title is valid
3 page.text is not (should be page.body )
Without type checking, the compilation of the template succeeds, because the template engine doesn’t know about the model
until a page is actually rendered. This means that the problem would only surface at runtime, once the page is rendered:
Runtime error
No such property: text
In some situations, this can be complicated to sort out or even notice. By declaring the type of the pages to the template engine,
we’re now capable of failing at compile time:
modelTypes = < , >(); 1
modelTypes.put("pages", "List<Page>"); 2
= engine.createTypeCheckedModelTemplate("main.tpl", modelTypes) 3
1 create a map which will hold the model types
2 declare the type of the pages variables (note the use of a string for the type)
3 use createTypeCheckedModelTemplate instead of createTemplate
This time, when the template is compiled at the last line, an error occurs:
Template compilation time error
http://docs.groovy-lang.org/latest/html/documentation/ 378/502
1/6/2019 Groovy Language Documentation
[Static type checking] - No such property: text for class: Page
This means that you don’t need to wait for the page to be rendered to see an error. The use of
createTypeCheckedModelTemplate is mandatory.
Alternative declaration of types
Alternatively, if the developer is also the one who writes the templates, it is possible to declare the types of the expected variables
directly in the template. In this case, even if you call createTemplate , it will be type checked:
Inline declaration of types
modelTypes = { 1
< > pages 2
pages.each { page ->
p("Page title: $page.title")
p(page.text)
}
1 types need to be declared in the modelTypes header
2 declare one variable per object in the model
Performance of type checked templates
An additional interest of using type checked models is that performance should improve. By telling the type checker what are the
expected types, you also let the compiler generate optimized code for that, so if you are looking for the best performance,
consider using type checked templates.
3.12.8. Other solutions
Also, there are other templating solutions that can be used along with Groovy, such as FreeMarker (http://freemarker.org),
Velocity (http://velocity.apache.org), StringTemplate (http://stringtemplate.org) and others.
3.13. Servlet support
You can write (Java) Servlets in Groovy (called Groovlets).
There is also a GroovyServlet .
This feature will automatically compile your .groovy source les, turn them into bytecode, load the Class and cache it until you
change the source le.
Here’s a simple example to show you the kind of things you can do from a Groovlet.
Notice the use of implicit variables to access the session, output and request. Also notice that this is more like a script as it does
not have a class wrapper.
http://docs.groovy-lang.org/latest/html/documentation/ 379/502
1/6/2019 Groovy Language Documentation
(!session) {
session = request.getSession( )
}
(!session.counter) {
session.counter = 1
}
println """
<html>
<head>
<title>Groovy Servlet</title>
</head>
<body>
<p>
Hello, ${request.remoteHost}: ${session.counter}! ${new Date()}
</p>
</body>
</html>
"""
session.counter = session.counter + 1
Or, do the same thing using MarkupBuilder:
(!session) {
session = request.getSession( )
}
(!session.counter) {
session.counter = 1
}
html.html { // html is implicitly bound to new MarkupBuilder(out)
head {
title('Groovy Servlet')
}
body {
p("Hello, ${request.remoteHost}: ${session.counter}! ${new Date()}")
}
}
session.counter = session.counter + 1
3.13.1. Implicit variables
The following variables are ready for use in Groovlets:
variable name bound to note
request ServletRequest -
response ServletResponse -
context ServletContext -
application ServletContext -
session getSession(false) can be null! see <1>
params a Map object
http://docs.groovy-lang.org/latest/html/documentation/ 380/502
1/6/2019 Groovy Language Documentation
variable name bound to note
headers a Map object
out response.getWriter() see <2>
sout response.getOutputStream() see <2>
html new MarkupBuilder(out) see <2>
json new StreamingJsonBuilder(out) see <2>
1. The session variable is only set, if there was already a session object. See the if (session == null) checks in the examples
above.
2. These variables cannot be re-assigned inside a Groovlet . They are bound on rst access, allowing to e.g. calling methods on
the response object before using out .
3.13.2. Setting up groovylets
Add the following to your web.xml :
Groovy
groovy.servlet.GroovyServlet
Groovy
*.groovy
Then put the required groovy jar les into WEB-INF/lib .
Now put the .groovy les in, say, the root directory (i.e. where you would put your html les). The GroovyServlet takes care of
compiling the .groovy les.
So for example using tomcat you could edit tomcat/conf/server.xml like this:
path="/groovy" docBase="c:/groovy-servlet"
Then access it with http://localhost:8080/groovy/hello.groovy (http://localhost:8080/groovy/hello.groovy)
3.14. Integrating Groovy in a Java application
3.14.1. Groovy integration mechanisms
The Groovy language proposes several ways to integrate itself into applications (Java or even Groovy) at runtime, from the most
basic, simple code execution to the most complete, integrating caching and compiler customization.
All the examples written in this section are using Groovy, but the same integration mechanisms can be used from
Java.
Eval
The groovy.util.Eval class is the simplest way to execute Groovy dynamically at runtime. This can be done by calling the me
method:
http://docs.groovy-lang.org/latest/html/documentation/ 381/502
1/6/2019 Groovy Language Documentation
groovy.util.
.me('33*3') == 99
.me('"foo".toUpperCase()') == 'FOO'
Eval supports multiple variants that accept parameters for simple evaluation:
.x(4, '2*x') == 8 1
.me('k', 4, '2*k') == 8 2
.xy(4, 5, 'x*y') == 20 3
.xyz(4, 5, 6, 'x*y+z') == 26 4
1 Simple evaluation with one bound parameter named x
2 Same evaluation, with a custom bound parameter named k
3 Simple evaluation with two bound parameters named x and y
4 Simple evaluation with three bound parameters named x , y and z
The Eval class makes it very easy to evaluate simple scripts, but doesn’t scale: there is no caching of the script, and it isn’t meant
to evaluate more than one liners.
GroovyShell
Multiple sources
The groovy.lang.GroovyShell class is the preferred way to evaluate scripts with the ability to cache the resulting script
instance. Although the Eval class returns the result of the execution of the compiled script, the GroovyShell class o ers more
options.
shell = () 1
result = shell.evaluate '3*5' 2
result2 = shell.evaluate( ('3*5')) 3
result == result2
script = shell.parse '3*5' 4
script groovy.lang.
script.run() == 15 5
1 create a new GroovyShell instance
2 can be used as Eval with direct execution of the code
3 can read from multiple sources ( String , Reader , File , InputStream )
4 can defer execution of the script. parse returns a Script instance
5 Script de nes a run method
Sharing data between a script and the application
It is possible to share data between the application and the script using a groovy.lang.Binding :
sharedData = () 1
shell = (sharedData) 2
now = ()
sharedData.setProperty('text', 'I am shared data!') 3
sharedData.setProperty('date', now) 4
result = shell.evaluate('"At $date, $text"') 5
result == "At $now, I am shared data!"
1 create a new Binding that will contain shared data
2 create a GroovyShell using this shared data
3 add a string to the binding
4 add a date to the binding (you are not limited to simple types)
http://docs.groovy-lang.org/latest/html/documentation/ 382/502
1/6/2019 5 evaluate the script Groovy Language Documentation
Note that it is also possible to write from the script into the binding:
sharedData = () 1
shell = (sharedData) 2
shell.evaluate('foo=123') 3
sharedData.getProperty('foo') == 123 4
1 create a new Binding instance
2 create a new GroovyShell using that shared data
3 use an undeclared variable to store the result into the binding
4 read the result from the caller
It is important to understand that you need to use an undeclared variable if you want to write into the binding. Using def or an
explicit type like in the example below would fail because you would then create a local variable:
sharedData = ()
shell = (sharedData)
shell.evaluate('int foo=123')
{
sharedData.getProperty('foo')
} ( e) {
println "foo is defined as a local variable"
}
You must be very careful when using shared data in a multithreaded environment. The Binding instance that
you pass to GroovyShell is not thread safe, and shared by all scripts.
It is possible to work around the shared instance of Binding by leveraging the Script instance which is returned by parse :
shell = ()
b1 = (x:3) 1
b2 = (x:4) 2
script = shell.parse('x = 2*x')
script.binding = b1
script.run()
script.binding = b2
script.run()
b1.getProperty('x') == 6
b2.getProperty('x') == 8
b1 != b2
1 will store the x variable inside b1
2 will store the x variable inside b2
However, you must be aware that you are still sharing the same instance of a script. So this technique cannot be used if you have
two threads working on the same script. In that case, you must make sure of creating two distinct script instances:
http://docs.groovy-lang.org/latest/html/documentation/ 383/502
1/6/2019 Groovy Language Documentation
shell = ()
b1 = (x:3)
b2 = (x:4)
script1 = shell.parse('x = 2*x') 1
script2 = shell.parse('x = 2*x') 2
script1 != script2
script1.binding = b1 3
script2.binding = b2 4
t1 = .start { script1.run() } 5
t2 = .start { script2.run() } 6
[t1,t2]*.join() 7
b1.getProperty('x') == 6
b2.getProperty('x') == 8
b1 != b2
1 create an instance of script for thread 1
2 create an instance of script for thread 2
3 assign rst binding to script 1
4 assign second binding to script 2
5 start rst script in a separate thread
6 start second script in a separate thread
7 wait for completion
In case you need thread safety like here, it is more advisable to use the GroovyClassLoader directly instead.
Custom script class
We have seen that the parse method returns an instance of groovy.lang.Script , but it is possible to use a custom class, given
that it extends Script itself. It can be used to provide additional behavior to the script like in the example below:
{
name
greet() {
"Hello, $name!"
}
}
The custom class de nes a property called name and a new method called greet . This class can be used as the script base class
by using a custom con guration:
org.codehaus.groovy.control.
config = () 1
config.scriptBaseClass = 'MyScript' 2
shell = ( . .classLoader, (), config) 3
script = shell.parse('greet()') 4
script
script.setName('Michel')
script.run() == 'Hello, Michel!'
1 create a CompilerConfiguration instance
2 instruct it to use MyScript as the base class for scripts
3 then use the compiler con guration when you create the shell
4 the script now has access to the new method greet
You are not limited to the sole scriptBaseClass con guration. You can use any of the compiler con guration
tweaks, including the compilation customizers.
http://docs.groovy-lang.org/latest/html/documentation/ 384/502
1/6/2019 GroovyClassLoader Groovy Language Documentation
In the previous section, we have shown that GroovyShell was an easy tool to execute scripts, but it makes it complicated to
compile anything but scripts. Internally, it makes use of the groovy.lang.GroovyClassLoader , which is at the heart of the
compilation and loading of classes at runtime.
By leveraging the GroovyClassLoader instead of GroovyShell , you will be able to load classes, instead of instances of scripts:
groovy.lang.
gcl = () 1
clazz = gcl.parseClass('class Foo { void doIt() { println "ok" } }') 2
clazz.name == 'Foo' 3
o = clazz.newInstance() 4
o.doIt() 5
1 create a new GroovyClassLoader
2 parseClass will return an instance of Class
3 you can check that the class which is returns is really the one de ned in the script
4 and you can create a new instance of the class, which is not a script
5 then call any method on it
A GroovyClassLoader keeps a reference of all the classes it created, so it is easy to create a memory leak. In
particular, if you execute the same script twice, if it is a String, then you obtain two distinct classes!
groovy.lang.
gcl = ()
clazz1 = gcl.parseClass('class Foo { }') 1
clazz2 = gcl.parseClass('class Foo { }') 2
clazz1.name == 'Foo' 3
clazz2.name == 'Foo'
clazz1 != clazz2 4
1 dynamically create a class named "Foo"
2 create an identical looking class, using a separate parseClass call
3 make sure both classes have the same name
4 but they are actually di erent!
The reason is that a GroovyClassLoader doesn’t keep track of the source text. If you want to have the same instance, then the
source must be a le, like in this example:
gcl = ()
clazz1 = gcl.parseClass(file) 1
clazz2 = gcl.parseClass( (file.absolutePath)) 2
clazz1.name == 'Foo' 3
clazz2.name == 'Foo'
clazz1 == clazz2 4
1 parse a class from a File
2 parse a class from a distinct le instance, but pointing to the same physical le
3 make sure our classes have the same name
4 but now, they are the same instance
Using a File as input, the GroovyClassLoader is capable of caching the generated class le, which avoids creating multiple
classes at runtime for the same source.
GroovyScriptEngine
http://docs.groovy-lang.org/latest/html/documentation/ 385/502
1/6/2019 The groovy.util.GroovyScriptEngine class provides aGroovy
exibleLanguage
foundation for applications which rely on script reloading and
Documentation
script dependencies. While GroovyShell focuses on standalone Script`s and `GroovyClassLoader handles dynamic
compilation and loading of any Groovy class, the GroovyScriptEngine will add a layer on top of GroovyClassLoader to handle
both script dependencies and reloading.
To illustrate this, we will create a script engine and execute code in an in nite loop. First of all, you need to create a directory with
the following script inside:
ReloadingTest.groovy
{
sayHello() {
greet = "Hello, world!"
greet
}
}
()
then you can execute this code using a GroovyScriptEngine :
binding = ()
engine = ([tmpDir.toURI().toURL()] URL[]) 1
( ) {
greeter = engine.run('ReloadingTest.groovy', binding) 2
println greeter.sayHello() 3
.sleep(1000)
}
1 create a script engine which will look for sources into our source directory
2 execute the script, which will return an instance of Greeter
3 print the greeting message
At this point, you should see a message printed every second:
Hello, world!
Hello, world!
...
Without interrupting the script execution, now replace the contents of the ReloadingTest le with:
ReloadingTest.groovy
{
sayHello() {
greet = "Hello, Groovy!"
greet
}
}
()
And the message should change to:
Hello, world!
...
Hello, Groovy!
Hello, Groovy!
...
But it is also possible to have a dependency on another script. To illustrate this, create the following le into the same directory,
without interrupting the executing script:
http://docs.groovy-lang.org/latest/html/documentation/ 386/502
1/6/2019 Depencency.groovy Groovy Language Documentation
{
message = 'Hello, dependency 1'
}
and update the ReloadingTest script like this:
ReloadingTest.groovy
{
sayHello() {
greet = ().message
greet
}
}
()
And this time, the message should change to:
Hello, Groovy!
...
Hello, dependency 1!
Hello, dependency 1!
...
And as a last test, you can update the Dependency.groovy le without touching the ReloadingTest le:
Depencency.groovy
{
message = 'Hello, dependency 2'
}
And you should observe that the dependent le was reloaded:
Hello, dependency 1!
...
Hello, dependency 2!
Hello, dependency 2!
CompilationUnit
Ultimately, it is possible to perform more operations during compilation by relying directly on the
org.codehaus.groovy.control.CompilationUnit class. This class is responsible for determining the various steps of
compilation and would let you introduce new steps or even stop compilation at various phases. This is for example how stub
generation is done, for the joint compiler.
However, overriding CompilationUnit is not recommended and should only be done if no other standard solution works.
3.14.2. Bean Scripting Framework
The Bean Scripting Framework (http://commons.apache.org/proper/commons-bsf/) is an attempt to create an API
to allow calling scripting languages from Java. It hasn’t been updated for long and abandoned in favor of the
standard JSR-223 API.
The BSF engine for Groovy is implemented by the org.codehaus.groovy.bsf.GroovyEngine class. However, that fact is
normally hidden away by the BSF APIs. You just treat Groovy like any of the other scripting languages via the BSF API.
http://docs.groovy-lang.org/latest/html/documentation/ 387/502
1/6/2019 Groovy Language Documentation
Since Groovy has its own native support for integration with Java, you only need to worry about BSF if you also
want to also be able to call other languages, e.g. JRuby (https://www.jruby.org/) or if you want to remain very
loosely coupled from your scripting language.
Getting started
Provided you have Groovy and BSF jars in your classpath, you can use the following Java code to run a sample Groovy script:
myScript = "println('Hello World')\n return [1, 2, 3]";
manager = ();
answer = ( ) manager.eval("groovy", "myScript.groovy", 0, 0, myScript);
assertEquals(3, answer.size());
Passing in variables
BSF lets you pass beans between Java and your scripting language. You can register/unregister beans which makes them known to
BSF. You can then use BSF methods to lookup beans as required. Alternatively, you can declare/undeclare beans. This will register
them but also make them available for use directly in your scripting language. This second approach is the normal approach used
with Groovy. Here is an example:
manager = ();
manager.declareBean("xyz", 4, . );
answer = manager.eval("groovy", "test.groovy", 0, 0, "xyz + 1");
assertEquals(5, answer);
Other calling options
The previous examples used the eval method. BSF makes multiple methods available for your use (see the BSF documentation
(http://commons.apache.org/proper/commons-bsf/manual.html) for more details). One of the other available methods is apply. It
allows you to de ne an anonymous function in your scripting language and apply that function to arguments. Groovy supports
this function using closures. Here is an example:
manager = ();
< > ignoreParamNames = ;
< > args = < >();
args.add(2);
args.add(5);
args.add(1);
actual = ( ) manager.apply("groovy", "applyTest", 0, 0,
"def summer = { a, b, c -> a * 100 + b * 10 + c }", ignoreParamNames, args);
assertEquals(251, actual.intValue());
Access to the scripting engine
Although you don’t normally need it, BSF does provide a hook that lets you get directly to the scripting engine. One of the
functions which the engine can perform is to invoke a single method call on an object. Here is an example:
manager = ();
bsfEngine = manager.loadScriptingEngine("groovy");
manager.declareBean("myvar", "hello", . );
myvar = manager.lookupBean("myvar");
result = ( ) bsfEngine.call(myvar, "reverse", [0]);
assertEquals("olleh", result);
3.14.3. JSR 223 javax.script API
JSR-223 is a standard API for calling scripting frameworks in Java. It is available since Java 6 and aims at providing a
common framework for calling multiple languages from Java. Groovy provides its own richer integration
mechanisms, and if you don’t plan to use multiple languages in the same application, it is recommended that you
use the Groovy integration mechanisms instead of the limited JSR-223 API.
Here is how you need to initialize the JSR-223 engine to talk to Groovy from Java:
http://docs.groovy-lang.org/latest/html/documentation/ 388/502
1/6/2019 Groovy Language Documentation
javax.script. ;
javax.script. ;
javax.script. ;
...
factory = ();
engine = factory.getEngineByName("groovy");
Then you can execute Groovy scripts easily:
sum = ( ) engine.eval("(1..10).sum()");
assertEquals( (55), sum);
It is also possible to share variables:
engine.put("first", "HELLO");
engine.put("second", "world");
result = ( ) engine.eval("first.toLowerCase() + ' ' + second.toUpperCase()");
assertEquals("hello WORLD", result);
This next example illustrates calling an invokable function:
javax.script. ;
...
factory = ();
engine = factory.getEngineByName("groovy");
fact = "def factorial(n) { n == 1 ? 1 : n * factorial(n - 1) }";
engine.eval(fact);
inv = ( ) engine;
[] params = {5};
result = inv.invokeFunction("factorial", params);
assertEquals( (120), result);
The engine keeps per default hard references to the script functions. To change this you should set a engine level scoped attribute
to the script context of the name #jsr223.groovy.engine.keep.globals with a String being phantom to use phantom
references, weak to use weak references or soft to use soft references - casing is ignored. Any other string will cause the use of
hard references.
3.15. Domain-Speci c Languages
3.15.1. Command chains
Groovy lets you omit parentheses around the arguments of a method call for top-level statements. "command chain" feature
extends this by allowing us to chain such parentheses-free method calls, requiring neither parentheses around arguments, nor
dots between the chained calls. The general idea is that a call like a b c d will actually be equivalent to a(b).c(d) . This also
works with multiple arguments, closure arguments, and even named arguments. Furthermore, such command chains can also
appear on the right-hand side of assignments. Let’s have a look at some examples supported by this new syntax:
// equivalent to: turn(left).then(right)
turn left right
// equivalent to: take(2.pills).of(chloroquinine).after(6.hours)
take 2.pills of chloroquinine after 6.hours
// equivalent to: paint(wall).with(red, green).and(yellow)
paint wall red, green yellow
// with named parameters too
// equivalent to: check(that: margarita).tastes(good)
check that: margarita tastes good
// with closures as parameters
// equivalent to: given({}).when({}).then({})
given { } { } { }
http://docs.groovy-lang.org/latest/html/documentation/ 389/502
1/6/2019 It is also possible to use methods in the chain which take no arguments,
Groovy butDocumentation
Language in that case, the parentheses are needed:
// equivalent to: select(all).unique().from(names)
all unique() names
If your command chain contains an odd number of elements, the chain will be composed of method / arguments, and will nish
by a nal property access:
// equivalent to: take(3).cookies
// and also this: take(3).getCookies()
take 3 cookies
This command chain approach opens up interesting possibilities in terms of the much wider range of DSLs which can now be
written in Groovy.
The above examples illustrate using a command chain based DSL but not how to create one. There are various strategies that you
can use, but to illustrate creating such a DSL, we will show a couple of examples - rst using maps and Closures:
show = { println it }
square_root = { .sqrt(it) }
please(action) {
[the: { what ->
[of: { n -> action(what(n)) }]
}]
}
// equivalent to: please(show).the(square_root).of(100)
please show the square_root of 100
// ==> 10.0
As a second example, consider how you might write a DSL for simplifying one of your existing APIs. Maybe you need to put this
code in front of customers, business analysts or testers who might be not hard-core Java developers. We’ll use the Splitter
from the Google Guava libraries (https://github.com/google/guava) project as it already has a nice Fluent API. Here is how we
might use it out of the box:
@Grab('com.google.guava:guava:r09')
com.google.common. .*
result = .on(',').trimResults( . ('_' )).split("_a ,_b_
,c__").iterator().toList()
It reads fairly well for a Java developer but if that is not your target audience or you have many such statements to write, it could
be considered a little verbose. Again, there are many options for writing a DSL. We’ll keep it simple with Maps and Closures. We’ll
rst write a helper method:
@Grab('com.google.guava:guava:r09')
com.google.common. .*
split( ) {
[on: { sep ->
[trimming: { trimChar ->
.on(sep).trimResults( . (trimChar
)).split( ).iterator().toList()
}]
}]
}
now instead of this line from our original example:
result = .on(',').trimResults( . ('_' )).split("_a ,_b_
,c__").iterator().toList()
we can write this:
http://docs.groovy-lang.org/latest/html/documentation/ 390/502
1/6/2019 Groovy Language Documentation
result = split "_a ,_b_ ,c__" on ',' trimming '_\'
3.15.2. Operator overloading
Various operators in Groovy are mapped onto regular method calls on objects.
This allows you to provide your own Java or Groovy objects which can take advantage of operator overloading. The following table
describes the operators supported in Groovy and the methods they map to.
Operator Method
a + b a.plus(b)
a - b a.minus(b)
a * b a.multiply(b)
a ** b a.power(b)
a / b a.div(b)
a % b a.mod(b)
a | b a.or(b)
a & b a.and(b)
a ^ b a.xor(b)
a++ or ++a a.next()
a-- or --a a.previous()
a[b] a.getAt(b)
a[b] = c a.putAt(b, c)
a << b a.leftShift(b)
a >> b a.rightShift(b)
a >>> b a.rightShiftUnsigned(b)
switch(a) { case(b) : } b.isCase(a)
if(a) a.asBoolean()
~a a.bitwiseNegate()
-a a.negative()
+a a.positive()
a as b a.asType(b)
a == b a.equals(b)
a != b ! a.equals(b)
a <=> b a.compareTo(b)
a > b a.compareTo(b) > 0
a >= b a.compareTo(b) >= 0
a < b a.compareTo(b) < 0
http://docs.groovy-lang.org/latest/html/documentation/ 391/502
1/6/2019 Groovy Language Documentation
Operator Method
a <= b a.compareTo(b) <= 0
3.15.3. Script base classes
The Script class
Groovy scripts are always compiled to classes. For example, a script as simple as:
println 'Hello from Groovy'
is compiled to a class extending the abstract groovy.lang.Script (http://docs.groovy-lang.org/2.5.5/html/gapi/index.html?
groovy/lang/Script.html) class. This class contains a single abstract method called run. When a script is compiled, then its body will
become the run method, while the other methods found in the script are found in the implementing class. The Script class
provides base support for integration with your application through the Binding object, as illustrated in this example:
binding = () 1
shell = (binding) 2
binding.setVariable('x',1) 3
binding.setVariable('y',3)
shell.evaluate 'z=2*x+y' 4
binding.getVariable('z') == 5 5
1 a binding is used to share data between the script and the calling class
2 a GroovyShell can be used with this binding
3 input variables are set from the calling class inside the binding
4 then the script is evaluated
5 and the z variable has been "exported" into the binding
This is a very practical way to share data between the caller and the script, however it may be insu cient or not practical in some
cases. For that purpose, Groovy allows you to set your own base script class. A base script class has to extend groovy.lang.Script
(http://docs.groovy-lang.org/2.5.5/html/gapi/index.html?groovy/lang/Script.html) and be a single abstract method type:
{
name
greet() { println "Hello, $name!" }
}
Then the custom script base class can be declared in the compiler con guration, for example:
config = () 1
config.scriptBaseClass = 'MyBaseClass' 2
shell = ( . .classLoader, config) 3
shell.evaluate """
setName 'Judith' 4
greet()
"""
1 create a custom compiler con guration
2 set the base script class to our custom base script class
3 then create a GroovyShell using that con guration
4 the script will then extend the base script class, giving direct access to the name property and greet method
The @BaseScript annotation
As an alternative, it is also possible to use the @BaseScript annotation directly into a script:
http://docs.groovy-lang.org/latest/html/documentation/ 392/502
1/6/2019 Groovy Language Documentation
groovy.transform.
@BaseScript baseScript
setName 'Judith'
greet()
where @BaseScript should annotate a variable which type is the class of the base script. Alternatively, you can set the base script
class as a member of the @BaseScript annotation itself:
@BaseScript( )
groovy.transform.
setName 'Judith'
greet()
Alternate abstract method
We have seen that the base script class is a single abstract method type that needs to implement the run method. The run
method is executed by the script engine automatically. In some circumstances it may be interesting to have a base class which
implements the run method, but provides an alternative abstract method to be used for the script body. For example, the base
script run method might perform some initialization before the run method is executed. This is possible by doing this:
{
count
scriptBody() 1
run() {
count++ 2
scriptBody() 3
count 4
}
}
1 the base script class should de ne one (and only one) abstract method
2 the run method can be overridden and perform a task before executing the script body
3 run calls the abstract scriptBody method which will delegate to the user script
4 then it can return something else than the value from the script
If you execute this code:
result = shell.evaluate """
println 'Ok'
"""
result == 1
Then you will see that the script is executed, but the result of the evaluation is 1 as returned by the run method of the base
class. It is even clearer if you use parse instead of evaluate , because it would allow you to execute the run method several
times on the same script instance:
script = shell.parse("println 'Ok'")
script.run() == 1
script.run() == 2
3.15.4. Adding properties to numbers
In Groovy number types are considered equal to any other types. As such, it is possible to enhance numbers by adding properties
or methods to them. This can be very handy when dealing with measurable quantities for example. Details about how existing
classes can be enhanced in Groovy are found in the extension modules (core-metaprogramming.html#_extension_modules)
section or the categories (core-metaprogramming.html#categories) section.
An illustration of this can be found in Groovy using the TimeCategory :
http://docs.groovy-lang.org/latest/html/documentation/ 393/502
1/6/2019 Groovy Language Documentation
( ) {
println 1.minute. .now 1
println 10.hours.ago
someDate = () 2
println someDate - 3.months
}
1 using the TimeCategory , a property minute is added to the Integer class
2 similarily, the months method returns a groovy.time.DatumDependentDuration which can be used in calculus
Categories are lexically bound, making them a great t for internal DSLs.
3.15.5. @DelegatesTo
Explaining delegation strategy at compile time
@groovy.lang.DelegatesTo is a documentation and compile-time annotation aimed at:
documenting APIs that use closures as arguments
providing type information for the static type checker and compiler
The Groovy language is a platform of choice for building DSLs. Using closures, it’s quite easy to create custom control structures,
as well as it is simple to create builders. Imagine that you have the following code:
email {
'[email protected]'
to '[email protected]'
subject 'The pope has resigned!'
body {
p 'Really, the pope has resigned!'
}
}
One way of implementing this is using the builder strategy, which implies a method, named email which accepts a closure as an
argument. The method may delegate subsequent calls to an object that implements the from , to , subject and body methods.
Again, body is a method which accepts a closure as an argument and that uses the builder strategy.
Implementing such a builder is usually done the following way:
email( cl) {
email = ()
code = cl.rehydrate(email, , )
code.resolveStrategy = .DELEGATE_ONLY
code()
}
the EmailSpec class implements the from , to , … methods. By calling rehydrate , we’re creating a copy of the closure for which
we set the delegate , owner and thisObject values. Setting the owner and the this object is not very important here since
we will use the DELEGATE_ONLY strategy which says that the method calls will be resolved only against the delegate of the closure.
{
( ) { println "From: $from"}
to( ... to) { println "To: $to"}
subject( subject) { println "Subject: $subject"}
body( body) {
bodySpec = ()
code = body.rehydrate(bodySpec, , )
code.resolveStrategy = .DELEGATE_ONLY
code()
}
}
http://docs.groovy-lang.org/latest/html/documentation/ 394/502
1/6/2019 The EmailSpec class has itself a body method acceptingGroovy
a closure that is cloned
Language and executed. This is what we call the builder
Documentation
pattern in Groovy.
One of the problems with the code that we’ve shown is that the user of the email method doesn’t have any information about
the methods that he’s allowed to call inside the closure. The only possible information is from the method documentation. There
are two issues with this: rst of all, documentation is not always written, and if it is, it’s not always available (javadoc not
downloaded, for example). Second, it doesn’t help IDEs. What would be really interesting, here, is for IDEs to help the developer by
suggesting, once they are in the closure body, methods that exist on the email class.
Moreover, if the user calls a method in the closure which is not de ned by the EmailSpec class, the IDE should at least issue a
warning (because it’s very likely that it will break at runtime).
One more problem with the code above is that it is not compatible with static type checking. Type checking would let the user
know if a method call is authorized at compile time instead of runtime, but if you try to perform type checking on this code:
email {
'[email protected]'
to '[email protected]'
subject 'The pope has resigned!'
body {
p 'Really, the pope has resigned!'
}
}
Then the type checker will know that there’s an email method accepting a Closure , but it will complain for every method
call inside the closure, because from , for example, is not a method which is de ned in the class. Indeed, it’s de ned in
the EmailSpec class and it has absolutely no hint to help it knowing that the closure delegate will, at runtime, be of
type EmailSpec :
@groovy.transform.
sendEmail() {
email {
'[email protected]'
to '[email protected]'
subject 'The pope has resigned!'
body {
p 'Really, the pope has resigned!'
}
}
}
will fail compilation with errors like this one:
[Static type checking] - Cannot find matching method MyScript#from(java.lang.String). Please check
if the declared type is right and if the method exists.
@ line 31, column 21.
from '[email protected]'
@DelegatesTo
For those reasons, Groovy 2.1 introduced a new annotation named @DelegatesTo . The goal of this annotation is to solve both
the documentation issue, that will let your IDE know about the expected methods in the closure body, and it will also solve the
type checking issue, by giving hints to the compiler about what are the potential receivers of method calls in the closure body.
The idea is to annotate the Closure parameter of the email method:
email(@DelegatesTo( ) cl) {
email = ()
code = cl.rehydrate(email, , )
code.resolveStrategy = .DELEGATE_ONLY
code()
}
http://docs.groovy-lang.org/latest/html/documentation/ 395/502
1/6/2019 What we’ve done here is telling the compiler (or the IDE) that when
Groovy the method
Language will be called with a closure, the delegate of this
Documentation
closure will be set to an object of type email . But there is still a problem: the default delegation strategy is not the one which is
used in our method. So we will give more information and tell the compiler (or the IDE) that the delegation strategy is also
changed:
email(@DelegatesTo(strategy= .DELEGATE_ONLY, value= ) cl) {
email = ()
code = cl.rehydrate(email, , )
code.resolveStrategy = .DELEGATE_ONLY
code()
}
Now, both the IDE and the type checker (if you are using @TypeChecked ) will be aware of the delegate and the delegation
strategy. This is very nice because it will both allow the IDE to provide smart completion, but it will also remove errors at compile
time that exist only because the behaviour of the program is normally only known at runtime!
The following code will now pass compilation:
@TypeChecked
doEmail() {
email {
'[email protected]'
to '[email protected]'
subject 'The pope has resigned!'
body {
p 'Really, the pope has resigned!'
}
}
}
DelegatesTo modes
@DelegatesTo supports multiple modes that we will describe with examples in this section.
Simple delegation
In this mode, the only mandatory parameter is the value which says to which class we delegate calls. Nothing more. We’re telling
the compiler that the type of the delegate will always be of the type documented by @DelegatesTo (note that it can be a
subclass, but if it is, the methods de ned by the subclass will not be visible to the type checker).
body(@DelegatesTo( ) cl) {
// ...
}
Delegation strategy
In this mode, you must specify both the delegate class and a delegation strategy. This must be used if the closure will not be called
with the default delegation strategy, which is Closure.OWNER_FIRST .
body(@DelegatesTo(strategy= .DELEGATE_ONLY, value= ) cl) {
// ...
}
Delegate to parameter
In this variant, we will tell the compiler that we are delegating to another parameter of the method. Take the following code:
( target, code) {
clone = code.rehydrate(target, , )
clone()
}
Here, the delegate which will be used is not created inside the exec method. In fact, we take an argument of the method and
delegate to it. Usage may look like this:
http://docs.groovy-lang.org/latest/html/documentation/ 396/502
1/6/2019 Groovy Language Documentation
email = ()
(email) {
'...'
to '...'
send()
}
Each of the method calls are delegated to the email parameter. This is a widely used pattern which is also supported
by @DelegatesTo using a companion annotation:
(@DelegatesTo. target, @DelegatesTo code) {
clone = code.rehydrate(target, , )
clone()
}
A closure is annotated with @DelegatesTo , but this time, without specifying any class. Instead, we’re annotating another
parameter with @DelegatesTo.Target . The type of the delegate is then determined at compile time. One could think that we are
using the parameter type, which in this case is Object but this is not true. Take this code:
{
sayHello() { println 'Hello' }
}
greeter = ()
(greeter) {
sayHello()
}
Remember that this works out of the box without having to annotate with @DelegatesTo . However, to make the IDE aware of
the delegate type, or the type checker aware of it, we need to add @DelegatesTo . And in this case, it will know that the Greeter
variable is of type Greeter , so it will not report errors on the sayHello method even if the exec method doesn’t explicitly de ne
the target as of type Greeter. This is a very powerful feature, because it prevents you from writing multiple versions of the
same exec method for di erent receiver types!
In this mode, the @DelegatesTo annotation also supports the strategy parameter that we’ve described upper.
Multiple closures
In the previous example, the exec method accepted only one closure, but you may have methods that take multiple closures:
fooBarBaz( foo, bar, baz) {
...
}
Then nothing prevents you from annotating each closure with @DelegatesTo :
{ foo( msg) { println "Foo ${msg}!" } }
{ bar( x) { println "Bar ${x}!" } }
{ baz( d) { println "Baz ${d}!" } }
fooBarBaz(@DelegatesTo( ) foo, @DelegatesTo( ) bar, @DelegatesTo( )
baz) {
...
}
But more importantly, if you have multiple closures and multiple arguments, you can use several targets:
http://docs.groovy-lang.org/latest/html/documentation/ 397/502
1/6/2019 Groovy Language Documentation
fooBarBaz(
@DelegatesTo. ('foo') foo,
@DelegatesTo. ('bar') bar,
@DelegatesTo. ('baz') baz,
@DelegatesTo(target='foo') cl1,
@DelegatesTo(target='bar') cl2,
@DelegatesTo(target='baz') cl3) {
cl1.rehydrate(foo, , ).call()
cl2.rehydrate(bar, , ).call()
cl3.rehydrate(baz, , ).call()
}
a = ()
b = ()
c = ()
fooBarBaz(
a, b, c,
{ foo('Hello') },
{ bar(123) },
{ baz( ()) }
)
At this point, you may wonder why we don’t use the parameter names as references. The reason is that the
information (the parameter name) is not always available (it’s a debug-only information), so it’s a limitation of the
JVM.
Delegating to a generic type
In some situations, it is interesting to instruct the IDE or the compiler that the delegate type will not be a parameter but a generic
type. Imagine a con gurator that runs on a list of elements:
<T> configure( <T> elements, configuration) {
elements.each { e->
clone = configuration.rehydrate(e, , )
clone.resolveStrategy = .DELEGATE_FIRST
clone.call()
}
}
Then this method can be called with any list like this:
@groovy.transform.
{
name
}
< > list = []
3.times { list << () }
configure(list) {
name = 'My Realm'
}
list.every { it.name == 'My Realm' }
To let the type checker and the IDE know that the configure method calls the closure on each element of the list, you need to
use @DelegatesTo di erently:
<T> configure(
@DelegatesTo. <T> elements,
@DelegatesTo(strategy= .DELEGATE_FIRST, genericTypeIndex=0) configuration) {
clone = configuration.rehydrate(e, , )
clone.resolveStrategy = .DELEGATE_FIRST
clone.call()
}
http://docs.groovy-lang.org/latest/html/documentation/ 398/502
1/6/2019 @DelegatesTo takes an optional genericTypeIndex argument that tells what
Groovy Language is the index of the generic type that will be used
Documentation
as the delegate type. This must be used in conjunction with @DelegatesTo.Target and the index starts at 0. In the example
above, that means that the delegate type is resolved against List<T> , and since the generic type at index 0 is T and inferred as
a Realm , the type checker infers that the delegate type will be of type Realm .
We’re using a genericTypeIndex instead of a placeholder ( T ) because of JVM limitations.
Delegating to an arbitrary type
It is possible that none of the options above can represent the type you want to delegate to. For example, let’s de ne a mapper
class which is parametrized with an object and de nes a map method which returns an object of another type:
<T,U> { 1
T value 2
(T value) { .value = value }
U map( <U> producer) { 3
producer. = value
producer()
}
}
1 The mapper class takes two generic type arguments: the source type and the target type
2 The source object is stored in a nal eld
3 The map method asks to convert the source object to a target object
As you can see, the method signature from map does not give any information about what object will be manipulated by the
closure. Reading the method body, we know that it will be the value which is of type T , but T is not found in the method
signature, so we are facing a case where none of the available options for @DelegatesTo is suitable. For example, if we try to
statically compile this code:
mapper = < , >('Hello')
mapper.map { length() } == 5
Then the compiler will fail with:
Static type checking] - Cannot find matching method TestScript0#length()
In that case, you can use the type member of the @DelegatesTo annotation to reference T as a type token:
<T,U> {
T value
(T value) { .value = value }
U map(@DelegatesTo(type="T") <U> producer) { 1
producer. = value
producer()
}
}
1 The @DelegatesTo annotation references a generic type which is not found in the method signature
Note that you are not limited to generic type tokens. The type member can be used to represent complex types, such as
List<T> or Map<T,List<U>> . The reason why you should use that in last resort is that the type is only checked when the type
checker nds usage of @DelegatesTo , not when the annotated method itself is compiled. This means that type safety is only
ensured at the call site. Additionally, compilation will be slower (though probably unnoticeable for most cases).
3.15.6. Compilation customizers
Introduction
Whether you are using groovyc to compile classes or a GroovyShell , for example, to execute scripts, under the hood, a
compiler con guration is used. This con guration holds information like the source encoding or the classpath but it can also be
used to perform more operations like adding imports by default, applying AST transformations transparently or disabling global
http://docs.groovy-lang.org/latest/html/documentation/ 399/502
1/6/2019 AST transformations. Groovy Language Documentation
The goal of compilation customizers is to make those common tasks easy to implement. For that, the CompilerConfiguration
class is the entry point. The general schema will always be based on the following code:
org.codehaus.groovy.control.
// create a configuration
config = ()
// tweak the configuration
config.addCompilationCustomizers(...)
// run your script
shell = (config)
shell.evaluate(script)
Compilation customizers must extend the org.codehaus.groovy.control.customizers.CompilationCustomizer class. A customizer
works:
on a speci c compilation phase
on every class node being compiled
You can implement your own compilation customizer but Groovy includes some of the most common operations.
Import customizer
Using this compilation customizer, your code will have imports added transparently. This is in particular useful for scripts
implementing a DSL where you want to avoid users from having to write imports. The import customizer will let you add all the
variants of imports the Groovy language allows, that is:
class imports, optionally aliased
star imports
static imports, optionally aliased
static star imports
org.codehaus.groovy.control.customizers.
icz = ()
// "normal" import
icz.addImports('java.util.concurrent.atomic.AtomicInteger',
'java.util.concurrent.ConcurrentHashMap')
// "aliases" import
icz.addImport('CHM', 'java.util.concurrent.ConcurrentHashMap')
// "static" import
icz.addStaticImport('java.lang.Math', 'PI') // import static java.lang.Math.PI
// "aliased static" import
icz.addStaticImport('pi', 'java.lang.Math', 'PI') // import static java.lang.Math.PI as pi
// "star" import
icz.addStarImports 'java.util.concurrent' // import java.util.concurrent.*
// "static star" import
icz.addStaticStars 'java.lang.Math' // import static java.lang.Math.*
A detailed description of all shortcuts can be found in org.codehaus.groovy.control.customizers.ImportCustomizer
(http://docs.groovy-lang.org/2.5.5/html/gapi/index.html?org/codehaus/groovy/control/customizers/ImportCustomizer.html)
AST transformation customizer
The AST transformation customizer is meant to apply AST transformations transparently. Unlike global AST transformations that
apply on every class beeing compiled as long as the transform is found on classpath (which has drawbacks like increasing the
compilation time or side e ects due to transformations applied where they should not), the customizer will allow you to
selectively apply a transform only for speci c scripts or classes.
As an example, let’s say you want to be able to use @Log in a script. The problem is that @Log is normally applied on a class node
and a script, by de nition, doesn’t require one. But implementation wise, scripts are classes, it’s just that you cannot annotate this
implicit class node with @Log . Using the AST customizer, you have a workaround to do it:
http://docs.groovy-lang.org/latest/html/documentation/ 400/502
1/6/2019 Groovy Language Documentation
org.codehaus.groovy.control.customizers.
groovy.util.logging.
acz = ( )
config.addCompilationCustomizers(acz)
That’s all! Internally, the @Log AST transformation is applied to every class node in the compilation unit. This means that it will be
applied to the script, but also to classes de ned within the script.
If the AST transformation that you are using accepts parameters, you can use parameters in the constructor too:
acz = ( , value: 'LOGGER')
// use name 'LOGGER' instead of the default 'log'
config.addCompilationCustomizers(acz)
As the AST transformation customizers works with objects instead of AST nodes, not all values can be converted to AST
transformation parameters. For example, primitive types are converted to ConstantExpression (that is LOGGER is converted
to new ConstantExpression('LOGGER') , but if your AST transformation takes a closure as an argument, then you have to give it
a ClosureExpression , like in the following example:
configuration = ()
expression = ().buildFromCode( .CONVERSION) { -> }.expression[0]
customizer = ( , value: expression, thrown:
)
configuration.addCompilationCustomizers(customizer)
shell = (configuration)
shouldFail( ) {
shell.evaluate("""
// equivalent to adding @ConditionalInterrupt(value={true}, thrown: SecurityException)
class MyClass {
void doIt() { }
}
new MyClass().doIt()
""")
}
For a complete list of options, please refer to org.codehaus.groovy.control.customizers.ASTTransformationCustomizer
(http://docs.groovy-lang.org/2.5.5/html/gapi/index.html?
org/codehaus/groovy/control/customizers/ASTTransformationCustomizer.html)
Secure AST customizer
This customizer will allow the developer of a DSL to restrict the grammar of the language, to prevent users from using some
constructs, for example. It is only ``secure'' in that sense only and it is very important to understand that it does not replace a
security manager. The only reason for it to exist is to limit the expressiveness of the language. This customizer only works at the
AST (abstract syntax tree) level, not at runtime! It can be strange at rst glance, but it makes much more sense if you think of
Groovy as a platform to build DSLs. You may not want a user to have a complete language at hand. In the example below, we will
demonstrate it using an example of language that only allows arithmetic operations, but this customizer allows you to:
allow/disallow creation of closures
allow/disallow imports
allow/disallow package de nition
allow/disallow de nition of methods
restrict the receivers of method calls
restrict the kind of AST expressions a user can use
restrict the tokens (grammar-wise) a user can use
restrict the types of the constants that can be used in code
http://docs.groovy-lang.org/latest/html/documentation/ 401/502
1/6/2019 For all those features, the secure AST customizer works using either
Groovy a whitelist
Language (list of elements that are allowed) or a blacklist (list
Documentation
of elements that are disallowed). For each type of feature (imports, tokens, …) you have the choice to use either a whitelist or a
blacklist, but you can mix whitelists and blacklists for distinct features. In general, you will choose whitelists (disallow all, allow
selected).
org.codehaus.groovy.control.customizers.
org.codehaus.groovy.syntax. .* 1
scz = ()
scz. {
closuresAllowed = // user will not be able to write closures
methodDefinitionAllowed = // user will not be able to define methods
importsWhitelist = [] // empty whitelist means imports are disallowed
staticImportsWhitelist = [] // same for static imports
staticStarImportsWhitelist = ['java.lang.Math'] // only java.lang.Math is allowed
// the list of tokens the user can find
// constants are defined in org.codehaus.groovy.syntax.Types
tokensWhitelist = [ 1
PLUS,
MINUS,
MULTIPLY,
DIVIDE,
MOD,
POWER,
PLUS_PLUS,
MINUS_MINUS,
COMPARE_EQUAL,
COMPARE_NOT_EQUAL,
COMPARE_LESS_THAN,
COMPARE_LESS_THAN_EQUAL,
COMPARE_GREATER_THAN,
COMPARE_GREATER_THAN_EQUAL,
].asImmutable()
// limit the types of constants that a user can define to number types only
constantTypesClassesWhiteList = [ 2
,
,
,
,
,
.TYPE,
.TYPE,
.TYPE,
.TYPE
].asImmutable()
// method calls are only allowed if the receiver is of one of those types
// be careful, it's not a runtime type!
receiversClassesWhiteList = [ 2
,
,
,
,
,
].asImmutable()
}
use for token types from org.codehaus.groovy.syntax.Types (http://docs.groovy-lang.org/2.5.5/html/gapi/index.html?
1
org/codehaus/groovy/syntax/Types.html)
2 you can use class literals here
If what the secure AST customizer provides out of the box isn’t enough for your needs, before creating your own compilation
customizer, you might be interested in the expression and statement checkers that the AST customizer supports. Basically, it
allows you to add custom checks on the AST tree, on expressions (expression checkers) or statements (statement checkers). For
http://docs.groovy-lang.org/latest/html/documentation/ 402/502
1/6/2019 this, you must implement org.codehaus.groovy.control.customizers.SecureASTCustomizer.StatementChecker
Groovy Language Documentation
or org.codehaus.groovy.control.customizers.SecureASTCustomizer.ExpressionChecker .
Those interfaces de ne a single method called isAuthorized , returning a boolean, and taking a Statement (or Expression ) as
a parameter. It allows you to perform complex logic over expressions or statements to tell if a user is allowed to do it or not.
For example, there’s no prede ned con guration ag in the customizer which will let you prevent people from using an attribute
expression. Using a custom checker, it is trivial:
scz = ()
checker = { expr ->
!(expr )
} .
scz.addExpressionCheckers(checker)
Then we can make sure that this works by evaluating a simple script:
(config).evaluate '''
class A {
int val
}
def a = new A(val: 123)
a.@val 1
'''
1 will fail compilation
Statements can be checked using org.codehaus.groovy.control.customizers.SecureASTCustomizer.StatementChecker
(http://docs.groovy-lang.org/2.5.5/html/gapi/index.html?
org/codehaus/groovy/control/customizers/SecureASTCustomizer/StatementChecker.html) Expressions can be checked using
org.codehaus.groovy.control.customizers.SecureASTCustomizer.ExpressionChecker (http://docs.groovy-
lang.org/2.5.5/html/gapi/index.html?org/codehaus/groovy/control/customizers/SecureASTCustomizer/ExpressionChecker.html)
Source aware customizer
This customizer may be used as a lter on other customizers. The lter, in that case, is
the org.codehaus.groovy.control.SourceUnit . For this, the source aware customizer takes another customizer as a delegate,
and it will apply customization of that delegate only and only if predicates on the source unit match.
SourceUnit gives you access to multiple things but in particular the le being compiled (if compiling from a le, of course). It
gives you the potential to perform operation based on the le name, for example. Here is how you would create a source aware
customizer:
org.codehaus.groovy.control.customizers.
org.codehaus.groovy.control.customizers.
= ()
sac = ( )
Then you can use predicates on the source aware customizer:
http://docs.groovy-lang.org/latest/html/documentation/ 403/502
1/6/2019 Groovy Language Documentation
// the customizer will only be applied to classes contained in a file name ending with 'Bean'
sac.baseNameValidator = { baseName ->
baseName.endsWith 'Bean'
}
// the customizer will only be applied to files which extension is '.spec'
sac.extensionValidator = { ext -> ext == 'spec' }
// source unit validation
// allow compilation only if the file contains at most 1 class
sac.sourceUnitValidator = { sourceUnit -> sourceUnit.AST.classes.size() == 1 }
// class validation
// the customizer will only be applied to classes ending with 'Bean'
sac.classValidator = { cn -> cn.endsWith('Bean') }
Customizer builder
If you are using compilation customizers in Groovy code (like the examples above) then you can use an alternative syntax to
customize compilation. A builder ( org.codehaus.groovy.control.customizers.builder.CompilerCustomizationBuilder )
simpli es the creation of customizers using a hierarchical DSL.
org.codehaus.groovy.control.
org.codehaus.groovy.control.customizers.builder. .withConfig
1
conf = ()
withConfig(conf) {
// ... 2
}
1 static import of the builder method
2 con guration goes here
The code sample above shows how to use the builder. A static method, withCon g, takes a closure corresponding to the builder
code, and automatically registers compilation customizers to the con guration. Every compilation customizer available in the
distribution can be con gured this way:
Import customizer
withConfig(configuration) {
imports { // imports customizer
normal 'my.package.MyClass' // a normal import
'AI', 'java.util.concurrent.atomic.AtomicInteger' // an aliased import
star 'java.util.concurrent' // star imports
staticMember 'java.lang.Math', 'PI' // static import
staticMember 'pi', 'java.lang.Math', 'PI' // aliased static import
}
}
AST transformation customizer
withConfig(conf) {
ast( ) 1
}
withConfig(conf) {
ast( , value: 'LOGGER') 2
1 apply @Log transparently
2 apply @Log with a di erent name for the logger
Secure AST customizer
http://docs.groovy-lang.org/latest/html/documentation/ 404/502
1/6/2019 Groovy Language Documentation
withConfig(conf) {
secureAst {
closuresAllowed =
methodDefinitionAllowed =
}
}
Source aware customizer
withConfig(configuration){
source(extension: 'sgroovy') {
ast( ) 1
}
}
withConfig(configuration){
source(extensions: ['sgroovy','sg']) {
ast( ) 2
}
}
withConfig(configuration) {
source(extensionValidator: { it.name ['sgroovy','sg']}) {
ast( ) 2
}
}
withConfig(configuration) {
source(basename: 'foo') {
ast( ) 3
}
}
withConfig(configuration) {
source(basenames: ['foo', 'bar']) {
ast( ) 4
}
}
withConfig(configuration) {
source(basenameValidator: { it ['foo', 'bar'] }) {
ast( ) 4
}
}
withConfig(configuration) {
source(unitValidator: { unit -> !unit.AST.classes.any { it.name == 'Baz' } }) {
ast( ) 5
}
}
1 apply CompileStatic AST annotation on .sgroovy les
2 apply CompileStatic AST annotation on .sgroovy or .sg les
3 apply CompileStatic AST annotation on les whose name is 'foo'
4 apply CompileStatic AST annotation on les whose name is 'foo' or 'bar'
5 apply CompileStatic AST annotation on les that do not contain a class named 'Baz'
Inlining a customizer
Inlined customizer allows you to write a compilation customizer directly, without having to create a class for it.
http://docs.groovy-lang.org/latest/html/documentation/ 405/502
1/6/2019 Groovy Language Documentation
withConfig(configuration) {
(phase:'CONVERSION') { source, context, classNode -> 1
println "visiting $classNode" 2
}
}
1 de ne an inlined customizer which will execute at the CONVERSION phase
2 prints the name of the class node being compiled
Multiple customizers
Of course, the builder allows you to de ne multiple customizers at once:
withConfig(configuration) {
ast( )
ast( )
}
Con g script ag
So far, we have described how you can customize compilation using a CompilationConfiguration class, but this is only possible
if you embed Groovy and that you create your own instances of CompilerConfiguration (then use it to create a
GroovyShell , GroovyScriptEngine , …).
If you want it to be applied on the classes you compile with the normal Groovy compiler (that is to say with groovyc , ant
or gradle , for example), it is possible to use a compilation ag named configscript that takes a Groovy con guration script as
argument.
This script gives you access to the CompilerConfiguration instance before the les are compiled (exposed into the
con guration script as a variable named configuration ), so that you can tweak it.
It also transparently integrates the compiler con guration builder above. As an example, let’s see how you would activate static
compilation by default on all classes.
Static compilation by default
Normally, classes in Groovy are compiled with a dynamic runtime. You can activate static compilation by placing an annotation
named @CompileStatic on any class. Some people would like to have this mode activated by default, that is to say not having to
annotated classes. Using configscript , this is possible. First of all, you need to create a le named config.groovy into
src/conf with the following contents:
withConfig(configuration) { 1
ast(groovy.transform. )
}
1 con guration references a CompilerConfiguration instance
That is actually all you need. You don’t have to import the builder, it’s automatically exposed in the script. Then, compile your les
using the following command line:
groovyc -configscript src/conf/config.groovy src/main/groovy/MyClass.groovy
We strongly recommend you to separate con guration les from classes, hence why we suggest using the src/main and
src/conf directories above.
AST transformations
If:
runtime metaprogramming doesn’t allow you do do what you want
you need to improve the performance of the execution of your DSLs
you want to leverage the same syntax as Groovy but with di erent semantics
you want to improve support for type checking in your DSLs
http://docs.groovy-lang.org/latest/html/documentation/ 406/502
1/6/2019 Then AST transformations are the way to go. Unlike the techniques used soDocumentation
Groovy Language far, AST transformations are meant to change or
generate code before it is compiled to bytecode. AST transformations are capable of adding new methods at compile time for
example, or totally changing the body of a method based on your needs. They are a very powerful tool but also come at the price
of not being easy to write. For more information about AST transformations, please take a look at the compile-time
metaprogramming (http://docs.groovy-lang.org/latest/html/documentation/index.html#_compile_time_metaprogramming)
section of this manual.
3.15.7. Custom type checking extensions
It may be interesting, in some circumstances, to provide feedback about wrong code to the user as soon as possible, that is to say
when the DSL script is compiled, rather than having to wait for the execution of the script. However, this is not often possible with
dynamic code. Groovy actually provides a practical answer to this known as type checking extensions (type-checking-
extensions.html).
3.15.8. Builders
(TBD)
Creating a builder
(TBD)
BuilderSupport
(TBD)
FactoryBuilderSupport
(TBD)
Existing builders
(TBD)
MarkupBuilder
See Creating Xml - MarkupBuilder.
StreamingMarkupBuilder
See Creating Xml - StreamingMarkupBuilder.
SaxBuilder
A builder for generating Simple API for XML (SAX) (https://en.wikipedia.org/wiki/Simple_API_for_XML) events.
If you have the following SAX handler:
org.xml.sax.helpers. {
log = ''
startElement( uri, localName, qName, org.xml.sax. attributes)
{
log += "Start Element: $localName, "
}
endElement( uri, localName, qName) {
log += "End Element: $localName, "
}
}
You can use SaxBuilder to generate SAX events for the handler like this:
handler = ()
builder = groovy.xml. (handler)
builder.root() {
helloWorld()
}
http://docs.groovy-lang.org/latest/html/documentation/ 407/502
1/6/2019 And then check that everything worked as expected: Groovy Language Documentation
handler.log == 'Start Element: root, Start Element: helloWorld, End Element: helloWorld, End
Element: root, '
StaxBuilder
A Groovy builder that works with Streaming API for XML (StAX) (http://en.wikipedia.org/wiki/StAX) processors.
Here is a simple example using the StAX implementation of Java to generate XML:
factory = javax.xml.stream. .newInstance()
writer = ()
builder = groovy.xml. (factory.createXMLStreamWriter(writer))
builder.root(attribute:1) {
elem1('hello')
elem2('world')
}
writer.toString() == '<?xml version="1.0" ?><root attribute="1"><elem1>hello</elem1>
<elem2>world</elem2></root>'
An external library such as Jettison (https://github.com/jettison-json/jettison) can be used as follows:
@Grab('org.codehaus.jettison:jettison:1.3.3')
@GrabExclude('stax:stax-api') // part of Java 6 and later
org.codehaus.jettison.mapped.*
writer = ()
mappedWriter = ( (), writer)
builder = groovy.xml. (mappedWriter)
builder.root(attribute:1) {
elem1('hello')
elem2('world')
}
writer.toString() == '{"root":{"@attribute":"1","elem1":"hello","elem2":"world"}}'
DOMBuilder
A builder for parsing HTML, XHTML and XML into a W3C DOM (https://en.wikipedia.org/wiki/Document_Object_Model) tree.
For example this XML String :
recordsXML = '''
<records>
<car name='HSV ' make=' ' year='2006'>
<country>Australia</country>
<record type='speed'>Production Pickup Truck with speed of 271kph</record>
</car>
<car name='P50' make=' ' year='1962'>
<country>Isle of Man</country>
<record type='size'>Smallest Street-Legal Car at 99cm wide and 59 kg in weight</record>
</car>
<car name=' ' make=' ' year='1931'>
<country>France</country>
<record type='price'>Most Valuable Car at $15 million</record>
</car>
</records>'''
Can be parsed into a DOM tree with a DOMBuilder like this:
http://docs.groovy-lang.org/latest/html/documentation/ 408/502
1/6/2019 Groovy Language Documentation
reader = (recordsXML)
doc = groovy.xml. .parse(reader)
And then processed further e.g. by using DOMCategory:
records = doc.documentElement
(groovy.xml.dom. ) {
records.car.size() == 3
}
NodeBuilder
NodeBuilder is used for creating nested trees of Node (http://docs.groovy-lang.org/2.5.5/html/gapi/index.html?
groovy/util/Node.html) objects for handling arbitrary data. To create a simple user list you use a NodeBuilder like this:
nodeBuilder = ()
userlist = nodeBuilder.userlist {
user(id: '1', firstname: 'John', lastname: 'Smith') {
address(type: 'home', street: '1 Main St.', city: 'Springfield', state: 'MA', zip:
'12345')
address(type: 'work', street: '2 South St.', city: 'Boston', state: 'MA', zip: '98765')
}
user(id: '2', firstname: 'Alice', lastname: 'Doe')
}
Now you can process the data further, e.g. by using GPath expressions:
[email protected](', ') == 'John, Alice'
userlist.user.find { it.@lastname == 'Smith' }.address.size() == 2
JsonBuilder
Groovy’s JsonBuilder makes it easy to create Json. For example to create this Json string:
carRecords = '''
{
"records": {
"car": {
"name": "HSV Maloo",
"make": "Holden",
"year": 2006,
"country": "Australia",
"record": {
"type": "speed",
"description": "production pickup truck with speed of 271kph"
}
}
}
}
'''
you can use a JsonBuilder like this:
http://docs.groovy-lang.org/latest/html/documentation/ 409/502
1/6/2019 Groovy Language Documentation
builder = ()
builder.records {
car {
name 'HSV Maloo'
make 'Holden'
year 2006
country 'Australia'
record {
type 'speed'
description 'production pickup truck with speed of 271kph'
}
}
}
json = .prettyPrint(builder.toString())
We use JsonUnit (https://github.com/lukas-krecan/JsonUnit) to check that the builder produced the expected result:
.assertJsonEquals(json, carRecords)
If you need to customize the generated output you can pass a JsonGenerator instance when creating a JsonBuilder :
groovy.json.*
generator = . ()
.excludeNulls()
.excludeFieldsByName('make', 'country', 'record')
.excludeFieldsByType( )
.addConverter(URL) { url -> "http://groovy-lang.org" }
.build()
builder = (generator)
builder.records {
car {
name 'HSV Maloo'
make 'Holden'
year 2006
country 'Australia'
homepage URL('http://example.org')
record {
type 'speed'
description 'production pickup truck with speed of 271kph'
}
}
}
builder.toString() == '{"records":{"car":{"name":"HSV Maloo","homepage":"http://groovy-
lang.org"}}}'
StreamingJsonBuilder
Unlike JsonBuilder which creates a data structure in memory, which is handy in those situations where you want to alter the
structure programmatically before output, StreamingJsonBuilder directly streams to a writer without any intermediate
memory data structure. If you do not need to modify the structure and want a more memory-e cient approach, use
StreamingJsonBuilder .
The usage of StreamingJsonBuilder is similar to JsonBuilder . In order to create this Json string:
http://docs.groovy-lang.org/latest/html/documentation/ 410/502
1/6/2019 Groovy Language Documentation
carRecords = '''
{
"records": {
"car": {
"name": "HSV Maloo",
"make": "Holden",
"year": 2006,
"country": "Australia",
"record": {
"type": "speed",
"description": "production pickup truck with speed of 271kph"
}
}
}
}
'''
you use a StreamingJsonBuilder like this:
writer = ()
builder = (writer)
builder.records {
car {
name 'HSV Maloo'
make 'Holden'
year 2006
country 'Australia'
record {
type 'speed'
description 'production pickup truck with speed of 271kph'
}
}
}
json = .prettyPrint(writer.toString())
We use JsonUnit (https://github.com/lukas-krecan/JsonUnit) to check the expected result:
.assertJsonEquals(json, carRecords)
If you need to customize the generated output you can pass a JsonGenerator instance when creating a
StreamingJsonBuilder :
http://docs.groovy-lang.org/latest/html/documentation/ 411/502
1/6/2019 Groovy Language Documentation
generator = . ()
.excludeNulls()
.excludeFieldsByName('make', 'country', 'record')
.excludeFieldsByType( )
.addConverter(URL) { url -> "http://groovy-lang.org" }
.build()
writer = ()
builder = (writer, generator)
builder.records {
car {
name 'HSV Maloo'
make 'Holden'
year 2006
country 'Australia'
homepage URL('http://example.org')
record {
type 'speed'
description 'production pickup truck with speed of 271kph'
}
}
}
writer.toString() == '{"records":{"car":{"name":"HSV Maloo","homepage":"http://groovy-
lang.org"}}}'
SwingBuilder
SwingBuilder allows you to create full- edged Swing GUIs in a declarative and concise fashion. It accomplishes this by
employing a common idiom in Groovy, builders. Builders handle the busywork of creating complex objects for you, such as
instantiating children, calling Swing methods, and attaching these children to their parents. As a consequence, your code is much
more readable and maintainable, while still allowing you access to the full range of Swing components.
Here’s a simple example of using SwingBuilder :
groovy.swing.
java.awt. BL
count = 0
().edt {
frame(title: 'Frame', size: [300, 300], show: ) {
borderLayout()
textlabel = label(text: 'Click the button!', constraints: BL.NORTH)
button(text:'Click Me',
actionPerformed: {count++; textlabel.text = "Clicked ${count} time(s)."; println
"clicked"}, constraints:BL.SOUTH)
}
}
Here is what it will look like:
This hierarchy of components would normally be created through a series of repetitive instantiations, setters, and nally attaching
this child to its respective parent. Using SwingBuilder , however, allows you to de ne this hierarchy in its native form, which
makes the interface design understandable simply by reading the code.
The exibility shown here is made possible by leveraging the many programming features built-in to Groovy, such as closures,
implicit constructor calling, import aliasing, and string interpolation. Of course, these do not have to be fully understood in order
to use SwingBuilder ; as you can see from the code above, their uses are intuitive.
Here is a slightly more involved example, with an example of SwingBuilder code re-use via a closure.
http://docs.groovy-lang.org/latest/html/documentation/ 412/502
1/6/2019 Groovy Language Documentation
groovy.swing.
javax.swing.*
java.awt.*
swing = ()
sharedPanel = {
swing.panel() {
label("Shared Panel")
}
}
count = 0
swing.edt {
frame(title: 'Frame', defaultCloseOperation: .EXIT_ON_CLOSE, pack: , show: ) {
vbox {
textlabel = label('Click the button!')
button(
text: 'Click Me',
actionPerformed: {
count++
textlabel.text = "Clicked ${count} time(s)."
println "Clicked!"
}
)
widget(sharedPanel())
widget(sharedPanel())
}
}
}
Here’s another variation that relies on observable beans and binding:
groovy.swing.
groovy.beans.
{
@Bindable count = 0
}
model = ()
().edt {
frame(title: 'Java Frame', size: [100, 100], locationRelativeTo: , show: ) {
gridLayout(cols: 1, rows: 2)
label(text: bind(source: model, sourceProperty: 'count', converter: { v -> v? "Clicked $v
times": ''}))
button('Click me!', actionPerformed: { model.count++ })
}
}
@Bindable is one of the core AST Transformations. It generates all the required boilerplate code to turn a simple bean into an
observable one. The bind() node creates appropriate PropertyChangeListeners that will update the interested parties
whenever a PropertyChangeEvent is red.
AntBuilder
Despite being primarily a build tool, Apache Ant (http://ant.apache.org/) is a very practical tool for manipulating les including zip
les, copy, resource processing, … But if ever you’ve been working with a build.xml le or some Jelly script and found yourself a
little restricted by all those pointy brackets, or found it a bit weird using XML as a scripting language and wanted something a little
cleaner and more straight forward, then maybe Ant scripting with Groovy might be what you’re after.
Groovy has a helper class called AntBuilder which makes the scripting of Ant tasks really easy; allowing a real scripting language
to be used for programming constructs (variables, methods, loops, logical branching, classes etc). It still looks like a neat concise
version of Ant’s XML without all those pointy brackets; though you can mix and match this markup inside your script. Ant itself is a
collection of jar les. By adding them to your classpath, you can easily use them within Groovy as is. We believe using
AntBuilder leads to more concise and readily understood syntax.
http://docs.groovy-lang.org/latest/html/documentation/ 413/502
1/6/2019 AntBuilder exposes Ant tasks directly using the convenient builder
Groovy notation
Language that we are used to in Groovy. Here is the most
Documentation
basic example, which is printing a message on the standard output:
ant = () 1
ant.echo('hello from Ant!') 2
1 creates an instance of AntBuilder
2 executes the echo task with the message in parameter
Imagine that you need to create a ZIP le. It can be as simple as:
ant = ()
ant.zip(destfile: 'sources.zip', basedir: 'src')
In the next example, we demonstrate the use of AntBuilder to copy a list of les using a classical Ant pattern directly in Groovy:
// let's just call one task
ant.echo("hello")
// here is an example of a block of Ant inside GroovyMarkup
ant.sequential {
echo("inside sequential")
myDir = "target/AntTest/"
mkdir(dir: myDir)
copy(todir: myDir) {
fileset(dir: "src/test") {
include(name: "**/*.groovy")
}
}
echo("done")
}
// now let's do some normal Groovy again
file = (ant.project.baseDir,"target/AntTest/some/pkg/MyTest.groovy")
file.exists()
Another example would be iterating over a list of les matching a speci c pattern:
// let's create a scanner of filesets
scanner = ant.fileScanner {
fileset(dir:"src/test") {
include(name:"**/My*.groovy")
}
}
// now let's iterate over
found =
(f scanner) {
println("Found file $f")
found =
f
f.name.endsWith(".groovy")
}
found
Or executing a JUnit test:
ant.junit {
classpath { pathelement(path: '.') }
test(name:'some.pkg.MyTest')
}
We can even go further by compiling and executing a Java le directly from Groovy:
http://docs.groovy-lang.org/latest/html/documentation/ 414/502
1/6/2019 Groovy Language Documentation
ant.echo(file:'Temp.java', '''
class Temp {
public static void main(String[] args) {
System.out.println("Hello");
}
}
''')
ant.javac(srcdir:'.', includes:'Temp.java', fork:'true')
ant.java(classpath:'.', classname:'Temp', fork:'true')
ant.echo('Done')
It is worth mentioning that AntBuilder is included in Gradle (http://gradle.org/), so you can use it in Gradle just like you would in
Groovy. Additional documentation can be found in the Gradle manual (http://gradle.org/docs/current/userguide/ant.html).
CliBuilder
CliBuilder provides a compact way to specify the available options for a commandline application and then automatically parse
the application’s commandline parameters according to that speci cation. By convention, a distinction is made between option
commandline parameters and any remaining parameters which are passed to an application as its arguments. Typically, several
types of options might be supported such as -V or --tabsize=4 . CliBuilder removes the burden of developing lots of code
for commandline processing. Instead, it supports a somewhat declarative approach to declaring your options and then provides a
single call to parse the commandline parameters with a simple mechanism to interrogate the options (you can think of this as a
simple model for your options).
Even though the details of each commandline you create could be quite di erent, the same main steps are followed each time.
First, a CliBuilder instance is created. Then, allowed commandline options are de ned. This can be done using a dynamic api
style or an annotation style. The commandline parameters are then parsed according to the options speci cation resulting in a
collection of options which are then interrogated.
Here is a simple example Greeter.groovy script illustrating usage:
// import of CliBuilder not shown 1
// specify parameters
cli = (usage: 'groovy Greeter [option]') 2
cli.a(longOpt: 'audience', args: 1, 'greeting audience') 3
cli.h(longOpt: 'help', 'display usage') 4
// parse and process parameters
options = cli.parse(args) 5
(options.h) cli.usage() 6
println "Hello ${options.a ? options.a : 'World'}" 7
Earlier versions of Groovy had a CliBuilder in the groovy.util package and no import was necessary. While still supported,
this approach is now deprecated and you should instead choose the groovy.cli.picocli or groovy.cli.commons version. The
1
groovy.util version points to the commons-cli version for backwards compatibility but will be removed in a future version of
Groovy.
2 de ne a new CliBuilder instance specifying an optional usage string
3 specify a -a option taking a single argument with an optional long variant --audience
4 specify a -h option taking no arguments with an optional long variant --help
5 parse the commandline parameters supplied to the script
6 if the h option is found display a usage message
7 display a standard greeting or, if the a option is found, a customized greeting
Running this script with no commandline parameters, i.e.:
> groovy
results in the following output:
Hello World
http://docs.groovy-lang.org/latest/html/documentation/ 415/502
1/6/2019 Running this script with -h as the single commandline parameter, i.e.:
Groovy Language Documentation
> groovy -h
results in the following output:
usage: groovy Greeter [option]
-a,--audience <arg> greeting audience
-h,--help display usage
Running this script with --audience Groovologist as the commandline parameters, i.e.:
> groovy --audience
results in the following output:
Hello Groovologist
When creating the CliBuilder instance in the above example, we set the optional usage property within the constructor call.
This follows Groovy’s normal ability to set additional properties of the instance during construction. There are numerous other
properties which can be set such as header and footer . For the complete set of available properties, see the available
properties for the CliBuilder (http://docs.groovy-lang.org/2.5.5/html/gapi/index.html?groovy/util/CliBuilder.html) class.
When de ning an allowed commandline option, both a short name (e.g. "h" for the help option shown previously) and a short
description (e.g. "display usage" for the help option) must be supplied. In our example above, we also set some additional
properties such as longOpt and args . The following additional properties are supported when specifying an allowed
commandline option:
Name Description Type
argName the name of the argument for this String
option used in output
longOpt the long representation or long name of String
the option
args the number of argument values int or String <1>
optionalArg whether the argument value is optional boolean
required whether the option is mandatory boolean
type the type of this option Class
valueSeparator the character that is the value separator char <2>
defaultValue a default value String
convert converts the incoming String to the Closure <1>
required type
1 More details later
2 Single character Strings are coerced to chars in special cases in Groovy
If you have an option with only a longOpt variant, you can use the special shortname of '_' to specify the option, e.g. :
cli._(longOpt: 'verbose', 'enable verbose logging') . Some of the remaining named parameters should be fairly self-
explanatory while others deserve a bit more explanation. But before further explanations, let’s look at ways of using CliBuilder
with annotations.
Using Annotations and an interface
http://docs.groovy-lang.org/latest/html/documentation/ 416/502
1/6/2019 Rather than making a series of method calls (albeit in a very declarative
Groovy Languagemini-DSL form) to specify the allowable options, you can
Documentation
provide an interface speci cation of the allowable options where annotations are used to indicate and provide details for those
options and for how unprocessed parameters are handled. Two annotations are used: groovy.cli.Option (http://docs.groovy-
lang.org/2.5.5/html/gapi/index.html?groovy/cli/Option.html) and groovy.cli.Unparsed (http://docs.groovy-
lang.org/2.5.5/html/gapi/index.html?groovy/cli/Unparsed.html).
Here is how such a speci cation can be de ned:
{
@Option(shortName='h', description='display usage') help() 1
@Option(shortName='a', description='greeting audience') audience() 2
@Unparsed(description = "positional parameters") remaining() 3
1 Specify a Boolean option set using -h or --help
2 Specify a String option set using -a or --audience
3 Specify where any remaining parameters will be stored
Note how the long name is automatically determined from the interface method name. You can use the longName annotation
attribute to override that behavior and specify a custom long name if you wish or use a longName of '_' to indicate that no long
name is to be provided. You will need to specify a shortName in such a case.
Here is how you could use the interface speci cation:
// import CliBuilder not shown
cli = (usage: 'groovy Greeter') 1
argz = '--audience Groovologist'.split()
options = cli.parseFromSpec( , argz) 2
options.audience() == 'Groovologist' 3
argz = '-h Some Other Args'.split()
options = cli.parseFromSpec( , argz) 4
options.help()
options.remaining() == ['Some', 'Other', 'Args'] 5
1 Create a CliBuilder instance as before with optional properties
2 Parse parameters using the interface speci cation
3 Interrogate options using the methods from the interface
4 Parse a di erent set of parameters
5 Interrogate the remaining parameters
When parseFromSpec is called, CliBuilder automatically creates an instance implementing the interface and populates it. You
simply call the interface methods to interrogate the option values.
Using Annotations and an instance
Alternatively, perhaps you already have a domain class containing the option information. You can simply annotate properties or
setters from that class to enable CliBuilder to appropriately populate your domain object. Each annotation both describes that
option’s properties through the annotation attributes and indicates the setter the CliBuilder will use to populate that option in
your domain object.
Here is how such a speci cation can be de ned:
http://docs.groovy-lang.org/latest/html/documentation/ 417/502
1/6/2019 Groovy Language Documentation
{
@Option(shortName='h', description='display usage')
help 1
audience
@Option(shortName='a', description='greeting audience')
setAudience( audience) { 2
.audience = audience
}
getAudience() { audience }
@Unparsed(description = "positional parameters")
remaining 3
1 Indicate that a Boolean property is an option
2 Indicate that a String property (with explicit setter) is an option
3 Specify where any remaining args will be stored
And here is how you could use the speci cation:
// import CliBuilder not shown
cli = (usage: 'groovy Greeter [option]') 1
options = () 2
argz = '--audience Groovologist foo'.split()
cli.parseFromInstance(options, argz) 3
options.audience == 'Groovologist' 4
options.remaining == ['foo'] 5
1 Create a CliBuilder instance as before with optional parameters
2 Create an instance for CliBuilder to populate
3 Parse arguments populating the supplied instance
4 Interrogate the String option property
5 Interrogate the remaining arguments property
When parseFromInstance is called, CliBuilder automatically populates your instance. You simply interrogate the instance
properties (or whatever accessor methods you have provided in your domain object) to access the option values.
Using Annotations and a script
Finally, there are two additional convenience annotation aliases speci cally for scripts. They simply combine the previously
mentioned annotations and groovy.transform.Field (http://docs.groovy-lang.org/2.5.5/html/gapi/index.html?
groovy/transform/Field.html). The groovydoc for those annotations reveals the details: groovy.cli.OptionField (http://docs.groovy-
lang.org/2.5.5/html/gapi/index.html?groovy/cli/OptionField.html) and groovy.cli.UnparsedField (http://docs.groovy-
lang.org/2.5.5/html/gapi/index.html?groovy/cli/UnparsedField.html).
Here is an example using those annotations in a self-contained script that would be called with the same arguments as shown for
the instance example earlier:
// import CliBuilder not shown
groovy.cli.
groovy.cli.
@OptionField audience
@OptionField help
@UnparsedField remaining
().parseFromInstance( , args)
audience == 'Groovologist'
remaining == ['foo']
Options with arguments
http://docs.groovy-lang.org/latest/html/documentation/ 418/502
1/6/2019 We saw in our initial example that some options act like Groovy
ags, e.g.Language -h but others take an argument, e.g.
GreeterDocumentation
Greeter --audience Groovologist . The simplest cases involve options which act like ags or have a single (potentially
optional) argument. Here is an example involving those cases:
// import CliBuilder not shown
cli = ()
cli.a(args: 0, 'a arg') 1
cli.b(args: 1, 'b arg') 2
cli.c(args: 1, optionalArg: , 'c arg') 3
options = cli.parse('-a -b foo -c bar baz'.split()) 4
options.a ==
options.b == 'foo'
options.c == 'bar'
options.arguments() == ['baz']
options = cli.parse('-a -c -b foo bar baz'.split()) 5
options.a ==
options.c ==
options.b == 'foo'
options.arguments() == ['bar', 'baz']
1 An option that is simply a ag - the default; setting args to 0 is allowed but not needed.
2 An option with exactly one argument
3 An option with an optional argument; it acts like a ag if the option is left out
4 An example using this spec where an argument is supplied to the 'c' option
5 An example using this spec where no argument is supplied to the 'c' option; it’s just a ag
Note: when an option with an optional argument is encountered, it will (somewhat) greedily consume the next parameter from
the supplied commandline parameters. If however, the next parameter matches a known long or short option (with leading single
or double hyphens), that will take precedence, e.g. -b in the above example.
Option arguments may also be speci ed using the annotation style. Here is an interface option speci cation illustrating such a
de nition:
{
@Option a()
@Option b()
@Option(optionalArg= ) [] c()
@Unparsed remaining()
}
And here is how it is used:
cli = ()
options = cli.parseFromSpec( , '-a -b foo -c bar baz'.split())
options.a()
options.b() == 'foo'
options.c() == ['bar']
options.remaining() == ['baz']
options = cli.parseFromSpec( , '-a -c -b foo bar baz'.split())
options.a()
options.c() == []
options.b() == 'foo'
options.remaining() == ['bar', 'baz']
This example makes use of an array-typed option speci cation. We cover this in more detail shortly when we discuss multiple
arguments.
Specifying a type
http://docs.groovy-lang.org/latest/html/documentation/ 419/502
1/6/2019 Arguments on the commandline are by nature Strings (or Groovy
arguably can be considered
Language Booleans for ags) but can be converted to
Documentation
richer types automatically by supplying additional typing information. For the annotation-based argument de nition style, these
types are supplied using the eld types for annotation properties or return types of annotated methods (or the setter argument
type for setter methods). For the dynamic method style of argument de nition a special 'type' property is supported which allows
you to specify a Class name.
When an explicit type is de ned, the args named-parameter is assumed to be 1 (except for Boolean-typed options where it is 0
by default). An explicit args parameter can still be provided if needed. Here is an example using types with the dynamic api
argument de nition style:
argz = '''-a John -b -d 21 -e 1980 -f 3.5 -g 3.14159
-h cv.txt -i DOWN and some more'''.split()
cli = ()
cli.a(type: , 'a-arg')
cli.b(type: , 'b-arg')
cli.c(type: , 'c-arg')
cli.d(type: , 'd-arg')
cli.e(type: , 'e-arg')
cli.f(type: , 'f-arg')
cli.g(type: , 'g-arg')
cli.h(type: , 'h-arg')
cli.i(type: , 'i-arg')
options = cli.parse(argz)
options.a == 'John'
options.b
!options.c
options.d == 21
options.e == 1980L
options.f == 3.5f
options.g == 3.14159
options.h == ('cv.txt')
options.i == .DOWN
options.arguments() == ['and', 'some', 'more']
Primitives, numeric types, les, enums and arrays thereof, are supported (they are converted using
StringGroovyMethods#asType(String, Class) (http://docs.groovy-lang.org/2.5.5/html/gapi/index.html?
org/codehaus/groovy/runtime/StringGroovyMethods.html#asType)).
Custom parsing of the argument String
If the supported types aren’t su cient, you can supply a closure to handle the String to rich type conversion for you. Here is a
sample using the dynamic api style:
argz = '''-a John -b Mary -d 2016-01-01 and some more'''.split()
cli = ()
lower = { it.toLowerCase() }
cli.a(convert: lower, 'a-arg')
cli.b(convert: { it.toUpperCase() }, 'b-arg')
cli.d(convert: { .parse('yyyy-MM-dd', it) }, 'd-arg')
options = cli.parse(argz)
options.a == 'john'
options.b == 'MARY'
options.d.format('dd-MMM-yyyy') == '01-Jan-2016'
options.arguments() == ['and', 'some', 'more']
Alternatively, you can use the annotation style by supplying the conversion closure as an annotation parameter. Here is an
example speci cation:
{
@Option(convert={ it.toLowerCase() }) a()
@Option(convert={ it.toUpperCase() }) b()
@Option(convert={ .parse("yyyy-MM-dd", it) }) d()
@Unparsed remaining()
}
http://docs.groovy-lang.org/latest/html/documentation/ 420/502
1/6/2019 And an example using that speci cation: Groovy Language Documentation
newYears = .parse("yyyy-MM-dd", "2016-01-01")
argz = '''-a John -b Mary -d 2016-01-01 and some more'''.split()
cli = ()
options = cli.parseFromSpec( , argz)
options.a() == 'john'
options.b() == 'MARY'
options.d() == newYears
options.remaining() == ['and', 'some', 'more']
Options with multiple arguments
Multiple arguments are also supported using an args value greater than 1. There is a special named parameter,
valueSeparator , which can also be optionally used when processing multiple arguments. It allows some additional exibility in
the syntax supported when supplying such argument lists on the commandline. For example, supplying a value separator of ','
allows a comma-delimited list of values to be passed on the commandline.
The args value is normally an integer. It can be optionally supplied as a String. There are two special String symbols: + and * .
The * value means 0 or more. The + value means 1 or more. The * value is the same as using + and also setting the
optionalArg value to true.
Accessing the multiple arguments follows a special convention. Simply add an 's' to the normal property you would use to access
the argument option and you will retrieve all the supplied arguments as a list. So, for a short option named 'a', you access the rst
'a' argument using options.a and the list of all arguments using options.as . It’s ne to have a shortname or longname ending
in 's' so long as you don’t also have the singular variant without the 's'. So, if name is one of your options with multiple arguments
and guess is another with a single argument, there will be no confusion using options.names and options.guess .
Here is an excerpt highlighting the use of multiple arguments:
// import CliBuilder not shown
cli = ()
cli.a(args: 2, 'a-arg')
cli.b(args: '2', valueSeparator: ',', 'b-arg') 1
cli.c(args: '+', valueSeparator: ',', 'c-arg') 2
options = cli.parse('-a 1 2 3 4'.split()) 3
options.a == '1' 4
options. == ['1', '2'] 5
options.arguments() == ['3', '4']
options = cli.parse('-a1 -a2 3'.split()) 6
options. == ['1', '2']
options.arguments() == ['3']
options = cli.parse(['-b1,2']) 7
options.bs == ['1', '2']
options = cli.parse(['-c', '1'])
options.cs == ['1']
options = cli.parse(['-c1'])
options.cs == ['1']
options = cli.parse(['-c1,2,3'])
options.cs == ['1', '2', '3']
1 Args value supplied as a String and comma value separator speci ed
2 One or more arguments are allowed
3 Two commandline parameters will be supplied as the 'b' option’s list of arguments
4 Access the 'a' option’s rst argument
5 Access the 'a' option’s list of arguments
6 An alternative syntax for specifying two arguments for the 'a' option
http://docs.groovy-lang.org/latest/html/documentation/ 421/502
1/6/2019 7 Groovy Language
The arguments to the 'b' option supplied as a comma-separated Documentation
value
As an alternative to accessing multiple arguments using the plural name approach, you can use an array-based type for the
option. In this case, all options will always be returned via the array which is accessed via the normal singular name. We’ll see an
example of this next when discussing types.
Multiple arguments are also supported using the annotation style of option de nition by using an array type for the annotated
class member (method or property) as this example shows:
{
@Option(numberOfArguments=2) [] a()
@Option(numberOfArgumentsString='2', valueSeparator=',') [] b()
@Option(numberOfArgumentsString='+', valueSeparator=',') [] c()
@Unparsed remaining()
}
And used as follows:
cli = ()
options = cli.parseFromSpec( , '-a 1 2 3 4'.split())
options.a() == ['1', '2']
options.remaining() == ['3', '4']
options = cli.parseFromSpec( , '-a1 -a2 3'.split())
options.a() == ['1', '2']
options.remaining() == ['3']
options = cli.parseFromSpec( , ['-b1,2'] [])
options.b() == ['1', '2']
options = cli.parseFromSpec( , ['-c', '1'] [])
options.c() == ['1']
options = cli.parseFromSpec( , ['-c1'] [])
options.c() == ['1']
options = cli.parseFromSpec( , ['-c1,2,3'] [])
options.c() == ['1', '2', '3']
Types and multiple arguments
Here is an example using types and multiple arguments with the dynamic api argument de nition style:
argz = '''-j 3 4 5 -k1.5,2.5,3.5 and some more'''.split()
cli = ()
cli.j(args: 3, type: [], 'j-arg')
cli.k(args: '+', valueSeparator: ',', type: [], 'k-arg')
options = cli.parse(argz)
options.js == [3, 4, 5] 1
options.j == [3, 4, 5] 1
options.k == [1.5, 2.5, 3.5]
options.arguments() == ['and', 'some', 'more']
1 For an array type, the trailing 's' can be used but isn’t needed
Setting a default value
Groovy makes it easy using the Elvis operator to provide a default value at the point of usage of some variable, e.g.
String x = someVariable ?: 'some default' . But sometimes you wish to make such a default part of the options
speci cation to minimise the interrogators work in later stages. CliBuilder supports the defaultValue property to cater for
this scenario.
Here is how you could use it using the dynamic api style:
http://docs.groovy-lang.org/latest/html/documentation/ 422/502
1/6/2019 Groovy Language Documentation
cli = ()
cli.f longOpt: 'from', type: , args: 1, defaultValue: 'one', 'f option'
cli.t longOpt: 'to', type: , defaultValue: '35', 't option'
options = cli.parse('-f two'.split())
options.hasOption('f')
options.f == 'two'
!options.hasOption('t')
options.t == 35
options = cli.parse('-t 45'.split())
!options.hasOption('from')
options. == 'one'
options.hasOption('to')
options.to == 45
Similarly, you might want such a speci cation using the annotation style. Here is an example using an interface speci cation:
{
@Option(shortName='f', defaultValue='one') ()
@Option(shortName='t', defaultValue='35') to()
}
Which would be used like this:
cli = ()
options = cli.parseFromSpec( , '-f two'.split())
options. () == 'two'
options.to() == 35
options = cli.parseFromSpec( , '-t 45'.split())
options. () == 'one'
options.to() == 45
You can also use the defaultValue annotation attribute when using annotations with an instance, though it’s probably just as
easy to provide an initial value for the property (or backing eld).
Use with TypeChecked
The dynamic api style of using CliBuilder is inherently dynamic but you have a few options should you want to make use of
Groovy’s static type checking capabilities. Firstly, consider using the annotation style, for example, here is an interface option
speci cation:
{
@Option name()
@Option age()
@Unparsed remaining()
}
And it can be used in combination with @TypeChecked as shown here:
@TypeChecked
testTypeCheckedInterface() {
argz = "--name John --age 21 and some more".split()
cli = ()
options = cli.parseFromSpec( , argz)
n = options.name()
a = options.age()
n == 'John' && a == 21
options.remaining() == ['and', 'some', 'more']
}
http://docs.groovy-lang.org/latest/html/documentation/ 423/502
1/6/2019 Secondly, there is a feature of the dynamic api style whichGroovy
o ers some support.
Language The de nition statements are inherently dynamic
Documentation
but actually return a value which we have ignored in earlier examples. The returned value is in fact a TypedOption<Type> and
special getAt support allows the options to be interrogated using the typed option, e.g. options[savedTypeOption] . So, if you
have statements similar to these in a non type checked part of your code:
cli = ()
< > age = cli.a(longOpt: 'age', type: , 'some age option')
Then, the following statements can be in a separate part of your code which is type checked:
args = '--age 21'.split()
options = cli.parse(args)
a = options[age]
a == 21
Finally, there is one additional convenience method o ered by CliBuilder to even allow the de nition part to be type checked.
It is a slightly more verbose method call. Instead of using the short name (the opt name) in the method call, you use a xed name
of option and supply the opt value as a property. You must also specify the type directly as shown in the following example:
groovy.cli.
groovy.transform.
@TypeChecked
testTypeChecked() {
cli = ()
< > name = cli.option( , opt: 'n', longOpt: 'name', 'name option')
< > age = cli.option( , longOpt: 'age', 'age option')
argz = "--name John --age 21 and some more".split()
options = cli.parse(argz)
n = options[name]
a = options[age]
n == 'John' && a == 21
options.arguments() == ['and', 'some', 'more']
}
Advanced CLI Usage
NOTE Advanced CLI features
CliBuilder can be thought of as a Groovy friendly wrapper on top of either picocli
(https://github.com/remkop/picocli) or Apache Commons CLI (https://commons.apache.org/proper/commons-cli/).
If there is a feature not provided by CliBuilder that you know is supported in the underlying library, the current
CliBuilder implementation (and various Groovy language features) make it easy for you to call the underlying
library methods directly. Doing so is a pragmatic way to leverage the Groovy-friendly syntax o ered by
CliBuilder and yet still access some of the underlying library’s advanced features. A word of caution however;
future versions of CliBuilder could potentially use another underlying library and in that event, some porting
work may be required for your Groovy classes and/or scripts.
Apache Commons CLI
As an example, here is some code for making use of Apache Commons CLI’s grouping mechanism:
org.apache.commons.cli.*
cli = ()
cli.f longOpt: 'from', 'f option'
cli.u longOpt: 'until', 'u option'
optionGroup = ()
optionGroup. {
addOption cli.option('o', [longOpt: 'output'], 'o option')
addOption cli.option('d', [longOpt: 'directory'], 'd option')
}
cli.options.addOptionGroup optionGroup
!cli.parse('-d -o'.split()) 1
http://docs.groovy-lang.org/latest/html/documentation/ 424/502
1/6/2019 1 Groovy
The parse will fail since only one option from a group Language
can be Documentation
used at a time.
Picocli
Below are some features available in the picocli version of CliBuilder .
New property: errorWriter
When users of your application give invalid command line arguments, CliBuilder writes an error message and the usage help
message to the stderr output stream. It doesn’t use the stdout stream to prevent the error message from being parsed when
your program’s output is used as input for another process. You can customize the destination by setting the errorWriter to a
di erent value.
On the other hand, CliBuilder.usage() prints the usage help message to the stdout stream. This way, when users request
help (e.g. with a --help parameter), they can pipe the output to a utility like less or grep .
You can specify di erent writers for testing. Be aware that for backwards compatibility, setting the writer property to a di erent
value will set both the writer and the errorWriter to the speci ed writer.
ANSI colors
The picocli version of CliBuilder renders the usage help message in ANSI colors on supported platforms automatically. If desired
you can customize (http://picocli.info/#_usage_help_with_styles_and_colors) this. (An example follows below.)
New property: name
As before, you can set the synopsis of the usage help message with the usage property. You may be interested in a small
improvement: if you only set the command name , a synopsis will be generated automatically, with repeating elements followed
by … and optional elements surrounded with [ and ] . (An example follows below.)
New property: usageMessage
This property exposes a UsageMessageSpec object from the underlying picocli library, which gives ne-grained control over
various sections of the usage help message. For example:
cli = ()
cli.name = "myapp"
cli.usageMessage. {
headerHeading("@|bold,underline Header heading:|@%n")
header("Header 1", "Header 2") // before the synopsis
synopsisHeading("%n@|bold,underline Usage:|@ ")
descriptionHeading("%n@|bold,underline Description heading:|@%n")
description("Description 1", "Description 2") // after the synopsis
optionListHeading("%n@|bold,underline Options heading:|@%n")
footerHeading("%n@|bold,underline Footer heading:|@%n")
footer("Footer 1", "Footer 2")
}
cli.a('option a description')
cli.b('option b description')
cli.c(args: '*', 'option c description')
cli.usage()
Gives this output:
http://docs.groovy-lang.org/latest/html/documentation/ 425/502
1/6/2019 Groovy Language Documentation
New property: parser
The parser property gives access to the picocli ParserSpec object that can be used to customize the parser behavior. See the
documentation (http://picocli.info/apidocs/picocli/CommandLine.Model.ParserSpec.html) for details.
Map options
Finally, if your application has options that are key-value pairs, you may be interested in picocli’s support for maps. For example:
java.util.concurrent.
java.util.concurrent. .DAYS
java.util.concurrent. .HOURS
cli = ()
cli.D(args: 2, valueSeparator: '=', 'the old way') 1
cli.X(type: , 'the new way') 2
cli.Z(type: , auxiliaryTypes: [ , ].toArray(), 'typed map') 3
options = cli.parse('-Da=b -Dc=d -Xx=y -Xi=j -ZDAYS=2 -ZHOURS=23'.split()) 4
options. == ['a', 'b', 'c', 'd'] 5
options. == [ 'x':'y', 'i':'j' ] 6
options. == [ (DAYS ):2, (HOURS ):23 ] 7
1 Previously, key=value pairs were split up into parts and added to a list
2 Picocli map support: simply specify Map as the type of the option
3 You can even specify the type of the map elements
4 To compare, let’s specify two key-value pairs for each option
5 Previously, all key-value pairs end up in a list and it is up to the application to work with this list
6 Picocli returns the key-value pairs as a Map
7 Both keys and values of the map can be strongly typed
ObjectGraphBuilder
ObjectGraphBuilder is a builder for an arbitrary graph of beans that follow the JavaBean convention. It is in particular useful for
creating test data.
Let’s start with a list of classes that belong to your domain:
http://docs.groovy-lang.org/latest/html/documentation/ 426/502
1/6/2019 Groovy Language Documentation
com.acme
{
name
address
employees = []
}
{
line1
line2
zip
state
}
{
name
employeeId
address
company
}
Then using ObjectGraphBuilder building a Company with three employees is as easy as:
builder = () 1
builder.classLoader = . .classLoader 2
builder.classNameResolver = "com.acme" 3
acme = builder.company(name: 'ACME') { 4
3.times {
employee(id: it.toString(), name: "Drone $it") { 5
address(line1:"Post street") 6
}
}
}
acme !=
acme
acme.name == 'ACME'
acme.employees.size() == 3
employee = acme.employees[0]
employee
employee.name == 'Drone 0'
employee.address
1 creates a new object graph builder
2 sets the classloader where the classes will be resolved
3 sets the base package name for classes to be resolved
4 creates a Company instance
5 with 3 Employee instances
6 each of them having a distinct Address
Behind the scenes, the object graph builder:
will try to match a node name into a Class , using a default ClassNameResolver strategy that requires a package name
then will create an instance of the appropriate class using a default NewInstanceResolver strategy that calls a no-arg
constructor
resolves the parent/child relationship for nested nodes, involving two other strategies:
RelationNameResolver will yield the name of the child property in the parent, and the name of the parent property in the
child (if any, in this case, Employee has a parent property aptly named company )
http://docs.groovy-lang.org/latest/html/documentation/ 427/502
1/6/2019 ChildPropertySetter will insert the child into theGroovy
parentLanguage
taking intoDocumentation
account if the child belongs to a Collection or not
(in this case employees should be a list of Employee instances in Company ).
All 4 strategies have a default implementation that work as expected if the code follows the usual conventions for writing
JavaBeans. In case any of your beans or objects do not follow the convention you may plug your own implementation of each
strategy. For example imagine that you need to build a class which is immutable:
@Immutable
{
name
age
}
Then if you try to create a Person with the builder:
person = builder.person(name:'Jon', age:17)
It will fail at runtime with:
Cannot set readonly property: name for class: com.acme.Person
Fixing this can be done by changing the new instance strategy:
builder.newInstanceResolver = { klazz, attributes ->
(klazz.getConstructor( )) {
o = klazz.newInstance(attributes)
attributes.clear()
o
}
klazz.newInstance()
}
ObjectGraphBuilder supports ids per node, meaning that you can store a reference to a node in the builder. This is useful when
multiple objects reference the same instance. Because a property named id may be of business meaning in some domain
models ObjectGraphBuilder has a strategy named IdentifierResolver that you may con gure to change the default name
value. The same may happen with the property used for referencing a previously saved instance, a strategy named
ReferenceResolver will yield the appropriate value (default is `refId'):
company = builder.company(name: 'ACME') {
address(id: 'a1', line1: '123 Groovy Rd', zip: 12345, state: 'JV') 1
employee(name: 'Duke', employeeId: 1, address: a1) 2
employee(name: 'John', employeeId: 2 ){
address( refId: 'a1' ) 3
}
}
1 an address can be created with an id
2 an employee can reference the address directly with its id
3 or use the refId attribute corresponding to the id of the corresponding address
Its worth mentioning that you cannot modify the properties of a referenced bean.
JmxBuilder
See Working with JMX - JmxBuilder for details.
FileTreeBuilder
FileTreeBuilder (http://docs.groovy-lang.org/2.5.5/html/gapi/index.html?groovy/util/FileTreeBuilder.html) is a builder for
generating a le directory structure from a speci cation. For example, to create the following tree:
http://docs.groovy-lang.org/latest/html/documentation/ 428/502
1/6/2019 Groovy Language Documentation
src/
|--- main
| |--- groovy
| |--- Foo.groovy
|--- test
|--- groovy
|--- FooTest.groovy
You can use a FileTreeBuilder like this:
tmpDir = .createTempDir()
fileTreeBuilder = (tmpDir)
fileTreeBuilder.dir('src') {
dir('main') {
dir('groovy') {
file('Foo.groovy', 'println "Hello"')
}
}
dir('test') {
dir('groovy') {
file('FooTest.groovy', 'class FooTest extends GroovyTestCase {}')
}
}
}
To check that everything worked as expected we use the following `assert`s:
(tmpDir, '/src/main/groovy/Foo.groovy').text == 'println "Hello"'
(tmpDir, '/src/test/groovy/FooTest.groovy').text == 'class FooTest extends
GroovyTestCase {}'
FileTreeBuilder also supports a shorthand syntax:
tmpDir = .createTempDir()
fileTreeBuilder = (tmpDir)
fileTreeBuilder.src {
main {
groovy {
'Foo.groovy'('println "Hello"')
}
}
test {
groovy {
'FooTest.groovy'('class FooTest extends GroovyTestCase {}')
}
}
}
This produces the same directory structure as above, as shown by these `assert`s:
(tmpDir, '/src/main/groovy/Foo.groovy').text == 'println "Hello"'
(tmpDir, '/src/test/groovy/FooTest.groovy').text == 'class FooTest extends
GroovyTestCase {}'
3.16. Working with JMX
3.16.1. Introduction
Given that Groovy sits directly on top of Java, Groovy can leverage the tremendous amount of work already done for JMX
(http://www.oracle.com/technetwork/java/javase/tech/javamanagement-140525.html) with Java. In addition, Groovy provides a
GroovyMBean class which makes an MBean look like a normal Groovy object. This simpli es Groovy code for interacting with
MBeans. For example, the following code:
http://docs.groovy-lang.org/latest/html/documentation/ 429/502
1/6/2019 Groovy Language Documentation
println server.getAttribute(beanName, 'Age')
server.setAttribute(beanName, ('Name', 'New name'))
[] = [5, 20]
[] signature = [ .TYPE, .TYPE]
println server.invoke(beanName, 'add', , signature)
can be simpli ed to:
mbean = (server, beanName)
println mbean.
mbean. = 'New name'
println mbean.add(5, 20)
The remainder of this page shows you how to:
Monitor the JVM using MXBeans
Monitor Apache Tomcat and display statistics
Monitor Oracle OC4J and display information
Monitor BEA WebLogic and display information
Leverage Spring’s MBean annotation support to export your Groovy beans as MBeans
3.16.2. Monitoring the JVM
MBeans are not accessed directly by an application but are managed by a repository called an MBean server. Java includes a
special MBean server called the platform MBean server, which is built into the JVM. Platform MBeans are registered in this server
using unique names.
You can monitor the JVM through its platform MBeans with the following code:
http://docs.groovy-lang.org/latest/html/documentation/ 430/502
1/6/2019 Groovy Language Documentation
java.lang.management.*
os = .operatingSystemMXBean
println """OPERATING SYSTEM:
\tarchitecture = $os.arch
\tname = $os.name
\tversion = $os.version
\tprocessors = $os.availableProcessors
"""
rt = .runtimeMXBean
println """RUNTIME:
\tname = $rt.name
\tspec name = $rt.specName
\tvendor = $rt.specVendor
\tspec version = $rt.specVersion
\tmanagement spec version = $rt.managementSpecVersion
"""
cl = .classLoadingMXBean
println """CLASS LOADING SYSTEM:
\tisVerbose = ${cl.isVerbose()}
\tloadedClassCount = $cl.loadedClassCount
\ttotalLoadedClassCount = $cl.totalLoadedClassCount
\tunloadedClassCount = $cl.unloadedClassCount
"""
comp = .compilationMXBean
println """COMPILATION:
\ttotalCompilationTime = $comp.totalCompilationTime
"""
mem = .memoryMXBean
heapUsage = mem.heapMemoryUsage
nonHeapUsage = mem.nonHeapMemoryUsage
println """MEMORY:
HEAP STORAGE:
\tcommitted = $heapUsage.committed
\tinit = $heapUsage.init
\tmax = $heapUsage.max
\tused = $heapUsage.used
NON-HEAP STORAGE:
\tcommitted = $nonHeapUsage.committed
\tinit = $nonHeapUsage.init
\tmax = $nonHeapUsage.max
\tused = $nonHeapUsage.used
"""
.memoryPoolMXBeans.each { mp ->
println "\tname: " + mp.name
[] mmnames = mp.memoryManagerNames
mmnames.each{ mmname ->
println "\t\tManager Name: $mmname"
}
println "\t\tmtype = $mp.type"
println "\t\tUsage threshold supported = " + mp.isUsageThresholdSupported()
}
println()
td = .threadMXBean
println "THREADS:"
td.allThreadIds.each { tid ->
println "\tThread name = ${td.getThreadInfo(tid).threadName}"
}
println()
println "GARBAGE COLLECTION:"
.garbageCollectorMXBeans.each { gc ->
http://docs.groovy-lang.org/latest/html/documentation/ 431/502
1/6/2019 println "\tname = $gc.name" Groovy Language Documentation
println "\t\tcollection count = $gc.collectionCount"
println "\t\tcollection time = $gc.collectionTime"
[] mpoolNames = gc.memoryPoolNames
mpoolNames.each { mpoolName ->
println "\t\tmpool name = $mpoolName"
}
}
When run, you will see something like this:
http://docs.groovy-lang.org/latest/html/documentation/ 432/502
1/6/2019 Groovy Language Documentation
OPERATING SYSTEM:
architecture = x86
name = Windows XP
version = 5.1
processors = 2
RUNTIME:
name = 620@LYREBIRD
spec name = Java Virtual Machine Specification
vendor = Sun Microsystems Inc.
spec version = 1.0
management spec version = 1.0
CLASS LOADING SYSTEM:
isVerbose = false
loadedClassCount = 919
totalLoadedClassCount = 919
unloadedClassCount = 0
COMPILATION:
totalCompilationTime = 91
MEMORY:
HEAP STORAGE:
committed = 3108864
init = 0
max = 66650112
used = 1994728
NON-HEAP STORAGE:
committed = 9240576
init = 8585216
max = 100663296
used = 5897880
name: Code Cache
Manager Name: CodeCacheManager
mtype = Non-heap memory
Usage threshold supported = true
name: Eden Space
Manager Name: MarkSweepCompact
Manager Name: Copy
mtype = Heap memory
Usage threshold supported = false
name: Survivor Space
Manager Name: MarkSweepCompact
Manager Name: Copy
mtype = Heap memory
Usage threshold supported = false
name: Tenured Gen
Manager Name: MarkSweepCompact
mtype = Heap memory
Usage threshold supported = true
name: Perm Gen
Manager Name: MarkSweepCompact
mtype = Non-heap memory
Usage threshold supported = true
THREADS:
Thread name = Monitor Ctrl-Break
Thread name = Signal Dispatcher
Thread name = Finalizer
Thread name = Reference Handler
Thread name = main
GARBAGE COLLECTION:
name = Copy
collection count = 60
collection time = 141
http://docs.groovy-lang.org/latest/html/documentation/ 433/502
1/6/2019 mpool name = Eden Space Groovy Language Documentation
mpool name = Survivor Space
name = MarkSweepCompact
collection count = 0
collection time = 0
mpool name = Eden Space
mpool name = Survivor Space
mpool name = Tenured Gen
mpool name = Perm Gen
3.16.3. Monitoring Tomcat
First start up Tomcat (http://tomcat.apache.org) with JMX monitoring enabled by setting the following:
JAVA_OPTS=- .sun.management.jmxremote - .sun.management.jmxremote.port=9004\
- .sun.management.jmxremote.authenticate= - .sun.management.jmxremote.ssl=
You can do this in your startup script and may choose any available port, we used 9004.
The following code uses JMX to discover the available MBeans in the running Tomcat, determine which are web modules, extract
the processing time for each web module and displays the result in a graph using JFreeChart:
groovy.swing.
javax.management.
javax.management.remote.
javax.management.remote.
javax.swing. WC
org.jfree.chart.
org.jfree.data.category.
org.jfree.chart.plot.
serverUrl = 'service:jmx:rmi:///jndi/rmi://localhost:9004/jmxrmi'
server = .connect( (serverUrl)).
serverInfo = (server, 'Catalina:type=Server').serverInfo
println "Connected to: $serverInfo"
query = ('Catalina:*')
[] allNames = server.queryNames(query, )
modules = allNames.findAll { name ->
name.contains('j2eeType=WebModule')
}.collect{ (server, it) }
println "Found ${modules.size()} web modules. Processing ..."
dataset = ()
modules.each { m ->
println m.name()
dataset.addValue m.processingTime, 0, m.path
}
labels = ['Time per Module', 'Module', 'Time']
options = [ , , ]
chart = .createBarChart(*labels, dataset,
.VERTICAL, *options)
swing = ()
frame = swing.frame(title:'Catalina Module Processing Time',
defaultCloseOperation:WC.EXIT_ON_CLOSE) {
panel(id:'canvas') { rigidArea(width:600, height:250) }
}
frame.pack()
frame.show()
chart.draw(swing.canvas.graphics, swing.canvas.bounds)
When run, we will see a trace of progress being made:
http://docs.groovy-lang.org/latest/html/documentation/ 434/502
1/6/2019 Groovy Language Documentation
Connected to: Apache Tomcat/6.0.13
Found 5 web modules. Processing ...
Catalina:j2eeType=WebModule,name=//localhost/,J2EEApplication=none,J2EEServer=none
Catalina:j2eeType=WebModule,name=//localhost/host-manager,J2EEApplication=none,J2EEServer=none
Catalina:j2eeType=WebModule,name=//localhost/docs,J2EEApplication=none,J2EEServer=none
Catalina:j2eeType=WebModule,name=//localhost/examples,J2EEApplication=none,J2EEServer=none
Catalina:j2eeType=WebModule,name=//localhost/manager,J2EEApplication=none,J2EEServer=none
The output will look like this:
Note: if you get errors running this script, see the Troubleshooting section below.
3.16.4. OC4J Example
Here is a script to access OC4J and print out some information about the server, its runtime and (as an example) the con gured
JMS destinations:
javax.management.remote.*
oracle.oc4j.admin.jmx.remote.api.
serverUrl = ('service:jmx:rmi://localhost:23791')
serverPath = 'oc4j:j2eeType=J2EEServer,name=standalone'
jvmPath = 'oc4j:j2eeType=JVM,name=single,J2EEServer=standalone'
provider = 'oracle.oc4j.admin.jmx.remote'
credentials = [
( .CREDENTIALS_LOGIN_KEY): 'oc4jadmin',
( .CREDENTIALS_PASSWORD_KEY): 'admin'
]
env = [
( .PROTOCOL_PROVIDER_PACKAGES): provider,
( .CREDENTIALS): credentials
]
server = .connect(serverUrl, env).
serverInfo = (server, serverPath)
jvmInfo = (server, jvmPath)
println """Connected to $serverInfo.node. \
Server started ${new Date(serverInfo.startTime)}.
OC4J version: $serverInfo.serverVersion from $serverInfo.serverVendor
JVM version: $jvmInfo.javaVersion from $jvmInfo.javaVendor
Memory usage: $jvmInfo.freeMemory bytes free, \
$jvmInfo.totalMemory bytes total
"""
query = javax.management. ('oc4j:*')
[] allNames = server.queryNames(query, )
dests = allNames.findAll { name ->
name.contains('j2eeType=JMSDestinationResource')
}.collect { (server, it) }
println "Found ${dests.size()} JMS destinations. Listing ..."
dests.each { d -> println "$d.name: $d.location" }
Here is the result of running this script:
http://docs.groovy-lang.org/latest/html/documentation/ 435/502
1/6/2019 Groovy Language Documentation
Connected to LYREBIRD. Server started Thu May 31 21:04:54 EST 2007.
OC4J version: 11.1.1.0.0 from Oracle Corp.
JVM version: 1.6.0_01 from Sun Microsystems Inc.
Memory usage: 8709976 bytes free, 25153536 bytes total
Found 5 JMS destinations. Listing ...
Demo Queue: jms/demoQueue
Demo Topic: jms/demoTopic
jms/Oc4jJmsExceptionQueue: jms/Oc4jJmsExceptionQueue
jms/RAExceptionQueue: jms/RAExceptionQueue
OracleASRouter_store: OracleASRouter_store
As a slight variation, this script displays a pie chart of memory usage using JFreeChart:
org.jfree.chart.
javax.swing. WC
javax.management.remote.*
oracle.oc4j.admin.jmx.remote.api.
url = 'service:jmx:rmi://localhost:23791'
credentials = [:]
credentials[ .CREDENTIALS_LOGIN_KEY] = "oc4jadmin"
credentials[ .CREDENTIALS_PASSWORD_KEY] = "password"
env = [:]
env[ .PROTOCOL_PROVIDER_PACKAGES] = "oracle.oc4j.admin.jmx.remote"
env[ .CREDENTIALS] = credentials
server = .connect( (url), env).
jvmInfo = (server, 'oc4j:j2eeType=JVM,name=single,J2EEServer=standalone')
piedata = org.jfree.data.general. ()
piedata.setValue "Free", jvmInfo.freeMemory
piedata.setValue "Used", jvmInfo.totalMemory - jvmInfo.freeMemory
options = [ , , ]
chart = .createPieChart('OC4J Memory Usage', piedata, *options)
chart.backgroundPaint = java.awt. .white
swing = groovy.swing. ()
frame = swing.frame(title:'OC4J Memory Usage', defaultCloseOperation:WC.EXIT_ON_CLOSE) {
panel(id:'canvas') { rigidArea(width:350, height:250) }
}
frame.pack()
frame.show()
chart.draw(swing.canvas.graphics, swing.canvas.bounds)
Which looks like:
3.16.5. WebLogic Example
This script prints out information about the server followed by information about JMS Destinations (as an example). Many other
mbeans are available (http://docs.oracle.com/cd/E13222_01/wls/docs90/wlsmbeanref/core/index.html).
http://docs.groovy-lang.org/latest/html/documentation/ 436/502
1/6/2019 Groovy Language Documentation
javax.management.remote.*
javax.management.*
javax.naming.
urlRuntime = '/jndi/weblogic.management.mbeanservers.runtime'
urlBase = 'service:jmx:t3://localhost:7001'
serviceURL = (urlBase + urlRuntime)
h = ()
h.put( .SECURITY_PRINCIPAL, 'weblogic')
h.put( .SECURITY_CREDENTIALS, 'weblogic')
h.put( .PROTOCOL_PROVIDER_PACKAGES, 'weblogic.management.remote')
server = .connect(serviceURL, h).
domainName =
('com.bea:Name=RuntimeService,Type=weblogic.management.mbeanservers.runtime.RuntimeServic
eMBean')
rtName = server.getAttribute(domainName, 'ServerRuntime')
rt = (server, rtName)
println "Server: name=$rt.Name, state=$rt.State, version=$rt.WeblogicVersion"
destFilter = .match( .attr('Type'), .value('JMSDestinationRuntime'))
server.queryNames( ('com.bea:*'), destFilter).each { name ->
jms = (server, name)
println "JMS Destination: name=$jms.Name, type=$jms.DestinationType,
messages=$jms.MessagesReceivedCount"
}
Here is the output:
Server: name=examplesServer, state=RUNNING, version=WebLogic Server 10.0 Wed May 9 18:10:27 EDT
2007 933139
JMS Destination: name=examples-jms!exampleTopic, type=Topic, messages=0
JMS Destination: name=examples-jms!exampleQueue, type=Queue, messages=0
JMS Destination: name=examples-jms!jms/MULTIDATASOURCE_MDB_QUEUE, type=Queue, messages=0
JMS Destination: name=examplesJMSServer!examplesJMSServer.TemporaryQueue0, type=Queue, messages=68
JMS Destination: name=examples-jms!quotes, type=Topic, messages=0
JMS Destination: name=examples-jms!weblogic.wsee.wseeExamplesDestinationQueue, type=Queue,
messages=0
JMS Destination: name=examples-jms!weblogic.examples.ejb30.ExampleQueue, type=Queue, messages=0
3.16.6. Spring Example
You can also use Spring to automatically register beans as JMX aware.
Here is an example class (Calculator.groovy):
http://docs.groovy-lang.org/latest/html/documentation/ 437/502
1/6/2019 Groovy Language Documentation
org.springframework.jmx. .annotation.*
@ManagedResource(objectName="bean:name=calcMBean", description="Calculator MBean")
{
invocations
@ManagedAttribute(description="The Invocation Attribute")
getInvocations() {
invocations
}
= 10
@ManagedAttribute(description="The Base to use when adding strings")
getBase() {
@ManagedAttribute(description="The Base to use when adding strings")
setBase( ) {
. =
}
@ManagedOperation(description="Add two numbers")
@ManagedOperationParameters([
@ManagedOperationParameter(name="x", description="The first number"),
@ManagedOperationParameter(name="y", description="The second number")])
add( x, y) {
invocations++
x + y
}
@ManagedOperation(description="Add two strings representing numbers of a particular base")
@ManagedOperationParameters([
@ManagedOperationParameter(name="x", description="The first number"),
@ManagedOperationParameter(name="y", description="The second number")])
addStrings( x, y) {
invocations++
result = .valueOf(x, ) + .valueOf(y, )
.toString(result, )
}
}
Here is the Spring con guration le (beans.xml):
http://docs.groovy-lang.org/latest/html/documentation/ 438/502
1/6/2019 Groovy Language Documentation
<?xml version="1.0" encoding="UTF-8"?>
xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-
beans.xsd"
id="mbeanServer"
class="org.springframework.jmx.support.MBeanServerFactoryBean"
name="locateExistingServerIfPossible" value="true"
id="exporter"
class="org.springframework.jmx.export.MBeanExporter"
name="assembler" ref="assembler"
name="namingStrategy" ref="namingStrategy"
name="beans"
key="bean:name=defaultCalcName" value-ref="calcBean"
name="server" ref="mbeanServer"
name="autodetect" value="true"
id="jmxAttributeSource"
class="org.springframework.jmx.export.annotation.AnnotationJmxAttributeSource"
<!-- will create management interface using annotation metadata -->
id="assembler"
class="org.springframework.jmx.export.assembler.MetadataMBeanInfoAssembler"
name="attributeSource" ref="jmxAttributeSource"
<!-- will pick up the ObjectName from the annotation -->
id="namingStrategy"
class="org.springframework.jmx.export.naming.MetadataNamingStrategy"
name="attributeSource" ref="jmxAttributeSource"
id="calcBean"
class="Calculator"
name="base" value="10"
Here is a script which uses this bean and con guration:
http://docs.groovy-lang.org/latest/html/documentation/ 439/502
1/6/2019 Groovy Language Documentation
org.springframework.context.support.
java.lang.management.
javax.management.
javax.management.
// get normal bean
ctx = ("beans.xml")
calc = ctx.getBean("calcBean")
.start {
// access bean via JMX, use a separate thread just to
// show that we could access remotely if we wanted
server = .platformMBeanServer
mbean = (server, 'bean:name=calcMBean')
sleep 1000
8 == mbean.add(7, 1)
mbean. = 8
'10' == mbean.addStrings('7', '1')
mbean. = 16
sleep 2000
println "Number of invocations: $mbean.Invocations"
println mbean
}
15 == calc.add(9, 6)
'11' == calc.addStrings('10', '1')
sleep 2000
'20' == calc.addStrings('1f', '1')
And here is the resulting output:
Number of invocations: 5
MBean Name:
bean:name=calcMBean
Attributes:
(rw) int Base
(r) int Invocations
Operations:
int add(int x, int y)
java.lang.String addStrings(java.lang.String x, java.lang.String y)
int getInvocations()
int getBase()
void setBase(int p1)
You can even attach to the process while it is running with jconsole
(http://docs.oracle.com/javase/1.5.0/docs/guide/management/jconsole.html). It will look something like:
http://docs.groovy-lang.org/latest/html/documentation/ 440/502
1/6/2019 Groovy Language Documentation
We started the Groovy application with the -Dcom.sun.management.jmxremote JVM argument.
See also:
Dynamic language beans in Spring
Using Spring Factories with Groovy
Spring JMX Documentation (http://static.springsource.org/spring/docs/3.2.x/spring-framework-reference/html/jmx.html)
3.16.7. Troubleshooting
java.lang.SecurityException
If you get the following error, your container’s JMX access is password protected:
java.lang.SecurityException: Authentication failed! Credentials required
To x that, add an environment with the credentials when connecting, like this (password has to be set before that):
jmxEnv =
(password != ) {
jmxEnv = [( .CREDENTIALS): ( [])["monitor", password]]
}
connector = .connect( (serverUrl), jmxEnv)
Details for the software you are trying to monitor/manage may di er slightly. Check out the other examples using credentials
above if appropriate (e.g. OC4J and WebLogic). If you still have troubles, you will have to consult the documentation for the
software you are trying to monitor/manage for details on how to provide credentials.
3.16.8. JmxBuilder
JmxBuilder is a Groovy-based domain speci c language for the Java Management Extension (JMX) API. It uses the builder
pattern (FactoryBuilder) to create an internal DSL that facilitates the exposure of POJO’s and Groovy beans as management
components via the MBean server. JmxBuilder hides the complexity of creating and exporting management beans via the JMX API
and provides a set of natural Groovy constructs to interact with the JMX infrastructure.
Instantiating JmxBuilder
To start using JmxBuilder, simply make sure the jar le is on your class path. Then you can do the following in your code:
http://docs.groovy-lang.org/latest/html/documentation/ 441/502
1/6/2019 Groovy Language Documentation
jmx = ()
That’s it! You are now ready to use the JmxBuilder.
NOTE
You can pass in an instance of your own MBeanServer to the builder (JmxBuilder(MBeanServer))
If no MBeanServer is speci ed, the builder instance will default to the underlying platform MBeanServer.
Once you have an instance of JmxBuilder, you are now ready to invoke any of its builder nodes.
JMX Connectors
Remote connectivity is a crucial part of the JMX architecture. JmxBuilder facilitates the creation of connector servers and
connector clients with a minimal amount of coding.
Connector Server
JmxBuilder.connectorServer() supports the full Connector api syntax and will let you specify properties, override the URL, specify
your own host, etc.
Syntax
jmx.connectorServer(
protocol:"rmi",
host:"...",
port:1099,
url:"...",
properties:[
"authenticate":true|false,
"passwordFile":"...",
"accessFile":"...",
"sslEnabled" : true | false
// any valid connector property
]
)
Note that the serverConnector node will accept four ServerConnector property aliases (authenticate, passwordFile,accessFile, and
sslEnabled). You can use these aliases or provided any of the RMI-supported properties.
Example - Connector Server (see correction below)
jmx.connectorServer(port: 9000).start()
The snippet above returns an RMI connector that will start listening on port 9000. By default, the builder will internally generate
URL "service:jmx:rmi:///jndi/rmi://localhost:9000/jmxrmi".
NOTE: Sadly you are as likely to get something like the following when attempting to run the previous snippet of code (example is
incomplete, see below):
Caught: java.io.IOException: Cannot bind to URL [rmi://localhost:9000/jmxrmi]:
javax.naming.ServiceUnavailableException [Root exception is java.rmi.ConnectException: Connection
refused to host: localhost; nested exception is:
?????? java.net.ConnectException: Connection refused]
??
This occurs on Mac and Linux (CentOS 5) with Groovy 1.6 installed. Perhaps there were assumptions made about the
con guration of the /etc/hosts le?
The correct example is shown below.
Connector Example (Corrected) - Connector Server
http://docs.groovy-lang.org/latest/html/documentation/ 442/502
1/6/2019 The example above does not create the RMI registry. So, in order Language
Groovy to export,Documentation
you have to rst export the RMI object registry (make
sure to import java.rmi.registry.LocateRegistry ).
java.rmi.registry.
//...
.createRegistry(9000)
jmx.connectorServer(port: 9000).start()
Connector Client
JmxBuilder.connectorClient() node lets you create JMX connector client object to connect to a JMX MBean Server.
Syntax
jmx.connectorClient (
protocol:"rmi",
host:"...",
port:1099,
url:"...",
)
Example - Client Connector
Creating a connector client can be done just as easily. With one line of code, you can create an instance of a JMX Connector Client
as shown below.
client = jmx.connectorClient(port: 9000)
client.connect()
You can then access the MBeanServerConnection associated with the connector using:
client.getMBeanServerConnection()
JmxBuilder MBean Export
You can export a Java object or a Groovy object with minimal coding. JmxBuilder will even nd and export dynamic Groovy
methods injected at runtime.
Implicit vs Explicit Descriptors
When using the builder, you can let JmxBuilder implicitly generate all of your MBean descriptor info. This is useful when you
want to write minimal code to quickly export your beans. You can also explicitly declare all descriptor info for the bean. This gives
you total control on how you want to describe every piece of information that you want to export for the underlying bean.
The JmxBuilder.export() Node
The JmxBuilder.export() node provides a container where all management entities to be exported to the MBeanServer are
placed. You can place one or more bean() or timer() nodes as children of the export() node. JmxBuilder will automatically batch
export the entities described by the nodes to the MBean server for management (see example below).
beans = jmx. {
bean( ())
bean( ())
bean( ())
}
In the code snippet above, JmxBuilder.export() will export three management beans to the MBean server.
JmxBuilder.export() Syntax
JmxBuilder.export() node supports the registrationPolicy parameter to specify how JmxBuilder will behave to resolve bean name
collision during MBean registration:
http://docs.groovy-lang.org/latest/html/documentation/ 443/502
1/6/2019 Groovy Language Documentation
jmx.export(policy:"replace|ignore|error")
or
jmx.export(regPolicy:"replace|ignore|error")
replace - JmxBuilder.export() will replace any bean already registered with the MBean during export.
ignore - The bean being exported will be ignored if the same bean is already registered.
error - JmxBuilder.export() throws an error upon bean name collision during registration.
Integration with GroovyMBean Class
When you export an MBean to the MBeanServer, JmxBuilder will return an instance of GroovyMBean representing the
management bean that have been exported by the builder. Nodes such as bean() and timer() will return an instances of
GroovyMBean when they are invoked. The export() node returns an array of all of GroovyMBean[] representing all managed
objects exported to the MBean server.
MBean Registration with JmxBuilder.bean()
This portion of this reference uses class RequestController to illustrate how to use JmxBuilder to export runtime management
beans. The class is for illustration purpose and can be a POJO or a Groovy bean.
RequestController
{
// constructors
() { () }
( resource) { }
// attributes
isStarted() { }
getRequestCount() { 0 }
getResourceCount() { 0 }
setRequestLimit( limit) { }
getRequestLimit() { 0 }
// operations
start() { }
stop() { }
putResource( name, resource) { }
makeRequest( res) { }
makeRequest() { }
}
Implicit Export
As mentioned earlier, you can use JmxBuilder’s exible syntax to export any POJO/POGO with no descriptor. The builder can
automatically describe all aspects of the management beans using implicit defaults. These default values can easily be overridden
as we’ll see in this in the next section.
The simplest way to export a POJO or POGO is listed below.
jmx. {
bean( (resource: "Hello World"))
}
What this does:
First, the JmxBuilder.export() node will export an MBean to the MBeanServer representing the declared POJO instance.
The builder will generate a default ObjectName for the MBean and all other MBean descriptor information.
JmxBuilder will automatically export all declared attributes (MBean getter/setters), constructors, and operations on the
instance.
The exported attributes will have read-only visibility.
Remember, JmxBuilder.export() returns an array of GroovyMBean[] objects for all exported instances. So, once you call
JmxBuilder.export(), you have immediate access to the underlying MBean proxy (via GroovyMBean).
http://docs.groovy-lang.org/latest/html/documentation/ 444/502
1/6/2019 JConsole view of Exported Bean Groovy Language Documentation
JmxBuilder.bean() Syntax
The JmxBuilder.bean() node supports an extensive set of descriptors to describe your bean for management. The JMX
MBeanServer uses these descriptors to expose meta data about the bean exposed for management.
http://docs.groovy-lang.org/latest/html/documentation/ 445/502
1/6/2019 Groovy Language Documentation
jmx.export {
bean(
target:bean instance,
name:ObjectName,
desc:"...",
attributes:"*",
attributes:[]
attributes:[ "AttrubuteName1","AttributeName2",...,"AttributeName_n" ]
attributes:[
"AttributeName":"*",
"AttributeName":[
desc:"...",
defaultValue:value,
writable:true|false,
editable:true|false,
onChange:{event-> // event handler}
]
],
constructors:"*",
constructors:[
"Constructor Name":[],
"Constructor Name":[ "ParamType1","ParamType2,...,ParamType_n" ],
"Constructor Name":[
desc:"...",
params:[
"ParamType1":"*",
"ParamType2":[desc:"...", name:"..."],...,
"ParamType_n":[desc:"...", name:"..."]
]
]
],
operations:"*",
operations:[ "OperationName1", "OperationName2",...,"OperationNameN" ],
operations:[
"OperationName1":"*",
"OperationName2":[ "type1","type2,"type3" ]
"OperationName3":[
desc:"...",
params:[
"ParamType1":"*"
"ParamType2":[desc:"...", name:"..."],...,
"ParamType_n":[desc:"...", name:"..."]
],
onInvoked:{event-> JmxBuilder.send(event:"", to:"")}
]
],
listeners:[
"ListenerName1":[event: "...", from:ObjectName, call:{event->}],
"ListenerName2":[event: "...", from:ObjectName, call:&methodPointer]
]
)
}
Instead of describing the entire node, the following section explore each attribute separately.
Bean() Node - Specifying MBean ObjectName
Using the bean() node descriptors, you can specify your own MBean ObjectName.
ctrl = (resource:"Hello World")
beans = jmx. {
bean(target: ctrl, name: "jmx.tutorial:type=Object")
}
http://docs.groovy-lang.org/latest/html/documentation/ 446/502
1/6/2019 The ObjectName can be speci ed as a String or an instance of theLanguage
Groovy ObjectName.
Documentation
Bean() Node - Attribute Export
JMX attributes are the setters and getters on the underlying bean. The JmxBuilder.bean() node provides several ways to exibly
describe and export MBean attributes. You can combine them however you want to achieve any level of attribute visibility. Let’s
take a look.
Export All Attributes with Wildcard "*"
The following code snippet will describe and export all attributes on the bean as read-only. JmxBuilder will use default values to
describe the attributes that exported for management.
objName = ("jmx.tutorial:type=Object")
beans = jmx. {
bean(target: (),
name: objName,
attributes: "*")
}
Export Attribute List
JmxBuilder will let you specify a list of attributes to export.
objName = ("jmx.tutorial:type=Object")
beans = jmx. {
bean(
target: (),
name: objName,
attributes: ["Resource", "RequestCount"]
)
}
In the snippet above, only the "Resource" and "RequestCount" attributes will be exported. Again, since no descriptors are
provided, JmxBuilder will use sensible defaults to describe the exported attributes.
Export Attribute with Explicit Descriptors
One of the strengths of JmxBuilder is its exibility in describing MBean. With the builder you can describe all aspects of the
MBeans attribute that you want to export to the MBeanServer (see syntax above).
objName = ("jmx.tutorial:type=Object")
beans = jmx. {
bean(
target: (),
name: objName,
attributes: [
"Resource": [desc: "The resource to request.", readable: , writable: ,
defaultValue: "Hello"],
"RequestCount": "*"
]
)
}
In the snippet above, attribute "Resource" is fully-described using all supported descriptors (i.e. desc, readable, writable,
defaultValue) for a JMX attribute. However, we use the wildcard to describe attribute RequestCount and it will be exported and
described using defaults.
Bean() Node - Constructor Export
JmxBuilder supports the explicit description and export of constructors de ned in the underlying bean. There are several
options available when exporting constructors. You can combine them however you want to achieve the desired level of
manageability.
Export all Constructors with "*"
You can use the builder’s special '""' notation to *export all constructors declared on the underlying bean. The builder will use
default values to describe the MBean constructors.
http://docs.groovy-lang.org/latest/html/documentation/ 447/502
1/6/2019 Groovy Language Documentation
objName = ("jmx.tutorial:type=Object")
beans = jmx. {
bean(
target: (),
name: objName,
constructors: "*"
)
}
Export Constructors using Parameter Descriptor
JmxBuilder lets you target speci c constructor to export by describing the parameter signature. This is useful when you have
several constructors with di erent parameter signature and you want to export speci c constructors.
objName = ("jmx.tutorial:type=Object")
beans = jmx. {
bean(
target: (),
name: objName,
constructors: [
"RequestController": ["Object"]
]
)
}
Here, JmxBuilder will export a constructor that takes one parameter of type "Object". Again, JmxBuilder will use default values
to ll in the description of the constructor and the parameters.
Export Constructor with Explicit Descriptors
JmxBuilder allows you to fully-describe the constructor that you want to target for export (see syntax above).
objName = ("jmx.tutorial:type=Object")
beans = jmx. {
bean(target: (), name: objName,
constructors: [
"RequestController": [
desc: "Constructor takes param",
: ["Object" : [name: "Resource", desc: "Resource for controller"]]
]
]
)
}
In the code above, JmxBuilder will target a constructor that takes one parameter for export to the MBeanServer. Notice how the
constructor can be fully-described using all optional descriptor keys including parameter descriptors.
Bean() Node - Operation Export
Similar to constructors, JmxBuilder supports the description and export of MBean operations using a exible notation (see above
for syntax). You can combine these notations however you want to achieve the level of operation manageability desired.
Export All Operations with "*"
You can use the builder’s special '""'' notation to *export all operations de ned on the bean to be exposed for management. The
builder will use default descriptor values for the operations being exported.
objName = ("jmx.tutorial:type=Object")
beans = jmx. {
bean(
target: (),
name: objName,
operations: "*"
)
}
http://docs.groovy-lang.org/latest/html/documentation/ 448/502
1/6/2019 In this snippet, JmxBuilder will export all bean operationsGroovy
and will use default
Language values to describe them in the MBeanServer.
Documentation
Export Operation List
JmxBuilder has a shorthand notation that lets you quickly target operations to be exported by providing a list of methods to
export.
objName = ("jmx.tutorial:type=Object")
beans = jmx. {
bean(
target: (),
name: objName,
operations: ["start", "stop"]
)
}
In the snippet above, the builder will only export methods start() and stop(). All other methods will be ignored. JmxBuilder will
use default descriptor values to describe the operations being exported.
Export Operations by Signature
Using JmxBuilder, you can target methods to export for management using the methods’s parameter signature. This is useful
when you want to distinguish methods with the same name that you want to export (i.e. stop() instead of stop(boolean)).
objName = ("jmx.tutorial:type=Object")
beans = jmx. {
bean(
target: (),
name: objName,
operations: [
"makeRequest": ["String"]
]
)
}
In the snippet above, JmxBuilder would select method makeRequest(String) to be exported instead of the other version
makeRequest() which takes no parameter. In this shorthand context, the signature is speci ed as a list of type (i.e. "String").
Export Operations with Explicit Descriptors
JmxBuilder supports detailed descriptors for bean operations. You can supply deep descriptor info about any operation on your
bean including a name, description, method parameters, parameter type, and parameter description.
objName = ("jmx.tutorial:type=Object")
beans = jmx. {
bean(target: (), name: objName,
operations: [
"start": [desc: "Starts request controller"],
"stop": [desc: "Stops the request controller"],
"setResource": [ : ["Object"]],
"makeRequest": [
desc: "Executes the request.",
: [
"String": [name: "Resource", desc: "The resource to request"]
]
]
]
)
}
The snippet above shows all of the ways JmxBuilder allows you to describe an operation targeted for management:
Operations start() and stop() are described by the "desc" key (this is enough since there are no params).
In operation setResource() uses of a shorthand version of params: to describe the parameters for the method.
makeRequest() uses the the extended descriptor syntax to describe all aspects of the operation.
http://docs.groovy-lang.org/latest/html/documentation/ 449/502
1/6/2019 Embedding Descriptor Groovy Language Documentation
JmxBuilder supports the ability to embed descriptors directly in your Groovy class. So, instead of wrapping your description
around the declared object (as we’ve seen here), you can embed your JMX descriptors directly in your class.
RequestControllerGroovy
{
// attributes
started
requestCount
resourceCount
requestLimit
resources
// operations
start() { }
stop(){ }
putResource( name, resource) { }
makeRequest( res) { }
makeRequest() { }
descriptor = [
name: "jmx.builder:type=EmbeddedObject",
operations: ["start", "stop", "putResource"],
attributes: "*"
]
}
// export
jmx. (
bean( ())
)
There are two things going on in the code above:
Groovy class RequestControllerGroovy is de ned and includes a static descriptor member. That member is used to declare a
JmxBuilder descriptor to describe member of the class targeted for JMX export.
The second part of the code shows how to use JmxBuilder to export that class for management.
Timer Export
JMX standards mandate that the implementation of the API makes available a timer service. Since JMX is a component-based
architecture, timers provide an excellent signalling mechanism to communicate to registered listener components in the
MBeanServer. JmxBuilder supports the creation and export of timers using the same easy syntax we’ve seen so far.
Timer Node Syntax
timer(
name:ObjectName,
event:"...",
message:"...",
data:dataValue
startDate:"now"|dateValue
period:"99d"|"99h"|"99m"|"99s"|99
occurrences:long
)
The timer() node supports several attributes:
name: - Required The quali ed JMX ObjectName instance (or String) for the timer.
event: - The JMX event type string that will be broadcast with every timing signal (default "jmx.builder.event").
message: - An optional string value that can be sent to listeners.
data: - An optional object that can be sent to listeners of timing signal.
startDate: - When to start timer. Set of valid values [ "now", date object ]. Default is "now"
http://docs.groovy-lang.org/latest/html/documentation/ 450/502
1/6/2019 period: - A timer’s period expressed as either a number of millisecond
Groovy LanguageorDocumentation
time unit (day, hour, minute, second). See description
below.
occurrences: - A number indicating the number of time to repeat timer. Default is forever.
Exporting a Timer
timer = jmx.timer(name: "jmx.builder:type=Timer", : "heartbeat", period: "1s")
timer.start()
This snippet above describes, creates, and exports a standard JMX Timer component. Here, the timer() node returns a
GroovyMBean that represents the registered timer MBean in the MBeanServer.
An alternative way of exporting timers is within the JmxBuilder.export() node.
beans = jmx. {
timer(name: "jmx.builder:type=Timer1", : "event.signal", period: "1s")
timer(name: "jmx.builder:type=Timer2", : "event.log", period: "1s")
}
beans[0].start()
beans[1].start()
Timer Period
The timer() node supports a exible notation for specifying the timer period values. You can specify the time in second, minutes,
hour, and day. The default is millisecond.
timer(period: 100) = 100 millisecond
timer(period: "1s") = 1 second
timer(period: "1m") = 1 minute
timer(period: "1h") = 1 hour
timer(period: "1d") = 1 day
The node will automatically translate.
JmxBuilder and Events
An integral part of JMX is its event model. Registered management beans can communicate with each other by broadcasting
events on the MBeanServer’s event bus. JmxBuilder provides several ways to easily listen and react to events broadcasted on
the MBeanServer’s event bus. Developers can capture any event on the bus or throw their own to be consumed by other
components registered on the MBeanServer.
Event Handling Closures
JmxBuilder leverages Groovy’s use of closures to provide simple, yet elegant, mean of reacting to JMX events. JmxBuilder supports
two closure signatures:
Parameterless
callback = { ->
// event handling code here.
}
JmxBuilder executes the closure and passes no information about the event that was captured on the bus.
With Event Parameter
callback = { ->
// event handling code
}
JmxBuilder will pass an "event" object to the closure using this format. The event object contains information about the event
was intercepted so that it can be handled by the handler. The parameter will contain di erent set of info depending on the event
that was captured.
Handling Attribute onChange Event
http://docs.groovy-lang.org/latest/html/documentation/ 451/502
1/6/2019 When describing attributes (see bean() node section above), you can
Groovy provide
Language a closure (or method pointer) for callback to be
Documentation
executed when the value of the attribute is updated on the exported MBean. This gives developers an opportunity to listen to
and react to state changes on the MBean.
jmx. {
bean(
target: (), name: "jmx.tutorial:type=Object",
attributes: [
"Resource": [
readable: , writable: ,
onChange: { e ->
println e.oldValue
println e.newValue
}
]
]
)
}
The sample snippet above shows how to specify an "onChange" callback closure when describing MBean attributes. In this
sample code, whenever attribute "Resource" is updated via the exported MBean, the onChange event will be executed.
Attribute onChange Event Object
When handling the attribute onChange event, the handler closure will receive an event object with the following info:
event.oldValue - the previous attribute value before the change event.
event.newValue - the new value of the attribute after the change.
event.attribute - the name of the attribute on which the event occurred.
event.attributeType - the data type of the attribute that causes the event.
event.sequenceNumber - a numeric value representing the sequence number of event.
event.timeStamp - a time stamp for the event occurrence.
Handling Operation onCall Event
Similar to mbean attributes, JmxBuilder a ords developers the ability to listen for operation invocation on an MBean registered
in the MBeaServer. JmxBuilder accepts a callback closure that will be executed after the MBean method has invoked.
{
handleStart(e){
println e
}
}
handler = ()
beans = jmx. {
bean(target: (), name: "jmx.tutorial:type=Object",
operations: [
"start": [
desc:"Starts request controller",
onCall:handler.&handleStart
]
]
)
}
The snippet above shows how to declare an "onCall" closure to be used as listener when operation "start()" is invoked on the
MBean. This sample uses the method pointer syntax to illustrate the versatility of JmxBuilder.
Operation onCall Event Object
When handling the operation onCall event, the callback closure will receive an event object with the following info:
http://docs.groovy-lang.org/latest/html/documentation/ 452/502
1/6/2019 event.event - the event type string that was broadcasted.
Groovy Language Documentation
event.source - The object on which the method was invoked.
event.data - the data type of the attribute that causes the event.
event.sequenceNumber - a numeric value representing the sequence number of event.
event.timeStamp - a time stamp for the event occurrence.
Listener MBean
When you export an MBean with the bean() node, you can de ne events the MBean can listen and react to. The bean() node
provides a "listeners:" attribute that lets you de ne event listeners that your bean can react to.
beans = jmx. {
timer(name: "jmx.builder:type=Timer", : "heartbeat", period: "1s").start()
bean(target: (), name: "jmx.tutorial:type=Object",
operations: "*",
listeners: [
heartbeat: [
: "jmx.builder:type=Timer",
call: { e ->
println e
}
]
]
)
}
In the sample above, we see the syntax for adding listeners to an exported MBean.
Fist, a timer is exported and started.
Then an MBean is declared that will listen to the timer event and do something meaningful.
The "heartbeat:" name is arbitrary and has no correlation to the timer declared above.
The source of the event is speci ed using the "from:" attribute.
You can also specify an event type you are interested in receiving from a broadcaster (since a broadcaster can be emitting
multiple events).
Listening to JMX Events
In some cases, you will want to create stand-alone event listeners (not attached to exported MBeans). JmxBuilder provides the
Listener() node to let you create JMX listeners that can listen to MBeanServer events. This is useful when creating JMX client
applications to monitor/manage JMX agents on remote JMX MBeanServers.
Listener Node Syntax
jmx.listener(
event: "...",
from: "object name" | ObjectName,
call: { event-> }
)
Here is the description of the listener() node attributes:
event: An optional string that identi es the JMX event type to listen for.
from (required): The JMX ObjectName of the component to listen to. This can be speci ed as a string or an instance of
ObjectName
call: The closure to execute when the event is captured. This can also be speci ed as a Groovy method pointer.
Here is an example of JmxBuilder’s listener node:
http://docs.groovy-lang.org/latest/html/documentation/ 453/502
1/6/2019 Groovy Language Documentation
jmx.timer(name: "jmx.builder:type=Timer", period: "1s").start()
jmx.listener(
: "jmx.builder:type=Timer",
call: { e ->
println "beep..."
}
)
This example shows how you can use a stand alone listener (outside of an MBean export). Here, we export a timer with a 1
second resolution. Then, we specify a listener to that timer that will print "beep" every second.
Emitting JMX Events
JmxBuilder provides the tools needed to broadcast your own events on the MBeanServer’s event bus. There are no restrictions
on the event type you can broadcast. You simply declare your emitter and the event type that you want to send, then broadcast
your event at any time. Any registered component in the MBeanServer can register themselves to listen to your events.
Emitter Syntax
jmx.emitter(name:"Object:Name", event:"type")
The attributes for the node Emitter() can be summarized as follows:
name: an optional JMX ObjectName used to register your emitter in the MBeanServer. Default is
jmx.builder:type=Emitter,name=Emitter@OBJECT_HASH_VALUE
event: an option string value that describes the JMX event type. Default is "jmx.builder.event.emitter".
Declare the Emitter
emitter = jmx.emitter()
The snippet declares the emitter using implicit descriptor syntax. JmxBuilder will do the followings:
Create and register an emitter MBean with a default ObjectName.
Setup a default event type with value "jmx.builder.event.emitter".
Return a GroovyMBean representing the emitter.
As with other nodes in the builder, you can override all keys in the emitter() node. You can specify the ObjectName and the
event type.
Broadcast Event
Once you have declared your emitter, you can broadcast your event.
emitter.send()
The sample above shows the emitter sending an event, once it has been declared. Any JMX component registered in the
MBeanServer can register to receive message from this emitter.
Sending Event Objects
You can optionally pass data to the receiver when you send the message.
emitter.send("Hello!")
If you use an event listener closure (see above) that accepts a parameter, you can access that value.
3.16.9. Further JMX Information
Monitoring the Java Virtual Machine (http://www.ddj.com/dept/java/184406481?pgno=1)
Using Groovy for System Management (http://buttso.blogspot.com/2006/05/using-groovy-for-system-management.html)
Groovier jconsole! (https://blogs.oracle.com/sundararajan/entry/groovier_jconsole)
http://docs.groovy-lang.org/latest/html/documentation/ 454/502
1/6/2019 JMX Scripts with Eclipse Monkey (http://jmesnil.net/weblog/2007/05/23/jmx-scripts-with-eclipse-monkey)
Groovy Language Documentation
Using JMX to monitor Apache ActiveMQ (http://activemq.apache.org/jmx.html)
3.17. Creating Swing UIs
Creating Swing UIs is made easy thanks to the use of SwingBuilder.
3.18. Security
(TBD)
3.19. Design patterns in Groovy
Using design patterns (http://en.wikipedia.org/wiki/Design_pattern_%28computer_science%29) with Java is a well-established
topic. Design patterns also apply to Groovy:
some patterns carry over directly (and can make use of normal Groovy syntax improvements for greater readability)
some patterns are no longer required because they are built right into the language or because Groovy supports a better way
of achieving the intent of the pattern
some patterns that have to be expressed at the design level in other languages can be implemented directly in Groovy (due to
the way Groovy can blur the distinction between design and implementation)
3.19.1. Patterns
Abstract Factory Pattern
The Abstract Factory Pattern (http://en.wikipedia.org/wiki/Abstract_factory_pattern) provides a way to encapsulate a group of
individual factories that have a common theme. It embodies the intent of a normal factory, i.e. remove the need for code using an
interface to know the concrete implementation behind the interface, but applies to a set of interfaces and selects an entire family
of concrete classes which implement those interfaces.
As an example, I might have interfaces Button, TextField and Scrollbar. I might have WindowsButton, MacButton, FlashButton as
concrete classes for Button. I might have WindowsScrollBar, MacScrollBar and FlashScrollBar as concrete implementations for
ScrollBar. Using the Abstract Factory Pattern should allow me to select which windowing system (i.e. Windows, Mac, Flash) I want
to use once and from then on should be able to write code that references the interfaces but is always using the appropriate
concrete classes (all from the one windowing system) under the covers.
Example
Suppose we want to write a game system. We might note that many games have very similar features and control.
We decide to try to split the common and game-speci c code into separate classes.
First let’s look at the game-speci c code for a Two-up (http://en.wikipedia.org/wiki/Two-Up) game:
http://docs.groovy-lang.org/latest/html/documentation/ 455/502
1/6/2019 Groovy Language Documentation
{
welcome = 'Welcome to the twoup game, you start with $1000'
= 'Sorry, you have no money left, goodbye'
}
{
convert(input) { input.toInteger() }
}
{
money = 1000
random = ()
tossWasHead() {
= random.nextInt()
% 2 == 0
}
moreTurns() {
(money > 0) {
println "You have $money, how much would you like to bet?"
}
play(amount) {
coin1 = tossWasHead()
coin2 = tossWasHead()
(coin1 && coin2) {
money += amount
println 'You win'
} (!coin1 && !coin2) {
money -= amount
println 'You lose'
} {
println 'Draw'
}
}
}
Now, let’s look at the game-speci c code for a number guessing game:
http://docs.groovy-lang.org/latest/html/documentation/ 456/502
1/6/2019 Groovy Language Documentation
{
welcome = 'Welcome to the guessing game, my secret number is between 1 and 100'
= 'Correct'
}
{
convert(input) { input.toInteger() }
}
{
lower = 1
upper = 100
guess = ().nextInt(upper - lower) + lower
moreTurns() {
= (lower == guess || upper == guess)
(! ) {
println "Enter a number between $lower and $upper"
}
!
}
play(nextGuess) {
(nextGuess <= guess) {
lower = [lower, nextGuess].max()
}
(nextGuess >= guess) {
upper = [upper, nextGuess].min()
}
}
}
Now, let’s write our factory code:
guessFactory = [messages: , control: , converter:
]
twoupFactory = [messages: , control: , converter: ]
{
factory
getMessages() { factory.messages.newInstance() }
getControl() { factory.control.newInstance() }
getConverter() { factory.converter.newInstance() }
}
The important aspect of this factory is that it allows selection of an entire family of concrete classes.
Here is how we would use the factory:
.factory = twoupFactory
messages = .messages
control = .control
converter = .converter
println messages.welcome
reader = ( ( . ))
(control.moreTurns()) {
input = reader.readLine().trim()
control.play(converter.convert(input))
}
println messages.
Note that the rst line con gures which family of concrete game classes we will use. It’s not important that we selected which
family to use by using the factory property as shown in the rst line. Other ways would be equally valid examples of this pattern.
For example, we may have asked the user which game they wanted to play or determined which game from an environment
setting.
http://docs.groovy-lang.org/latest/html/documentation/ 457/502
1/6/2019 With the code as shown, the game might look like this when run: Language Documentation
Groovy
Welcome to the twoup game, you start with $1000
You have 1000, how much would you like to bet?
300
Draw
You have 1000, how much would you like to bet?
700
You win
You have 1700, how much would you like to bet?
1700
You lose
Sorry, you have no money left, goodbye
If we change the rst line of the script to GameFactory.factory = guessFactory, then the sample run might look like this:
Welcome to the guessing game, my secret number is between 1 and 100
Enter a number between 1 and 100
75
Enter a number between 1 and 75
35
Enter a number between 1 and 35
15
Enter a number between 1 and 15
5
Enter a number between 5 and 15
10
Correct
Adapter Pattern
The Adapter Pattern (http://en.wikipedia.org/wiki/Adapter_pattern) (sometimes called the wrapper pattern) allows objects
satisfying one interface to be used where another type of interface is expected. There are two typical avours of the pattern: the
delegation avour and the inheritance avour.
Delegation Example
Suppose we have the following classes:
{
width
}
{
radius
}
{
radius
pegFits(peg) {
peg.radius <= radius
}
toString() { "RoundHole with radius $radius" }
}
We can ask the RoundHole class if a RoundPeg ts in it, but if we ask the same question for a SquarePeg , then it will fail because
the SquarePeg class doesn’t have a radius property (i.e. doesn’t satisfy the required interface).
To get around this problem, we can create an adapter to make it appear to have the correct interface. It would look like this:
http://docs.groovy-lang.org/latest/html/documentation/ 458/502
1/6/2019 Groovy Language Documentation
{
peg
getRadius() {
.sqrt(((peg.width / 2) ** 2) * 2)
}
toString() {
"SquarePegAdapter with peg width $peg.width (and notional radius $radius)"
}
}
We can use the adapter like this:
hole = (radius: 4.0)
(4..7).each { w ->
peg = (peg: (width: w))
(hole.pegFits(peg)) {
println "peg $peg fits in hole $hole"
} {
println "peg $peg does not fit in hole $hole"
}
}
Which results in the following output:
peg SquarePegAdapter with peg width 4 (and notional radius 2.8284271247461903) fits in hole
RoundHole with radius 4.0
peg SquarePegAdapter with peg width 5 (and notional radius 3.5355339059327378) fits in hole
RoundHole with radius 4.0
peg SquarePegAdapter with peg width 6 (and notional radius 4.242640687119285) does not fit in hole
RoundHole with radius 4.0
peg SquarePegAdapter with peg width 7 (and notional radius 4.949747468305833) does not fit in hole
RoundHole with radius 4.0
Inheritance Example
Let’s consider the same example again using inheritance. First, here are the original classes (unchanged):
{
width
}
{
radius
}
{
radius
pegFits(peg) {
peg.radius <= radius
}
toString() { "RoundHole with radius $radius" }
}
An adapter using inheritance:
{
getRadius() {
.sqrt(((width / 2) ** 2) * 2)
}
toString() {
"SquarePegAdapter with width $width (and notional radius $radius)"
}
}
http://docs.groovy-lang.org/latest/html/documentation/ 459/502
1/6/2019 Using the adapter: Groovy Language Documentation
hole = (radius: 4.0)
(4..7).each { w ->
peg = (width: w)
(hole.pegFits(peg)) {
println "peg $peg fits in hole $hole"
} {
println "peg $peg does not fit in hole $hole"
}
}
The output:
peg SquarePegAdapter with width 4 (and notional radius 2.8284271247461903) fits in hole RoundHole
with radius 4.0
peg SquarePegAdapter with width 5 (and notional radius 3.5355339059327378) fits in hole RoundHole
with radius 4.0
peg SquarePegAdapter with width 6 (and notional radius 4.242640687119285) does not fit in hole
RoundHole with radius 4.0
peg SquarePegAdapter with width 7 (and notional radius 4.949747468305833) does not fit in hole
RoundHole with radius 4.0
Adapting using Closures
As a variation of the previous examples, we could instead de ne the following interface:
{
getRadius()
}
We can then de ne an adapter as a closure as follows:
adapter = {
p -> [getRadius: { .sqrt(((p.width / 2) ** 2) * 2) }]
}
And use it like this:
peg = (width: 4)
(hole.pegFits(adapter(peg))) {
// ... as before
}
Adapting using the ExpandoMetaClass
As of Groovy 1.1, there is a built-in MetaClass which can automatically add properties and methods dynamically.
Here is how the example would work using that feature:
peg = (width: 4)
peg.metaClass.radius = .sqrt(((peg.width / 2) ** 2) * 2)
After you create a peg object, you can simply add a property to it on the y. No need to change the original class and no need for
an adapter class.
Bouncer Pattern
The Bouncer Pattern (http://www.c2.com/cgi/wiki?BouncerPattern) describes usage of a method whose sole purpose is to either
throw an exception (when particular conditions hold) or do nothing. Such methods are often used to defensively guard pre-
conditions of a method.
http://docs.groovy-lang.org/latest/html/documentation/ 460/502
1/6/2019 When writing utility methods, you should always guard against
Groovyfaulty input Documentation
Language arguments. When writing internal methods, you may
be able to ensure that certain pre-conditions always hold by having su cient unit tests in place. Under such circumstances, you
may reduce the desirability to have guards on your methods.
Groovy di ers from other languages in that you frequently use the assert method within your methods rather than having a
large number of utility checker methods or classes.
Null Checking Example
We might have a utility method such as:
{
check(name, arg) {
(arg == ) {
(name + ' is null')
}
}
}
And we would use it like this:
doStuff( name, value) {
.check('name', name)
.check('value', value)
// do stuff
}
But a more Groovy way to do this would simply be like this:
doStuff( name, value) {
name != , 'name should not be null'
value != , 'value should not be null'
// do stuff
}
Validation Example
As an alternative example, we might have this utility method:
{
NUMBER_PATTERN = "\\\\d+(\\\\.\\\\d+(E-?\\\\d+)?)?"
isNumber(str) {
(!str ==~ NUMBER_PATTERN) {
("Argument '$str' must be a number")
}
}
isNotZero(number) {
(number == 0) {
('Argument must not be 0')
}
}
}
And we would use it like this:
http://docs.groovy-lang.org/latest/html/documentation/ 461/502
1/6/2019 Groovy Language Documentation
stringDivide( dividendStr, divisorStr) {
.isNumber(dividendStr)
.isNumber(divisorStr)
dividend = dividendStr.toDouble()
divisor = divisorStr.toDouble()
.isNotZero(divisor)
dividend / divisor
}
println stringDivide('1.2E2', '3.0')
// => 40.0
But with Groovy we could just as easily use:
stringDivide( dividendStr, divisorStr) {
dividendStr =~ .NUMBER_PATTERN
divisorStr =~ .NUMBER_PATTERN
dividend = dividendStr.toDouble()
divisor = divisorStr.toDouble()
divisor != 0, 'Divisor must not be 0'
dividend / divisor
}
Chain of Responsibility Pattern
In the Chain of Responsibility Pattern, objects using and implementing an interface (one or more methods) are intentionally
loosely coupled. A set of objects that implement the interface are organised in a list (or in rare cases a tree). Objects using the
interface make requests from the rst implementor object. It will decide whether to perform any action itself and whether to pass
the request further down the line in the list (or tree). Sometimes a default implementation for some request is also coded into the
pattern if none of the implementors respond to the request.
Example
In this example, the script sends requests to the lister object. The lister points to a UnixLister object. If it can’t handle the
request, it sends the request to the WindowsLister . If it can’t handle the request, it sends the request to the DefaultLister .
http://docs.groovy-lang.org/latest/html/documentation/ 462/502
1/6/2019 Groovy Language Documentation
{
nextInLine
( ) { nextInLine = }
listFiles(dir) {
( .getProperty('os.name') == 'Linux') {
println "ls $dir".execute().text
} {
nextInLine.listFiles(dir)
}
}
}
{
nextInLine
( ) { nextInLine = }
listFiles(dir) {
( .getProperty('os.name') == 'Windows XP') {
println "cmd.exe /c dir $dir".execute().text
} {
nextInLine.listFiles(dir)
}
}
}
{
listFiles(dir) {
(dir).eachFile { f -> println f }
}
}
lister = ( ( ()))
lister.listFiles('Downloads')
The output will be a list of les (with slightly di erent format depending on the operating system).
Here is a UML representation:
Variations to this pattern:
we could have an explicit interface, e.g. Lister , to statically type the implementations but because of duck-typing this is
optional
we could use a chain tree instead of a list, e.g. if (animal.hasBackbone()) delegate to VertebrateHandler else delegate
to InvertebrateHandler
we could always pass down the chain even if we processed a request
we could decide at some point to not respond and not pass down the chain
we could use Groovy’s meta-programming capabilities to pass unknown methods down the chain
Composite Pattern
http://docs.groovy-lang.org/latest/html/documentation/ 463/502
1/6/2019 The Composite Pattern (http://en.wikipedia.org/wiki/Composite_pattern)
Groovy Language allows you to treat single instances of an object the same
Documentation
way as a group of objects. The pattern is often used with hierarchies of objects. Typically, one or more methods should be callable
in the same way for either leaf or composite nodes within the hierarchy. In such a case, composite nodes typically invoke the
same named method for each of their children nodes.
Example
Consider this usage of the composite pattern where we want to call toString() on either Leaf or Composite objects.
In Java, the Component class is essential as it provides the type used for both leaf and composite nodes. In Groovy, because of
duck-typing, we don’t need it for that purpose, however, it can still server as a useful place to place common behaviour between
the leaf and composite nodes.
For our purposes, we will assemble the following hierarchy of components.
Here is the code:
http://docs.groovy-lang.org/latest/html/documentation/ 464/502
1/6/2019 Groovy Language Documentation
{
name
toString(indent) {
("-" * indent) + name
}
}
{
children = []
toString(indent) {
s = .toString(indent)
children.each { child ->
s += "\\n" + child.toString(indent + 1)
}
s
}
leftShift(component) {
children << component
}
}
{ }
root = (name: "root")
root << (name: "leaf A")
comp = (name: "comp B")
root << comp
root << (name: "leaf C")
comp << (name: "leaf B1")
comp << (name: "leaf B2")
println root.toString(0)
Here is the resulting output:
root
-leaf A
-comp B
--leaf B1
--leaf B2
-leaf C
Decorator Pattern
The Decorator Pattern (http://en.wikipedia.org/wiki/Decorator_pattern) provides a mechanism to embellish the behaviour of an
object without changing its essential interface. A decorated object should be able to be substituted wherever the original (non-
decorated) object was expected. Decoration typically does not involve modifying the source code of the original object and
decorators should be able to be combined in exible ways to produce objects with several embellishments.
Traditional Example
Suppose we have the following Logger class.
{
log( message) {
println message
}
}
There might be times when it is useful to timestamp a log message, or times when we might want to change the case of the
message. We could try to build all of this functionality into our Logger class. If we did that, the Logger class would start to be
very complex. Also, everyone would obtain all of features even when they might not want a small subset of the features. Finally,
feature interaction would become quite di cult to control.
To overcome these drawbacks, we instead de ne two decorator classes. Uses of the Logger class are free to embellish their base
logger with zero or more decorator classes in whatever order they desire. The classes look like this:
http://docs.groovy-lang.org/latest/html/documentation/ 465/502
1/6/2019 Groovy Language Documentation
{
logger
(logger) {
.logger = logger
}
log( message) {
now = .instance
logger.log("$now.time: $message")
}
}
{
logger
(logger) {
.logger = logger
}
log( message) {
logger.log(message.toUpperCase())
}
}
We can use the decorators like so:
logger = ( ( ()))
logger.log("G'day Mate")
// => Tue May 22 07:13:50 EST 2007: G'DAY MATE
You can see that we embellish the logger behaviour with both decorators. Because of the order we chose to apply the decorators,
our log message comes out capitalised and the timestamp is in normal case. If we swap the order around, let’s see what happens:
logger = ( ( ()))
logger.log('Hi There')
// => TUE MAY 22 07:13:50 EST 2007: HI THERE
Now the timestamp itself has also been changed to be uppercase.
A touch of dynamic behaviour
Our previous decorators were speci c to Logger objects. We can use Groovy’s Meta-Object Programming capabilities to create a
decorator which is far more general purpose in nature. Consider this class:
( ) {
. =
}
invokeMethod( name, args) {
newargs = args.collect { arg ->
(arg ) {
arg.toLowerCase()
} {
arg
}
}
.invokeMethod(name, newargs)
}
}
It takes any class and decorates it so that any String method parameter will automatically be changed to lower case.
logger = ( ( ()))
logger.log('IMPORTANT Message')
// => Tue May 22 07:27:18 EST 2007: important message
http://docs.groovy-lang.org/latest/html/documentation/ 466/502
1/6/2019 Just be careful with ordering here. The original decoratorsGroovy
were restricted
LanguagetoDocumentation
decorating Logger objects. This decorator works
with any object type, so we can’t swap the ordering around, i.e. this won’t work:
// Can't mix and match Interface-Oriented and Generic decorators
// logger = new TimeStampingLogger(new GenericLowerDecorator(new Logger()))
We could overcome this limitation be generating an appropriate Proxy type at runtime but we won’t complicate the example here.
Runtime behaviour embellishment
You can also consider using the ExpandoMetaClass from Groovy 1.1 to dynamically embellish a class with behaviour. This isn’t
the normal style of usage of the decorator pattern (it certainly isn’t nearly as exible) but may help you to achieve similar results in
some cases without creating a new class.
Here’s what the code looks like:
// current mechanism to enable ExpandoMetaClass
.metaClassRegistry.metaClassCreationHandle = ()
logger = ()
logger.metaClass.log = { m -> println 'message: ' + m.toUpperCase() }
logger.log('x')
// => message: X
This achieves a similar result to applying a single decorator but we have no way to easily apply and remove embellishments on the
y.
More dynamic decorating
Suppose we have a calculator class (Actually any class would do).
{
add(a, b) { a + b }
}
We might be interested in observing usage of the class over time. If it is buried deep within our codebase, it might be hard to
determine when it is being called and with what parameters. Also, it might be hard to know if it is performing well. We can easily
make a generic tracing decorator that prints out tracing information whenever any method on the Calc class is called and also
provide timing information about how long it took to execute. Here is the code for the tracing decorator:
( ) {
. =
}
invokeMethod( name, args) {
println "Calling $name$args"
before = .currentTimeMillis()
result = .invokeMethod(name, args)
println "Got $result in ${System.currentTimeMillis()-before} ms"
result
}
}
Here is how to use the class in a script:
tracedCalc = ( ())
15 == tracedCalc.add(3, 12)
And here is what you would see after running this script:
Calling add{3, 12}
Got 15 in 31 ms
http://docs.groovy-lang.org/latest/html/documentation/ 467/502
1/6/2019 Decorating with an Interceptor Groovy Language Documentation
The above timing example hooks into the lifecycle of Groovy objects (via invokeMethod ). This is such an important style
performing meta-programming that Groovy has special support for this style of decorating using interceptors.
Groovy even comes with a built-in TracingInterceptor . We can extend the built-in class like this:
{
beforeTime
beforeInvoke( , methodName, [] arguments) {
.beforeInvoke( , methodName, arguments)
beforeTime = .currentTimeMillis()
}
afterInvoke( , methodName, [] arguments, result) {
.afterInvoke( , methodName, arguments, result)
duration = .currentTimeMillis() - beforeTime
writer.write("Duration: $duration ms\\n")
writer.flush()
result
}
}
Here is an example of using this new class:
proxy = .getInstance( )
proxy.interceptor = ()
proxy. {
7 == ().add(1, 6)
}
And here is the output:
before Calc.ctor()
after Calc.ctor()
Duration: 0 ms
before Calc.add(java.lang.Integer, java.lang.Integer)
after Calc.add(java.lang.Integer, java.lang.Integer)
Duration: 2 ms
Decorating with java.lang.re ect.Proxy
If you are trying to decorate an object (i.e. just a particular instance of the class, not the class generally), then you can use Java’s
java.lang.reflect.Proxy . Groovy makes working with this easier than just Java. Below is a code sample taken out of a grails
project that wraps a java.sql.Connection so that it’s close method is a no-op:
getGroovySql() {
con = session.connection()
invoker = { , method, args ->
(method.name == "close") {
log.debug("ignoring call to Connection.close() for use by groovy.sql.Sql")
} {
log.trace("delegating $method")
con.invokeMethod(method.name, args)
}
} ;
proxy = .newProxyInstance( getClass().getClassLoader(), [ ] [],
invoker )
(proxy)
}
If there were many methods to intercept, then this approach could be modi ed to look up closure in a map by method name and
invoke it.
Decorating with Spring
http://docs.groovy-lang.org/latest/html/documentation/ 468/502
1/6/2019 The Spring Framework (http://www.springframework.org)Groovy
allows Language to be applied with interceptors (you may have heard
decoratorsDocumentation
the terms advice or aspect). You can leverage this mechanism from Groovy as well.
First de ne a class that you want to decorate (we’ll also use an interface as is normal Spring practice):
Here’s the interface:
{
add(a, b)
}
Here’s the class:
{
add(a, b) { a + b }
}
Now, we de ne our wiring in a le called beans.xml as follows:
<?xml version="1.0" encoding="UTF-8"?>
xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:lang="http://www.springframework.org/schema/lang"
xsi:schemaLocation="
http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/lang
http://www.springframework.org/schema/lang/spring-lang.xsd"
id="performanceInterceptor" autowire="no"
class="org.springframework.aop.interceptor.PerformanceMonitorInterceptor"
name="loggerName" value="performance"
id="calc" class="util.CalcImpl"
class="org.springframework.aop.framework.autoproxy.BeanNameAutoProxyCreator"
name="beanNames" value="calc"
name="interceptorNames" value="performanceInterceptor"
Now, our script looks like this:
@Grab('org.springframework:spring-context:3.2.2.RELEASE')
org.springframework.context.support.
ctx = ('beans.xml')
calc = ctx.getBean('calc')
println calc.add(3, 25)
And when we run it, we see the results:
21/05/2007 23:02:35 org.springframework.aop.interceptor.PerformanceMonitorInterceptor
invokeUnderTrace
FINEST: StopWatch 'util.Calc.add': running time (millis) = 16
You may have to adjust your logging.properties le for messages at log level FINEST to be displayed.
Asynchronous Decorators using GPars
Using the example code in Panini (http://www.cs.iastate.edu/~design/projects/panini/docs/starting.shtml) for inspiration. Here is a
Groovy version that avoids using an @AddedBehavior annotation at the expense of not having as general an algorithm for
selecting the methods to decorate. This isn’t a limitation of the particular approach chosen but just a simpli cation for illustrative
purposes (but don’t assume below is an exact equivalent).
http://docs.groovy-lang.org/latest/html/documentation/ 469/502
1/6/2019 Groovy Language Documentation
@Grab('org.codehaus.gpars:gpars:0.10')
groovyx.gpars. .withPool
{
()
getText()
}
{
document
() { println document }
getText() { document }
}
words( text) {
text.replaceAll('[^a-zA-Z]', ' ').trim().split("\\\\s+")*.toLowerCase()
}
avgWordLength = {
words = words(it.text)
sprintf "Avg Word Length: %4.2f", words*.size().sum() / words.size()
}
modeWord = {
wordGroups = words(it.text).groupBy {it}.collectEntries { k, v -> [k, v.size()] }
maxSize = wordGroups*.value.max()
maxWords = wordGroups.findAll { it.value == maxSize }
"Mode Word(s): ${maxWords*.key.join(', ')} ($maxSize occurrences)"
}
wordCount = { d -> "Word Count: " + words(d.text).size() }
asyncDecorator( d, c) {
.INSTANCE.instantiateDelegate([ : {
withPool {
result = c.callAsync(d)
d. ()
println result. ()
}
}], [ ], d)
}
d = asyncDecorator(asyncDecorator(asyncDecorator(
(document:"This is the file with the words in it\\n\\t\\nDo you see the
words?\\n"),
// new DocumentImpl(document: new File('AsyncDecorator.groovy').text),
wordCount), modeWord), avgWordLength)
d. ()
Delegation Pattern
The Delegation Pattern (http://en.wikipedia.org/wiki/Delegation_pattern) is a technique where an object’s behavior (public
methods) is implemented by delegating responsibility to one or more associated objects.
Groovy allows the traditional style of applying the delegation pattern, e.g. see Replace Inheritance with Delegation.
Implement Delegation Pattern using ExpandoMetaClass
The groovy.lang.ExpandoMetaClass (http://docs.groovy-lang.org/2.5.5/html/gapi/index.html?groovy/lang/ExpandoMetaClass.html)
allows usage of this pattern to be encapsulated in a library. This allows Groovy to emulate similar libraries available for the Ruby
language.
Consider the following library class:
http://docs.groovy-lang.org/latest/html/documentation/ 470/502
1/6/2019 Groovy Language Documentation
{
targetClass
(targetClass, ) {
.targetClass = targetClass
. =
}
( methodName) {
(methodName, methodName)
}
( methodName, asMethodName) {
targetClass.metaClass."$asMethodName" = .&"$methodName"
}
delegateAll( [] names) {
names.each { (it) }
}
delegateAll( names) {
names.each { k, v -> (k, v) }
}
delegateAll() {
. .methods*.name.each { (it) }
}
}
With this in your classpath, you can now apply the delegation pattern dynamically as shown in the following examples. First,
consider we have the following classes:
{
name
}
{
borrowAmount(amount) {
"borrow \\$$amount"
}
borrowFor(thing) {
"buy \\$thing"
}
}
lender = ()
delegator = ( , lender)
We can now use the delegator to automatically borrow methods from the lender object to extend the Person class. We can
borrow the methods as is or with a rename:
delegator. 'borrowFor'
delegator. 'borrowAmount', 'getMoney'
p = ()
println p.borrowFor('present') // => buy present
println p.getMoney(50)
The rst line above, adds the borrowFor method to the Person class by delegating to the lender object. The second line adds a
getMoney method to the Person class by delegating to the lender object’s borrowAmount method.
Alternatively, we could borrow multiple methods like this:
delegator.delegateAll 'borrowFor', 'borrowAmount'
Which adds these two methods to the Person class.
http://docs.groovy-lang.org/latest/html/documentation/ 471/502
1/6/2019 Or if we want all the methods, like this: Groovy Language Documentation
delegator.delegateAll()
Which will make all the methods in the delegate object available in the Person class.
Alternatively, we can use a map notation to rename multiple methods:
delegator.delegateAll borrowAmount:'getMoney', borrowFor:'getThing'
Implement Delegation Pattern using @Delegate annotation
Since version 1.6 you can use the built-in delegation mechanism which is based on AST transformation.
This make delegation even easier:
{
name
@Delegate mortgageLender = ()
}
{
borrowAmount(amount) {
"borrow \\$$amount"
}
borrowFor(thing) {
"buy $thing"
}
}
p = ()
"buy present" == p.borrowFor('present')
"borrow \\$50" == p.borrowAmount(50)
Flyweight Pattern
The Flyweight Pattern (http://en.wikipedia.org/wiki/Flyweight_pattern) is a pattern for greatly reducing memory requirements by
not requiring that heavy-weight objects be created in large numbers when dealing with systems that contain many things that are
mostly the same. If for instance, a document was modelled using a complex character class that knew about unicode, fonts,
positioning, etc., then the memory requirements could be quite large for large documents if each physical character in the
document required its own character class instance. Instead, characters themselves might be kept within Strings and we might
have one character class (or a small number such as one character class for each font type) that knew the speci cs of how to deal
with characters.
In such circumstances, we call the state that is shared with many other things (e.g. the character type) instrinsic state. It is
captured within the heavy-weight class. The state which distinguishes the physical character (maybe just its ASCII code or Unicode)
is called its extrinsic state.
Example
First we are going to model some complex aircraft (the rst being a hoax competitor of the second - not that is relevant to the
example).
{
wingspan = '80.8 m'
capacity = 1000
speed = '1046 km/h'
range = '14400 km'
// ...
}
http://docs.groovy-lang.org/latest/html/documentation/ 472/502
1/6/2019 Groovy Language Documentation
{
wingspan = '79.8 m'
capacity = 555
speed = '912 km/h'
range = '10370 km'
// ...
}
If we want to model our eet, our rst attempt might involve using many instances of these heavy-weight objects. It turns out
though that only a few small pieces of state (our extrinsic state) change for each aircraft, so we will have singletons for the heavy-
weight objects and capture the extrinsic state (bought date and asset number in the code below) separately.
{
instances = [797: (), 380: ()]
}
{
type // instrinsic state
assetNumber // extrinsic state
bought // extrinsic state
(typeCode, assetNumber, bought) {
type = .instances[typeCode]
.assetNumber = assetNumber
.bought = bought
}
describe() {
println """
Asset Number: $assetNumber
Capacity: $type.capacity people
Speed: $type.speed
Range: $type.range
Bought: $bought
"""
}
}
fleet = [
(380, 1001, '10-May-2007'),
(380, 1002, '10-Nov-2007'),
(797, 1003, '10-May-2008'),
(797, 1004, '10-Nov-2008')
]
fleet.each { p -> p.describe() }
So here, even if our eet contained hundreds of planes, we would only have one heavy-weight object for each type of aircraft.
As a further e ciency measure, we might use lazy creation of the yweight objects rather than create the initial map up front as in
the above example.
Running this script results in:
http://docs.groovy-lang.org/latest/html/documentation/ 473/502
1/6/2019 Groovy Language Documentation
Asset Number: 1001
Capacity: 555 people
Speed: 912 km/h
Range: 10370 km
Bought: 10-May-2007
Asset Number: 1002
Capacity: 555 people
Speed: 912 km/h
Range: 10370 km
Bought: 10-Nov-2007
Asset Number: 1003
Capacity: 1000 people
Speed: 1046 km/h
Range: 14400 km
Bought: 10-May-2008
Asset Number: 1004
Capacity: 1000 people
Speed: 1046 km/h
Range: 14400 km
Bought: 10-Nov-2008
Iterator Pattern
The Iterator Pattern (http://en.wikipedia.org/wiki/Iterator_pattern) allows sequential access to the elements of an aggregate object
without exposing its underlying representation.
Groovy has the iterator pattern built right in to many of its closure operators, e.g. each and eachWithIndex as well as the
for .. in loop.
For example:
printAll(container) {
(item container) { println item }
}
numbers = [ 1,2,3,4 ]
months = [ :31, :30, :31 ]
colors = [ java.awt. .BLACK, java.awt. .WHITE ]
printAll numbers
printAll months
printAll colors
Results in the output:
1
2
3
4
May=31
Mar=31
Apr=30
java.awt.Color[r=0,g=0,b=0]
java.awt.Color[r=255,g=255,b=255]
Another example:
colors.eachWithIndex { item, pos ->
println "Position $pos contains '$item'"
}
Results in:
http://docs.groovy-lang.org/latest/html/documentation/ 474/502
1/6/2019 Groovy Language Documentation
Position 0 contains 'java.awt.Color[r=0,g=0,b=0]'
Position 1 contains 'java.awt.Color[r=255,g=255,b=255]'
The iterator pattern is also built in to other special operators such as the eachByte , eachFile , eachDir , eachLine ,
eachObject , eachMatch operators for working with streams, URLs, les, directories and regular expressions matches.
Loan my Resource Pattern
The Loan my Resource (https://wiki.scala-lang.org/display/SYGN/Loan) pattern ensures that a resource is deterministically
disposed of once it goes out of scope.
This pattern is built in to many Groovy helper methods. You should consider using it yourself if you need to work with resources in
ways beyond what Groovy supports.
Example
Consider the following code which works with a le. First we might write some line to the le and then print its size:
f = ('junk.txt')
f.withPrintWriter { pw ->
pw.println( ())
pw.println( . .name)
}
println f.size()
// => 42
We could also read back the contents of the le a line at a time and print each line out:
f.eachLine { line ->
println line
}
// =>
// Mon Jun 18 22:38:17 EST 2007
// RunPattern
Note that normal Java Reader and PrintWriter objects were used under the covers by Groovy but the code writer did not have
to worry about explicitly creating or closing those resources. The built-in Groovy methods loan the respective reader or writer to
the closure code and then tidy up after themselves. So, you are using this pattern without having to do any work.
Sometimes however, you wish to do things slightly di erently to what you can get for free using Groovy’s built-in mechanisms.
You should consider utilising this pattern within your own resource-handling operations.
Consider how you might process the list of words on each line within the le. We could actually do this one too using Groovy’s
built-in functions, but bear with us and assume we have to do some resource handling ourselves. Here is how we might write the
code without using this pattern:
reader = f.newReader()
reader.splitEachLine(' ') { wordList ->
println wordList
}
reader.close()
// =>
// [ "Mon", "Jun", "18", "22:38:17", "EST", "2007" ]
// [ "RunPattern" ]
Notice that we now have an explicit call to close() in our code. If we didn’t code it just right (here we didn’t surround the code in
a try … finally block, we run the risk of leaving the le handle open.
Let’s now apply the loan pattern. First, we’ll write a helper method:
http://docs.groovy-lang.org/latest/html/documentation/ 475/502
1/6/2019 Groovy Language Documentation
withListOfWordsForEachLine( f, c) {
r = f.newReader()
{
r.splitEachLine(' ', c)
} {
r?.close()
}
}
Now, we can re-write our code as follows:
withListOfWordsForEachLine(f) { wordList ->
println wordList
}
// =>
// [ "Mon", "Jun", "18", "22:38:17", "EST", "2007" ]
// [ "RunPattern" ]
This is much simpler and has removed the explicit close() . This is now catered for in one spot so we can apply the appropriate
level of testing or reviewing in just one spot to be sure we have no problems.
Null Object Pattern
The Null Object Pattern (http://en.wikipedia.org/wiki/Null_Object_pattern) involves using a special object place-marker object
representing null. Typically, if you have a reference to null, you can’t invoke reference.field or reference.method() You
receive the dreaded NullPointerException . The null object pattern uses a special object representing null, instead of using an
actual null . This allows you to invoke eld and method references on the null object. The result of using the null object should
semantically be equivalent to doing nothing.
Simple Example
Suppose we have the following system:
{
salary
}
{
name
job
}
people = [
(name: 'Tom', job: (salary: 1000)),
(name: 'Dick', job: (salary: 1200)),
]
biggestSalary = people.collect { p -> p.job.salary }.max()
println biggestSalary
When run, this prints out 1200 . Suppose now that we now invoke:
people << (name: 'Harry')
If we now try to calculate biggestSalary again, we receive a null pointer exception.
To overcome this problem, we can introduce a NullJob class and change the above statement to become:
{ salary = 0 }
people << (name: 'Harry', job: ())
biggestSalary = people.collect { p -> p.job.salary }.max()
println biggestSalary
http://docs.groovy-lang.org/latest/html/documentation/ 476/502
1/6/2019 This works as we require but it’s not always the best way to do this
Groovy with Groovy.
Language Groovy’s safe-dereference operator ( ?. )
Documentation
operator and null aware closures often allow Groovy to avoid the need to create a special null object or null class. This is
illustrated by examining a groovier way to write the above example:
people << (name:'Harry')
biggestSalary = people.collect { p -> p.job?.salary }.max()
println biggestSalary
Two things are going on here to allow this to work. First of all, max() is 'null aware' so that [300, null, 400].max() == 400. Secondly,
with the ?. operator, an expression like p?.job?.salary will be equal to null if salary is equal to null, or if job is equal ` null
or if p is equal to null. You don’t need to code a complex nested if ... then ... else to avoid a NullPointerException .
Tree Example
Consider the following example where we want to calculate size, cumulative sum and cumulative product of all the values in a tree
structure.
Our rst attempt has special logic within the calculation methods to handle null values.
{
left, right, value
size() {
1 + (left ? left.size() : 0) + (right ? right.size() : 0)
}
sum() {
value + (left ? left.sum() : 0) + (right ? right.sum() : 0)
}
product() {
value * (left ? left.product() : 1) * (right ? right.product() : 1)
}
}
root = (
value: 2,
left: (
value: 3,
right: (value: 4),
left: (value: 5)
)
)
println root.size()
println root.sum()
println root.product()
If we introduce the null object pattern (here by de ning the NullTree class), we can now simplify the logic in the size() , sum()
and`product()` methods. These methods now much more clearly represent the logic for the normal (and now universal) case.
Each of the methods within NullTree returns a value which represents doing nothing.
http://docs.groovy-lang.org/latest/html/documentation/ 477/502
1/6/2019 Groovy Language Documentation
{
left = (), right = (), value
size() {
1 + left.size() + right.size()
}
sum() {
value + left.sum() + right.sum()
}
product() {
value * left.product() * right.product()
}
}
{
size() { 0 }
sum() { 0 }
product() { 1 }
}
root = (
value: 2,
left: (
value: 3,
right: (value: 4),
left: (value: 5)
)
)
println root.size()
println root.sum()
println root.product()
The result of running either of these examples is:
4
14
120
Note: a slight variation with the null object pattern is to combine it with the singleton pattern. So, we wouldn’t write new NullTree()
wherever we needed a null object as shown above. Instead we would have a single null object instance which we would place
within our data structures as needed.
Pimp my Library Pattern
The Pimp my Library (http://www.artima.com/weblogs/viewpost.jsp?thread=179766) Pattern suggests an approach for extending
a library that nearly does everything that you need but just needs a little more. It assumes that you do not have source code for
the library of interest.
Example
Suppose we want to make use of the built-in Integer facilities in Groovy (which build upon the features already in Java). Those
libraries have nearly all of the features we want but not quite everything. We may not have all of the source code to the Groovy
and Java libraries so we can’t just change the library. Instead we augment the library. Groovy has a number of ways to do this. One
way is to use a Category.
First, we’ll de ne a suitable category.
http://docs.groovy-lang.org/latest/html/documentation/ 478/502
1/6/2019 Groovy Language Documentation
{
greaterThanAll( , [] others) {
greaterThanAll( , others)
}
greaterThanAll( , others) {
others.every { > it }
}
}
We have added two methods which augment the Integer methods by providing the greaterThanAll method. Categories follow
conventions where they are de ned as static methods with a special rst parameter representing the class we wish to extend. The
greaterThanAll(Integer self, others) static method becomes the greaterThanAll(other) instance method.
We de ned two versions of greaterThanAll . One which works for collections, ranges etc. The other which works with a variable
number of Integer arguments.
Here is how you would use the category.
( ) {
4.greaterThanAll(1, 2, 3)
!5.greaterThanAll(2, 4, 6)
5.greaterThanAll(-4..4)
5.greaterThanAll([])
!5.greaterThanAll([4, 5])
}
As you can see, using this technique you can e ectively enrich an original class without having access to its source code.
Moreover, you can apply di erent enrichments in di erent parts of the system as well as work with un-enriched objects if we
need to.
Proxy Pattern
The Proxy Pattern (http://en.wikipedia.org/wiki/Proxy_pattern) allows one object to act as a pretend replacement for some other
object. In general, whoever is using the proxy, doesn’t realise that they are not using the real thing. The pattern is useful when the
real object is hard to create or use: it may exist over a network connection, or be a large object in memory, or be a le, database
or some other resource that is expensive or impossible to duplicate.
Example
One common use of the proxy pattern is when talking to remote objects in a di erent JVM. Here is the client code for creating a
proxy that talks via sockets to a server object as well as an example usage:
{
accumulate(args) {
result
s = ("localhost", 54321)
s.withObjectStreams { ois, oos ->
oos << args
result = ois.readObject()
}
s.close()
result
}
}
println ().accumulate([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
// => 55
Here is what your server code might look like (start this rst):
http://docs.groovy-lang.org/latest/html/documentation/ 479/502
1/6/2019 Groovy Language Documentation
{
accumulate(args) {
args.inject(0) { total, arg -> total += arg }
}
}
port = 54321
accumulator = ()
server = (port)
println "Starting server on port $port"
( ) {
server.accept() { socket ->
socket.withObjectStreams { ois, oos ->
args = ois.readObject()
oos << accumulator.accumulate(args)
}
}
}
Singleton Pattern
The Singleton Pattern (http://en.wikipedia.org/wiki/Singleton_pattern) is used to make sure only one object of a particular class is
ever created. This can be useful when when exactly one object is needed to coordinate actions across a system; perhaps for
e ciency where creating lots of identical objects would be wasteful, perhaps because a particular algorithm needing a single point
of control is required or perhaps when an object is used to interact with a non-shareable resource.
Weaknesses of the Singleton pattern include:
It can reduce reuse. For instance, there are issues if you want to use inheritance with Singletons. If SingletonB extends
SingletonA , should there be exactly (at most) one instance of each or should the creation of an object from one of the
classes prohibit creation from the other. Also, if you decide both classes can have an instance, how do you override the
getInstance() method which is static?
It is also hard to test singletons in general because of the static methods but Groovy can support that if required.
Example: The Classic Java Singleton
Suppose we wish to create a class for collecting votes. Because getting the right number of votes may be very important, we
decide to use the singleton pattern. There will only ever be one VoteCollector object, so it makes it easier for us to reason
about that objects creation and use.
{
votes = 0
INSTANCE = ()
getInstance() { INSTANCE }
() { }
display() { println "Collector:${hashCode()}, Votes:$votes" }
}
Some points of interest about this code:
it has a private constructor, so no VoteCollector objects can be created in our system (except for the INSTANCE we create)
the INSTANCE is also private, so it can’t be changed once set
we haven’t made the updating of votes thread-safe at this point (it doesn’t add to this example)
the vote collector instance is not lazily created (if we never reference the class, the instance won’t be created; however, as soon
as we reference the class, the instance will be created even if not needed initially)
We can use this singleton class in some script code as follows:
http://docs.groovy-lang.org/latest/html/documentation/ 480/502
1/6/2019 Groovy Language Documentation
collector = .instance
collector.display()
collector.votes++
collector =
.start{
collector2 = .instance
collector2.display()
collector2.votes++
collector2 =
}.join()
collector3 = .instance
collector3.display()
Here we used the instance 3 times. The second usage was even in a di erent thread (but don’t try this in a scenario with a new
class loader).
Running this script yields (your hashcode value will vary):
Collector:15959960, Votes:0
Collector:15959960, Votes:1
Collector:15959960, Votes:2
Variations to this pattern:
To support lazy-loading and multi-threading, we could just use the synchronized keyword with the getInstance() method.
This has a performance hit but will work.
We can consider variations involving double-checked locking and the volatile keyword, but see the limitations of this
approach here (http://www.ibm.com/developerworks/java/library/j-dcl/index.html).
Example: Singleton via MetaProgramming
Groovy’s meta-programming capabilities allow concepts like the singleton pattern to be enacted in a far more fundamental way.
This example illustrates a simple way to use Groovy’s meta-programming capabilities to achieve the singleton pattern but not
necessarily the most e cient way.
Suppose we want to keep track of the total number of calculations that a calculator performs. One way to do that is to use a
singleton for the calculator class and keep a variable in the class with the count.
First we de ne some base classes. A Calculator class which performs calculations and records how many such calculations it
performs and a Client class which acts as a facade to the calculator.
{
total = 0
add(a, b) { total++; a + b }
getTotalCalculations() { 'Total Calculations: ' + total }
toString() { 'Calc: ' + hashCode() }
}
{
calc = ()
executeCalc(a, b) { calc.add(a, b) }
toString() { 'Client: ' + hashCode() }
}
Now we can de ne and register a MetaClass which intercepts all attempts to create a Calculator object and always provides a
pre-created instance instead. We also register this MetaClass with the Groovy system:
http://docs.groovy-lang.org/latest/html/documentation/ 481/502
1/6/2019 Groovy Language Documentation
{
INSTANCE = ()
() { ( ) }
invokeConstructor( [] arguments) { INSTANCE }
}
registry = .metaClassRegistry
registry.setMetaClass( , ())
Now we use instances of our Client class from within a script. The client class will attempt to create new instances of the
calculator but will always get the singleton.
client = ()
3 == client.executeCalc(1, 2)
println "$client, $client.calc, $client.calc.totalCalculations"
client = ()
4 == client.executeCalc(2, 2)
println "$client, $client.calc, $client.calc.totalCalculations"
Here is the result of running this script (your hashcode values may vary):
Client: 7306473, Calc: 24230857, Total Calculations: 1
Client: 31436753, Calc: 24230857, Total Calculations: 2
Guice Example
We can also implement the Singleton Pattern using Guice (https://github.com/google/guice).
Consider the Calculator example again.
Guice is a Java-oriented framework that supports Interface-Oriented design. Hence we create a Calculator interface rst. We
can then create our CalculatorImpl implementation and a Client object which our script will interact with. The Client class
isn’t strictly needed for this example but allows us to show that non-singleton instances are the default. Here is the code:
http://docs.groovy-lang.org/latest/html/documentation/ 482/502
1/6/2019 Groovy Language Documentation
@Grapes([@Grab('aopalliance:aopalliance:1.0'), @Grab('com.google.code.guice:guice:1.0')])
com.google.inject.*
{
add(a, b)
}
{
total = 0
add(a, b) { total++; a + b }
getTotalCalculations() { 'Total Calculations: ' + total }
toString() { 'Calc: ' + hashCode() }
}
{
@Inject calc
executeCalc(a, b) { calc.add(a, b) }
toString() { 'Client: ' + hashCode() }
}
injector = .createInjector (
[configure: { binding ->
binding.bind( )
.to( )
.asEagerSingleton() } ]
)
client = injector.getInstance( )
3 == client.executeCalc(1, 2)
println "$client, $client.calc, $client.calc.totalCalculations"
client = injector.getInstance( )
4 == client.executeCalc(2, 2)
println "$client, $client.calc, $client.calc.totalCalculations"
Note the @Inject annotation in the Client class. We can always tell right in the source code which elds will be injected.
In this example we chose to use an explicit binding. All of our dependencies (ok, only one in this example at the moment) are
con gured in the binding. The Guide injector knows about the binding and injects the dependencies as required when we create
objects. For the singleton pattern to hold, you must always use Guice to create your instances. Nothing shown so far would stop
you creating another instance of the calculator manually using new CalculatorImpl() which would of course violate the desired
singleton behaviour.
In other scenarios (though probably not in large systems), we could choose to express dependencies using annotations, such as
the following example shows:
http://docs.groovy-lang.org/latest/html/documentation/ 483/502
1/6/2019 Groovy Language Documentation
@Grapes([@Grab('aopalliance:aopalliance:1.0'), @Grab('com.google.code.guice:guice:1.0')])
com.google.inject.*
@ImplementedBy( )
{
// as before ...
}
@Singleton
{
// as before ...
}
{
// as before ...
}
injector = .createInjector()
// ...
Note the @Singleton annotation on the CalculatorImpl class and the @ImplementedBy annotation in the Calculator
interface.
When run, the above example (using either approach) yields (your hashcode values will vary):
Client: 8897128, Calc: 17431955, Total Calculations: 1
Client: 21145613, Calc: 17431955, Total Calculations: 2
You can see that we obtained a new client object whenever we asked for an instance but it was injected with the same calculator
object.
Spring Example
We can do the Calculator example again using Spring as follows:
http://docs.groovy-lang.org/latest/html/documentation/ 484/502
1/6/2019 Groovy Language Documentation
@Grapes([@Grab('org.springframework:spring-core:3.2.2.RELEASE'),
@Grab('org.springframework:spring-beans:3.2.2.RELEASE')])
org.springframework.beans.factory.support.*
{
add(a, b)
}
{
total = 0
add(a, b) { total++; a + b }
getTotalCalculations() { 'Total Calculations: ' + total }
toString() { 'Calc: ' + hashCode() }
}
{
( calc) { .calc = calc }
calc
executeCalc(a, b) { calc.add(a, b) }
toString() { 'Client: ' + hashCode() }
}
// Here we 'wire' up our dependencies through the API. Alternatively,
// we could use XML-based configuration or the Grails Bean Builder DSL.
factory = ()
factory.registerBeanDefinition('calc', ( ))
beanDef = ( , )
beanDef.setAutowireMode( .AUTOWIRE_AUTODETECT)
factory.registerBeanDefinition('client', beanDef)
client = factory.getBean('client')
3 == client.executeCalc(1, 2)
println "$client, $client.calc, $client.calc.totalCalculations"
client = factory.getBean('client')
4 == client.executeCalc(2, 2)
println "$client, $client.calc, $client.calc.totalCalculations"
And here is the result (your hashcode values will vary):
Client: 29418586, Calc: 10580099, Total Calculations: 1
Client: 14800362, Calc: 10580099, Total Calculations: 2
Further information
Simply Singleton (http://www.javaworld.com/javaworld/jw-04-2003/jw-0425-designpatterns.html?page=1)
Use your singletons wisely (http://www.ibm.com/developerworks/webservices/library/co-single/index.html)
Double-checked locking and the Singleton pattern (http://www.ibm.com/developerworks/java/library/j-dcl/index.html)
Lazy Loading Singletons (https://web.archive.org/web/20160807234810/http://blog.crazybob.org/2007/01/lazy-loading-
singletons.html)
Implementing the Singleton Pattern in C# (http://www.yoda.arachsys.com/csharp/singleton.html)
State Pattern
The State Pattern (http://en.wikipedia.org/wiki/State_pattern) provides a structured approach to partitioning the behaviour within
complex systems. The overall behaviour of a system is partitioned into well-de ned states. Typically, each state is implemented by
a class. The overall system behaviour can be determined rstly by knowing the current state of the system; secondly, by
understanding the behaviour possible while in that state (as embodied in the methods of the class corresponding to that state).
Example
Here is an example:
http://docs.groovy-lang.org/latest/html/documentation/ 485/502
1/6/2019 Groovy Language Documentation
{
context = ()
connect() {
context.state.connect()
}
disconnect() {
context.state.disconnect()
}
send_message(message) {
context.state.send_message(message)
}
receive_message() {
context.state.receive_message()
}
}
{
state = ( )
}
{
context
(context) {
.context = context
inform()
}
}
{
(context) {
(context)
}
inform() {
println "offline"
}
connect() {
context.state = (context)
}
disconnect() {
println "error: not connected"
}
send_message(message) {
println "error: not connected"
}
receive_message() {
println "error: not connected"
}
}
{
(context) {
(context)
}
inform() {
println "connected"
}
connect() {
println "error: already connected"
}
disconnect() {
context.state = (context)
}
send_message(message) {
println "\"$message\" sent"
}
receive_message() {
println "message received"
http://docs.groovy-lang.org/latest/html/documentation/ 486/502
1/6/2019 } Groovy Language Documentation
}
client = ()
client.send_message("Hello")
client.connect()
client.send_message("Hello")
client.connect()
client.receive_message()
client.disconnect()
Here is the output:
offline
error: not connected
connected
"Hello" sent
error: already connected
message received
offline
One of the great things about a dynamic language like Groovy though is that we can take this example and express it in many
di erent ways depending on our particular needs. Some potential variations for this example are shown below.
Variation 1: Leveraging Interface-Oriented Design
One approach we could take is to leverage Interface-Oriented Design
(http://www.pragmaticprogrammer.com/titles/kpiod/index.html). To do this, we could introduce the following interface:
{
connect()
disconnect()
send_message(message)
receive_message()
}
Then our Client , Online and 'O ine` classes could be modi ed to implement that interface, e.g.:
{
// ... as before ...
}
{
// ... as before ...
}
{
// ... as before ...
}
You might ask: Haven’t we just introduced additional boilerplate code? Can’t we rely on duck-typing for this? The answer is 'yes'
and 'no'. We can get away with duck-typing but one of the key intentions of the state pattern is to partition complexity. If we know
that the client class and each state class all satisfy one interface, then we have placed some key boundaries around the
complexity. We can look at any state class in isolation and know the bounds of behaviour possible for that state.
We don’t have to use interfaces for this, but it helps express the intent of this particular style of partitioning and it helps reduce
the size of our unit tests (we would have to have additional tests in place to express this intent in languages which have less
support for interface-oriented design).
Variation 2: Extract State Pattern Logic
Alternatively, or in combination with other variations, we might decide to extract some of our State Pattern logic into helper
classes. For example, we could de ne the following classes in a state pattern package/jar/script:
http://docs.groovy-lang.org/latest/html/documentation/ 487/502
1/6/2019 Groovy Language Documentation
{
registry = .metaClassRegistry
create(objectClass, param) {
registry.getMetaClass(objectClass).invokeConstructor([param] [])
}
}
{
context
setContext(context) {
.context = context
}
invokeMethod( name, arg) {
context.invokeMethod(name, arg)
}
startFrom(initialState) {
setContext( .create(initialState, ))
}
}
{
client
(client) { .client = client }
transitionTo(nextState) {
client.setContext( .create(nextState, client))
}
}
This is all quite generic and can be used wherever we want to introduce the state pattern. Here is what our code would look like
now:
http://docs.groovy-lang.org/latest/html/documentation/ 488/502
1/6/2019 Groovy Language Documentation
{
() {
startFrom( )
}
}
{
(client) {
(client)
println "offline"
}
connect() {
transitionTo( )
}
disconnect() {
println "error: not connected"
}
send_message(message) {
println "error: not connected"
}
receive_message() {
println "error: not connected"
}
}
{
(client) {
(client)
println "connected"
}
connect() {
println "error: already connected"
}
disconnect() {
transitionTo( )
}
send_message(message) {
println "\"$message\" sent"
}
receive_message() {
println "message received"
}
}
client = ()
client.send_message("Hello")
client.connect()
client.send_message("Hello")
client.connect()
client.receive_message()
client.disconnect()
You can see here the startFrom and transitionTo methods begin to give our example code a DSL feel.
Variation 3: Bring on the DSL
Alternatively, or in combination with other variations, we might decide to fully embrace a Domain Speci c Language (DSL)
approach to this example.
We can de ne the following generic helper functions ( rst discussed here (http://www.bytemycode.com/snippets/snippet/640/)):
http://docs.groovy-lang.org/latest/html/documentation/ 489/502
1/6/2019 Groovy Language Documentation
{
fsm
fromState
toState
(a_fsm) {
fsm = a_fsm
}
on(a_event) {
= a_event
on(a_event, a_transitioner) {
on(a_event)
a_transitioner. =
a_transitioner.call()
(a_fromState) {
fromState = a_fromState
to(a_toState) {
a_toState, "Invalid toState: $a_toState"
toState = a_toState
fsm.registerTransition( )
isValid() {
&& fromState && toState
}
toString() {
"$event: $fromState=>$toState"
}
}
http://docs.groovy-lang.org/latest/html/documentation/ 490/502
1/6/2019 Groovy Language Documentation
{
transitions = [:]
initialState
currentState
(a_initialState) {
a_initialState, "You need to provide an initial state"
initialState = a_initialState
currentState = a_initialState
}
record() {
.newInstance( )
}
reset() {
currentState = initialState
}
isState(a_state) {
currentState == a_state
}
registerTransition(a_grammar) {
a_grammar.isValid(), "Invalid transition ($a_grammar)"
transition
= a_grammar.
fromState = a_grammar.fromState
toState = a_grammar.toState
(!transitions[ ]) {
transitions[ ] = [:]
}
transition = transitions[ ]
!transition[fromState], "Duplicate fromState $fromState for transition $a_grammar"
transition[fromState] = toState
}
fire(a_event) {
currentState, "Invalid current state '$currentState': passed into constructor"
transitions.containsKey(a_event), "Invalid event '$a_event', should be one of
${transitions.keySet()}"
transition = transitions[a_event]
nextState = transition[currentState]
nextState, "There is no transition from '$currentState' to any other state"
currentState = nextState
currentState
}
}
Now we can de ne and test our state machine like this:
http://docs.groovy-lang.org/latest/html/documentation/ 491/502
1/6/2019 Groovy Language Documentation
{
fsm
setUp() {
fsm = .newInstance('offline')
recorder = fsm.record()
recorder.on('connect'). ('offline').to('online')
recorder.on('disconnect'). ('online').to('offline')
recorder.on('send_message'). ('online').to('online')
recorder.on('receive_message'). ('online').to('online')
}
testInitialState() {
fsm.isState('offline')
}
testOfflineState() {
shouldFail{
fsm.fire('send_message')
}
shouldFail{
fsm.fire('receive_message')
}
shouldFail{
fsm.fire('disconnect')
}
'online' == fsm.fire('connect')
}
testOnlineState() {
fsm.fire('connect')
fsm.fire('send_message')
fsm.fire('receive_message')
shouldFail{
fsm.fire('connect')
}
'offline' == fsm.fire('disconnect')
}
}
This example isn’t an exact equivalent of the others. It doesn’t use prede ned Online and Offline classes. Instead it de nes
the entire state machine on the y as needed. See the previous reference (http://www.bytemycode.com/snippets/snippet/640/)
for more elaborate examples of this style.
See also: Model-based testing using ModelJUnit
Strategy Pattern
The Strategy Pattern (http://en.wikipedia.org/wiki/Strategy_pattern) allows you to abstract away particular algorithms from their
usage. This allows you to easily swap the algorithm being used without having to change the calling code. The general form of the
pattern is:
In Groovy, because of its ability to treat code as a rst class object using anonymous methods (which we loosely call Closures), the
need for the strategy pattern is greatly reduced. You can simply place algorithms inside Closures.
http://docs.groovy-lang.org/latest/html/documentation/ 492/502
1/6/2019 Example Groovy Language Documentation
First let’s look at the traditional way of encapsulating the Strategy Pattern.
{
execute(n, m)
}
{
execute(n, m) { n * m }
}
{
execute(n, m) {
result = 0
n.times{
result += m
}
result
}
}
sampleData = [
[3, 4, 12],
[5, -5, -25]
]
[] multiplicationStrategies = [
(),
()
]
sampleData.each{ data ->
multiplicationStrategies.each { calc ->
data[2] == calc.execute(data[0], data[1])
}
}
Here we have de ned an interface Calc which our concrete strategy classes will implement (we could also have used an abstract
class). We then de ned two algorithms for doing simple multiplication: CalcByMult the normal way, and CalcByManyAdds using
only addition (don’t try this one using negative numbers - yes we could x this but it would just make the example longer). We
then use normal polymorphism (http://en.wikipedia.org/wiki/Polymorphism_in_object-oriented_programming) to invoke the
algorithms.
Here is the Groovier way to achieve the same thing using Closures:
multiplicationStrategies = [
{ n, m -> n * m },
{ n, m -> result = 0; n.times{ result += m }; result }
]
sampleData = [
[3, 4, 12],
[5, -5, -25]
]
sampleData.each{ data ->
multiplicationStrategies.each { calc ->
data[2] == calc(data[0], data[1])
}
}
Template Method Pattern
http://docs.groovy-lang.org/latest/html/documentation/ 493/502
1/6/2019 The Template Method Pattern (http://en.wikipedia.org/wiki/Template_method_pattern) abstracts away the details of several
Groovy Language Documentation
algorithms. The generic part of an algorithm is contained within a base class. Particular implementation details are captured
within base classes. The generic pattern of classes involved looks like this:
Example
In this example, Accumulator captures the essence of the accumulation algorithm. The base classes Sum and Product provide
particular customised ways to use the generic accumulation algorithm.
{
initial
doAccumulate(total, v)
accumulate(values) {
total = initial
values.each { v -> total = doAccumulate(total, v) }
total
}
}
{
() { initial = 0 }
doAccumulate(total, v) { total + v }
}
{
() { initial = 1 }
doAccumulate(total, v) { total * v }
}
println ().accumulate([1,2,3,4])
println ().accumulate([1,2,3,4])
The resulting output is:
10
24
In this particular case, you could use Groovy’s inject method to achieve a similar result using Closures:
addAll = { total, item -> total += item }
accumulated = [1, 2, 3, 4].inject(0, addAll)
println accumulated // => 10
Thanks to duck-typing, this would also work with other objects which support an add (plus() in Groovy) method, e.g.:
In this particular case, you could use Groovy’s inject method to achieve a similar result using Closures:
accumulated = [ "1", "2", "3", "4" ].inject("", addAll)
println accumulated // => "1234"
We could also do the multiplication case as follows:
http://docs.groovy-lang.org/latest/html/documentation/ 494/502
1/6/2019 Groovy Language Documentation
multAll = { total, item -> total *= item }
accumulated = [1, 2, 3, 4].inject(1, multAll)
println accumulated // => 24
Using closures this way looks more like the Strategy Pattern but if we realise that the built-in inject method is the generic part of
the algorithm for our template method, then the Closures become the customised parts of the template method pattern.
Visitor Pattern
The Visitor Pattern (http://en.wikipedia.org/wiki/Visitor_pattern) is one of those well-known but not often used patterns. I think
this is strange, as it is really a nice thing.
The goal of the pattern is to separate an algorithm from an object structure. A practical result of this separation is the ability to
add new operations to existing object structures without modifying those structures.
Simple Example
This example considers how to calculate the bounds of shapes (or collections of shapes). Our rst attempt uses the traditional
visitor pattern. We will see a more Groovy way to do this shortly.
http://docs.groovy-lang.org/latest/html/documentation/ 495/502
1/6/2019 Groovy Language Documentation
{ }
{
x, y, width, height
(x, y, width, height) {
.x = x; .y = y; .width = width; .height = height
}
(rect) {
(!rect)
minx = [rect.x, x].min()
maxx = [rect.x + width, x + width].max()
miny = [rect.y, y].min()
maxy = [rect.y + height, y + height].max()
(minx, miny, maxx - minx, maxy - miny)
}
accept(visitor) {
visitor.visit_rectangle( )
}
}
{
x1, y1, x2, y2
(x1, y1, x2, y2) {
.x1 = x1; .y1 = y1; .x2 = x2; .y2 = y2
}
accept(visitor){
visitor.visit_line( )
}
}
{
shapes = []
add(shape) { shapes += shape }
remove(shape) { shapes -= shape }
accept(visitor) {
visitor.visit_group( )
}
}
{
bounds
visit_rectangle(rectangle) {
(bounds)
bounds = bounds. (rectangle)
bounds = rectangle
}
visit_line(line) {
line_bounds = (line.x1, line.y1, line.x2-line.y1, line.x2-line.y2)
(bounds)
bounds = bounds. (line_bounds)
bounds = line_bounds
}
visit_group( ) {
.shapes.each { shape -> shape.accept( ) }
}
}
http://docs.groovy-lang.org/latest/html/documentation/ 496/502
1/6/2019 = () Groovy Language Documentation
.add( (100, 40, 10, 5))
.add( (100, 70, 10, 5))
.add( (90, 30, 60, 5))
visitor = ()
.accept(visitor)
bounding_box = visitor.bounds
println bounding_box. ()
That took quite a bit of code.
We can improve the clarity of our code (and make it about half the size) by making use of Groovy Closures as follows:
{
accept( ) { ( ) }
}
{
x, y, w, h
bounds() { }
(rect) {
(!rect)
minx = [ rect.x, x ].min()
maxx = [ rect.x + w, x + w ].max()
miny = [ rect.y, y ].min()
maxy = [ rect.y + h, y + h ].max()
(x:minx, y:miny, w:maxx - minx, h:maxy - miny)
}
}
{
x1, y1, x2, y2
bounds() {
(x:[x1, x2].min(), y:[y1, y2].min(), w:(x2 - x1).abs(), h:(y2 - y1).abs())
}
}
{
shapes = []
leftShift(shape) { shapes += shape }
accept( ) { shapes.each{it.accept( )} }
}
= ()
<< (x:100, y:40, w:10, h:5)
<< (x:100, y:70, w:10, h:5)
<< (x1:90, y1:30, x2:60, y2:5)
bounds
.accept{ bounds = it.bounds(). (bounds) }
println bounds. ()
Advanced Example
http://docs.groovy-lang.org/latest/html/documentation/ 497/502
1/6/2019 Groovy Language Documentation
{
visit( n1)
visit( n2)
}
{
accept( visitor)
}
{
[] children = [0]
accept( visitor) {
visitor.visit( )
( i = 0; i < children.length; ++i) {
children[i].accept(visitor)
}
}
}
{
[] children = [0]
accept( visitor) {
visitor.visit( )
( i = 0; i < children.length; ++i) {
children[i].accept(visitor)
}
}
}
{
count = 0
visit( n1) {
count++
}
visit( n2){}
}
If we now use NodeType1Counter on a tree like this:
root = ()
root.children = [2]
root.children[0] = ()
root.children[1] = ()
Then we have one NodeType1 object as root and one of the children is also a NodeType1 instance. The other child is a
NodeType2 instance. That means using NodeType1Counter here should count 2 NodeType1 objects.
Why to use this
As you can see here very good we have a visitor that has a state while the tree of objects is not changed. That’s pretty useful in
di erent areas, for example you could have a visitor counting all node types, or how many di erent types are used, or you could
use methods special to the node to gather information about the tree and much more.
What happens if we add a new type?
In this case we have to do much work.. we have to change Visitor to accept the new type, we have to write the new type itself of
course and we have to change every Visitor we have already implemented. After very few changes you will modify all your Visitors
to extend a default implementation of the visitor, so you don’t need to change every Visitor each time you add a new type.
What if we want to have di erent iteration patterns?
Then you have a problem. since the node describes how to iterate, you have no in uence and stop iteration at a point or change
the order. So maybe we should change this a little to this:
http://docs.groovy-lang.org/latest/html/documentation/ 498/502
1/6/2019 Groovy Language Documentation
{
visit( n1)
visit( n2)
}
{
visit( n1) {
( i = 0; i < n1.children.length; ++i) {
n1.children[i].accept( )
}
}
visit( n2) {
( i = 0; i < n2.children.length; ++i) {
n2.children[i].accept( )
}
}
}
{
accept( visitor)
}
{
[] children = [0]
accept( visitor) {
visitor.visit( )
}
}
{
[] children = [0];
accept( visitor) {
visitor.visit( )
}
}
{
count = 0
visit( n1) {
count++
.visit(n1)
}
}
Some small changes but with big e ect… the visitor is now recursive and tells me how to iterate. The implementation in the Nodes
is minimized to visitor.visit(this) , DefaultVisitor is now able to catch the new types, we can stop iteration by not
delegating to super. Of course the big disadvantage now is that it is no longer iterative, but you can’t get all the bene ts.
Make it Groovy
The question now is how to make that a bit more Groovy. Didn’t you nd this visitor.visit(this) strange? Why is it there?
The answer is to simulate double dispatch. In Java the compile time type is used, so when I visitor.visit(children[i]) then
the compiler won’t be able to nd the correct method, because Visitor does not contain a method visit(Visitable) . And
even if it would, we would like to visit the more special methods with NodeType1 or NodeType2 .
Now Groovy is not using the static type, Groovy uses the runtime type. This means I could do visitor.visit(children[i])
directly. Hmm.. since we minimized the accept method to just do the double dispatch part and since the runtime type system of
Groovy will already cover that.. do we need the accept method? I think you can guess that I would answer no. But we can do more.
We had the disadvantage of not knowing how to handle unknown tree elements. We had to extends the interface Visitor for
that, resulting in changes to DefaultVisitor and then we have the task to provide a useful default like iterating the node or not
doing anything at all. Now with Groovy we can catch that case by adding a visit(Visitable) method that does nothing. That
would be the same in Java btw.
But don’t let us stop here… do we need the Visitor interface? If we don’t have the accept method, then we don’t need the
Visitor interface at all. So the new code would be:
http://docs.groovy-lang.org/latest/html/documentation/ 499/502
1/6/2019 Groovy Language Documentation
{
visit( n1) {
n1.children.each { visit(it) }
}
visit( n2) {
n2.children.each { visit(it) }
}
visit( v) { }
}
{ }
{
[] children = []
}
{
[] children = []
}
{
count = 0
visit( n1) {
count++
.visit(n1)
}
}
Looks like we saved a few lines of code here. But we made more. The Visitable nodes now do not refer to any Visitor class
or interface. For me this is the best level of separation you could get here. But do we really need to stop here? No. Let us change
the Visitable interface a little and let it return the children we want to visit next. This allows us a general iteration method.
{
visit( v) {
doIteraton(v)
}
doIteraton( v) {
v.children.each {
visit(it)
}
}
}
{
[] getChildren()
}
{
[] children = []
}
{
[] children = []
}
{
count = 0
visit( n1) {
count++
.visit(n1)
}
}
http://docs.groovy-lang.org/latest/html/documentation/ 500/502
1/6/2019 DefaultVisitor now looks a bit di erent. I added a doIteration method
Groovy Language that will get the children it should iterate over and
Documentation
then call visit on each element. Per default this will call visit(Visitable) which then iterates over the children of this child. I
changed Visitable to ensure that any node will be able to return children (even if empty). I didn’t have to change the
NodeType1 and NodeType2 class, because the way the children led was de ned already made them a property, which means
Groovy is so nice to generate a get method for us. No the really interesting part is NodeType1Counter , it is interesting because
we have not changed it. super.visit(n1) will now call visit(Visitable) which will call doIteration which will start the
next level of iteration. So no change. But visit(it) will call visit(NodeType1) if it is of type NodeType1 . In fact we don’t need
the doIteration method, we could do that in visit(Visitable) too, but I thought this variant is better, because it allows us to
write a new Visitor that overwrites visit( Visitable ) for error cases which of course means we must not do super.visit(n1)
but doIteration(n1) .
Summary
In the end we got ~40% less code, a robust and stable architecture and we completely removed the Visitor from the Visitable. I
heard about visitor implementations based on Re ection to get a more generic version. Well, with this you see there is really no
need to do such thing. If we add new types we don’t need to change anything. It is said that the visitor pattern doesn’t t extreme
programming techniques very well because you need to make changes to so many classes all the time. I think I proved that this is
because of Java not because the pattern is bad or something.
There are variants of the Visitor pattern, like the acyclic visitor pattern, that tries to solve the problem of adding new node types
with special visitors. I don’t like that very much, it works with casts, catches the ClassCastException and other nasty things. In
the end it tries to solve something we don’t even get with the Groovy version.
One more thing. NodeType1Counter could be implemented in Java as well. Groovy will recognize the visit methods and call them
as needed because DefaultVisitor is still Groovy and does all the magic.
Further Information
Componentization: the Visitor example (http://se.ethz.ch/~meyer/publications/computer/visitor.pdf)
3.19.2. References
1. Erich Gamma, Richard Helm, Ralph Johnson, John Vlissides (1995). Design Patterns: Elements of Reusable Object-Oriented
Software. Addison-Wesley. ISBN 0-201-63361-2.
The canonical reference of design patterns.
2. Martin Fowler (1999). Refactoring: Improving the Design of Existing Code. Addison-Wesley. ISBN 0-201-48567-2.
3. Joshua Kerievsky (2004). Refactoring To Patterns. Addison-Wesley. ISBN 0-321-21335-1.
4. Eric Freeman, Elisabeth Freeman, Kathy Sierra, Bert Bates (2004). Head First Design Patterns. O’Reilly. ISBN 0-596-00712-4. *A
great book to read, informative as well as amusing.
5. Dierk Koenig with Andrew Glover, Paul King, Guillaume Laforge and Jon Skeet (2007). Groovy in Action. Manning. ISBN 1-
932394-84-2.
Discusses Visitor, Builder and other Patterns.
6. Brad Appleton (1999). Pizza Inversion - a Pattern for E cient Resource Consumption (http://www.bradapp.com/docs/pizza-
inv.html).
One of the most frequently used patterns by many software engineers!
7. Design Patterns in Dynamic Languages by Neil Ford. Houston Java User’s Group. Examples in Groovy and Ruby.
http://www.oracle.com/technetwork/server-storage/ts-4961-159222.pdf (http://www.oracle.com/technetwork/server-
storage/ts-4961-159222.pdf)
4. Acknowledgements
4.1. Contributors
The Groovy team would like to thank the contributors of this documentation (by alphabetical order):
Dan Allen (https://github.com/mojavelinux)
Dmitry Andreychuk (https://github.com/and-dmitry)
Hamlet D’Arcy (http://hamletdarcy.blogspot.fr/)
Aseem Bansal (https://github.com/anshbansal)
http://docs.groovy-lang.org/latest/html/documentation/ 501/502
1/6/2019 Andrey Bloschetsov (https://github.com/bura) Groovy Language Documentation
J Brown (https://github.com/JBrownVisualSpection)
Je Scott Brown (https://github.com/je brown)
Cédric Champeau (http://twitter.com/CedricChampeau)
Tobia Conforto (https://github.com/tobia)
Dimitar Dimitrov (https://github.com/ddimtirov)
Andrew Eisenberg (http://twitter.com/werdnagreb)
Marcin Erdmann (https://github.com/erdi)
Christoph Frick (https://github.com/christoph-frick)
Mario García (http://twitter.com/marioggar)
David Michael Karr (https://github.com/davidmichaelkarr)
Paul King (http://twitter.com/paulk_asert)
Guillaume Laforge (http://twitter.com/glaforge)
Peter Ledbrook (http://twitter.com/pledbrook)
Grant McConnaughey (http://grantmcconnaughey.github.io/)
David Nahodil (https://github.com/dnahodil)
James Northrop (https://github.com/jnorthr)
Marc Paquette (https://github.com/marcpa00)
Michael Schuenck (https://github.com/michaelss)
Pascal Schumacher (https://github.com/PascalSchumacher)
Shil Sinha (https://github.com/shils)
Maksym Stavytskyi (https://github.com/stavytskyi)
André Steingreß (https://twitter.com/asteingr)
Edinson Padrón Urdaneta (https://github.com/EPadronU)
Keegan Witt (https://github.com/keeganwitt)
Daniel Sun (https://twitter.com/daniel_sun)
4.2. License
This work is licensed under the Apache License, Version 2.0 (http://www.apache.org/licenses/LICENSE-2.0).
Version 2.5.5
Last updated 2018-12-21 09:39:08 AEST
http://docs.groovy-lang.org/latest/html/documentation/ 502/502
You might also like
- Working With MongoDB Data in Nodejs Apps With MongooseNo ratings yetWorking With MongoDB Data in Nodejs Apps With Mongoose153 pages
- Typescript Practice - Exercises 1. Enumerator: Pricelist (No ratings yetTypescript Practice - Exercises 1. Enumerator: Pricelist (4 pages
- Lab 03 - Version Control With GIT in Azure ReposNo ratings yetLab 03 - Version Control With GIT in Azure Repos52 pages
- Keith Tab W Tkinter Tutorial Learn TkinterNo ratings yetKeith Tab W Tkinter Tutorial Learn Tkinter241 pages
- A Level Computer Science for AQA Unit 1 (Kevin Bond)No ratings yetA Level Computer Science for AQA Unit 1 (Kevin Bond)512 pages
- Learn Python 3 - Modules Cheatsheet - CodecademyNo ratings yetLearn Python 3 - Modules Cheatsheet - Codecademy2 pages
- Object-Oriented Concepts For Database Design: Michael R. Blaha and William J. PremerlaniNo ratings yetObject-Oriented Concepts For Database Design: Michael R. Blaha and William J. Premerlani9 pages
- Characters: Character Legend Example Sample MatchNo ratings yetCharacters: Character Legend Example Sample Match5 pages
- Red Hat JBoss Enterprise Application Platform-7.1-How To Configure Server Security-en-USNo ratings yetRed Hat JBoss Enterprise Application Platform-7.1-How To Configure Server Security-en-US204 pages
- ColdFusion Interview Questions, Answers, and Explanations: ColdFusion Certification ReviewFrom EverandColdFusion Interview Questions, Answers, and Explanations: ColdFusion Certification ReviewNo ratings yet
- CACS 406 Network Administration VII Semester Elective BCA SyllabusNo ratings yetCACS 406 Network Administration VII Semester Elective BCA Syllabus3 pages
- Oracle 12cR2 Installation On Linux With ASMNo ratings yetOracle 12cR2 Installation On Linux With ASM40 pages
- Iphone App Development Company & Online Presence - A Guide!No ratings yetIphone App Development Company & Online Presence - A Guide!5 pages
- Build An ERC20 Token On Ethereum (Mehran Hydary) (Z-Library)No ratings yetBuild An ERC20 Token On Ethereum (Mehran Hydary) (Z-Library)198 pages
- WSTE 06182009 CICSWebServicesStructureDebugging WieseNo ratings yetWSTE 06182009 CICSWebServicesStructureDebugging Wiese62 pages
- Simio Installation Notes: Table 1: Download Folder Names Download Folder Name DescriptionNo ratings yetSimio Installation Notes: Table 1: Download Folder Names Download Folder Name Description5 pages
- Chapter 2: Testing Throughout The Software Developement LifecycleNo ratings yetChapter 2: Testing Throughout The Software Developement Lifecycle47 pages
- Mod Menu Log - Com - Brotato.shooting - Survivors.action - RoguelikeNo ratings yetMod Menu Log - Com - Brotato.shooting - Survivors.action - Roguelike7 pages
