GEP-22

Single inheritance forces all reuse through a single line, leading to deep hierarchies, fragile base-class problems, and inability to mix unrelated capabilities.

Java 8 default methods attach behaviour to interfaces but are stateless by design, do not support stackable composition through super, and their resolution rules are designed around binary compatibility rather than composition.

Runtime mixins (Groovy’s pre-2.3 @Mixin annotation, since deprecated) weave behaviour at runtime but the resulting object is not an instanceof the mixed-in type, defeating type-based dispatch and compile-time checks.

Delegation via @Delegate expresses has-a relationships well but is verbose for genuine is-a composition and does not support overriding delegated behaviour transparently.

Public and private methods are supported. protected and package-private are not supported.

Abstract methods are permitted; concrete classes that implement the trait must provide an implementation unless they too are abstract.

Private methods do not appear on the generated trait interface and are not visible to other classes.

The final modifier records the intended modifier of the woven method in the implementing class. Mixing final and non-final declarations of the same signature across multiple inherited traits is permitted; normal trait method-selection rules apply and the resulting method takes the modifier of the selected source.

For a field bar of type T declared in trait my.pkg.Foo, the implementing class gains a field named my_pkg_Foo__bar of type T.

The mangling rule is: replace each . in the package name with _, append <traitSimpleName>__<fieldName>. The double underscore separates the trait identity from the field identity.

Private fields follow the same scheme but are also marked private; the mangling guarantees no collisions when a class implements multiple traits that declare fields of the same name (the diamond problem for state).

T.this.* (GROOVY-12104). T.this is Java’s enclosing-instance access for inner classes, and a trait is not an enclosing scope of its implementer (per item 1, this is the implementing instance directly), so it has no coherent meaning here. The rejection covers both method calls (T.this.m(…​)) and field/property access (T.this.x). For normal dispatch use this.m(…​) (item 1); for explicit trait-anchored dispatch use T.super.m(…​) (item 3).

unqualified super.m(…​) from a static trait method (GROOVY-12105). The unqualified super form of item 2 is supported for instance methods only; from a static trait method the trait chain is not walked. Use T.super.m(…​) for the trait’s own static m, or call the implementer-side method by name without a qualifier. (This restriction is specific to traits: Groovy permits unqualified super.m(…​) in static methods of plain classes, where it dispatches to the actual superclass’s static method.)

by providing its own implementation of the method, or

by calling T.super.m(…​) for the desired trait T.

implements SomeTrait (or TraitA and TraitB),

implements every interface that the original object implemented, and

delegates to the original object for behaviour not supplied by the applied trait(s).

Defining a trait — checks that run when the trait itself is compiled, independent of @CompileStatic. Malformed trait code is rejected outright (for example a misapplied @Virtual, a T.this.* qualifier, or unqualified super from a static trait method — see this, super, and stackable traits). These rejections always apply, in dynamic and statically-checked code alike, because you cannot even define such a trait.

Weaving a trait — what happens when a class names the trait in its implements clause: per-direct-implementer composition, the bridge forwarders, and the static-helper plumbing (see Bytecode and stub model).

Using a trait — resolving a call at its call site, which follows the compilation mode. Under @CompileStatic/@TypeChecked an unresolvable call is a compile-time error; in dynamic code the same call instead fails at runtime with MissingMethodException. So the resolvability rules below describe the same outcome reported at two different times depending on how the calling code is compiled.

Each implementing class receives its own copy of static state. A static field declared in a trait is conceptually a template, instantiated per implementer; static state is not shared across implementing classes.

Public static methods declared in a trait are promoted onto the generated trait interface as JVM-native interface statics (GROOVY-12111). External calls of both forms — Trait.staticMethod(…​) against the trait itself and Impl.staticMethod(…​) against an implementing class — are supported.

Static trait methods, fields and properties may be declared in, and called from, @CompileStatic and @TypeChecked contexts. Calls inside a statically-checked trait body are subject to the ordinary type-checking and resolvability rules.

A public static method declared in a trait is declarer-bound by default: a call of the form m(…​) or this.m(…​) made directly in the body of a trait method resolves to the trait’s own copy regardless of any same-signature static method declared on the implementing class. The implementer’s same-name static is an independent method, not an override; external Impl.m() reaches that method, but trait-body calls do not see it.

A public static method may be annotated @Virtual to opt into per-implementer override dispatch. Trait-body calls of the form m(…​) or this.m(…​) to a @Virtual callee are routed through the implementing class at runtime, so a same-signature static declared on the implementer shadows the trait’s default from inside trait code. A @Virtual method is not promoted onto the trait interface (interface statics are declarer-bound by JVM rule, which is incompatible with virtual dispatch). It therefore has no qualified Trait.m(…​) form: a bare Trait.m(…​) names the trait with no implementing class to dispatch through, so it is rejected — a compile-time error under @CompileStatic/@TypeChecked (GROOVY-12112), and a runtime MissingMethodException in dynamic code. Read a concrete class’s value with Impl.m(…​), or use T.super.m(…​) from within trait code for the trait’s own definition.

@Virtual is valid only on public static (non-abstract) trait methods. Applying it elsewhere — to an instance method, a private method or an abstract method — is a compile-time error.

A private static method declared in a trait is trait-internal: it is not composed onto the implementing class, is not overridable, and is not promoted onto the trait interface.

A static method call made from inside a closure body inside a trait method dispatches through the trait helper rather than through the implementing class. An implementer’s override is not visible from such a call site, regardless of whether the callee is marked @Virtual.

A reference to a static field from trait code reads the trait’s template field, not any same-named static on the implementing class. Per-implementer overridable defaults should be expressed through a @Virtual accessor method, not a field (cf. the inheritance-of-state gotcha in Limitations). For example:

import groovy.transform.Virtual
trait V {
    @Virtual static String getOrigin() { 'trait' }   // overridable default
    static String describe() { "origin is ${origin}" }
}
class Over implements V {
    static String getOrigin() { 'class' }            // visible to trait body
}
assert Over.describe() == 'origin is class'

Trait composition occurs at the class that names the trait in its implements clause. A subclass of an implementer does not re-compose the trait; same-name static members declared on the subclass are not visible to trait code, because the trait’s forwarder dispatches through the direct implementer.

A T.m() call made from within trait T's own body resolves through the trait interface’s JVM-native static (the promotion described above), and so reaches the trait’s own copy — the same trait-anchored dispatch that any Trait.m() caller sees from outside the trait. This applies to plain (non-@Virtual) statics only; a @Virtual callee has no qualified form, so T.m() from trait code is rejected the same way as any other Trait.m(…​) call (GROOVY-12112) — use unqualified m(…​)/this.m(…​) for override-visible dispatch, or T.super.m(…​) for the trait’s own default.

Static methods declared in a super-trait are inherited by a sub-trait and may be called from the sub-trait’s own body, resolved by the same rules as a static declared in the trait itself: an unqualified m(…​) or this.m(…​) call is declarer-bound (or, for a @Virtual callee, dispatches through the implementing class so an implementer’s override is visible); a Parent.m(…​) call resolves through the super-trait’s promoted interface static (for the non-@Virtual statics that are promoted there); and Parent.super.m(…​) reaches the super-trait’s own copy. Argument resolution is subtype-aware — an argument whose static type is a subtype of the declared parameter type resolves just as it does for plain-class static inheritance (GROOVY-12106). For example:

@CompileStatic
trait ExecutesClosures {
    static String withDelegate(Closure callable, Object delegate) { /* ... */ "for ${delegate.class.simpleName}" }
}
final class Argument { }
@CompileStatic
trait Arguable extends ExecutesClosures {
    String handle(Argument arg) { withDelegate({ -> }, arg) }   // inherited static; arg is a subtype of Object
}
class C implements Arguable { }
assert new C().handle(new Argument()) == 'for Argument'

Mixing static and instance methods of the same signature across multiple traits is undefined behaviour and should be avoided. If selection chooses a static variant where an instance variant is required, a compilation error is raised; conversely, an instance selection silently shadows the static variant.

A trait method (static or instance) that collides with a same-signature method inherited by the implementing class from its superclass shadows the inherited one at any call site where the trait method is reachable. At an instance call site (new D().m()), the trait member takes precedence regardless of whether either member is static or instance; at a static call site (D.m()), the trait member wins when it is itself static, while the inherited class static is reached only when the trait member is instance (and therefore unreachable via a static call).

To disambiguate such a collision, declare m on the implementing class and from its body invoke super.m() for the superclass version and T.super.m() for the trait version. Both super-call forms work uniformly for static and instance trait members; T.super.m() is the canonical escape for any trait-vs-superclass collision.

@SelfType constrains what an implementing class must already be (its supertype shape).

@Sealed constrains which specific classes are allowed to implement the trait at all.

A trait’s class-level type parameter is promoted to a method-level type parameter on each generated static helper method (a static method cannot reference an enclosing type variable). Bounds are carried across the promotion intact, including intersection bounds (T extends A & B) and F-bounds (T extends Comparable<T>).

A method-level type parameter that shadows a class-level one of the same name is renamed when both are flattened onto a single helper static, preserving the shadowing semantics without a JVM-level name clash.

The generic signature on the trait interface (against which a call from an implementing class is type-checked) and the generic signature on the helper (through which the call dispatches, and against which a trait-body call is checked) agree, so a call resolves identically from both sites.

A generic field — including a parameterised collection field — survives field-helper remapping with its fixed type argument, so @CompileStatic implementer code sees the reified element type.

A static method inherited from a generic super-trait resolves from a sub-trait body with subtype-aware argument matching, exactly as for plain-class static inheritance (GROOVY-12106; see Static members).

Self-types (trait T<SELF extends T<SELF>>) and stackable T.super.m(…​) calls preserve the type parameter through the lowering.

A trait may implement the MOP hook methods methodMissing, propertyMissing and invokeMethod; they are woven onto the implementing class and handle that class’s otherwise-unresolved calls and property accesses.

A real (woven) trait method always takes precedence over the implementer’s methodMissing/propertyMissing: only genuinely unresolved names reach the hook.

A trait’s invokeMethod, in the absence of GroovyInterceptable, acts as a missing-method fallback — it intercepts only calls that do not resolve to a real method — exactly as it would on a plain class. It is not a blanket interceptor unless the implementing class also implements GroovyInterceptable.

A trait method is an ordinary instance method on the implementer, so a runtime metaClass/ExpandoMetaClass override of that method shadows the trait’s version, just as it would shadow a class-declared method. Trait methods carry no privilege against the MOP.

Remapped public trait fields are reachable dynamically under their mangled names (Fields), through both property and subscript access.

AST transform compatibility is best-effort. Some transforms (@CompileStatic, @TypeChecked, logging transforms) apply cleanly to traits; others apply only to the implementing class; others are unsupported. New transforms should be evaluated case by case.

Prefix and postfix operators (+`, `--`) on a trait field are rejected at compile time. The workaround is `= / -=. The reason is that the field-helper indirection cannot represent the read-modify-write sequence atomically.

Constructors on traits are not supported. Initialisation logic should be expressed via abstract methods supplied by the implementing class, or via property defaults.

Inheritance-of-state gotcha: trait method bodies that read a trait field directly read the trait’s own field, not any same-named property declared by the implementing class. To pick up an overriding value, trait code should access state through accessors (getX()), not by direct field reference. The same rule applies to static-field references — see Static members.

TraitASTTransformation — entry point invoked for every trait declaration; produces the interface, helper, field-helper and (where applicable) static-field-helper artefacts.

TraitComposer — weaves trait methods, accessors and bridge methods into each implementing class.

TraitReceiverTransformer — rewrites references inside trait method bodies so that this, super and field accesses resolve to the implementing-instance receiver and to helper-routed state.

Traits — utility class holding helper-class naming constants ($Trait$Helper, $Trait$FieldHelper, $Trait$StaticFieldHelper), trait detection predicates, and self-type collection logic.

TraitTypeCheckingExtension — integrates traits with the static type checker (GEP-8).

groovy.transform.Trait (since 2.3.0)

groovy.transform.SelfType (since 2.4.0)

GROOVY-7134: introduce @SelfType for statically checked traits.

GROOVY-8233: Java stub generation for static properties of traits.

GROOVY-8299: native default/private/static methods in interfaces (decoupling from trait machinery in 5.0).

GROOVY-8219, GROOVY-8788: @TupleConstructor interaction with traits and default values.

GROOVY-8951: trait getter conflicts with generated getter (pre-compiled case).

GROOVY-11674: deterministic ordering of trait methods for reproducible builds.

GROOVY-11907: trait field reference transform restructure.

GROOVY-8854 (interim): trait this.staticMethod() receiver rewrite (the change that later caused the 5.0 dispatch regression corrected in GROOVY-11985).

GROOVY-11985 (interim): experimented with restoring the 4.x behavior but ultimately rolled back.

GROOVY-12093: finalises the trait-static dispatch model — declarer-bound by default, with the @Virtual marker opting into per-implementer override dispatch for callees that need it.

GROOVY-12111: exposes public trait static methods on the generated trait interface as JVM-native interface statics, so both Trait.m() from outside the trait and T.m() from inside the trait body resolve at the JVM level (@Virtual methods are excluded — interface statics are declarer-bound by JVM rule, incompatible with virtual dispatch).

GROOVY-12104: rejects the T.this.* qualifier inside trait code at compile time (previously produced invalid or mis-typed bytecode at runtime).

GROOVY-12105: rejects unqualified super.m(…​) from a static trait method at compile time (previously threw MissingMethodException because the trait chain is not walked for statics).

GROOVY-12106: a sub-trait again resolves a static method inherited from a super-trait from its own body, including with a subtype argument (static type checking had matched the inherited helper static by exact parameter type only, regressing this in the 5.0.x line).

GROOVY-12112: rejects a qualified Trait.m(…​) call to a @Virtual trait static with a clear compile-time error (under @CompileStatic/@TypeChecked) instead of the generic "cannot find matching method"; dynamic code still reports a runtime MissingMethodException.