Release notes for Groovy 6.0

Without async/await, concurrent code requires chaining futures:

With async/await, the same logic reads like synchronous code:

Exception handling works with standard try/catch — no .exceptionally() chains.

Launch tasks concurrently and coordinate results:

An async closure containing yield return becomes a lazy generator — it produces values on demand with natural back-pressure:

Go-style inter-task communication. A producer sends values into a channel (AsyncChannel); a consumer receives them:

AsyncScope binds the lifetime of child tasks to a scope — when the scope exits, all children are guaranteed complete or cancelled:

An Agent wraps a value and serialises updates via functions, eliminating data races by design. Reads compose with await:

An agent also exposes its update stream as a java.util.concurrent.Flow.Publisher via changes(), so for await consumes state transitions directly:

A hand-written actor (Actor) expresses concurrency by encoding a message protocol — typed messages, a switch over message kinds, and explicit send/sendAndGet plumbing at every call site:

To know whether the actor is being used safely, a reader (human or AI) has to follow each message kind through the dispatch loop and match it against every call site. @ActiveObject (applicable target: TYPE) inverts this: write a normal class, mark methods that participate in the actor’s serialised mailbox with @ActiveMethod (applicable target: METHOD), and the AST transform routes those calls through an internal actor:

The thread-safety contract is now explicit and local. The @ActiveObject annotation declares the concurrency model; @ActiveMethod bodies contain plain business logic; callers see ordinary method calls — no message types to invent, no switch to parse, no manual reply plumbing. For non-blocking use, @ActiveMethod(blocking = false) returns an Awaitable that plugs straight into await and Awaitable.all.

A DataflowVariable is a single-assignment variable: any thread that reads before it is bound blocks until a value is available. DataflowVariable implements Awaitable, so it composes directly with await and async {} regardless of which task binds first:

The companion Dataflows class auto-creates variables on property access for an even more concise form (async { df.fullName = "${df.first} ${df.last}" }).

For CPU-bound data parallelism, Collection gains a family of parallel methods backed by a ForkJoinPool:

ParallelScope.withPool binds a pool for a block, and Pool offers Pool.cpu(), Pool.fixed(n), Pool.io(), and Pool.virtual() factories so CPU-bound and I/O-bound workloads can use distinct pools without leaking into the common pool. The previously introduced @Parallel loop annotation shares this infrastructure:

As a rule of thumb, prefer parallel collections (or @Parallel) for CPU-bound work and async/await with virtual threads for I/O-bound work — ForkJoinPool workers are precious and should not be tied up in Thread.sleep, network calls, or blocking I/O.

AsyncChannel (introduced with async/await) gains composable pipeline operations — filter, map, merge, split, tap — and ChannelSelect for Go-style multi-channel selection. BroadcastChannel adds one-to-many delivery and exposes asPublisher() for direct Flow.Publisher interop, so any subscriber — including a for await loop — receives every message:

The same for await works against any JDK Flow.Publisher, Reactor Flux (via groovy-reactor), or RxJava Observable (via groovy-rxjava).

For Java, Kotlin, and other JVM languages that want the same toolkit without the full Groovy runtime, the standalone groovy-concurrent-java module exposes AsyncScope, Pool, ParallelScope, Actor, Agent, DataflowVariable, AsyncChannel, BroadcastChannel, and ChannelSelect against plain java.util.function types. The Groovy-only sugar (async/await keywords, for await, defer, @ActiveObject, Dataflows, parallel extension methods) requires the full Groovy dependency.

The module ships under the org.apache.groovy:groovy-concurrent-java coordinate and is mutually exclusive with the full groovy runtime (Gradle enforces this via a shared capability; a runtime warning fires if both jars are detected on the classpath).

A closure-based DSL for quick scripting:

Responses auto-parse by content type: result.json, result.xml, result.html (via jsoup), or result.parsed for auto-dispatch.

Define a typed interface and Groovy generates the implementation at compile time. Parameters are mapped by convention — no annotations needed for the common case:

Both sides offer native async via HttpClient.sendAsync() — no extra threads consumed while waiting:

These CompletableFuture returns are first-class await targets in Groovy 6: def data = await api.getDataAsync('42').

Contract annotations now work in Groovy scripts, not just inside classes (GROOVY-11885). @Requires and @Ensures can be placed on script methods, and @Invariant can be placed on an import statement to apply as a class-level invariant for the script:

These annotations can be combined to build strong confidence in the correctness of an algorithm. Consider this insertion sort that merges two pre-sorted lists:

The @Ensures postcondition verifies that the result is sorted. The @Invariant asserts that no elements are lost or gained — the total number of elements across all three lists stays constant throughout the loop. The @Decreases annotation uses a lexicographic measure over the two input list sizes, giving us confidence that the loop terminates: on each iteration at least one input list shrinks, and they can never grow.

See also the loop invariants blog post for more on how contracts support correctness reasoning.

The NullChecker extension (GROOVY-11894) validates code annotated with @Nullable, @NonNull, and @MonotonicNonNull annotations, detecting null-related errors at compile time. It recognises these annotations by simple name from any package (JSpecify, JSR-305, JetBrains, SpotBugs, Checker Framework, or your own):

Without the null guard, dereferencing a @Nullable parameter produces a compile-time error. The checker also recognises safe navigation, early-exit patterns, @NullCheck, and @MonotonicNonNull for lazy initialisation.

Passing strict: true extends the checker with flow-sensitive analysis that detects null issues even in completely unannotated code — no @Nullable, no @NonNull, no special types:

The checker tracks nullability through assignments and control flow, catching potential dereferences that would otherwise surface only at runtime. This is also an example of parameterized type checking extensions in action — the strict: true argument is passed directly in the extension string.

See also the NullChecker blog post for a detailed walkthrough.

A trailing *ident captures the remaining elements:

The rest binding works against any RHS supporting either getAt(IntRange) or iterator(). The compiler picks one of three lowerings — a Stream rewrap that keeps lazy pipelines lazy, an getAt(IntRange) slice (whose return type drives the rest binder’s type), or an iterator fallback that supports unbounded sources without materialising them:

*ident in non-tail position lowers via indexed access against a sized, indexable RHS:

key: ident pairs in the declarator list bind via property access (map keys, JavaBean getters, or getProperty via the MOP):

The rest binder may carry a type ascription, mirroring the existing positional form:

For symmetry with switch case patterns and bracket-form declarations, def and var may appear before any binder; they are equivalent to omitting a type. Modifiers on the outer declaration propagate to every binder (including rest and map-style):

The "discard" convention (def (, y, m) = Calendar.instance) applies uniformly across every new form. is a regular identifier throughout — no wildcard semantics, no special parser node:

Several variants of groupByMany (GROOVY-11808) exist for grouping lists, arrays, and maps of items by multiple keys — similar to Eclipse Collections' groupByEach and a natural fit for many-to-many relationships that SQL handles with GROUP BY.

The most common form takes a closure that maps each item to a list of keys:

For maps whose values are already lists, a no-args variant groups keys by their values:

A two-closure form also exists for transforming both keys and values. See the groupByMany blog post for more examples including Eclipse Collections interop.

waitForResult replaces the manual stream/exit-code dance with a single call (GROOVY-11901):

The groovy-nio module adds async file operations on Path that return CompletableFuture results (GROOVY-11902). These compose naturally with Groovy 6’s async/await:

GINQ’s groupby clause now supports an into keyword (GROOVY-11915) that binds each group to a named variable with aggregate access:

SQL-style set operators (GROOVY-11919) for combining query results: union, intersect, minus, and unionall:

See the GINQ user guide for the full set of clauses and operators.

CsvSlurper parses CSV text into a list of maps, keyed by column headers:

The separator and quote characters can be customised via fluent setters, and quoted fields follow RFC 4180 rules (embedded commas, newlines, and doubled quotes). Set useHeader = false to treat the first row as data and key rows by auto-generated column names. Reader/InputStream/File/Path overloads of parse are provided alongside parseText.

CsvBuilder converts collections of maps to CSV:

When Jackson is on the classpath, CsvSlurper can parse CSV directly into typed objects, and CsvBuilder can write typed objects to CSV. This is particularly useful for CSV since all values are strings — Jackson handles conversion to numeric, date, and other types automatically:

See the Processing CSV user guide for the full API and configuration options.

MarkdownSlurper parses Markdown text into a MarkdownDocument backed by nested lists and maps. Each node is a Map with a type key plus type-specific fields:

The document exposes convenience properties — headings, codeBlocks, links, tables — that recursively walk the tree, so nodes nested inside list items or block quotes are still found. A text property gives a plain-text projection of the whole document with formatting markers stripped.

Pulling fenced code blocks by language is a common pattern when consuming LLM output:

section(headingText) returns the nodes between a given heading and the next heading of equal or higher level — handy for parsing structured agent replies:

GFM-style tables are supported when the org.commonmark:commonmark-ext-gfm-tables jar is on the classpath. Call enableTables(true) on the slurper and each row comes back as a Map keyed by header:

Supported node types include heading, paragraph, code_block, list/list_item, block_quote, link, image, text, inline_code, emphasis/strong, html_block/html_inline, thematic_break, line breaks, and (with the GFM extension) table.

See the Processing Markdown user guide for the full node schema and additional examples.

Both engines respect the grape.root system property for relocating the cache root.

When both engines are on the classpath, GrapeIvy is selected by default. To switch to GrapeMaven for a specific invocation:

Set the same property in JAVA_OPTS for a global default.

Custom GrapeEngine implementations are discovered via the standard java.util.ServiceLoader mechanism by including a jar with a META-INF/services/groovy.grape.GrapeEngine entry naming the implementation class. See the user guide for the full registration protocol.

Most existing @Grab scripts work unchanged with both engines. The notable differences when moving from GrapeIvy to GrapeMaven:

Switching from GrapeMaven back to GrapeIvy is generally straightforward since GrapeIvy’s defaults are more permissive.

See the Grape user guide for the full per-engine specification, custom-engine registration steps, per-engine logging configuration, and detailed migration walkthrough.

Groovy’s command-line tools resolve logging configuration in the following order (first match wins):

For example, to enable verbose Grape logging, create ~/.groovy/logging.properties with:

Loggers are organized by module (Core, Grape, Ant, Console, GroovyDoc, JSON, Servlet, Swing, Testing) — see the logging guide for the full list of logger names and their levels.

For most users, no special Groovy module is needed — simply add the standard JUnit Jupiter dependencies to your Gradle or Maven project and write tests in Groovy as usual:

The new groovy-test-junit6 module provides additional capabilities for users who need them:

Similarly, the existing groovy-test-junit5 module continues to provide the same capabilities for JUnit 5 users.

GroovyDoc gained a -theme flag controlling the output palette strategy (GROOVY-11947):

The default stylesheet has been refactored around semantic CSS custom properties (--fg, --bg, --link, --bg-panel, etc.), so author stylesheets supplied via --add-stylesheet can reference the same tokens and become theme-aware automatically — the same hook that enables fully custom palettes. When Prism.js syntax highlighting is enabled, the highlight theme swaps in sync with the page palette (GROOVY-11946).

The same theming model has been extended to docgenerator, the tool that produces the Groovy user guide and other distribution-bundled documentation. Output supports light, dark, and custom themes, following the OS preference by default and sharing the GroovyDoc CSS-custom-property approach so that custom stylesheets remain palette-aware.

GroovyConsole now offers light, dark, follow-system, and custom theme options, applied across the editor pane, output pane, and surrounding chrome. The active choice is persisted between sessions.

A run of /// line comments can now be used as a doc comment whose body is CommonMark Markdown (GROOVY-11542):

Headings, bullets, fenced code blocks, emphasis, and inline code all render as you would expect. Headings are shifted down two levels (so # becomes <h3>), fitting under each page’s existing title structure. Inline Javadoc tags continue to work inside Markdown bodies; tag-like text inside fenced code blocks stays literal. Traditional /** …​ */ Javadoc blocks still work and can coexist with /// comments in the same source file.

See JEP 467 and CommonMark for the full syntax and semantics.

The JEP 413 {@snippet} tag is now supported (GROOVY-11938) in three forms. Inline body:

External reference to a file in the package’s snippet-files/ directory (a region can also be selected via region="name"):

Markup comments inside snippet bodies let authors highlight, replace, or link to portions of the code without editing the source itself:

@highlight, @replace, and @link all support substring=, regex=, and region= attributes. See JEP 413 for the full markup reference.

Two author-facing conveniences apply to the external form: the language class is inferred from the file’s extension when no explicit lang="…​" is given, and a leading license or copyright header in the referenced file is stripped from the rendered output (opt out with keepHeader=true). See the dochome:groovydoc.html[Groovydoc documentation] for the full list of recognised extensions and the header-detection heuristic.

Two new generator flags make the rendered output immediately more modern:

-syntaxHighlighter=prism bundles Prism.js for client-side syntax highlighting of {@snippet} blocks and Markdown fenced code. Groovy, Java, XML, JSON, YAML, TOML, SQL, CSV, Markdown, JavaScript, and regex are supported out of the box.

-theme controls the palette strategy (GROOVY-11947):

Under the hood, the default stylesheet has been refactored around semantic CSS custom properties (--fg, --bg, --link, --bg-panel, etc.). Author stylesheets supplied via --add-stylesheet can reference the same tokens and become theme-aware automatically.

The new -preLanguage <lang> option (CLI) / preLanguage="lang" attribute (Ant task) sets a default Prism language for unattributed <pre> blocks in doc comments, so legacy code samples get highlighted without source edits (GROOVY-11950). See the dochome:groovydoc.html[Groovydoc documentation] for the rewrite rules and the per-block opt-out.

Smaller improvements that collectively close the long-standing gap with modern Javadoc:

The new options above are exposed through the GroovyDoc CLI (groovydoc) and the Ant task. Gradle’s built-in groovydoc task currently lags behind both surfaces and does not yet expose every new flag.

Until that gap closes, we recommend either driving GroovyDoc via the Ant task from Gradle, or replicating the approach used by the Apache Groovy and Grails builds themselves — both projects wrap GroovyDoc in their own plugin/build glue to access the full feature set.

Java’s Security Manager has been deprecated for removal by JEP 411, which argues that it is rarely used to secure modern applications and that security is better achieved through other mechanisms such as containers and operating system security.

Groovy 6 removes its use of AccessController.doPrivileged calls and related Security Manager infrastructure (GROOVY-10581). Code that relied on Groovy’s Security Manager integration should adopt alternative security mechanisms. Groovy 5 still includes such support on JDK versions that support it.