@Documented
@Incubating
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.PARAMETER)
public @interface ClassTag

Parameter annotation marking a Class parameter as compiler-supplied under static compilation. On the JVM, a method that needs the runtime type of a generic type parameter cannot recover it (erasure), so the API must take an explicit Class<T> token. That token is redundant with a type the compiler already knows — the receiver's type argument. @ClassTag removes the redundancy.

Under @CompileStatic / @TypeChecked, when a call omits the Class token argument(s), the type checker may select an overload whose parameters, beyond those matching the supplied arguments, are all @ClassTag Class<X> and synthesise the X.class argument(s) from the receiver's matching type argument(s), rewriting the call. Each @ClassTag parameter is filled at its declared position — anywhere in the parameter list, not just trailing — and the caller's supplied arguments map to the remaining (non-tag) parameters in order.

As an example, asChecked declares an explicit token:

 public static <T> List<T> asChecked(List<T> self, @ClassTag Class<T> type)
 

 List<String> list = [].asChecked()      // compiler injects String.class
 

Selection is normally additive: the tagged overload is chosen only when the call as written matches no method (as above — there is no token-less asChecked()). When a token-less overload also matches, choosing the tagged one instead (preemption) changes the meaning of existing source, so three conditions gate it:

• Intent — the API author must declare the tagged overload preemptive with preempt=true; without it the overload is only ever selected additively. Groovy's own checked withDefault overloads declare it (their lenient sibling predates them and could silently corrupt a typed map's key set).
• Containment — a tagged overload may only preempt a token-less overload declared by the same class (or, for instance methods, the same class hierarchy). A library can upgrade callers of its own lenient API but can never capture calls owned by another library, so adding a jar to the compile classpath cannot re-route existing calls it does not already own.
• Consent — the consumer may veto all preemption globally via CompilerConfiguration.setClassTagPreemptionDisabled (also seeded from the groovy.classtag.preemption.disable system property). Code compiled with the veto behaves exactly as it did before any library declared preemption; a finer-grained (per-method or per-call-site) opt-out may be added later if experience shows the need.

Boundaries:

• Static only. Dynamic Groovy ignores the annotation and binds the original overload; the shorter (token-less) spelling is static-only syntax. If no token can be synthesised there is no zero-token method to bind, so the call fails to resolve.
• The type variable must be statically known. List<String> works; def, raw List, and wildcard-only types do not — no token is synthesised.
• Receiver type arguments only. A type variable declared by the method itself (which shadows any like-named class variable) cannot be reified from the receiver; tagging one on an instance method compiled from source is a compile-time error. Static methods are exempt: in the extension-method authoring pattern the type variable is necessarily method-declared and connects to the receiver through the self parameter.
• Erased fidelity. The synthesised Class<X> reifies only the erased class: List<String> and List<Integer> are indistinguishable.
• Nothing-to-gain guard. When every token would erase to Object (e.g. a List<Object> receiver), no token is synthesised — a checked Object view could never reject anything — so an additive call fails to resolve and a preemptive upgrade is skipped (the lenient overload is kept).
• Escape hatch. Passing the Class explicitly always works, in every mode.

Since:

6.0.0