\n27. The Complement Operator

The exclamation (!) sign is used switch a value to its opposite boolean value. In boolean algebra¹ this is referred to as a Not (or negation) operator.

\n\n\n \n \n \n \n \n \n \n \n \n \n\n

Complement operator
Operator
`!`

The following example makes sure that “not true” is the same as “false”:

assert !true == false\n

\n\n

The complement operator results in the following:

\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n

The complement truth table
Value	Complement
`true`	`false`
`false`	`true`

see http://en.wikipedia.org/wiki/Boolean_algebra ↩\n

",{"_1281":1282,"_42":43,"_46":47,"_44":45,"_64":65,"_1283":1284,"_1603":1279},"previewContent","

\n \n
- \n Introduction\n
  - \n Something Wrong?\n
  - \n Bookmarks\n
  - \n Conventions Used in This Book\n
  - \n Your Rights and This Book\n
  \n
- \n Legal Notices\n
\n
\n I Getting started\n
- \n 1. Introduction\n
- \n 2. Installing Groovy\n
  - \n Don’t Install Groovy\n
  - \n Install a Java Virtual Machine\n
  - \n Install Groovy\n
  \n
- \n 3. Your first lines of Groovy\n
  - \n Examining the script\n
  \n
- \n 4. Running a script\n
- \n 5. Compiling Groovy\n
- \n 6. Comments\n
  - \n Single-line comments\n
  - \n Multi-line comments\n
  - \n Usage to avoid\n
  - \n Groovydoc\n
  \n
- \n 7. Statements\n
  - \n Usage to avoid\n
  \n
- \n 8. The assert statement\n
  - \n Handling failed assertions\n
  \n
- \n 9. Reserved Words\n
- \n 10. Packages\n
  - \n Using import\n
  - \n Built in Libraries\n
  - \n Useful third-party libraries\n
  \n
- \n 11. Grape\n
\n
\n II Variables\n
- \n 12. Introduction\n
- \n 13. Declaring Variables\n
  - \n Variable names\n
  - \n Data Types\n
  \n
- \n 14. Objects\n
  - \n Declaring and using a class\n
  - \n Useful Methods\n
  - \n Existing classes\n
  - \n Classes and literal values\n
  \n
- \n 15. Booleans\n
  - \n Useful Methods\n
  \n
- \n 16. Numbers\n
  - \n Integers\n
  - \n Decimals\n
  - \n Scientific notation\n
  - \n Number Systems\n
  - \n Useful Methods and Properties\n
  \n
- \n 17. Strings\n
  - \n Escape sequences\n
  - \n GStrings\n
  - \n Multiline Strings\n
  - \n Building Strings\n
  - \n Useful Methods\n
  \n
- \n 18. Collections\n
  - \n Lists\n
  - \n Maps\n
  \n
- \n 19. Arrays\n
  - \n Manipulating arrays\n
  \n
- \n 20. Ranges\n
  - \n Half-Open Ranges\n
  - \n Ranges of Objects\n
  - \n Ranges and List Indexes\n
  - \n Ranges and Loops\n
  - \n Useful Methods\n
  \n
- \n 21. Regular Expressions\n
  - \n Regular Expression Syntax\n
  - \n Useful Methods\n
  \n
- \n 22. Data types\n
  - \n Groovy’s use of types\n
  - \n Using a specific type\n
  - \n The null Value\n
  - \n Available data types\n
  - \n Type Conversions\n
  \n
\n
\n III Operators\n
- \n 23. Introduction\n
  - \n Arithmetic and Conditional Operators\n
  - \n String Operators\n
  - \n Regular Expression Operators\n
  - \n Collection Operators\n
  - \n Object Operators\n
  \n
- \n 24. Operator Overloading\n
- \n 25. Numeric Operators\n
  - \n Operator Precedence\n
  - \n Order of Precedence\n
  \n
- \n 26. Simple Assignment Operator\n
- \n 27. The Complement Operator\n
- \n 28. Equality Operators\n
  - \n What Is Equality?\n
  - \n Precedence\n
  - \n Overloading Equality\n
  \n
- \n 29. Arithmetic operators\n
  - \n Additive Operators\n
  - \n Multiplicative Operators\n
  - \n The Power operator\n
  - \n Precedence\n
  \n
- \n 30. Relational Operators\n
  - \n Spaceship\n
  - \n Overloading the relational operators\n
  \n
- \n 31. Increment and Decrement Operators\n
  - \n Overloading the Increment and Decrement Operators\n
  \n
- \n 32. Conditional Operators\n
  - \n What Is Truth?\n
  - \n Evaluation\n
  - \n Conditional-And\n
  - \n Conditional-Or\n
  - \n Conditional Operator\n
  \n
- \n 33. Bitwise Operators\n
  - \n Truth Tables\n
  - \n Flag example\n
  - \n Shift Example\n
  \n
- \n 34. Compound Assignment Operators\n
- \n 35. String Operators\n
  - \n Concatenate Operator\n
  - \n Append Operator\n
  - \n Remove Operator\n
  - \n Remove In-Place Operator\n
  - \n Repeat Operator\n
  - \n Repeat In-PlaceOperator\n
  - \n Increment and Decrement Operators\n
  - \n Warning: Strings Are Expensive!\n
  - \n Templates\n
  \n
- \n 36. Regular Expression Operators\n
  - \n Find (=~)\n
  - \n Match (==~)\n
  \n
- \n 37. Collection operators\n
  - \n Membership Operator (Lists and Maps)\n
  - \n Append (Lists and Maps)\n
  - \n Addition (Lists and Maps)\n
  - \n Subtraction (Lists and Maps)\n
  - \n Compound Assignment Operators (Lists and Maps)\n
  - \n Spread Operator (Lists)\n
  - \n Spread-Dot Operator (Lists)\n
  - \n A Little Set Theory\n
  \n
- \n 38. Object Operators\n
  - \n Safe Navigation Operator\n
  - \n Casting Operator\n
  - \n Identity Operator\n
  - \n Type Comparison\n
  - \n Field Operator and Method Reference\n
  \n
\n
\n IV Control Flow Statements\n
- \n 39. Introduction\n
- \n 40. Blocks\n
  - \n Variable Scope\n
  \n
- \n 41. The if Statement\n
  - \n if - else\n
  - \n if - else if - else\n
  \n
- \n 42. The switch Statement\n
  - \n The Versatile Groovy switch\n
  - \n Using Ranges\n
  - \n Using Regular Expressions\n
  - \n Using Class Checks\n
  \n
- \n 43. The for Loop\n
  - \n The for-in Loop\n
  - \n The Java for-each\n
  - \n A C-style for Loop\n
  \n
- \n 44. The while loop\n
  - \n There is no do...while loop\n
  \n
- \n 45. Branching statements\n
  - \n break\n
  - \n continue\n
  - \n Labelled branching\n
  - \n return\n
  \n
\n
\n V Exceptions\n
- \n 46. Introduction\n
- \n 47. Common Exceptions\n
  - \n java.lang.NullPointerException\n
  - \n java.lang.AssertionError\n
  - \n java.lang.NumberFormatException\n
  - \n groovy.lang.MissingPropertyException\n
  - \n groovy.lang.MissingMethodException\n
  - \n java.lang.IndexOutOfBoundsException\n
  - \n java.lang.ArrayIndexOutOfBoundsException\n
  \n
- \n 48. Anatomy of an Exception\n
- \n 49. Try-Catch-Finally\n
  - \n Scope\n
  - \n try-catch\n
  - \n try-catch-finally\n
  - \n try-finally\n
  \n
- \n 50. How Much Should We try?\n
- \n 51. Causing an Exception\n
  - \n Constructing an Exception\n
  - \n Creating Your Own Exception\n
  \n
- \n 52. Catching Errors\n
- \n 53. Methods and Exceptions\n
\n
\n VI Methods\n
- \n 54. Introduction\n
- \n 55. The Basics\n
- \n 56. Parameters\n
  - \n Declaring data types for parameters\n
  - \n Multiple parameters\n
  \n
- \n 57. Default Values for Parameters\n
- \n 58. Named Arguments\n
- \n 59. Variable Arguments (Varargs)\n
- \n 60. Return value\n
  - \n Multiple Returns\n
  - \n Declaring data types for return values\n
  - \n Sequential method calls\n
  \n
- \n 61. Throwing an exception\n
- \n 62. Documenting a method\n
- \n 63. Techniques\n
  - \n Valid parameters\n
  - \n Comment your method\n
  - \n Check the parameters\n
  - \n Get really typed\n
  - \n Testing\n
  \n
\n
\n VII Closures\n
- \n 64. Introduction\n
- \n 65. Introducing Closures\n
  - \n Anonymous Functions\n
  - \n The ‘it’ parameter\n
  \n
- \n 66. Parameters\n
- \n 67. Returning Values\n
- \n 68. Closures as Method Parameters\n
  - \n Methods with Closure Parameters\n
  \n
- \n 69. Loops and closures\n
  - \n each\n
  - \n collect\n
  - \n sort\n
  \n
- \n 70. Useful Methods That Use Closures\n
  - \n any\n
  - \n find and findAll\n
  - \n split\n
  - \n with\n
  \n
- \n 71. Closure scope\n
  - \n A More Involved Example\n
  \n
\n
\n VIII Object-oriented programming\n
- \n 72. Introduction\n
- \n 73. Expando\n
  - \n Using Expando with CSV data\n
  \n
- \n 74. The basics of OO\n
  - \n Classes\n
  - \n Interfaces\n
  - \n Inheritance\n
  - \n Traits\n
  - \n Packages\n
  - \n Summary\n
  \n
- \n 75. Properties and Fields\n
  - \n Properties\n
  - \n Fields\n
  - \n Default values\n
  - \n Casting maps to objects\n
  \n
- \n 76. Getters and Setters\n
  - \n Fields\n
  - \n Pseudo properties\n
  \n
- \n 77. Methods\n
  - \n Overloading\n
  \n
- \n 78. Constructors\n
  - \n Writing your own constructor(s)\n
  - \n TupleConstructor annotation\n
  - \n Instance initializer blocks\n
  - \n When and How Things Happen\n
  - \n Constructors and instance methods\n
  \n
- \n 79. Class Methods and Variables\n
  - \n Static initializer blocks\n
  \n
- \n 80. Final Variables\n
  - \n Final fields and the map-like constructor\n
  - \n Final objects\n
  - \n Final classes and methods\n
  \n
- \n 81. Access Modifiers\n
  - \n Applying Access Modifiers\n
  \n
- \n 82. Useful Annotations\n
  - \n ToString\n
  - \n EqualsAndHashCode\n
  - \n Canonical\n
  - \n Immutable\n
  \n
- \n 83. Let Go of That Instance!\n
- \n 84. Enums\n
- \n 85. The synchronized modifier\n
\n
\n IX More object-oriented programming\n
- \n 86. Introduction\n
  - \n The Shapes demo\n
  \n
- \n 87. Organising your code\n
  - \n Packages\n
  - \n Compiling and running\n
  \n
- \n 88. Naming your packages\n
- \n 89. Packages and directory structure\n
- \n 90. The Shapes demo - packages\n
- \n 91. Interfaces\n
- \n 92. Referring to objects by their interface\n
- \n 93. General advice for interfaces\n
  - \n Groovy interfaces don’t allow default methods\n
  - \n The constant interface antipattern\n
  \n
- \n 94. The Shapes demo - Interfaces\n
- \n 95. Traits\n
- \n 96. Trait properties and fields\n
- \n 97. Trait methods\n
- \n 98. Trait static members\n
- \n 99. The class-trait relationship\n
  - \n Self types\n
  \n
- \n 100. Traits and interfaces\n
- \n 101. Implementing multiple traits\n
- \n 102. The Shapes demo - Traits\n
- \n 103. Inheritance\n
  - \n Some inheritance theory\n
  \n
- \n 104. Subclassing\n
  - \n Type comparison\n
  \n
- \n 105. Final Classes and Methods\n
- \n 106. Abstract classes\n
- \n 107. The Shapes demo - Inheritance\n
\n
\n X Going further\n
- \n 108. Other Topics\n
  - \n Type Checking\n
  - \n Static Compilation\n
  - \n Metaprogramming\n
  - \n Generics\n
  - \n Inner Classes\n
  - \n Single abstract methods\n
  \n
- \n 109. The great beyond\n
  - \n Build large applications\n
  - \n Use the Groovy ecosystem\n
  \n
- \n Appendix: The Shapes demo code listing\n
  - \n package org.groovy_tutorial.shapes\n
  - \n package org.groovy_tutorial.shapes.triangle\n
  - \n package org.groovy_tutorial.shapes.triangle\n
  \n
- \n Colophon\n
\n

Introduction

\n\n

I like Groovy.

\n\n

I like the way it lets me use the Java skills I’ve built up over the years but it makes it easier to code solutions to problems. I like the way it doesn’t, well, get in the way. With Groovy I can:

\n\n

Easily code small scripts to perform command-line tasks
Tie together existing systems and libraries - leveraging the breadth and depth of existing Java-based projects
Write entire applications that can be deployed onto any system running the Java Virtual Machine (JVM) - without having to tell people the code isn’t in Java.

\n\n

Groovy programs run on the Java Virtual Machine (JVM) and the JVM is installed across a huge spectrum of systems: desktops, servers, mobiles and the Internet of Things. Importantly, the Java world has been going through a great renewal phase. Where once the JVM and the Java programming language were almost synonyms, a range of JVM-based languages have appeared: Groovy, Scala, Clojure, Jython. These aren’t languages that run within a Java program (though many can do just that), these are languages that compile down to JVM bytecode and run in a way that means you don’t even need to tell your SysAdmin that you didn’t write it in Java. What’s more, we’re not at the “cutting edge” of this approach - it’s been going for long enough that you can expect a level of stability that supports the use of these languages in real application development.

\n\n

In the following sections I aim to guide you through the basics of Groovy. I haven’t really focussed on writing a “How to program” guide nor do I expend a lot of words comparing Groovy with Java. You may also notice that I haven’t included the output of most of the code examples - this is to save some clutter in the text and encourage you pop open a groovyConsole and try the code for yourself. Go on, you know you’ll love it.

\n\n

I really hope that this tutorial gives you a basis in understanding the Groovy language and I hope that you start to see why I like Groovy so much.

\n\n

Enjoy!

\n\n

Duncan (@groovytutorial)

\n\n\n\n

Something Wrong?

\n\n

If you find something wrong I’d really appreciate you letting me know via the GitHub issue system. Please remember that I’m not a big corporation or an automaton - I can’t respond immediately to queries and I am an assemblage of emotions that respond well to positive encouragement a lot better than negativity.

\n\n

Bookmarks

\n\n

Between Groovy and Java there’s a lot of useful websites - this is a few key ones you’ll want to have in your browser.

\n\n

Core resources to have at-hand:

\n\n

\nThe Groovy homepage is a great starting point.
The latest Groovy API documents are available at:\n
- \nThe Groovy API - aka the GAPI
- \nThe Groovy extensions to the JDK - aka the GDK
\n
The Java API always comes in handy\n
- So do The Java Tutorials\n
\n
Whilst not a perfect fit for Groovy, I tend to use the Google Java Style as my stern mentor.

\n\n

I’ve been establishing www.groovy-tutorial.org to supplement this book with practical\nGroovy tutorials. Keep an eye out for new content!

\n\n

Great blogs and sites that provide Groovy coding examples:

\n\n

\nMr Haki - A really useful site containing heaps of Groovy code examples.
\nInfoQ - Another useful site for Groovy articles.

\n\n

The book Groovy in Action (2nd Edition) will help you go further with your Groovy programming.

\n\n

If you find yourself stuck and needing some help, the following channels are worth tuning into:

\n\n

\nStackOverflow’s Groovy tag is really useful\n
- search for an answer before posting a question
- Check out their article “How do I ask a good question?” - it’s an excellent outline for asking in a way people may answer
\n
The Groovy Mailing lists are also worth joining and searching

\n\n

I suggest to anyone within the orbit of Java that “Effective Java (2nd edition)” by Joshua Bloch should not only be read (repeatedly) but always at-hand.

\n\n

Conventions Used in This Book

\n\n

I’ve tried to present this book in a manner that will suit both the reader that likes a linear path of front-to-back and those who like to dip in on specific items.

\n\n

Code

\n\n

Code is displayed using a monospaced font.

\n\n

Code presented within regular language looks something like:

\n\n

\n
Use of println as your primary testing framework is discouraged.
\n

\n\n

Blocks of code are presented as follows:

\n\n

A block of code

\n\n

def name = \"Billy\"\nprintln \"Hi there $name\"\n

\n\n\n\n

Some code doesn’t feature a title and is presented so as to be more aligned with the flow of the text:

\n\n

def name = \"Billy\"\nprintln \"Hi there $name\"\n

\n\n\n\n

I’ve opted not to display line numbers with code as it makes copy and paste difficult.

\n\n

The book formatting/layout process can cause code to be broken over to another line. In these cases a backslash (\\) is added at the end of the first line:

\n\n

def x = 10 \\\n+ 1\n

\n\n\n\n

Unfortunately this syntax isn’t always Groovy-compliant and can cause the code to fail. If a code listing doesn’t seem to work your best bet is to remove the backslash and newline.

\n\n

Asides

\n\n

I use a variety of asides to note information. These appear with an icon and some text and, on most occasions, feature a title.

\n\n\n\n\n\n\n\n

Your Rights and This Book

I’m making the “Groovy Tutorial” freely available because I feel that open source projects such as Groovy deserve to have a variety of documentation that helps people use open source software. This body of work is one that took a significant amount of unpaid time but I have benefitted from many people’s work in developing open source software and the associated, freely available text, that they make available.

\n\n

This work is licensed under a Creative Commons Attribution License - this means that you have the right to share and adapt the text as you see fit but you must give me “appropriate credit, provide a link to the license, and indicate if changes were made. You may do so in any reasonable manner, but not in any way that suggests the licensor endorses you or your use”. If you decide to use the whole text or parts thereof in a manner that derives you an income I think it’d be civil of you to consider contributing to my retirement fund.

\n\n

All code samples are licensed under the Apache License, Version 2.0.\nIf you would like to browse a subset of the code examples used in this book you’ll find them in the GitHub repository.

\n\n

The “source” for this book is written in Markdown, based on the LeanPub Manual. You can access the source from my GitHub repository.

\n\n

I don’t provide any warranties, guarantees or certainties¹. You should use this text to help you in your Groovy coding but you are responsible for your journey :)

\n\n

… or pekignese↩\n

\n\n\n

Legal Notices

\n\n

Acknowledgement of trademarks:

\n\n

Java™ is a registered trademark of Oracle and/or its affiliates.
Apple® and OS X® are trademarks of Apple Inc., registered in the U.S. and other countries
Microsoft® and Windows® are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.
Spring IO® and Grails™ are trademarks/service marks of Pivotal Software, Inc. and its subsidiaries and affiliates
Gradle™ is a trademark of Gradle, Inc. in the United States and/or other jurisdictions.
Android™ is a trademark of Google Inc.
Git™ is a trademark of the Software Freedom Conservancy.

\n\n

None of the companies listed above endorse this book.

\n\n

The Groovy logo that features on the cover page was sourced from the groovy-website GitHub project

\n\n

If you believe that any part of this text infringes on your intellectual property, copyright, trademark(s) or any other legal structure then please contact me - I’m sure we can sort it out.

\n\n\n

\nI Getting started

\n\n

\n1. Introduction

\n\n

Getting to know a new programming language can be both fun and, sometimes, frustrating. In this section we’ll get Groovy installed, write the mandatory “Hello, World” program and look at some of the basic aspects of Groovy.

\n\n

\n2. Installing Groovy

\n\n\n\n

There are a few methods for installing Groovy on your system and this section will describe the basics for getting started. Before you get started make sure that any installations are for the versions listed in the table below:

\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n

System	Version
Java JDK	8 (7 is fine too)
Groovy	2.4.0 (or higher)

\n\n\n\n

Don’t Install Groovy

\n\n

I know this chapter is about installing Groovy but perhaps it’s worth leaving this until later. The Groovy web console is an online Groovy console that should let you run most of the sample code provided in this book. Provided you have web access you can skip through to the next chapter and get straight into writing some code!

\n\n

However, please note that the web console has some limitations and won’t run code that attempts to access URLs and files.

\n\n

Install a Java Virtual Machine

All methods for installing Groovy require that you have a Java Virtual Machine (JVM) installed. For the purposes of this book we’ll use the Java 8 SE JDK (Java 8 Standard Edition Development Kit). You’ll notice that Java 8 may also be represented as Java 1.8 - the former is the Java Platform version number (8) and the latter is the version string (1.8).

\n\n\n\n

To install the Java JDK, head to the Oracle site and locate the download appropriate to your platform: Oracle JDK Downloads. For the most part these installs are straight-forward and have enough associated documentation so we won’t go through this step-by-step.

\n\n

Before moving onto the Groovy installation I’d like to make you aware that the Oracle JDK is not the only version of the JDK available. As you become more comfortable with working in a Java-based environment you might like to take a look at the Open JDK.

\n\n

Install Groovy

Once you have the JDK installed it’s time to get Groovy. We’ll be using Groovy 2.4 throughout this book. Other (newer) versions may work fine - it’s just that the examples used throughout the book have been tested against Groovy 2.4.

\n\n

The following subsections will guide you through an installation based on which platform you’re using.

\n\n

Windows

The Groovy Download page includes links to a Windows installer - download this and run the installer using the provided defaults (it’s as easy as that).

\n\n

Just make sure you’re downloading a 2.4.x version!

\n\n\n

Once you have the JDK and Groovy installed you should see the GroovyConsole application in your Windows 7 Start menu. Start up the GroovyConsole application and you should be good to go.

\n\n

Mac OSX and Linux

SDKMAN! is the best tool for getting Groovy running on your system. The homepage is http://sdkman.io/ but you don’t need to visit it to run an installation.

\n\n

If you are comfortable with using the terminal then you just need to run the following command as a regular user¹:

\n\n

curl -s get.sdkman.io | bash\n

\n\n\n\n

Once SDKMAN! has been installed, run the following command to determine which versions of Groovy are available:

\n\n

sdk list groovy\n

\n\n\n\n

You’ll see a large table of version numbers but are most interested in those marked with 2.4.x - you’ll want the version with the highest value of x (e.g. 2.4.4). To install Groovy you now just call sdk as below:

\n\n

sdk install groovy 2.4.4\n

\n\n\n\n

Checking Groovy (all platforms)

Once you have the JDK and Groovy installed, run the following command to double-check your Groovy version:

\n\n

groovy -v\n

\n\n\n\n

You should see something like the following output:

\n\n

Groovy Version: 2.4.0 JVM: 1.8.0_31 Vendor: Oracle Corporation OS: Mac OS X\n

\n\n\n\n

This tells me that I am running:

\n\n

Groovy 2.4.0
The Oracle Java 8 JVM
The Apple Mac OS X operating system

\n\n

Alternatives

The Groovy Download page provides binary and source releases for Groovy. These are perfectly fine to use but you’ll need to setup your system path to get up and running.

\n\n

For those on Mac OS X you can also explore one of the following package manager options:

\n\n

MacPorts
Homebrew

\n\n

Linux users may find Groovy packages in their distribution’s package repository but check the version being installed.

\n\n

The curl command line tool is used for transferring data. It’s very likely that your Linux distribution’s package manager (yum, apt-get etc) includes a copy of cURL but if it doesn’t, visit http://curl.haxx.se/ to download it.↩\n

\n\n\n

\n3. Your first lines of Groovy

\n\n\n\n

The Groovy Console provides a handy environment for preparing and testing basic Groovy scripts. In order to open the console you need to start a command line (or terminal) session and enter the following command:

\n\n

Start the console

\n\n

groovyConsole &\n

\n\n\n\n\n\n

The Groovy Console should look something like the following screen grab:

\n\n\n

The main parts of the console are:

\n\n

The top half is the editor area for adding your Groovy script
The bottom half is the output area that displays the results of your script
The menu provides the standard tools for opening and saving files (File) and cut/copy/paste (Edit)
The Script menu gives you a number of functions you’ll use as you work through this book:\n
1. \nRun will run the script
2. \nRun Selection allows you to select (highlight) part of your script and run only that section
\n
The View menu lets you reset the output area (Clear Output)\n
1. I’d suggest that you select Auto Clear Output on Run as this helps reduce confusion
\n

\n\n

Once you have the Groovy Console open, enter the following line in the editor area:

\n\n

Let’s get groovy

\n\n

print 'hello, world'\n

\n\n\n\n\n\n

Once that’s ready, go to the menu and select Script -> Run and you should see your output in the bottom half of the window something like the image below:

\n\n\n

If you see the output hello, world then congratulations - you’ve taken your first step into a larger world.

\n\n

Examining the script

Our first Groovy script is very simple: it uses the print method (function) to output the string hello world to the console.

\n\n\n\n

For those that have come from languages such as C++ and Java the script print \"hello, world\" probably appears to be missing items such as imported libraries for output and “container” or “boilerplate” code that sets up the context of the code. In fact, if we were to write this code in Java it would look something like:

\n\n

Hello,world - Java style

\n\n

class Hello {\n    public static void main(String[] args) {\n        System.out.print(\"hello, world\");\n    }\n}\n

\n\n\n\n\n\n

When I look at the code above I see why Groovy is so appealing to me:

\n\n

Groovy lets me focus on solving the problem and not working through so much decoration code.\n
- Groovy doesn’t need semi-colons at the end of each statement
- Groovy essentially builds the Hello class around the script
\n
The Groovy code is much more readable and this should help reduce bugs (or at least make finding them easier)
Most Java code is valid Groovy code - you can copy that Java code into the Groovy Console and run it - it will work
Groovy lets you use the comprehensive standard Java libraries and the extensive third-party libraries written by the Java developer community.\n
1. But also extends these standard libraries with some great timesavers.
\n

\n\n

Groovy gives us the brevity and flexibility of a scripting language (such as Python, Ruby and Perl) whilst letting us tap into the galaxy of existing Java libraries.

\n\n

\n4. Running a script

Now that we can output something to the screen, let’s try and make our example a little more personal. Clear the Groovy Console editor and enter the following:

\n\n

Using command-line arguments

\n\n

println \"hello, ${args[0]}\"\n

\n\n\n\n

Before we try to run this, let’s look at what’s in the code:

\n\n

\nprint has become println - this does the same thing as our previous use of print but adds a new line at the end of the output.\n
- This makes the output easier to read when we’re running on the command line
\n
Instead of the text world we’re now using ${args[0]}:\n
- \nargs is a variable (an array¹) that holds any command-line arguments we pass to the script\n
  - You may have noticed String[] args in the Java version of hello, world - essentially Groovy is writing that segment of code for you.
  - \nargs[0] is the first element in the args array - this is the first parameter (command-line argument) passed to the script
  \n
- The ${...} notation tells Groovy that the contents need to the resolved into a value - in this case Groovy needs to determine the value of args[0] before displaying the output
\n

\n\n

Don’t worry if this appears to be a big jump from our hello, world - there’s a range of concepts being introduced and we’ll work through them in this tutorial section. For now, put the code into your Groovy Console and know that, when run, your script will say hello to a specified person.

\n\n

You now need to save your script so go to the File menu and select Save. When prompted, name the file Hello.groovy and save it into a directory you can access.

\n\n

Unfortunately we can’t run this script in the Groovy Console as it doesn’t provide an option for passing in a command-line parameter. Follow this process to run the script:

\n\n

Open a command prompt (terminal) and change to the directory (cd) into which you saved Hello.groovy.
Type the command groovy Hello.groovy Newman and press the return key

\n\n

You should see the following output:

\n\n

hello, Newman\n

\n\n\n\n

Of course you can change “Newman” to be any name so feel free to try out your name, the dog’s name etc. However, make sure you add a name - your script needs that parameter or you’ll see a disconcerting error.

\n\n

More about arrays in a little bit↩\n

\n\n\n

\n5. Compiling Groovy

You can compile a Groovy script into a class file - the same type of file that Java developers compile their code into. The resulting class file is in bytecode format that can be read by the Java Virtual Machine (JVM). Once compiled to bytecode, Groovy code can work on the same JVM that runs existing Java systems - this is extremely handy if you work in a Java-centric organisation but want to use Groovy.

\n\n

In order to compile Hello.groovy we will use the groovyc command in the command-prompt as follows:

\n\n

groovyc Hello.groovy\n

\n\n\n\n

When you look at the directory contents you should now see a file named Hello.class. Don’t try to read the contents of the file - it’s now in bytecode.

\n\n

We’ll explore this further in the Organising your code chapter.

\n\n

\n6. Comments

\n\n\n\n

Comments are not read by the Groovy compiler - they’re purely used to help humans follow your code. They’re really important once your code becomes more complex and your programs larger. Key places you’ll see/use comments are:

\n\n

When a complex algorithm is being used
When specific business logic is being implemented
For documenting interfaces that other coders will use
To remind you why you chose one approach over another - really handy when you revisit the code in 6-weeks and say “why did I do it that way?”.

\n\n

Single-line comments

A single-line comment is introduced with two forward slash characters (//):

\n\n

Single-line comment

\n\n

//This is a single-line comment\nprintln \"hello, world\"\n

\n\n\n\n

Single-line comments can be appended to a Groovy statement:

\n\n

Inline comments

\n\n

def radius = 10\ndef pi = 3.14 //This is not very precise\ndef area = pi * (radius * radius)\n

\n\n\n\n

Multi-line comments

\n\n

A multi-line comment is introduced by the characters /* and terminated with the characters */. Generally, the /* and */ appear on their own line:

\n\n

Multi-line comments

\n\n

/*\nThis is a multi-line comment\nand here is the second line\n*/\n

\n\n\n\n

Multi-line comments are most commonly formatted with an asterisk (*) on each line, aligned with the introductory asterisk as follows:

\n\n

Formatting multi-line comments

\n\n

/*\n * This is a multiline comment\n * and here is the second line\n */\n

\n\n\n\n

Multi-line comments can be introduced and terminated on a single line:

\n\n

Multi-line one liners

\n\n

/* This is a multiline comment on a single line */\n

\n\n\n\n

Nesting within a multi-line comment is not possible, rendering the following code invalid:

\n\n

Don’t nest comments

\n\n

/*\n * Multi-line comments cannot\n * /* be nested */\n */\n

\n\n\n\n

Usage to avoid

In a similar vein to single-line comments, multi-line comments can be appended to a statement. However, the single-line comment is generally more readable than the following example:

\n\n

def radius = 10\ndef pi = 3.14 /* This is not very precise */\ndef area = pi * (radius * radius)\n

\n\n\n\n

Even less expected is a multi-line comment appended to a statement in the following manner:

\n\n

def radius = 10\ndef pi = 3.14 /* This is not very precise\n                and should really use java.lang.Math.PI */\ndef area = pi * (radius * radius)\n

\n\n\n\n

In such a case the multi-line comment should appear above the statement being discussed:

\n\n

def radius = 10\n/*\n * This is not very precise\n * and should really use java.lang.Math.PI\n*/\ndef pi = 3.14\ndef area = pi * (radius * radius)\n

\n\n\n\n

Use of a comment within a statement should never be contemplated as it results in code that is hard to read:

\n\n

def radius = 10\ndef pi = 3.14\ndef area = pi * /* I should find out how to square */ (radius * radius)\n

\n\n\n\n

Groovydoc

\n\n

Java provides a very handy tool for documenting the outward-facing aspects of your code - i.e. those items that others may reuse - it’s called javadoc¹. Groovy has its own version called groovydoc. Essentially this is the same tool as javadoc but is run over groovy code.

\n\n

See the Javadoc guide ↩\n

\n\n\n

\n7. Statements

\n\n\n\n

A Groovy statement is generally completed by an end-of-line (EOL) character such as a carriage return:

\n\n

def num = 21\nprintln num\n

\n\n\n\n

A semicolon (;) can be used to explicitly mark the end of a statement however this is deemed to be redundant in most cases and spoils readability:

\n\n

def num = 21;\nprintln num;\n

\n\n\n\n

The backslash (\\) is used indicates that a statement continues on the next line. The example below uses continuation to break up a long statement:

\n\n

def solution =  1 * 2 * 3 \\\n                * 4 * 5 * 6\n

\n\n\n\n

Without the backslash the code above would cause an error but a minor rewrite will work:

\n\n

def solution =  1 * 2 * 3 *\n            4 * 5 * 6\n

\n\n\n\n

I would suggest the first version is easier to read and explicitly indicates that you intend to carry into the next line. However, statements can span multiple lines without a backslash provided Groovy can determine that the lines make up a single statement. This feature should be utilised if it aids in improved readability - this is often referred to as line-wrapping. For example, an array declaration that provides a number of entries may be written as:

\n\n

Okay formatting

\n\n

def myArray = ['Tasmania', 'Victoria', 'New South Wales', 'Queensland', 'Western\\\n Australia', 'South Australia']\n

\n\n\n\n

The judicious use of line-wrapping may improve readability:

\n\n

Better formatting

\n\n

def myArray = ['Tasmania',\n               'Victoria',\n               'New South Wales',\n               'Queensland',\n               'Western Australia',\n               'South Australia']\n

\n\n\n\n

It is difficult to provide specific metrics regarding readability in these cases and the programmer is left to determine the best use of white space and placement.

\n\n

Usage to avoid

\n\n

A semicolon can be used to separate two statements appearing on the same line:

\n\n

One statement per line please

\n\n

def num = 1 + 1; println num\n

\n\n\n\n

The presentation of multiple statements in a single line should be avoided - it’s not easy to read and is likely to trip you up at some point.

\n\n

Groovy is very forgiving of statements spread over more than one line but usage such as the one below should be avoided as it reduces readability. For example, the following code will actually work but it looks odd and isn’t worth the hassle:

\n\n

Keep things together

\n\n

def num = 1 +\n1\nprintln num\n

\n\n\n\n

\n8. The `assert` statement

\n\n\n\n

The assert statement is perhaps out of order being described here but it will be relied on in many code examples.

\n\n\n\n

The assert statement evaluates a boolean expression (one that is true or false). If the result is false then the assertion has failed, the program is halted and an error is reported. The following example provides an obviously incorrect statement:

\n\n

Basic assert

\n\n

assert 1 == 2\n

\n\n\n\n

An expression can be appended to the assert statement after a colon (:):

\n\n

Assert with expression

\n\n

assert true == false : 'true cannot be false'\n

\n\n\n\n

The second expression can be anything Groovy can evaluate and the result is used in the error message. The following example will (unhelpfully) place the number “8.0” in the error message:

\n\n

Assert with expression

\n\n

assert true == false : Math.sqrt(64)\n

\n\n\n\n

Handling failed assertions

For the purposes of our tutorial scripts, using asserts is a handy way to demonstrate a result for a problem. However, it’s not good practice to have a program suddenly just quit when an assertion fails. When you start writing large programs, your code should aim to “fail gracefully” unless it’s really in a position where bailing out is the only option.

\n\n

Groovy (unlike Java) does not provide a mechanism for turning off assertions so be careful about where you use the assert statement in larger systems. Remember that a failed assert raises an Error (which signals a critical problem) rather than an Exception (from which a program is more likely to recover). Arguably, in running (production) systems, assertions are best suited to dark places in code that should never be reached - they flag when the extremely unlikely condition has happened.

\n\n

The error raised by a failed assertion can be caught within a try-catch and handled but this isn’t how errors are usually treated (we normally just let them happen). The following example illustrates a class handling a failed assertion by logging the problem - don’t be concerned if you don’t follow the code as it utilises a number of concepts not yet visited:

\n\n

Handling failed assertions

\n\n

import groovy.util.logging.*\n\n@Log\nclass AssertionTest {\n    static void runTest() {\n        try {\n            assert true == false : 'true cannot be false'\n        } catch(AssertionError err) {\n            log.severe \"An assertion failed ${err}\"\n        }\n    }\n}\n\nAssertionTest.runTest()\n

\n\n\n\n

The section on Exceptions will explain this syntax in more depth.

\n\n\n\n

Although it’s Java-focussed, check out the Programming with Assertions guide for more information.

\n\n

\n9. Reserved Words

\n\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n

Groovy’s reserved words
abstract	as	assert	boolean	break
byte	case	catch	char	class
const	continue	def	default	do
double	else	enum	extends	false
final	finally	float	for	goto
if	implements	import	in	instanceof
int	interface	long	native	new
null	package	private	protected	public
return	short	static	strictfp	super
switch	synchronized	this	threadsafe	throw
throws	trait	transient	true	try
void	volatile	while

\n\n

Groovy relies of a number of key words that it reserves for its own use. This means that you shouldn’t use these words for the names of variables and other items you declare. For example, the code below won’t run as package is a reserved word:

\n\n

def package = 'my package'\n

\n\n\n\n

\n10. Packages

\n\n\n\n

Except for very small programs, most Groovy and Java-based programs are made up of packages of code:

\n\n

The package keyword is used to designate that a class is part of a package and we’ll cover this more fully in the Organising your code chapter.
The import keyword is used to import classes from other packages into a program.

\n\n

Consider the sample code below:

\n\n

Using imports

\n\n

package test\n\nimport java.time.Year\n\nprintln Year.now()\n

\n\n\n\n

I’ve indicated that this code:

\n\n

Is part of a package named test\n
Needs to use the Year class defined in the java.time package

\n\n

This notion of packaging allows for thousands of developers to create classes and packages without clashing. If another developer creates a Year class but puts it into a package with a name other than java.time then all will be well. Oh, and you’d never start your own package name with java. - that really won’t work out well for you¹.

\n\n

Before you write any new code you should always check out these resources in the order I’ve given below:

\n\n

The Groovy API (GAPI)\n
The Groovy extensions to the JDK (GDK)\n
The standard Java classes (JDK)\n

\n\n

Using the order I’ve provided above lets you look at the libraries providing the Groovy approach first (the GAPI and GDK) then looking at the Java standard library (JDK).

\n\n

For the rest of this chapter I’ll focus on import as that will help us in the early set of tutorials.

\n\n

Using `import`\n

\n\n

You can import other classes in a variety of manners - let’s take a look.

\n\n

Basic Imports

The basic form of imports are the most commonly seen and you should get accustomed to them pretty quickly.

\n\n

import java.time.Year: This will import the Year class from the java.time package
import java.time.*: This is a star (wildcard) import; This will import all classes in the java.time package

\n\n

Static imports

\n\n

Static imports can help your code look a little cleaner as they give you an easy way to refer to useful constants and functions (methods) declared in other code packages².

\n\n

import static java.lang.Math.PI: This is a static import; This lets you import static items from another class; In this example I’ve imported the PI constant from the java.lang.Math class and can now use it as if it was just part of my code: println PI\n
import static java.lang.Math.PI as pi: This is a static import with aliasing\n; This is the same as the previous import but I can use the as keyword to rename the item being imported - I’ve decided to use PI but refer to it using the lowercase form (pi)
import static java.util.UUID.randomUUID as generateId: This is also a static import with aliasing but I’ve imported the randomUUID static method and given in the alias generateId\n; I can now call println generateId() in my program
import static java.lang.Math.*: This is a static star import and will import all static elements described in Math and let me refer to them directly in my program.

\n\n

I’ve thrown the term static around a lot here - don’t worry too much about this for now as we’ll really only need basic imports for now. The notion of static will be covered when we get to object-oriented Groovy.

\n\n

Built in Libraries

\n\n

The following libraries are imported into Groovy by default - you don’t need to do anything to start using them:

\n\n

java.io.*
java.lang.*
java.math.BigDecimal
java.math.BigInteger
java.net.*
java.util.*
groovy.lang.*
groovy.util.*

\n\n

Groovy is able to make use of classes within these packages without explicitly importing them. You can still declare them with import and you’ll notice various development environments (IDEs) will do this regardless of Groovy’s default - either way it’ll be groovy.

\n\n

Useful third-party libraries

There is an extensive body of existing Java libraries available to the Groovy developer and it’s best to do some investigating before you write your own code - re-using well-supported libraries is a real time saver - here’s a couple to take a look at:

\n\n

Apache Commons
Google Guava

\n\n

In the olden days (in Java-time) you’d often have to download the third-party library you wanted, download any other libraries it depended on, store them in the correct place (called a Classpath) and then you could start using it. Time went by and systems such as Apache Maven came along to make it easier to grab a copy of your dependencies. This then lead to The (Maven) Central Repository and made it even easier to grab the libraries you needed.

\n\n\n\n

There’s actually a package naming convention that is very easy to follow.↩\n
We’ll describe how these are written in the Class Methods and Variables chapter.↩\n

\n\n\n

\n11. Grape

Whilst you can use Maven or (even better) Gradle to grab dependencies, Groovy includes a dependency manager called Grape that you can start using straight away.

\n\n

Say I wanted to grab a copy of my favourite web page and had worked out that Apache’s HTTP Components would really help me. I can search the Maven Central Repository and find what I need. In fact, that web page even tells me how to use the library with Grape:

\n\n

Grape example

\n\n

@Grapes(\n@Grab(group='org.apache.httpcomponents', module='httpcomponents-client', version\\\n='4.4')\n)\n

\n\n\n\n\n\n

Grape uses annotations - essentially the “at” (@) sign followed by a name - to do its thing. In the example above:

\n\n

\n@Grapes starts of the grape listing\n
- You need this if you’re grabbing several libraries in the same segment (node) of your code - we can actually ignore this in smaller examples.
\n
Each grape is declared using @Grab and providing the following:\n
- The group that holds the module
- The name of the module\n
- The required version of the module\n
\n

\n\n

In the code below I use the Apache HTTP Components library to report on the HTTP status line from my request to “http://www.example.org”. I’ve trimmed off the @Grapes as I just need to Grab one module:

\n\n

Using Grape

\n\n

@Grab(group='org.apache.httpcomponents', module='httpclient', version='4.3.6')\nimport org.apache.http.impl.client.HttpClients\nimport org.apache.http.client.methods.HttpGet\n\ndef httpclient = HttpClients.createDefault()\ndef httpGet = new HttpGet('http://www.example.org')\ndef response = httpclient.execute(httpGet)\n\nprintln response.getStatusLine()\n

\n\n\n\n\n\n

You can use a short-form version of @Grab using the format <group>:<module>:<version> - this would let us use the following:

\n\n

Short-form grape

\n\n

@Grab('org.apache.httpcomponents:httpclient:4.3.6')\n

\n\n\n\n

Once you start building more complex programs you will probably turn to Gradle but Grape works just fine for these tutorials.

\n\n

\nII Variables

\n\n

\n12. Introduction

\n\n

Variables are (perhaps unsurprisingly), items that can change. Essentially a variable is a “box” that can hold a value. Groovy is a “dynamic language” in that it allows you to easily store and manipulate variables regardless of their value. This places it in similar company to Python and Ruby but, as a child of Java, Groovy can also operate as a “typed language”. In typed languages we can specify the data type (e.g. a number or piece of text) of the variable.

\n\n

Groovy lets us work in both language modes - dynamic and typed - and this flexibility makes it that much easier to use.

\n\n

\n13. Declaring Variables

\n\n\n\n

Groovy provides a few ways to create a variable but the best one to start with is to use the def keyword. In the example below I define (def) a new variable named score that can be used to hold a value later in my program:

\n\n

Defining a variable

\n\n

def score\n

\n\n\n\n

In the next example I assign score a value of 10 and ask Groovy to display the value of score using println:

\n\n

Using a variable

\n\n

def score\nscore = 10\nprintln score\n

\n\n\n\n

Instead of declaring score and then assigning it the value 10 I can do this on a single line using def score = 10. I do just this in the example below and then change the value of score (it is a variable after all) - try this in your Groovy Console and the printlns will show you the value of score after it’s been set.

\n\n

Changing the value

\n\n

def score = 10\nprintln score\nscore = 11\nprintln score\n

\n\n\n\n

You’ll note that the second time I use score I don’t need the def prefix as I’ve already declared score and don’t need to redeclare it.

\n\n\n\n

If we’re declaring a number of variables we could provide a def on each line:

\n\n

def myNumber\ndef myName\n

\n\n\n\n

Alternatively, the previous example could be represented on a single line in which each variable is separated by a comma (,):

\n\n

def myNumber, myName\n

\n\n\n\n

You can assign values to variables defined on a single line:

\n\n

def number1 = 10, number2 = 20\n

\n\n\n\n

A set of variables can be assigned values from a list (multiple assignment):

\n\n

Multiple assignment

\n\n

def number1, number2\n(number1, number2) = [10, 20]\n\nassert number1 == 10\nassert number2 == 20\n

\n\n\n\n

In the next example a third variable is introduced but the assignment list only provides two elements. This will result in number1 and number2 being set but number3 remaining without a value (null):

\n\n

Multiple assignment

\n\n

def number1, number2, number3\n(number1, number2, number3) = [10, 20]\n\nassert number1 == 10\nassert number2 == 20\nassert number3 == null\n

\n\n\n\n

Finally, we can perform multiple assignment at the point of declaring the variables:

\n\n

Multiple assignment

\n\n

def (number1, number2, number3) = [10, 20, 30]\n\nassert number1 == 10\nassert number2 == 20\nassert number3 == 30\n

\n\n\n\n

Variable names

Variable names must meet the following criteria:

\n\n

Must start with a letter (upper-case [A-Z] or lower-case [a-z])\n - The underscore (_) is also allowed but this is very strongly discouraged
Must only contain letters, digits (0-9) or an underscore (_)\n
- The dollar-sign ($) is also allowed but very strongly discouraged
\n
Must not match a keyword (reserved word)

\n\n

The use of literate variable names that comply to the criteria is encouraged. For example, a variable named x provides little information as to its role whereas accountNumber is likely to be clear within the context of a broader system.

\n\n

Data Types

Data types define the sort of data a variable can hold. Most programming language feature the following data types:

\n\n

Booleans\n
- A logical value of true or false\n
\n
Characters and strings\n
- A character is a single letter, number or symbol (e.g. #)
- A piece of text is referred to as a “string”
\n
Numbers\n
- Integers (whole numbers) both positive and negative
- Decimals (fractional numbers) both positive and negative
\n
Dates and times\n
- You know, like dates and times
\n
Lists and sets\n
- A variable that holds a number of values (list)
- A variable that holds unique values (set)
\n
Maps\n
- A variable that holds a number of values, each referred to by a key
\n
Ranges\n
- A numeric sequence between a start and an end value - e.g. 1 to 10
\n

\n\n

Being an object-oriented programming language, Groovy lets you also define your own types of objects (called classes).

\n\n

Groovy allows you to create and use variables without declaring a data type - often called dynamic typing. Java, on the other hand, uses static typing and you need to tell Java the data type you want to use when declaring a variable. Once again, Groovy is flexible and lets you use dynamic or static typing (or both) in your programs.

\n\n

\n14. Objects

\n\n\n\n

But what is an object? Well, an object is an encapsulation of properties and methods:

\n\n

\nProperties and Fields are variables that hold data about the object\n
- For example, a person object may have properties such as name and email\n
- There is a difference between Properties and Fields but we’ll look into that later.
\n
\nMethods are a means for accessing and manipulating the object’s properties\n
- For example a person object may have methods such as getName() and setName(name)\n
- Methods can take parameters and/or return values. For example: getName() would return the person’s name; and setName(name) takes 1 parameter (name) and sets the person’s name to that value
- Methods are sometimes called functions\n
\n

\n\n

We use the class structure to define this assembly of properties and methods.

\n\n\n\n

Declaring and using a class

\n\n

Let’s look at a Groovy script that declares a new class:

\n\n

Declaring a new class

\n\n

class Person {\n    def name\n    def email\n\n    def getName() {\n        return this.name\n    }\n\n    def setName(name) {\n        this.name = name\n    }\n\n    def getEmail() {\n        return this.email\n    }\n\n    def setEmail(email) {\n        this.email = email\n    }\n}\n\n// Create a new variable to hold an instance of the Person class\ndef david = new Person(name: 'David', email: 'david@example.com')\n\n// Change David's email address:\ndavid.setEmail('dave@example.com')\n\n// Print out David's information\nprintln david.getName()\nprintln david.getEmail()\n

\n\n\n\n

A class is defined using the class keyword and it’s best practice to use an uppercase letter for the first character: class Person {

\n\n\n\n

We declare the two properties in much the same way as we do for any variable:

\n\n

Properties

\n\n

def name\ndef email\n

\n\n\n\n

A number of methods are declared to let us set and retrieve (get) the values of the object’s properties:

\n\n

Methods

\n\n

def getName() {\n    return this.name\n}\n\ndef setName(name) {\n    this.name = name\n}\n\ndef getEmail() {\n    return this.email\n}\n\ndef setEmail(email) {\n    this.email = email\n}\n

\n\n\n\n\n\n

After we’ve declared the Person class we can now create instances of the class and assign values to the properties:

\n\n

Creating an instance

\n\n

def david = new Person(name: 'David', email: 'david@example.com')\n

\n\n\n\n

We use def david as we would for other variables and then use new Person to indicated that david will hold an instance of the Person class. Lastly we call a special method called a constructor that Groovy provides us for our objects: (name: 'David', email: 'david@example.com'). This sets up david with starting values for the properties.

\n\n\n\n\n\n

At some point David changes his email address so we call the setEmail method:

\n\n

david.setEmail('dave@example.com')\n

\n\n\n\n

You can see that the method call uses dot-point notation of <variable name>.<method name> - the dot (.) separates the variable name (david) from the method (setEmail).

\n\n

Lastly, we use the two get methods to display david’s information:

\n\n

Calling methods

\n\n

println david.getName()\nprintln david.getEmail()\n

\n\n\n\n

The example Person class has demonstrated a number of Groovy’s object-oriented programming syntax:

\n\n

Creating a new class with properties and methods
Creating a new instance of the class and calling its constructor
Changing (setting) and retrieving (getting) the instance’s properties

\n\n

You can create lots of Person instances and each will exist in their own context. This means that david and sarah don’t get mixed up:

\n\n

Creating instances

\n\n

def david = new Person(name: 'David', email: 'david@example.com')\ndef sarah = new Person(name: 'Sarah', email: 'sarah@example.com')\n

\n\n\n\n

Useful Methods

\n\n

In the Groovy/Java family tree, java.lang.Object is the grand-daddy of all classes. Using a system called “inheritance”, each new class inherits attributes such as methods and properties from their forebears. Even the Person class I described above inherits from java.lang.Object and the Groovy developers have enhanced that class further! This means that all classes have built-in features that we can access. Let’s look at a few of them.

\n\n

`class`

\n\n

The class property is used to access the Class that defines the object. This can be really useful when we want to check what sort of object we’re dealing with.

\n\n

The class property

\n\n

class Person {\n    def name\n    def email\n}\n\ndef david = new Person(name: 'David', email: 'david@example.com')\n\nprintln david.class.name\n

\n\n\n\n

`dump()`

\n\n

This will return a String that describes the object instance’s internals. Try out the following code to see what gets dumped:

\n\n

The dump method

\n\n

class Person {\n    def name\n    def email\n}\n\ndef david = new Person(name: 'David', email: 'david@example.com')\n\nprintln david.dump()\n

\n\n\n\n

`with()`

\n\n

This method works with closures (we’ll cover them later) to give us an easy format for accessing a object’s properties in methods. In the example below I wrap some code using with and don’t have to use david.name and david.email to access those properties:

\n\n

The with method

\n\n

class Person {\n    def name\n    def email\n}\n\ndef david = new Person(name: 'David', email: 'david@example.com')\n\ndavid.with {\n    println name\n    println email\n}\n

\n\n\n\n

Existing classes

\n\n

The great strength/benefit/bonus of an object-oriented programming platform such as Java is the vast array of existing libraries of objects that you can reuse in your code. In Groovy and Java the listing of these available objects are referred to as the Application Programming Interface (API).

\n\n

If we were going to create a variable to hold a string (a piece of text) we would do something like:

\n\n

Creating a new String

\n\n

def quote = 'Well may we say \"God save the Queen\", because nothing will save the\\\n Governor-General!'\n

\n\n\n\n

We could also use the following code to do exactly the same thing as the code above:

\n\n

Also creating a new String

\n\n

def quote = new String('Well may we say \"God save the Queen\", because nothing wi\\\nll save the Governor-General!')\n

\n\n\n\n

This looks similar to the way we created an instance of the Person class - we create a new instance of String and pass the text into the constructor.

\n\n\n\n

Now that we have our quote string we actually also get a number of methods that help us handle our variable:

\n\n

Handy String methods

\n\n

def quote = 'Well may we say \"God save the Queen\", because nothing will save the\\\n Governor-General!'\n\n//Display the quote in upper case letters\nprintln quote.toUpperCase()\n\n//Display the quote backwards\nprintln quote.reverse()\n\n//Display the number of characters in the quote\nprintln quote.size()\n

\n\n\n\n

The example above demonstrates how we can call methods on an object instance and you’ll see this used in the rest of the tutorials. Be sure to try out the code above to see what it does!

\n\n

Classes and literal values

Literal values are best thought of the value you would write down:

\n\n

Boolean:\n
- true
- false
\n
Numbers:\n
- 42
- 3.14
\n
Strings (text):\n
- ‘hi there’
\n

\n\n\n\n

We can call methods directly on literal values as Groovy will create an appropriate object instance for us:

\n\n

Calling a method from a literal

\n\n

assert 1.plus(1) == 2\n

\n\n\n\n

This definitely looks a bit odd but think of it this way:

\n\n

Groovy sees the literal value 1 followed by a method call
Groovy creates a number object instance for 1\n
Groovy then calls the plus method against the new number instance

\n\n\n\n

This can start to be very useful when you look at lists and ranges - something we’ll get to soon.

\n\n

Lastly, as the literal is put into an object we can access methods and properties for the object. In the example below I can see what data type Groovy is actually using when I use 3.14:

\n\n

Accessing properties from a literal

\n\n

println 3.14.class.name\n

\n\n\n\n

\n15. Booleans

\n\n\n\n

Boolean variables are perhaps the simplest and can hold a value of either true or false.

\n\n

Booleans

\n\n

def truth = true\ndef lies = false\n

\n\n\n\n

Useful Methods

\n\n

Booleans have a small number of methods that you generally won’t find yourself using as they (mostly) have equivalent operators that are more “natural” to read and write.

\n\n

The and(right) method performs a logical ‘and’

\n\n

The and method

\n\n

def truth = true\ndef lies = false\nassert truth.and(lies) == false\n

\n\n\n\n

The conditional And operator (&&) is equivalent to the and method and the assertion above could also be written as assert truth && lies == false

\n\n

The or(right) method performs a logical ‘or’

\n\n

The or method

\n\n

def truth = true\ndef lies = false\nassert truth.or(lies) == true\n

\n\n\n\n

The conditional Or operator (||) is equivalent to the or method and the assertion above could also be written as assert truth || lies == true

\n\n

\n16. Numbers

\n\n\n\n

There are two main types of numbers you’re likely to need:

\n\n

Integers (whole numbers)
Decimals

\n\n

Groovy also gives us scientific notation and other number systems and we’ll take a look at how you use them.

\n\n

Integers

Integers are whole numbers and can be negative or positive:

\n\n

Using Integers

\n\n

def age = 27\ndef coldDay = -8\n

\n\n\n\n

Groovy will also handle very large numbers:

\n\n

Large numbers

\n\n

// 1 astronomical unit (au)\ndef distanceEarthToSun = 149597870700\ndef distanceNeptuneToSun = distanceEarthToSun * 30\n

\n\n\n\n

Decimals

Decimal numbers provide a fraction and can be negative or positive:

\n\n

Using decimals

\n\n

def pi = 3.14159\n\n// Measured in celsius\ndef absoluteZero = -273.15\n

\n\n\n\n

Scientific notation

Base-10 (decimal) scientific notation ( $\"a$ ) can also be used by placing an e or E before the exponent:

\n\n

Using SN

\n\n

def atomicMass = 1.67e-27\n

\n\n\n\n

The next example sets the au variable to $\"1.49597870700$ and then checks to make sure I haven’t messed up the exponent:

\n\n

Just a check

\n\n

def au = 1.49597870700e11\nassert au == 149597870700\n

\n\n\n\n

In the previous two examples you can see a signed (positive or negative) integer as the exponent:

\n\n

\ne-27 is negatively signed
\ne11 can also be written as e+11 and is positively signed

\n\n\n\n

Number Systems

\n\n

Most of the time we deal with decimal (base-10) numbers but there are other number systems out there. If we want to use the number 15 in base-10 we just type 15 but we can also use:

\n\n

Binary (base-2) by prefixing 0b\n
- That’s a zero followed by lower-case “b”
\n
Octal (base-8) by prefixing 0\n
- That’s just zero
\n
Hexadecimal (base-16) by prefixing 0x\n
- That’s a zero followed by lower-case “x”
\n

\n\n

The code below illustrates the many faces of the number 15 (base-10):

\n\n

Different number systems

\n\n

println 0b1111    //Binary\nprintln 15         //Decimal\nprintln 017       //Octal\nprintln 0xf       //Hexadecimal\n

\n\n\n\n

To help you deal with long numbers Groovy lets you use underscores (_) to visually break up the number without changing its value:

\n\n

Formatting large numbers

\n\n

assert 1_000_000 == 1000000\nassert 0b0001_0110_1101 == 365\n

\n\n\n\n

Let’s close with a joke:

\n\n

Lolz

\n\n

def value = 0b10\n\nprintln \"There are only $value types of people in the world - those who know bin\\\nary and those who don't\"\n

\n\n\n\n

Useful Methods and Properties

\n\n

Groovy (Java) numbers trace their lineage (inherit) back to java.lang.Number. The Number class provides methods to covert between different types of numbers (integer, decimal etc) - we’ll cover this in the chapter on Data Types.

\n\n

Most numerical classes (e.g. Integer) provide the handy max and min methods that let you compare two numbers of the same numerical type:

\n\n

max and min

\n\n

assert Integer.max(10, 2) == 10\nassert Integer.min(10, 2) == 2\n

\n\n\n\n

\n17. Strings

\n\n\n\n

There are two main ways in which you can declare a string in Groovy: single or double quotes

\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n

The String section
Method	Usage
Single quotes (`'...'`)	These are fixed strings and tell Groovy that the string is as we’ve written it (e.g. `def pet = 'dog'`).
Double quotes (`\"...\"`)	These are called GStrings and let us interpolate (insert) variables into our string. (e.g. `def petDescription = \"My pet is a $pet\"`)
Three single quotes (`'''...'''`)	A multi-line fixed string
Three double quotes (`\"\"\"...\"\"\"`)	A multi-line GString

\n\n

Here’s a quick example of a fixed string and a GString in action:

\n\n

Fixed strings and GStrings

\n\n

def pet = 'dog'\ndef petDescription = \"My pet is a $pet\"\nprintln petDescription\n

\n\n\n\n

Escape sequences

\n\n

Strings can contain escape sequences, allowing you to use non-printable characters in your text.

\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n

Escape sequences
Sequence	Character
\\n	line feed
\\f	form feed
\\r	carriage return
\\t	horizontal tab
\\’	single quote
\\”	double quote
\\\\	backslash

\n\n

The line feed (\\n) is often used to move to a new line:

\n\n

The line feed

\n\n

print 'Hi \\n there\\n'\n

\n\n\n\n

You’ll notice the use of print in the example above - the final \\n performs the same as println and moves to a new line.

\n\n

The form feed (\\f) and carriage return (\\r) aren’t often used. Form feed indicates a new page and carriage return goes back to the start of the line.

\n\n

The horizontal tab (\\t) is essentially the same as the tab key on your keyboard. It’s useful for formatting things like tables of information:

\n\n

Sequences

\n\n

println 'name\\tage\\tcolour'\nprintln 'Sam\\t12\\tblue'\nprintln 'Alice\\t8\\tgreen'\n

\n\n\n\n

If you wish to use a quote within your string that matches the quote type you’re using to surround your string then you need to escape the internal quote using the \\ character. In the code below you can see the quotes being escaped (\\' and \\\"):

\n\n

Escape, escape!

\n\n

println 'That\\'s mine'\nprintln \"I said \\\"NO!\\\"\"\n

\n\n\n\n

As the backslash (\\) is used to escape characters, it needs an escape of its own. In order to use a backslash in a string you need to double it up (\\\\) as in the example below:

\n\n

Backslashing

\n\n

println 'c:\\\\documents\\\\report.doc'\n

\n\n\n\n

GStrings

In order to have Groovy interpolate the value of a variable we use the $ symbol in front of the variable name - as you can see with $pet below:

\n\n

GStrings

\n\n

def pet = 'dog'\nprintln \"I own a $pet\"\n

\n\n\n\n

This can be handy if you have a number of variables that you’d like to use in a string:

\n\n

Interpolating strings

\n\n

def name = 'Sally'\ndef hobby = 'surfing'\nprintln \"Did you know that $name likes $hobby?\"\n

\n\n\n\n\n\n

GStrings also let you interpolate more complicated expressions into a string by using ${...}. In the following example we perform a calculation within the GString:

\n\n

Operation in a GString

\n\n

println \"10 to the power of 6 is ${10**6}\"\n

\n\n\n\n

We can also access information about a variable in the same manner:

\n\n

Operation in a GString

\n\n

def word = 'Supercalifragilisticexpialidocious'\nprintln \"$word has ${word.length()} letters\"\n

\n\n\n\n\n\n

Multiline Strings

\n\n

The examples given so far use short strings but longer strings would be cumbersome to type using \\n all over the place. Instead, Groovy provides multiline strings - the code below declares a multiline fixed string:

\n\n

A Multiline string

\n\n

def poem = '''But the man from Snowy River let the pony have his head,\nAnd he swung his stockwhip round and gave a cheer,\nAnd he raced him down the mountain like a torrent down its bed,\nWhile the others stood and watched in very fear.'''\n\nprint poem\n

\n\n\n\n

If you run the code above you’ll see that new lines are used at the correct points in the display but the first line is not quite right. You can modify this slightly and place a backslash (\\) at the start of the string - using statement continuation for readability:

\n\n

Fixing the first line

\n\n

def poem = '''\\\nBut the man from Snowy River let the pony have his head,\nAnd he swung his stockwhip round and gave a cheer,\nAnd he raced him down the mountain like a torrent down its bed,\nWhile the others stood and watched in very fear.'''\n\nprint poem\n

\n\n\n\n\n\n

GStrings can also be defined using the multiline format:

\n\n

A multiline GString

\n\n

def animal = 'velociraptor'\n\nprintln \"\"\"But the man from Snowy River let the ${animal} have his head,\nAnd he swung his stockwhip round and gave a cheer,\nAnd he raced him down the mountain like a torrent down its bed,\nWhile the others stood and watched in very fear.\"\"\"\n

\n\n\n\n

Building Strings

\n\n

Working with basic strings is fine but if you need to build up a large piece of text throughout a program they can become very inefficient. We’ll look into this in the tutorial on Operators.

\n\n

Useful Methods

\n\n

Strings (text) are important aspects to human-based systems so most programming languages provide a number of methods for modifying, search, slicing and dicing strings. Groovy provides a number of helpful methods you can use with strings and we’ll look at just a few of them here:

\n\n

\nlength() : returns the number of characters in a string
\nreverse(): returns the mirrored version of the string
\ntoUpperCase() and toLowerCase(): returns the string with all of the characters converted to upper or lower case.

\n\n

Some String methods

\n\n

def str = 'Hello, World'\nprintln str.length()\nprintln str.reverse()\nprintln str.toUpperCase()\nprintln str.toLowerCase()\n

\n\n\n\n

The trim() method returns the string with any leading and trailing whitespace removed:

\n\n

Trimming a String

\n\n

def str = '  Hello, World  '\nprintln str.trim()\n

\n\n\n\n

The substring method returns a subsection of a string and can be used in two possible ways:

\n\n

Provide a start index (e.g. substring(7)) to get the subsection that includes that index (i.e. the 7th character in the string) through to the end of the string
Provide a start and an end index (e.g. substring(7, 9)) to get the subsection that includes that start index through to the end index of the string

\n\n

Substrings

\n\n

def str = 'Hello, World'\nprintln str.substring(7)\nprintln str.substring(7,9)\n

\n\n\n\n

A number of methods are provided to help you with basic searching:

\n\n

The indexOf and lastIndexOf methods return the index (location) of the specified character in the string
\ncontains, startsWith, and endsWith return true or false if the supplied parameter is located within the string

\n\n

Basic searching

\n\n

def str = 'Hello, World'\n\n//These methods return the index of the requested character\nprintln str.indexOf(',')\nprintln str.lastIndexOf('o')\n\n//These methods check if the string contains another string\nprintln str.contains('World')\nprintln str.startsWith('He')\nprintln str.endsWith('rld')\n

\n\n\n\n

The replace method lets us provide a string that we want to change to a new value:

\n\n

Replacing text

\n\n

def str = 'Hello, World'\n\nprintln str.replace('World', 'Fred')\n

\n\n\n\n\n\n

Lastly, and a favourite of mine, is toURL(). This converts a String to a URL object which, in Groovy has a great text\nproperty that lets us load the text of our favourite web page:

\n\n

println 'http://www.example.com/'.toURL().text\n

\n\n\n\n

\n18. Collections

\n\n\n\n

Collections group a number of values in a single container. The Java Collections Framework provides a really extensible and unified approach to handling collections. Groovy makes these even easier to use and focusses on two key collection types:

\n\n

Lists: provide a container for several values
Maps: use keys as a method for indexing a set of values

\n\n

Lists

\n\n

List variables contain several items and are declared using square brackets ([...]).

\n\n

The example below declares a variable (temperatures) as an empty list:

\n\n

Declaring an empty list

\n\n

def temperatures = []\n

\n\n\n\n

The next examples declares the temperatures list with some initial values:

\n\n

Declaring a list with values

\n\n

def temperatures = [10, 5, 8, 3, 6]\n

\n\n\n\n

In the temperatures example the list contains just numbers but Groovy lists can contain a mix of data types:

\n\n

Lists can contain mixed types

\n\n

def mixed = [1, true, 'rabbit', 3.14]\nprintln mixed[2]\nprintln mixed[-3]\nprintln mixed.get(3)\n

\n\n\n\n

The square brackets [] are used to create a list but are also used to refer to indexes in the list (e.g. mixed[2]) - this is often referred to as subscript notation. In the example above you’ll notice I’ve printed out mixed[2] - the list item with index (subscript) 2. Somewhat confusingly this causes rabbit to be displayed. This is because lists are zero-based and the first item is at index 0, not index 1. Where we use mixed[2] we’re asking for the third item in the list.

\n\n

It may surprise some programmers that println mixed[-3] is valid - it’s a very handy approach to accessing list items from the end of the list. Item -1 is the last in the list so mixed[-3] will be the value true.

\n\n

The get() method can also be used to access a list element by its index - e.g. mixed.get(3) gives us 3.14.

\n\n

I can provide multiple indexes in the subscript notation and grab the specified elements from the list. In the example below I grab elements 0 and 2 (temperatures[0, 2]) and then elements 1, 3 and 4 (temperatures[1, 3, 4]):

\n\n

Using indexes with lists

\n\n

def temperatures = [10, 5, 8, 3, 6]\nassert temperatures[0, 2] == [10, 8]\nassert temperatures[1, 3, 4] == [5, 3, 6]\n

\n\n\n\n

Ranges can also be used in the subscript notation and, as demonstrated in the example below, return a list containing the items whose indexes are included in the range:

\n\n

Using ranges with lists

\n\n

def temperatures = [10, 5, 8, 3, 6]\nassert temperatures[1..3] == [5, 8, 3]\n

\n\n\n\n

We can also use a mix of individual indexes and ranges as we see fit:

\n\n

Indexes and ranges with lists

\n\n

def temperatures = [10, 5, 8, 3, 6]\nassert temperatures[0..1, 3] == [10, 5, 3]\nassert temperatures[0..1, 1..3] == [10, 5, 5, 8, 3]\nassert temperatures[0..1, 1..3, 4] == [10, 5, 5, 8, 3, 6]\n

\n\n\n\n

What? Let’s take a look:

\n\n

\ntemperatures[0..1, 3] returns a list containing the elements of temperatures with the indexes 0, 1 and 3
\ntemperatures[0..1, 1..3] returns a list using two ranges to select the indexes. As index item 1 is requested twice, the returned list features the item (5) twice.
\ntemperatures[0..1, 1..3, 4] does the same as the previous statement but adds in the item at index 4\n

\n\n

Adding elements

\n\n

To add an element to a list we use the add() method or the << operator:

\n\n

Adding elements

\n\n

def mixed = [1, true, 'rabbit', 3.14]\nmixed << 'biscuit'\nmixed.add(101)\nprintln mixed\n

\n\n\n\n

Sets

Sets are much like lists but each element in a set is unique:

\n\n

Declaring a Set

\n\n

def names = ['sally', 'bob', 'sally', 'jane'] as Set\nprintln names\n

\n\n\n\n

If you try the code above you’ll get [sally, bob, jane] - the set just ignores the repeated element.

\n\n\n\n

Useful List Methods

\n\n

The size() method returns the number of elements in the list:

\n\n

List size

\n\n

def periodic = ['hydrogen', 'helium', 'lithium']\nprintln periodic.size()\n

\n\n\n\n

The first() and last() methods return the first and last elements in a list. The head() method is synonymous with first().

\n\n

First and last methods

\n\n

def periodic = ['hydrogen', 'helium', 'lithium']\nprintln periodic.first()\nprintln periodic.head()\nprintln periodic.last()\n

\n\n\n\n

The tail() method returns the list minus the first (head) element and the init() method returns the list minus the last element:

\n\n

Tail method

\n\n

def periodic = ['hydrogen', 'helium', 'lithium']\nassert periodic.tail() == ['helium', 'lithium']\nassert periodic.init() == ['hydrogen', 'helium']\n

\n\n\n\n

The contains() method returns true if the requested element is contained in the list:

\n\n

Contains method

\n\n

def periodic = ['hydrogen', 'helium', 'lithium']\nassert periodic.contains('helium') == true\n

\n\n\n\n

The reverse() method returns the mirror of the list:

\n\n

Reverse method

\n\n

def periodic = ['hydrogen', 'helium', 'lithium']\nprintln periodic.reverse()\n

\n\n\n\n

The sort() will sort the elements in a “natural” order. Basically, this relies on the list elements being comparable in some manner. The sort method is best used when the list contents are all of the same type (e.g. strings or numbers):

\n\n

Sort method

\n\n

def periodic = ['hydrogen', 'helium', 'lithium']\nperiodic.sort()\n

\n\n\n\n

The asImmutable() method is a handy way to set the list contents in stone - “Immutable” essentially means “unchanging”.

\n\n

Don’t go changing

\n\n

def friends = ['fred', 'sally', 'akbar'].asImmutable()\n\n//This next line will cause an exception:\nfriends << 'jake'\n

\n\n\n\n

Maps

\n\n

Maps allow us to build up a type of look-up table using keys and values. Other languages call these dictionaries or associated arrays.

\n\n

An empty map is declared using [:] and the example below shows this in use when declaring the periodic variable.

\n\n

Declaring an empty map

\n\n

def periodic = [:]\n

\n\n\n\n

Each key in a map is unique and points to a value in the map. In the example below we see the start of a basic periodic table by declaring a variable (periodic) with a set of key-value pairs (key: value) each separated by a comma (,) and held within square brackets ([...]):

\n\n

Declaring a map with elements

\n\n

def periodic = ['h': 'hydrogen',\n\t\t'he': 'helium',\n\t\t'li': 'lithium']\n\nprintln periodic['li']\nprintln periodic.li\nprintln periodic.get('li')\n

\n\n\n\n

You should also note that we can access map items using:

\n\n

The key in square brackets ([])\n
1. Much as we did with lists: println periodic['li'].
2. This is often referred to as subscript notation.
\n
We can also use the period (.) followed by the key:\n
1. As in println periodic.li.
2. This is often referred to as dot-point notation\n
\n
Lastly, the get() method is passed a key and returns the associated value

\n\n\n\n

The keys in a map can be names provided they adhere to the same rules we follow for variable names. That means that the keys in periodic don’t have to be written as strings:

\n\n

Keys as names

\n\n

def periodic = [h: 'hydrogen',\n        he: 'helium',\n        li: 'lithium']\n

\n\n\n\n

Adding elements

To add an element to a map we can use the square bracket, dot-point notation, << operator, or put() method to add on a new key/value pair:

\n\n

Adding elements

\n\n

def periodic = ['h': 'hydrogen',\n        'he': 'helium',\n        'li': 'lithium']\n\nperiodic['be'] = 'Beryllium'\nperiodic.b = 'Boron'\nperiodic << ['c': 'Carbon']\nperiodic.put('n', 'Nitrogen')\n\nprintln periodic\n

\n\n\n\n

Keys

Map keys don’t have to be strings - they can be a mix of strings, numbers or other objects. Let’s look at an example then go through the various bits of code:

\n\n

Different types of keys

\n\n

class Chicken {\n    def name\n\n    String toString() {\n        return \"I am $name\".toString()\n    }\n}\n\ndef cluckers = new Chicken(name: 'Cluckers')\n\ndef mixedMap = [\n        12        : 'Eggs in a carton',\n        'chicken' : 'Egg producer',\n        (cluckers): 'Head chicken'\n]\n\nprintln mixedMap[12]\nprintln mixedMap.get(12)\n\nprintln mixedMap.chicken\nprintln mixedMap['chicken']\nprintln mixedMap.get('chicken')\n\nprintln mixedMap[(cluckers)]\nprintln mixedMap.get(cluckers)\n\nprintln mixedMap\n

\n\n\n\n

In the example above:

\n\n

I create a new class (Chicken)\n
1. … and store a new instance of Chicken in the variable cluckers\n
\n
I then create a map variable called mixedMap with different types of keys:\n
1. \n12 is a number
2. \n'chicken' is a string
3. \n(cluckers) indicates that the key is a variable value
\n
I use the square-bracket notation and get method to access the value aligned to the key 12\n
1. \nmixedMap.12 won’t work
\n
I use the square-bracket, dot-point and get method to access the value aligned to the key 'chicken'\n
I use the square-bracket notation and get method to access the value aligned to the key (cluckers)\n
1. mixedMap.cluckers
\n
\nprintln mixedMap is called to display the map contents

\n\n\n\n

For those interested in such things, the (cluckers) key isn’t affected if I change the value of cluckers later on. If you append the code below to the chicken example you’ll see that mixedMap.get(cluckers) will now return null as the match fails. You’ll also notice that println mixedMap is the same output you get before changing cluckers:

\n\n

Changing objects used as keys

\n\n

cluckers = new Chicken(name: 'Bill')\nprintln mixedMap.get(cluckers)\nprintln mixedMap\n

\n\n\n\n

Useful Map Methods

\n\n

As with lists, the size() methods returns the number of elements in a map.

\n\n

The get method can be used to get the value for the requested key. A second optional parameter can be provided and is returned if the map does not contain the requested key:

\n\n

Get method

\n\n

def periodic = ['h': 'hydrogen',\n        'he': 'helium',\n        'li': 'lithium']\n\nprintln periodic.get('he')\nprintln periodic.get('he', 'Unknown element')\nprintln periodic.get('x', 'Unknown element')\n

\n\n\n\n

The keySet() method returns a list containing all of the keys in a map and values() returns a list of the values in a map:

\n\n

keySet method

\n\n

def periodic = ['h': 'hydrogen',\n        'he': 'helium',\n        'li': 'lithium']\n\nprintln periodic.keySet()\nprintln periodic.values()\n

\n\n\n\n

The containsKey() and containsValue() methods are useful for checking on map contents:

\n\n

Checking for keys and values

\n\n

def periodic = ['h': 'hydrogen',\n        'he': 'helium',\n        'li': 'lithium']\n\nprintln periodic.containsKey('li')\nprintln periodic.containsValue('carbon')\n

\n\n\n\n

The asImmutable() method works for maps in the same manner as it does for lists:

\n\n

Don’t go changing

\n\n

def periodic = ['h': 'hydrogen',\n        'he': 'helium',\n        'li': 'lithium'].asImmutable()\n\n//This will cause an exception:\nperiodic.x = 'new element'\n

\n\n\n\n

\n19. Arrays

\n\n\n\n

For my money, the collections we’ve just looked at (lists, sets, maps) are more versatile than arrays and collections are my preferred approach. However, there’s a lot of code out there using arrays so let’s take a quick look.

\n\n

Arrays contain a fixed number of elements of a specified data type. Let’s look at an example of array declaration and usage:

\n\n

Declaring an array

\n\n

Number[] point = new Number[2]\n\npoint[0] = 27\npoint[1] = -153\n\nassert point.length == 2\n

\n\n\n\n

So let’s dissect that chunk of code:

\n\n

The point variable is declared using Number[] point = new Number[2]\n
- \nNumber[] indicates that we want an array of Numbers
- \n[] indicates that the variable is an array, not just a single Number value
- \nnew Number[2] sets point to be an empty array that can contain two (2) elements of the Number class (or a subtype thereof).
- Don’t use def as we’re specifying the data type
\n
Arrays are zero-based, meaning that the first element is at index 0\n
- \npoint[0] is the first element
- \npoint[1] is the second
\n
\npoint.length returns the number of elements in the array\n
- Note that the range of indexes for an array is 0..(point.length - 1)\n
- \npoint.size() would also work and provides the same result as point.length\n
\n

\n\n

If I’d tried something like point[2] = 99 I would get a java.lang.ArrayIndexOutOfBoundsException as the array can only hold 2 elements.

\n\n

It’s important to note that the size of an array is fixed at declaration. If you decide that you need to expand the array then you’ll slap your forehead and ask “Why didn’t I use collections?”. If you dig your heels in and stay with arrays you might check out the java.lang.System.arraycopy method and learn the gentle art of copying and resizing arrays. Then, you’ll start using collections.

\n\n

We can be more direct in creating the array and provide the values up-front. In the example below I create an array that can hold two elements and I load the values into the array:

\n\n

Setting elements at creation

\n\n

Number[] point = [27, -153]\n

\n\n\n\n

So, why did I pick Number? Well, I want an array of numerical values but perhaps wasn’t sure which type of numbers. Provided the values I put into the array are subtypes of Number, all will be well. That means the following will work fine and nothing will be truncated:

\n\n

Number[] point = [27.9, -153]\n

\n\n\n\n

If I really wanted to be specific about the type of number I could have declared point as an array of Integer values:

\n\n

Integer[] point = [27, -153]\n

\n\n\n\n

Arrays can also be declared to be of a primitive type such as int¹:

\n\n

int[] point = [27, -153]\n

\n\n\n\n

Going further with subtypes etc, arrays can be of any type and the Object class provides a flexible type when your array needs to hold a mixture of values (e.g. numbers, strings, various types):

\n\n

A mixed bag array

\n\n

Object[] bag = new Object[4]\nbag[0] = true\nbag[1] = 'Rabbit'\nbag[2] = 3.14\nbag[3] = null\n

\n\n\n\n

Without wanting to be repetitive, the example above would probably be easier to work with if we used a collection such as a list.

\n\n

Manipulating arrays

\n\n

We’ve seen the size() method and length property - both indicating how many elements the array can hold.

\n\n

Sorting an array is easy with the sort() method:

\n\n

Sorting an array

\n\n

Number[] nums = [99, 10.2, -7, 99.1]\nnums.sort()\nprintln nums\n

\n\n\n\n\n\n

Of course sort() works well if the element types have a meaningful sorting order but try out the following code and you’ll see that the sort() perhaps isn’t overly useful on mixed values:

\n\n

Can this be sorted?

\n\n

Object[] bag = new Object[4]\n\nbag[0] = true\nbag[1] = 'Rabbit'\nbag[2] = 3.14\nbag[3] = null\n\nprintln bag.sort()\n

\n\n\n\n

Use the Arrays.asList() static method to get a copy of an array into a list (collection):

\n\n

Arrays to lists with asList

\n\n

Number[] nums = [99, 10.2, -7, 99.1]\ndef list = Arrays.asList(nums)\n

\n\n\n\n

Alternatively, you can use the as operator to cast the array to a List.

\n\n

Arrays to lists with as

\n\n

Number[] nums = [99, 10.2, -7, 99.1]\ndef list = nums as List\n

\n\n\n\n

Check out the java.util.Arrays class for more array methods.

\n\n

Primitive types are discussed in the Data Types chapter.↩\n

\n\n\n

\n20. Ranges

\n\n\n\n

Ranges define a starting point and an end point. Let’s look at a well-known type of range:

\n\n

Declaring a range

\n\n

def countdown = 10..0\n\nprintln countdown.getFrom()\nprintln countdown.getTo()\n

\n\n\n\n

The countdown range starts at 10 and goes down to 0. The notation should be easy to decipher: <start>..<end>.

\n\n

Printing out a range variable will display that a range is rather like a list of values - in the case of countdown they’re numbers:

\n\n

Ready for launch

\n\n

def countdown = 10..0\nprintln countdown\n

\n\n\n\n

Whilst my examples so far all go down, you can just as easily have a range that goes up:

\n\n

Going up

\n\n

def floors = 1..10\nprintln floors\n

\n\n\n\n

You can also use decimals but note that it is only the integer (whole-number) component that is stepped through:

\n\n

Decimals in ranges

\n\n

def countdown = 10.1..1.1\nprintln countdown\n

\n\n\n\n

Half-Open Ranges

\n\n

Ranges aren’t just limited to inclusive ranges such as 1..10. You can also declare a half-open range using ..< - that’s two periods and a less-than. This denotes that the range ends prior to the number to the right. In the example below I setup a grading criteria that avoids an overlap between the grades:

\n\n

Half-open range declarations

\n\n

def gradeA = 90..100\ndef gradeB = 80..<90\ndef gradeC = 65..<80\ndef gradeD = 50..<65\ndef gradeF = 0..<50\n

\n\n\n\n

I could tweak the above code if I want to get fancy:

\n\n

A fancier approach

\n\n

def gradeA = 90..100\ndef gradeB = 80..<gradeA.getFrom()\ndef gradeC = 65..<gradeB.getFrom()\ndef gradeD = 50..<gradeC.getFrom()\ndef gradeF = 0..<gradeD.getFrom()\n

\n\n\n\n

Ranges of Objects

\n\n

Ranges are primarily used with numbers but they can be of any object type that can be iterated through. This basically means that Groovy needs to know what object comes next in the range - these objects provide a next and previous method to determine this sequence. Over time you’ll discover various options for use in ranges but numbers really are the main type.

\n\n

Apart from numbers, individual characters (letters) can be used in ranges. In the example below I create a range of lower-case letters:

\n\n

A range of characters

\n\n

def alphabet = 'a'..'z'\nprintln alphabet\n

\n\n\n\n

Ranges and Enums

\n\n\n\n

Ranges can be handy when dealing with enums as they give us the ability to set a subset of enum values. In the example below I create a handy helpdesk tool:

\n\n

Setup an enum listing the possible ticket priorities
Create a new class to describe helpdesk tickets
Setup a helpdeskQueue containing a list of tickets
Set the focus variable as a range of Priority values
Go through the list of tickets and pick up any that are set to the priority I care about.

\n\n

Using a helpdesk ticket enum

\n\n

enum Priority {\n    LOW,MEDIUM,HIGH,URGENT\n}\n\nclass Ticket {\n    def priority\n    def title\n}\n\ndef helpdeskQueue = [\n    new Ticket(priority: Priority.HIGH, title: 'My laptop is on fire'),\n    new Ticket(priority: Priority.LOW, title: 'Where is the any key'),\n    new Ticket(priority: Priority.URGENT, title: 'I am the CEO and I need a coff\\\nee'),\n    new Ticket(priority: Priority.MEDIUM, title: 'I forgot my password')\n]\n\ndef focus = Priority.HIGH..Priority.URGENT\n\nfor (ticket in helpdeskQueue) {\n    if (ticket.priority in focus) {\n        println \"You need to see to: ${ticket.title}\"\n    }\n}\n

\n\n\n\n

Try the example above out with various settings for the focus variable:

\n\n

\ndef focus = Priority.MEDIUM..Priority.URGENT\n
- Gives us more tickets to see to :(
\n
\ndef focus = Priority.HIGH..Priority.LOW\n
- Is actually similar to 4..1 and leaves out the tickets marked URGENT\n
\n

\n\n

Ranges and List Indexes

\n\n

You can access a subset of a list using a range subscript. In the example below I use the subscript [1..3] to grab a new list containing elements 1 through 3 of the temperatures list.

\n\n\n\n

Accessing range elements

\n\n

def temperatures = [10, 5, 8, 3, 6]\ndef subTemp = temperatures[1..3]\nassert subTemp == [5, 8, 3]\n

\n\n\n\n

Ranges and Loops

\n\n

Ranges are most often see when we’re using loops - we’ll get to them in a later tutorial but here’s an example of a launch sequence:

\n\n

Looping with ranges

\n\n

def countdown = 10..0\n\nfor (i in countdown) {\n    println \"T minus $i and counting\"\n}\n

\n\n\n\n

In the above example I store the range in the countdown variable in case I need it again later. If I don’t really need to re-use the range I can put the range’s literal value directly into the loop:

\n\n

Looping with ranges refined

\n\n

for (i in 10..1) {\n    println \"T minus $i and counting\"\n}\n

\n\n\n\n

Useful Methods

\n\n

We can use the size() method to find out how many elements are in the range:

\n\n

The size method

\n\n

def dalmations = 1..101\nprintln dalmations.size()\n

\n\n\n\n

As seen earlier, the getFrom() and getTo() methods return the start and final values respectively:

\n\n

The range’s start and end values

\n\n

def intRange = 1..10\nprintln intRange.getFrom()\nprintln intRange.getTo()\n

\n\n\n\n

The isReverse() method returns true if a range iterates downwards (backwards):

\n\n

Checking for reverse

\n\n

def countdown = 10..0\nassert countdown.isReverse() == true\n

\n\n\n\n

You can can use the reverse() method to flip the range:

\n\n

Reversing the range

\n\n

def floors = 1..10\nprintln floors.reverse()\n

\n\n\n\n

In order to check if a value is contained within a range we use the containsWithinBounds method and pass it the value we’re checking on:

\n\n

Checking bounds

\n\n

def countdown = 10..0\nassert countdown.containsWithinBounds(5) == true\n

\n\n\n\n

The step method returns a list based on going through the range via the specified increment (step). In the example below I step through the range one at a time (step(1)) and then two at a time (step(2)):

\n\n

Stepping

\n\n

def countdown = 5..1\nassert countdown.step(1) == [5, 4, 3, 2, 1]\nassert countdown.step(2) == [5, 3, 1]\n

\n\n\n\n

As step returns a list I can use it to populate a list variable that has too many numbers for me to be bothered typing out:

\n\n

def dalmations = (1..101).step(1)\nprintln dalmations\n

\n\n\n\n

As we’re about to see the step method is very effective when used with closures.

\n\n

Ranges and Closures

\n\n

Closures are a method (function) that can be handled in a manner similar to variables. A closure is described within curly brackets {..} and can be passed as method parameters. Closure have a default variable named it and this holds a value passed to the closure by its caller.

\n\n

We’ll look into closures much more thoroughly in a later tutorial but, for now, take in the following examples and refer back to them when you get to know closures a little better.

\n\n

The step method will call a closure for each item in a range. In the example below I step through countdown one number at a time and, for each number, I display a message:

\n\n

Stepping through a range with closures

\n\n

def countdown = 10..1\ncountdown.step(1) {\n    println \"T minus $it and counting\"\n}\n

\n\n\n\n\n\n

I can use the range literal but need to place it within (..):

\n\n

Using the range literal

\n\n

(10..1).step(1) {\n    println \"T minus $it and counting\"\n}\n

\n\n\n\n

You can change the size of each step - in the case below I step down by 2 each time. Run the code and notice that launch never happens!

\n\n

Changing the step

\n\n

(10..1).step(2) {\n    println \"T minus $it and counting\"\n}\n

\n\n\n\n

\n21. Regular Expressions

\n\n\n\n

Regular expressions (RegEx’s) get entire books devoted to them and you’ll find some developers are RegEx ninjas and others (like myself) are RegEx numpties. This chapter will introduce the basics but the Java Tutorial’s Regular Expression trail is a useful reference as is Wikipedia for those seeking RegEx glory. There are also a number of online tools such as RegExr that come in very handy when trying to debug that elusive RegEx pattern.

\n\n

To define the regular expression pattern we use the ~/ / syntax:

\n\n

Declaring a regex

\n\n

def regex = ~/\\n/\n

\n\n\n\n

Once stored as a variable, this regular expression can be used in a variety of ways. The example below sets up three string variables and tests them against the regex pattern by using the matches method - which returns true if the string matches the pattern:

\n\n

Matching against a regex

\n\n

def regex = ~/https?:\\/\\/.*/\n\ndef httpUrl = 'http://www.example.com/'\ndef httpsUrl = 'https://secure.example.com/'\ndef ftpUrl = 'ftp://ftp.example.com/'\n\nassert httpUrl.matches(regex)\nassert httpsUrl.matches(regex)\nassert ! ftpUrl.matches(regex)\n

\n\n\n\n

In the code above, ~/https?:\\/\\/.*/ is the regular expression pattern that’s essentially looking for any string starting with http or https. The s? will match 0 or 1 occurrence of s in the pattern. You’ll notice the odd-looking \\/\\/ - I need to escape the forward slashes in http:// so that Groovy doesn’t confuse them with the slashes used to define the regular expression pattern (~/../).

\n\n

We’ll also look at the special operators for regular expressions in the section on Operators.

\n\n

Underpinning Groovy’s regular expression functionality is the Java class java.util.regex.Pattern. Groovy handles the compiling of the pattern and this helps you focus on the struggle of getting the regular expression correct :)

\n\n

Regular Expression Syntax

\n\n

Regular expressions use a number of syntactic elements to define a pattern of text. We’ll take a brief look at them here.

\n\n

Characters

\n\n

These elements are used to match specific literal characters.

\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n

Literal characters
Element	Matches
`g`	The character `g`\n
`\\\\`	The backslash character
`\\t`	Tab character
`\\n`	Newline character
`\\f`	Formfeed character
`\\r`	Carriage-return character

\n\n

In the example below I take a section of a poem and use the split method to get a list whose elements contain a single line from the poem.

\n\n

Splitting a poem

\n\n

// The Ballad of the Drover by Henry Lawson\ndef poem = '''\\\n Across the stony ridges,\n  Across the rolling plain,\n Young Harry Dale, the drover,\n  Comes riding home again.\n And well his stock-horse bears him,\n  And light of heart is he,\n And stoutly his old pack-horse\n  Is trotting by his knee.'''\n\ndef regex = ~/\\n/\n\ndef lines = regex.split(poem)\n\ndef i = 1\nfor (line in lines) {\n    println \"Line $i: $line\"\n    i++\n}\n

\n\n\n\n

Character Classes

\n\n

Character classes are used to define character sets and sequences.

\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n

Character classes
Element	Matches
`[xyz]`	\n`x`, `y` or `z`\n
`[^xyz]`	Not `x`, `y` or `z`\n
`[a-zA-Z]`	Range of characters (all letters)
`[0-9]`	Range of characters (all numbers)
`[a-zA-Z_0-9]`	Range of characters

\n\n

Predefined Character Classes

\n\n

The predefined character classes save you from having to define the class specifically and are handy for seeking out words and whitespace.

\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n

Predefined character classes
Element	Matches
`.`	Any character
`\\d`	Digits `[0-9]`\n
`\\D`	Non-digits
`\\s`	Whitespace
`\\S`	Not whitespace
`\\w`	Word character `[a-zA-Z_0-9]`\n
`\\W`	Not a word character

\n\n

Boundaries

\n\n

Boundaries, to state the obvious, mark the edge of something - specifically a line or a word.

\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n

Boundaries
Element	Matches
`^`	Start of a line
`$`	End of a line
`\\b`	Word boundary
`\\B`	Non-word boundary

\n\n

Quantifiers

\n\n

These determine how many matches are acceptable. For example s? matches the character s zero or one time - meaning that I expect that character to be an s or, if it’s not, move to the next part of the pattern. s+ means that I really want at least one s at that point.

\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n

Quantifiers
Element	Matches
`?`	Single match
`*`	Zero or more matches
`+`	One or more matches
`{n}?`	Exactly n matches
`{n, }?`	At least n matches
`{n,m}?`	At least n but not more that m matches

\n\n

Useful Methods

\n\n

A number of String methods can accept a regular expression and these are my preferred approach to checking text against regular expressions. Most of them take the pattern as the first parameter.

\n\n

We saw the matches() method at the beginning of the chapter:

\n\n

Matching

\n\n

def regex = ~/https?:\\/\\/.*/\ndef httpUrl = 'http://www.example.com/'\n\nassert httpUrl.matches(regex)\n

\n\n\n\n

The find() method returns the first match against the pattern within the string. In the example below the find() will return the match against the port number in the URL:

\n\n

Finding

\n\n

def regex = ~/:[0-9]+/\ndef httpUrl = 'http://www.example.com:8080/'\n\nprintln httpUrl.find(regex)\n

\n\n\n\n

The findAll() method returns a list of matches for the pattern. In the example below I am returned all words in speech that start with like:

\n\n

findAll

\n\n

def speech = '''This like guy like I know but like don\\'t really like\n was like so mean but likely to be nice when you know him better.'''\n\nprintln speech.findAll(~/\\blike\\w*\\b/)\n

\n\n\n\n

\n
Like, wow!
\n

\n\n

The example below provides a very basic word counter by seeking out the \\b\\w+\\b pattern and displaying the size of the list returned by findAll:

\n\n

A word counter

\n\n

def poem = '''\\\n Across the stony ridges,\n  Across the rolling plain,\n Young Harry Dale, the drover,\n  Comes riding home again.'''\n\ndef regex = ~/\\b\\w+\\b/\n\nprintln poem.findAll(regex).size()\n

\n\n\n\n

The replaceFirst() and replaceAll() methods seek out matches and replace them in a manner that their names implies:

\n\n

Replacing

\n\n

def speech = '''This like guy like I know but like don\\'t really like\n was like so mean but likely to be a nice guy when you know him better.'''\n\nprintln speech.replaceAll(~/\\blike\\b/, 'um')\nprintln speech.replaceFirst(~/\\bguy\\b/, 'marmoset')\n

\n\n\n\n

The splitEachLine() method is very handy when handling structured files such as comma-separated files. You can see in the example below that the first parameter is the pattern that will match commas (~/,/) and the second parameter is a closure that will do something for each line. Within the closure, the it variable is a list with each element being the delimited segment of the text with the line:

\n\n

Splitting

\n\n

def csv = '''\\\nBill,555-1234,cats\nJane,555-7485,dogs\nIndira,555-0021,birds'''\n\ncsv.splitEachLine(~/,/) {\n    println \"Name: ${it[0]}\"\n}\n

\n\n\n\n

Pattern Methods

\n\n

The java.util.regex.Pattern class provides a number of useful methods. I prefer to use the String methods but maybe I’m just lazy.

\n\n

The static matches method is called against Pattern to evaluate a pattern against a piece of text. You’ll note that the first parameter is the pattern but represented as a string so you drop the ~/../ notation:

\n\n

Using Pattern

\n\n

//Note the import\nimport java.util.regex.Pattern\nassert Pattern.matches('https?://.*/', 'http://www.example.com/') == true\n

\n\n\n\n

The matcher() method is called against a regular expression pattern and is passed the text that is to be checked. A Matcher variable is returned and these give you a whole heap of regular expression functionality. In my example I just check for the match by calling matches():

\n\n

Using Matcher

\n\n

def regex = ~/https?:\\/\\/.*/\ndef httpUrl = 'http://www.example.com/'\ndef matcher = regex.matcher(httpUrl)\nassert matcher.matches() == true\n

\n\n\n\n

The split() method uses a pattern as a delimiter and returns the elements of the parameter broken up by the delimiter. In my example below I split the domain up based on the period (.) delimiter:

\n\n

Another split`

\n\n

def regex = ~/\\./\ndef domain = 'www.example.com'\n\nprintln regex.split(domain)\n

\n\n\n\n

That last example is simple but you can use some pretty funky patterns to split up a string.

\n\n

\n22. Data types

\n\n\n\n

Groovy does not preclude the programmer from explicitly declaring a data type, particularly when it would be pertinent to constrain the values being managed. Furthermore, knowledge of data types is very useful for a number of reasons:

\n\n

Use of JVM-compatible libraries may require knowledge of the data types required by method calls.\n
- Important if you want to mine the rich collection of existing Java libraries
\n
Conversion between different data types (such as decimal numbers to whole numbers) can cause truncation and other (perhaps unexpected) results.\n
- Essential knowledge if your program relies on calculations
\n

\n\n

Most of Java’s “core” classes (types) are defined in the java.lang package. Groovy enhances some of these in the GDK to give you extra flexibility.

\n\n

Groovy’s use of types

The table below illustrates Groovy’s selection of a data type based on a literal value:

\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n

Groovy’s use of types
Value	Assigned Type
`true`	java.lang.Boolean
`'a'`	java.lang.String
`\"This is a String\"`	java.lang.String
`\"Hello ${Larry}\"`	org.codehaus.groovy.runtime.GStringImpl
`127`	java.lang.Integer
`32767`	java.lang.Integer
`2147483647`	java.lang.Integer
`9223372036854775807`	java.lang.Long
`92233720368547758070`	java.math.BigInteger
`3.14`	java.math.BigDecimal
`3.4028235E+38`	java.math.BigDecimal
`1.7976931348623157E+308`	java.math.BigDecimal

\n\n

It is important to note that the type is selected at each assignment - a variable that is assigned a string such as \"Hello\" is typed as java.lang.String but changes to java.lang.Integer when later assigned the value 101.

\n\n

Using a specific type

A variable can be declared as being of a specific data type. When using a type, drop the def keyword:

\n\n

Declaring a variable using a specific type

\n\n

Integer myNum = 1\nString myName = \"Fred nurk\"\n

\n\n\n\n

Suffixes can also be used if you want to be really specific about the data type Groovy is to use for a number. When using suffixes you use the def keyword to define the variable: def dozen = 12i

\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n

Type suffixes supported by Groovy
Suffix	Type	Example
\n`I` or `i`\n	Integer	`12i`
\n`L` or `l`\n	Long	`23423l`
\n`F` or `f`\n	Float	`3.1415f`
\n`D` or `d`\n	Double	`3.1415d`
\n`G` or `g`\n	BigInteger	`1_000_000g`
\n`G` or `g`\n	BigDecimal	`3.1415g`

\n\n

You may have noticed that BigInteger and BigDecimal have the same suffix - this isn’t a typo - Groovy works out which one you need simply by determining if the number is a whole number (BigInteger) or a decimal (BigDecimal).

\n\n

If you’re going to use explicit types then you need to know limitations of that type. For example, the following code will fail:

\n\n

assert 3.1415926535f == 3.1415926535d\n

\n\n\n\n

This failure occurs because Float will shorten (narrow) the value to 3.1415927 - not a mistake you’d want to make when measuring optics for your space telescope! You can see which type Groovy will use automatically by running this snippet of code:

\n\n

println 3.1415926535.class.name\n

\n\n\n\n

The `null` Value

Variables that are not assigned a value at declaration are provided a null value by default. This is a special reference that indicates the variable is devoid of a value.

\n\n

Variables can be explicitly assigned null:

\n\n

def id = null\n

\n\n\n\n

Available data types

As Groovy imports the java.lang package as well as the java.math.BigDecimal and java.math.BigInteger classes by default, a range of data types are available for immediate use:

\n\n

\nBoolean: to store a logical value of true or false\n
Numbers (based on java.lang.Number):\n
- Byte
- Short
- Integer
- Long
- Float
- Double
- BigDecimal
- BigInteger
\n
\nCharacter: A single character such as a letter or non-printing character
\nString: A regular Java-esque piece of text
\nGString: A Groovy string that allows for interpolation
\nObject: This is the base class for all other classes
\nClosure: The class that holds closure values

\n\n

The types listed above are often referred to as reference types, indicating that they relate to a class definition. Groovy also provides a set of primitive types that are more closely aligned to the C programming language than an object-oriented language such as Java and Groovy.

\n\n

Primitive types

The table below maps the types defined in java.lang against their equivalent primitive types:

\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n

The primitive types
Type	Primitive type	Value range	Size (bits)
Boolean	`boolean`	\n`true` or `false`\n	-
Byte	`byte`	-128 to 127, inclusive	8
Short	`short`	-32768 to 32767, inclusive	16
Character	`char`	‘\\u0000’ to ‘\\uffff’ inclusive	16
Integer	`int`	-2147483648 to 2147483647, inclusive	32
Long	`long`	-9223372036854775808 to 9223372036854775807, inclusive	64
Float	`float`	32-bit IEEE 754 floating-point numbers	32
Double	`double`	64-bit IEEE 754 floating-point numbers	64

\n\n

You can check those value ranges by using the MIN_VALUE and MAX_VALUE constants available on the various classes representing numbers:

\n\n

Determining value range

\n\n

println Integer.MIN_VALUE\nprintln Integer.MAX_VALUE\nprintln Float.MIN_VALUE\nprintln Float.MAX_VALUE\n

\n\n\n\n

As an object-oriented language Groovy also provides a mechanism for declaring new data types (objects) that extend and encapsulate information to meet a range of requirements. These implicitly extend the java.lag.Object class.

\n\n\n\n

Type Conversions

\n\n

Groovy will convert values assigned to variables into the variable’s declared data type. For example, the code below declares a variable of type “String” and then assigns it 3.14 (a number). The assertion that the variable remains of type “String” will succeed, indicating that 3.14 was converted to a String value by Groovy before being assigned to the myName variable.

\n\n

Checking the type

\n\n

String myName = \"Fred nurk\"\nmyName = 3.14\nassert myName.class == java.lang.String\n

\n\n\n\n

Care must be taken to not rely totally on this automatic conversion. In the example below the assertion will fail as the myPi variable is declared as an Integer and the assignment drops the fractional component of 3.14:

\n\n

def pi = 3.14\nInteger myPi = pi\nassert myPi == pi\n

\n\n\n\n

Casting

\n\n

The as operator can be used to cast (change) a value to another class.

\n\n

Casting

\n\n

def pi = 3.1415926535 as Integer\nassert 3 == pi\n

\n\n\n\n\n\n

This will be discussed further in the Object Operators tutorial.

\n\n

Converting Numbers

\n\n

java.lang.Number provides a number of methods for converting numbers between the various numerical data types:

\n\n

byteValue()
\ndoubleValue()\n
- also toDouble()\n
\n
\nfloatValue()\n
- also toFloat()\n
\n
\nintValue()\n
- also toInteger()\n
\n
\nlongValue()\n
- also toLong()\n
\n
shortValue()
toBigInteger()
toBigDecimal()

\n\n

Here’s a small example of grabbing the whole (integer) component from a number:

\n\n

Getting the integer

\n\n

def pi = 3.1415926535\nassert 3 == pi.intValue()\nassert 3 == pi.toInteger()\n

\n\n\n\n

\nIII Operators

\n\n

\n23. Introduction

\n\n

Groovy supports a range of operators - those you know from primary school (e.g. + and =), through to more specialised operators.

\n\n

Operators are used with values and variables and the context in which they’re used will vary the resulting output. This introduction lists the range of operators available to you and the following chapters describe each in more detail.

\n\n

Arithmetic and Conditional Operators

\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n

Arithmetic and Conditional Operators
Operator(s)	Type
`=`	Simple Assignment Operator
`!`	Logical Complement Operator
\n`==` `!=`\n	Equality Operators
\n`+` `-` `` `/` `%` `*`\n	Arithmetic Operators
\n`>` `<` `<=` `>=`\n	Relational Operators
\n`++` `--`\n	Increment and Decrement Operators
\n`&&` `\|\|` `?:`\n	Conditional Operators
\n`<<` `>>` `>>>` `~` `&` `\|` `^`\n	Bitwise Operators
\n`+=` `-=` `*=` `/=` `&=` `\|=` `^=` `%=` `<<=` `>>=` `>>>=`\n	The Compound Assignment Operators

\n\n

String Operators

\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n

String Operators
Operator(s)	Type
\n`+`, `<<`\n	Concatenate Operator
\n`<<=` `+=`\n	Append Operator
`-`	Remove Operator
`-=`	Remove In-place Operator
`*`	Repeat Operator
`*=`	Repeat In-place Operator
\n`++` `--`\n	Increment and Decrement Operators

\n\n

Regular Expression Operators

\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n

Regular Expression Operators
Operator(s)	Type
`=~`	Find
`==~`	Match

\n\n

Collection Operators

\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n

Collection Operators
Operator(s)	Type
`in`	Membership Operator
`*`	Spread Operator
`*.`	Spread-Dot Operator
`..`	Range Operator
`[]`	Subscript Operator

\n\n

Object Operators

\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n

Object Operators
Operator(s)	Type
`?.`	Safe Navigation Operator
`.@`	Field Operator
`.&`	Method Reference
`as`	Casting Operator
`is`	Identity Operator
\n`instanceof`, `in`\n	Type Comparison

\n\n

\n24. Operator Overloading

\n\n

Groovy supports something called “operator overloading” and it’s possible for classes to determine how they want operators to behave. Throughout this tutorial I’ll provide some examples of overloading but before we go too far, let’s take a look at what “operator overloading” actually means.

\n\n

The C++ language provides a mechanism for programmers to customise how operators such as + (plus) and - (minus) work. This functionality isn’t provided in Java but is available to Groovy programmers. Essentially, a class can include certain methods that replace (overload) the default implementation - as such methods are tied to specific operators.

\n\n

Consider the + operator, as seen in many great additions. You can use the operator in a statement such as 10 + 2 but you can also use the plus method instead: 10.plus(2). I’d argue (strongly) that using the plus method in your code will be far less readable. However, you should be able to see that using the + operator actually results in the plus method being called.

\n\n

This means that you can use operator overloading for evil - say, by creating a numerical class that ignores all mathematical sense. Aside from developer practical jokes you’ll probably only use operator overloading every now and then. Where it does become extremely useful is in the core Groovy classes and the Groovy extensions to the JDK.

\n\n

In the coming chapters you’ll see a range of operator usage that isn’t available to the Java developer but made available through Groovy’s extensions to the JDK and through the GAPI.

\n\n

To highlight all of this, operator overloading can be used in classes via the methods associated in the following table:

\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n

Methods for overloading operators
Method	Operator
plus	`+`
minus	`-`
div	`/`
mod	`%`
multiply	`*`
power	`**`
equals	`==`
compareTo	\n`<=>`, `>`, `<`\n
rightShift	`>>`
leftShift	`<<`
next	`++`
previous	`--`

\n\n\n\n

Throughout the tutorials on operators I’ll provide information as to how certain functionality is obtained through operator overloading. Feel free to glaze past these sections - they’re mainly there to explain why/how stuff is happening.

\n\n

\n25. Numeric Operators

\n\n\n\n

The following chapters will describe each of the numerical operators in further detail. In this tutorial I just lay the list of operators out for you to quickly see and then describe operator precedence - the order in which the operators are evaluated.

\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n

Groovy’s numerical operators
Operator(s)	Type
`=`	Simple Assignment Operator
`!`	Logical Complement Operator
\n`==` `!=`\n	Equality Operators
\n`+` `-` `` `/` `%`, `*`\n	Arithmetic Operators
\n`>` `<` `<=` `>=`\n	Relational Operators
\n`++` `--`\n	Increment and Decrement Operators
\n`&&` `\|\|` `?:`\n	Conditional Operators
\n`<<` `>>` `>>>` `~` `&` `\|` `^`\n	Bitwise Operators
\n`+=` `-=` `*=` `/=` `&=` `\|=` `^=` `%=` `<<=` `>>=` `>>>=`\n	The Compound Assignment Operators

\n\n

Operator Precedence

Operator precedence describes the order in which operators are evaluated. For example, most people know that the multiplication operator is evaluated before the addition, resulting in the following code displaying 20 (and not 60):

\n\n

println 10 + 2 * 5\n

\n\n\n\n

Parentheses can be used to denote the need for an operator to be evaluated first, allowing the following code to give us 60:

\n\n

def result = (10 + 2) * 5\nprintln result\n

\n\n\n\n\n\n

Operators with the same (equal) precedence (e.g. + and -) are evaluated depending on their associativity. There are three types of associativity:

\n\n

Left-associative: where the operators are grouped left to right
Associative: where operators are grouped arbitrarily\n
- Not seen in Groovy
\n
Right-associative: where the operators are grouped right to left

\n\n

For example, the additive operators (+ and -) are left associative, meaning that they are evaluated left to right. The expression 6 + 2 - 4 is evaluated as the result of 6 + 2 minus 4.

\n\n\n\n

The simple assignment operator (=) is right associative, resulting in the following code displaying a result of 2:

\n\n

Right associativity in assignments

\n\n

def a = 10\ndef b = 5\ndef c = 2\n\na = b = c\n\nprintln a\n

\n\n\n\n\n\n

Order of Precedence

\n\n

The order of precedence (highest to lowest) for the arithmetic operators is as follows:

\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n

Numeric operator precedence
Operator		Example
Postfix increment and decrement		\n`n++`, `n--`\n
Unary operators
	Positive and negative	`-10`
	Prefix increment and decrement	\n`++2`, `--1`\n
	Logical complement	`!true`
	Bitwise complement	`~0x64`
Power		`10**2`
Multiplicative		\n`10 * 2`, `6 / 3`\n
Additive		\n`5 + 5`, `10 - 2`\n
Shift		`>>`
Relational		`10 > 4`
Equality		`1 == 1`
Bitwise AND		`&`
Bitwise XOR		`^`
Bitwise OR		`\|`
Logical AND		`true && false`
Logical OR		`true \|\| false`
Ternary		`10 > 2? true: false`
Assignment (simple and compound)		\n`10 += 2`, `var = 9`\n

\n\n

\n26. Simple Assignment Operator

\n\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n\n

Simple assignment operator
Operator
`=`

\n\n

The equals (=) sign is used to assign a value to a variable:

\n\n

def age = 101\ndef name = \"Fred\"\n

\n\n\n\n\n\n

In the following code the variable count is assigned the numeric value 10:

\n\n

def count = 10\n

\n\n\n\n

If we then wanted to compare count with another value (11) we need to use the == operator:

\n\n

if (count == 11) println \"Count is 11\"\n

\n\n\n\n

Use of = in the comparison will cause a compilation error:

\n\n

if (count = 11) println \"Count is 11\"\n

\n\n\n\n

Rest assured that if you accidentally use the simple assignment operator (=) instead of the equality operator (==) you’ll not be the first in making that mistake.

\n\n

\n27. The Complement Operator

\n\n\n\n

The exclamation (!) sign is used switch a value to its opposite boolean value. In boolean algebra¹ this is referred to as a Not (or negation) operator.

\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n\n

Complement operator
Operator
`!`

\n\n

The following example makes sure that “not true” is the same as “false”:

\n\n

assert !true == false\n

\n\n\n\n

The complement operator results in the following:

\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n

The complement truth table
Value	Complement
`true`	`false`
`false`	`true`

\n\n

see http://en.wikipedia.org/wiki/Boolean_algebra ↩\n

\n\n\n

\n28. Equality Operators

\n\n\n\n

The equality operators return a boolean (true or false) result from a comparison.

\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n

The equality operators
Operator	Name
==	Equal to
!=	Not equal to

\n\n

All of the following comparisons evaluate as being true:

\n\n

Some equality checks

\n\n

assert -99 == -99\nassert 'koala' == 'koala'\nassert 'cat' != 'dog'\nassert 6 != 7\n\ndef domesticAnimal = 'dog'\ndef wildAnimal = 'lion'\nassert domesticAnimal != wildAnimal\n\ndef str1 = 'Hello'\ndef str2 = 'Hello'\nassert str1 == str2\n

\n\n\n\n

What Is Equality?

\n\n

Equality can be a little tricky - both for Groovy and humanity. Think about the statement “Hey cool, we have the same car!”. This could mean that we have the same make and model but different instances of a car or it could mean that we share a car.

\n\n\n\n

Using is and ==

\n\n

def obj1 = new Object()\ndef obj2 = new Object()\ndef obj3 = obj1\n\nassert obj1.is(obj3)\nassert ! obj1.is(obj2)\n\nassert obj1 != obj2\nassert obj1 == obj3\n\nassert ! obj1.equals(obj2)\nassert obj1.equals(obj3)\n

\n\n\n\n

Precedence

In the following example, the equality operator (!=) is evaluated before the assignment operator (=), resulting in the value of truth being the boolean value true:

\n\n

def truth = 'cats' != 'dogs'\nassert truth == true\n

\n\n\n\n

Overloading Equality

\n\n

It is possible to define a custom implementation of == by overriding the equals(Object obj) method. This can be handy if your object has a simple method for determining equality, such as comparing staff members by their ID:

\n\n

Overloading ==

\n\n

class StaffMember {\n    def id\n\n    @Override\n    boolean equals(obj) {\n        if (this.id == obj.id) {\n            return true\n        } else {\n            return false\n        }\n    }\n}\n\ndef fred = new StaffMember(id: 12)\ndef jan = new StaffMember(id: 47)\ndef janet = new StaffMember(id: 47)\n\nassert fred != jan\nassert jan == janet\n

\n\n\n\n

The Groovy package groovy.transform provides a handy annotation that generates an equals implementation which compares the object’s properties. This reduces the previous StaffMember class to even fewer lines of code:

\n\n

Using the built-n EqualsAndHashCode

\n\n

@groovy.transform.EqualsAndHashCode\nclass StaffMember {\n    def id\n}\n\ndef fred = new StaffMember(id: 12)\ndef jan = new StaffMember(id: 47)\ndef janet = new StaffMember(id: 47)\n\nassert fred != jan\nassert jan == janet\n

\n\n\n\n\n\n

See http://en.wikipedia.org/wiki/Java_hashCode()↩\n

\n\n\n

\n29. Arithmetic operators

\n\n\n\n

The five arithmetic operators (+, -, *, /, %) are familiar to most people from their early school days.

\n\n

Additive Operators

\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n

The additive operators
Operator	Name
+	Plus
-	Minus

\n\n

The additive operators provide for basic addition and subtraction.

\n\n

assert 1 + 1 == 2\nassert 10 - 9 == 1\n

\n\n\n\n

Additive operators are left-associative - they are assessed from left to right:

\n\n

assert 1 + 4 - 3 == 2\n

\n\n\n\n\n\n

Multiplicative Operators

\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n

The multiplicative operators
Operator	Name
*	Multiply
/	Divide
%	Remainder

\n\n

The remainder operator (%) is also commonly referred to as the modulus operator and returns the remainder of a division:

\n\n

assert 13 % 2 == 1\n

\n\n\n\n

Multiplicative operators are left-associative:

\n\n

assert 10 * 6 / 2 == 30\n

\n\n\n\n

The Power operator

\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n\n

The power operator
Operator	Name
**	Power

\n\n

The power operator (**) is used to raise a number to the power of the second number:

\n\n

assert 5**3 == 125\n

\n\n\n\n\n\n

Precedence

Multiplicative operators have precedence over additive operators.

\n\n

assert 10 - 1 * 10 == 0\n

\n\n\n\n

If the result above is surprising and the expected result was 90 then parentheses “()” should have been used:

\n\n

assert (10 - 1) * 10 == 90\n

\n\n\n\n

The elements within parentheses have precedence over the rest of the evaluation. This results in (10 - 1) being evaluated first and the result being multiplied by 10.

\n\n

If we consider Pythagoras’ theorem: ( $\"a^2$ ) the operator precedence will yield the correct answer without requiring parentheses:

\n\n

assert 3 * 3 + 4 * 4 == 5 * 5\n

\n\n\n\n

However, we could use parentheses purely for the sake of clarity:

\n\n

assert (3 * 3) + (4 * 4) == (5 * 5)\n

\n\n\n\n\n\n

Nested parentheses can be used to further delineate an expression. The innermost parentheses are evaluated first, then moving outwards:

\n\n

assert ((10 - 1) * 10) / 2 == 45\n

\n\n\n\n

In the equation above, (10 - 1) is evaluated first, the result (9) is then multiplied by 10 and that result (90) being divided by 2.

\n\n

For significantly more complex calculations such as the quadratic equation (below) parentheses are required if the calculation is to be performed in a single expression:

\n\n $\"x$ \n\n

Part implementation of the quadratic equation

\n\n

def a = 5\ndef b = 6\ndef c = 1\ndef x\nx = ((-1 * b) + Math.sqrt((b**2) - (4 * a * c))) / (2 * a)\nassert x == -0.2\n

\n\n\n\n\n\n

\n30. Relational Operators

\n\n\n\n

Similar to the Equality Operators, the expressions involving Relational Operators return a boolean result (true or false).

\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n

The relational operators
Operator	Name
>	Greater than
>=	Greater than or equal to
<	Less than
<=	Less than or equal to
`<=>`	Spaceship

\n\n

All of the following operations resolve to true:

\n\n

It’s all true

\n\n

assert 5 > 2\nassert 4 >= 3\nassert 4 >= 4\nassert 8 < 9\nassert 6 <= 7\nassert 7 <= 7\n

\n\n\n\n

Ordinarily, the operands used in a relational comparison can be compared in a meaningful manner. If they are different data types then the operands need to be able to find a common type for comparison (such as both being numbers) - the following code will cause and exception because Groovy can’t be expected compare a string with a number in this way:

\n\n

if ('easy' < 123) println \"It's easier than 123\"\n

\n\n\n\n

Spaceship

The spaceship operator comes from the Perl programming language. The Spaceship operator is most often seen where sorting is done.

\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n\n

The spaceship operator
Operator
`<=>`

\n\n

In the example below the sort function uses the closure to define the sort algorithm and this is where the spaceship lands:

\n\n

UFO sighting

\n\n

def nums = [42, -99, 6.3, 1, 612, 1, -128, 28, 0]\n\n//Descending\nprintln nums.sort{n1, n2 -> n2<=>n1 }\n\n//Ascending\nprintln nums.sort{n1, n2 -> n1<=>n2 }\n

\n\n\n\n

The following table indicates the result for spaceship expressions (LHS = left-hand side, RHS = right-hand side):

\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n

Expression	Result
LHS less than RHS	-1
LHS equals RHS	0
LHS greater than RHS	1

\n\n

The following assertions all resolve as true:

\n\n

assert 2 <=> 2 == 0\nassert 1 <=> 2 == -1\nassert 2 <=> 1 == 1\n

\n\n\n\n

Overloading the relational operators

The compareTo method is used by Groovy to assess the result of relational operations:

\n\n

\tassert 1.compareTo(2) == -1\n

\n\n\n\n\n\n

Java’s Comparable interface is implemented by classes that allow instances to be compared. Custom classes can determine their own appropriate algorithm for the Comparable’s compareTo method and this will be available when you use the relational operators.

\n\n

Overloading relational operators

\n\n

class Num implements Comparable {\n    def val\n\n    @Override\n    int compareTo(obj) {\n         if (val < obj.val) {\n             return -1\n         } else if (val > obj.val) {\n             return 1\n         } else {\n             return 0\n         }\n    }\n}\n\ndef a = new Num(val: 2)\ndef b = new Num(val: 5)\ndef c = new Num(val: 2)\n\nassert a < b\nassert b > a\nassert a != b\nassert a == c\n

\n\n\n\n

You’ll notice that I’ve tested a != b and a == c - these equality operators actually call the compareTo method. There’s been a bit of discussion about how Groovy handles == and the underlying equals and compareTo methods so if you’re looking to overload these operators it’d be worth your time checking up on what the Groovy developers are planning.

\n\n

\n31. Increment and Decrement Operators

\n\n\n\n

The increment operator increments a value to its next value. When you increment or decrement a variable using ++ or -- the variable is modified to the new value.

\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n

Inc and dec
Operator	Name
++	Increment
–	Decrement

\n\n

The increment and decrement operators come in two flavours, prefix and postfix:

\n\n

Prefixes are assessed before the statement is evaluated\n
- assert ++5 == 6
\n
Postfixes are assessed after the statement is evaluated\n
- assert 5++ == 5
\n

\n\n

Using inc and dec

\n\n

assert 10++ == 10\nassert ++10 == 11\nassert --10 == 9\nassert 10-- == 10\n

\n\n\n\n

The increment and decrement behaves differently depending on the type of value being used.

\n\n

Booleans don’t increment/decrement

\n\n

Numbers increment/decrement by 1:

\n\n

def num = 10\nnum++\nassert num == 11\n

\n\n\n\n

Characters move to the previous (--) or next (++) character:

\n\n

def ch = 'c'\nch--\nassert ch == 'b'\n

\n\n\n\n

Strings are a little odd and it is the last character in the string that is affected:

\n\n

def str = 'hello'\nstr++\nassert str == 'hellp'\n

\n\n\n\n

Enums¹ will cycle through the enum values:

\n\n

enum Priority {\n    LOW, MEDIUM, HIGH\n}\ndef task = Priority.LOW\ntask++\nassert task == Priority.MEDIUM\n

\n\n\n\n

BUT be aware that you’ll cycle back to the beginning of the value list. The following example is a good example of where you can easily get caught out:

\n\n

def task = Priority.LOW\ntask--\nassert task == Priority.HIGH\n

\n\n\n\n

Overloading the Increment and Decrement Operators

\n\n

By overloading next and previous methods, a custom class can support the increment and decrement operators.

\n\n

The example below demonstrates a class that increments/decrements by 2:

\n\n

Overloading increment and decrement

\n\n

class StepTwo extends Object {\n    def value\n\n    StepTwo(val) {\n        this.value = val\n    }\n\n\n    def next() {\n        value += 2\n        return this\n    }\n\n    def previous() {\n        value -= 2\n        return this\n    }\n\n    String toString() {\n        return \"I have a value of ${this.value}\"\n    }\n}\n\ndef two = new StepTwo(3)\nprintln two\ntwo++\nprintln two\ntwo--\nprintln two\n

\n\n\n\n

We’ll get to Enums much later.↩\n

\n\n\n

\n32. Conditional Operators

\n\n\n\n

You’ll most often see Conditional-and (&&) and Conditional-or (||) used in conditional statements such as if. We also use them in expressions such as assert to determine if a statement is true or false.

\n\n

The Conditional Operator (?:) is a short-form variant of the if-else statement that really helps with code readability. It’s also referred to as the “elvis” operator and the “ternary” operator.

\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n

The conditional operators
Operator	Name
`&&`	Conditional-and
`\|\|`	Conditional-or
`?:`	Conditional operator

\n\n

What Is Truth?

\n\n

All of the following statements resolve as true and the assertions all pass:

\n\n

assert 1\nassert true\nassert 'Hello'\n

\n\n\n\n

Obviously false is false but so is 0, '' (empty string) and null.

\n\n

The complement operator (!) can be used to negate an expression, allowing the following assertions to pass:

\n\n

assert !false\nassert !0\nassert !''\nassert !null\n

\n\n\n\n

Evaluation

\n\n

Conditional operators are evaluated left-to-right. The assertion in the following code passes as the result of true && false is false but is then or’d with true, resulting in true:

\n\n

assert true && false || true\n

\n\n\n\n

Conditional-And

Conditional-and uses the boolean AND to determine if a statement is true or false. In order to be true, both the left-hand and right-hand operands must evaluate to true, as described in the truth table below:

\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n

AND Truth Table
LHS	RHS	Result
0	0	0
1	0	0
0	1	0
1	1	1

\n\n

In a conditional-and statement, both expressions are always evaluated. In the example below, ++counter is evaluated (giving counter now equal to 1) before the conditional is assessed:

\n\n

def counter = 0\ndef result = true && ++counter\n\nassert result == true\nassert counter == 1\n

\n\n\n\n

Conditional-Or

Conditional-or uses the boolean OR to determine if a statement is true or false. In order to be true, either the left-hand or right-hand operands must evaluate to true, as described in the truth table below:

\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n

OR Truth Table
LHS	RHS	Result
0	0	0
1	0	1
0	1	1
1	1	1

\n\n

In a conditional-or statement, each expression is evaluated in left-to-right order until either an expression resolves to true or no expressions are left (resulting in false overall). Once an expression is evaluated to true no further evaluation of the conditional is performed. This is important to keep in mind if you have an expression performing an operation that you later rely on as it may never be evaluated. In the example below I demonstrate a similar block of code used in the conditional-and section but I’ll use a conditional-or. The final assertion (assert counter == 1) will fail as ++counter is never evaluated:

\n\n

def counter = 0\ndef result = true || ++counter\n\nassert result == true\nassert counter == 1\n

\n\n\n\n

Conditional Operator

\n\n

The conditional operator (?:) is most commonly used when assigning a value to a variable. A conditional expression is used for the first operand and placed to the left of the question-mark. If this resolves to true then the second operand is evaluated, otherwise the third operand is evaluated. This sounds a little confusing so let’s look at an example:

\n\n

A basic tax calculator

\n\n

def salary = 100000\n\ndef taxBracket = salary < 75000 ? 'Bracket 1': 'Bracket 2'\n\nassert taxBracket == 'Bracket 2'\n

\n\n\n\n

In the code above the relational expression (salary < 75000) is evaluated and, in this case, resolves to false and the third operand (Bracket 2) is evaluated and assigned to taxBracket. As the operand is just a string there’s no real evaluation but we can use any expression that will return a result.

\n\n

The code below will calculate income tax based on the person’s income:

\n\n

More tax

\n\n

def salary = 100000\n\ndef tax = salary < 75000 ? salary * 0.1: salary * 0.2\n\nassert tax == 20000\n

\n\n\n\n\n\n

A major benefit of the conditional operator is readability. Consider the previous code being re-written using an if statement and I trust you’ll see that ?: makes for more compact and readable code:

\n\n

A less readable option

\n\n

def salary = 100000\ndef tax = 0\n\nif (salary < 75000) {\n    tax = salary * 0.1\n} else {\n    tax = salary * 0.2\n}\n\nassert tax == 20000\n

\n\n\n\n

Default values

\n\n

The conditional operator is also really useful for default values - these are used when you want to make sure a variable always has a value. In the code below the Person class has been prepared to ensure that any instance that has not been explicitly given a value for the name property is assigned Anonymous as the name:

\n\n

Using ?: to set a default value

\n\n

class Person {\n    def name\n\n    def Person(name = '') {\n        setName(name)\n    }\n\n    def setName(name) {\n        this.name = name ?: 'Anonymous'\n    }\n}\n\ndef jim = new Person()\nprintln jim.name\n

\n\n\n\n

Instead of writing this.name = name ? name: 'Anonymous' you’ll notice that I didn’t provide a second operand. This is another bonus for the ternary operator - if the conditional resolves to true and no second operand is provided, the result of the conditional is returned. This is a boring way to say that in this.name = name ?: 'Anonymous' if name is not false then it is assigned to this.name.

\n\n\n\n

Avoiding NPEs

NPEs (Null-Pointer Expressions) are the bane of Java and Groovy programmers. You’ll see a lot of code checking for null and this reduces readability. This is usually in the form if (myObj != null) {...} or using the conditional operator (myObj != null) ? ... : ....

\n\n

As null evaluates to false in Groovy, the conditional operator provides a compact means by which to check if an object is null before trying to access the object:

\n\n

def myObj = null\ndef dump =  myObj ? myObj.dump() : ''\n

\n\n\n\n

In the example above I test myObj and, if it isn’t null then dump is given the value returned by myObj.dump(). Otherwise an empty string ('') is returned.

\n\n

As an alternative, the safe-navigation operator (?.) can be used to test for null prior to attempting access on the object:

\n\n

def myObj = null\ndef dump = myObj?.dump()\n

\n\n\n\n

The safe navigation operator is discussed further under Object Operators.

\n\n

In Java

In the code below I’ve provided a small example of checking for null in Java. You’ll note that we need to be explicit on our conditional ((t == null)):

\n\n

Checking for null in Java

\n\n

public class NullTest {\n    public static void main(String[] args) {\n        NullTest t = null;\n\n        String output = (t == null) ? \"Null\" : \"Not null\";\n\n        System.out.println(output);\n    }\n}\n

\n\n\n\n

To prove that I’m not just bloating my code to prove a point, here’s a slightly more compact version of the example:

\n\n

Checking for null in Java - compacted

\n\n

public class NullTest {\n    public static void main(String[] args) {\n        NullTest t = null;\n        System.out.println(t==null ? \"Null\" : \"Not null\");\n    }\n}\n

\n\n\n\n

You’ll note that I didn’t bother with the output variable and dropped the parentheses (they’re not required). The code is reasonably compact but rewritten in Groovy it gets even tidier:

\n\n

Checking for null in Groovy

\n\n

class NullTest {\n    static main(args) {\n        def t = null\n        println(t ? 'Not null' : 'Null')\n    }\n}\n

\n\n\n\n

You still need to check for null in Groovy but the shortened conditional operator and the safe navigation operator really do help cut down on the boiler-plate stuff.

\n\n

\n33. Bitwise Operators

\n\n\n\n

I have to admit that I haven’t seen many instances of bitwise manipulation since my university assignments. That’s not to say they’re not used or not important - I’ve just not done a lot of programming that’s called on bitwise operators.

\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n

The bitwise operators
Operator	Name
&	Bitwise AND
\|	Bitwise OR
^	Bitwise XOR¹\n
~	Bitwise negation (Not)
>>	Right shift
>>>	Right shift unsigned
<<	Left shift

\n\n

Truth Tables

\n\n

Truth tables describe the results of various logical operations. The truth tables below illustrate the NOT, AND, OR and XOR logic.

\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n

Not (`~`)	Result
Not 0	0
Not 1	1

\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n

And (`&`)	Result
0 AND 0	0
0 AND 1	0
1 AND 0	0
1 AND 1	1

\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n

Or (`\|`)	Result
0 OR 0	0
0 OR 1	1
1 OR 0	1
1 OR 1	1

\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n

Xor (`^`)	Result
0 XOR 0	0
0 XOR 1	1
1 XOR 0	1
1 XOR 1	0

\n\n

Flag example

\n\n

The unix file permission scheme uses binary flags for read, write and execute permissions on files. You see them when you run ls -l as something like -rwxr-xr-x. Essentially, this is a set of flags where binary 1 turns on that permission and binary 0 turns it off. The three elements I’ll look at here are read (r), write (w) and execute (x):

\n\n

READ has the binary value 001 (decimal 1)
WRITE has the binary value 010 (decimal 2)
EXECUTE has the binary value 100 (decimal 4)

\n\n

Let’s look at the example code first and then I’ll discuss it:

\n\n

A bitwise example

\n\n

//Create global variables for the permissions\nREAD = 0b100\nWRITE = 0b010\nEXECUTE = 0b001\n\nprintln 'Checking for READ:'\ncheckFile(READ)\n\nprintln 'Checking for WRITE:'\ncheckFile(WRITE)\n\nprintln 'Checking for READ or EXECUTE:'\ncheckFile(READ | EXECUTE)\n\ndef checkFile (check) {\n    def fileList = [:]\n    for (i in 0..7) {\n        fileList[\"File $i\"] = i\n    }\n\n    for (file in fileList) {\n        if (file.value & check) {\n            println \"$file.key (${displayFilePermission(file.value)}) meets crit\\\neria\"\n        }\n    }\n}\n\ndef displayFilePermission(val) {\n    def retval = \"\"\n    retval <<= (READ & val)? 'r': '-'\n    retval <<= (WRITE & val)? 'w': '-'\n    retval <<= (EXECUTE & val)? 'x': '-'\n    return retval\n}\n

\n\n\n\n\n\n

First up I set the flags for each of the three elements using the 0b prefix to indicate binary numbers:

\n\n

READ = 0b100\nWRITE = 0b010\nEXECUTE = 0b001\n

\n\n\n\n

I then call my checkFile method to see which permissions match what I’m seeking. The third call to checkFile is the more interesting as I OR two flags: READ | EXECUTE. If I OR the READ flag (100) with the EXECUTE flag (001) I get 101 (decimal 5):

\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n

Value	Binary		Operator
READ	1	0	OR
EXECUTE	0	1
Result	1	1	=

\n\n

The checkFile method does the checking for me. The first part of the method just creates a set of possible files - enough to cover the various variations of the rwx elements:

\n\n

def fileList = [:]\nfor (i in 0..7) {\n    fileList[\"File $i\"] = i\n}\n

\n\n\n\n\n\n

It’s the second half of checkFile that does the important stuff:

\n\n

for (file in fileList) {\n    if (file.value & check) {\n        println \"$file.key (${displayFilePermission(file.value)}) meets criteria\"\n    }\n}\n

\n\n\n\n

The if (file.value & check) performs an AND on the check requested (e.g. READ) and the file’s permissions. If the AND returns a result greater than 0 then the file’s permission match the check. For example, a file with execute permission (--x) meets the READ | EXECUTE criteria:

\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n

Item	Value	Binary		Operator
`check`	READ \| EXECUTE	1	1	AND
`file`	`--x`	0	1
	Result	0	1	=

\n\n

A file with read and write permission (rw-) also matches:

\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n

Item	Value	Binary			Operator
`check`	READ \| EXECUTE	1	0	1	AND
`file`	`rw-`	1	1	0
	Result	1	0	0	=

\n\n

However, a file with only the write permission (-w-) will not successfully match:

\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n

Item	Value	Binary			Operator
`check`	READ \| EXECUTE	1	0	1	AND
`file`	`-w-`	0	1	0
	Result	0	0	0	=

\n\n

Lastly, the displayFilePermission method just helps me display the permissions in the rwx format.

\n\n

Some other quick points follow:

\n\n

I can negate (~) a value to indicate that I want the inverse of a value, rather than ORing the other options individually:

\n\n

println 'Checking for WRITE or EXECUTE:'\ncheckFile(~READ)\n

\n\n\n\n

I can XOR (^) to aggregate the permissions but ignore intersections (where both variables contain the same flag):

\n\n

def file1 = READ | EXECUTE\ndef file2 = WRITE | EXECUTE\nprintln 'File 1: ' << displayFilePermission(file1)\nprintln 'File 2: ' << displayFilePermission(file2)\nprintln 'Result: ' << displayFilePermission(file1 ^ file2)\n

\n\n\n\n

Shift Example

\n\n

Shifting just moves the bits in a binary to the left (<<) or to the right (>>), depending on the left-hand operand. If we take the following list as a starting point we can see how progressive shifts left change a value:

\n\n

0001 (binary) = 1 (decimal)
0010 (binary) = 2 (decimal)
0100 (binary) = 4 (decimal)
1000 (binary) = 8 (decimal)

\n\n

With this is mind the following code demonstrates the left- and right-shift operators:

\n\n

assert 2 << 1 == 4\t//Left-shift once\nassert 2 << 2 == 8\t//Left-shift twice\nassert 2 >> 1 == 1\t//Right-shift once\n

\n\n\n\n

The code below displays a table in which each row represents a value that’s be left-shifted by one position more than the prior row:

\n\n

A bit shifting example

\n\n

def value = 0b0000_0000_0000_0000_1111_1111\n\nprintln '| Shift   | Hex      | Decimal  | Octal    | Binary                   |'\nprintln '|---------|----------|----------|----------|--------------------------|'\n(0..16).each {\n    def shifted = value << it\n    def hexDisplay = '0x' << Integer.toHexString(shifted).padLeft(6, '0')\n    def binDisplay = Integer.toBinaryString(shifted).padLeft(24, '0')\n    def decDisplay = \"$shifted\".padLeft(8, ' ')\n    def octDisplay = Integer.toOctalString(shifted).padLeft(8, ' ')\n    def shiftDisplay = \"$it\".padLeft(7, ' ')\n    println \"| $shiftDisplay | $hexDisplay | $decDisplay | $octDisplay | $binDis\\\nplay |\"\n}\nprintln '|---------|----------|----------|----------|--------------------------|'\n

\n\n\n\n\n\n

Known as an Exclusive OR↩\n

\n\n\n

\n34. Compound Assignment Operators

\n\n\n\n

The compound assignment operators¹ really just conflate an operation that involves a variable which is, it turn, used to store the result. Let’s look at an example to make this clearer. In the example below I really just want to add 10 to the cost variable:

\n\n

def cost = 20\ncost = cost + 10\nassert cost == 30\n

\n\n\n\n

By using a compound assignment operator I can clean up the code (in a very minor way) by performing the operation ‘in place’:

\n\n

def cost = 20\ncost += 10\nassert cost == 30\n

\n\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n

The compound assignment operators
Operator	Name
*=	Multiply
/=	Divide
%=	Remainder
+=	Plus
-=	Minus
**=	Power
<<=	Bitwise left-shift
>>=	Bitwise right-shift
>>>=	Bitwise unsigned right-shift
&=	Bitwise And
^=	Bitwise Xor
\|=	Bitwise Or

\n\n

Also known as augmented assignment operators. See http://en.wikipedia.org/wiki/Augmented_assignment ↩\n

\n\n\n

\n35. String Operators

\n\n\n\n

You’ll spend a lot of your career manipulating strings so anything that makes them less of a hassle is nice. Groovy helps you with the following operators overloaded for your string work.

\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n

String operators
Operator(s)	Type
\n`+`, `<<`\n	Concatenate Operator
\n`<<=` `+=`\n	Append Operator
`-`	Remove Operator
`-=`	Remove In-place Operator
`*`	Repeat Operator
`*=`	Repeat In-place Operator
\n`++` `--`\n	Increment and Decrement Operators

\n\n

Concatenate Operator

\n\n

The concatenate operator joins two strings together:

\n\n

println  'It was the best of times.' << 'It was the worst of times.'\n

\n\n\n\n

The above example is rather daft as we could have just put both strings together in the same set of quotes. You’re more likely to see strings added to over the course of a program:

\n\n

def quote = 'It was the best of times.'\nquote = quote << 'It was the worst of times.'\nprintln quote\n

\n\n\n\n

Instead of using the concatenate you could have just used string interpolation:

\n\n

def quote = 'It was the best of times.'\nquote = \"$quote It was the worst of times.\"\nprintln quote\n

\n\n\n\n

The + operator is used in the same manner as <<:

\n\n

def quote = 'It was the best of times.'\nquote = quote + 'It was the worst of times.'\nprintln quote\n

\n\n\n\n

As you’ll see in later in this chapter it’s best to use << over +

\n\n

Concatenation and Types

\n\n

When you concatenate a string with a number Groovy will cast the number into a string. That means you can end up with 1 + 1 = 11 as the code below demonstrates:

\n\n

assert '1' + 1 == '11'\nassert 1 + '1' == '11'\n

\n\n\n\n

If you’re really wanting to add a string to a number you need to make sure you explicitly turn the string into a number:

\n\n

assert '1'.toInteger() + 1 == 2\n

\n\n\n\n

This may all sound a bit odd now but if you’re trying to work out why your program’s maths seems all wrong it’s worth looking into where strings and numbers are being mashed together.

\n\n

Append Operator

\n\n

The append operator (<<=) conflates the assignment (=) and concatenate operators:

\n\n

def quote = 'It was the best of times.'\nquote <<= 'It was the worst of times.'\nprintln quote\n

\n\n\n\n

This saves you from having to use quote = quote << 'It was the worst of times.'

\n\n\n\n

Remove Operator

\n\n

The remove operator (-) removes the first instance of a string or regular expression from another string. The easiest form just removes the first instance of a specific string - in the case of the example below, ‘of ‘ is removed:

\n\n

quote = 'It was the worst of times.' - 'of '\nprintln quote\n

\n\n\n\n

The example above will display It was the worst times.

\n\n

A regular expression pattern can also be used if you want to use a pattern. In the example below, the first occurrence of “bat” or “rat” is removed, resulting in cat rat monkey:

\n\n

println 'cat bat rat monkey' - ~/[br]at/\n

\n\n\n\n

Remove In-Place Operator

\n\n

Works just like the remove operator (-) but does the match to the variable as well as modifying it. As for the first remove example, a string can be provided for removal:

\n\n

quote = 'It was the worst of times.'\nquote -= 'of '\nprintln quote\n

\n\n\n\n

…and it can also use patterns:

\n\n

def str = 'cat bat rat monkey'\nstr -= ~/[br]at/\nprintln str\n

\n\n\n\n

Repeat Operator

\n\n

This is a great operator for those that love repetition! Let’s print out hello ten-times, each time one a new line:

\n\n

print 'hello\\n' * 10\n

\n\n\n\n

Repeat In-PlaceOperator

\n\n

This one applies the multiplier against the variable and stores the result back in the variable:

\n\n

def complaint = 'ow'\ncomplaint *= 10\nprintln complaint\n

\n\n\n\n

I’ll leave it to you to see what happens :)

\n\n

Increment and Decrement Operators

\n\n

The increment operator will move the last character of the string to its next value:

\n\n

def str = 'hello'\nstr++\nassert str == 'hellp'\n

\n\n\n\n

The increment/decrement actually works across the Unicode character codes¹ so don’t expect code to just use ‘a’ to ‘z’:

\n\n

def str = 'fo%'\nstr--\nassert str == 'fo$'\n

\n\n\n\n

For a small experiment, try the following code - it will display a subset of the Unicode characters:

\n\n

//\\u00A1 is the Unicode character for an inverted exclamation mark\ndef chr = '\\u00A1'\nfor (i in 161..191) {\n    println chr\n    chr++\n}\n

\n\n\n\n

I’m sure that this is useful somewhere…..

\n\n

Warning: Strings Are Expensive!

\n\n

Many programs build strings up over the course of their operation. This can start becoming very expensive in terms of program resources such as memory because, without the correct approach, the JVM has to copy strings to new memory locations each time you use concatenation.

\n\n

Java developers turn to the StringBuilder and StringBuffer classes to make their string building more efficient. Groovy developers using dynamic types can use a few tricks to stay dynamic and ensure efficiency.

\n\n

Let’s take a look at two approaches to building a string. In the first example I’ll use the += operator and perform 1000 concatenations:

\n\n

Timing the += concatenation

\n\n

import java.text.DecimalFormat\n\ndef quote = 'It was the best of times. It was the worst of times.\\n'\n\ndef str = \"\"\n\ndef startTime = System.nanoTime()\n1000.times {\n    str += quote\n}\ndef endTime = System.nanoTime()\n\nDecimalFormat formatter = new DecimalFormat(\"#,###\")\ndef duration = formatter.format(endTime - startTime)\n\nprintln \"That took $duration nano seconds\"\n

\n\n\n\n\n\n

In the next example I’ll change just 1 thing: I’ll use the <<= operator rather than +=:

\n\n

Timing the <<= concatenation

\n\n

import java.text.DecimalFormat\n\ndef quote = 'It was the best of times. It was the worst of times.\\n'\n\ndef str = \"\"\n\ndef startTime = System.nanoTime()\n1000.times {\n    str <<= quote\n}\ndef endTime = System.nanoTime()\n\nDecimalFormat formatter = new DecimalFormat(\"#,###\")\ndef duration = formatter.format(endTime - startTime)\n\nprintln \"That took $duration nano seconds\"\n

\n\n\n\n

When I run these scripts in groovyConsole I can see that the results are very different. When I ran each test 100 times and averaged the result I got:

\n\n

Example 1 (using +=): 24,215,520 ns
Example 2 (using <<=): 191,490 ns

\n\n

To me this is evidence enough for me to use ‘<<=’ over +=!

\n\n

Templates

\n\n

If you find yourself building strings around boilerplate text - such as a form letter - consider using Groovy’s templating system.

\n\n

See the Unicode Character Code Charts ↩\n

\n\n\n

\n36. Regular Expression Operators

\n\n\n\n

The earlier tutorial on Regular Expressions covered regular expression (pattern) variables and described the find and match methods. These operators are similar to these methods but return true or false if the pattern is found in (find) or matches (match) the first operand (a string).

\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n

RegEx operators
Operator(s)	Type
`=~`	Find
`==~`	Match

\n\n

For these operations, the left-hand operand must be a string and the right-hand operand a regular expression pattern.

\n\n

Find (`=~`)

Returns true if the string on the left-side contains the pattern on the right of the operator.

\n\n

def regex = ~/:[0-9]+/\ndef httpUrl1 = 'http://www.example.com:8080/'\ndef httpUrl2 = 'http://www.example.com/'\n\nassert httpUrl1 =~ regex\nassert ! (httpUrl2 =~ regex)\n

\n\n\n\n

Match (`==~`)

Returns true if the string on the left-side matches (completely) the pattern provided on the right of the operator

\n\n

def regex = ~/https?:\\/\\/.*/\n\ndef httpUrl = 'http://www.example.com/'\ndef ftpUrl = 'ftp://ftp.example.com/'\n\nassert httpUrl ==~ regex\nassert ! (ftpUrl ==~ regex)\n

\n\n\n\n

\n37. Collection operators

\n\n\n\n

A number of operators are provided for working with Lists and Maps. Some overload operators such as + and << whilst others (such as in) are more collection-oriented. Certain operators work with both Lists and Maps whilst others apply to only one.

\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n

Operator(s)	Type
`in`	Membership Operator
`<<`	Append operator
`+`	Addition operator
`-`	Subtraction operator
\n`+=` `-=`\n	Compound assignment operators
`*`	Spread Operator
`*.`	Spread-Dot Operator
`..`	Range Operator
`[]`	Subscript Operator

\n\n

This chapter won’t discuss the following operators as they’ve been described earlier:

\n\n

The Range operator creates a list of sequential values and is usually seen with numbers. This is how we created Range variables.
The Subscript operator is used to access items in a List or a Map and this was discussed in the tutorial on collection variables.

\n\n

To finish this chapter off I’ll do a little bit of mucking around with set theory.

\n\n

Membership Operator (Lists and Maps)

\n\n

The in operator is used to determine if an item is “in” a list or is a key in a map.

\n\n

Using the in operator

\n\n

assert 6 in [1, 2, 6, 9]\nassert !(3 in [1, 2, 6, 9])\n\ndef grades = ['Maths': 'A',\n    'English': 'C',\n    'Science': 'B'].asImmutable()\n\nassert 'Science' in grades\nassert !('French' in grades)\n

\n\n\n\n

Append (Lists and Maps)

\n\n

The << operator adds a new element to an existing list:

\n\n

def friends = ['Frank', 'Larry']\nfriends << 'Jane'\nprintln friends\n

\n\n\n\n

It’s important to note that appending a list to a list will add a new element that contains the list in the right-hand operand:

\n\n

def friends = ['Frank', 'Larry']\nfriends << ['Jane', 'Greg']\nassert friends == ['Frank', 'Larry', ['Jane', 'Greg']]\n

\n\n\n\n

In order to add the individual items of one list to another I need to use the addAll() method:

\n\n

def friends = ['Frank', 'Larry']\nfriends.addAll(['Jane', 'Greg'])\nassert friends == ['Frank', 'Larry', 'Jane', 'Greg']\n

\n\n\n\n\n\n

I can also use << to append a new key:value pair to a map:

\n\n

def grades = [:]\ngrades << ['Maths': 'A']\ngrades << ['English': 'C']\ngrades << ['Science': 'B']\nprintln grades\n

\n\n\n\n

If I was to add another line grades << ['Science': 'F'] to the code above, the value for Science would be changed to F as the map’s keys are unique.

\n\n

Addition (Lists and Maps)

\n\n

The addition operator (+) returns a new list with the right-hand operand added:

\n\n

def friends = ['Frank', 'Larry']\nassert friends + 'Jane' == ['Frank', 'Larry', 'Jane']\n

\n\n\n\n\n\n

When we add two lists together we get a union of the two lists returned:

\n\n

def friends = ['Frank', 'Larry']\nassert friends + ['Jane', 'Greg'] == ['Frank', 'Larry', 'Jane', 'Greg']\n

\n\n\n\n\n\n

Adding to a Set returns a set with the union sans any duplicates:

\n\n

def set = [2, 4, 6, 8] as Set\nassert set + [8, 10] == [2, 4, 6, 8, 10] as Set\n

\n\n\n\n

The addition operator will either add a key:value pair to a map or alter the value held against an existing key. In the example below I create a new map item with a result for my French class and then change an existing map item with a reduced English score:

\n\n

def grades = ['Maths': 'A',\n    'English': 'C',\n    'Science': 'B']\n\nassert grades + ['French': 'F'] == ['Maths': 'A', 'English': 'C', 'Science': 'B'\\\n, 'French': 'F']\nassert grades + ['English': 'D'] == ['Maths': 'A', 'English': 'D', 'Science': 'B\\\n']\n

\n\n\n\n

Subtraction (Lists and Maps)

\n\n

The subtraction (-) operator will return a new list with an element removed if the list contains the element:

\n\n

assert [2, 4, 6, 8] - 6 == [2, 4, 8]\n

\n\n\n\n

A list can also be subtracted from a list, returning a new list containing items in the left-hand operand ([2, 4, 6, 8]) that are not in the right-hand operand ([2, 6, 12]):

\n\n

assert [2, 4, 6, 8] - [2, 6, 12] == [4, 8]\n

\n\n\n\n

In the example below my attempt to remove Gary doesn’t do anything as he’s not in the list (this doesn’t cause an exception) but I do succeed in un-friending Frank:

\n\n

def friends = ['Frank', 'Larry', 'Jane']\nassert friends - 'Gary' == ['Frank', 'Larry', 'Jane']\nassert friends - 'Frank' == ['Larry', 'Jane']\n

\n\n\n\n

When subtraction is applied to a Map the right-hand operand needs to be a key:value pair. In the example below I attempt 3 things:

\n\n

I attempt to remove ['English': 'D'] but it’s not in grades so nothing happens
I attempt to remove ['French': 'F'] but it’s not in grades so nothing happens
I attempt to remove ['English': 'C'] and it is in grades so the removal occurs.

\n\n

Subtracting from a map

\n\n

def grades = ['Maths': 'A',\n    'English': 'C',\n    'Science': 'B']\n\nassert grades - ['English': 'D'] == ['Maths': 'A', 'English': 'C', 'Science': 'B\\\n']\nassert grades - ['French': 'F'] == ['Maths': 'A', 'English': 'C', 'Science': 'B']\nassert grades - ['English': 'C'] == ['Maths': 'A', 'Science': 'B']\n

\n\n\n\n

Compound Assignment Operators (Lists and Maps)

\n\n

Just as we saw with numbers, the addition and subtraction operators returns a value but don’t actually change the variable involved in the operation. To change the value of grades I would have needed to assign the resultant back into the variable as follows:

\n\n

grades = grades + ['French': 'F']\nassert grades  == ['Maths': 'A', 'English': 'C', 'Science': 'B', 'French': 'F']\n

\n\n\n\n

If we want to use the grades variable as the left-hand operand and change its value we can use the compound assignment operators. This means I could also have written the previous example using the += compound assignment:

\n\n

grades += ['French': 'F']\nassert grades  == ['Maths': 'A', 'English': 'C', 'Science': 'B', 'French': 'F']\n

\n\n\n\n

Using the append operator in its compound form (<<=) is redundant.

\n\n

Immutability and Assignment

\n\n

Consider the following code and see if you’re surprised:

\n\n

def grades = ['Maths': 'A',\n    'English': 'C',\n    'Science': 'B'].asImmutable()\n\ngrades += ['French': 'F']\nassert grades  == ['Maths': 'A', 'English': 'C', 'Science': 'B', 'French': 'F']\n

\n\n\n\n

Groovy let me change something that’s immutable! I should go to the mailing list and report this! The outrage!

\n\n

Hang on! What asImmutable() does is set the elements of the list to be unchangeable but it doesn’t make the grades variable immutable. As the + operator actually returns a new list value, Groovy is correct in assigning that new value to grades.

\n\n

If I’d used grades << ['French': 'F'] instead of grades += [‘French’: ‘F’] I would get a java.lang.UnsupportedOperationException as I’m actually trying to add a new element to grades.

\n\n

If I really want to make grades completely immutable (constant) then I’d need to use the final modifier and declare grades within a class. The code below demonstrates how I’d set up the class and ensure that attempts to change grades cause an exception:

\n\n

class Report {\n    final grades = ['Maths': 'A',\n        'English': 'C',\n        'Science': 'B'].asImmutable()\n}\n\ndef myReport = new Report()\nmyReport.grades += ['French': 'F']\n

\n\n\n\n

Running the code above will earn you a groovy.lang.ReadOnlyPropertyException.

\n\n

Spread Operator (Lists)

\n\n

The Spread operator extracts each element in the List into another list or a method’s parameters. This is helpful when you need to include a list’s individual items in another list or when your list can be used as parameters in a method call.

\n\n

Extracting Into Lists

\n\n

In the first example, one lists’s items are extracted into another list:

\n\n

def list = [1, 2, 6, 9]\ndef list2 = [*list, 12, 34]\nassert list2 == [1, 2, 6, 9, 12, 34]\n

\n\n\n\n

This usage looks rather like the addAll() method but you may need to be mindful as to the position in which the list is extracted. The example below uses addAll() but results in list2 being ordered differently than in the previous example:

\n\n

def list = [1, 2, 6, 9]\ndef list2 = [12, 34]\nlist2.addAll(list)\nassert list2 == [12, 34, 1, 2, 6, 9]\n

\n\n\n\n

In this last example I demonstrate an easy approach to creating a union of the two lists:

\n\n

def list = [1, 2, 6, 9]\ndef list2 = [12, 34]\nassert [*list, *list2] == [1, 2, 6, 9, 12, 34]\n

\n\n\n\n

Extracting as Parameters

\n\n

In the next example I extract the items in the score list out, each aligning with the parameters in the method signature:

\n\n

def mean(num1, num2, num3) {\n  (num1 + num2 + num3) / 3\n}\ndef scores = [4, 8, 3]\nassert mean(*scores) == 5\n

\n\n\n\n

That last example is a little bit of a goldilocks moment - I have exactly the same number of items in the list as the method has parameters. I also have a pretty limited version of the mean method - it only works on 3 numbers. However, a method with a varargs parameter is a little less fairy tale:

\n\n

def mean(...nums) {\n  def total = 0\n  for (item in nums) {\n    total += item\n  }\n  return total / nums.size()\n}\n\ndef scores = [4, 8, 3]\nassert mean(*scores) == 5\n

\n\n\n\n

One last example of using the spread operator:

\n\n

def buyGroceries(...items) {\n    for (item in items) {\n        println item\n    }\n}\n\ndef shoppingList = ['apples', 'cat food', 'cream']\nbuyGroceries(*shoppingList)\n

\n\n\n\n\n\n

Multiply Operator

\n\n

Note that you can use * as a form of multiplication involving lists but this doesn’t return a list containing each element multiplied by the right-hand operand. Rather, the returned list just contains the original list elements repeated by the number of times set by the right-hand operand. In the example below I get 2, 4, 6 repeated 4 times:

\n\n

def list = [2, 4, 6]\nprintln list * 4\n

\n\n\n\n

Spread-Dot Operator (Lists)

The *. operator calls an action (method) on each item in the list and returns a new list containing the results. In the example below I call the reverse() method on each list element:

\n\n

println(['carrot', 'cabbage', 'cauliflower']*.reverse())\n

\n\n\n\n

The spread operator mimics the collect() method - with the previous example being equivalent to the following:

\n\n

['carrot', 'cabbage', 'cauliflower'].collect{it?.reverse()}\n

\n\n\n\n

The spread operator makes the method call using the “Safe navigation Operator” (?.) to make sure that the list element isn’t null - refer to the Object Operators tutorial for more information. In the next example I include a null in the list and the returned list features the null:

\n\n

println(['carrot', 'cabbage', null, 'cauliflower']*.reverse())\n

\n\n\n\n

For maps I can’t use *. so need to use the collect() method.

\n\n

A Little Set Theory

\n\n

Writing this chapter got me thinking about set theory and how various aspects can be achieved in Groovy lists.

\n\n

Membership

\n\n

The in method gives us a membership check:

\n\n

assert 4 in [2, 4, 6, 8]\n

\n\n\n\n

Union

\n\n

The addition operator provides us with the ability to performs unions:

\n\n

assert [2, 4, 6, 8] + [1, 3, 5, 7] == [2, 4, 6, 8, 1, 3, 5, 7]\n

\n\n\n\n

Complements

\n\n

The subtraction operator (-) gives us set complement (difference):

\n\n

assert [2, 4, 6, 8] - [6, 8, 10] == [2, 4]\n

\n\n\n\n

Intersection

\n\n

The disjoint() method will return true if two lists don’t contain any intersecting elements:

\n\n

assert [2, 4, 6, 8].disjoint([1, 3, 5, 7]) == true\n

\n\n\n\n

If disjoint() returns false then some elements intersect.

\n\n

def list1 = [2, 4, 6, 8]\ndef list2 = [6, 8, 10]\n\nassert ([*list1, *list2] as Set) - (list1 - list2) - (list2 - list1) == [6, 8] a\\\ns Set\n

\n\n\n\n

Guava Sets Library

\n\n

All this got me thinking further and looking into Google’s Guava libraries - here’s some code that uses Guava to scratch my set itch:

\n\n

Sip some guava

\n\n

@Grab(group='com.google.guava', module='guava', version='18.0')\nimport static com.google.common.collect.Sets.*\n\ndef list1 = [2, 4, 6, 8] as Set\ndef list2 = [6, 8, 10] as Set\n\nprintln \"Intersection: \" << intersection(list1, list2)\nprintln \"Union: \" << union(list1, list2)\nprintln \"Difference (list1 - list2): \" << difference(list1, list2)\nprintln \"Difference (list2 - list1): \" << difference(list2, list1)\n\nprintln \"Cartesian product of list1 and list2\"\nfor (set in cartesianProduct(list1, list2)) {\n    println \" - $set\"\n}\n\nprintln \"Powersets of list1: \"\nfor (set in powerSet(list1)) {\n    println \" - $set\"\n}\n

\n\n\n\n

\n38. Object Operators

\n\n\n\n

It could be argued that all operators are object operators as nearly every variable or value in Groovy is an object. However, these operators are all about working with and checking on the object’s structure.

\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n

Object operators
Operator(s)	Type
`?.`	Safe Navigation Operator
`as`	Casting Operator
`is`	Identity Operator
\n`instanceof` `in`\n	Type Comparisons
`.@`	Field Operator
`.&`	Method Reference

\n\n\n\n

The Safe Navigation operator (?.) checks to make sure that a variable isn’t null before calling the requested method. Consider the following code:

\n\n

Hitting a null

\n\n

class Person{\n    def name\n}\n\ndef fred = new Person(name: 'Fred')\n\n//various statements\nfred = null\n//various statements\n\nprintln fred.name\n

\n\n\n\n

As fred somehow became null at some point in the code, that call to fred.name causes a nasty java.lang.NullPointerException (aka the NPE). This happens a lot as variables (in this case fred) can end up being null for a number of reasons, including:

\n\n

The variable never gets set in the first place - perhaps the initialisation failed but we didn’t catch it properly
A method returns null instead of an object instance
We get passed a parameter that has null value.

\n\n

In order to stop the NPE you’ll normally see developers using an if statement to check that the variable isn’t null before trying to call a method:

\n\n

Checking for null

\n\n

class Person{\n    def name\n}\n\ndef fred = new Person(name: 'Fred')\n\n//various statements\nfred = null\n//various statements\n\nif (fred) {\n    println fred.name\n}\n

\n\n\n\n\n\n

Groovy’s Safe Navigation operator saves some time and code. In the code below, Groovy checks that the fred variable isn’t null before trying to access the name property - giving us a compact piece of code: fred?.name.

\n\n

Safe navigation

\n\n

class Person{\n    def name\n}\n\ndef fred = new Person(name: 'Fred')\n\n//various statements\nfred = null\n//various statements\n\nprintln fred?.name\n

\n\n\n\n

You’ll see that “null” is displayed - this is because fred is null. Groovy doesn’t even try to access the name property.

\n\n

Casting Operator

\n\n

The Casting operator (as) changes the data type of a value or variable to the specified class. This is sometimes called “casting”, “type conversion” or “coercing”. You’ll have seen this in action when we created a Set:

\n\n

def nums = [1, 6, 3, 9, 3] as Set\n

\n\n\n\n\n\n

The as tells Groovy that you want to convert the item to be of the specified data type (class) - in the example above I use Set. The code below demonstrates a few more conversions:

\n\n

assert 3.14 as Integer == 3\nassert 101 as String == '101'\nassert true as String == 'true'\nassert '987' as Integer == 987\n

\n\n\n\n

You’ll note that the cast can be lossy - 3.14 as Integer caused the value to be truncated to 3. Not all values can be cast to all types and code such as 'hello, world' as Integer causes an exception.

\n\n

Identity Operator

\n\n

The Identity operator (is) determines if two variables are referencing the same object instance. This “operator” is really a method that you call by using obj1.is(obj2) to check if obj1 and obj2 reference the same instance.

\n\n

As we saw in the chapters on Equality Operators and Relational Operators, Groovy uses the == operator to determine if two objects are equivalent based on their state. Using == for this purpose is really useful and improves code readability but it means that the traditional Java use of == to determine if two objects reference the same instance needs a replacement in Groovy. The is method is that replacement.

\n\n

In the code below I describe a Person class and use a very helpful annotation (@groovy.transform.EqualsAndHashCode) so that Groovy sets up the approach to determining if two instances of Person are the same - such that == returns true. I’ve decided that all people will have a unique identifier and, provided two instances have the same identifier, they’re the same person. This means that all three variations (fred, freddie, frederick) of the person with the ID 345 are equal (==) to each other. However, by using is I can see that, whilst fred and freddie point to the same instance of Person, frederick points to a different instance.

\n\n

Can I see some identification?

\n\n

@groovy.transform.EqualsAndHashCode(includes=\"id\")\nclass Person{\n    def id\n    def name\n}\n\ndef fred = new Person(id: 345, name: 'Fred')\ndef freddie = fred\ndef frederick = new Person(id: 345, name: 'Frederick')\n\n//Check that they're all the same person\nassert fred == freddie\nassert fred == frederick\nassert freddie == frederick\n\n//Check which variable points to the same instance\nassert fred.is(freddie)\nassert ! fred.is(frederick)\n

\n\n\n\n

Type Comparison

\n\n

The Type Comparison operators (instanceof and in) is used to determine if a variable is an instance of the specified class.

\n\n

In this next example I check to make sure that fred is a Person:

\n\n

Type comparison

\n\n

class Person{\n    def name\n}\n\ndef fred = new Person(name: 'Fred')\n\nassert fred instanceof Person\nassert fred in Person\n

\n\n\n\n

Checking the variable’s type can be useful in dynamically typed languages such as Groovy as it lets us check before we call a property or method that may not be there:

\n\n

class Person{\n    def name\n}\n\ndef fred = new Person(name: 'Fred')\n\nif (fred instanceof Person) {\n    println fred?.name\n}\n

\n\n\n\n

In my Person example I’m not really using the full benefits of object-oriented programming that we can leverage in Groovy - primarily because we’re yet to get up to that. However, trust me when I say that class hierarchies and interfaces give us a handy way to build up a family tree of classes and that we can use instanceof or in to check if the object instance has a legacy that helps us achieve an outcome. For example, the Integer and Float classes are a subclass (child) of the Number class.

\n\n\n\n

In the example below I set up an add method that adds two numbers (handy!). Before I try to add those two numbers I use in to make sure they’re actually Numbers. If they aren’t, I throw an exception at you.

\n\n

def add(num1, num2) {\n    if (num1 in Number && num2 in Number) {\n        return num1 + num2\n    }\n    throw new IllegalArgumentException('Parameters must be Numbers')\n}\n\nassert add(1, 6) == 7\nassert add(3.14, 9.2) == 12.34\n\nadd('Rabbit', 'Flower')\n

\n\n\n\n\n\n

Field Operator and Method Reference

\n\n\n\n

The Field operator (.@) provides direct access to an object’s property (field) rather than using a getter/setter. Use this with a lot of caution or, even better, don’t use it at all.

\n\n

The Method Reference operator (.&) returns a reference to an object method. This can be handy when you’d like to use the method as a closure. This is a very useful feature so use it at will!

\n\n

In the example below I describe the Person class. When I then create an instance called example you’ll notice that:

\n\n

\nexample.name = 'Fred' causes setName() to be called
\nprintln example.name causes getName() to be called
\nexample.@name = 'Jane' and println example.@name both access the name property directly.
\ndef intro = example.&introduceSelf sets intro as a pointer (closure) to the introduceSelf method.\n
- Which is then called using intro()\n
\n

\n\n

Field operators and method references

\n\n

class Person {\n    def name\n\n    def setName(name) {\n        println 'You called setName()'\n        this.name = name\n    }\n\n    def getName() {\n        println 'You called getName()'\n        return this.name\n    }\n\n    def introduceSelf() {\n        println \"Hi, my name is ${this.name}\"\n    }\n}\n\ndef example = new Person()\n\n//example.name actually calls the getter or setter\nexample.name = 'Fred'\nprintln example.name\n\n//example.@name directly access the field\nexample.@name = 'Jane'\nprintln example.@name\n\n//intro holds the reference to the introduceSelf method\ndef intro = example.&introduceSelf\n\n//This next line calls introduceSelf()\nintro()\n

\n\n\n\n

\nIV Control Flow Statements

\n\n

\n39. Introduction

\n\n\n\n

Most code needs to reflect a decision-making process. A decision may be an either-or in which we process one set of statements rather than another. Another decision may be to run the same set of statements for a finite (or infinite) period.

\n\n

Groovy supports a range of control-flow statements:

\n\n

The conditional statements:\n
- \nif and if-else\n
- switch
- try-catch-finally
\n
The looping statements:\n
- for
- \nfor-each
- while
\n
The branching statements:\n
- break
- continue
- return
\n

\n\n

This section will describe the conditional and looping statements and discuss how and where the break and continue branching statements fit in.

\n\n

The try-catch-finally statement will be explored in the Exceptions section.

\n\n

The return statement will be explored in the Methods section and the Closures section.

\n\n

\n40. Blocks

\n\n\n\n\n

Groovy uses curly brackets {..} to enclose blocks of code. These are primarily used to group a set of statements within elements such as control flow, class, method and closure declarations. Blocks also let you “partition off” parts of code so that items such as variables aren’t visible to other parts of your code - referred to as “scope”.

\n\n

Groovy doesn’t allow the use of anonymous code block such as the one below:

\n\n

A sample block

\n\n

{\n    def count = 0\n    assert count == 0\n}\n

\n\n\n\n

You need to label the block provided above if you want to use it in Groovy code:

\n\n

A labelled block

\n\n

Block1:{\n    def count = 0\n    assert count == 0\n}\n

\n\n\n\n

This limitation is primarily due to the closure syntax - labelling the block ensures it isn’t confused with a closure.

\n\n

Blocks appearing within blocks are called “nested blocks”:

\n\n

A nested block

\n\n

Block1:{\n    def count = 0\n    assert count == 0\n    NestedBlock: {\n        assert count == 0\n    }\n}\n

\n\n\n\n

If the above code was a Groovy script the block structures really would be redundant “noise” - you’re not likely to see usage such as Block1:{..} very often. You’re more likely to see blocks used with control flow statements (such as if):

\n\n

if (true) {\n    //some code\n}\n

\n\n\n\n

… in class declarations:

\n\n

class Person {\n\n}\n

\n\n\n\n

… in method declarations:

\n\n

def doStuff() {\n\n}\n

\n\n\n\n

… in closure declarations

\n\n

{name ->\n    println \"Hello, $name\"\n}\n

\n\n\n\n

Variable Scope

\n\n

Variable Scope refers to the visibility of a variable from other blocks. A variable declared at the top level is visible to blocks nested within it. The reverse, however, is not true. This lets us declare variables within a block that is specific to that block (and any nested blocks) but doesn’t interfere with the rest of the program.

\n\n

In the example below, the code within Block1 can “see” the count variable so both asserts work:

\n\n

A sample block

\n\n

def count = 0\n\nBlock1: {\n    assert count == 0\n}\n\nassert count == 0\n

\n\n\n\n

The second assert will fail as count is not in scope in the main body of the script:

\n\n

Block1: {\n    def count = 0\n    assert count == 0\n}\n\nassert count == 0\n

\n\n\n\n

In the next example, count is visible to the nested bock (Block2):

\n\n

Block1:{\n    def count = 0\n\n    Block2:{\n        assert count == 0\n    }\n}\n

\n\n\n\n

What all of this means is that you need to keep an eye on where the variable can be “seen”. In the example below, the volume variable is visible (within scope) of the if block but the dbLevel variable is local to the if block.

\n\n

def volume = 11\n\nif (volume > 10) {\n    def dbLevel = 'extreme'\n    println \"A volume of $volume is $dbLevel\"\n    //more code\n}\n

\n\n\n\n

I repeatedly make a mistake in which I declare a variable within a try block but I need to use the variable later on. The code below is an example of my mistake - println myObj will never work as myObj is not visible at that level.

\n\n

try {\n    def myObj = new Object()\n} catch (any) {\n    //Do something to handle the exception\n}\n\nprintln myObj\n

\n\n\n\n

I’ve put the def myObj = new Object() into the try block as the instantiation may cause an exception. What I needed to do was separate the variable definition (def) from the creation of a new instance (instantiation):

\n\n

def myObj\n\ntry {\n    myObj = new Object()\n} catch (any) {\n    //Do something to handle the exception\n}\n\nprintln myObj\n

\n\n\n\n

\n41. The `if` Statement

\n\n\n\n

Few programs consist of a set of statements read one after another from top-to-bottom. At various points we need the code to evaluate one set of statements rather than another - depending on the current context in which the program is running. The if statement is key to directing which route to take.

\n\n

As an example, let’s say we have some code that displays the result of a division. It’s very important that we don’t try to divide a number by 0 as this causes an error. In the code below we use the if statement to check if the denominator is 0 before we perform the division:

\n\n

A quick if

\n\n

def numerator = 0\ndef denominator = 0\n\n// ... various statements\n\nif (denominator != 0) {\n    println numerator / denominator\n}\n

\n\n\n\n

if evaluates the conditional expression between the parentheses - (..) - and will only process the statement block if the conditional result is true.

\n\n

\n`if` - `else`\n

\n\n

An else section can be provided where you want to process statements when the conditional result is false.

\n\n

if - else

\n\n

def numerator = 0\ndef denominator = 0\n\n// ... various statements\n\nif (denominator != 0) {\n    println numerator / denominator\n} else {\n    println 'I refuse to divide by zero'\n}\n

\n\n\n\n

\n`if` - `else if` - `else`\n

\n\n

if and else let you deal with situations where you have two possible outcomes but sometimes you might have a few conditions that you want to check for:

\n\n

if - else if - else

\n\n

def game = 'tennis'\n\nif (game == 'chess') {\n    println 'I like to play chess'\n} else {\n    if (game == 'tennis') {\n       println 'I can play tennis if you want'\n    } else {\n        println \"Sorry, I don't know how to play $game\"\n    }\n}\n

\n\n\n\n

The code above places another if check within the else block and checks if the player is asking for a different game (“tennis”). This looks (sort of) clean but start to picture a larger set of checks and the code gets confusing. Instead of nesting the second if within the else block, Groovy lets you use else if:

\n\n

def game = 'tennis'\n\nif (game == 'chess') {\n    println 'I like to play chess'\n} else if (game == 'tennis') {\n    println 'I can play tennis if you want - just let me warm up'\n} else if (game == 'golf') {\n    println 'I can play golf if you want but I get very angry'\n} else {\n    println \"Sorry, I don't know how to play $game\"\n}\n

\n\n\n\n

The code above tidies up the nesting by allowing the second if to be part of the else block. Essentially you can provide a long series of checks in a single if-else if set and Groovy will evaluate each until one resolves to true. You can optionally provide an else block at the end to ensure that can all other outcomes (defined or otherwise) be dealt with.

\n\n\n\n

It’s important to note that once an if evaluates to true, no other if expressions are evaluated. It’s a case of the first positive match wins. In the code below, the conditional (game=='chess' || game == 'tennis') is redundant because an earlier condition would have returned true ((game == 'chess'))

\n\n

if (game == 'chess') {\n    println 'I like to play chess'\n} else if (game == 'tennis') {\n    println 'I can play tennis if you want'\n} else if (game=='chess' || game == 'tennis') {\n    println 'Can you really play both of these at once?'\n} else {\n    println \"Sorry, I don't know how to play $game\"\n}\n

\n\n\n\n

That last point is also important as Groovy will also not evaluate any expressions used in further if expressions. In the example below, --i is never evaluated as the first if expression resolves to true:

\n\n

def i = 10\n\nif (++i > 10) {\n\t//do something\n} else if (--i < 10) {\n\t//do something\n}\n\nassert i == 11\n

\n\n\n\n

\n42. The `switch` Statement

\n\n\n\n

There are times when the number of possibilities are larger than a readable if-else-if statement can handle. There are also times where we want to execute a specific set of statements but then “fall through” to others. It’s in these places that the switch statement comes in handy.

\n\n

Let’s take a look at an example:

\n\n

Switch

\n\n

switch (game) {\n    case 'chess':\n        println 'I like to play chess'\n        break\n    case 'go':\n        println 'I can play go if you want'\n        break\n    case 'ludo':\n        println 'I can play ludo if you want'\n        break\n    default:\n        println \"Sorry, I don't know how to play $game\"\n}\n

\n\n\n\n

The switch statement evaluates an expression - in the example above it’s the value of a variable (game) but it could be the result of an operation. This is called the switch value.

\n\n

The rest of the switch block is broken up into cases and (optionally) a default. Each case is assessed against the switch value and the first match is selected. Each case is declared:

\n\n

prefixed by the keyword case, followed by\n
- an expression, and lastly,\n
  - a colon :\n
  \n
\n

\n\n

The case expression can be a more complex expression but in our example above I’ve used a string value (e.g. chess). If the value of game was 'ludo' then the statements under case 'ludo': are evaluated.

\n\n

The break statement indicates the end of the set of statements for the case and signals that the switch statement has completed. In the example above I’ve used break for every case but this isn’t required. If break isn’t provided, execution of the switch is said to “fall through” to the next set of statements. Essentially, Groovy will keep evaluating expressions until either a break is provided or the end of the switch block is reached.

\n\n

Falling through can be useful if you want to perform the same set of statements for more than one case. The example snippet below provides an example of such a case (pun intended):

\n\n

case 'snowboarding':\ncase 'snowball fight':\n    println 'But it\\'s summer!'\n    break\n

\n\n\n\n

Here’s another example of falling through:

\n\n

Falling through

\n\n

def score = 2\n\nprintln 'You win: '\n\nswitch (score) {\n    case 3:\n        println '- gift voucher'\n     case 2:\n        println '- toy'\n    case 1:\n        println '- stamp'\n    default:\n        println '- certificate'\n}\n

\n\n\n\n

In the code above the prizes are accumulated depending on your score and a score of 2 sees you win a toy, stamp and certificate - lucky you! Our default ensures that every child wins a prize, regardless of their score.

\n\n\n\n

The Versatile Groovy `switch`\n

\n\n

The Groovy switch statement is much more powerful than Java’s and can work across all data types.

\n\n

\n
In Java switch is limited to the primitive types (and their object wrappers), Strings and Enums and the case expression is limited to a value (not an operation).
\n

\n\n

Groovy achieves through the use of the isCase method defined for the Object class and overloaded by subclasses such as Pattern. Essentially, the switch value is passed to the case instance. In the example below, 10.isCase(score) would be called:

\n\n

switch (score) {\n\tcase 10:\n\t\t//etc\n}\n

\n\n\n\n

If this all sounds a little foreign, don’t worry, just check out the following sections to see how versatile the switch statement can be.

\n\n

Using Ranges

\n\n

Ranges can be used in the case and is selected when the switch value is in the range.

\n\n

Let’s play some blackjack:

\n\n

Switch with ranges

\n\n

switch (hand) {\n    case 1..16:\n        println 'HIT'\n        break\n    case 17..21:\n        println 'STAND'\n        break\n    default:\n        println 'BUST'\n        break\n}\n

\n\n\n\n

Using Regular Expressions

\n\n

Groovy extends the Java regular expression Pattern class to provide for their use in switch statements. This can be really handy if you want to test for a number of patterns.

\n\n

In the example below I set up a list of URI’s¹ and assess them against regular expressions based on various URI formats.

\n\n\n\n

Switch with RegEx

\n\n

def location = ['urn:isbn:0451450523',\n                'http://en.wikipedia.org/wiki/Uniform_resource_locator',\n                'HTTPS://secure.example.com/',\n                'mailto:duncan@example.com',\n                'fax:53454567567']\n\nlocation.each {\n    switch( it.toLowerCase() ) {\n        case ~/^urn:.*/ :\n            print 'This looks like a URN'\n            break\n        case ~/^https?:.*/ :\n            print 'This looks like a HTTP(S) URL'\n            break\n        case ~/^mailto:.*/ :\n            print 'This looks like an email address'\n            break\n        default:\n            print 'Not sure what this is'\n    }\n    println \" ($it)\"\n}\n

\n\n\n\n

Using Class Checks

\n\n

Groovy’s switch can use a data type (Class) for comparison. Essentially, the switch will use the instanceof operator to compare the switch value with a class name provided in the case. In the example below I iterate through a list containing elements of various types. I use the switch statement to then determine the type of each list item:

\n\n

Switch with class checks

\n\n

def objList = [ 10,\n                'hello',\n                [1, 5, 8],\n                [name: 'Dave'],\n                ~/\\n/\n              ]\n\nfor (item in objList) {\n    switch (item) {\n        case String:\n            println 'You gave me a string'\n            break\n        case Number:\n            println 'You gave me a number'\n            break\n        case List:\n            println 'You gave me a list'\n            break\n        case Map:\n            println 'You gave me a map'\n            break\n        default:\n            println \"Sorry, I can't handle instances of ${item.class}\"\n    }\n}\n

\n\n\n\n

See http://en.wikipedia.org/wiki/Uniform_resource_identifier↩\n

\n\n\n

\n43. The `for` Loop

\n\n\n\n

The for loop will repeat a block of code whilst its condition is true:

\n\n

for

\n\n

for (<condition>) {\n\t//statements\n}\n

\n\n\n\n

The `for-in` Loop

\n\n

The for-each loop basically says “for each element is this collection, perform the following”:

\n\n

for-in

\n\n

for (<var> in <iterator>) {\n\t//statements\n}\n

\n\n\n\n\n\n

In the Groovy for-in loop we have a variable (var) provided as the next item in the iterator¹. In most cases this is a collection of objects such as a list or map.

\n\n

You can’t change the iterator within a loop - it’d just be too confusing! That means code such as the following causes an exception and won’t run:

\n\n

def scores = [4, 8, 2]\n\nfor (i in scores) {\n    scores << i**2\n}\n

\n\n\n\n

Using a range

Consider a variable called countdown to hold a range:

\n\n

def countdown = (10..0)\n

\n\n\n\n

By itself, countdown probably doesn’t seem too useful but let’s look at a for loop:

\n\n

def countdown = (10..0)\n\nfor (i in countdown) {\n    println \"Launch in T-$i seconds\"\n}\n\nprintln 'Blast off!'\n

\n\n\n\n

So let’s break down for (i in countdown) {:

\n\n

The (...) parentheses holds the condition
The variable i will hold the next element in countdown\n
- You can name this as you would any other variable
\n
The element to the right of the in reserved word is the variable being iterated (looped) over
\n{ starts the loop body\n
- and its matching } closes it
\n

\n\n\n\n

If you run this code in groovyConsole you’ll see our launch sequence displayed.

\n\n

To make our code even more compact (yet readable), we can use the literal value for the range (10..0) in our for condition:

\n\n

for (i in 10..0) {\n    println \"Launch in T-$i seconds\"\n}\nprintln 'Blast off!'\n

\n\n\n\n

Lists

\n\n

Looping through the items in a list is quite straight forward now you’ve seen the range example:

\n\n

Looping through a list

\n\n

def planets = [\n    'Mercury',\n    'Venus',\n    'Earth',\n    'Mars'\n]\n\nfor (planet in planets) {\n    println planet\n}\n

\n\n\n\n\n\n

Maps

\n\n

Iterating through maps is much the same as we did for lists but the iteration variable consists of the key and the value for that map item. The next code segment will just display the value of each map item:

\n\n

def domains = [\n    'com': 'Corporate sites',\n    'org': 'Non-commercial sites',\n    'mil': 'Military sites'\n]\n\nfor (site in domains) {\n    println site\n}\n

\n\n\n\n

The code above will display a set of lines such as com=Corporate sites - illustrating that site contains a key/value pair.

\n\n

Instead of printing out the iteration variable (site) we can be a little smarter and access the key (site.key) and value (site.value) individually:

\n\n

def domains = [\n    'com': 'Corporate sites',\n    'org': 'Non-commercial sites',\n    'mil': 'Military sites'\n]\n\nfor (site in domains) {\n    println site.key << ': ' << site.value\n}\n

\n\n\n\n

The Java for-each

\n\n

Groovy supports Java’s version of a for-each loop:

\n\n

for (<Type> <var>: <iterator>) {\n\t//statements\n}\n

\n\n\n\n

Unlike Groovy’s for-in loop, the Java version:

\n\n

uses : instead if in\n
Requires you to declare a data type for the iteration variable\n
- Which makes lists consisting of elements with different data types a little more tricky.
\n

\n\n

Re-writing the previous planets example in the Java for-each style we’d see the following:

\n\n

def planets = [\n    'Mercury',\n    'Venus',\n    'Earth',\n    'Mars'\n]\n\nfor (String planet: planets) {\n    println planet\n}\n

\n\n\n\n\n\n

The Java version has no real benefit over the Groovy approach so I’d stick with the Groovy for (<var> in <iterator>). The Groovy approach also makes for easier iteration over maps.

\n\n

If you really want to set a data type for your iteration variable you can still be Groovy about it:

\n\n

def planets = [\n    'Mercury',\n    'Venus',\n    'Earth',\n    'Mars',\n]\n\nfor (String planet in planets) {\n    println planet\n}\n

\n\n\n\n

A C-style `for` Loop

Java (and Groovy) both offer the for loop syntax found in the C programming language:

\n\n

C-style for

\n\n

for (<init variable>; <condition>; <update expression>) {\n\t//statements\n}\n

\n\n\n\n

\n<init variable> initialises the loop variable before the first iteration
\n<condition> sets the condition to be met for the iteration to commence
\n<update expression> is evaluated after each iteration

\n\n

This next example does the same as for (i in (10..1)) but is more verbose:

\n\n

for (i = 10; i >= 0; i--) {\n    println i\n}\n

\n\n\n\n

So what’s happening in (i = 10; i >= 0; i--)?

\n\n

\ni = 10 initialises the loop variable i to 10\n
\ni >= 0 is the conditional that says “keep looping until i is no longer greater than or equal to 10”
\ni-- is evaluated after each iteration - i is decremented by 1.

\n\n

The <update expression> can be a more complex expression:

\n\n

for (i = 0; i <= 20; i += 2) {\n    println i\n}\n

\n\n\n\n

Infinite loops

The C-style for loop can let you set up infinite loops:

\n\n

An infinite loop

\n\n

for (;;) {\n\n}\n

\n\n\n\n

These are often used in event-based systems. Essentially, the program will enter a loop and await incoming events such as a mouse-click. It’s a very interesting aspect to coding but outside the scope of these tutorials.

\n\n\n\n

The C-style loop doesn’t protect you from altering the thing you’re working on and, perhaps inadvertently, creating an infinite loop. That means that the code below needs the safety brake provided by (&& i < 20) as the loop keeps altering the size of scores. If you take out && i < 20 and run the code below it won’t stop unless you interrupt it or you run out of system resources:

\n\n

def scores = [4, 8, 2]\n\nfor (i = 0; i < scores.size && i < 20; i++) {\n    println scores[i]\n    scores << scores[i]**2\n}\n

\n\n\n\n

Many Groovy classes implement a feature (interface) named Iterable and these let you easily iterate over a collection of items. Lists and Maps are both iterable, making it very easy to loop through their contents.↩\n

\n\n\n

\n44. The `while` loop

\n\n\n\n

The while loop will repeat a block of code whilst its condition is true:

\n\n

While

\n\n

while (<condition>) {\n\t//statements\n}\n

\n\n\n\n\n\n

while loops feature the following:

\n\n

\n<condition> can be a value or expression - the loop will only iterate if <condition> is true.
The while loop syntax does not manage an iterator variable - you must do this yourself\n
- It’s very easy to create an infinite while loop if you’re not paying attention
\n

\n\n

The example below uses a common approach for while loops and sets a flag to indicate when the desired state has been reached and the loop can stop:

\n\n

def flag = false\ndef num = 0\n\nwhile (!flag) {\n    num++\n    if (num**2 == 64) {\n        flag = true\n    }\n}\n\nprintln \"The square root of 64 is $num\"\n

\n\n\n\n

The code above will increment num by 1 each iteration and test to see if num^2 is equal to 64. Once the correct num is reached, flag is change to true and the while condition now resolves to false - indicating that the while loop should run the next iteration.

\n\n

The while loop can also be used to create an infinite loop: while(true) {}

\n\n

There is no `do...while` loop

\n\n

Unlike Java, Groovy does not have a do...while loop¹. Don’t be sad.

\n\n

\nA ticket has been lodged to request one.↩\n

\n\n\n

\n45. Branching statements

\n\n\n\n

Groovy has three branching statements:

\n\n

break
continue
return

\n\n

break

\n\n

We first came across the use of break in the switch statement - it’s used to indicate the end of the set of statements for the case and signals that the switch statement has completed.

\n\n

The break reserved word is also used to exit out of a loop - even if there are more iterations possible. In the code below I iterate through the list until I reach the value 'Earth' and then break out of the loop:

\n\n

Break

\n\n

def planets = [\n    'Mercury',\n    'Venus',\n    'Earth',\n    'Mars'\n]\n\nfor (planet in planets) {\n    println planet\n    if (planet == 'Earth') {\n        break\n    }\n}\n

\n\n\n\n

When we looked at the while loop I gave an example of setting a flag variable and checking that as the loop’s condition. This could have been refined using break and not using flag at all:

\n\n

def num = 0\n\nwhile (true) {\n    num++\n    if (num**2 == 64) {\n        break\n    }\n}\n\nprintln \"The square root of 64 is $num\"\n

\n\n\n\n\n\n

I’ll refine that while loop just a little further:

\n\n

def num = 0\n\nwhile (++num) {\n    if (num**2 == 64) {\n        break\n    }\n}\n\nprintln \"The square root of 64 is $num\"\n

\n\n\n\n

As Groovy resolves a number other than 0 to be true, ++num will allow the loop to commence and we still rely on break to get us out of the loop.

\n\n

continue

The continue reserved word will cause the next iteration of the loop - ignoring anything within the rest of the current iteration. In the loop below I use continue to ignore 'Earth'.

\n\n

Continue

\n\n

def planets = [\n    'Mercury',\n    'Venus',\n    'Earth',\n    'Mars'\n]\n\nfor (planet in planets) {\n    if (planet == 'Earth') {\n        continue\n    }\n    println planet\n}\n

\n\n\n\n

Labelled branching

\n\n

If you have a secret desire to create spaghetti code that quickly becomes unreadable then labels are for you!

\n\n

Labels are used when you have nested loops - a loop within a loop. Both break and continue can be given a label that directs the program to another nesting level. In the example below I label the first loop flowerlist and, when I get to the colour 'Green' in the inner loop, my continue is directed not at the inner loop but at the outer one labelled flowerlist - this is called a “labelled continue”:

\n\n

Using labels

\n\n

def colours = ['Red', 'Orange', 'Yellow', 'Green', 'Blue', 'Indigo', 'Violet']\n\ndef flowers = ['daisy', 'rose', 'tulip']\n\nflowerlist:\n    for (flower in flowers) {\n        for (colour in colours) {\n            if (colour == 'Green') {\n                continue flowerlist\n            }\n            println \"$colour $flower\"\n        }\n    }\n

\n\n\n\n

As you can see, the label consists of a name, followed by a colon (:) that appears above the loop being labelled. The code above will display the following:

\n\n

Red daisy\nOrange daisy\nYellow daisy\nRed rose\nOrange rose\nYellow rose\nRed tulip\nOrange tulip\nYellow tulip\n

\n\n\n\n\n\n

A labelled break works much the same way and defers control back to the loop designated by the label.

\n\n

There are times when labels are useful but really think about what you need to do before resorting to them. For example, using a break in the code above would have done the job:

\n\n

def colours = ['Red', 'Orange', 'Yellow', 'Green', 'Blue', 'Indigo', 'Violet']\n\ndef flowers = ['daisy', 'rose', 'tulip']\n\nfor (flower in flowers) {\n    for (colour in colours) {\n        if (colour == 'Green') {\n            break\n        }\n        println \"$colour $flower\"\n    }\n}\n

\n\n\n\n

return

\n\n

The return statement is used to hand control back to the caller¹. In most cases, return is used in a method or closure to return a value. In the most basic usage, the keyword return just appears on a line by itself:

\n\n

//some code\nreturn\n

\n\n\n\n

Any code that appears below the return is unreachable and is never evaluated:

\n\n

//some code...\nreturn\n//unreachable code...\n

\n\n\n\n

Return can be provided a value and this is returned to the caller:

\n\n

//some code\nreturn 3.14\n

\n\n\n\n

You can use an expression in the return statement and the result is returned:

\n\n

//some code\nreturn circumference / diameter\n

\n\n\n\n

Using return within the body of a script² will cause it to exit as the command-line/terminal is the caller. When exiting you can choose to return a value - usually 0 if the script succeeds, or an error number if it fails.

\n\n

The caller is the section of code that called the method/closure.↩\n
By body I mean the main part of the script.↩\n

\n\n\n

\nV Exceptions

\n\n

\n46. Introduction

\n\n\n\n

Groovy takes on Java’s approach to raising, handling and reporting errors and exceptions:

\n\n

\nErrors are serious problems that usually cause an application to halt (“crash”). In most cases you won’t handle these - they’ll happen and the program will fall over.
\nExceptions are less serious and applications, with good exception handling set up, may be able to keep going.

\n\n

At the heart of this model is the java.lang.Throwable¹ class. Exceptions and Errors are are two sides to the Throwable family tree:

\n\n

\njava.lang.Exception is the superclass (parent) of all exceptions
\njava.lang.Error is the superclass (parent) of all errors

\n\n

When writing Groovy applications you’re likely to interact with exceptions in the following ways:

\n\n

Catching exceptions (using try-catch) thrown by various classes, be they written by you, part of the Java/Groovy libraries or from a third-party.
Throwing your own exceptions using (throw) to signal that something’s gone wrong in your code.
Being surprised and frustrated when exceptions “just happen”

\n\n

Your goal should be to use defensive coding and testing that seeks to handle what you think is necessary but be prepared for issues to arise and use facilities such as logging to help you determine the root-cause.

\n\n

Check out the JavaDoc for Throwable ↩\n

\n\n\n

\n47. Common Exceptions

\n\n\n\n

In the following sections we’ll throw some errors and exceptions (on purpose) so that we can check out some of the most common children of java.lang.Throwable you’re likely to see. As a bonus we’ll also discover a few approaches to avoiding them.

\n\n

java.lang.NullPointerException

\n\n

The good old NullPointerException (NPE) will haunt your debugging sessions for years to come. Basically it means that you’ve tried to call a method or access a property on an object that isn’t there (i.e. the variable is null). Let’s cause an NPE - it’s easy:

\n\n

def tmp = null\ntmp.class\n

\n\n\n\n

To avoid these, check for null by:

\n\n

Using the Safe Navigation operator (tmp?.class)
Checking the variable with an if statement before trying to access it

\n\n

java.lang.AssertionError

\n\n

This is an Error, not an Exception and occurs when your assert expression evaluates to false:

\n\n

assert true == false : 'This cannot be'\n

\n\n\n\n\n\n

When your Groovy assertions fail you actually seem to receive a org.codehaus.groovy.runtime.powerassert.PowerAssertionError - a subclass of java.lang.AssertionError.

\n\n

The assert statement is usually seen in tests and small scripts. It’s usually better to signal an incorrect state/situation using throws - more about them in a later chapter.

\n\n

java.lang.NumberFormatException

\n\n

Groovy can be used as a dynamic language so there are times where you may try to do something to a value that just can’t be done. Trying to convince something that it can be a number when it really can’t be will give you a NumberFormatException:

\n\n

'Kitten' as Integer\n

\n\n\n\n

If you really need a variable to be a specific type you could use the class check feature of the switch statement. In the code below I check if value is of a type within the Number family tree before I try to convert it to an Integer. If it isn’t, I could throw and exception or handle it in some other way:

\n\n

def value = 'kitten'\n\nswitch (value) {\n    case Number:\n        value = value as Integer\n        break;\n    default:\n        println 'I should throw an exception'\n}\n

\n\n\n\n

groovy.lang.MissingPropertyException

\n\n

This exception happens when you try to access an object’s property but it doesn’t have that property. In the example below, my Person class doesn’t have a name property:

\n\n

class Person {}\ndef jim = new Person()\njim.name\n

\n\n\n\n

Using try-catch around this sort of exception can let you duck type - an approach that uses an object’s properties and methods to determine if something is possible.

\n\n

I reckon that the hasProperty() method available on all Groovy objects is a cleaner approach than the try-catch option. We can check the object has the property before trying to use it and without causing an exception:

\n\n

class Person {}\ndef jim = new Person()\n\nif (jim.hasProperty('name')) {\n    jim.name\n}\n

\n\n\n\n

groovy.lang.MissingMethodException

\n\n

This exception appears when you call a method on an object that doesn’t support the method. The lack of a getName() method on the Person class will cause an exception for poor old jim:

\n\n

class Person {}\ndef jim = new Person()\njim.getName()\n

\n\n\n\n

There’s no hasMethod() method - it’s called respondsTo():

\n\n

class Person {}\ndef jim = new Person()\n\nif (jim.respondsTo('getName')) {\n    jim.getName()\n}\n

\n\n\n\n

The respondsTo() method just checks if the method exists but we may want to be certain that the methods exists and has the parameter list we’re after. To achieve this we need to call respondsTo() with a second parameter, a list of the method argument types we expect - respondsTo(String name, Object[] argTypes).

\n\n

java.lang.IndexOutOfBoundsException

\n\n

These appear when you attempt to get() an index from a list that isn’t there. The code below attempts to get the 5th element from a 3-element list:

\n\n

def list = [0, 1, 2]\nprintln list.get(5)\n

\n\n\n\n

Note that if we’d written that code in a slightly different way, we’d get null returned rather than an exception raised:

\n\n

def list = [0, 1, 2]\nprintln list[5]\n

\n\n\n\n

Checking list.size() (or the length property) before trying to access is another option:

\n\n

def list = [0, 1, 2]\n\nif (list.size() >= 5) {\n    println list.get(5)\n}\n

\n\n\n\n

Of course the for-in loop will iterate through the list and not try to give you an element that isn’t there.

\n\n\n\n

def list = [0, 1, 2]\n\nfor (item in list) {\n    println item\n}\n

\n\n\n\n

java.lang.ArrayIndexOutOfBoundsException

\n\n

If you just had to use an array (instead of a list) then you’ll get an ArrayIndexOutOfBoundsException if you attempt to use an array index that isn’t there:

\n\n

Integer[] nums = [0, 1, 2]\nnums[5]\n

\n\n\n\n

We can use the length property to make sure we don’t try to access an element that isn’t there:

\n\n

Integer[] nums = [0, 1, 2]\n\nif (nums.length >= 5) {\n    nums[5]\n}\n

\n\n\n\n

The for-in loop is also handy for staying within the bounds:

\n\n

Integer[] nums = [0, 1, 2]\n\nfor (item in nums) {\n    println item\n}\n

\n\n\n\n

\n48. Anatomy of an Exception

\n\n\n\n

Throwable and all of its descendants provide a number of useful methods. Let’s start off with a very basic try-catch block so that we can then dissect the NullPointerException:

\n\n

What a catch

\n\n

try {\n    def person = null\n    person.getName()\n} catch (any) {\n    println \"Exception received: ${any.class.name}\"\n    println()\n    println \"getMessage() returns: ${any.getMessage()}\"\n    println()\n    println \"getCause() returns: ${any.getCause()}\"\n    println()\n    println 'getStackTrace() returned:'\n    for (item in any.getStackTrace()) {\n        println \"${item.getFileName()}\\t${item.getLineNumber()}\\t${item.getClass\\\nName()}\\t${item.getMethodName()}\\t${item.isNativeMethod()}\"\n    }\n}\n

\n\n\n\n

any.class.name: Tells us the type of exception that was raised; We get: java.lang.NullPointerException\n
getMessage(): Returns the message that was set by the thrower of the exception; We get: Cannot invoke method getName() on null object\n
getCause(): This isn’t always set but can be handy to know. Essentially this is set if the exception is “relaying” another exception.; We get: null\n
for (item in any.getStackTrace()) {..}: The getStackTrace() method returns an array of java.lang.StackTraceElement. Each StackTraceElement can then be further dissected to see what was happening when the exception occurred.; In my example I output a tab separated row for each StackTraceElement - the methods that I call should be reasonably self-explanatory but you can always check the Java API for more information.; To just dump out the stack trace I could have just used printStackTrace()\n

\n\n

\n49. Try-Catch-Finally

\n\n\n\n

The try-catch-finally statement can have three forms:

\n\n

try-catch
try-catch-finally
try-finally

\n\n

Groovy doesn’t support the try-with-resources syntax available in Java. Groovy’s closure infrastructure often takes care of closing resources for you (you may not even need a finally block).

\n\n

Scope

Before getting into the specific syntax it’s important to point out that the try statement presents a block with its own scope. This means that variables declared within the try block can’t been seen outside the block. In the example below the assert fails not because score doesn’t equal 12 but because the score variable is out-of-scope:

\n\n

try {\n    def score = 12\n} catch (any) {\n\n}\n\nassert score == 12\n

\n\n\n\n

In fact, the score variable won’t be visible to the catch block or a finally block. If you do need to access score outside of the try block then you should declare it before the try:

\n\n

def score\ntry {\n    score = 12\n} catch (any) {\n\n}\n\nassert score == 12\n

\n\n\n\n

try-catch

The basic format of try-catch is as follows:

\n\n

try-catch

\n\n

try {\n\t//statements...\n} catch (<Exception type> <var>) {\n\t//statements...\n}\n

\n\n\n\n

If an exception occurs within the try block:

\n\n

The catch variable (var) is set to the exception instance
If Exception type is provided (this is optional) then the catch block will only be activated if the exception is of that type.

\n\n

In the following example I generate an exception on purpose by dividing 10 by 0. The catch block is set up to catch any exception raised:

\n\n

try {\n    10 / 0\n} catch (any) {\n    println any.message\n    any.printStackTrace()\n}\n

\n\n\n\n

As we saw in an earlier chapter, exceptions in Groovy are objects - they have fields and methods, allowing me to display the message within the exception as well as display the stack trace.

\n\n\n\n

An Exception type can be provided for a catch block. In the example below I only catch an ArithmeticException - any other type of exception is raised up to the caller:

\n\n

try {\n    10 / 0\n} catch (ArithmeticException e) {\n    println 'I just caught an ArithmeticException'\n}\n

\n\n\n\n

A try-catch statement can consist of multiple catch blocks, each targeting specific exceptions. In this next example I explicitly catch ArithmeticException and have a default catch to pick up any other exception raised:

\n\n

try {\n    10 / 0\n} catch (ArithmeticException e) {\n    println 'I just caught an ArithmeticException'\n} catch (any) {\n    println 'What just happened?'\n}\n

\n\n\n\n

In this next example I explicitly catch IllegalStateException and ArithmeticException and have a default catch to pick up any other exception raised:

\n\n

try {\n    10 / 0\n} catch (IllegalStateException e) {\n    println 'I just caught an IllegalStateException'\n} catch (ArithmeticException e) {\n    println 'I just caught an ArithmeticException'\n} catch (any) {\n    println 'What just happened?'\n}\n

\n\n\n\n\n\n

If we wanted to handle a number of exception types (sometimes called a multicatch) in the same manner, the | operator can be used within the same catch to provide a separator for the exception types:

\n\n

try {\n    10 / 0\n} catch (IllegalStateException | ArithmeticException e) {\n    println 'I just caught an exception I want to handle'\n} catch (any) {\n    println 'What just happened?'\n}\n

\n\n\n\n

The last catch block (catch (any)) is a very useful one to reflect on when considering how you deal with exceptions. By providing a catch block you are flagging an intent to actually do something useful with an exception. If you don’t actually intend to add any value to the situation then I’d suggest not catching the exception. That way it will pass up the chain to the calling code (which may chose to actually handle the exception). The buck stops at the top-level code (e.g. the script) and, without explicit handling, the exception will be displayed and the program halted.

\n\n

My preference is to use try-finally if I just want to tidy up resources (such as files) if an exception occurs - that way the exception will pass up to the caller but I don’t get in the way. In most cases I use the explicit form of catch and indicate which Exception type I am prepared to handle.

\n\n

try-catch-finally

The try-catch statement can have an optional finally block. This is run regardless of if an exception is raised. The finally block doesn’t receive any incoming parameter and can appear no more than once per try:

\n\n

try-catch-finally

\n\n

try {\n\t//statements...\n} catch (<Exception type> <var>) {\n\t//statements...\n} finally {\n\t//statements\n}\n

\n\n\n\n

In the code below, the println in the finally block will run regardless of whether an exception was raised or the try block completed successfully:

\n\n

try {\n    10 / 0\n} catch (any) {\n    println any.message\n} finally {\n    println 'I think we survived'\n}\n

\n\n\n\n

But why use finally? Exceptions are used in a large number of places, including:

\n\n

Failure to read/write a file
Failure to access a database
Trying to access null\n

\n\n

The finally block comes in handy when you need to tidy up resources before either completing the try block or losing control to an exception. You’ll most commonly see finally used to close files, disconnect from databases or return the system to a state in which it can continue.

\n\n

try-finally

The third form of the try statement doesn’t provide a catch block:

\n\n

try-finally

\n\n

try {\n\t//statements...\n} finally {\n\t//statements\n}\n

\n\n\n\n

Essentially we’re indicating that any exceptions will just be raised up to the caller but we need to tidy up some resources before losing control:

\n\n

try {\n    10 / 0\n} finally {\n    println 'Finally block has been evaluated'\n}\n

\n\n\n\n\n\n

\n50. How Much Should We try?

\n\n\n\n

Whilst you could wrap an entire script/method/closure in a huge try statement this will quickly get confusing - imagine how many catch blocks you’ll need at the end of a 150-line script! Yes, you can catch (any) but you’d really have no clue what caused the exception.

\n\n

Take the following example:

\n\n

try {\n    methodOne()\n    methodTwo()\n    //148 more lines of code :)\n} catch (MethodOneException e) {\n\n} catch (MethodTwoException e) {\n\n}\n

\n\n\n\n

I tend to “localise” my try blocks so that they deal more specifically with the exception arising from a specific method call:

\n\n

try {\n    methodOne()\n} catch (MethodOneException e) {\n\n}\n\ntry {\n    methodTwo()\n} catch (MethodTwoException e) {\n\n}\n

\n\n\n\n

Although that last example results in more code I suggest it’s more useful as it helps localise the exception. In the first example I could end up catching a MethodTwoException from my call to methodOne - probably not what I really intended. If both methods throw the same exception type then localising really helps as I’ll know which method threw the exception.

\n\n

Additionally, if you go with the rule that you’re only catching exceptions you’re prepared to actually do something with, a lot of your code may not be wrapped with a try statement at all!

\n\n

\n51. Causing an Exception

\n\n\n\n

The throw statement will cause an exception to be thrown. You’ll use this inside your own code to either throw an exception type already provided by Java or Groovy or to throw an exception type that you have developed. Remembering that exceptions are classes, you can create your own subclass of Exception for your own project. Let’s take a small step back for now and see how we throw an exception.

\n\n

Often, new is used within a throw statement to initialise a new exception instance. The example below will throw a new instance of the IllegalStateException. As part of creating the new exception instance I pass it a message to help inform the user as to why they’re getting an exception:

\n\n

Throwing an exception

\n\n

def numerator = 10\ndef denominator = -1\n\ntry {\n\tif (denominator < 0) {\n\t\tthrow new IllegalStateException('I haven\\'t learnt how to divide negative numb\\\ners')\n\t} else {\n\t\treturn numerator / denominator\n\t}\n} catch (any) {\n\tprintln \"${any.message} (${any.class.name})\"\n}\n

\n\n\n\n

You can use new to create a new instance of an exception but this won’t cause the exception to be thrown - you’ll need to throw it. The long-form version of the previous example would appear as:

\n\n

def ise = new IllegalStateException('I haven\\'t learnt how to divide negative nu\\\nmbers')\nthrow ise\n

\n\n\n\n\n\n

In the code above I throw an exception (IllegalStateException) to indicate a limitation in my program. As before, the catch will receive the thrown exception but this time it could be either the IllegalStateException or the ArithmeticException:

\n\n

Catching different exceptions

\n\n

def numerator = 10\ndef denominator = -1\n\ntry {\n    if (denominator < 0) {\n        throw new IllegalStateException('I haven\\'t learnt how to divide negativ\\\ne numbers')\n    } else {\n        return numerator / denominator\n    }\n} catch (IllegalStateException e) {\n    println 'I just caught an IllegalStateException'\n} catch (ArithmeticException e) {\n    println 'I just caught an ArithmeticException'\n} catch (any) {\n    println 'What just happened?'\n}\n

\n\n\n\n

The code above makes a little more sense than my earlier example as denominator may be 0 or a negative number and we are concerned with both possibilities. As mentioned earlier, we can use | to handle more than one exception type within the same catch block:

\n\n

Grouping catches

\n\n

def numerator = 10\ndef denominator = -1\n\ntry {\n    if (denominator < 0) {\n        throw new IllegalStateException('I haven\\'t learnt how to divide negativ\\\ne numbers')\n    } else {\n        return numerator / denominator\n    }\n} catch (IllegalStateException | ArithmeticException e) {\n    println 'Stand back, I know how to handle this'\n} catch (any) {\n    println 'What just happened?'\n}\n

\n\n\n\n

Constructing an Exception

\n\n

There are a few approaches to constructing an exception, the main ones being:

\n\n

new IllegalStateException(): Creates a new instance without a message
new IllegalStateException('Sorry, Dave, I cannot allow this'): Creates a new instance with a message
new IllegalStateException('Sorry, Dave, I cannot allow this', e): Creates a new instance with a message and provides the exception (e) that caused the exception you’re now throwing.

\n\n

Let’s look at an example usage of the last variation. In the following code snippet I catch two possible exceptions and bundle e into a new exception instance but pass e to the new instance so that the caller could determine the cause:

\n\n

catch (IllegalStateException | ArithmeticException e) {\n    throw new IllegalStateException('Unable to perform operation', e)\n}\n

\n\n\n\n

Upon having the exception thrown at me I could use the getCause() method to determine if there was an underlying cause.

\n\n

Creating Your Own Exception

\n\n

Whilst you can write your own Exceptions (they’re just objects after all), you should look to the pre-packaged ones and see if they meet your needs. Alternatively, consider if you can write a subclass that provides refinement to an existing exception rather than just extending Exception.

\n\n

\n52. Catching Errors

\n\n\n\n

Before we go too far on this one please note that errors indicate serious/abnormal problems and shouldn’t be caught.

\n\n

Errors are different to exceptions as they indicate a fundamental issue rather than a recoverable problem. It’s highly unlikely you’ll ever need to handle an error so treat it like a cold and don’t try to catch one. They may “crash” your program but it’s likely any treatment that you try to apply will make things worse. For example, if somehow you managed to catch a java.lang.OutOfMemoryError, how would you respond?

\n\n\n\n

One more time: don’t catch errors.

\n\n

Errors are objects and can be caught much like exceptions but the following won’t work:

\n\n

try {\n    assert true == false\n} catch (err) {\n    println 'I caught the error!'\n    println err.message\n}\n

\n\n\n\n

The code above doesn’t do what we hoped as, by default, the catch is looking for Exception or one of its subclasses¹ - probably because we shouldn’t catch errors.

\n\n

In order to catch an error we must provide Error (or a subclass of Error) as the data type in the catch:

\n\n

try {\n    assert true == false\n} catch (Error err) {\n    println 'I caught the error!'\n    println err.message\n}\n

\n\n\n\n

This is why, when we write our own exception we extend Exception rather than implement Throwable.↩\n

\n\n\n

\n53. Methods and Exceptions

\n\n\n\n

The code in this chapter is rather skewed as we’d rarely throw an exception and catch it within the same try-catch block. Rather, we’re most likely to throw an exception from a method back to the caller and we use try blocks to catch exceptions from methods we’re calling.

\n\n

Throwing an exception from a method results in no return value being returned to the caller - the caller needs to handle the exception. It’s important to note that, where the try and/or catch block contain a return statement, the finally block will be evaluated before the return is actually processed. In the next two examples below, the println in the finally block will always display.

\n\n

Using return in catch

\n\n

def testMethod() {\n    try {\n        10 / 0\n    } catch (any) {\n        return\n    } finally {\n        println 'Finally block has been evaluated'\n    }\n}\n

\n\n\n\n

Using return in try

\n\n

def testMethod() {\n    try {\n        return 100\n    } catch (any) {\n        println 'Exception'\n    } finally {\n        println 'Finally block has been evaluated'\n    }\n}\n\ntestMethod()\n

\n\n\n\n

We’re about to get to the section on Methods.

\n\n

\nVI Methods

\n\n

\n54. Introduction

\n\n\n\n

Methods (sometimes also called functions) are blocks of code that can be run more than once and encapsulate a segment of logic. We define a method by writing the code that will be run when the method is called. Calling a method is the process of your code asking the method to start.

\n\n

Groovy, like Java, is object-oriented and works around classes. C and Pascal are procedural and work around functions. Whilst the methods described here may look a bit like C-style programming that lets you build libraries of functions, what is really happening is Groovy wraps your code in a class definition behind the scenes. You’re only likely to create “raw” methods, like the ones below, as a means to break up your scripts. More usually you’ll create methods within your classes.

\n\n

Methods have a number of features:

\n\n

Methods have names\n
- this allows you to call your method in a meaningful way
\n
Methods can accept parameters\n
- these are inputs into your method that can affect how your method operates
\n
Methods can return a result value \n
- this can be captured by a variable from the code calling the method
\n
Methods have their own scope\n
- they can have their own variables and not inadvertently affect the rest of your program
\n

\n\n

We’ve already looked at various methods for use with variables such as lists and maps so you’ve seen methods being called throughout the previous chapters.

\n\n

\n55. The Basics

\n\n

Let’s start by examining a new method we’ll write to calculate the average of the numbers in a list:

\n\n

def determineAverage(list) {\n    return list.sum() / list.size()\n}\n

\n\n\n\n

Breaking that code up we can see:

\n\n

The def reserved word is used to commence the method declaration\n
- Much like we use when defining a variable
\n
\ndetermineAverage is the name of the method
The method accepts a single parameter, list\n
A single value is returned using the return reserved word\n
- In this case it’s the result of list.sum() / list.size()\n
\n

\n\n

The method name (determineAverage) may look a bit odd but it uses a naming strategy called “lower Camel Case”. The camel aspect is the use of upper-case letters to indicate individual words in the name (hence Average). The first word in the method name is a verb (determine) to indicate that a method “does” something.

\n\n

Let’s return to that determineAverage method and get a complete script together - you can copy and paste this into groovyConsole and run it to experience the method first-hand:

\n\n

The determineAverage method

\n\n

def determineAverage(list) {\n    return list.sum() / list.size()\n}\n\ndef scores = [2, 7, 4, 3]\ndef result = determineAverage(scores)\nprintln result\n

\n\n\n\n

Let’s look at the main components of that script:

\n\n

The determineAverage method is defined as before\n
- This can appear above or below the other code
\n
A new list of numbers is created: def scores = [2, 7, 4, 3]\n
The method is called with the scores variable passed as a parameter
The return value (result) of determineAverage is stored in the result variable.

\n\n

In the example I called the method using determineAverage(scores) but, in many cases, I don’t need to use the parentheses and determineAverage scores would have also worked. That’s why println 'hello, world' works just fine. This works really well when you start to use Groovy to construct domain-specific languages.

\n\n

\n56. Parameters

\n\n\n\n

Let’s look at the last example from the previous chapter:

\n\n

The determineAverage method

\n\n

def determineAverage(list) {\n    return list.sum() / list.size()\n}\n\ndef scores = [2, 7, 4, 3]\ndef result = determineAverage(scores)\nprintln result\n

\n\n\n\n

You might be wondering what happened to the scores variable once it was passed to determineAverage as a parameter. Basically, Groovy gave it another name (list) for use within the method. Inside the method, list is just another variable. This means that if determineAverage changes list in some way, this is reflected in the scores variable used in the main script:

\n\n

A poor example

\n\n

def scores = [2, 7, 4, 3]\ndef result = determineAverage(scores)\nprintln result\nprintln scores\n\ndef determineAverage(list) {\n    list << 9\n    return list.sum() / list.size()\n}\n

\n\n\n\n

The code above is very poorly behaved - it modifies list by adding a new item. Unless you provided documentation that explicitly states that you will change a parameter, most developers will assume that their parameters will be safely untouched by your method.

\n\n\n\n

Declaring data types for parameters

\n\n

Groovy lets you designate a data type for your parameters:

\n\n

Parameter with data type

\n\n

def determineAverage(List list) {\n    return list.sum() / list.size()\n}\n

\n\n\n\n

As you start to develop classes and larger programs, methods create your Application Programming Interface (API). Such methods can be called by other people’s code and they could be using another JVM language (such as Java). It can make their life a little easier if you indicate the data types you’re expecting for your parameters. Alternatively, you can stay true to dynamic typing and let people know through your documentation.

\n\n

Multiple parameters

\n\n

Let’s look at another method - one that needs several parameters:

\n\n

Multiple parameters

\n\n

def callFriend(name, phone, message) {\n    println \"Dialling $name on $phone\"\n    println \"Hi, $name - $message\"\n}\n

\n\n\n\n

Either of these calls would work - it just depends if you want to use the parentheses:

\n\n

callFriend('Barry', '0400 123 456', 'Did you see that local sporting team?')\n\ncallFriend 'Alex', '07 3344 0000', 'Could you please check on my pets whilst I\\'\\\nm away?'\n

\n\n\n\n

Each parameter may be typed if needed:

\n\n

def callFriend(String name, String phone, String message) {..}\n

\n\n\n\n

You can provide a mix of typed and untyped parameters but this is a little messy and I think it’s bad form so I can’t be bothered encouraging such an action by providing an example.

\n\n

\n57. Default Values for Parameters

\n\n\n\n

One or more parameters can be defined with a default value. This can be really useful if most calls to the method will use the defaults:

\n\n

Parameters with defaults

\n\n

def displayMessage (message,\n                    title = 'Important message:',\n                    border = true) {\n\n    def borderText = ''\n\n    if (border) {\n        borderText = '--------------------------'\n    }\n\n    println \"\"\"\\\n\t    $borderText\n\t    $title\n\t    \\t $message\n\t    $borderText\n\t    \"\"\"\n}\n\ndisplayMessage 'Preparing to shut down. Please save your work'\n

\n\n\n\n

The displayMethod can be called in a number of ways:

\n\n

displayMessage 'Preparing to shut down. Please save your work'
displayMessage 'The system appears to have crashed', 'Error!'
displayMessage 'Be prepared for the happiness patrol', 'Public announcement:', false

\n\n

When you get to method overloading and other object-oriented concepts you’ll see that default parameter values can aid in reducing the variations of a method that you might need to provide.

\n\n

\n58. Named Arguments

\n\n\n\n

You can use named arguments by having the first parameter be a Map. Consider the method below:

\n\n

Named parameters

\n\n

def displayMessage (options, message) {\n\n    def borderText = ''\n    if (! options.containsKey('border') || options.border) {\n        borderText = '--------------------------'\n    }\n\n    def title = 'Important message:'\n    if (options.title) {\n        title = options.title\n    }\n\n    println \"\"\"\\\n\t    $borderText\n\t    $title\n\t    \\t $message\n\t    $borderText\n\t    \"\"\"\n}\n\ndisplayMessage(title: 'Canberra', border: true, 'The capital of Australia')\n

\n\n\n\n

The options parameter is actually a Map and this lets the caller use an interesting Groovy syntax when calling the method. Instead of passing a Map ([:]) to the options parameter, the caller can use the key: value format in their method call. This lets us call displayMessage in many ways, including:

\n\n

displayMessage(title: 'Canberra', border: true, 'The capital of Australia')
displayMessage title: 'Time', \"It is now ${new Date()}\"
displayMessage border: false, 'Hang in there little buddy!'

\n\n

My recommendation is to use named parameters for non-essential parameters and to make sure that your method can operate correctly if a named parameter is not provided.

\n\n

If others are to be using your method or you need to remember which named parameters are available, then you’ll make sure that you add some useful documentation to the method.

\n\n

\n59. Variable Arguments (Varargs)

\n\n\n\n

There are times where we want to pass a variable number of parameters to the method. However, the parameter list for a method is fixed.

\n\n

One approach is to use a list for a catch-all parameter, such as items does in the code below:

\n\n

Using a list parameter

\n\n

def buyGroceries(store, items) {\n    println \"I'm off to $store to buy:\"\n    for (item in items) {\n        println \"  -$item\"\n    }\n}\n\nbuyGroceries 'The Corner Store', ['apples', 'cat food', 'cream']\n

\n\n\n\n

Whilst the list path is an option, Groovy supports the use of variable arguments (varargs) using the “three-dot” (...) notation for the last (and only the last) parameter:

\n\n

Using a varargs parameter

\n\n

def buyGroceries(... items) {\n    for (item in items) {\n        println item\n    }\n}\n\nbuyGroceries 'apples', 'cat food', 'cream'\n

\n\n\n\n

We can set a specific data type for the items parameter by placing the type before the ...:

\n\n

Using a typed varargs parameter

\n\n

def buyGroceries(String... items) {\n    for (item in items) {\n        println item\n    }\n}\n\nbuyGroceries 'apples', 'cat food', 'cream'\n

\n\n\n\n

Let’s return to the first example in this chapter and rewrite it using varargs:

\n\n

Varargs instead of a list

\n\n

def buyGroceries(store, ... items) {\n    println \"I'm off to $store to buy:\"\n    for (item in items) {\n        println \"  -$item\"\n    }\n}\n\nbuyGroceries 'The Corner Store', 'apples', 'cat food', 'cream'\n

\n\n\n\n

So the items parameter is actually a list inside buyGroceries but the caller just passes a series of values to the method.

\n\n\n\n

\n60. Return value

\n\n\n\n

When we started this tutorial I provided a very basic method for calculating averages. I’ve rewritten it slightly to use varargs and this is a good starting point into using the return statement:

\n\n

println determineAverage(10, 20, 30, 40)\n\ndef determineAverage(... list) { \n    return list.sum() / list.size()\n}\n

\n\n\n\n

In the code above I return the average to the caller so, instead of printing out the result I could also assign it to a variable: def avg = determineAverage(10, 20, 30, 40).

\n\n

Using the return reserved word isn’t required as Groovy will return the result of the last statement:

\n\n

println determineAverage(10, 20, 30, 40)\n\ndef determineAverage(... list) { \n    list.sum() / list.size()\n}\n

\n\n\n\n

You can use return to explicitly exit a method. By itself, return actually returns null. In the useless method I provide below, I explicitly provide return:

\n\n

def printer(message) {\n    println message\n    return\n}\n\nprinter('hello, world')\n

\n\n\n\n

That use of return in the last bit of code was redundant as the method would exit anyway (it had nothing left to do). However, this can be handy if the last expression to run in a method returns a value that we don’t want as the return value for our method.

\n\n

Anything after a return is inaccessible, as illustrated by my even more useless method:

\n\n

def printer(message) {\n    println message\n    return\n    println 'Help, I don\\'t exist'\n}\n

\n\n\n\n

That last line in the method will never, ever, ever be called. But if I really wanted it to be called I can use the try-finally approach:

\n\n

def printer(message) {\n    try{\n        println message\n        return\n    } finally {\n        println 'Help, I don\\'t exist'\n    }\n}\n

\n\n\n\n

Now, that last bit of text will be displayed as it’s in a finally block. This example is rather daft but it serves to illustrate how finally can be used to clean up something like an open file before the return is actioned.

\n\n

Multiple Returns

\n\n

You can have more than one return statement in a method but only one will ever be evaluated. This is really handy as it localises the return and prevents the method from further evaluation. You can also place a return at the very end of the method block to ensure that the method always returns a value. In the code below I use two return statements in the switch but also have return false at the bottom of the method just in case something slips through (most likely when I add in code at a later date):

\n\n

def checkAnimalAsPet(animal) {\n    switch(animal){\n        case 'dog':\n        case 'cat':\n            return true\n        default:\n            return false   \n    }\n    return false\n}\n\nassert checkAnimalAsPet('cat') \nassert checkAnimalAsPet('dog')\nassert checkAnimalAsPet('lion') == false\nassert checkAnimalAsPet('pterodactyl') == false\n

\n\n\n\n

You’ll note that, in the checkAnimalAsPet method I have a switch with no breaks. Essentially, the return is breaking out of the switch and the method all at once.

\n\n

Declaring data types for return values

\n\n

A data type can be declared for the return value by replacing def with the class name: \ne.g. Number determineAverage(... list){..}:

\n\n

Number determineAverage(... list) { \n    return list.sum() / list.size()\n}\n\nprintln determineAverage(10, 20, 30, 40)\n

\n\n\n\n

This is very handy if your method is to be accessed as part of an API, especially by Java programs.

\n\n

You may notice some methods defined with a return type of void. This indicates that the method won’t return a value:

\n\n

void displayText() {\n\tprintln 'Hello, World'\n}\n

\n\n\n\n

I can still use return within the method - I just can’t return a value.

\n\n

Sequential method calls

\n\n

In many examples I have used a method’s returned value to set a value of a variable, in an assert or as the input to a println. As the return value has its own type, we can actually call a method straight from the method call. This can be useful if one method call is just an intermediary step towards our goal and we don’t want to explicitly store its return value.

\n\n

In the example below I call the tokenize method which returns a List of the words in the poem I then call the size method for that list to determine how many words are in the poem:

\n\n

def poem = '''\\\nOnce a jolly swagman camped by a billabong\nUnder the shade of a coolibah tree,\nAnd he sang as he watched and waited till his billy boiled:\n\"Who'll come a-waltzing Matilda, with me?\"\n'''\n\npoem.tokenize().size()\n

\n\n\n\n\n\n

\n61. Throwing an exception

\n\n\n\n

A method is able to throw an exception just as we saw in the Exceptions tutorial. In the code below I throw an exception if the caller to determineAverage() tries to pass a String through as a parameter:

\n\n

Throwing an exception from a method

\n\n

def determineAverage(...values) throws IllegalArgumentException {\n    for (item in values) {\n        if (item in String) {\n            throw new IllegalArgumentException()\n        }\n    }\n    return values.sum() / values.size()\n}\n\n//This works:\nassert determineAverage(12, 18) == 15\n\n//This does not work - we get an exception\ndetermineAverage(5, 5, 8, 'kitten')\n

\n\n\n\n

None of that code is new to you except for the throws IllegalArgumentException that forms part of the method’s signature¹. The use of throws helps describe our method a little better by making callers aware of what to expect.

\n\n

Multiple exceptions can be listed against throws, as seen in the example below:

\n\n

Throwing exceptions from a method

\n\n

def determineAverage(...values)\n        throws IllegalArgumentException, NullPointerException {\n    for (item in values) {\n        if (item in String) {\n            throw new IllegalArgumentException()\n        }\n    }\n    return values.sum() / values.size()\n}\n

\n\n\n\n

Groovy doesn’t require that you explicitly provide a throws listing if your method throws an exception or passes up an exception that it doesn’t handle. However, if your method is to be used by others, I’d suggest that including throws is worth the effort.

\n\n

You may note that, in that last example, I placed throws on a second line - this helps readability as it breaks up the display of the signature just slightly.

\n\n

This is the section of the method definition contain the return type, method name, parameters and thrown exceptions. As always, Wikipedia has some further information ↩\n

\n\n\n

\n62. Documenting a method

\n\n\n\n

The groovydoc command that comes with the Groovy installation can be used to generate HTML documentation from comments within your code. GroovyDoc is based on JavaDoc and uses much the same syntax.

\n\n

Let’s look at a Groovy method that features GroovyDoc comments:

\n\n

A method with doc comments

\n\n

/**\n * Returns the average of the parameters\n *\n * @param values  a series of numerical values\n * @throws IllegalArgumentException if a values parameter is a String\n * @returns The average of the values\n */\ndef determineAverage(...values)\n        throws IllegalArgumentException {\n    for (item in values) {\n        if (item in String) {\n            throw new IllegalArgumentException()\n        }\n    }\n    return values.sum() / values.size()\n}\n

\n\n\n\n

Taking a look at the commenting:

\n\n

The multi-line comment block starts with /** to indicate that this is a GroovyDoc
The first piece of text provides the summary of the method. It’s one line and meant to be terse.
A set of @param tags can be provided to describe each parameter.\n
- The format is @param <parameter name> <summary>\n
- You don’t provide the parameter type even if you declare one
\n
Each exception that can be thrown by the method is listed against a @throws tag and provides a summary as to when the exception may be thrown.\n
- The format is @throws <exception class> <summary>\n
\n
The @returns tag describes what the method will return\n
- The format is @returns <summary>\n
\n

\n\n

If you copy the sample code into a file named Average.groovy you can then run the following command in your command line/terminal:

\n\n

groovydoc -d doc Average.groovy\n

\n\n\n\n

This will produce a directory named doc that contains a set of documentation files. Inside the doc directory you’ll see index.html - open this in a browser to view your documentation.

\n\n

As you click through the various links you’ll find the documentation for the determineAverage() method. It’ll contain the following information (but look a lot prettier):

\n\n

java.lang.Object determineAverage(java.lang.Object… values)

\n\n

Returns the average of the parameters

\n\n

throws:: IllegalArgumentException if a parameter is a String
returns:: The average of the values
Parameters:: values - a series of numerical values

\n\n

If you keep clicking links in the html files but can’t find it, look in the DefaultPackage directory for a file name Average.html - that’ll be what you’re after.

\n\n

\n63. Techniques

\n\n\n\n

I’d like to tell you that your programming career will be all about writing perfect code that never has problems but I’d just be lying. Here are some techniques to help make sure your methods are more robust and helpful to other programmers.

\n\n

Valid parameters

\n\n

We understand that the method determineAverage(...values) is expecting a list of numbers and have used a reasonably clear naming strategy (determineAverage) to display that the method is number-oriented but what happens when our colleague gives us something like:

\n\n

determineAverage(5, 5, 8, 'kitten')\n

\n\n\n\n

Clearly, kittens aren’t something that the average calculation can understand¹. If you try to run that code you’ll get a nasty error that basically says your code has failed. Don’t be too hard on your colleague though - perhaps they’ve loaded data from a file that’s become corrupted by felines.

\n\n

Comment your method

Firstly, make sure that determineAverage has some useful documentation such as:

\n\n

Provide comments

\n\n

/**\n * Returns the average of the parameters\n *\n * @param values a series of numerical values\n * @returns The average of the values\n */\ndef determineAverage(... values) {\n    values.sum() / values.size()\n}\n

\n\n\n\n

In the example above I’ve just added a GroovyDoc comment block that describes what the method does, its parameter and what it will return. At the very least, other developers will see how they should be using my method.

\n\n

Check the parameters

Next, I can be more defensive in my coding and make sure that the method has a prerequisite that needs to be met before it attempts to run.

\n\n

Check parameters

\n\n

/**\n * Returns the average of the parameters\n *\n * @param values  a series of numerical values\n * @throws IllegalArgumentException if a parameter is a String\n * @returns The average of the values\n */\ndef determineAverage(...values)\n        throws IllegalArgumentException {\n    for (item in values) {\n        if (item in String) {\n            throw new IllegalArgumentException()\n        }\n    }\n    values.sum() / values.size()\n}\n\n//This works:\nassert determineAverage(12, 18) == 15\n\n//This does not work - we get an exception\ndetermineAverage(5, 5, 8, 'kitten')\n

\n\n\n\n

The approach above checks to make sure that no parameter is a String - if you pass one to the method you’ll get an exception thrown back at you. In reality I should make sure that only numbers can be passed in and my check won’t pick up a Boolean value - more on this in a moment.

\n\n

What do you think would happen if I called the method with no parameters - determineAverage()?

\n\n

(pause)

\n\n

Well, the division would attempt to divide by zero and that’s a fail so I need to also check that values isn’t empty (I’ll leave out the comments for brevity):

\n\n

Check all parameters

\n\n

def determineAverage(...values)\n        throws IllegalArgumentException {\n    for (item in values) {\n        if (item in String) {\n            throw new IllegalArgumentException()\n        }\n    }\n\n    if (!values) {\n        return 0\n    }\n\n    values.sum() / values.size()\n}\n\nassert determineAverage() == 0\n

\n\n\n\n

Note that if no parameters are passed, I return 0. I really don’t like returning null from methods as it makes other developers then have to check for null. I also don’t want to raise an exception - I’m happy enough to say that the average of no values is 0.

\n\n

Get really typed

\n\n

If I really want to get specific with the data types I’ll take as parameters and return from the method then I can switch to static typing. I can make sure that all my parameters are of type Number (or one of its subtypes) and that I will return a value of type Number. The code below really gets specific about data types:

\n\n

Use typed parameters

\n\n

/**\n * Returns the average of the parameters\n *\n * @param values  a series of numerical values\n * @throws IllegalArgumentException if a parameter is a String\n * @returns The average of the values\n */\nNumber determineAverage(Number...values) {\n    if (!values) {\n        return 0\n    }\n\n    values.sum() / values.length\n}\n

\n\n\n\n

The following two calls to the method would work:

\n\n

assert determineAverage(2, 7, 4, 4) == 4.25\nassert determineAverage() == 0\n

\n\n\n\n

…but the following two calls won’t work:

\n\n

determineAverage(2, 7, 4, 4, 'kitten')\ndetermineAverage(2, 7, 4, 4, true)\n

\n\n\n\n

If you are writing a method that needs to be very specific about data types for parameters and/or return values then this is the way to go.

\n\n

Testing

\n\n

I’d get into a lot of trouble from experienced developers if I just left this chapter without mentioning testing.\nSo, here’s a little example using Spock!

\n\n\n

Firstly, this won’t run in your groovyConsole. You need to copy the code into the online Spock web console² and then click on “Run Script”:

\n\n

A Spock example

\n\n

import spock.lang.Specification\n\nclass MathDemo {\n    /**\n     * Returns the average of the parameters\n     *\n     * @param values a series of numerical values\n     * @throws IllegalArgumentException if a parameter is a String\n     * @returns The average of the values\n     */\n    static determineAverage(... values)\n            throws IllegalArgumentException {\n        for (item in values) {\n            if (!(item instanceof Number)) {\n                throw new IllegalArgumentException()\n            }\n        }\n\n        if (!values) {\n            return 0\n        }\n\n        return values.sum() / values.size()\n    }\n}\n\nclass AvgSpec extends Specification {\n\n    @Unroll\n    def \"average of #values gives #result\"(values, result) {\n        expect:\n        MathDemo.determineAverage(*values) == result\n\n        where:\n        values         || result\n        [ 1, 2, 3 ]    || 2\n        [ 2, 7, 4, 4 ] || 4.25\n        [ ]            || 0\n    }\n\n    @Unroll\n    def \"determineAverage called with #values throws #exception\"(values, excepti\\\non) {\n        setup:\n        def e = getException(MathDemo.&determineAverage, *values)\n\n        expect:\n        exception == e?.class\n\n        where:\n        values          || exception\n        [ 'kitten', 1 ] || java.lang.IllegalArgumentException\n        [ 99, true ]    || java.lang.IllegalArgumentException\n        [ 1, 2, 3 ]     || null\n    }\n\n    Exception getException(closure, ... args) {\n        try {\n            closure.call(args)\n            return null\n        } catch (any) {\n            return any\n        }\n    }\n}\n

\n\n\n\n

When you run this in the Spock web console you should get:

\n\n

AvgSpec\n - average of [1, 2, 3] gives 2\n - average of [2, 7, 4, 4] gives 4.25\n - average of [] gives 0\n - determineAverage called with [kitten, 1] throws class java.lang.IllegalArgume\\\nntException\n - determineAverage called with [99, true] throws class java.lang.IllegalArgumen\\\ntException\n - determineAverage called with [1, 2, 3] throws null\n

\n\n\n\n

So there’s a lot going on here that we haven’t covered in the tutorials so far but let’s try to break it down:

\n\n

I wrapped the determineAverage() method in a class named MathDemo and made it a static method\n
- I won’t explain this here - just trust me that you can call MathDemo.determineAverage()\n
- But do note that I’ve changed determineAverage() to better check that the parameters are numbers.
\n
I then created a spock test Specification subclass called AvgSpec\n
1. The first test is def \"average of #values gives #result\"(values, result)\n
  1. This runs a series of tests using the data table in the where: block
  2. Yes, that’s right, Groovy will let you use a string as the name of the method - that’s v.cool but you can’t use interpolation (${}).
  \n
2. The second test is def \"determineAverage called with #values throws #exception\"(values, exception)\n
  1. This checks to make sure that the IllegalArgumentException is thrown for incorrect parameters
  \n
\n

\n\n

As I say, there are a number of topics such as classes and closures that I haven’t covered - this example was just a quick one and should make sense as you learn about those additional concepts.

\n\n

Pun intended↩\n
I’ve published the code to make it easy for you but can’t promise that this link will always work.↩\n

\n\n\n

\nVII Closures

\n\n

\n64. Introduction

\n\n\n\n

Closures represent a reference to a function (method) that is accompanied by a referencing environment. This means that you can store function references in a variable and pass them to a function and that the original scope of the closure is available. Confused? Well, let’s get into it!

\n\n\n\n

\n65. Introducing Closures

\n\n

In the last tutorial we looked at methods and this prepares us as we start to look at closures. If you take a look at the following code you’re likely to quickly see what the printer() method does:

\n\n

Using a method reference

\n\n

def printer() {\n    println 'Hello, world'\n}\n\ndef cls = this.&printer\ncls()\n

\n\n\n\n

So what about def cls = this.&printer? Well, .& is the Method Reference operator and it returns a reference to the printer() method. I use this in the script as I need to reference the current instance in which I’m running - remember that Groovy wraps the script in a class.

\n\n

Once I have the reference I can then call the closure with cls().

\n\n

Note the following:

\n\n

When I define the closure (def cls = this.&printer) I don’t put the parentheses after the method name (printer)
When I call the closure I pass in the parameters

\n\n

Say I set this up a little differently and create a Test class with two printer methods - one that takes a parameter and one that doesn’t:

\n\n

Overloading and method references

\n\n

class Test {\n    static printer() {\n        println 'Hello, world'\n    }\n\n    static printer(name) {\n        println \"Hello, $name\"\n    }\n}\n\ndef cls = Test.&printer\ncls()\ncls('Newman')\n

\n\n\n\n

You’ll see if you run that last example that the call to the closure (cls) will result in the associated method being called depending on the parameters I provide.

\n\n

Anonymous Functions

\n\n

In the first examples of this chapter I used the Method Reference operator to point to an existing method that I had defined in a class. Closures can also be defined using anonymous functions. This lets us create a function at the point we define the variable.

\n\n

In the next example I create an anonymous function using the regular block syntax ({..}) and store the function reference in cls:

\n\n

A basic closure

\n\n

def cls = { println 'Hello, world' }\ncls()\n

\n\n\n\n

That’s pretty nifty! We can define a function when needed and store it in a variable. This variable can then be passed to methods and other closures as a parameter.

\n\n

The ‘it’ parameter

\n\n

Anonymous functions get a single parameter named it by default. That means that you can use it as a parameter inside your function and it will contain the parameter passed in the call to the closure.

\n\n

Let’s write a version of the printer method that uses the it parameter:

\n\n

Using it

\n\n

def cls = { println \"Hello, $it\" }\ncls('Jerry')\n

\n\n\n\n\n\n

\n66. Parameters

\n\n\n\n

We just saw that closures have an in-built it parameter but we can specify a parameter when we declare the closure:

\n\n

Specifying a parameter

\n\n

def cls = { name -> println \"Hello, $name\" }\ncls('Jerry')\n

\n\n\n\n

In the example above I declare the name parameter and this replaces it - in fact, if I called it within the closure I’d get an exception.

\n\n

The syntax of closures is starting to become evident:

\n\n

Start the closure with {\n
List parameters, followed by ->\n
Write a set of statements for the closure body
End the closure with }\n

\n\n

Each parameter is separated using a comma (,):

\n\n

Specifying two parameters

\n\n

def cls = { name, pet -> println \"Hello, $name. How is your $pet?\" }\ncls('Jerry', 'cat')\n

\n\n\n\n

As the closure gets more complicated I like to break it up over a number of lines. I start the closure and declare the parameters on the first line. The body of the closure then follows much the same as a method body and a final line closes off the closure:

\n\n

Formatting a closure

\n\n

def cls = { name, pet ->\n    println \"Hello, $name. How is your $pet?\"\n}\n\ncls('Barry', 'Lemur')\n

\n\n\n\n

Closure parameters let me do the same things I can do with method parameters:

\n\n

Use data types for parameters
Provide default values
Varargs
Named parameters

\n\n

Parameter data types:

\n\n

Specifying typed parameters

\n\n

def cls = { String name, String pet ->\n    println \"Hello, $name. How is your $pet?\"\n}\n\ncls('Sally', 'Echidna')\n

\n\n\n\n

Default values:

\n\n

Specifying parameters with default types

\n\n

def cls = { name, pet = 'dog' ->\n    println \"Hello, $name. How is your $pet?\"\n}\n\ncls('Barry')\n

\n\n\n\n

Varargs:

\n\n

Specifying varargs

\n\n

def cls = { name, ... pets ->\n    println \"Hello, $name. How are your $pets?\"\n}\n\ncls('Herman', 'cat', 'dog', 'spider')\n

\n\n\n\n

Named parameters:

\n\n

Specifying “named” parameters

\n\n

def cls = { grades, name ->\n    println \"This year $name received the following grades: $grades\"\n}\n\ncls(maths: 'D', science: 'C', art: 'A', 'Albert')\n

\n\n\n\n

So closures and methods are rather similar - there’s no black magic going on.

\n\n

\n67. Returning Values

\n\n\n\n

Just like methods, closures can return a value. In this next example, the result of the last expression is returned (the value of num1 or num2):

\n\n

Returning a value

\n\n

def max = { num1, num2 ->\n    if (num1 >= num2) {\n        num1\n    } else if (num2 > num1) {\n        num2\n    }\n}\n\nprintln max(14, 6)\n

\n\n\n\n

Alternatively, we can use the return statement to explicitly exit the closure and return a value:

\n\n

Explicitly returning a value

\n\n

def myClosure = { num1, num2 ->\n    if (num1 >= num2) {\n        return num1\n    } else if (num2 > num1) {\n        return num2\n    }\n}\n\nprintln myClosure(14, 6)\n

\n\n\n\n

Unlike a method, closures can’t explicitly define the data type of a return value. You might take a crack at Integer maxNumber = {num1, num2 -> ...} to set the return type but this statement won’t work as maxNumber doesn’t hold the result of the closure - it holds a reference to the closure.

\n\n

Closure myClosure = { num1, num2 -> ...} will work as the myClosure variable is actually of the Closure data type.

\n\n

\n68. Closures as Method Parameters

\n\n\n\n

We often say closures are first-class citizens in Groovy. This means that you can use them across the language in a similar manner to other first-class citizens, such as variables.

\n\n

The best example to start our exploration is the each method that’s available to your collections (lists and maps). each can be called on a list or a map and is passed a closure as a parameter, allowing you to perform operations on each member of the collection. In the next example I call each on the numList variable and pass it a very basic closure as a parameter:

\n\n

def numList = [6, 9, 11, 4, 7]\ndef myClosure = { println it }\nnumList.each(myClosure)\n

\n\n\n\n

However, we can avoid myClosure altogether as we don’t really need to use it anywhere else in our code. So, we use an anonymous closure - one that doesn’t get a name (i.e. assigned to a variable). This is really useful if we don’t need to use the closure outside of the method being called:

\n\n

def numList = [6, 9, 11, 4, 7]\nnumList.each({ println it })\n

\n\n\n\n

Whilst the closure can be placed within the (...) parentheses, this becomes cumbersome for larger anonymous closures so Groovy lets us drop the parentheses:

\n\n

def numList = [6, 9, 11, 4, 7]\nnumList.each { println it }\n

\n\n\n\n

For a final example, we can call the each method directly against the literal array, just to prove that Groovy has a versatile and flexible syntax:

\n\n

[6, 9, 11, 4, 7].each { println it }\n

\n\n\n\n

Methods with Closure Parameters

\n\n

Your own methods can accept one or more closures as a parameter. When doing this we usually follow a basic convention of:

\n\n

Use closure as the parameter name
Put the closure parameter at the end of the parameter list

\n\n

In the example below, the mutator method accepts a closure as the second parameter:

\n\n

def mutator(value, closure) {\n    closure(value)\n}\n\nmutator 10, {it**2}\n

\n\n\n\n

We are able to call mutator in a number of ways:

\n\n

mutator(10, {it**2})
mutator 10, {it**2}
mutator(10) {it**2}

\n\n

Those last two options are very useful if you’re going to pass a non-trivial closure as it helps the reader see that the last parameter is a closure and not some random block.

\n\n

Here’s another example, a method findPrimes that accepts a list of numbers (such as a range) and a closure. The method loops through the list and, when it determines the item is a prime number it will call our closure:

\n\n

Finding primes

\n\n

def findPrimes(list, closure) {\n    list.each {\n        def isPrime = true\n        if (it != 2) {\n            for (divisor in (2..it / 2)) {\n                if (it % divisor == 0) {\n                    isPrime = false\n                    break\n                }\n            }\n        }\n        if (isPrime) {\n            closure(it)\n        }\n    }\n}\n\ndef numList = (1..100)\nfindPrimes numList, { println \"I found a prime: $it\" }\n

\n\n\n\n

If I wanted to be specific about my parameter data types, the correct data type for closure is Closure. This lets me prepare a static typed method signature of def findPrimes(List list, Closure closure)

\n\n

One last round at this one - this time to set a return value from the findPrimes method. The code is not really different to the previous example but it throws a number of items together: a typed method signature, a closure parameter, and a return value for the method (the list of primes).

\n\n

Finding primes, part 2

\n\n

List findPrimes(List list, Closure closure) {\n    def result = [ ]\n    list.each {\n        def isPrime = true\n        if (it != 2) {\n            for (divisor in (2..it / 2)) {\n                if (it % divisor == 0) {\n                    isPrime = false\n                    break\n                }\n            }\n        }\n        if (isPrime) {\n            result << it\n            closure(it)\n        }\n    }\n    result\n}\n\ndef primes = findPrimes 0..100, { println \"I found a prime: $it\" }\n\nprintln primes\n

\n\n\n\n

\n69. Loops and closures

\n\n\n\n

A number of Groovy types (such as lists and maps) support methods like each which call a closure on each member of a collection. These are similar to loops (for and while) but each call to the closure is discreet and you can’t use the break branching statement to exit as you would with a loop. However, you can use return as somewhat of a proxy for continue.

\n\n

In this chapter we’ll take a look at a number of these methods.

\n\n

`each`

\n\n

We looked at each in the previous chapter but let’s do one more. In the example below I determine the average of a list of numbers and then use the each method to tell us something about each number’s relationship to the average:

\n\n

Using each

\n\n

def scores = [ 2, 4, 6, 8, 10 ]\ndef total = 0\ndef average = 0\n\nfor (i in scores) {\n    total += i\n}\n\naverage = total / scores.size\n\nprintln \"The average of the scores ($scores) is $average\"\n\nscores.each {\n    print \"The value $it is \"\n\n    if (it > average) {\n        println 'above average'\n    } else if (it < average) {\n        println 'below average'\n    } else {\n        println 'average'\n    }\n}\n

\n\n\n\n

`collect`

\n\n

The collect method calls a closure for each item in a list and returns a list of the results from each closure call. This next example takes a list of test scores and uses the closure’s algorithm for returning a list of grades:

\n\n

Using collect

\n\n

def grades = [ 45, 70, 95, 51 ].collect {\n    switch (it) {\n        case (90..100):\n            'A'\n            break\n        case (70..89):\n            'B'\n            break\n        case (50..69):\n            'C'\n            break\n        default:\n            'F'\n    }\n}\n\nprintln grades\n

\n\n\n\n

`sort`

\n\n

The sort method, when called on a list, will use the closure to evaluate a sorting algorithm and alter the list to reflect its sorted form.

\n\n

In the next example I provide a very basic sorting closure - one that just returns the length of the string it’s passed. This means that the sort method will return a list with the shortest string first:

\n\n

assert ['cat', 'rabbit', 'ox'].sort{it.length()} == ['ox', 'cat', 'rabbit']\n

\n\n\n\n

In this use of sort the closure accepts a single parameter and returns a numerical value. sort uses this result to determine the list item’s new place in the sorted list. A string of length 2 will be placed at an earlier index to a string with a length of 6.

\n\n

It’s important to remember that the list is changed by the sort method - the next example highlights this as the animals variable is different after sort is called.

\n\n

def animals = ['cat', 'rabbit', 'ox']\nanimals.sort{it.length()}\nassert animals == ['ox', 'cat', 'rabbit']\n

\n\n\n\n

When the sort method is passed a closure that accepts two parameters then it works through the list by comparing neighbours. As sort changes the list, these neighbours change, resulting in the closure undertaking a number of comparisons, at least equal to the number of list items. This is powerful stuff so let’s look at a sorting closure I used when discussing Relational Operators:

\n\n

Using sort

\n\n

def nums = [ 42, -99, 6.3, 1, 612, 1, -128, 28, 0 ]\n\n//Ascending\nnums.sort { n1, n2 -> n1 <=> n2 }\n\nassert nums == [ -128, -99, 0, 1, 1, 6.3, 28, 42, 612 ]\n

\n\n\n\n

\n70. Useful Methods That Use Closures

\n\n\n\n

Groovy adds a number of methods to java.lang.Object that gives you the power of closures baked into many of the data types you’ll use on a daily basis.

\n\n

`any`

\n\n

The any method is passed a closure that evaluates a criteria (condition). If any element in the collection meets that criteria, true is returned. Importantly, any will only iterate through the list until it the criteria is met.

\n\n

def scores = [10, 8, 11, 6]\nassert scores.any {it > 10} == true\n

\n\n\n\n

\n`find` and `findAll`\n

\n\n

The find method locates the first item in a collection that meets the criteria set in the closure:

\n\n

def animals = ['dog', 'rat', 'cat', 'mouse']\nassert animals.find {it in ['rat', 'mouse', 'wild pig'] } == 'rat'\n

\n\n\n\n

The findAll method is similar to find but returns all collection items that meet the criteria set by the closure:

\n\n

def animals = ['dog', 'rat', 'cat', 'mouse']\nassert animals.findAll {it in ['rat', 'mouse', 'wild pig'] } == ['rat', 'mouse']\n

\n\n\n\n

`split`

\n\n

The split method splits a collection into two lists: the first list contains all items that meet the criteria set by the closure parameter and the second list contains all remaining items.

\n\n

In the example below I use the split method to get a list of those who got a score over 100 and those that didn’t.

\n\n

Using split

\n\n

def players = [\n        [ name: 'Fred', topScore: 120 ],\n        [ name: 'Sally', topScore: 200 ],\n        [ name: 'Felix', topScore: 101 ],\n        [ name: 'Albert', topScore: 12 ],\n        [ name: 'Jane', topScore: 20 ]\n]\n\ndef result = players.split { it.topScore > 100 }\n\nresult[0].each { println \"$it.name is in the hall of fame\" }\n\nresult[1].each { println \"$it.name missed out\" }\n

\n\n\n\n

`with`

\n\n

The with method provides a handy approach to calling several methods and manipulating fields for an object.

\n\n

In the example below I use with to perform a set of operations on an instance of the Person class:

\n\n

Using with

\n\n

class Person {\n    def name\n    def email\n    def mobile\n\n    def printBusinessCard() {\n        println \"$name\"\n        println \"e: $email\"\n        println \"m: $mobile\"\n    }\n}\n\ndef john = new Person()\n\njohn.with {\n    name = 'John Smith'\n    email = 'john@example.com'\n    mobile = '0401 999 888'\n    printBusinessCard()\n}\n

\n\n\n\n

This approach can be really useful when creating an object. In the snippet below I create a new Person and set up their details at the same time:

\n\n

Using with at instantiation time

\n\n

class Person {\n    def name\n    def email\n    def mobile\n\n    def printBusinessCard() {\n        println \"$name\"\n        println \"e: $email\"\n        println \"m: $mobile\"\n    }\n}\n\ndef stacey = new Person().with {\n    name = 'Stacey Jane'\n    email = 'stacy@example.com'\n    mobile = '0401 333 666'\n    //This is the same as saying 'return it':\n    it\n}\nstacey.printBusinessCard()\n

\n\n\n\n

\n71. Closure scope

\n\n\n\n

In the first chapter on closures I mentioned that: Closures represent a reference to a function (method) that is accompanied by a referencing environment. Up to now we’ve mainly used closures as methods that can be referenced by variables or passed as parameters. Methods declared in classes can access the fields in their class and closures can also access items such as variables available in the context from which they were created.

\n\n

I’ve tried to demonstrate this concept in the example below. You’ll notice that my basic closure refers to a variable code that isn’t a declared parameter of the closure nor is it a variable declared within the closure. Rather, code references a variable available within the scope in which the closure is declared - i.e. code can be accessed by the doubleCross closure as both are declared in the same block.

\n\n

A small example of context

\n\n

def spyMethod(closure) {\n    closure()\n}\n\ndef code = 'eagle'\n\n//This is the closure\ndef doubleCross = { println \"The code is $code\" }\n\nspyMethod(doubleCross)\n\ncode = 'badger'\nspyMethod(doubleCross)\n

\n\n\n\n

A More Involved Example

\n\n

My doubleCross was quite basic and perhaps makes the usefulness of this concept appear to be ho-hum. In fact, it’s extremely useful and opens the door to techniques such as Domain Specific Languages - something for you to research later. For now, I’ll take you through a step-by-step example of a more complex use of closure context.

\n\n

First of all I’ll create a very basic class to describe an address book Contact. For each contact I’ll record their name and phone number. I’ll also define a closure named call and this is a simple function that I can use when calling the contact.

\n\n

class Contact {\n    def name\n    def phone\n\n    final call = { message ->\n        println \"Calling ${this.name} on ${this.phone} with the message: '$messa\\\nge'\"\n    }\n}\n

\n\n\n\n\n\n

Once I’ve defined the Contact class I’ll create a couple of contacts - Andrew and Sally.

\n\n

def andrew = new Contact(name: 'Andrew', phone: '+61 432 321 736')\ndef sally = new Contact(name: 'Sally', phone: '+61 400 800 900')\n

\n\n\n\n

I’ll then create a list of Contacts I need to call back (perhaps my mobile phone battery died) and add Andrew and Sally. You’ll note that I don’t add the Contact instances to the call-back list, I actually add the closure for each contact. Think of this as the statement “I’ll add to the list the activity of calling the contact”.

\n\n

def needToCallBack = []\nneedToCallBack << andrew.call\nneedToCallBack << sally.call\n

\n\n\n\n

Imagine that a whole lot of other code now “does stuff” and eventually we discard the andrew and sally variables:

\n\n

andrew = null\nsally = null\n

\n\n\n\n

Now this is where it gets interesting. What if my mobile battery is now recharged and I want to start calling people back? Surely the fact that I blew away my andrew and sally variables would make this impossible? Well, remember how my needToCallBack list contains references to the call closures? These closures actually hang on to their original context - the andrew and sally instances.

\n\n

All of this means that I can now use the each method on needToCallBack and I can realise those closures:

\n\n

needToCallBack.each { it('It\\'s Duncan here, sorry I missed your call') }\n

\n\n\n\n

This will now cause each of the call closures to be called - allowing me to get back in touch with andrew and sally.

\n\n

I broke up the code in the discussion so present it all here in full for you copy and try out for yourself:

\n\n

The complete Groovy message service

\n\n

class Contact {\n    def name\n    def phone\n\n    //A closure for calling the contact\n    final call = { message ->\n        println \"Calling ${this.name} on ${this.phone} with the message: '$messa\\\nge'\"\n    }\n}\n\ndef andrew = new Contact(name: 'Andrew', phone: '+61 432 321 736')\ndef sally = new Contact(name: 'Sally', phone: '+61 400 800 900')\n\ndef needToCallBack = [ ]\nneedToCallBack << andrew.call\nneedToCallBack << sally.call\n\n// Lots of other code ......\n\nandrew = null\nsally = null\n\nneedToCallBack.each { it('It\\'s Duncan here, sorry I missed your call') }\n

\n\n\n\n

\nVIII Object-oriented programming

\n\n

\n72. Introduction

\n\n\n\n

This section introduces a range of object-oriented terminology and provides you with a set of resources that will help you really hone those object-oriented programming skills.

\n\n

Object-oriented programming is often referred to by its acronym “OO” or “OOP” and has been around for some time. We won’t delve into history here - check out Wikipedia if you’d like to learn more. For now, let’s describe the essentials of OOP through a Groovy lens.

\n\n

The object-oriented programming approach models concepts based on a combination of properties and methods. The concept being modelled may be a real-world entity such as a person, a car or a tree. It may also be a “virtual” concept such as a bank account, an HTTP server or a sales report.

\n\n

The properties of an object (also referred to as fields) hold data that is important to the object’s state.

\n\n

Methods (less often referred to as functions) provide a means of accessing and manipulating the object’s properties and behaviours. Encapsulation is an important concept in OOP and relates to the use of methods to hide and even protect an object’s properties from direct access. Essentially, other code interacts with the object via its methods - often referred to as its interface.

\n\n

\n73. Expando

\n\n\n\n

Before getting stuck into formal object definitions, let’s take a look at the Expando class that ships with Groovy. Expando provides a very flexible way to construct an object on the fly.

\n\n

In the example below the monster variable is dynamically assigned a set of fields and methods (through the use of closures).

\n\n

The Expando Monster

\n\n

def monster = new Expando()\n\nmonster.with {\n    //Let's add some properties\n    name = 'Dr Frankensteins Monster'\n    owner = 'Dr Frankenstein'\n    height = 8\n\n    //Add some closures (methods)\n    getOwner = { owner }\n    getName = { name }\n    getHeight = { height }\n\n    scareVillage = { village ->\n        println \"Look out $village here comes $name!\"\n    }\n}\n\nmonster.scareVillage('Darmstadt')\n

\n\n\n\n

The monster Expando looks to be acting in a manner similar to a Map but it gives us more functionality. Whilst the properties can be assigned to an Expando instance in the same way as a Map, the addition of a closure illustrates the difference. In the example below the use of a Map to define the vampire variable demonstrates that the scareVillage can’t rely on an instance field (name) so must refer back to the vampire map:

\n\n

The Vampire Map

\n\n

def vampire = [ : ]\nvampire.name = 'Dracula'\n\nvampire.scareVillage = { village ->\n    println \"Look out $village here comes $vampire.name!\"\n}\n\nvampire.scareVillage('London')\n

\n\n\n\n

By using the Expando class instead of a Map, the instance fields can be accessed.

\n\n

Using Expando with CSV data

\n\n

Expando can be useful when we want to consume data from a source (such as a file) and manipulate it as an object. One such example is an application that reads a comma-separated file (a CSV) that contains a header row and multiple subsequent data rows. The header row tells us the fields in our data objects and we can start to throw in some methods to help handle our data.

\n\n

I’ll start with a full listing of a script that accepts CSV data (I’ll just use a String but it could be from a file) about various contacts. Expando will help me then produce a vCard for each contact. Take a read of the full listing and we’ll then break it down into easier chunks.

\n\n

The full CSV example

\n\n

//This is a basic CSV (Comma-separated file)  described as a string\ndef table = '''\\\n\tname,email,phone\n\tFred,fred@email.com,555-678345\n\tAlex,alex@email.com,555-987123\n\tSimon,simon@example.com,555-567321\n\t'''\n\n//We define the separator as the comma character\ndef separator = ','\n\n//Read the CSV in and break it up by linebreaks\ndef csv = table.tokenize()\n\n//Extract the first row - it contains the headers (field names)\nheader = csv[0].tokenize(separator)\ncsv.remove(0)\n\ndef contactList = [ ]\n\nfor (row in csv) {\n\n    Expando contact = new Expando()\n\n    //Now setup the contact class with field names based on the header\n    row.tokenize(separator).eachWithIndex { key, value ->\n        contact.setProperty header[value], key\n    }\n\n    contact.getVCard = {\n        \"\"\"BEGIN:VCARD\n            VERSION:4.0\n            N:$name\n            EMAIL:$email\n            TEL;TYPE=work,voice;VALUE=uri:tel:$phone\n            END:VCARD\"\"\"\n    }\n    contactList << contact\n}\n\ncontactList.each {\n    println it.vcard\n}\n

\n\n\n\n

The handy tokenize method is used to break the CSV data into individual rows. The first row is actually a header row and we perform another tokenize to extract each header item (field) and then remove the header row from the data table:

\n\n

def csv = table.tokenize()\nheader = csv[0].tokenize(',')\ncsv.remove(0)\n

\n\n\n\n

A contactList is then defined - this will hold our list of contacts:

\n\n

def contactList = []\n

\n\n\n\n

The code now iterates through the data table. For each row, an instance of Expando is declared:

\n\n

Expando contact = new Expando()\n

\n\n\n\n

tokenize is again used to separate each field in the row. The eachWithIndex method passes the field’s value and its index into the closure’s key and value parameters respectively. I use the index to work out the field name in header and set the value as the field from the row:

\n\n

//Now setup the contact class with field names based on the header\nrow.tokenize(',').eachWithIndex { key, value ->\n    contact.setProperty header[value], key\n}\n

\n\n\n\n\n\n

The getVCard closure is then added to the contact - this will construct a vCard for use in other systems:

\n\n

contact.getVCard = {\n    \"\"\"BEGIN:VCARD\n    VERSION:4.0\n    N:$name\n    EMAIL:$email\n    TEL;TYPE=work,voice;VALUE=uri:tel:$phone\n    END:VCARD\"\"\"\n}\ncontactList << contact\n

\n\n\n\n

Once each row has been consumed we can display our contactList:

\n\n

for (contact in contactList) {\n    println contact.getVCard()\n}\n

\n\n\n\n

\n74. The basics of OO

\n\n

This chapter will provide a whirlwind tour of the various object oriented programming concepts supported by Groovy.

\n\n

Classes

Object-oriented programmers use classes to classify objects. As such, a class defines the properties (fields)¹ and methods of an object.

\n\n

In Groovy the class keyword if used when declaring a new class:

\n\n

class Person {}\n

\n\n\n\n\n\n

Objects consist of properties (data) and methods for interacting with that data. For example, the code below describes a Person class with a name property and a getName method:

\n\n

A basic class with a property and a method

\n\n

class Person {\n    def name\n\n    def getName() {\n        return this.name\n    }\n}\n

\n\n\n\n

In order to create an instance of the Person class we use the new keyword and assign the result to a variable

\n\n

def john = new Person(name: 'John')\nprintln john.getName()\n

\n\n\n\n

The call to new Person(...) is actually using a special method called a “constructor”. Classes can define a variety of constructors to help with creating an instance and Groovy has some handy tricks we’ll explore later.

\n\n

Instead of using the def keyword the variable could be declared as being of the Person type:

\n\n

Person john = new Person(name: 'John')\n

\n\n\n\n\n\n

Instance and Class Elements

\n\n

In the getName method you’ll notice the keyword this is used. You can translate this to mean “this instance”. Groovy supports instance properties and methods - those operating on a specific instance of the class. This means that your code isolates one instance from another and prevents you from inadvertently altering instances.

\n\n

Static fields/properties and methods are also supported - these apply at a class level. By preceding a field or a method with the keyword static we indicate that it is relevant to all instances of the class. In the example below I set the specie field to be static and this means I access it at the class level by referring to Person.specie.

\n\n

Class properties use the static keyword

\n\n

class Person {\n    static specie = 'homo sapien'\n    def name\n}\n\nprintln Person.specie\n

\n\n\n\n

Constants

\n\n

An (English) language lawyer might think that the keyword static indicates that the value of specie can’t be changed. However, if you try Person.specie = 'tubulidentata' you’ll see that we can turn Person into a different specie! This is definitely not what we want so we need to declare specie as a constant.

\n\n

The final keyword precedes static/instance fields and methods to make them constant:

\n\n

Make it constant with final

\n\n

class Person {\n    static final SPECIE = 'homo sapien'\n    def name\n}\n

\n\n\n\n

Constructors

\n\n

Constructors are a special type of method that is called when a new instance is created. We saw that Groovy provides a built-in constructor when we called new Person(name: 'John'). This takes a map in which the keys match the fields in the Person object.

\n\n

To define a custom constructor we define a method with the same name as the class but without the def preceding it. The example below declares a constructor this way (Person(name)):

\n\n

Constructing a person

\n\n

class Person {\n    def name\n\n    Person(name) {\n        this.name = name\n    }\n\n    def getName() {\n        this.name\n    }\n}\n\ndef john = new Person('John')\n\nprintln john.dump()\n

\n\n\n\n\n\n

Overloading

\n\n

The overloading feature of Groovy classes allows us to create multiple versions of the same method. The parameter list for each version of the method varies to allow callers to provide either a different number of parameters (as in the example below) or with the same number of parameters but with different types. Overloading is useful but also consider using default values for parameters as this can help reduce the number of methods you need to write and maintain.

\n\n

Overloading the mean method

\n\n

class Math {\n    static mean(num1, num2) {\n        (num1 + num2) / 2\n    }\n\n    static mean(... nums) {\n        nums.sum() / nums.size()\n    }\n\n}\n\nprintln Math.mean(10, 20)\nprintln Math.mean(2, 4, 6, 8)\n

\n\n\n\n\n\n

Interfaces

Interfaces provide a method for defining programming interfaces. Interfaces, for the most part, just define method signatures and not their implementation. Classes implement these interfaces in a manner that reflect the class’s role/model/context.

\n\n

The example below defines an interface named Exercise with a single method run. The Athlete class then implements the interface:

\n\n

Implementing an interface

\n\n

interface Exercise {\n    def run(int distance)\n}\n\nclass Athlete implements Exercise {\n    def name\n\n    def run(int distance) {\n        println \"I'm off for a ${distance}km run.\"\n    }\n}\n\ndef robert = new Athlete(name: 'Rob')\nrobert.run(10)\n

\n\n\n\n

Inheritance

A superclass is one from which other classes inherit functionality. The “child” classes are referred to as being subclasses. A subclass inherits from a superclass through the use of the extends keyword.

\n\n

In the code below, StaffMember is a subclass of Person. This allows StaffMember to access the name field defined in Person:

\n\n

Inheritance in action

\n\n

class Person {\n    def name\n}\n\nclass StaffMember extends Person {\n    def staffID\n\n    def getIdentification() {\n        println \"${this.name} - ${this.staffID}\"\n    }\n}\n\ndef sally = new StaffMember(name: 'Sally', staffID: 765)\nsally.identification\n

\n\n\n\n

Unlike interfaces, superclasses can provide implemented methods and fields that subclasses can utilise. However, Superclasses can work somewhat like interfaces and their methods can be declared as abstract to force subclasses to provide their own implementation.

\n\n\n\n

Overriding methods

Subclasses can also override methods and fields implemented by superclasses. This lets subclasses provide more contextual implementations if needed. A subclass can refer directly to superclass fields and methods by using the super keyword.

\n\n

In the example below, StaffMember is a subclass of Person. The StaffMember class overrides the getName method and prefixes a string to the name returned by the superclass.

\n\n

Overriding methods

\n\n

class Person {\n    def name\n\n    def getName() {\n        this.name\n    }\n}\n\nclass StaffMember extends Person {\n    def staffID\n\n    @Override\n    def getName() {\n        \"Team member ${super.name}\"\n    }\n\n    def getIdentification() {\n        println \"${this.name} - ${this.staffID}\"\n    }\n}\n\ndef sally = new StaffMember(name: 'Sally', staffID: 765)\nprintln sally.name\n

\n\n\n\n\n\n\n\n

Traits

\n\n

At first glance, traits can be considered as interfaces with an implementation but they offer a really useful approach to adding features or abilities to a class. A common example may be to add the flying trait to animals or vehicles. The trait may have its own fields and/or methods.

\n\n

In the example below:

\n\n

A very basic Project class is defined. It just stores the project name
An Agile trait provides some basic fields used to describe an agile aspect to projects. A very basic method (startIteration) gives us an example method to call.
A Scrum class is defined:\n
1. It extends the Project class
2. It implements the Agile trait
3. Two Scrum-specific fields are added (productOwner & scrumMaster)
\n
I can then create an instance of Scrum and provide it information for both the Project/Scrum hierarchy as well as the Agile trait.\n
1. I then call the Agile trait’s startIteration method and our project is away!
\n

\n\n

Applying a trait

\n\n

class Project {\n    def name\n}\n\ntrait Agile {\n    def iterationLength = 4\n    def backlog = [ ]\n    def developmentTeam = [ ]\n\n    def startIteration() {\n        println \"\"\"\\\n\t            We're staring our $iterationLength week iteration for $name\n\t            Team members: $developmentTeam\n\t            Backlog: $backlog\n\t            \"\"\"\n    }\n}\n\nclass Scrum\n        extends Project\n        implements Agile {\n\n    def productOwner\n    def scrumMaster\n}\n\ndef project = new Scrum().with {\n    name = 'Project X'\n    iterationLength = 2\n    productOwner = 'Charlie'\n    scrumMaster = 'Bobby'\n    developmentTeam = [ 'Dean', 'Sam' ]\n    backlog << 'As a User I want to press buttons'\n    backlog << 'As an Admin I want to lockout users'\n    //This returns 'it' (the new instance of Scrum)\n    it\n}\n\nproject.startIteration()\n

\n\n\n\n

Packages

As discussed earlier, Groovy allows programmers to group objects into packages. In the following snippet the Person class is allocated to the myobjects package:

\n\n

Put classes into packages

\n\n

package myobjects\n\nclass Person {}\n

\n\n\n\n

Packages are central to using others’ code in your programs and allowing your code to be used elsewhere.

\n\n

Summary

This chapter has provided an extremely brief overview of object-oriented programming supported by small Groovy examples.\nThe following chapters in this section will explore fundamental aspects of fields and methods and the subsequent section\nwill dive far deeper into how to really get OO with Groovy.

\n\n

At this stage I’ll use ‘field’ and ‘property’ interchageably - there is a difference but I’ll discuss this soon.↩\n

\n\n\n

\n75. Properties and Fields

\n\n\n\n

In this chapter we’ll delve more into properties and fields. They’re almost the same thing and are known more generally as member variables as they hold data regarding the state of an object instance. In less technical terms, they help describe a specific instance (e.g. Jim) of a class (Person).

\n\n

Properties

The class below is composed of three properties and could be used to pass a person’s details around in a system. You may come across references to this type of structure as “Groovy beans”:

\n\n

A basic person class with three properties

\n\n

class Person {\n    def name\n    def email\n    def mobile\n}\n\ndef astrid = new Person()\nastrid.name = 'Astrid Smithson'\nastrid.email = 'astrid@example.com'\nastrid.mobile = '0418 111 222'\n\nprintln astrid.dump()\n

\n\n\n\n

In the code above I create a new instance of the Person class by calling new Person() and can then access each property using dot-point notation. This type of class can be really handy when you just need a structure for storing and handing around data - say, for example, you load a record from a database and want to feed it to other classes and their methods for processing.

\n\n\n\n

Groovy provides a built-in approach to passing in property values when creating a new instance. The code below creates a new Person but sets the property values using named arguments:

\n\n

def astrid = new Person(name: 'Astrid Smithson', email: 'astrid@example.com', mo\\\nbile: '0418 111 222')\n

\n\n\n\n

We don’t have to set all of the properties, just the ones we need:

\n\n

def astrid = new Person(name: 'Astrid Smithson', email: 'astrid@example.com')\n

\n\n\n\n\n\n

Viewing an object’s properties/fields

If you try to use println to display the details for astrid you’ll get something like Person@46423706. It’s not very useful - just the type of the Object and an identifier. If you want to find out the field values, call the dump method that all objects inherit from Object:

\n\n

println astrid.dump()\n

\n\n\n\n

Typed properties

\n\n

Just as we saw with variables, properties can be defined with a specific data type, rather than with a dynamic type. The code below redefines the Person class with typed properties:

\n\n

A basic person class with three typed properties

\n\n

class Person {\n    String name\n    String email\n    String mobile\n}\n

\n\n\n\n\n\n

People often ask if they should just use def or assign an explicit type. My answer is pretty straight-forward: if you know how you’ll use it and you’ll only use it one way, give it a type. The name property is a good example and I would use String. In other situations you may want to be flexible in what you can store so use def.

\n\n

Fields

\n\n

A field is pretty much the same thing as a property - it’s a member variable - but there’s a difference: fields are defined with an access modifier and properties are not. An access modifier is used to allow/block access from other code using the class and its member variables and methods.

\n\n\n\n

In the code below I have rewritten the Person class using fields rather than properties:

\n\n

class Person {\n    public name\n    private email\n    private mobile\n}\n

\n\n\n\n

Firstly, you’ll see that I haven’t used the def keyword - I don’t need to do this when I provide an access modifier. I could have declared public def name but it’s not good style as the def is implied. We can specify a type for a field by stating the type after the access modifier:

\n\n

class Person {\n    public String name\n    private String email\n    private String mobile\n}\n

\n\n\n\n\n\n

Default values

Properties and fields are much like variables and can be declared with an initial value:

\n\n

class Person {\n    public String name = 'anonymous'\n    private String email = 'anon@example.com'\n    private String mobile = ''\n}\n

\n\n\n\n

The initial value doesn’t have to be a literal, it can be determined from an expression.

\n\n

Casting maps to objects

\n\n

Groovy gives bean-style objects a really interesting approach to casting¹ a map or a list to an object. Let’s get\nan example going first:

\n\n

Using a map to create a new instance

\n\n

class Person {\n    def name\n    def email\n    def mobile\n}\n\ndef astrid = [name: 'Astrid Smithson', email: 'astrid@example.com'] as Person\nprintln astrid.dump()\n\nPerson gretchen = [name: 'Gretchen Gaul', email: 'gretchen@example.com']\nprintln gretchen.dump()\n

\n\n\n\n

For the first person (astrid) I explicitly cast the map to a Person instance using\n[name: 'Astrid Smithson', email: 'astrid@example.com'] as Person. Groovy creates a new instance of Person and calls\nthe name and email setters.

\n\n

In the case of gretchen I don’t need to call as Person as Groovy infers this from the fact I declared the variable’s\ntype (Person gretchen).

\n\n

Remember the as operator?↩\n

\n\n\n

\n76. Getters and Setters

\n\n

Getters and setters are methods:

\n\n

Getters are used to read the value of a member variable\n
- Their name begins with get followed by the title-case version of the property name
- \ngetName, getEmail, getMobile\n
- Getter methods don’t have any parameters
\n
Setters are used to set the value of a member variable.\n
- Their name begins with set followed by the title cased version of the property name
- \nsetName, setEmail, setMobile\n
\n

\n\n\n\n

In Java code you often see a lot of anaemic setters and getters - basically the getters just return name and the setters just this.name = name. In a class with a lot of member variables this results in a lot of boilerplate code that really gets in the way of readability. Groovy, however, creates these anaemic setters/getters for properties behind the scenes so you don’t have to. In the next code example I use my basic Person class with three properties:

\n\n

Where did getEmail come from?

\n\n

class Person {\n    def name\n    def email\n    def mobile\n}\n\ndef jess = new Person()\njess.setEmail('jess_at_example.com')\nprintln jess.getEmail()\n

\n\n\n\n

I never wrote the getEmail and setEmail methods - Groovy just worked out that my email property would need associated getters and setters.

\n\n

This means that most Groovy classes only need to provide getters/setters for properties if they need specific functionality or want to turn off the default behaviour. In the code below I define the setter for the email field as I want to make sure the caller is passing me a valid email address:

\n\n

A custom setter

\n\n

class Person {\n    def name\n    def email\n    def mobile\n\n    void setEmail(email) throws IllegalArgumentException {\n        def regex = ~/[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+/\n        if (email.matches(regex)) {\n            this.email = email\n            return\n        }\n        throw new IllegalArgumentException('Incorrect email format')\n    }\n}\n\ndef jess = new Person()\n\njess.setEmail('jess@example.com')\nprintln jess.dump()\n\n//This will fail\njess.setEmail('jess_at_example.com')\nprintln jess.dump()\n

\n\n\n\n

What if I don’t want a setter or getter? You can define your own setter or getter, mark each with the private access modifier and document it. I also like to throw exceptions to really prove my point:

\n\n

Change my ID will you?

\n\n

class Person {\n    def id\n    def name\n    def email\n    def mobile\n\n    /**\n     * Will NOT set the ID - do not call\n     * @throws Exception Always throws an exception\n     */\n    private void setId(id) throws Exception {\n        throw new Exception('Method not available')\n    }\n}\n

\n\n\n\n

In the code above you’ll see that any call to setId will cause an exception to be thrown - whether it calls the setter directly (p.setId 1234) or indirectly (p.id = 1234).

\n\n

Fields

Setters and getters aren’t generated for fields. You need to create your own setters and getters for fields (if you want them). In the code below\nwe can’t use p.setName('Bill') as the setter is not created for us - instead, we access the field directly with p.name = 'Bill':

\n\n

A basic field

\n\n

class Person {\n    private String name\n}\n\nPerson p = new Person()\np.name = 'Bill'\nprintln p.dump()\n

\n\n\n\n

If you do provide a setter for a field (such as setName in the code below), an attempt to directly set the field’s value (e.g. p.name = 'Bill') is deferred to the setter:

\n\n

A setter

\n\n

class Person {\n    private String name\n\n    void setName(name) {\n        println 'Setting name...'\n        this.name = name\n    }\n}\n\nPerson p = new Person()\np.name = 'Bill'\nprintln p.dump()\n\np.setName 'William'\nprintln p.dump()\n

\n\n\n\n

The call to p.setName also works but using p.name is a little cleaner in terms of aesthetics/style.

\n\n\n\n

Pseudo properties

\n\n

The Groovy model for setters and getters means that you can access Java and Groovy getter/setter methods as if they were\nproperties. For example, instead of calling myUrl.getText() on an instance of java.net.URL, I can just use myUrl.text:

\n\n

def myUrl = new URL('http://www.example.com')\nprint myUrl.text\n

\n\n\n\n

The URL class may have an underlying member variable called text but that’s not really our concern. What it does guide us to is\nthe fact that, provided we use the get and set prefix on methods we can then access them as if they were properties. Consider\na Person class that stores the person’s date of birth (DOB). When we know their DOB we can calculate their age:

\n\n

Age is a pseudo property

\n\n

import java.time.LocalDate\nimport java.time.Period\n\nclass Person {\n    String name\n    LocalDate dateOfBirth\n\n    Integer getAge() {\n        Period.between(dateOfBirth, LocalDate.now()).years\n    }\n}\n\nPerson jim = new Person(dateOfBirth: LocalDate.of(1983, 06, 04))\nprintln jim.age\n

\n\n\n\n

In the code above I define the getAge getter to perform the calculation to determine the person’s age. This is better than\nhaving an age property/field as this can be calculated from the DOB. The other advantage is in long-running systems - if we\nstored the age then it becomes out of date as the system runs for days/weeks/months.

\n\n

It’s important to note that we can’t call jim.age = 100 in the code above as we don’t provide a setter. Naturally, we could provide a setter\nbut it doesn’t make a lot of sense in terms of the Person’s age.

\n\n\n\n

\n77. Methods

\n\n

Methods were covered in their own section and we just looked at getters/setters so you’d think that\nwe’ve covered it all. Well, there’s a bit more to say about methods in Groovy.

\n\n

In The basics of OO I touched on instance and class elements:

\n\n

Instance elements are properties/fields and methods that relate to a specific instance of a class\n
- These are also referred to as member variables and member methods/functions
\n
Class elements are properties/fields and methods that relate to the class itself - not a specific instance\n
- These are covered in the chapter on Class Methods\n
\n

\n\n

In the code below I have two instance properties (name and email) and an instance method (getContact())

\n\n

getContact is an instance method

\n\n

class Person {\n    String name\n    String email\n\n    String getContact() {\n        \"$name <$email>\"\n    }\n}\n\nPerson jenny = new Person(name: 'Jenny', email: 'jen@example.com')\nprintln jenny.getContact()\n\nPerson dave = new Person(name: 'Dave', email: 'dave@example.com')\nprintln dave.getContact()\n

\n\n\n\n

When we look at the two instances of People (jenny and dave) we can see that the call to getContact() is specific to each\ninstance of the class. This means that our request for jenny’s contact information doesn’t return us dave’s details.

\n\n\n\n

There are times when we need to make sure we’re specific when referring to instance elements within a class. In order to do this, we use the this keyword:

\n\n

Using this

\n\n

class Person {\n    String name\n    String email\n\n    void setName(name) {\n        this.name = name\n    }\n\n    String getContact() {\n        \"$name <$email>\"\n    }\n}\n\nPerson jenny = new Person()\njenny.setName('Jenny')\njenny.setEmail('jen@example.com')\nprintln jenny.getContact()\n

\n\n\n\n

In the example above I have provided a setName(name) method and set the instance’s name property using this.name = name. This example\nis demonstrating a primary use of this: to delineate between the method parameter and the instance property. this can be used for both\nmember variables (e.g. this.email) and when calling member methods (this.setEmail()) but is limited to elements within the class - it can’t\nbe called from outside the class (e.g. jenny.this.setName('Jenny')).

\n\n\n\n

Overloading

I’ve deferred a really useful method feature for this section: method overloading.\nOverloading allows a class to declare a method with the same name more than once, provided each version of the method has different parameters.

\n\n\n\n

In the example below I provide two implementations of the exercise method: one that takes no parameters and another\nthat takes one parameter (duration).

\n\n

A basic example of overloading

\n\n

class Person {\n    String name\n\n    def exercise() {\n        println 'I am exercising but I\\'m not sure for how long'\n    }\n\n    def exercise(duration) {\n        println \"I am exercising for $duration minutes\"\n    }\n}\n\nPerson sam = new Person(name: 'Sam')\n\nsam.exercise()\nsam.exercise(10)\n

\n\n\n\n

Whilst my example has just two versions of the exercise method, I could keep adding more\n(def exercise(duration, location), def exercise(duration, location, activity)) to cover all of the cases I need. In many cases\nI’ll need a baseline of functionality and, in order to save me writing this functionality into each version of exercise, I can\ncall from one method to another:

\n\n

One method calling its cousin

\n\n

class Person {\n    String name\n\n    def exercise() {\n        //Generate a random number using java.util.Random\n        Random random = new Random()\n\n        //Use nextInt to get a random number between 0 and 120\n        exercise(random.nextInt(120))\n    }\n\n    def exercise(duration) {\n        println \"I am exercising for $duration minutes\"\n    }\n}\n\nPerson sam = new Person(name: 'Sam')\n\nsam.exercise()\n

\n\n\n\n

In the previous versions of exercise I haven’t used parameter types so my overloads must be differentiated by the number of parameters\nfor each version of the method. However, if I provide specific parameter types I can have several variations of a method,\ndifferentiated by the parameter types:

\n\n

One method calling its cousin

\n\n

class Person {\n    String name\n\n    def exercise() {\n        println 'I am exercising but I\\'m not sure for how long'\n    }\n\n    def exercise(Integer duration) {\n        println \"I am exercising for $duration minutes\"\n    }\n\n    def exercise(String activity) {\n        println \"I think I'll go for a $activity\"\n    }\n\n    def exercise(String activity, Integer duration) {\n        exercise(activity)\n        exercise(duration)\n    }\n}\n\nPerson sam = new Person(name: 'Sam')\n\nsam.exercise()\nsam.exercise(10)\nsam.exercise('walk')\nsam.exercise('jog', 30)\n

\n\n\n\n

Whilst I could have written another exercise method with exercise(Integer duration, String activity) I have already provided\nexercise(String activity, Integer duration) so such an addition would, at best, be redundant but could also be confusing if\neach variation did something functionally different. For example, say exercise(Integer duration, String activity) were to be written as:

\n\n

def exercise(Integer duration, String activity) {\n    println \"I'll go for a $activity in $duration minutes\"\n}\n

\n\n\n\n

I can technically do this as the parameters are different to exercise(String activity, Integer duration) but you can see\nthat my intent is different to the intent seen in the other exercise methods. Avoid this type of coding - it really is a trap. Overloading\nbest works when you have the same functionality that can work with different parameters. Using overloading to provide different functionality, depending on parameters,\nis likely to trip you up. Instead of overloading with that last example, I would have given the method a different signature that\nbetter reflects what the method is doing: delayExercise(Integer duration, String activity).

\n\n

Default parameter values can make this confusing

\n\n

Try the code below in a groovyConsole:

\n\n

A basic example of overloading

\n\n

class Person {\n    String name\n\n    def exercise() {\n        println 'I am exercising but I\\'m not sure for how long'\n    }\n\n    def exercise(duration = 10) {\n        println \"I am exercising for $duration minutes\"\n    }\n}\n\nPerson sam = new Person(name: 'Sam')\n\nsam.exercise()\nsam.exercise(10)\n

\n\n\n\n

Unfortunately that example won’t even run - Groovy reports that method \"java.lang.Object exercise()\" that is already defined.\nIt’s not always clear where this clash lays - after all, I have explicitly written two versions of exercise, each with a different parameter list.\nHowever, my use of a default value for a parameter (exercise(duration = 10)) is implicitly defining two versions of the exercise method:

\n\n

\nexercise() - this is what clashes with the explicitly declared exercise()\n
exercise(duration)

\n\n

In larger classes this can get a little confusing so, when it happens to you, start looking at the overloaded methods with\n default parameter values.

\n\n

Overloading != Overriding

Before we move on, it’s worth highlighting two pieces of terminology:

\n\n

\nOverloading is when a class is defined with methods with the same name but different parameters to others within the class or its superclass(es).
\nOverriding is when a subclass redefines a method from its superclass. We’ll see this in the chapter on Inheritance\n

\n\n

When we looked at Operator Overloading we saw that we could write a plus method that aligns with the\n+ operator. The overloading aspect indicates that the functionality for the operator (+) is being defined for certain operands\n and this is using different parameter types in overloading.

\n\n

\n78. Constructors

\n\n\n\n

A constructor is a special type of method that is called when instantiating a new instance of a class. We create a new instance every time we use the new keyword:

\n\n

A basic bean-type class

\n\n

class Person {\n    def name\n    def email\n    def mobile\n}\n\ndef astrid = new Person()\n

\n\n\n\n

In the code above I define the Person class with three properties and then create a new instance in the astrid variable. The new keyword indicates to Groovy that a new Person instance is to be created. The Person() aspect is actually a call to the constructor for the class. However, I haven’t actually provided a constructor for the Person class so what am I calling? Groovy classes all trace back to the Object class - where a class does not explicitly state that it inherits from (subclasses) another class it is automatically seen as a subclass of Object.

\n\n

Groovy sees Person() and knows that the Person class doesn’t provide a no-parameter (aka no-argument or no-args) constructor but Object does so that is called and it doesn’t really do anything interesting. This whole arrangement means that your classes automatically have a no-argument constructor.

\n\n

As always, Groovy adds a little extra on top and we’ve seen that we can use the map notation to assign values to member variables (properties/fields) when we create a new instance:

\n\n

def astrid = new Person([name: 'Astrid Smithson', email: 'astrid@example.com'])\n

\n\n\n\n

You can see that new Person is being passed a map consisting of keys that relate to properties in the class. This means you can prepare the map elsewhere in your code and then pass it into the constructor:

\n\n

def details = [name: 'Astrid Smithson', email: 'astrid@example.com']\ndef astrid = new Person(details)\n

\n\n\n\n

Groovy gives us that little bit of syntactic sugar and lets us drop the square brackets ([]) in the call:

\n\n

def astrid = new Person(name: 'Astrid Smithson', email: 'astrid@example.com')\n

\n\n\n\n

This looks like a built-in constructor that accepts a map (or map-like) syntax in which each of the keys match a name of a member variable. This is really useful for bean-type classes that we’re using to keep data fields together. However, this isn’t a true constructor as Groovy doesn’t generate a Person constructor that takes a map as its parameter. Instead, the no-args constructor is called followed by the setters for each key in the map. This isn’t usually a problem until you’re using final properties and fields.

\n\n\n\n

Writing your own constructor(s)

Whilst the no-args constructor and map parameter approach can be useful, you’ll probably need to define your own constructors at some point. This may be due to a few reasons, such as:

\n\n

You need information when you create a new instance that is more than just the member variables - perhaps you need to calculate something
You don’t want the caller to be able to populate a member variable - perhaps you’ll load that from a database or perform a calculation to determine its value

\n\n

If you need to do something specific in order to sensibly create a new instance of your class you’ll need to define one or more constructors. So, let’s look at an example:

\n\n

A basic constructor for Person

\n\n

class Person {\n    def name\n    def email\n    def mobile\n\n    //Here's the constructor:\n    Person(name) {\n        this.name = name\n    }\n}\n\ndef astrid = new Person('Astrid Smithson')\nprintln astrid.dump()\n

\n\n\n\n

In order to define a constructor we declare a method that:

\n\n

Can have an access modifier (discussed in a later chapter)
Has no return value declared - none, not even void\n
Has the same name as the class in which it is defined - yes, it is case-sensitive
Can take 0 or more arguments

\n\n

Now that you’ve supplied a constructor you’ll lose the built-in “map constructor”. Be warned that this isn’t always obvious! If we create a new instance using named arguments, our dump will show us that astrid’s name becomes a list:

\n\n

def astrid = new Person(name: 'Astrid Smithson', email: 'astrid@example.com', mo\\\nbile: '0418 111 222')\nprintln astrid.dump()\n

\n\n\n\n

This will display: <Person@45ceff52 name=[name:Astrid Smithson, email:astrid@example.com] email=null mobile=null>. You should be able to see that the name property is just plain wrong.

\n\n

By adding the Person(name) constructor we’ve effectively changed Person so that it has two constructors: the no-argument constructor and one that accepts the Person’s name. If the coder using our Person class wanted to add an email or mobile number they’d have to do that after instantiating the instance.

\n\n

We can define as many constructors as we feel necessary - they all carry the same name as their class but have different parameter lists (Ã la overloading). In the code below I provide two constructor definitions:

\n\n

A class with two constructor definitions

\n\n

class Person {\n    private name\n    def email\n    def mobile\n\n    Person(name) {\n        this.name = name\n    }\n\n    Person(name, email) {\n        this(name)\n        this.email = email\n    }\n}\n\ndef astrid = new Person('Astrid Smithson', 'astrid@example.com')\nprintln astrid.dump()\n

\n\n\n\n\n\n

You can probably work out what most of the code above does - one constructor allows for just a name argument and the other allows for both a name and an email. But what is this(name) doing? First, remember that this is used to refer to the current instance. What I wanted to do from Person(name, email) was call Person(name) so as to set the name - perhaps I was going to put some more complex logic in around setting the name. In order to call the Person(name) constructor from another constructor I need to to refer to this so this(name) is a call to another constructor within the class. This is commonly referred to as “constructor chaining”.

\n\n

There is a specific rule we have to follow when constructor chaining - calls to other constructors must occur before any other statements. That means the following constructor code won’t compile:

\n\n

Person(name, email) {\n    this.email = email\n    this(name)\n}\n

\n\n\n\n\n\n

Before moving on, there’s still that no-args constructor that we get even when we don’t ask for it. Sometimes we actually want to force\nother developers to use a constructor with arguments. For example the Person(Integer id) might use the id parameter to load the\nPerson’s details from a file/database. In this case the no-args constructor could leave us with some sort of zombie person instance\nwith no information. One approach to avoiding this is to prepend the private modifier to indicate\nthat other coders shouldn’t use it:

\n\n

private Person() {}\n

\n\n\n\n

If you want to be really forceful, just throw an exception if someone tries their luck:

\n\n

private Person() {\n    throw new IllegalArgumentException('Do not use the no-arg constructor')\n}\n

\n\n\n\n

Lists

\n\n

Good old Groovy never stops giving us different ways to do things and, in the code below, we can cast a list of values into\na Person:

\n\n

That list constructs!

\n\n

class Person {\n    String name\n    String email\n    String mobile\n\n    Person(name, email) {\n        this.name = name\n        this.email = email\n    }\n\n    Person(name, email, mobile) {\n        this(name, email)\n        this.mobile = mobile\n    }\n}\n\ndef astrid = ['Astrid Smithson', 'astrid@example.com', '12345'] as Person\nprintln astrid.dump()\n\nPerson gretchen = ['Gretchen Gaul', 'gretchen@example.com']\nprintln gretchen.dump()\n

\n\n\n\n

For astrid I cast the three item list explicitly using as Person because I didn’t supply a type when decalaring the\nvariable (def astrid). Groovy takes my 3 items, sees that there is a three-argument constructor, and passes it through.\nIn the case of gretchen I don’t need the explicit cast as I declared a type with the variable (Person gretchen). The\nlist has 2 items so the two-argument constructor is called.

\n\n

I could have been groovier and declared one constructor, with mobile given a default value, and got the same result:

\n\n

 Person(name, email, mobile = '') {\n     this.name = name\n     this.email = email\n     this.mobile = mobile\n }\n

\n\n \n\n

\n\n

There’s two really interesting things to keep in mind with this:

\n\n

The constructor is being called (unlike with the “map constructor”)
This will work with all the various Groovy and Java classes

\n\n

On that last point, let’s look at two quick examples to prove I’m not fooling you:

\n\n

//Prepare a calendar using YYYY, MM, DD\ndef calendar = [2015, 01, 31] as GregorianCalendar\n\n//Setup a URL\njava.net.URL url = ['http', 'www.example.com', 80, '/index.html']\n

\n\n\n\n

TupleConstructor annotation

The @groovy.transform.TupleConstructor is an annotation that we can add to our classes and have a variety of constructors automatically generated for us:

\n\n

The TupleConstructor annotation

\n\n

@groovy.transform.TupleConstructor\nclass Person {\n    def name = 'Anonymous'\n    def email\n    def mobile\n}\n\ndef unknown = new Person()\ndef astrid = new Person('Astrid Smithson')\ndef john = new Person('John Hancock', 'john@example.com')\ndef kelly = new Person('Kelly Grant', 'kelly@example.com', '044 555 555')\ndef dave = new Person(name: 'Dave Smith', email: 'dave@example.com')\n

\n\n\n\n

The TupleConstructor annotation gives us the map-based constructor as well as a set of constructors matching the member variables - effectively generating the following constructors:

\n\n

Person(name)
Person(name, email)
Person(name, email, mobile)

\n\n

You can see where the “telescoping” notion comes from - each constructor adds a parameter over the last.

\n\n

You can configure the annotation to include and exclude specific fields so, when you’re wanting to give it a spin in your own code, check out @groovy.transform.TupleConstructor.

\n\n

Instance initializer blocks

\n\n

A stand-alone instance initializer block can be used to provide a base setup for a new instance. This is useful if you need a block of code in order to set default/original values for one or more member variables.

\n\n

Instance initializer blocks appear inside the class itself, surrounded by curly braces {}:

\n\n

A basic class with an initializer block

\n\n

class Person {\n    UUID id\n    String name\n\n    {\n        this.name = 'Anonymous'\n        this.id = UUID.randomUUID()\n    }\n}\n\nPerson paul = new Person()\nprintln paul.dump()\n

\n\n\n\n

The code above offers nothing over setting the property defaults directly (UUID id = UUID.randomUUID()) - it’s just a simple example. You can use an initializer block or constructors, or both. The initializer block will be called before any constructor(s).

\n\n\n\n

There is a small trap to be wary of when using an instance initializer block - the syntax Groovy uses for passing closures as parameters will cause a failure around initializer blocks in some conditions. The following code is an example of this and won’t run:

\n\n

An initializer block that gets mistaken as a closure

\n\n

class Person {\n    private Integer id\n    private String name = 'Anonymous'\n\n    {\n        this.id = UUID.randomUUID()\n    }\n}\n\nPerson fred = new Person(name: 'Fred')\n

\n\n\n\n

In order to get around this, prefix the initializer block with a semicolon (;)¹. This stamps a definite statement delimiter against the initializer block:

\n\n

A prefixed initializer block

\n\n

class Person {\n    private UUID id\n    private String name = 'Anonymous'\n\n    ;{\n        this.id = UUID.randomUUID()\n    }\n}\n\nPerson fred = new Person(name: 'Fred')\nprintln fred.dump()\n

\n\n\n\n

I’d suggest always using the prefix - it isn’t messy and makes sure that Groovy knows it’s looking at an initializer block.

\n\n

When and How Things Happen

It can be frustrating when you’ve written a nice looking class but things don’t happen in the manner you intended.\nThis can be due to the stuff going on behind the scenes that isn’t always immediately obvious.\nLet’s take a look at a Person object that uses an initializer block and a constructor as well as provide a field setter and a helper method:

\n\n

Investigate the order of things

\n\n

class Person {\n    private String name\n\n    ;{\n        this.name = 'Anonymous'\n        println \"Initialised default name to ${this.name}\"\n    }\n\n    public Person(name) {\n        this.name = name\n        println \"Constructor called with name: ${this.name}\"\n    }\n\n    public void setName(name){\n        this.name = name\n        println \"setName called. Name is now: ${this.name}\"\n    }\n\n    public void changeName(name) {\n        this.name = name\n        println \"changeName called. Name is now: ${this.name}\"\n    }\n}\n\nPerson fred = new Person('Fred')\n\nprintln \"After instantiation, name is: $fred.name\"\n\nfred.name = 'Freda'\n\nfred.changeName 'Frederique'\n

\n\n\n\n

Running the code above will yield the following output:

\n\n

Initialised default name to Anonymous\nConstructor called with name: Fred\nAfter instantiation, name is: Fred\nsetName called. Name is now: Freda\nchangeName called. Name is now: Frederique\n

\n\n\n\n

From that output we can piece together a basic set of rules that helps us see how things happen:

\n\n

The initialiser block is called before the constructor
Setting a field within object methods (e.g. with this.name = name) performs a direct change of the field
Setting a field externally (e.g. with fred.name = 'Freda') causes the setter (setName) to be called

\n\n

Constructors and instance methods

In the last code example I set the name field directly in the constructor. When looking at the code you may wonder if it isn’t better to have the constructor call the setter (setName) so that I can place any logic around setting the field in a single method. Be careful with this as a more complicated setter may call on other instance fields that have not yet been initialised. Normally, the constructor code is self-contained and would only call other constructors or static methods (we’ll look at these shortly).

\n\n

However, the changeName method may have been best to use setName rather than changing the field directly. This would allow me to centralise any associated logic.

\n\n

If you do need to provide some checks or other logic before allowing a field to be set then it might be worth placing this logic in another (private) method that doesn’t change any instance fields directly. To achieve this, the method’s parameters would cover all of the required items for validation (e.g. private String checkName(name, validNameList)) and return the name (if valid) or throw an exception if the check fails. The code might look something like:

\n\n

private String checkName(name, validNameList) throws IllegalArgumentException {\n    if (name in validNameList) {\n        return name\n    } else {\n        throw new IllegalArgumentException('The name is not in the list of valid\\\n names')\n    }\n}\n

\n\n\n\n

Thanks to Jochen “blackdrag” Theodorou for his guidance on this ↩\n

\n\n\n

\n79. Class Methods and Variables

\n\n

In the preceding chapters we looked at instance properties/fields (variables) and instance methods (including constructors) -\n the components of a class that pertain to individual instantiations of the class. This ensures that each instance\n works against its own state and doesn’t interfere with other instances. There are many times, however, when we want a class to\n provide a method that isn’t bound to an instance or when we want a field/property that is used across instances. This is\n where class methods and class variables are utilised.

\n\n

So, when to use class methods and variables? There’s a number of answers to this but the following three are the main ones:

\n\n

When a single property is best shared across all instances: This is often the case with configuration properties
When a method isn’t really specific to an instance: The method sits nicely with the class’s concepts but doesn’t need to relate directly to each instance
When the class is really just a library of methods and constants: Sometimes you just need a set of utility methods

\n\n

It’s important to note a few things about class methods:

\n\n

They can’t access this as there’s no underlying instance
They can’t use instance (member) variables

\n\n

Declaring a field/property or method as static is easy: you just prepend the static modifier. Lets look at an example:

\n\n

A brief example of class methods and variables

\n\n

import groovy.json.JsonSlurper\n\nclass Configuration {\n    static String databaseName = ''\n    static String databasePassword = ''\n    static String logFile = ''\n\n    static loadConfig() {\n        //This is the config file:\n        File file = new File('config.json')\n\n        //We use JsonSlurper to read a JSON file:\n        JsonSlurper slurper = new JsonSlurper()\n\n        //Now parse the config file\n        def config = slurper.parse(file)\n\n        //We can access the config file elements using dot-point notation:\n        databaseName = config.database\n        databasePassword = config.password\n        logFile = config.log\n\n    }\n}\n\nConfiguration.loadConfig()\n\nprintln \"\"\"\\\n    System database: ${Configuration.databaseName}\n    System database password: ${Configuration.databasePassword}\n    Log file: ${Configuration.logFile}\n\"\"\"\n

\n\n\n\n

The code above provides a common use of static variables as it reads in configuration from a source and makes that\nconfiguration available to the rest of the system. In this case I have chosen to use JSON\nnotation to store the configuration and the file config.json appears thus:

\n\n

config.json

\n\n

{\n  \"database\": \"CorporateData\",\n  \"password\": \"password\",\n  \"log\": \"/tmp/log.txt\"\n}\n

\n\n\n\n

In the Configuration class you can see three class variables: databaseName, databasePassword and logFile. These\nare accessed via the class, and not an instance, by using the <class name>.<variable name> form: Configuration.databaseName.\nI’ve also defined the class method loadConfig and this is accessed through Configuration.loadConfig. You’ll see that\nI don’t have to instantiate Configuration by calling new nor do I assign Configuration to a variable - I just access\n Configurations’s class members when I need them.

\n\n\n\n

I’ve used the String type for the static variables in Configuration but, should I want to use dynamic types, I just\nuse static <varName> and don’t need def:

\n\n

static databaseName = ''\nstatic databasePassword = ''\nstatic logFile = ''\n

\n\n\n\n

Whilst the Configuration class only defines class methods and variables, classes can have a mix of these elements. The\nnext example is more complex:

\n\n

A mix of static and instance elements

\n\n

@Grab('org.javamoney:moneta:1.0')\n\nimport groovy.transform.ToString\nimport org.javamoney.moneta.Money\n\n@ToString(includeNames = true)\nclass SilverCreditCard {\n    String cardNumber\n    String cardHolderName\n    Money balance = Money.of(0, currency)\n\n    static String currency = 'AUD'\n    static Money creditLimit = Money.of(5_000, currency)\n\n    static SilverCreditCard applyForAccount(String applicantName, Money totalAss\\\nets, Money totalDebts) {\n        if (totalAssets.subtract(totalDebts).subtract(creditLimit).isPositive())\\\n {\n            // TODO: Create a new record in the database etc\n            return new SilverCreditCard(cardNumber: '0000 1111 2222 3333', cardH\\\nolderName: applicantName)\n        } else {\n            // TODO: Throw an exception - don't just return null\n            return null\n        }\n    }\n\n    static SilverCreditCard loadAccount(String cardNumber) {\n        // TODO: Lookup the number in our database\n        new SilverCreditCard(cardNumber: cardNumber, cardHolderName: 'Fred Nurk'\\\n, balance: Money.of(100, currency))\n    }\n\n    Money deposit(Money amt) {\n        //TODO: Implement\n    }\n\n    Money withdrawl(Money amt) {\n        //TODO: Implement\n    }\n}\n\nSilverCreditCard yourCard = SilverCreditCard.loadAccount('1234 5678 9876 5432')\nprintln yourCard\n\nSilverCreditCard myCard = SilverCreditCard.applyForAccount('Jim Smith',\n        Money.of(20_000, SilverCreditCard.currency),\n        Money.of(10_000, SilverCreditCard.currency))\n\nprintln myCard\n

\n\n\n\n

Running this code will cause an error to be displayed but don’t panic - it’s just saying that I haven’t provided a\n configuration for the Java money classes. It’s all cool and fine for this example.

\n\n

In the code above I have described a credit card account - the SilverCreditCard. This class uses class\nvariables to describe the policy for the credit card product (bank speak) and class methods for accessing\nindividual accounts (after all, you don’t want people to just new CreditCard do you?):

\n\n

Class variables:\n
- \ncurrency is the currency used by all Silver Credit Cards
- \ncreditLimit is the maximum limit allowed for this type of account
\n
Class methods:\n
- \napplyForAccount is for new customers requesting an account - it would return an instance of SilverCreditCard being the newly created account
- \nloadAccount is for existing customers wanting to access their account - it would return an instance of SilverCreditCard with information loaded from a database
\n

\n\n

The instance elements represent a single customer’s SilverCreditCard account and aid in tracking their account:

\n\n

Instance properties:\n
- \ncardNumber is the unique number for the account
- \ncardHolderName is the name of the card holder
- \nbalance is how much they’ve spent on their credit card
\n
Instance methods:\n
- \ndeposit and withdrawal would let the person use their account
\n

\n\n\n\n

Static initializer blocks

\n\n

Classes don’t have a constructor-style approach that you can use to prepare the class variables for use.\nHowever, there is a static form of the intializer block:

\n\n

A static initializer

\n\n

import groovy.json.JsonSlurper\n\nclass Configuration {\n    static String databaseName = ''\n    static String databasePassword = ''\n    static String logFile = ''\n\n    static {\n        //This is the config file:\n        File file = new File('config.json')\n\n        //We use JsonSlurper to read a JSON file:\n        JsonSlurper slurper = new JsonSlurper()\n\n        //Now parse the config file\n        def config = slurper.parse(file)\n\n        //We can access the config file elements using dot-point notation:\n        databaseName = config.database\n        databasePassword = config.password\n        logFile = config.log\n\n    }\n}\n\nprintln \"\"\"\\\n    System database: ${Configuration.databaseName}\n    System database password: ${Configuration.databasePassword}\n    Log file: ${Configuration.logFile}\n\"\"\"\n

\n\n\n\n

You’ll see that I’ve just moved the earlier loadConfig class method into a static initializer block (static { }).\nThis is probably a good idea as the initializer block is acted on before the class variables are accessed,\nallowing me to make sure that the configuration is ready to go rather than relying on other developers to call loadConfig.\nAdditionally, the initializer block will only be called once so the config file is only read once\n - much more efficient than if loadConfig is called over and over by other code.

\n\n

More on this in Access Modifiers ↩\n

\n\n\n

\n80. Final Variables

\n\n\n\n

The final modifier can be prefixed to a class- or instance-variable declaration so as to declare it to be immutable (something that doesn’t change).\nOnce set, any attempt to change the value will result in a groovy.lang.ReadOnlyPropertyException but you have to be\nmindful of a few gotchas, especially with collections and objects - we’ll cover these shortly.

\n\n

First up, let’s look at the final modifier in action:

\n\n

Class and instance usage

\n\n

class Record {\n    static final String OWNER\n    final Date creationDate\n}\n

\n\n\n\n

In the code above I’ve declared one class variable (owner) and one instance variable (creationDate) as final.\nYou’ll notice that I’ve not actually set the value for these so that’s the next step. I have three options available to\nme when setting the value for a final variable:

\n\n

Option 1: At the point of declaration (class and instance variables):

\n\n

class Record {\n    static final String OWNER = 'Secret Corp'\n    final Date creationDate = new Date()\n}\n\nRecord myRecord = new Record()\n

\n\n\n\n

Option 2: In an initializer block (class and instance variables):

\n\n

class Record {\n    static final String OWNER\n\n    static {\n        owner = 'Secret Corp'\n    }\n\n    final GregorianCalendar creationDate\n\n    ;{\n        creationDate = new GregorianCalendar()\n    }\n}\n\nRecord myRecord = new Record()\n

\n\n\n\n

Option 3: In the constructor (instance variables only):

\n\n

class Record {\n    static final String OWNER = 'Secret Corp'\n\n    final Calendar creationDate\n\n    Record() {\n        creationDate = new GregorianCalendar()\n    }\n\n    Record(GregorianCalendar created) {\n        creationDate = created\n    }\n}\n\nRecord record1 = new Record()\n\nGregorianCalendar created = new GregorianCalendar(2015, 5, 4)\nRecord record2 = new Record(created)\n

\n\n\n\n

Option 1 is usually best for simple assignments (such as a value or a minor expression) and Option 2 is handy if the\nyou need a more complicated expression or set of expressions. The third option is mainly used when the value is passed\nby the client code into the constructor and then assigned to the instance variable either directly or following some evaluations.

\n\n\n\n

Final fields and the map-like constructor

Just remember that the map-like constructor that comes as a Groovy beans bonus won’t help you with final variables.\nThe code below won’t work as Groovy is not setting creationDate in the constructor but through the setter after\ninstantiating the instance:

\n\n

The attempt to use handy built-in approach will fail

\n\n

class Record {\n    final Date creationDate\n}\n\nRecord myRecord = new Record(creationDate: new Date())\n

\n\n\n\n

Final objects

When a variable is marked as final it is the value held by the variable that is immutable. This is fine for primitive values\n(such as int) and some of the elementary classes (such as Integer and String) as their underlying value isn’t changeable once\ninstantiated.\nHowever, if that value points to an object that is mutable (can be changed) then your class might find its variables\nbeing changed by code outside the class. This isn’t a good thing as the class should be managing its own state. Let’s\ntake a look at how this can happen and how we can stop it.

\n\n

First up, let’s consider a class FinalReport that is meant to hold a set of Records for archiving purposes. That means\n that once a FinalReport has been prepared, we don’t want people tampering with it:

\n\n

First stab at a protected report

\n\n

import groovy.transform.ToString\n\n@ToString(includeNames = true)\nclass FinalReport {\n    final List records\n\n    FinalReport(List records) {\n        this.records = records\n    }\n}\n\n@ToString(includeNames = true)\nclass Record {\n    final Date creationDate = new Date()\n    String title\n    String text\n\n    Record(String title, String text) {\n        this.title = title\n        this.text = text\n    }\n}\n\ndef recordSet = [\n        [ 'Record A', 'This is a record' ] as Record,\n        [ 'Record B', 'This is another record' ] as Record,\n        [ 'Record C', 'This is yet another record' ] as Record\n]\n\nFinalReport report = new FinalReport(recordSet)\n\nreport.records[1].text = 'REDACTED'\nprintln report.records[1]\n\nreport.records << new Record('Record Z', 'You just got hacked')\nprintln report\n

\n\n\n\n

First of all you’ll notice the @ToString(includeNames = true) annotation. This is used to have a toString() method\ngenerated for the class. This is really handy and I provide a description in the Useful Annotations chapter.

\n\n

When setting up the FinalReport class I dutifully set final List records so that the list of records is final but\ntwo sections of code just blew a hole in my archive-ready report. The first one altered the text of a record in the report:

\n\n

report.records[1].text = 'REDACTED'\nprintln report.records[1]\n

\n\n\n\n

The second section of code added a new record to the report:

\n\n

report.records << new Record('Record Z', 'You just go hacked')\nprintln report\n

\n\n\n\n

My FinalReport isn’t really very final and is quite open to tampering. This is one reason you write test suites for your code -\nto make sure that you haven’t made an incorrect assumption. Let’s take a look at a more locked-down version of the previous\ncode:

\n\n

Make it all final

\n\n

import groovy.transform.ToString\n\n@ToString(includeNames = true)\nclass FinalReport {\n    final List records\n\n    FinalReport(List records) {\n        this.records = records.asImmutable()\n    }\n}\n\n@ToString(includeNames = true)\nclass Record {\n    final Date creationDate = new Date()\n    final String title\n    final String text\n\n    Record(String title, String text) {\n        this.title = title\n        this.text = text\n    }\n}\n\ndef recordSet = [\n        [ 'Record A', 'This is a record' ] as Record,\n        [ 'Record B', 'This is another record' ] as Record,\n        [ 'Record C', 'This is yet another record' ] as Record\n]\n\nFinalReport report = new FinalReport(recordSet)\n\n//This will fail with groovy.lang.ReadOnlyPropertyException\ntry {\n    report.records[1].text = 'REDACTED'\n} catch (ReadOnlyPropertyException e) {\n    println 'Sorry, you can\\'t change a record in a final report'\n}\n\n//This will fail with java.lang.UnsupportedOperationException\ntry {\n    report.records << new Record('Record Z', 'You just got hacked')\n} catch (UnsupportedOperationException e) {\n    println 'Sorry, you can\\'t add a record to a final report'\n}\n\nprintln report\n

\n\n\n\n

You’ll notice I’ve made a number of changes to really lock things down:

\n\n

All of the properties in Record are now marked as final\n
- This means that Record instances can’t be tampered with post-creation
\n
The records property in FinalReport is still marked as final (final List records)\n
- This means that the records list can’t just be swapped over for another
\n
In the FinalReport constructor I call asImmutable() against the records parameter as this creates a copy of the list and marks it as immutable.\n
- This means that the list can’t have new items added or removed.
\n

\n\n

My first stab at the code assumed that final List records meant that the list of records couldn’t be changed. This is\ntrue to an extent - once records was assigned an instance of a list it couldn’t be assigned another. However, it didn’t mean\nthat the items in the list couldn’t be changed or the list have items added/removed. I needed to make sure that each list item\n(each being a Record instance) was itself locked down by making all of its properties final. I also needed to lock down\nthe list being passed to my constructor by using the asImmutable() method to copy the incoming list and stop it from being changed.

\n\n\n\n

The `@Immutable` annotation

\n\n

As always, Groovy gives me a very handy approach to locking down my classes so that they’re immutable. The @Immutable\nannotation does quite a number of things for me, including:

\n\n

Makes properties final\n
Sets up a map-based constructor and a tuple constructor (as per @TupleConstructor)
Ensures that certain types of parameter (such as Date and collections) are defensively copied
Prepares a toString method (as per @ToString)

\n\n

So here’s how our FinalReport code now looks with the help of @Immutable:

\n\n

Use the @Immutable annotation

\n\n

import groovy.transform.Immutable\n\n@Immutable\nclass FinalReport {\n    final List records\n}\n\n@Immutable\nclass Record {\n    Date creationDate = new Date()\n    String title\n    String text\n}\n\ndef recordSet = [\n        new Record(title: 'Record A', text: 'This is a record'),\n        new Record(title: 'Record B', text: 'This is another record'),\n        new Record(title: 'Record C', text: 'This is yet another record')\n]\n\nFinalReport report = new FinalReport(recordSet)\n\n//This will fail with groovy.lang.ReadOnlyPropertyException\ntry {\n    report.records[1].text = 'REDACTED'\n} catch (ReadOnlyPropertyException e) {\n    println 'Sorry, you can\\'t change a record in a final report'\n}\n\n//This will fail with java.lang.UnsupportedOperationException\ntry {\n    report.records << new Record(title: 'Record Z', text: 'You just got hacked')\n} catch (UnsupportedOperationException e) {\n    println 'Sorry, you can\\'t add a record to a final report'\n}\n\nprintln report\n

\n\n\n\n

You can easily see that the code for my FinalReport and Record classes has been cut right back. This is really\nhelpful in many situations but @Immutable can’t do everything so make sure you read the documentation.

\n\n

Copying and cloning

\n\n

Just wandering a little off the final path, let’s take a quick look at how we could defensively handle mutable objects.\nDefensively copying basic objects such as String and Integers is easy as it happens at assignment time:

\n\n

Integer i = new Integer(10)\nInteger j = i\ni = 20\nassert !i.is(j)\n

\n\n\n\n

This works because i = 20 causes i to be assigned a new instance of Integer. Similarly, I can copy a list\nof numbers quite easily:

\n\n

def yourList = [2, 4, 6]\ndef myList = [*yourList]\n\nassert myList == yourList\nassert !myList.is(yourList)\n

\n\n\n\n

This is all reasonably straight-forward as I’m only dealing with basic objects. However, how do I defensively copy\nan object that consists of several properties/fields? Earlier, I re-programmed the Record class to make all of the\nproperties final and this meant that I didn’t really need to defensively copy instances.\nSometimes I don’t get that option, especially for existing or third-party developed classes. In such cases I have a few\noptions:

\n\n

Don’t copy the whole instance, just extract the fields I actually need and copy them
Create a new instance using the object’s current state as input
Call the clone() method if one exists.

\n\n

The second option is possible if I can use the object’s properties to create another instance via the constructor and/or\nsetters:

\n\n

Use the object’s state to instantiate a copy

\n\n

import groovy.transform.Canonical\n\n@Canonical\nclass Assignment {\n    final String studentName\n    String answers\n}\n\n@Canonical\nclass SubmissionSystem {\n    Map submissions = [:]\n\n    def submitAssignment(Assignment sub) {\n        if (!submissions.get(sub.studentName)) {\n            submissions.put sub.studentName, new Assignment(sub.studentName, sub\\\n.answers)\n        }\n    }\n}\n\nAssignment myAssignment = new Assignment('Fred Nurk', 'I have no idea')\n\nSubmissionSystem system = new SubmissionSystem()\nsystem.submitAssignment(myAssignment)\nprintln system\n\nmyAssignment.answers = 'A really good set of answers'\nprintln system\n

\n\n\n\n

In the code above the submitAssignment method calls the Assignment constructor to create a new instance. This helps\nmake sure that the student can’t mysteriously change their answers after submitting. You can see that it’s a pretty simple\nexample and a more complex classes will make this very difficult, especially if they have internal state that is hard to\nreach.

\n\n

The third option is to have a class implement the Cloneable interface. If a third-party class provides this then you’re\nin luck and can make a copy (clone):

\n\n

Using Cloneable

\n\n

import groovy.transform.Canonical\n\n@Canonical\nclass Assignment implements Cloneable {\n    final String studentName\n    String answers\n\n    @Override\n    protected Assignment clone() throws CloneNotSupportedException {\n        return new Assignment(studentName, answers)\n    }\n}\n\n@Canonical\nclass SubmissionSystem {\n    Map submissions = [:]\n\n    def submitAssignment(Assignment sub) {\n        if (!submissions.get(sub.studentName)) {\n            submissions.put sub.studentName, sub.clone()\n        }\n    }\n}\n\nAssignment myAssignment = new Assignment('Fred Nurk', 'I have no idea')\n\nSubmissionSystem system = new SubmissionSystem()\n\nsystem.submitAssignment(myAssignment)\nprintln system\n\nmyAssignment.answers = 'A really good set of answers'\nprintln system\n

\n\n\n\n

As Assignment provides a clone method we just need to call it and we’re returned a copy for our own use. Naturally,\nthis doesn’t help us if the author of Assignment doesn’t provide us with a clone method.\nCheck out the Useful Annotations chapter for the @Canonical annotation.

\n\n\n\n

Final classes and methods

The final modifier can also be used against class and method declarations. We’ll look into this in the\nchapter on Final Classes

\n\n

\n81. Access Modifiers

Classes are used to embody an abstraction of some real or virtual entity. You can probably guess what a BankAccount or an EmailMessage class embodies. In some cases we might be happy for other code to change a value held in a class instance or to run a method. However, in the case of a BankAccount class we are likely to need some sort of information hiding that moderates what other code is allowed to do:

\n\n

The balance field shouldn’t be directly accessible. Rather, two methods deposit and withdrawal have to be used.
The withdrawal method should not allow you take take out more money than the current balance.

\n\n

In Groovy we can implement the business logic just described through the use of Access Modifiers.

\n\n

Access modifiers are keywords (public, private, protected) that determine if another class can use an element (such as a property, field or method) of the class being described.

\n\n

\npublic elements can be accessed by all other classes and code
\nprivate elements are only accessible from within the class itself
\nprotected elements are only accessible from subclasses and within their own package

\n\n

Two things to keep in mind:

\n\n

Groovy applies public by default so you don’t need to explicitly declare anything as public.
Providing an access modifier means that def isn’t needed when you’re using dynamic types:\n
- \nprivate balance = 0 is preferred over private def balance = 0\n
- Similarly for methods: private applyAccountCharges() {...} rather than private def applyAccountCharges() {...}\n
\n

\n\n

For our BankAccount class we can make the balance field private:

\n\n

A basic BankAccount with information hiding

\n\n

class BankAccount {\n\n    private Integer balance = 0\n\n    Integer withdrawal(amount) {\n        if (amount > balance) {\n            throw new Exception('Insufficient balance')\n        }\n\n        balance -= amount\n    }\n\n    Integer deposit(amount) {\n        balance += amount\n    }\n}\n\ndef acct = new BankAccount()\nacct.deposit(100)\nacct.withdrawal(150)\n

\n\n\n\n

In the example above I set the balance field to private and then provide two public methods to allow for other code to perform a deposit or a withdrawal. The latter method even throws an exception if you try to take out too much.

\n\n

Now here’s “the rub”. Groovy doesn’t actually enforce the access modifier. That means that, given my BankAccount class I could still write acct.balance = 1_000_000 and access the field directly. A Python programmer might shrug at this and state that it’s a matter of respecting the original programmer’s intention. A Java programmer might be shocked that Groovy doesn’t throw an exception or an error.

\n\n\n\n

I’m usually pretty happy with the Python approach but if it was really a concern I could add the following method to my BankAccount class, as seen in the next example:

\n\n

A basic BankAccount with tighter control

\n\n

class BankAccount {\n\n    private Integer balance = 0\n\n    Integer withdrawal(amount) {\n        if (amount > balance) {\n            throw new Exception('Insufficient balance')\n        }\n\n        balance -= amount\n    }\n\n    Integer deposit(amount) {\n        balance += amount\n    }\n\n    private setBalance(amount) {\n\n    }\n}\n\ndef acct = new BankAccount(balance: 200)\nassert acct.balance == 0\n\ndef acct2 = new BankAccount()\nacct.balance = 100\nassert acct2.balance == 0\n

\n\n\n\n

Groovy generates setters and getters for properties but I need provide them for fields. In the case of the balance field, the setter method named setBalance is actually called when I do something like acct.balance = 1_000_000. Knowing this, I overrode the setter Groovy would have created with my own version that does nothing and I also used the private modifier. This does two things:

\n\n

The private modifier reinforces to other developers that they should not try to directly change the value of balance\n
If the other developers just don’t listen then I ignore their attempt to change the balance.

\n\n

Whilst my empty setBalance method helps prove a point, having to do that too often will reduce readability and annoy me with having to write lots of vacant code to protect my code from others who don’t listen. Essentially I take the approach that developers are (usually) sensible people that understand what they’re being asked not to fiddle with. If they fiddle then they can expect a weird outcome. So feel free to write a method with the signature private doSomethingEvil(), add some code that deletes all files and see who doesn’t pay attention :-)

\n\n\n\n

Applying Access Modifiers

The following access modifiers are available:

\n\n

Classes:\n
- public
- protected
\n
Fields\n
- public
- private
- protected
\n
Methods\n
- public
- private
- protected
\n

\n\n

Remember, you don’t need to explicitly declare an element as public as this is the default.

\n\n\n\n

If you want to really get into this topic, start with http://docs.oracle.com/javase/tutorial/essential/environment/security.html ↩\n

\n\n\n

\n82. Useful Annotations

\n\n\n\n

Groovy comes with a number of handy notations that let you easily customise a class without doing the hard work yourself.\nThis chapter will take a brief look at some of the handier annotations in the\ngroovy.tranform package.

\n\n

You can even write your own annotations but that’s something for another book…

\n\n

ToString

\n\n

The toString() method is used to provide a “human readable” representation of the object. It’s available on all\nobjects and you can override it but you can also just use the ToString annotation to make this even easier:

\n\n

The ToString annotation

\n\n

@groovy.transform.ToString\nclass Person {\n    def name\n    def email\n    def mobile\n\n    Person(name) {\n        this.name = name\n    }\n}\n\ndef astrid = new Person('Astrid Smithson')\n\nprintln astrid\n

\n\n\n\n

Instead of using the full library path with @groovy.transform.ToString you can use the import keyword:

\n\n

 import groovy.transform.ToString\n\n @ToString\n class Person {\n \t//...\n }\n

\n\n \n\n

\n\n

ToString takes a few options:

\n\n

\n@ToString(includeNames=true): will add in the property name, prefixing the property value
\n@ToString(includeFields=true): by default, properties are used but this adds in fields

\n\n

You can use several options at once:

\n\n

The ToString annotation with options

\n\n

@groovy.transform.ToString(includeNames=true, includeFields=true)\nclass Person {\n    def name\n    private email\n    private mobile\n\n    Person(name) {\n        this.name = name\n    }\n}\n\ndef astrid = new Person('Astrid Smithson')\n\nprintln astrid\n

\n\n\n\n

EqualsAndHashCode

Determining if two instances are equal is something you have to add in yourself. Groovy will agree that two\nvariables are the same if they point to the same instance of a class:

\n\n

def agentSmith1 = new Person(id: 411, name: 'Agent Smith')\ndef agentSmith2 = agentSmith1\nassert agentSmith1 == agentSmith2\n

\n\n\n\n

However, this isn’t Groovy being clever, it’s just seeing that agentSmith1 and agentSmith2 point to the same thing.\nIn the code below you’ll see that a Person instance with the same id and name as another Person instance doesn’t\nautomatically equate to them being equal:

\n\n

Same, same but not equal

\n\n

class Person {\n    def id\n    def name\n}\n\ndef agentSmith1 = new Person(id: 411, name: 'Agent Smith')\ndef agentSmith2 = agentSmith1\ndef agentSmith3 = new Person(id: 411, name: 'Agent Smith')\n\nassert agentSmith1 == agentSmith2\n\n//This will fail\nassert agentSmith2 == agentSmith3\n

\n\n\n\n

By using the EqualsAndHashCode annotation I can tell Groovy that two instances of Person with the same id are actually\nequal:

\n\n

The EqualsAndHashCode annotation

\n\n

@groovy.transform.EqualsAndHashCode(includes='id')\nclass Person {\n    def id\n    def name\n}\n\ndef agentSmith = new Person(id: 414, name: 'Agent Smith')\ndef agentSmith2 = new Person(id: 414, name: 'Agent X')\n\nassert agentSmith == agentSmith2\n

\n\n\n\n

Equality is not always easy to determine and will depend on the context in which you’re developing - my example above\nis likely to cause some debate as to if matching only on id is enough. The EqualsAndHashCode annotation has a few options that are worth digging into.

\n\n\n\n

Canonical

\n\n

The Canonical annotation brings together functionality from a suite of other annotations:

\n\n

ToString
EqualsAndHashCode
TupleConstructor

\n\n

We’ve looked at these previously so let’s jump to an example:

\n\n

The Canonical annotation

\n\n

@groovy.transform.Canonical\nclass Person {\n    def name\n    def email\n    def mobile\n}\n\nPerson phil = new Person('Phil', '041414141')\n\nprintln phil\n

\n\n\n\n

This saves you from needing to stack your annotations:

\n\n

Canonical combines three annotations

\n\n

import groovy.transform.EqualsAndHashCode\nimport groovy.transform.ToString\nimport groovy.transform.TupleConstructor\n\n@ToString\n@EqualsAndHashCode\n@TupleConstructor\nclass Person {\n    def name\n    def email\n    def mobile\n}\n\nPerson phil = new Person('Phil', '041414141')\n\nprintln phil\n

\n\n\n\n

Immutable

\n\n

The Immutable annotation provides similar features as Canonical but locks down new instances so that they can’t be changed after creation.\nImmutable objects can be very useful in systems using parallel processing or caching.

\n\n

You can’t touch this - it will cause an exception

\n\n

@groovy.transform.Immutable\nclass Person {\n    String name\n    String email\n    String mobile\n}\n\ndef krusty = new Person(name: 'Krusty')\nkrusty.email = 'heyhey@example.com'\n

\n\n\n\n

The code above will fail on krusty.email = 'heyhey@example.com' as the Immutable annotation marks the email field as final.

\n\n

\n83. Let Go of That Instance!

\n\n

Sometimes your variable (e.g. a class instance) can end up holding a large amount of data. For example, you might have placed the text of the complete works of Shakespeare into a property. The JVM performs a process called Garbage Collection so as to clean up data that you are no longer using. By assigning a variable to null we flag that the data previously held by the variable is no longer needed:

\n\n

myInstance = null\n

\n\n\n\n

For small Groovy scripts this may never be an issue but, for long running applications, data hanging around and not being used can start to soak up a serious amount of resources, especially memory. Once you’ve finished with a variable it’s worth assigning its value to null to let the JVM know you don’t need it anymore.

\n\n

You don’t always need to explicitly set variables to null - this would make your code far less readable. The JVM knows that once a variable is no longer in scope, it’s no longer accessible and, thus, is no longer needed. This means that if you have a variable declared inside a method, its value is no longer needed once the method has completed. The same goes for variables declared within scopes such as loops. This can get a bit tricky when regarding closures and object references so it’s not all plain sailing.

\n\n

There is an important caveat: if multiple variables refer to the same data then the JVM can only release resources once all references have “unlatched”. Let’s examine this in the code below:

\n\n

Example of multiple references to the same data

\n\n

class SampleText {\n    def text\n}\n\ndef shakespeare = new SampleText(text: 'It was the best of times....')\ndef marlow = shakespeare\nshakespeare = null\nprintln marlow.text\n

\n\n\n\n

I’ve defined a variable (shakespeare) to hold a new instance of the SampleText class and then said that another variable (marlow) points to that instance of SampleText. My call to marlow.text will still work despite my setting shakespeare to null. In this case we say that “marlow still holds a reference to the SampleText instance”. This means that the JVM can’t release the resources held by the instance until all references are set to null. I need to set marlow to null to completely release the resources.

\n\n\n\n

There’s a lot more to garbage collection than I want to cover here but if you spend a few moments searching “Java Garbage Collection” you’ll be able to delve deep into the topic.

\n\n

\n84. Enums

\n\n

Enums are a special type of class that represent an enumerated type\n- they’re used to define one or more constants. Sometimes people use strings for this but they aren’t always the best\noption for checking identifiers and enums are a nicer approach to declaring a set of constants than having lots of\nstatic final variables in a class.

\n\n

Booleans represent an enumerated type¹ that can be true or false but,\nwhilst these are English-language keywords, the boolean value true isn’t a string representing the text “true”:

\n\n

String t = 'true'\nBoolean b = true\n\n//This will fail\nassert t == b\n

\n\n\n\n

So let’s take a look at a very simple enum:

\n\n

A basic enum

\n\n

enum Months {\n    JAN,\n    FEB,\n    MAR,\n    APR,\n    MAY,\n    JUN,\n    JUL,\n    AUG,\n    SEP,\n    OCT,\n    NOV,\n    DEC\n}\n\n// enums help comparisons\nassert Months.JAN != Months.DEC\nassert Months.APR == Months.APR\n\n// enums aren't text strings\nassert Months.OCT != 'Oct'\n\n// Assign a variable to be the value of an enum constant\nMonths myMonth = Months.AUG\n\n// Iterate through the months\nfor (month in Months) {\n    println month\n}\n\n//The values method returns a list of the constants in the enum\nprintln Months.values()\n

\n\n\n\n

First up you’ll see that the enum keyword replaces class. Next, I’ve named the enum Months and provided a set\nof three-letter constants for each of the months in a year - these are the enum’s constants. The enum’s constants are\naccessed using the same approach we use for static variables: Months.JAN. Essentially, the enum’s constant is much the\nsame as a class’s static final variables but the ability to loop through the enum with for (month in Months) {}\nmarks enums as managing a set of constants rather than individual variables/constants.

\n\n

In the line Months myMonth = Months.AUG you’ll see that enums define types but in a manner different to that we saw in classes.\nThe myMonth variable is of the enum type Months but we don’t create the instance by calling Months myMonth = new Months().\nInstead, we assign myMonth to the value of one of the constants as AUG is a constant of type Months.

\n\n\n\n

One more point before moving on, the enum constants don’t have to be declared in upper-case, that’s just the usual approach\nand mirrors how we declared constants using the static final modifiers. It’s a just a standard approach to style rather than\nrequired by the language.

\n\n

Let’s take a look at another example - this time I’ll create a Gender enum and use it in my Person class:

\n\n

Another basic enum

\n\n

import groovy.transform.ToString\n\nenum Gender {\n    MALE,\n    FEMALE\n}\n\n@ToString\nclass Person {\n    String name\n    String email\n    String mobile\n    Gender gender\n}\n\nPerson jane = new Person(name: 'Jane', gender: Gender.FEMALE)\n\nprintln jane\n

\n\n\n\n

There’s probably nothing too new in that example but it helps us take a next step - to give the Gender enum constants a value:

\n\n

Adding to the enum

\n\n

import groovy.transform.ToString\n\nenum Gender {\n    MALE('male'),\n    FEMALE('female')\n\n    final String value\n\n    Gender(value) {\n        this.value = value\n    }\n\n    @Override\n    String toString() {\n        value\n    }\n}\n\n@ToString\nclass Person {\n    String name\n    String email\n    String mobile\n    Gender gender\n}\n\nPerson jane = new Person(name: 'Jane', gender: Gender.FEMALE)\nprintln jane\n

\n\n\n\n

Describing that last example can get a litle tricky so I’m going to step through it.\nFirst of all, I start the enum declaration as you’d expect:

\n\n

enum Gender {\n

\n\n\n\n

Then I list the enum’s constants but they look a little odd. In fact they look like constructor calls:

\n\n

MALE('male'),\nFEMALE('female')\n

\n\n\n\n

Remember how we don’t call new Gender()? That’s because MALE is a analagous to single static instance of the Gender enum and the\ncall MALE('male') is instantiating MALE via the constructor. Importantly, enum constructors are called internally\nby the enum and not from any external source - they’re private to the enum. The constructor is called once for each constant.

\n\n

The next part of the Gender enum, as listed below, declares a member variable (value) and the constructor sets the\nvariable based on the incoming parameter:

\n\n

final String value\n\nGender(value) {\n    this.value = value\n}\n

\n\n\n\n

I have declared value to be final as I don’t want others to change it. Whilst I could drop the final modifier\nit’s not a great idea as enums are generally seen as a constant construct.

\n\n

Lastly, I provide a toString method that helps us when displaying an enum constant:

\n\n

@Override\nString toString() {\n    value\n}\n

\n\n\n\n

The order within an enum is important and you must put the list of constants before any other items. I generally prefer\nto lay them out as follows:

\n\n

Constants
Member variables
Constructors
Methods

\n\n

Enums describe not just a set of constants but their order. Groovy provides the built-in next and previous methods\nthat help step through the constants in an enum. Let’s look at a school grades enum and the result of calling next on each constant:

\n\n

Iterate through an enum

\n\n

enum Grades {\n    FAIL,\n    PASS,\n    CREDIT\n}\n\nprintln Grades.FAIL.next()\nprintln Grades.PASS.next()\nprintln Grades.CREDIT.next()\n

\n\n\n\n

Running this script will yield:

\n\n

PASS\nCREDIT\nFAIL\n

\n\n\n\n

Unfortunately, according to Groovy, the next highest grade after CREDIT is FAIL - the next function just loops back to the first constant.\nThis next version will fix that by overriding the default behaviours for next and previous:

\n\n

Enhancing the enum

\n\n

enum Grades {\n    FAIL,\n    PASS,\n    CREDIT\n\n    def next() {\n        switch (this) {\n            case FAIL:\n                return PASS\n            case PASS:\n                return CREDIT\n            case CREDIT:\n                return CREDIT\n        }\n    }\n\n    def previous() {\n        switch (this) {\n            case FAIL:\n                return FAIL\n            case PASS:\n                return FAIL\n            case CREDIT:\n                return PASS\n        }\n    }\n}\n\nprintln Grades.FAIL.next()\nprintln Grades.PASS.next()\nprintln Grades.CREDIT.next()\n\nprintln Grades.FAIL.previous()\nprintln Grades.PASS.previous()\nprintln Grades.CREDIT.previous()\n

\n\n\n\n

This approach can be really useful when dealing with constants that can be escalated. Think about examples such as\na Priority enum with constants such as LOW, MEDIUM and HIGH or a DeliveryTime enum with NORMAL, PRIORITY and\nEXPRESS.

\n\n\n\n

However, Boolean is a class and extends java.lang.Object. Enums implcitly extend java.lang.Enum.↩\n

\n\n\n

\n85. The `synchronized` modifier

\n\n\n\n

The synchronized keyword is used in concurrent environments in which multiple threads are operating and there’s potential that code running on different threads are interacting on the same section of code. The synchronized modifier is used to indicate that the associated element can only be accessed by one caller at a time. In the code below you’ll see the various applications of synchronized available:

\n\n

Various usage of synchronized

\n\n

class PrizePool {\n\n    synchronized amount\n\n    static synchronized pools\n\n    synchronized calculateTotalPool() {\n        //synchronized code\n    }\n\n    def calculateWinnings() {\n        //non-synchronized code\n        synchronized (this) {\n            //synchronized code\n        }\n        //non-synchronized code\n    }\n\n    static synchronized removePool() {\n        //synchronized code\n    }\n\n    static addPool() {\n        //non-synchronized code\n        synchronized (PrizePool) {\n            //synchronized code\n        }\n        //non-synchronized code\n    }\n}\n

\n\n\n\n

First of all, member and static variables can be marked as synchronized - only one thread can read/write the variable at a time.
Instance and class methods can also be marked as synchronized. Once called by one thread, any other threads are prevented from accessing the method until the first thread’s call has completed.
One or more blocks within an instance or class method can be synchronized¹:\n
- Within an instance method the block is prefixed with synchronized (this) - note the use of an object instance (this)
- For a class method, the block is prefixed with synchronized (PrizePool) - note the use of a class name (PrizePool)
\n

\n\n\n\n

A good starting place for understanding this topic is the Concurrency section of The Java Tutorials. Additionally, the GPars Framework provides a library to assist you in writing concurrent/parallel Groovy and Java code.

\n\n\n\n

Whilst the example blocks use this instance and the PrizePool class, you can use other instances and classes.↩\n

\n\n\n

\nIX More object-oriented programming

\n\n

\n86. Introduction

\n\n

Now that you have a handle on constructing classes we’ll explore the various Groovy constructs for creating a more\nextensible codebase:

\n\n

Interfaces: define a set of method signatures that are then implemented by a class (or classes).
Traits: add abilities to a class
Inheritance: Allows a class to inherit the functionality of another class and extend it.\n
- When ChildClass inherits from ParentClass, we say that ChildClass is a subclass of ParentClass and that ParentClass is a superclass of ChildClass¹.
\n

\n\n

First up, we’ll look at how to organise your code before those classes get out of hand.

\n\n

The Shapes demo

Throughout this section I’ll build up an example library for working with two-dimensional shapes. You’ll see this in chapters with the The shapes demo prefix and a full listing is available as an appendix.

\n\n

As the Shapes demo source code is laid out as a larger project and divided into packages, you won’t be able to run it\nvia groovyConsole.\nTo support you in trying out the demo I’ve setup the shapes demo\nmini site. This provides a number of handy resources:

\n\n

A guide to building (compiling) the code both directly using groovyc and with the Gradle build tool.
Links to download the code
Various reports on the code

\n\n

Once you’ve read through the chapters in this section, head to the shapes demo\n mini site and give it a try.

\n\n

See: Wikipedia: Inheritance (object-oriented programming)↩\n

\n\n\n

\n87. Organising your code

\n\n

When you start writing larger code bases you’ll need to think about how to organise your code. You don’t have to do this\nif you’re using Groovy to write scripts that can fit into a reasonable file size (say, 400 lines) but really large files\ncan become difficult to scroll through and debug. There are two complementary tactics you can use when working with larger\nbodies of code:

\n\n

Break the code into packages
Put the code files into a directory structure that reflects your package structure

\n\n

We’ll start by looking at packages and then move onto directory structures.

\n\n

Packages

Code that doesn’t specify a package is said to be in the default package. Most of the code we’ve looked at so far\nhas been lacking a specific package and is automatically put into the default package - this is perfectly fine for small applications and scripts.\nHowever, once you start to build larger codebase you’ll want to start breaking your classes, enums, interfaces etc into\nseparate files and collect them into packages.

\n\n

The generally agreed approach to structuring larger codebases is to:

\n\n

Declare one structure (e.g. class, interface, enum) per file
Name the file after the structure declared in the file. For example, if you declare class Person{...} then name the file Person.groovy\n
Place these files into one or more packages

\n\n

Following this approach will help you avoid a mess of files that makes it hard to debug problems later.

\n\n

Let’s take a look at a basic example in which I have a script that declares a Person class and then tries to do something\nwith it:

\n\n

First attempt at Person.groovy - will fail

\n\n

package mypackage\n\nclass Person {\n    def name = ''\n}\n\ndef jim = new Person()\nprintln jim.name\n

\n\n\n\n

If I put the above script into a file named Person.groovy and try to run it with groovy Person.groovy\nit will give me the following error:

\n\n

org.codehaus.groovy.control.MultipleCompilationErrorsException: startup failed:\nPerson.groovy: 3: Invalid duplicate class definition of class mypackage.Person :\\\n The source Person.groovy contains at least two definitions of the class mypacka\\\nge.Person.\nOne of the classes is an explicit generated class using the class statement, the\\\n other is a class generated from the script body based on the file name. Solutio\\\nns are to change the file name or to change the class name.\n @ line 3, column 1.\n   class Person {\n   ^\n\n1 error\n

\n\n\n\n

Essentially, this is caused by Groovy trying to create a Person class around the def jim = new Person() - Groovy\nassumes that you want to create a class with the same name as the file but you have already declared a Person class in the file.

\n\n

If we’re following the rule of “One structure per file”, we should only declare the Person class in Person.groovy:

\n\n

Second attempt at Person.groovy - will work

\n\n

package mypackage\n\nclass Person {\n    def name = ''\n}\n

\n\n\n\n

In the same directory we’ll then create Main.groovy and put it into the mypackage.app package as follows:

\n\n

Main.groovy

\n\n

package mypackage.app\n\nimport mypackage.Person\n\ndef jim = new Person(name: 'Jim')\nprintln jim.name\n

\n\n\n\n

Note that I’m actually creating two packages:

\n\n

\nmypackage will contain the Person class
\nmypackage.app will contain the Main class

\n\n

As Person isn’t in the same package as Main, we need to import it using the fully qualified name for the Person\nclass: mypackage.Person.

\n\n

Compiling and running

Now that you have a Person.groovy file and a Main.groovy file you can run

\n\n

groovyc Main.groovy Person.groovy\n

\n\n\n\n

to compile the two files¹. Once groovyc has completed you’ll notice the following:

\n\n

A mypackage subdirectory has been created and contains Person.class\n
A mypackage/app subdirectory has been created and contains Main.class\n

\n\n

If I now run groovy Main I’ll get Jim’s name displayed as I expect but be warned that, whilst this call to groovy is\nusing the compiled Person class, it is actually using the Main.groovy file and not the compiled version. In most cases\nyou would keep Main.groovy as a script and not worry about putting it into a package - this is just for demonstration\npurposes.

\n\n

You can run your compiled Groovy classes using Java by doing the following:

\n\n

Download the groovy-all jar into the directory containing the mypackage subdirectory.
Now run java -cp groovy-all-2.4.4.jar:. mypackage.app.Main\n

\n\n

Short form: groovyc *.groovy↩\n

\n\n\n

\n88. Naming your packages

\n\n

If all Groovy and Java programmers just relied on the default package or mypackage it’d be almost impossible to\nshare code as it’s extremely likely more than one Person class would be created. The package naming convention helps to avoid this and there are two key elements to remember:

\n\n

Package names are written in lower-case to avoid clashing with elements such as class names.
It is recommended that a reversed domain name is used as the base package name

\n\n

The first point is straight-forward so let’s explore the second. If you or the company you work for own a domain name,\nyou basically just reverse it and then prefix specific package names. For example, as I own the groovy-tutorial.org\ndomain I should use:¹

\n\n

org.groovy_tutorial.mypackage\n

\n\n\n\n

I would use org.groovy_tutorial as the basis and then start with a prefix that reflects a project or library name for\n which I’m developing (e.g. org.groovy_tutorial.shapes). If I didn’t own a domain I could have used the name\n of the site on which my code is hosted:

\n\n

com.github.groovy_tutorial.shapes_demo\n

\n\n\n\n

I’m not pretending to own github.com but I’ve also included the organisation name and project name to ensure uniqueness.

\n\n

One final point to remember is that your chosen package name needs to be based on something that’s not likely to change\nand isn’t pinned to a single person. I’ve seen email addresses used (e.g. com.gmail.example) but this isn’t the best idea.\nJust take a moment before committing to a package name - you’ll thank yourself if the code is still going in five years.

\n\n

I’ve converted the hyphen (-) to an underscore (_) as package names can’t contain a hyphen (and domain names can’t contain an underscore).↩\n

\n\n\n

\n89. Packages and directory structure

Groovy is very forgiving and I can put all of my code files in a single directory, regardless of which package I say they’re\nin. This, however, is poor practice and I should create a directory structure that mirrors my package structure. In the last\nexample I had two packages, mypackage and the sub-package mypackage/app and, when compiled, the following directory structure\nappeared:

\n\n

mypackage/\n├── Person.class\n└── app\n    └── Main.class\n

\n\n\n\n

This structure reflects the one I should be using in my source:

\n\n

mypackage\n├── Person.groovy\n└── app\n    └── Main.groovy\n

\n\n\n\n

Here’s the logic:

\n\n

\nPerson.groovy is in the mypackage package so I create a mypackage directory and put Person.groovy in there
\nMain.groovy is in the mypackage.app package:\n
1. As app is a subpackage of mypackage so I should create an app subdirectory under mypackage and place Main.groovy there.
\n

\n\n\n\n

Once I’ve shuffled the files into the new structure I can compile them with:

\n\n

groovyc -d classes mypackage/Person.groovy mypackage/app/Main.groovy\n

\n\n\n\n

You’ll find the compiled class files in the classes directory (as set by the -d switch).

\n\n

At this point you’re probably thinking that having to individually name all of the directories in a large codebase\nis going to be unwieldy and you’re absolutely correct. Once you get beyond a few files you’ll turn to a build system\nsuch as Gradle.

\n\n

\n90. The Shapes demo - packages

\n\n

You’ll find the following packages in the shapes demo source code:

\n\n

org.groovy_tutorial.shapes
org.groovy_tutorial.shapes.triangle
org.groovy_tutorial.shapes.app

\n\n

These are all organised under the src/main/groovy directory:

\n\n

└── org\n    └── groovy_tutorial\n        └── shapes\n            ├── Circle.groovy\n            ├── Rectangle.groovy\n            ├── ShapeUtil.groovy\n            ├── Sides.groovy\n            ├── Square.groovy\n            ├── Triangle.groovy\n            ├── TwoDimensionalShape.groovy\n            ├── app\n            │   ├── Main.groovy\n            │   └── package-info.groovy\n            ├── package-info.groovy\n            └── triangle\n                ├── TriangleEquilateral.groovy\n                ├── TriangleIsosceles.groovy\n                ├── TriangleRightAngled.groovy\n                ├── TriangleSubtype.groovy\n                └── package-info.groovy\n

\n\n\n\n

Within each package’s folder you’ll notice a package-info.groovy file. This isn’t a script but the documentation for the\npackage. The groovydoc system will use this file when preparing the application’s documentation.\nFor further information, please check out the JavaDoc documentation section on “Package Comment Files”.

\n\n

\n91. Interfaces

\n\n\n\n

Interfaces provide a set of method signatures that are intended to be implemented by classes - they are an extremely useful construct that allows you to define a “contract” between your code and other developers.

\n\n

Let’s take a look at an example:

\n\n

An interface declaration

\n\n

interface SocialNetwork {\n    Member friend(Member friend)\n    Member unFriend(Member enemy)\n}\n

\n\n\n\n

The syntax looks much like that of a class but you’ll notice two key differences:

\n\n

The keyword interface is used to declare an interface
There are two method signatures (friend and unFriend) but I haven’t provided the code body for the method

\n\n

That last point is an important one: interfaces don’t define implementations, they are used to define an API that is implemented\n by one or more classes. Well thought out interfaces are integral to code that can be reused and maintained over time.\n Some developers will start a new coding effort by determining the interfaces they’ll need by asking “what elements will interact and how?”.

\n\n\n\n

An interface can’t be instantiated (e.g. SocialNetwork network = new SocialNetwork()) as it doesn’t actually do (implement) anything.\nIn order to implement an interface, the implements keyword, followed by the interface’s name, is used in the class declaration:

\n\n

Implementing the interface

\n\n

class Member implements SocialNetwork {\n    String name\n    def friends = [] as Set\n\n    @Override\n    Member friend(Member friend) {\n        friends << friend\n        friend\n    }\n\n    @Override\n    Member unFriend(Member enemy) {\n        friends -= enemy\n        enemy\n    }\n}\n

\n\n\n\n

In class Member implements SocialNetwork we bind the Member class to the SocialNetwork interface. This then means that\nthe class needs to provide implementations of the friend and unFriend methods. In the example above you’ll note that I’ve\nannotated each implemented method with @Override. This indicates to the Groovy compiler that those two methods are related to\nmethod signatures from an interface that is being implemented¹.

\n\n

Groovy (and Java) classes can implement more than one interface by listing them after the implements keyword - just\n use a comma (,) between each interface:

\n\n

Implementing more than one interface

\n\n

interface SocialNetwork {\n    Member friend(Member friend)\n    Member unFriend(Member enemy)\n}\n\ninterface Posts {\n    Map getPosts()\n    void addPost(String title, String body)\n}\n\nclass Member implements SocialNetwork, Posts {\n    String name\n    def friends = [] as Set\n    Map posts = [:]\n\n    @Override\n    Member friend(Member friend) {\n        friends << friend\n        friend\n    }\n\n    @Override\n    Member unFriend(Member enemy) {\n        friends -= enemy\n        enemy\n    }\n\n    @Override\n    void addPost(String title, String body) {\n        posts << [title: body]\n    }\n}\n

\n\n\n\n\n\n

I’ve provided a full code listing of the example below so that you can take this for a test spin in the groovyConsole:

\n\n

Full code listing plus usage

\n\n

interface SocialNetwork {\n    Member friend(Member friend)\n    Member unFriend(Member enemy)\n}\n\ninterface Posts {\n    Map getPosts()\n    void addPost(String title, String body)\n}\n\nclass Member implements SocialNetwork, Posts {\n    String name\n    def friends = [] as Set\n    Map posts = [:]\n\n    @Override\n    Member friend(Member friend) {\n        friends << friend\n        friend\n    }\n\n    @Override\n    Member unFriend(Member enemy) {\n        friends -= enemy\n        enemy\n    }\n\n    @Override\n    void addPost(String title, String body) {\n        posts << [title: body]\n    }\n}\n\ndef jim = new Member(name: 'Jim')\ndef gina = new Member(name: 'Gina')\ndef andrew = new Member(name: 'Andrew')\n\njim.with {\n    println 'Jim makes some friends: '\n    friend(gina)\n    friend(andrew)\n    friends.each { println \" - $it.name\" }\n\n    println '\\nJim makes an enemy of Andrew'\n    unFriend(andrew)\n\n    println '\\nJim now has these friends: '\n    friends.each { println \" - $it.name \" }\n\n    println '\\nAdding a post'\n    addPost('My weekend', 'Just hung out and stuff')\n    println getPosts()\n}\n

\n\n\n\n

It’s also used for methods overriding those declared in a superclass.↩\n

\n\n\n

\n92. Referring to objects by their interface

An interface defines functionality rather than state. In many cases you just want to interact with a specific\nset of an object’s functionality and referring to the interface rather than a specific class can make your code more adaptable.\nTwo interfaces, java.util.Map and java.util.List, come to mind when considering this:

\n\n

\njava.util.Map is implemented in a range of classes:\n
- \njava.util.Properties is used when reading and writing property files
- \njava.util.LinkedHashMap retains the order in which keys are inserted (and is used when you def myMap = [:])
- \njava.util.concurrent.ConcurrentHashMap provides for full concurrency in retrievals and updates
\n
\njava.util.List\n
- \njava.util.ArrayList provides a resizable array (and is used when you def myList = [])
- \njava.util.Stack is a last-in-first-out (LIFO) stack
\n

\n\n

So whilst I might choose a specific implementation class for my variable because of a need such as speed or concurrency,\nother parts of my code may be more interested in the interface level (e.g. java.util.Map).\nWhen declaring a variable I can provide an interface as the data type, e.g. Map posts = [:]. This means that I don’t\nreally care which implementation of Map is assigned to posts, I’ll only be accessing the methods declared by Map\n(e.g. keySet). In a slightly more convoluted example, Posts p = new Member() indicates that the variable p is only\ninterested in the Member object’s Posts functionality.

\n\n

Whilst handy for variable declaration, referring to interfaces when defining method parameters is extremely useful as it\n makes the method more abstract. Consider a method that will accept a Map parameter and iterate through it:

\n\n

def displayKeys(Map m) {\n    for (key in m.keySet()) {\n        println key\n    }\n}\n\ndef myMap = [name: 'Bill', id: '1234']\n\ndisplayKeys myMap\n

\n\n\n\n

It’s a rather useless example but the point is that the displayKeys method can accept any value for parameter m,\nprovided m is an instance of a class that implements the Map interface. If I’d been specific and written the method\nsignature as def displayKeys(LinkedHashMap m), my method has a far narrower field of usage. As I’m just using the Map\ninterface’s keySet method, I don’t really need to limit the possible values for m.

\n\n

Obviously, if you want/need to constrain usage to a specific implementation, you would declare that as the data type for the parameter.\nIf the method needed the storeToXML functionality of java.util.Properties then I’d need to use that instead of\njava.util.Map - just take a moment to make sure it’s really required.

\n\n

\n93. General advice for interfaces

\n\n

Groovy interfaces don’t allow default methods

\n\n

Java interfaces allow you to provide implementation for a method. Such methods are referred to as “default methods”\nas any implementing class doesn’t have to provide their own implementation. This might be helpful when an interface\nneeds to be updated/improved as it saves having to go through an existing codebase and providing the implementation.\nHowever, it’s also a bit of a trap as that approach “wedges” in functionality that may not really fit the implementing\nclasses (and their subclasses).

\n\n

Groovy’s traits gives you a neater approach to this.

\n\n

The constant interface antipattern

\n\n

In my earlier examples I omitted the fact that you can declare constants in an interface. At first glance this might\nsound like I’ve denied a useful piece of functionality but, in reality, the declaration of constants inside an interface\nisn’t a good idea. Consider the following example:

\n\n

Don’t do this

\n\n

interface SocialNetwork {\n    static final MAX_FRIENDS = 100\n\n    Member friend(Member friend)\n    Member unFriend(Member enemy)\n}\n

\n\n\n\n

The example above provides a strong example as to how this is a bad idea as MAX_FRIENDS really is an implementation detail\nand, furthermore, the interface construct doesn’t let us actually enforce the logic. The SocialNetwork interface\nrelies on implementing classes to make the link.

\n\n

If you focus your interfaces on providing method signatures, your code will be easier to maintain. When you need to define\nconstants, consider the following alternatives:

\n\n

For enumerated constants, definitely use an enum\n
If the constant is part of a class’s logic, declare the constant with the class
Consider creating a utility class that defines general constants of use in your program

\n\n

\n94. The Shapes demo - Interfaces

\n\n

One interface is defined within the shapes library: TwoDimensionalShape:

\n\n

The TwoDimensionalShape interface

\n\n

package org.groovy_tutorial.shapes\n\n/**\n * An interface for basic two-dimensional objects\n *\n * @see <a href=\"https://en.wikipedia.org/wiki/List_of_two-dimensional_geometric\\\n_shapes\">\n *     Wikipedia: List of two-dimensional geometric shapes</a>\n *\n * @author Duncan Dickinson\n */\ninterface TwoDimensionalShape {\n\n    /**\n     * The length of the path surrounding a 2D shape\n     * @see <a href=\"https://en.wikipedia.org/wiki/Perimeter\">Wikipedia: Perimet\\\ner</a>\n     * @return the perimeter of the shape\n     */\n    BigDecimal getPerimeter()\n\n    /**\n     * The extent of a 2D shape in a plane\n     * @see <a href=\"https://en.wikipedia.org/wiki/Area\">Wikipedia: Area</a>\n     * @return the area of the shape\n     */\n    BigDecimal getArea()\n\n    /**\n     * A handy display string\n     * @return a text representation of the shape\n     */\n    String getDisplayInfo()\n\n    /**\n     * @return the name of the shape\n     */\n    String getShapeName()\n}\n

\n\n\n\n

The interface is declared using the interface keyword followed by the name: interface TwoDimensionalShape.\nWithin the interface is the following method signatures:

\n\n

\nBigDecimal getPerimeter(): will return the shape’s perimeter
\nBigDecimal getArea(): will return the shape’s area
\nString getDisplayInfo(): is used to prepare a handy description of the shape
\nString getShapeName(): returns the name of the shape (e.g. square or circle)

\n\n

Each method signature is listed without a definition block ({...}) and it is up to the implementing class(es) to provide the “body” of the definition. The Circle class does just that:

\n\n

The Circle class

\n\n

package org.groovy_tutorial.shapes\n\nimport static java.lang.Math.PI\n\nimport groovy.transform.EqualsAndHashCode\nimport groovy.transform.ToString\n\n/**\n * Describes a circle\n * @author Duncan Dickinson\n */\n@EqualsAndHashCode(includes = 'radius')\n@ToString(includeNames = true, includeFields = true, includePackage = true)\nfinal class Circle implements TwoDimensionalShape {\n    private static final String SHAPE_NAME = 'Circle'\n\n    /** The radius of the circle */\n    final BigDecimal radius\n\n    /** The circle's perimeter (circumference) */\n    final BigDecimal perimeter\n\n    /** The circle's area */\n    final BigDecimal area\n\n    /**\n     *\n     * @param radius the radius of the circle (must be a positive number)\n     * @throws IllegalArgumentException if radius <= 0\n     */\n    Circle(BigDecimal radius) throws IllegalArgumentException {\n        ShapeUtil.checkSidesException(radius)\n        this.radius = radius\n        this.perimeter = calculatePerimeter(radius)\n        this.area = calculateArea(radius)\n    }\n\n    /**\n     * Helper function - defers to calculatePerimeter\n     * @see #calculatePerimeter(Number)\n     * @param radius\n     * @return the circumference (perimeter)\n     * @throws IllegalArgumentException if radius <= 0\n     */\n    static BigDecimal calculateCircumference(Number radius) throws IllegalArgume\\\nntException {\n        calculatePerimeter(radius)\n    }\n\n    /**\n     * Calculates the perimeter of a circle using the formula: p = 2*Pi*r\n     * @param radius\n     * @return the perimeter\n     * @throws IllegalArgumentException if radius <= 0\n     */\n    static BigDecimal calculatePerimeter(Number radius) throws IllegalArgumentEx\\\nception {\n        ShapeUtil.checkSidesException(radius)\n        (2 * PI * radius) as BigDecimal\n    }\n\n    /**\n     * Calculates the area of a circle using the formula: a = Pi*r^2\n     * @param radius\n     * @return the area\n     * @throws IllegalArgumentException if radius <= 0\n     */\n    static BigDecimal calculateArea(Number radius) throws IllegalArgumentExcepti\\\non {\n        ShapeUtil.checkSidesException(radius)\n        (PI * radius**2) as BigDecimal\n    }\n\n    /**\n     * Calculates the circle's diameter using the formula: d = 2r\n     * @param radius\n     * @return the diameter\n     * @throws IllegalArgumentException if radius <= 0\n     */\n    static BigDecimal calculateDiameter(Number radius) throws IllegalArgumentExc\\\neption {\n        ShapeUtil.checkSidesException(radius)\n        (radius * 2) as BigDecimal\n    }\n\n    @Override\n    String getDisplayInfo() {\n        \"$SHAPE_NAME: radius = $radius; diameter = $diameter; \\\ncircumference = ${circumference}; area = ${area}\"\n    }\n\n    /**\n     * Just a convenience - equivalent to getPerimeter\n     * @return the circumference\n     */\n    BigDecimal getCircumference() {\n        perimeter\n    }\n\n    /**\n     * A pseudo getter\n     * @return the diameter\n     */\n    Number getDiameter() {\n        calculateDiameter(this.radius)\n    }\n\n    @Override\n    String getShapeName() {\n        SHAPE_NAME\n    }\n}\n

\n\n\n\n

You’ll notice that the Circle class doesn’t explicitly provide an implementation for getPerimeter() and\ngetArea() as Groovy will generate these for the member fields.

\n\n

\n95. Traits

\n\n\n\n

Where classes can be used to describe real or virtual “things”, traits provide a construct for describing an ability or a set of related abilities. Let’s consider two contexts in which we might use traits:

\n\n

Using a class we might describe an Animal in terms of its features (diet, distribution) and then enhance the Animal with traits such as Hopping (for a wallaby) or Climbing (for a koala) or both (for a tree kangaroo).
A BankAccount class would have its properties (balance, accountHolder) but different accounts provides different abilities (or a combination thereof) such as Deposit, Overdraft or CurrencyConversion.

\n\n

It’s sometimes difficult to determine where a set of methods might instead be better grouped as a trait but the following may help your decision making:

\n\n

If the methods describe an ability or feature that is common to a variety of classes they’re a good candidate for a trait\n
- Even if this is at the abstract level and would need to be more specific for subtypes¹ - a wallaby hops differently to a frog.
\n
Where the various methods manipulate properties or fields that are otherwise not accessed or only read by the class.

\n\n

Let’s take a look at an example trait:

\n\n

A basic trait example

\n\n

trait Running {\n    void startEvent() {\n        println 'Ready, set, go!'\n    }\n}\n\nclass SportingEvent implements Running {\n    String name\n}\n\nSportingEvent stawellGift = new SportingEvent(name: 'The Stawell Gift')\n\nprintln \"Welcome to $stawellGift.name\"\nstawellGift.startEvent()\n

\n\n\n\n

This type of layout is much as we saw for class and interface definitions:

\n\n

The declaration starts with the trait keyword followed by the trait’s name
We use the CamelCase format for the trait’s name - as we did for classes and interfaces
Similar to a class, the body of the trait then provides the required properties, fields and methods\n
- In the Running trait you can see that there’s only one method declared: startEvent().
\n

\n\n

When it comes to use the trait in a class, the implements key is used: class SportingEvent implements Running. The class declaration can implement zero or more traits in the same way it can implement zero or more interfaces. In fact, a class declaration can implement a mix of traits and interfaces as can be seen in the snippet below:

\n\n

class SportingEvent implements SafetyCheck, Running, Swimming {...}\n

\n\n\n\n

At a guess, the Running and Swimming elements are traits and the SafetyCheck element could be a trait or an interface - we’d need to check the source code or groovydoc.

\n\n

We’ll look into this further in the chapter on Inheritance.↩\n

\n\n\n

\n96. Trait properties and fields

Traits can also declare properties:

\n\n

A trait with a property

\n\n

trait Running {\n    Integer distance\n\n    void startEvent() {\n        println 'Ready, set, go!'\n    }\n}\n\nclass SportingEvent implements Running {\n    String name\n}\n\nSportingEvent stawellGift = new SportingEvent(name: 'The Stawell Gift', distance\\\n: 120)\n\nprintln \"Welcome to $stawellGift.name - a ${stawellGift.distance}m race\"\nstawellGift.startEvent()\n

\n\n\n\n

As you can see in the example above, the Running trait’s distance property essentially becomes a property of the SportingEvent class. As for classes, getters and setters are generated for properties but you can supply your own if you need additional functionality.

\n\n

Member variables

Trait member variables (fields/properties) cannot use prefix or postfix operators (++ & --) in such a way that they change the value of the variable. You’ll need to use the compound assignment operators (+= & -=) instead.\nAttempting the code below will cause a compilation error:

\n\n

   trait Counting {\n       Number value = 1\n\n       def increment() {\n           value++\n       }\n   }\n

\n\n \n\n

\n\n

Fields within traits are somewhat different to those in classes. This can get a bit tricky so let’s lay out the example code first:

\n\n

A trait with fields

\n\n

trait Running {\n\n    Integer distance\n\n    public String raceType = 'foot race event'\n\n    private Integer maxCompetitors = 10\n\n    void startEvent() {\n        println 'Ready, set, go!'\n    }\n\n}\n\nclass SportingEvent implements Running {\n    String name\n\n    String describeEvent() {\n        \"This is a ${Running__raceType} for ${Running__maxCompetitors} competito\\\nrs\"\n    }\n}\n\nSportingEvent dash = new SportingEvent()\n\nassert dash.Running__raceType == 'foot race event'\nassert dash.Running__maxCompetitors == 10\n\ndash.Running__maxCompetitors = 99\nassert dash.Running__maxCompetitors == 99\n\nprintln dash.describeEvent()\n

\n\n\n\n

In the Running trait above you can see:

\n\n

One property (as before): Integer distance\n
A public field: public String raceType = 'foot race event'\n
A private field: private Integer maxCompetitors = 10\n

\n\n

Unlike properties, we cannot refer to a field as though it was a member of the SportingEvent class. In order to access the public and private fields I need to call dash.Running__raceType and dash.Running__maxCompetitors respectively. This notation uses the trait’s fully qualified name followed by two underscores then the field: <PackageName>_<TraitName>__<fieldName> and is needed both in the implementing class and external code.

\n\n

The fully qualified name format is a bit odd but, as we’ve looked at packages earlier it should be possible to clarify this:

\n\n

For a trait that is in the default package (i.e. not explictly put in a package), we just need <TraitName>__<fieldName> - as seen in Running__raceType\n
For a trait in a package, each package level is separated by an underscore (_):\n
- If Running was declared in the events package: events_Running__raceType\n
- If Running was declared in the events.track package: events_track_Running__raceType\n
- and so on…
\n

\n\n\n\n

\n97. Trait methods

Trait-defined methods are much the same as we saw with classes but the private access modifier prevents us from calling a trait’s private methods. In the example below, the call to the private SportingEvent.rigWinner method (race.rigWinner()) will work but the call to the Running trait’s private method (race.slow()) will cause a groovy.lang.MissingMethodException:

\n\n

Private methods

\n\n

trait Running {\n    void startEvent() {\n        println 'Ready, set, go!'\n    }\n\n    private String slow() {}\n}\n\nclass SportingEvent implements Running {\n    String name\n\n    private String rigWinner() {\n        'We know that Jane will win this'\n    }\n}\n\nSportingEvent race = new SportingEvent(name: 'The Dodgy Race')\n\nprintln \"Welcome to $race.name\"\nprintln race.rigWinner()\nrace.slow()\n

\n\n\n\n

\n98. Trait static members

As demonstrated in the example below, traits can have static properties, fields and methods:

\n\n

Traits and static members

\n\n

trait Running {\n    static final MAX_DISTANCE = 10_000\n\n    static public final MAX_COMPETITORS = 12\n\n    static describeRules() {\n        println 'Here are the rules of running....'\n    }\n}\n\nclass SportingEvent implements Running {\n\n}\n\nassert SportingEvent.MAX_DISTANCE == 10_000\n\nassert SportingEvent.Running__MAX_COMPETITORS == 12\n\nSportingEvent.describeRules()\n

\n\n\n\n

Accessing a static property: SportingEvent.MAX_DISTANCE\n
Accessing a static field: SportingEvent.Running__MAX_COMPETITORS\n
Accessing a static method: SportingEvent.describeRules()\n

\n\n

Static member support doesn’t appear to be “fully baked” at this time so it’s a good idea to keep an eye on the Groovy documentation.

\n\n

\n99. The class-trait relationship

When a trait is implemented by a class, the relation can be seen as the trait is “folded” into the implementing class. We saw this when we called the SportingEvents constructor and could see the Running trait’s properties. Because of this relationship, traits can refer to this to access instance members.

\n\n

The code below reveals that a trait’s class is that of the implementer:

\n\n

Uncover the mystery

\n\n

trait MyTrait {\n    Class whoIsThis() {\n        this.class\n    }\n}\n\nclass MyClass implements MyTrait {}\n\nassert new MyClass().whoIsThis() == MyClass\n

\n\n\n\n

In the next example you can see this being used internal to the trait (this.distance = distance) and the class (${this.name}) but also from the class into the trait (${this.distance}):

\n\n

Traits and this, again

\n\n

trait Running {\n    Integer distance\n\n    void setDistance(distance) {\n        if (distance > 10_000) {\n            throw new IllegalArgumentException('Surely you can\\'t run that far')\n        }\n        this.distance = distance\n    }\n}\n\nclass SportingEvent implements Running {\n    String name\n\n    def getAdvert() {\n        \"${this.name} is a ${this.distance}m event\"\n    }\n}\n\nSportingEvent groovySprint = new SportingEvent(name: 'The Groovy 500', distance:\\\n 500)\nprintln groovySprint.advert\n

\n\n\n\n

Self types

That last example could have been rewritten such that the getAdvert() method is declared in the trait (rather than the class):

\n\n

Traits and this

\n\n

trait Running {\n    Integer distance\n\n    void setDistance(distance) {\n        if (distance > 10_000) {\n            throw new IllegalArgumentException('Surely you can\\'t run that far')\n        }\n        this.distance = distance\n    }\n\n    def getAdvert() {\n        \"${this.name} is a ${this.distance}m event\"\n    }\n}\n\nclass SportingEvent implements Running {\n    String name\n}\n\nSportingEvent groovySprint = new SportingEvent(name: 'The Groovy 500', distance:\\\n 500)\nprintln groovySprint.advert\n

\n\n\n\n

This works fine as SportingEvent has a name property but there’s nothing enforcing this and you’re exposed to the risk of a groovy.lang.MissingPropertyException being raised at runtime if the method/property/field can’t be found.

\n\n

The @groovy.transform.SelfType annotation is used if a trait needs to be tied to a specific implementing class. The example below demonstrates the Running trait annotated with @SelfType(SportingEvent), indicating that the trait should only by implemented by SportingEvent (or one of its subclasses):

\n\n

The @SelfType annotation

\n\n

import groovy.transform.SelfType\n\n@SelfType(SportingEvent)\ntrait Running {\n    Integer distance\n\n    void setDistance(distance) {\n        if (distance > 10_000) {\n            throw new IllegalArgumentException('Surely you can\\'t run that far')\n        }\n        this.distance = distance\n    }\n\n    def getAdvert() {\n        \"${this.name} is a ${this.distance}m event\"\n    }\n}\n\nclass SportingEvent implements Running {\n    String name\n}\n

\n\n\n\n

By setting @SelfType(SportingEvent) we can ensure that Groovy will refuse to compile the following attempt:

\n\n

class Imposter implements Running {}\n

\n\n\n\n

Just be mindful with this capability - you want to make sure that you aren’t coupling your classes and traits too much. Thankfully, @SelfType can also be passed an interface, allowing for a more broadly implemented trait.

\n\n

\n100. Traits and interfaces

As Groovy’s interfaces don’t support default implementations it may be tempting to favour traits. This isn’t a good idea and you should try to describe interactions within your code and with other developers via an API described in interfaces.

\n\n

Once you’ve described your interface, a trait can implement the interface in the same manner as classes do, through the use of the implements keyword:

\n\n

Trait implementing an interface

\n\n

interface Locomotion {\n    String getDescription()\n}\n\ntrait Hopping implements Locomotion {\n    @Override\n    String getDescription() {\n        'hop hop hop'\n    }\n}\n

\n\n\n\n

\n101. Implementing multiple traits

As mentioned earlier, a class can implement more than one trait. This is straight-forward if the traits don’t intersect in terms of members (properties/fields/methods), as is the case in the example below:

\n\n

Simple implementation of two traits

\n\n

trait Hopping {\n    String hop() { 'I am hopping' }\n}\n\ntrait Climbing {\n    String climb() { 'I am climbing' }\n}\n\nclass TreeKangaroo implements Hopping, Climbing {}\n\nTreeKangaroo lumholtz = new TreeKangaroo()\n\nprintln lumholtz.hop()\nprintln lumholtz.climb()\n

\n\n\n\n

There’s nothing too difficult in the TreeKangaroo example but what if the traits had methods with the same name? Let’s belabour the sporting example one last time!

\n\n

I believe that the Triathlon consists of three parts - Running, Swimming, and Riding - and the example below sets up each of these as traits that implement the same interface:

\n\n

Handling trait collision

\n\n

interface Event {\n    void startEvent()\n}\n\ntrait Running implements Event {\n    @Override\n    void startEvent() {\n        println 'Start the running event'\n    }\n}\n\ntrait Swimming implements Event {\n    @Override\n    void startEvent() {\n        println 'Start the swimming event'\n    }\n}\n\ntrait Riding implements Event {\n    @Override\n    void startEvent() {\n        println 'Start the riding event'\n    }\n}\n\nclass Triathlon implements Running, Swimming, Riding {\n\n}\n\nTriathlon competition = new Triathlon()\n\ncompetition.startEvent()\n

\n\n\n\n

It’s easy to see that the Triathlon class now has three possibilities when competition.startEvent() is called. In this scenario, Groovy will use the trait that was declared last - Riding. I’ve listed my traits in the order I want to run the events but I really do want to run all three events.

\n\n

Groovy lets me manually determine how the colliding trait members will be treated. First of all, the Triathlon class will need to provide its own void startEvent() method. Then each trait’s startEvent() method will need to be called using the <TraitName>.super. prefix - e.g. Running.super.startEvent().

\n\n

In the improved Triathlon example below you’ll notice that I’ve decided to implement the Event interface as a triathlon is an event consisting of three events:

\n\n

Manual selection of trait methods

\n\n

class Triathlon implements Event, Running, Swimming, Riding {\n    @Override\n    void startEvent() {\n        Running.super.startEvent()\n        Swimming.super.startEvent()\n        Riding.super.startEvent()\n    }\n}\n

\n\n\n\n

This will now give me the three-stage event I was after.

\n\n

Before leaving this topic, there are some things to note about the example:

\n\n

The traits don’t have to implement the same interface, there just needs to be a collision in one or more of the trait members
I didn’t have to override the startEvent method - I could have used any name - but that would return to Groovy’s default of using the startEvent method of the last trait declared
Use of the <TraitName>.super. prefix doesn’t have to occur just in cases of a collision - you may just use it to clarify a section of code.
Concepts such as overriding and super will be covered more fully in the chapter on Inheritance.

\n\n

\n102. The Shapes demo - Traits

\n\n

The Sides trait is based on the notion that a two-dimensional shape consists of a set of sides (edges). In most cases there’d be at least 3 sides to a 2D shape (circles being the exception with 1 side) and it’s possible to determine a shape’s perimeter by adding up the lengths of the sides. In the Sides trait I wanted to provide classes with the ability to name each side using a single lower-case letter (e.g. a, b, c) and associate the side’s length.

\n\n

Let’s take a look at the code for the Sides trait and then examine its components.

\n\n

The Sides trait

\n\n

package org.groovy_tutorial.shapes\n\n/**\n * A basic trait describing the outer edges (sides) of a 2D shape.\n *\n * This trait uses the missingProperty method to allow implementations\n * to define sides using lower case characters (e.g. a, b, c). These properties \\\nmust:\n * <ul>\n *     <li>Be a single, lower-case character (matching Sides.SIDE_NAME_PATTERN)<\\\n/li>\n *     <li>Be only assigned a positive numeric value</li>\n * </ul>\n *\n * Once getPerimeter is called, the sides map is locked down and can't be modifi\\\ned.\n *\n * @author Duncan Dickinson\n */\ntrait Sides {\n    /** Defines the acceptable naming strategy for sides */\n    static final SIDE_NAME_PATTERN = /[a-z]/\n\n    /** Used to hold the named list of sides */\n    private final Map sideMap = [ : ]\n\n    /** The perimeter, as determined by the sum of the sides */\n    private BigDecimal perimeter = null\n\n    /**\n     * Calculates the perimeter of the shape (once).\n     * After calling this method, the sides are locked down and you can't add or\\\n edit them\n     * via propertyMissing\n     * @return the sum of the sideMap (the perimeter)\n     */\n    BigDecimal getPerimeter() {\n        perimeter = perimeter ?:sideMap.values().sum().toBigDecimal()\n    }\n\n    /**\n     * @return a CLONE of the sideMap\n     */\n    Map getSideMap() {\n        sideMap.clone() as Map\n    }\n\n    /**\n     * Gets the value for a named side\n     * @param name the name of the side (e.g. a, b, c)\n     * @return the value of the side\n     * @throws MissingPropertyException if name not found\n     */\n    def propertyMissing(String name) throws MissingPropertyException {\n        if (name.matches(SIDE_NAME_PATTERN)) {\n            return sideMap.get(name)\n        }\n\n        throw new MissingPropertyException(\"Property $name not found\")\n    }\n\n    /**\n     * Sets the length (value) for a named side\n     * @param name the name of the side\n     * @param value the length of the side\n     * @return the value back to the caller\n     * @throws ReadOnlyPropertyException if the perimeter has been calculated\n     * @throws IllegalArgumentException if the value <= 0\n     * @throws MissingPropertyException if name doesn't match SIDE_NAME_PATTERN\n     */\n    def propertyMissing(String name, value)\n            throws ReadOnlyPropertyException, IllegalArgumentException, MissingP\\\nropertyException {\n        if (name.matches(SIDE_NAME_PATTERN)) {\n            if (perimeter) {\n                throw new ReadOnlyPropertyException(name, Sides)\n            }\n            if (value in Number) {\n                ShapeUtil.checkSidesException(value)\n                sideMap.put(name, value as Number)\n                return sideMap.get(name)\n            }\n            throw new IllegalArgumentException(\"The value [$value] is not a posi\\\ntive number.\")\n        }\n        throw new MissingPropertyException(\"Property $name not found\")\n    }\n}\n

\n\n\n\n

Reviewing the code you’ll see:

\n\n

Each side will be added to the sideMap with a lower-case letter as the key and the side’s length as the value\n
- The SIDE_NAME_PATTERN provides a very basic pattern to limit the acceptable keys
- The getSideMap() will return a clone¹ of sideMap - this helps protect the property from changing externally to the trait.
\n
The perimeter field will hold the perimeter of the shape\n
- This is calculated via the getPerimeter() method (more on this in a moment)
- Note how the perimeter is calculated only once
\n

\n\n

Aside from the items listed above, you’ll notice two versions of the propertyMissing method. This is a special Groovy method that is called when a getter or setter is called on a property that doesn’t exist. The propertyMissing(String name) is called when code attempts to access (get) a non-existent property and propertyMissing(String name, value) is called when an attempt is made to mutate (set) a non-existent property. The getter is reasonably straight-forward as it just checks that the requested property name matches the SIDE_NAME_PATTERN and, if so, tries to access the property from sideMap.

\n\n

The setter version of propertyMissing is a little more complex and, stepping through the method, we can see:

\n\n

The requested property name must match SIDE_NAME_PATTERN\n
If the perimeter has already been calculated we throw an exception as sideMap is locked down once perimeter has been set
The value for the side (it’s length) must be a Number\n
A utility method ShapeUtil.checkSidesException is called to ensure that value > 0 as we don’t want negative- or zero-length sides
Once all of those preconditions are met the property can be set

\n\n

All of this results in the Sides trait providing implementing classes with not only the ability to store a list of sides and calculate the perimeter but also lets them use a nice letter-based notation for the sides.

\n\n

Both the Triangle and Rectangle classes implement the Sides trait as well as the TwoDimensionalShape interface. By implementing Sides, these classes are provided with an implementation of the getPerimeter() method required by the TwoDimensionalShape interface.

\n\n

We can see the interaction between the a shape class and the Sides trait by examining the Rectangle class:

\n\n

The Rectangle class

\n\n

package org.groovy_tutorial.shapes\n\nimport groovy.transform.EqualsAndHashCode\nimport groovy.transform.ToString\n\n/**\n * Describes a rectangle\n *\n * @author Duncan Dickinson\n */\n@EqualsAndHashCode(includes = 'length,width')\n@ToString(includeNames = true, includeFields = true, includePackage = true)\nclass Rectangle implements TwoDimensionalShape, Sides {\n\n    private static final String SHAPE_NAME = 'Rectangle'\n\n    /** The area of the rectangle */\n    final BigDecimal area\n\n    /**\n     *\n     * @param length\n     * @param width\n     * @throws IllegalArgumentException if one of the sides <= 0\n     */\n    Rectangle(Number length, Number width) throws IllegalArgumentException {\n        a = length\n        b = width\n        c = length\n        d = width\n\n        //Calling this causes the Sides trait to calculate the perimeter\n        //and lock off its sideMap\n        this.perimeter\n\n        this.area = length * width\n    }\n\n    @Override\n    String getDisplayInfo() {\n        \"$SHAPE_NAME: length = $a; width = $b; perimeter = $perimeter; area = $a\\\nrea\"\n    }\n\n    @Override\n    String getShapeName() {\n        SHAPE_NAME\n    }\n}\n

\n\n\n\n

Most of Rectangle’s use of the trait is seen in the constructor as we set the sides of the rectangle though a really easy-to-understand notation:

\n\n

a = length\nb = width\nc = length\nd = width\n

\n\n\n\n

The use of the Sides trait means that instances of Rectangle can use notation such as myRectangle.a.

\n\n

The Rectangle constructor also calls this.perimeter so as to calculate the perimeter - not because we specifically need it in the constructor but because it locks down the set of sides for the rectangle instance.

\n\n\n\n

Cloning was mentioned previously ↩\n

\n\n\n

\n103. Inheritance

\n\n

Inheritance provides a strategy for building up new types by drawing upon existing implementations. In Groovy this focuses on the class structure and we can use inheritance to create a class that builds on and refines the concepts defined in another class. This approach is supported by the interface structure for defining programming interfaces and the traits structure for encapsulating abilities or features that could be applicable to one or more classes.

\n\n

The options available in Groovy for combining these three structures are as follows:

\n\n

Interfaces can:\n
- Implement zero or more interfaces
\n
Traits can:\n
- Implement zero or more interfaces
- Implement zero or more traits
\n
Classes can:\n
- Implement zero or more interfaces
- Implement zero or more traits
- Extend zero or one class
\n

\n\n

The extends keyword is the gateway to inheritance in Groovy and the spartan example below demonstrates a how a we declare that a class (SuperHero) will inherit from another class (Person):

\n\n

class Person {}\n\nclass SuperHero extends Person {}\n

\n\n\n\n

Some inheritance theory

\n\n

Before we go much further into how inheritance is undertaken I’d like to explore some background aspects that are worth your consideration.

\n\n

Subclass and superclass: When ChildClass inherits from ParentClass, we say that ChildClass is a subclass of ParentClass and that ParentClass is a superclass of ChildClass\n
Overriding: When ChildClass subtypes ParentClass and ChildClass provides a method with the same signature as a method declared in ParentClass (or a supertype thereof and so on) then that method is said to be overridden.; Overriding provides a mechanism for the subtype to provide a more specific implementation than the supertype’s.
Single and multiple inheritance: Groovy supports single inheritance which means that a class can only be a subclass of a single superclass.; Other languages, such as C++, allow for multiple inheritance and this allows a class to have more than one superclass.; Multiple inheritance can suffer from the diamond problem in which the multiple paths through which subtyping occurs can make it difficult to determine the origin of an overridden method.; Groovy’s class inheritance, being based in single inheritance, doesn’t suffer from this problem as there is only one path back through the hierarchy.; However, Groovy classes can implement multiple traits and this can lead to the same problems encountered in multiple inheritance. The two approaches to resolving this (manual- or automatic-resolution) were discussed in the chapter on Traits.
Implementation inheritance or interface inheritance: Inheritance is often viewed through two facets: implementation inheritance or interface inheritance.; \nInterface inheritance occurs when the implements keyword is used by a class to inherit an interface.; \nImplementation inheritance occurs when the extends keyword is used by a class to inherit from another class.; As an interface contains no implementation the implementing class can’t be “injured” through its association with the interface unless the author of the interface changes the method signatures. This shouldn’t happen if the interface is well designed. The class implementing the interface is wholly responsible for the implementation details for the interface’s methods.; A subclass can be significantly injured by changes in the superclass as implementation inheritance reuses the parent class’s implementation and this is a form of coupling that can silently introduce bugs into your program.; The lure of reuse through implementation inheritance is often in its perceived time-saving value. However, as requirements change and the classes are refactored and other changes made, the use of implementation inheritance can create a house of cards. Interface inheritance, by not passing through implementation, avoids this.; Composition can combine the benefit of reuse seen in implementation inheritance with the flexibility and independence of interface inheritance.; Aim to use interface inheritance heavily and implementation inheritance sparingly.
Leaky implementation/abstraction: Inheritance may help in terms of code-reuse but it’s important to make sure that a class correctly encapsulates the desired concepts and doesn’t suffer from implementation leakage. As a superclass gets more complex or the subtype hierarchy gets deeper, implementations from higher-level supertypes start to build up and the lower-level subclasses end up with a large number of methods that may have no utility to that class. This will also blow out the number of tests you’ll need.
Composition: The super-/sub-class association in implementation inheritance works well when the subclass truly is a refined definition (subtype) of the superclass. I find that the relationship usually breaks down once the superclass becomes quite complex and the leaks start to pour out. If you find that you’re constantly changing a superclass in order to resolve issues in a subclass it’s probably time to rethink the design and consider composition.; In composition the candidate superclass is used as a member variable of the candidate subclass. Instead of using extends, the subclass just declares a member variable (a property or field) that holds an instance of the candidate superclass. At that point the candidate superclass isn’t actually a superclass, it’s just a member variable.; Sometimes human language leads us astray and the notion of a StudentClassList makes us think that such a class could extend an existing List implementation. However, it’s likely that StudentClassList really just needs a List as a member variable and will provide a set of methods to manage the business logic around the list.; It is often safer to use composition instead of inheritance if you’re considering creating a subclassing a class in a package that you don’t have control over. Whilst your class might just be a wrapper class brokering the interaction between its interface and the member variable, this is very useful if the other class changes.; It can be tempting to use implementation inheritance to “pass down” useful instance methods. Where this occurs it’s likely to be more useful take the composition approach or consider providing such methods as static, especially if the method logic is broadly useful.

\n\n

A quick web search on these topics will yield a wealth of articles that will help you refine your practice. I’d also recommend “Effective Java (2nd edition)” by Joshua Bloch as a great starting place.

\n\n

\n104. Subclassing

\n\n

As we saw in the previous chapter, the extends keyword announces that a class is a subclass of another:

\n\n

class Person {}\n\nclass SuperHero extends Person {}\n

\n\n\n\n

Let’s put something a little more useful together:

\n\n

Name that super hero

\n\n

\n27. The Complement Operator

Table of Contents

Introduction

Something Wrong?

Bookmarks

Conventions Used in This Book

Code

Asides

Your Rights and This Book

Legal Notices

\nI Getting started

\n1. Introduction

\n2. Installing Groovy

Don’t Install Groovy

Install a Java Virtual Machine

Install Groovy

Windows

Checking for Groovy in the Start Menu

Mac OSX and Linux

Checking Groovy (all platforms)

Alternatives

\n3. Your first lines of Groovy

Examining the script

\n4. Running a script

\n5. Compiling Groovy

\n6. Comments

Single-line comments

Multi-line comments

Usage to avoid

Groovydoc

\n7. Statements

Usage to avoid

\n8. The assert statement

Handling failed assertions

\n9. Reserved Words

\n10. Packages

Using import\n

Basic Imports

Static imports

Built in Libraries

Useful third-party libraries

\n11. Grape

\nII Variables

\n12. Introduction

\n13. Declaring Variables

Variable names

Data Types

\n14. Objects

Declaring and using a class

Useful Methods

class

dump()

with()

Existing classes

Classes and literal values

\n15. Booleans

Useful Methods

\n16. Numbers

Integers

Decimals

Scientific notation

Number Systems

Useful Methods and Properties

\n17. Strings

Escape sequences

GStrings

Multiline Strings

Building Strings

Useful Methods

\n18. Collections

Lists

Adding elements

Sets

Useful List Methods

Maps

Adding elements

Keys

Useful Map Methods

\n19. Arrays

Manipulating arrays

\n8. The `assert` statement

Using `import`\n

`class`

`dump()`

`with()`

The `null` Value