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

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

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

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

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

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

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

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

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

A letter can be in the following ranges:

Then following characters can contain letters and numbers.

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

But the following ones are invalid identifiers:

All keywords are also valid identifiers when following a dot:

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

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

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

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

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

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

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

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

When creating a string as follows:

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

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

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

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

Example of a slashy string:

Only forward slashes need to be escaped with a backslash:

Slashy strings are multiline:

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

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

Here are a few examples:

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

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

The integral literal types are the same as in Java:

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

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

For positive numbers:

As well as for negative numbers:

The decimal literal types are the same as in Java:

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

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

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

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

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

Examples:

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

Division and power binary operations aside (covered below),

The following table summarizes those rules:

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

Examples:

The following binary arithmetic operators are available in Groovy:

Here are a few examples of usage of those operators:

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

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

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

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

Let’s see them in action:

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

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

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

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

Groovy offers four bitwise operators:

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

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

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

Groovy offers three bit shift operators:

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

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

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

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

Instead of:

You can write:

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

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

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

Groovy 3.0.0 introduces the Elvis operator, for example:

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

Normally in Groovy, when you write code like this:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

This can be fixed by using coercion instead:

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

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

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

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

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

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

The below imports are added by groovy for you:

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

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

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

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

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

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

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

If you have the same signature, the imported method takes precedence.

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

Now, that’s clean!

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

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

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

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

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

Similar to Java, it is an error in Groovy to specify multiple imports with the same name but different types:

And to declare an import and a top-level type with the same name:

However, inner types can shadow names from the unit scope:

Take the following code for example:

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

A script can be considered as a class without needing to explicitly declare it. There are some differences which we’ll cover next. First, we’ll cover Groovy’s main Script class. Then, we’ll cover JEP 445 compatible classes.

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

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

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

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

Statements 1 and 3 are sometimes referred to as "loose" statements. They are not contained within an explicit enclosing method or class. Loose statements are assembled sequentially into the run method.

So, the above code is internally converted into:

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

will behave the same as:

However, there is a semantic difference between the two:

As mentioned previously, normally, public static void main and run methods are automatically added to your script, so it is normally illegal to add your own versions of either of those; you would see a duplicate method compiler error if you tried.

However, there are some exceptions where the above rules don’t apply. If your script contains only a compatible main method and no other loose statements, or only a no-arg run instance method (from Groovy 5), then it is allowed. In this case, no loose statements (because there aren’t any) are collected into the run method. The method you supplied is used instead of Groovy adding the respective method(s).

This can be useful if you need to add an annotation to the otherwise implicitly added main or run methods as this example shows:

To be recognised as a convenience variation, as well as having no loose statements, the parameter for the main method should be:

From Groovy 5, a no-arg instance run variant is also supported. This also allows annotations to be added. The run variant follows the JEP 445 rules for field declarations (hence doesn’t need to use the @Field annotation) as this example involving Jackson JSON serialization shows:

The run variant is recommended if you need your script to extend the Script class and have access to the script context and bindings. If you don’t have that requirement, providing one of the main variants will create a JEP 445 compatible class which won’t extend Script. We’ll cover JEP 445 compatible scripts in more detail next.

There are some differences with Groovy’s JEP 445 support and that offered by Java:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

There are some reasons for using inner classes:

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

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