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]

@jamesfredley I think i've addressed all of the issues you raised.

[bito-code-review]

This question isn’t related to the pull request. I can only help with questions about the PR’s code or comments.

[jamesfredley]

I will push a small documentation commit in a few minutes. Looks good to go!!!

[jdaugherty]

@codeconsole can you please confirm you are good to merge? James & I believe this is ready

[jdaugherty]

@codeconsole do you have time to review again? @jamesfredley do you agree his feedback is implemented? should we merge or wait for his second review?

[jamesfredley]

@jdaugherty I reviewed all feedback from everyone and believe it has been addressed. My two concerns on docs were handled in the two commits. I will merge 8.0.x in now so it actually runs the full CI.

[testlens-app]

✅ All tests passed ✅

🏷️ Commit: ac449c8
▶️ Tests: 40144 executed
⚪️ Checks: 35/35 completed

---

Learn more about TestLens at testlens.app.

[jamesfredley]

🚀

[jdaugherty]

Asking @codeconsole again to confirm he's ok with these changes. I believe they've been addressed, and @jamesfredley I think agrees with me. My assumption is we'll discuss in the weekly if @codeconsole doesn't respond.