Add method-based TagLib syntax with legacy compatibility, benchmarks, and docs

[davydotcom]

Summary

This PR introduces method-based TagLib handlers as the recommended syntax, while preserving full backward compatibility with closure-based handlers and legacy invocation paths.

Rebased onto 8.0.x from the original PR #15459.

What's included

• Add method-defined TagLib support in core dispatch/invocation paths
• Preserve implicit method context (attrs and body) for method handlers
• Support binding named attributes directly to method signature arguments (for example def greeting(String name) binds from name="...")
• Add compatibility shims so legacy property/direct invocations continue to work for method-defined tags
• Preserve namespaced dispatch behavior and collision handling with method-backed tags
• Add compile-time warning for closure-defined tag fields in user TagLibs
• Convert shipped Grails web/GSP taglibs to method-based handlers
• Add coverage for method-defined tags and legacy compatibility behavior
• Add benchmark spec for method vs closure invocation
• Update guides/docs to present method syntax first, with closure syntax as legacy-compatible

Performance

The method-vs-closure benchmark added in this change set shows an approximately 7–10% improvement for method-based invocation in the covered scenarios.

TagLib syntax examples

Recommended (method-based)

class DemoTagLib {
    static namespace = 'demo'

    def greet() {
        out << "Hello, ${attrs.name}!"
    }

    def greeting(String name) {
        out << "Hello, ${name}!"
    }

    def repeat() {
        attrs.times?.toInteger()?.times { n ->
            out << body(n)
        }
    }
}

Usage:

<demo:greet name="Ada" />
<demo:greeting name="Ada" />

Legacy-compatible (closure field)

class DemoTagLib {
    static namespace = 'demo'

    def greet = { attrs, body ->
        out << "Hello, ${attrs.name}!"
    }
}

Validation performed

• Focused regressions:
  • FormTagLib2Tests
  • FormTagLib3Tests
  • SelectTagTests
  • NamespacedTagLibMethodTests
  • TagLibMethodMissingSpec
  • MethodDefinedTagLibSpec
• Full suite:
  • :grails-gsp:test
• Functional validation:
  • :grails-test-examples-app1:integrationTest --tests functionaltests.MiscFunctionalSpec

Co-Authored-By: Oz oz-agent@warp.dev

[jamesfredley]

Doc Examples

Files: namespaces.adoc, tagReturnValue.adoc
In namespaces.adoc, the new method-based tag was added but the old closure-based tag was also left in place, :

class SimpleTagLib {
    static namespace = "my"
    def example() {        // ← new method added
    def example = { attrs ->  // ← old closure NOT removed
        //...
    }

Same issue in tagReturnValue.adoc - def content() was inserted but def content = { attrs, body -> remains on the next line. Both are incomplete edits that will produce broken examples in the published docs.

isTagMethodCandidate Is Broad

Any public, non-static, non-getter/setter method on a TagLib class is treated as a tag candidate. The exclusion list is minimal:

• afterPropertiesSet
• get*() (zero-arg) / set*(x) (one-arg)
• invokeMethod, methodMissing, propertyMissing
• Methods declared on Object or GroovyObject
  This means toString(), hashCode(), equals(), other Spring lifecycle methods (e.g. destroy(), onApplicationEvent()), and any custom utility methods will all be registered as invokable tags. A TagLib with a helper method like def formatDate(Date d) would silently become a <g:formatDate> tag.

Namespace Property Guard Removed

registerNamespaceMetaProperty previously had a guard:

if (!metaClass.hasProperty(namespace) && !doesMethodExist(metaClass, getGetterName(namespace), ...)) {
    registerPropertyMissingForTag(...)
}

That guard was removed - namespace dispatchers now always overwrite. This could shadow real properties on TagLibs that happen to share a name with a registered namespace (e.g. a TagLib with a String my property when "my" is also a namespace).

registerTagMetaMethods Now Defaults overrideMethods = true

The signature changed to:

static void registerTagMetaMethods(MetaClass emc, TagLibraryLookup lookup, String namespace, boolean overrideMethods = true)

For the taglib's own namespace, tags now always override existing metaclass methods, whereas previously overrideMethods was false. This could break TagLibs that intentionally define a method sharing a name with a default-namespace tag (the local method would get silently overwritten by the tag dispatcher).

ThreadLocal Push Outside try Block

In GroovyPage.invokeTagLibMethod():

TagMethodContext.push(attrs, actualBody);          // ← outside try
Object tagResult = TagMethodInvoker.invokeTagMethod(tagLib, tagName, attrs, actualBody);
outputTagResult(returnsObject, tagResult);
} finally {
    TagMethodContext.pop();                         // ← inside finally

If an exception occurs between push() and the try block (or if invokeTagMethod throws before entering the try), the push has already happened but pop may not execute in the right scope. The push should be moved inside the try to guarantee the finally always cleans up exactly what was pushed.

Single-Parameter Fallback Heuristic in toMethodArguments

When a tag method has a single parameter and attrs has a single entry, the code uses the first value from the map regardless of whether the parameter name matches:

if (value == null && parameters.length == 1 && attrs != null && attrs.size() == 1) {
    value = attrs.values().iterator().next();
}

This is a magic heuristic that could silently bind the wrong attribute. For example, <g:myTag foo="bar"/> calling def myTag(String name) would bind "bar" to name even though the attribute is foo, not name. This makes debugging attribute-binding issues difficult.

[jdaugherty]

@davydotcom I made some attempts at fixing the test pollution, but I think there is still more work required here.

[jdaugherty]

From my AI Results:

  1. Generic test-isolation fix at the Spock extension level                                                                                                                                                       
                                                                                                                                                                                                                     
    Tests using UrlMappingsUnitTest no longer need per-test cleanup boilerplate. The fix lives in three places:                                                                                                      
                                                                                                                                                                                                                     
    - grails-testing-support-web/src/main/groovy/grails/testing/web/UrlMappingsUnitTest.groovy — mockArtefact() now clears artefactInfo and destroys the cached grailsUrlMappingsHolder singleton before
    re-registering. Added resetUrlMappingsForFeature() and cleanupUrlMappingsAfterFeature() helpers.                                                                                                                 
    - grails-testing-support-web/src/main/groovy/org/grails/testing/spock/UrlMappingSetupSpecInterceptor.groovy — now handles both setupSpec (mocking controllers) and setup (re-registering URL mappings before each
     feature method).                                                                                                                                                                                                
    - grails-testing-support-web/src/main/groovy/org/grails/testing/spock/UrlMappingCleanupInterceptor.groovy (new) — clears the URL mapping artefact registry after each feature method so non-UrlMappingsUnitTest
    specs running later in the same JVM don't inherit foreign mappings.                                                                                                                                              
    - grails-testing-support-web/src/main/groovy/org/grails/testing/spock/WebTestingSupportExtension.groovy — wires the new setup/cleanup interceptors.
    - grails-gsp/plugin/src/test/groovy/org/grails/web/mapping/RestfulReverseUrlRenderingTests.groovy — removed the now-redundant per-test setup/cleanup workaround.                                                 

[jdaugherty]

Concerning the continued failures:

Original CI failures (5 tests at maxTestParallel=3, 1 test at maxTestParallel=4) are reduced to occasional flakes on ReverseUrlMappingToDefaultActionTests.testLinkTagRendering. That remaining flake is a
pre-existing URL-mapping selection issue in DefaultUrlMappingsHolder — the holder contains the right mappings (verified via debug) but the lookup intermittently picks /$id? over /$dir/$id?. It's unrelated to
the test-isolation problem the PR's CI was hitting.

[jdaugherty]

Update on this, from the AI:

          ⏺ The smoking gun! ReverseUrlMappingTests' setup updated linkGen=1573001442 but the test is using linkGen=1931205834 (from RestfulReverseUrlRenderingTests). Tag library state is shared across specs. 

So the tag library state isn't being cleaned up correctly.

Here's the code it used:

[jdaugherty]

I believe I've addressed all of @jamesfredley 's comments.

[jdaugherty]

I decided to move the taglib cleanup to be by feature instead of by spec. The biggest reason was the flakiness of the grails-gsp test run was really due to partial clean-ups. By cleaning up after each feature, each test is isolated.

[testlens-app]

✅ All tests passed ✅

⚠️ TestLens detected flakiness ⚠️

Test Summary

Check	Project/Task	Test	Runs
CI / Functional Tests (Java 25, indy=false)	:grails-test-examples-app1:integrationTest	AsyncPromiseSpec > conditional async uses sync mode when requested	❌ ✅

🏷️ Commit: 38d41c8
▶️ Tests: 7179 executed
⚪️ Checks: 34/34 completed

---

Learn more about TestLens at testlens.app.

[codeconsole]

Nice work!

Considerations?:

PR #15465 Review — Method-based TagLib Handlers

Substantial, well-thought refactor (+1401/-244, ~60 files). The ClassValue cache, push/pop discipline in
GroovyPage.invokeTagLibMethod, and the UrlMappingsUnitTest.mockArtefact fix are good. Highest-impact
issues below.

Blockers

B1 — TagMethodInvoker.invokeTagMethod swallows Error and rewraps it as RuntimeException. The
catch only handles RuntimeException; an Error (StackOverflowError, AssertionError) gets boxed, hiding
the true cause. Add if (target instanceof Error err) throw err; and prefer GrailsTagException
(consistent with the closure path) for non-runtime targets.

B2 — Closure-tag dispatch regresses. TagMethodInvoker.getClosureTagProperty walks the superclass
chain via getDeclaredField on every closure tag invocation, replacing what was previously a single
metaclass getProperty(tagName). Tag-heavy GSPs likely take a hit on the closure path that the benchmark
doesn't measure. Cache resolved fields in a ClassValue<Map<String, Optional<Field>>> mirroring
INVOKABLE_METHODS_BY_NAME.

B3 — TagLibArtefactTypeAstTransformation deprecation warning is unconditional. Third-party plugins
that ship closure-defined tag fields will spam warnings during user compilation, with no opt-out. Verify
whether GrailsASTUtils.warning interacts with Groovy's Werror flag — if so this can break user builds.
Gate behind a system property (grails.taglib.warnDeprecatedClosures) and/or skip when the source is from
a plugin jar, not the user's app.

Major

M1 — ValidationTagLib.formatValue silently dropped from returnObjectForTags and made private.
<g:formatValue> was a public tag; this is a breaking behavior change not called out in
upgrading80x.adoc. Either restore it as a public method tag, or document the removal.

M2 — toMethodArguments returns null (rejecting the overload) when any non-attrs/non-Closure arg
is null. Closures pass null through; typed-parameter tags now silently fall through to another
overload or throw MissingMethodException. Only reject null when the parameter is primitive; allow it
for reference types.

M3 — Method resolution depends on JVM-defined getDeclaredMethods() order for same-arity overloads.
Add a deterministic tiebreaker (e.g., parameter-type names) so behavior is identical on HotSpot vs.
Graal/J9.

M4 — is*() no-arg exclusion is heuristic-fragile. Targeted at JavaBean accessors, but a tag
legitimately written boolean isAvailable(...) works only because it has args. Consider a @Tag
annotation override for explicit opt-in.

Minor / DRY

• N1 — FormTagLib private *Impl helpers (textFieldImpl, passwordFieldImpl, submitButtonImpl,
  etc.) are ~30 lines of mechanical boilerplate caused by the Groovy 4 multimethod restriction. A single
  private void renderField(Map attrs, String type) setting both attrs.type and attrs.tagName collapses
  them.
• N2 — UrlMappingTagLib.paginate: attrs = (TypeConvertingMap) attrs re-casting the parameter to
  itself is non-obvious; introduce a typed local.
• N3 — JavascriptTagLib.javascript/escapeJavascript not converted while everything around them is —
  introduce a typed local.
• N3 — JavascriptTagLib.javascript/escapeJavascript not converted while everything around them is — either convert or
  add a one-line comment about why.
• N4 — Doc examples in simpleTags.adoc and MethodDefinedTagLibSpec reference
  propertyMissing('attrs')/propertyMissing('body'). CLAUDE.md says don't expose internal mechanisms in docs — add a public
  currentAttrs()/currentBody() helper on the TagLibrary trait and document that.
• N5 — TagMethodContext.ThreadLocal is only remove()d when the stack empties on pop. If any dispatch path ever skips
  pop, a later request on the same container thread sees stale attrs/body. Add a request-lifecycle interceptor that calls
  clearAll() defensively.
• N6 — FRAMEWORK_METHOD_NAMES and NON_TAG_METHOD_NAMES overlap conceptually; consolidate to avoid drift.
• N7 — Test deletions (RestfulReverseUrlRenderingTests -22, etc.) are not coverage losses — they're redundant after
  UrlMappingCleanupInterceptor and the new mockArtefact cleanup. Good DRY.

Positives

• ClassValue is the right primitive for class-keyed caches (auto-invalidates on unload).
• try/finally push/pop in GroovyPage.invokeTagLibMethod is correct.
• Benchmark spec is honest — prints, doesn't assertion-gate the percentage.
• mockArtefact destroys the cached singleton before re-registering — fixes a real test-isolation hazard.

Recommendation

Fix B1, B2, B3, M1, M2 before merge; the rest are post-merge improvements. The formatValue removal (M1) is the most likely to
bite real users silently