# Program structure

version 6.0.0-beta-1

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

## 1. Package names

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

Defining a package is very similar to Java:

    // defining a package named com.yoursite
    package com.yoursite

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

## 2. Imports

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

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

    // importing the class MarkupBuilder
    import groovy.xml.MarkupBuilder

    // using the imported class to create an object
    def xml = new MarkupBuilder()

    assert xml != null

### 2.1. Default imports

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

    long time = LocalDateTime.now().toEpochSecond(ZoneOffset.UTC)
    Date date = new Date(time)

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:

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

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

### 2.2. Simple import

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.

    // importing the class MarkupBuilder
    import groovy.xml.MarkupBuilder

    // using the imported class to create an object
    def xml = new MarkupBuilder()

    assert xml != null

### 2.3. Star import

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:

    import groovy.xml.MarkupBuilder
    import groovy.xml.StreamingMarkupBuilder

    def markupBuilder = new MarkupBuilder()

    assert markupBuilder != null

    assert new StreamingMarkupBuilder() != null

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`:

    import groovy.xml.*

    def markupBuilder = new MarkupBuilder()

    assert markupBuilder != null

    assert new StreamingMarkupBuilder() != null

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.

### 2.4. Static import

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

    import static java.lang.Boolean.FALSE

    assert !FALSE //use directly, without Boolean prefix!

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

    import static java.lang.String.format (1)

    class SomeClass {

        String format(Integer i) { (2)
            i.toString()
        }

        static void main(String[] args) {
            assert format('String') == 'String' (3)
            assert new SomeClass().format(Integer.valueOf(1)) == '1'
        }
    }

1 | static import of method
2 | declaration of method with same name as method statically imported above, but with a different parameter type
3 | compile error in Java, but is valid Groovy code

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

### 2.5. Static import aliasing

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

    import static Calendar.getInstance as now

    assert now().class == Calendar.getInstance().class

Now, that’s clean!

### 2.6. Static star import

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:

    import static java.lang.Math.*

    assert sin(0) == 0.0
    assert cos(0) == 1.0

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

### 2.7. Import aliasing

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:

    import java.util.Date
    import java.sql.Date as SQLDate

    Date utilDate = new Date(1000L)
    SQLDate sqlDate = new SQLDate(1000L)

    assert utilDate instanceof java.util.Date
    assert sqlDate instanceof java.sql.Date

### 2.8. Module import

Groovy supports Java’s module import declarations (JEP 476, finalized in Java 25). A module import imports all public types from all packages exported by the named module with a single statement:

    import module java.sql

    assert Connection.name == 'java.sql.Connection'
    assert DriverManager.name == 'java.sql.DriverManager'

This is equivalent to writing a star import (`import pkg.*`) for every package the module exports.

Module imports also include packages from any modules that the named module `requires transitive`. For example, `java.sql` transitively requires `java.xml`, `java.logging`, and `java.transaction.xa`:

    import module java.sql

    // Direct exports of java.sql
    assert Connection.name == 'java.sql.Connection'

    // From java.xml (requires transitive)
    assert Source.name == 'javax.xml.transform.Source'

    // From java.logging (requires transitive)
    assert Logger.name == 'java.util.logging.Logger'

Module imports work with system modules (JDK modules like `java.base`, `java.sql`, `java.desktop`), JPMS modules from modular JARs on the classpath (those containing `module-info.class`), and automatic modules (JARs with an `Automatic-Module-Name` manifest entry).

Explicit single-type imports take priority over module-expanded imports, which allows you to resolve any ambiguity by adding a specific import:

    import module java.desktop
    import java.util.List

    // The explicit single-type import wins over the
    // module-expanded java.awt.List
    assert List.name == 'java.util.List'

| The `module` keyword is context-sensitive — it can still be used as a variable, method, or class name. Wildcard (`import module java.base.*`) and alias (`import module java.base as jb`) forms are not supported.

### 2.9. Namespace conflicts

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

    import java.awt.List
    import java.util.List // error: name already declared

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

    import java.util.List
    class List { } // error: name already declared

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

    import java.util.List
    class Main {
        class List { } // allowed; "List" refers to this type within `Main`'s scope and `java.util.List` elsewhere
    }

## 3. Scripts versus classes

Groovy supports both scripts and classes. From Groovy 5, Groovy also supports JEP 445 compatible scripts.

### 3.1. Motivation for scripts

Take the following code for example:

Main.groovy

    class Main {                                    (1)
        static void main(String... args) {          (2)
            println 'Groovy world!'                 (3)
        }
    }

1 | define a `Main` class, the name is arbitrary
2 | the `public static void main(String[])` method is usable as the main method of the class
3 | the main body of the method

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:

Main.groovy

    println 'Groovy world!'

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.

### 3.2. `Script` class

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:

Main.groovy

    import org.codehaus.groovy.runtime.InvokerHelper
    class Main extends Script {                     (1)
        def run() {                                 (2)
            println 'Groovy world!'                 (3)
        }
        static void main(String[] args) {           (4)
            InvokerHelper.runScript(Main, args)     (5)
        }
    }

1 | The `Main` class extends the `groovy.lang.Script` class
2 | `groovy.lang.Script` requires a `run` method returning a value
3 | the script body goes into the `run` method
4 | the `main` method is automatically generated
5 | and delegates the execution of the script on the `run` method

If the script is in a 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`.

### 3.3. Methods

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

    int fib(int n) {
        n < 2 ? 1 : fib(n-1) + fib(n-2)
    }
    assert fib(10)==89

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

    println 'Hello'                                 (1)

    int power(int n) { 2**n }                       (2)

    println "2^6==${power(6)}"                      (3)

1 | script begins
2 | a method is defined within the script body
3 | and script continues

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:

    import org.codehaus.groovy.runtime.InvokerHelper
    class Main extends Script {
        int power(int n) { 2** n}                   (1)
        def run() {
            println 'Hello'                         (2)
            println "2^6==${power(6)}"              (3)
        }
        static void main(String[] args) {
            InvokerHelper.runScript(Main, args)
        }
    }

1 | the `power` method is copied as-is into the generated script class
2 | first statement is copied into the `run` method
3 | second statement is copied into the `run` method

| Even if Groovy creates a class from your script, it is totally transparent for the user. In particular, scripts are compiled to bytecode, and line numbers are preserved. This implies that if an exception is thrown in a script, the stack trace will show line numbers corresponding to the original script, not the generated code that we have shown.

### 3.4. Variables

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

    int x = 1
    int y = 2
    assert x+y == 3

will behave the same as:

    x = 1
    y = 2
    assert x+y == 3

However, there is a semantic difference between the two:

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

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

| Another approach to making a variable visible to all methods, is to use the @Field annotation. A variable annotated this way will become a field of the generated script class and, as for local variables, access won’t involve the script `Binding`. If you have a local variable or script field with the same name as a binding variable, we recommend renaming one of them to avoid potential confusion. If that’s not possible, you can use `binding.varName` to access the binding variable.

### 3.5. Convenience variations

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:

    @CompileStatic
    static main(args) {
        println 'Groovy world!'
    }

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

- untyped as above (`Object` type),

- or of type `String[]`,

- or have no arguments (from Groovy 5).

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:

    @JsonIgnoreProperties(["binding"])
    def run() {
        var mapper = new ObjectMapper()
        assert mapper.writeValueAsString(this) == '{"pets":["cat","dog"]}'
    }

    public pets = ['cat', 'dog']

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.

## 4. JEP 445 compatible scripts

From Groovy 5, support has been added for JEP 445 compatible scripts containing a `main` method. Such scripts have several differences to normal Groovy `Script` classes:

- they won’t have a `public static void main` method added

- they won’t extend the `Script` class and hence won’t have access to the script context or binding variables

- allows additional class-level fields and methods to be defined in addition to `main`

- can’t have "loose" statements outside the `main` method (excluding any field definitions)

A simple example might look like:

    void main(args) {
        println new Date()
    }

An example with additional fields and methods might look like:

    def main() {
        assert upper(foo) + lower(bar) == 'FOObar'
    }

    def upper(s) { s.toUpperCase() }

    def lower = String::toLowerCase
    def (foo, bar) = ['Foo', 'Bar']      (1)

1 | Note that multi-assignment syntax is supported and results in separate field definitions for each component.

### 4.1. Differences with Java JEP 445 behavior

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

- Java supports either a no-arg `main` method or one containing a single `String[]` parameter. Groovy also adds support for a single untyped (`Object`) parameter, e.g. `def main(args) { …​ }`. This addition is known by the Groovy runner but would not be known by the Java launch protocol for a JDK supporting JEP 445.

- Java supports `void` main methods. Groovy also adds support for untyped `def` (`Object`) methods, e.g. `def main(…​)` as well as `void main(…​)`. This addition is known by the Groovy runner but would not be known by the Java launch protocol for a JDK supporting JEP 445.

- For static `main` variants, Groovy promotes the no-arg or untyped variants to have the standard `public static void main(String[] args)` signature. This is for compatibility with versions of Groovy prior to Groovy 5 (where JEP 445 support was added). As a consequence, such classes are compatible with the Java launch protocol prior to JEP 445 support.

- Groovy’s runner has been made aware of JEP 445 compatible classes and can run all variations for JDK11 and above and without the need for preview mode to be enabled.

### 4.2. Main method selection priority

When a class has multiple valid `main` method signatures, the Groovy runner selects one using a priority order aligned with JEP 512. Static methods take priority over instance methods, and methods with parameters take priority over no-arg methods:

Priority | Method signature
--- | ---
1 | `static main(String[] args)`
2 | `static main(Object args)`
3 | `static main()`
4 | `main(String[] args)` (instance)
5 | `main(Object args)` (instance)
6 | `main()` (instance)

Only one method is selected — lower-priority `main` methods are not reachable from the Groovy runner. A compile-time warning is issued for any valid `main` method that would be shadowed by a higher-priority one.

| Having multiple `main` method overloads in a single class is considered poor style. We recommend providing a single `main` method to avoid any confusion about which one will run.