Package org.apache.groovy.lang.annotation

Annotation Interface GroovyABI

@Documented @Target({TYPE,METHOD,CONSTRUCTOR,FIELD}) @Retention(CLASS) public @interface GroovyABI
Marks a program element as part of Groovy's binary ABI.

Elements annotated with @GroovyABI may be referenced directly by bytecode generated by the Groovy compiler. Their signatures and semantics therefore form part of the compatibility contract between compiled Groovy classes and the Groovy runtime.

Changes to annotated elements must preserve binary compatibility with previously compiled Groovy code unless the corresponding compatibility guarantee is intentionally dropped.

This annotation is intended only for members that are referenced by bytecode which may outlive the compiler version that produced it. Members used exclusively by bytecode generated at runtime by the current Groovy version should not be annotated.

Prefer annotating the type when every reachable member shares the same since() value; annotate members individually only when their since differs or only part of the type is part of the ABI.

Do not apply @GroovyABI to private fields or methods. The compiler-emitted bytecode that makes up this contract lives in a separate class, so it can never reference a private member of the runtime type; such members are not part of the binary ABI surface.

since records the first Groovy release in which the element became part of the binary ABI. It is mandatory and must use the full three-part version form, e.g. "1.0.0".

Retention. This marker has RetentionPolicy.CLASS retention: it survives into published class files so the build's binary compatibility tooling can rely on it.

Notes:

  • groovy.*: These classes are part of the public API and are therefore not annotated.
  • runtime packages: These classes are normally internal and subject to removal or change. If any of their methods is referenced by the compiler, it must be annotated so the reference becomes visible.
  • AST helper classes not in runtime: Some AST transforms leverage helper classes that are not in a runtime package. These classes must be annotated.

  • Required Element Summary

    Required Elements
    Modifier and Type
    Required Element
    Description
    String
    since
     

  • Element Details