Add @GrailsBeans: compile bean-wiring DSL into real @AutoConfiguration classes

[codeconsole]

New Auto Configuration Bean DSL

@CompileStatic
class Application extends GrailsAutoConfiguration {
    static void main(String[] args) {
        GrailsApp.run(Application, args)
    }

    def beans = {  
        // insert autoconfig bean dsl here
    }
}

@CompileStatic
class MyGrailsPlugin extends Plugin {
    def version = GrailsUtil.getGrailsVersion()

    def beans = {
        // insert autoconfig bean dsl here
    }
}

Plugin.beanRegistrar() gives Grails a Spring-native, statically-compilable way to register beans, but it can't express fine-grained ordering against other @AutoConfiguration classes (Grails' own or third-party), and BeanRegistry.Spec has only one conditional primitive (fallback()) — nothing like @ConditionalOnProperty, @ConditionalOnClass, @ConditionalOnBean, or a custom Condition.

@GrailsBeans closes that gap: an AST transformation that compiles a doWithSpring()-style beans = { bean(["name", ] Type) { ... } } closure into real @Bean factory methods on a plain @AutoConfiguration class. Both the name and the body are optional: the name defaults to the type's JavaBeans-decapitalized simple name, and a bean that is nothing but its own no-argument construction needs no body at all, so bean(XmlDataBindingSourceCreator) says everything bean('xmlDataBindingSourceCreator', XmlDataBindingSourceCreator) { new XmlDataBindingSourceCreator() } does. Leaving the body empty means the same for a bean with dependencies — bean('validateableConstraintsEvaluator', DefaultConstraintEvaluatorFactoryBean).lazy() { List<MessageSource> messageSources, @Qualifier('grailsDomainClassMappingContext') MappingContext mappingContext, GrailsApplication grailsApplication -> } compiles to a method with exactly those parameters whose body is that constructor call, in the order written. The parameter list stays at the declaration deliberately: it is the only place in Groovy that can carry both a generic type and a parameter annotation, and because the generated body is the constructor call you would have written, the compiler selects the constructor from the parameter types — nothing reads the declared type's constructors, so adding one cannot change what an existing bean injects. Chaining .conditionalOnMissingBean(...) (positional types, the annotation's own named attributes, or bare to back off by return type), .conditionalOnMissingBeanName(...) (backs off by this bean's own name, stated once), .primary(), .lazy(), .scope("name"), and (repeatably) .annotate(AnnotationType[, attr: value, ...]) covers everything a hand-written @Bean method could carry — any @Conditional* (built-in or custom), @Order, @DependsOn, anything — and typed closure parameters (including their own annotations, e.g. @Qualifier) become constructor-style method parameters. One bean name may even be declared by several bean(...) statements when every declaration carries its own discriminating condition — the standard autoconfiguration pattern for mutually exclusive variants of one bean, e.g. UrlMappingsAutoConfiguration's two grailsUrlConverter beans selected by @ConditionalOnProperty; an unconditioned duplicate (which Spring would silently skip in favour of the first definition) stays a compile-time error. field(...) and method(...) round it out with private fields and helper methods on the generated class - field(...).value(Settings.SOME_KEY, 'default') compiles straight to a @Value("${...}") injection, bare constant keys included, and single-argument .value('app.some.key') auto-wraps a bare key into @Value("${app.some.key}") (strings already carrying ${...}/#{...} pass through verbatim) - for injected config and shared logic across beans - the same role a hand-written @Configuration class's own fields and methods play. Nothing DSL-specific survives into the compiled bytecode — verified with javap — so the result gets the entire @Conditional* family and Boot's own before=/after= ordering for free, correctly sequenced in Boot's deferred condition-evaluation pipeline.

Usage

Standalone class:

@GrailsBeans
@AutoConfiguration(before = [MessageSourceAutoConfiguration, WebMvcAutoConfiguration])
class MyBeans {
    def beans = {
        // a bean that is nothing but its own no-argument construction needs neither a
        // name (it is derived from the type) nor a body
        bean(FancyGreeter).conditionalOnMissingBean().primary()

        bean(SlowGreeter).lazy().scope('prototype')

        // with dependencies, the parameters say what gets injected and the body stays empty:
        // the constructor call is generated from them, in the order written
        bean(LoudGreeter) { Greeter greeter ->
        }

        bean(SpecialGreeter).annotate(Order, value: 1) { @Qualifier('special') Greeter greeter ->
        }

        // a body is only needed when construction is more than passing the parameters through
        bean(Greeter) {
            new Greeter('hello')
        }

        // an explicit name is for when the type does not produce the name you need.
        // 'legacy-greeter' isn't a valid Java identifier either, so the generated method gets a
        // synthesized name (greeter$0) - an implementation detail; Spring resolves the bean
        // by its @Bean("legacy-greeter") value, never by the method name
        bean('legacy-greeter', Greeter) {
            new Greeter('bonjour')
        }
    }
}

The standalone form works on any class Spring Boot processes as a configuration source — including an application's own Application class, where no imports-file registration is needed because Boot reads @Bean methods directly off the class it is launched with.

Directly on a *GrailsPlugin.groovy class, so bean definitions can live in the familiar plugin descriptor instead of a separate file — and there the annotation is implicit. A beans property on a plugin descriptor, or on an application's Application class, is compiled automatically, in the same way doWithSpring, watchedResources and dependsOn are conventions rather than annotated members; GlobalGrailsClassInjectorTransformation already runs at the same compile phase and already identifies these classes. @GrailsBeans is written out only for a standalone @AutoConfiguration class, which is neither. A class with no beans property is untouched, and so is one whose beans property isn't DSL-shaped — a pre-existing descriptor with def beans = [...], or a closure of something else, is left alone rather than failed with a DSL error it never asked for. Declaring the annotation explicitly still works, and opts back in to the strict errors. This is the actual conversion now live in this repository's own grails-i18n module — not an illustration; imports and comments are trimmed here for brevity; each block's linked filename is the verbatim, commit-pinned source. A second real conversion, UrlMappingsGrailsPlugin.groovy, replaces grails-url-mappings' hand-written UrlMappingsAutoConfiguration the same way — including its two mutually exclusive grailsUrlConverter variants sharing one bean name, selected by @ConditionalOnProperty.

Eight of the framework's own auto-configurations are now authored this way, most with their own before/after comment below: grails-i18n, grails-url-mappings, grails-sitemesh3, grails-mail, grails-core, grails-cache, grails-domain-class and grails-databinding.

grails-core is the module where the conversion goes furthest: CoreGrailsPlugin declared twelve beans through the deprecated bean builder DSL and now declares none that way — it has no doWithSpring at all. The four that benefit from Boot's condition and ordering machinery — classLoader, grailsConfigProperties, grailsResourceLocator, and the placeholder configurer ordered before = PropertyPlaceholderAutoConfiguration — moved into the beans block. The other eight, which depend on the plugin's own runtime state, moved to beanRegistrar(): the auto-proxy-creator variant, the two aware BeanPostProcessors, customEditors, proxyHandler, grailsBeanOverrideConfigurer, the development shutdown hook, and abstractGrailsResourceLocator — the last of these through a BeanDefinitionRegistryPostProcessor, since it is an abstract parent definition (see Limitations).

That move exposed a gap in the legacy unit-test harnesses rather than in the framework. AbstractGrailsTagTests calls doWithRuntimeConfiguration(springConfig) and stops there, running only the first of the two halves the runtime runs for a plugin, so any plugin contributing through beanRegistrar() was invisible to it. Both copies of that harness now apply the registrars after the DSL flush, in the same order and with the same precedence as GrailsApplicationPostProcessor.

The first four kept their exact class identity, because the *GrailsPlugin → *AutoConfiguration convention already produced the deleted class's name. The other four did not, and rather than pin the old names with @GrailsBeans(autoConfigurationName = ...) they take the convention name: GrailsCacheAutoConfiguration → CacheAutoConfiguration, GrailsDomainClassAutoConfiguration → DomainClassAutoConfiguration, and DataBindingConfiguration → DataBindingAutoConfiguration (which was registered as an auto-configuration while named only *Configuration). grails-core's keeps its name but changes package, since the generated sibling is emitted beside its plugin — org.grails.plugins.core.CoreAutoConfiguration → org.grails.plugins.CoreAutoConfiguration. All four are FQCN changes for anyone excluding them via @EnableAutoConfiguration(exclude = ...) or spring.autoconfigure.exclude; autoConfigurationName remains for a name that genuinely cannot move.

Before, I18nAutoConfiguration.java (since deleted) — a hand-written @Configuration-style class, six @Value-injected fields, a strategy-selecting helper method, four beans each backing off an existing same-named bean via @ConditionalOnMissingBean(name = ..., search = SearchStrategy.CURRENT):

@AutoConfiguration(before = { MessageSourceAutoConfiguration.class, WebMvcAutoConfiguration.class })
@ConditionalOnWebApplication(type = ConditionalOnWebApplication.Type.SERVLET)
public class I18nAutoConfiguration {

    @Value("${" + Settings.GSP_VIEW_ENCODING + ":UTF-8}")
    private String encoding;

    @Value("${" + Settings.GSP_ENABLE_RELOAD + ":false}")
    private boolean gspEnableReload;

    @Value("${" + Settings.I18N_CACHE_SECONDS + ":5}")
    private int cacheSeconds;

    @Value("${" + Settings.I18N_FILE_CACHE_SECONDS + ":5}")
    private int fileCacheSeconds;

    @Value("${" + Settings.I18N_LOCALE_RESOLVER + ":session}")
    private String localeResolverType;

    @Value("${grails.i18n.default.locale:}")
    private String defaultLocale;

    enum LocaleResolverStrategy { SESSION, COOKIE, ACCEPT_HEADER, FIXED }

    static LocaleResolverStrategy resolveStrategy(String value) {
        String normalized = value == null ? "" : value.toLowerCase(Locale.ROOT).replaceAll("[^a-z]", "");
        return switch (normalized) {
            case "cookie" -> LocaleResolverStrategy.COOKIE;
            case "acceptheader", "header", "accept" -> LocaleResolverStrategy.ACCEPT_HEADER;
            case "fixed" -> LocaleResolverStrategy.FIXED;
            default -> LocaleResolverStrategy.SESSION;
        };
    }

    @Bean(DispatcherServlet.LOCALE_RESOLVER_BEAN_NAME)
    @ConditionalOnMissingBean(name = DispatcherServlet.LOCALE_RESOLVER_BEAN_NAME, search = SearchStrategy.CURRENT)
    public LocaleResolver localeResolver() {
        return switch (resolveStrategy(localeResolverType)) {
            case COOKIE -> new CookieLocaleResolver("locale");
            case ACCEPT_HEADER -> new AcceptHeaderLocaleResolver();
            case FIXED -> new FixedLocaleResolver(fixedLocale());
            case SESSION -> new SessionLocaleResolver();
        };
    }

    private Locale fixedLocale() {
        if (StringUtils.hasText(defaultLocale)) {
            Locale parsed = StringUtils.parseLocale(defaultLocale);
            if (parsed != null) {
                return parsed;
            }
        }
        return Locale.getDefault();
    }

    @Bean
    @ConditionalOnMissingBean(name = "localeChangeInterceptor", search = SearchStrategy.CURRENT)
    public LocaleChangeInterceptor localeChangeInterceptor() {
        ParamsAwareLocaleChangeInterceptor localeChangeInterceptor = new ParamsAwareLocaleChangeInterceptor();
        localeChangeInterceptor.setParamName("lang");
        return localeChangeInterceptor;
    }

    @Bean(AbstractApplicationContext.MESSAGE_SOURCE_BEAN_NAME)
    @ConditionalOnMissingBean(name = AbstractApplicationContext.MESSAGE_SOURCE_BEAN_NAME, search = SearchStrategy.CURRENT)
    public MessageSource messageSource(GrailsApplication grailsApplication, GrailsPluginManager pluginManager) {
        PluginAwareResourceBundleMessageSource messageSource = new PluginAwareResourceBundleMessageSource(grailsApplication, pluginManager);
        messageSource.setDefaultEncoding(encoding);
        messageSource.setFallbackToSystemLocale(false);
        if (Environment.getCurrent().isReloadEnabled() || gspEnableReload) {
            messageSource.setCacheSeconds(cacheSeconds);
            messageSource.setFileCacheSeconds(fileCacheSeconds);
        }
        return messageSource;
    }

    @Bean
    @ConditionalOnMissingBean(AvailableLocaleResolver.class)
    public AvailableLocaleResolver availableLocaleResolver(GrailsApplication grailsApplication,
            @Value("${grails.i18n.availableLocales.includePlugins:true}") boolean includePlugins) {
        return new AvailableLocaleResolver(grailsApplication.getClassLoader(), fixedLocale(), includePlugins);
    }
}

After — I18nGrailsPlugin.groovy's class declaration and beans block (the rest of the file — doWithApplicationContext(), onChange(), isChildOfFile() — is pre-existing plugin-lifecycle logic, untouched by this conversion):

@Slf4j
@CompileStatic
@AutoConfiguration(before = [MessageSourceAutoConfiguration, WebMvcAutoConfiguration])
@ConditionalOnWebApplication(type = ConditionalOnWebApplication.Type.SERVLET)
class I18nGrailsPlugin extends Plugin {

    String baseDir = 'grails-app/i18n'
    String version = GrailsUtil.getGrailsVersion()
    String watchedResources = "file:./${baseDir}/**/*.properties".toString()

    static final String AVAILABLE_LOCALES_ATTRIBUTE = 'availableLocales'

    def beans = {
        field('encoding', String).value(Settings.GSP_VIEW_ENCODING, 'UTF-8')
        field('gspEnableReload', boolean).value(Settings.GSP_ENABLE_RELOAD, 'false')
        field('cacheSeconds', int).value(Settings.I18N_CACHE_SECONDS, '5')
        field('fileCacheSeconds', int).value(Settings.I18N_FILE_CACHE_SECONDS, '5')
        field('localeResolverType', String).value(Settings.I18N_LOCALE_RESOLVER, 'session')
        field('defaultLocale', String).value('grails.i18n.default.locale', '')

        method('fixedLocale', Locale) {
            if (StringUtils.hasText(defaultLocale)) {
                Locale parsed = StringUtils.parseLocale(defaultLocale)
                if (parsed != null) {
                    return parsed
                }
            }
            Locale.getDefault()
        }

        bean(LocaleResolver).conditionalOnMissingBeanName(search: SearchStrategy.CURRENT) {
            String normalized = localeResolverType == null ? '' :
                    localeResolverType.toLowerCase(Locale.ROOT).replaceAll('[^a-z]', '')
            switch (normalized) {
                case 'cookie':
                    return new CookieLocaleResolver('locale')
                case 'acceptheader':
                case 'header':
                case 'accept':
                    return new AcceptHeaderLocaleResolver()
                case 'fixed':
                    return new FixedLocaleResolver(fixedLocale())
                default:
                    return new SessionLocaleResolver()
            }
        }

        bean(LocaleChangeInterceptor).conditionalOnMissingBeanName(search: SearchStrategy.CURRENT) {
            new ParamsAwareLocaleChangeInterceptor(paramName: 'lang')
        }

        bean(MessageSource).conditionalOnMissingBeanName(search: SearchStrategy.CURRENT) { GrailsApplication grailsApplication, GrailsPluginManager pluginManager ->
            // Captured before tap: the message source has cacheSeconds/fileCacheSeconds
            // properties of its own, which inside tap would shadow these injected fields.
            int configuredCacheSeconds = cacheSeconds
            int configuredFileCacheSeconds = fileCacheSeconds
            new PluginAwareResourceBundleMessageSource(grailsApplication, pluginManager).tap {
                defaultEncoding = encoding
                fallbackToSystemLocale = false
                if (Environment.current.reloadEnabled || gspEnableReload) {
                    cacheSeconds = configuredCacheSeconds
                    fileCacheSeconds = configuredFileCacheSeconds
                }
            }
        }

        bean(AvailableLocaleResolver).conditionalOnMissingBean() { GrailsApplication grailsApplication,
                @Value('${grails.i18n.availableLocales.includePlugins:true}') boolean includePlugins ->
            new AvailableLocaleResolver(grailsApplication.classLoader, fixedLocale(), includePlugins)
        }
    }

Two simplifications versus the original, both functionally identical: bean names are the literal strings 'localeResolver'/'messageSource' rather than references to DispatcherServlet.LOCALE_RESOLVER_BEAN_NAME/AbstractApplicationContext.MESSAGE_SOURCE_BEAN_NAME (bean(name, Type) requires a String literal, and those constants' values are exactly those strings); and the original's LocaleResolverStrategy enum plus its resolveStrategy(String) helper are inlined as a plain switch on a normalized string, since the DSL can't declare a nested type.

The bean name argument itself is optional, same as it is on field(...)/method(...): all four beans derive their Spring names from their types via Introspector.decapitalize() (LocaleResolver → 'localeResolver', MessageSource → 'messageSource', ...) — exactly the values the original file's DispatcherServlet.LOCALE_RESOLVER_BEAN_NAME/AbstractApplicationContext.MESSAGE_SOURCE_BEAN_NAME constants carry. For the three name-guarded beans, .conditionalOnMissingBeanName(...) then feeds that same derived name into the condition's name member, so the bean name and the back-off name are one statement that cannot diverge; availableLocaleResolver's bare .conditionalOnMissingBean() is type-based, with Spring inferring the type from the method's return type. The derived names remain contractual — external code (e.g. grails-test-suite-uber's PluginTests.java) references localeChangeInterceptor by literal string — so a bean's type rename would change its derived name and break those references.

The sibling's name derives from the plugin-descriptor convention: a *GrailsPlugin class swaps that suffix for AutoConfiguration, so bare @GrailsBeans on I18nGrailsPlugin regenerates exactly the class identity I18nAutoConfiguration had before this conversion — anything referencing it by name (AutoConfiguration.imports, another auto-configuration's beforeName/afterName, a test importing it directly) keeps working unchanged, with no attribute needed. A class not ending in GrailsPlugin appends AutoConfiguration instead, and @GrailsBeans(autoConfigurationName = "...") overrides either derivation.

What the DSL above actually compiles to — the generated I18nAutoConfiguration sibling, shown here as its Java equivalent (verified via javap: nothing DSL-specific survives into the real bytecode — the beans closure itself is gone, and the one tap block in the messageSource body compiles the way tap does in any statically-compiled Groovy class: an inner closure class, no dynamic dispatch):

@AutoConfiguration(before = {MessageSourceAutoConfiguration.class, WebMvcAutoConfiguration.class})
@ConditionalOnWebApplication(type = ConditionalOnWebApplication.Type.SERVLET)
public class I18nAutoConfiguration {

    @Value("${grails.views.gsp.encoding:UTF-8}")
    private String encoding;

    @Value("${grails.gsp.enable.reload:false}")
    private boolean gspEnableReload;

    @Value("${grails.i18n.cache.seconds:5}")
    private int cacheSeconds;

    @Value("${grails.i18n.filecache.seconds:5}")
    private int fileCacheSeconds;

    @Value("${grails.i18n.localeResolver:session}")
    private String localeResolverType;

    @Value("${grails.i18n.default.locale:}")
    private String defaultLocale;

    private Locale fixedLocale() {
        if (StringUtils.hasText(defaultLocale)) {
            Locale parsed = StringUtils.parseLocale(defaultLocale);
            if (parsed != null) {
                return parsed;
            }
        }
        return Locale.getDefault();
    }

    @Bean("localeResolver")
    @ConditionalOnMissingBean(name = "localeResolver", search = SearchStrategy.CURRENT)
    public LocaleResolver localeResolver() {
        String normalized = localeResolverType == null ? "" :
                localeResolverType.toLowerCase(Locale.ROOT).replaceAll("[^a-z]", "");
        switch (normalized) {
            case "cookie":
                return new CookieLocaleResolver("locale");
            case "acceptheader":
            case "header":
            case "accept":
                return new AcceptHeaderLocaleResolver();
            case "fixed":
                return new FixedLocaleResolver(fixedLocale());
            default:
                return new SessionLocaleResolver();
        }
    }

    @Bean("localeChangeInterceptor")
    @ConditionalOnMissingBean(name = "localeChangeInterceptor", search = SearchStrategy.CURRENT)
    public LocaleChangeInterceptor localeChangeInterceptor() {
        ParamsAwareLocaleChangeInterceptor localeChangeInterceptor = new ParamsAwareLocaleChangeInterceptor();
        localeChangeInterceptor.setParamName("lang");
        return localeChangeInterceptor;
    }

    @Bean("messageSource")
    @ConditionalOnMissingBean(name = "messageSource", search = SearchStrategy.CURRENT)
    public MessageSource messageSource(GrailsApplication grailsApplication, GrailsPluginManager pluginManager) {
        int configuredCacheSeconds = this.cacheSeconds;
        int configuredFileCacheSeconds = this.fileCacheSeconds;
        PluginAwareResourceBundleMessageSource source = new PluginAwareResourceBundleMessageSource(grailsApplication, pluginManager);
        source.setDefaultEncoding(encoding);
        source.setFallbackToSystemLocale(false);
        if (Environment.getCurrent().isReloadEnabled() || gspEnableReload) {
            source.setCacheSeconds(configuredCacheSeconds);
            source.setFileCacheSeconds(configuredFileCacheSeconds);
        }
        return source;
    }

    @Bean
    @ConditionalOnMissingBean
    public AvailableLocaleResolver availableLocaleResolver(GrailsApplication grailsApplication,
            @Value("${grails.i18n.availableLocales.includePlugins:true}") boolean includePlugins) {
        return new AvailableLocaleResolver(grailsApplication.getClassLoader(), fixedLocale(), includePlugins);
    }
}

This isn't just plausible-looking: the full pre-existing grails-i18n test suite (conditional back-off by name and SearchStrategy.CURRENT, property-driven strategy selection, parent-context isolation, ordering against GrailsLocaleResolverAutoConfiguration) passes unmodified against the generated class, now renamed back to I18nAutoConfigurationSpec.groovy to match.

A Plugin subclass is instantiated by DefaultGrailsPlugin via plain reflection, never as a Spring bean, so it can't itself carry @Bean methods or a meaningful @AutoConfiguration/@Conditional* annotation. In this form, the compiled members land on a generated sibling class in the same package, named by the plugin-descriptor convention — a *GrailsPlugin class swaps that suffix for AutoConfiguration (I18nGrailsPlugin → I18nAutoConfiguration here), any other name appends it, and @GrailsBeans(autoConfigurationName = "...") overrides both. Every annotation that only makes sense on whatever Spring Boot actually evaluates moves onto that sibling, not just @AutoConfiguration: the whole @Conditional* family, @Import/@ImportAutoConfiguration/@ImportResource, @ComponentScan, @EnableConfigurationProperties, @PropertySource/@PropertySources, @AutoConfigureOrder/Before/After — including a composed annotation built on top of any of these (e.g. a project-specific @ConditionalOnFeature meta-annotated with Spring Boot's own @ConditionalOnProperty, found by walking the meta-annotation chain rather than requiring an exact match). An annotation outside that set stays put, since no automatic determination from metadata can cover annotations this transform has never heard of — name those explicitly with @GrailsBeans(moveAnnotations = [SomeVendorAnnotation]) and they move the same way. @AutoConfiguration is required on the plugin class (even bare) whenever this form is used — omitting it is a compile-time error, not a silent runtime gap, since the generated sibling would otherwise never be processed by Boot.

Registration

Because the result is an ordinary @AutoConfiguration class, it must be registered in META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports like any other. Apply the new org.apache.grails.buildsrc.autoconfiguration-imports convention plugin to generate that file automatically at build time by scanning the module's compiled classes for @AutoConfiguration — no hand-maintained imports file:

plugins {
    id 'org.apache.grails.buildsrc.autoconfiguration-imports'
}

grails-databinding is converted to it here, so its hand-maintained imports file is deleted; the task fails if a module keeps both, since the two copies land at the same path in the jar.

(grails-i18n predates this convention plugin and hand-maintains its imports file instead — either way works, the convention plugin just saves remembering to update it.)

Bugs found while converting

Converting the framework's own auto-configurations surfaced five defects, all silent and none caught by existing tests. Each is a separate commit and can be reviewed — or cherry-picked to a maintenance line — on its own.

Component scanning ignored grails.spring.bean.packages outside the project directory (0161f9d). This is the one worth reviewing on its own merits, and it is present on 7.1.x and 7.2.x as well. BuildSettings resolves CLASSES_DIR from a working-directory-relative probe:

boolean grailsAppDirPresent = new File('grails-app').exists() || new File('Application.groovy').exists()
if (!grailsAppDirPresent) { CLASSES_DIR = null }

and the scanner wrapped its entire resource lookup in if (BuildSettings.CLASSES_DIR != null), returning an empty array everywhere else. Reproduced on released 8.0.0-M4 by running one jar from two directories — started from the project root the scanned @Component registered, started from an empty directory it did not, same jar and same application.yml. That covers a systemd unit, a container with its own WORKDIR, or an app server, while sparing java -jar build/libs/app.jar from the project root, which is presumably why it survived. The custom resolution is replaced by PathMatchingResourcePatternResolver's own; the closure-class filter and plugin TypeFilters are kept. Applications that deploy this way will start getting beans they currently miss. Documented in the 8.0 upgrade guide, with the two things worth checking before upgrading: a duplicate bean name that now fails startup, and an injection point that was unambiguous becoming ambiguous.

grails.spring.placeholder.prefix never applied (100b9db). The configurer is a BeanFactoryPostProcessor, so its configuration class is built before @Value injection is active and the injected field was always null.

grails.gorm.autoTimestampCacheAnnotations never reached its consumers (1544bd7). The default was written with Config.put, but AutoTimestampEventListener and DomainModelServiceImpl read it through @Value("${...}"), which resolves against the environment. Development mode cached annotations — the opposite of the intent.

Sitemesh3EnvironmentPostProcessor never ran (da28b4f), registered under org.springframework.boot.env.EnvironmentPostProcessor, which Spring Boot 4 deprecated forRemoval and no longer loads. Its warning could not have printed anyway, logging from a phase that precedes Boot's logging initialisation; it now takes DeferredLogFactory and logs at error.

Three of those trace to one cause, since removed (2930502): GrailsPlaceholderConfigurer advertised GrailsConfigurationAware while being created before the BeanPostProcessor that populates it, so its Config was always null.

Limitations

The DSL still covers a narrower surface than doWithSpring(BeanBuilder):

• Each top-level statement inside beans { } must be exactly bean(...), field(...), or method(...) with their respective chaining — an if, a for loop, or any other imperative Groovy directly inside beans { } is a compile-time error. This is about the DSL's own top-level statements, not the bodies of bean(...)/method(...) closures, which accept arbitrary Groovy — field(...)/method(...) already cover the common reasons to want shared state or logic in the first place.
• .annotate(...) attribute values must resolve to a constant at compile time: a literal, a reference to a static final field, or a concatenation of those. Resolution happens while the DSL is compiled, before @CompileStatic runs, so it makes no difference whether the constant is declared on an interface or a class. What can't be used is anything that isn't a compile-time constant — a method call, a local, a value read from configuration. An attribute that itself takes a nested annotation isn't supported, and field(...)/method(...) can't declare a nested type (no inner enums/classes).
• Dependencies on other beans are expressed through typed closure parameters, autowired by type; there is no ref('beanName') lookup. Where the type alone is ambiguous, select by name with a parameter annotation — @Qualifier('beanName'), as DomainClassGrailsPlugin does for its MappingContext.
• A bean(...)/method(...) body can't reach members of the Plugin it was written in. The body is relocated onto the generated sibling, which extends Object and holds no reference to the plugin, so reading config, grailsApplication or applicationContext from a body fails — at compile time under @CompileStatic, otherwise not until Spring invokes the factory method. This is the habit worth unlearning when converting from doWithSpring, whose closures read plugin state freely: take injected configuration through field(...), and a GrailsApplication (or any other bean) through a typed closure parameter.
• Abstract parent bean definitions can't be stated directly — not in the DSL, and not through beanRegistrar()'s BeanRegistry.Spec, whose registerBean overloads all take a class and which has no parent/abstract setting. A classless definition existing only to be inherited therefore has to be contributed one level down, from a BeanDefinitionRegistryPostProcessor that reaches the underlying registry. CoreGrailsPlugin does exactly that for abstractGrailsResourceLocator — public surface, since third-party plugins inherit from it with bean.parent, asset-pipeline's assetResourceLocator among them — so this costs a small post-processor rather than keeping the bean builder DSL alive.

@GrailsBeans is independent of Plugin/beanRegistrar()/doWithSpring — reach for it specifically when a bean's registration needs ordering or conditioning against a particular other auto-configuration; beanRegistrar() remains the recommended way to register beans from a Plugin otherwise. Both are documented side by side in grails-doc/src/en/guide/plugins/hookingIntoRuntimeConfiguration.adoc, and application usage — including directly on the Application class — in the Grails-and-Spring chapter (spring/springdslAdditional.adoc).

[codecov]

Codecov Report

❌ Patch coverage is 83.01246% with 150 lines in your changes missing coverage. Please review.
✅ Project coverage is 52.1890%. Comparing base (57883c4) to head (9f18a77).

Files with missing lines	Patch %	Lines
...s/compiler/beans/GrailsBeansASTTransformation.java	86.2559%	30 Missing and 57 partials ⚠️
...ion/GlobalGrailsClassInjectorTransformation.groovy	66.6667%	4 Missing and 8 partials ⚠️
.../groovy/org/grails/plugins/CoreGrailsPlugin.groovy	86.2069%	3 Missing and 5 partials ⚠️
...t/annotation/GrailsComponentScanPostProcessor.java	61.9048%	5 Missing and 3 partials ⚠️
...roovy/grails/plugin/cache/CacheGrailsPlugin.groovy	65.0000%	4 Missing and 3 partials ⚠️
...vy/org/grails/plugins/i18n/I18nGrailsPlugin.groovy	74.0741%	3 Missing and 4 partials ⚠️
...lassIgnoringComponentScanBeanDefinitionParser.java	0.0000%	5 Missing ⚠️
...sitemesh3/Sitemesh3EnvironmentPostProcessor.groovy	42.8571%	4 Missing ⚠️
...ils/plugins/sitemesh3/Sitemesh3GrailsPlugin.groovy	75.0000%	1 Missing and 3 partials ⚠️
...ails/plugins/domain/DomainClassGrailsPlugin.groovy	40.0000%	2 Missing and 1 partial ⚠️
... and 3 more

Additional details and impacted files

@@               Coverage Diff                @@
##             8.0.x     #16019         +/-   ##
================================================
+ Coverage         0   52.1890%   +52.1890%     
- Complexity       0      18360      +18360     
================================================
  Files            0       2044       +2044     
  Lines            0      96915      +96915     
  Branches         0      16910      +16910     
================================================
+ Hits             0      50579      +50579     
- Misses           0      38893      +38893     
- Partials         0       7443       +7443     

Files with missing lines	Coverage Δ
.../web/controllers/ControllersAutoConfiguration.java	95.0820% <ø> (ø)
...g/context/support/GrailsPlaceholderConfigurer.java	88.2353% <100.0000%> (ø)
...plugins/databinding/DataBindingGrailsPlugin.groovy	100.0000% <100.0000%> (ø)
...ns/i18n/GrailsLocaleResolverAutoConfiguration.java	66.6667% <ø> (ø)
.../domain/DomainClassEnvironmentPostProcessor.groovy	85.7143% <85.7143%> (ø)
...ng/beans/AbstractResourceLocatorPostProcessor.java	83.3333% <83.3333%> (ø)
...plugins/web/mapping/UrlMappingsGrailsPlugin.groovy	47.0588% <81.8182%> (ø)
...ails/plugins/domain/DomainClassGrailsPlugin.groovy	40.0000% <40.0000%> (ø)
...sitemesh3/Sitemesh3EnvironmentPostProcessor.groovy	76.0000% <42.8571%> (ø)
...ils/plugins/sitemesh3/Sitemesh3GrailsPlugin.groovy	75.0000% <75.0000%> (ø)
... and 7 more

... and 2027 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[codeconsole]

Review comments are answered inline, each naming the commit its fix landed in. Four threads note where I did something different from what was suggested.

d8f2a7b78b adds one shape to the DSL that did not come from the review: a bean closure with parameters and an empty body constructs the declared type from those parameters.

bean('validateableConstraintsEvaluator', DefaultConstraintEvaluatorFactoryBean).lazy() {
        List<MessageSource> messageSources,
        @Qualifier('grailsDomainClassMappingContext') MappingContext mappingContext,
        GrailsApplication grailsApplication ->
}

The parameters are what gets injected; the body is generated as new DefaultConstraintEvaluatorFactoryBean(messageSources, mappingContext, grailsApplication). A body is still needed when construction is more than passing the parameters through — new ConfigProperties(grailsApplication.config), or anything followed by .tap { }. Documented in the guide and on @GrailsBeans.

Applied to five declarations: the constraint evaluator, the three mail beans and the CORS filter.

grails.util.GrailsUtilStackFiltererSpec and org.apache.grails.core.GrailsBootstrapRegistryInitializerSpec fail on 8.0.x independently of this branch.

[jdaugherty]

I asked AI to take another pass at this, overall I think this is the right solution at this point and I'll approve later today after some further testing.

Second pass, against 297767a.

Everything from the previous round is fixed. I checked each one against the branch rather than the commit messages: the interface walk and GroovyBugError catch, foldStringValue, the chained-root rejection, the derived-name identifier check, removeField, @TypeChecked propagation, the five source positions, the name:/search:-only back-off, the four upgrade-guide rows, the three documentation corrections, GreetingAutoConfiguration, the ASM-based imports scan, the Settings constants in UrlMappingsGrailsPlugin, the single api declaration and the seven deletions, the restored javadoc, the narrowed implicit trigger, and both example modules under grails-test-examples/. The 157 specs in grails-beans-dsl pass, grails-databinding:generateAutoConfigurationImports produces exactly org.grails.plugins.databinding.DataBindingAutoConfiguration, and the i18n specs genuinely exercise the beforeName ordering rather than declaration order. Those threads are resolved.

Six notes from this pass. The first is a compiler crash in the empty-body form added since the last round; the rest are documentation and diagnostics, plus one condition that came off in the cache conversion.

[jdaugherty]

The synthesized ConstructorCallExpression is the one generated node in this file with no setSourcePosition(...), and it is the node most likely to be the subject of a compile error: the constructor is selected from the closure's parameter types, so a parameter list matching no constructor — after someone adds an argument to the type's constructor, say — is the ordinary failure mode of the empty-body form.

Without a position the failure never reaches the error collector as a located message. Compiling the documented shape:

class NeedsString {
    NeedsString(String required) { }
}

@GrailsBeans
@CompileStatic
@AutoConfiguration
class ProbeWrongParams {
    def beans = {
        bean(NeedsString) { Integer n ->
        }
    }
}

In a normal build (assertions off):

org.codehaus.groovy.GroovyBugError: BUG! exception in phase 'class generation' in source unit '...' at line -1 column -1
On receiver: NeedsString with message: <$constructor$> and arguments: (n)
StaticTypesCallSiteWriter#makeCallSite should not have been called. Call site lacked method target for static compilation.
Please try to create a simple example reproducing this error and file a bug report at https://issues.apache.org/jira/browse/GROOVY

Under -ea — which is what Gradle's test workers run with, so it is what a plugin author sees from ./gradlew test — it degrades further, to a bare java.lang.AssertionError: null out of StaticCompilationVisitor.visitConstructorCallExpression. The bodyless bean(NeedsString) spelling fails identically. Same failure class as the getTypeClass() one: an internal compiler error at line -1 in place of a located message, with an invitation to file a Groovy bug.

The discrepancy is that the hand-written equivalent this is documented as compiling to is diagnosed properly:

[Static type checking] - Cannot find matching constructor NeedsArgsHand(). Please check if the declared type is correct and if the method exists.
 @ line 15, column 43.
               bean(NeedsArgsHand) { new NeedsArgsHand() }
                                     ^

So "resolved from these argument types exactly as it would be for a hand-written new Type(...)" holds for resolution but not for what the author is told when it fails.

Copying the position onto the construction closes it. Verified against the branch:

ConstructorCallExpression construction =
        new ConstructorCallExpression(beanType, constructorArguments(beanParameters));
construction.setSourcePosition(baseCall);

after which the same fixture reports

[Static type checking] - Cannot find matching constructor NeedsString(java.lang.Integer). Please check if the declared type is correct and if the method exists.
 @ line 15, column 21.
               bean(NeedsString) { Integer n ->
               ^

pointing at the bean(...) statement. A test would help: the spec has no case for a constructor mismatch in either the bodyless or the empty-body form, which is why this got through.

[codeconsole]

Fixed in a4deb3d2cd. Reproduced exactly as described — BUG! at line -1 for the empty-body form, against a located "Cannot find matching constructor" for the hand-written equivalent.

The position now goes on the whole synthesized construction: the ConstructorCallExpression, its argument list, each VariableExpression, and the enclosing ReturnStatement. Both spellings now report

[Static type checking] - Cannot find matching constructor NeedsString(java.lang.Integer).
 @ line 15, column 13.
               bean(NeedsString) { Integer n ->
               ^

Two tests, one per spelling, asserting the message and that it contains neither line -1 nor BUG!.

[jdaugherty]

The exception this bullet still carries is stale in the same way the concatenation one was, and for the same reason: foldStringValue resolves the value during canonicalization, before @CompileStatic's transform runs, so there is no reference left for it to rewrite into a getter call.

A static final on a Groovy class does fold. All four combinations, with @CompileStatic on the annotated class:

constant owner	.value(KEY, 'x')	.annotate(Value, value: '${' + KEY + ':y}')
same-compilation-unit Groovy class	${probe.key:x}	${probe.key:y}
already-compiled Groovy class	${precompiled.probe.key:x}	${precompiled.probe.key:y}

A bare reference as the whole attribute value folds too — .annotate(Value, value: PrecompiledKeys.KEY) gives precompiled.probe.key.

findStaticFinalField reads the FieldNode, and a Groovy property's backing field is still static final with its initial expression intact, so the property-versus-field distinction the bullet turns on no longer has any effect. As written it steers readers away from a shape that works — which is what the earlier version of this bullet did with Settings.

[codeconsole]

You're right, and this bullet has now been wrong twice. The previous correction removed the concatenation claim but kept this exception on the strength of your earlier report — which predated the fix that changed the behaviour. I should have tested it rather than carrying it forward.

Confirmed all three shapes fold with the constant on a Groovy class under @CompileStatic: .value(KEY, 'x') → ${probe.key:x}, the concatenation → ${probe.key:y}, a bare reference → probe.key.

Rewritten in f31d57061f to say what actually holds — values must resolve to a compile-time constant, resolution happens before @CompileStatic runs, so interface-versus-class makes no difference — with three unrolled cases so it cannot drift again. PR description updated to match.

[jdaugherty]

These four rows cover every FQCN change, but not the one change in this PR that alters which beans a running application ends up with.

The component-scan fix means an application whose working directory is not the project root — a systemd unit, a container with its own WORKDIR, an app server — starts registering @Components under grails.spring.bean.packages that it silently did not register before. The PR description says so plainly ("Applications that deploy this way will start getting beans they currently miss"); the guide says nothing.

It arguably deserves a row here more than the renames do. A stale exclude entry leaves a name that no longer resolves, which someone can at least search for; this one changes the contents of a running context with nothing to grep for, and in the direction of adding beans — a duplicate registration or an unexpected @Component picking up a bean name is how it will present.

Worth noting while you are here that grails.spring.bean.packages appears nowhere in grails-doc at all, so there is no existing page describing the property for this to cross-reference.

[codeconsole]

Agreed it matters more than the renames. Added as section 39 in 4e51a2556a, covering the working-directory probe, which deployment shapes it affected, and the two things to check before upgrading: a duplicate bean name that now fails startup, and an injection point that was unambiguous becoming ambiguous.

Noted that grails.spring.bean.packages appears only in the Application Properties reference, so there is nothing to cross-reference.

The section is numbered 39 after the duplicate 38.s. Those, and a duplicate 34., are both on 8.0.x — I checked — so renumbering belongs in its own PR against 8.0.x rather than as seven unrelated heading changes here.

[jdaugherty]

This branch fires for a shape that has nothing to do with argument order, and the message then sends the reader somewhere unrelated. Chaining a qualifier after the factory closure rather than before it:

bean(String) { 'hi' }.lazy()

bean(...) takes the name before the type: bean("myGreeter", Greeter), not bean(Greeter, "myGreeter")
 @ line 9, column 34.
               bean(String) { 'hi' }.lazy()
                            ^

The named spelling avoids the wrong advice but is no more useful:

bean('greeting', String) { 'hi' }.lazy()

bean(...) requires a type, optionally preceded by a name, e.g. bean(Greeter) or bean("myGreeter", Greeter)

It arrives here because factory is read off outerCall's arguments, so a closure sitting on baseCall is never stripped and is still in baseArgs at this point. Both spellings are a plausible first guess: the closure reads as belonging to bean(...), and it is where a body goes in every other DSL a Grails author writes. method('name', Type) { ... }.annotate(X) lands the same way, via "method(...) must end with a body closure".

Detecting a trailing ClosureExpression on the base call when qualifiers are present, and saying that qualifiers come before the body, is a one-line diagnostic — and a row in the malformed-statement table.

[codeconsole]

Fixed in a4deb3d2cd. bean(String) { 'hi' }.lazy() now reports

the body closure comes last, after every chained qualifier - write bean(...).lazy(...) { ... }
rather than bean(...) { ... }.lazy(...)

Put on the shared statement path rather than in bean(...), so field(...) and method(...) get it too — method('x', String) { 'y' }.annotate(...) was landing on "must end with a body closure" the same way. Three table rows.

[jdaugherty]

@ConditionalOnBean(CachePluginConfiguration) came off in this conversion and nothing replaces it. The deleted GrailsCacheAutoConfiguration carried it with the reason spelled out:

Gated on the CachePluginConfiguration definition contributed by the cache plugin descriptor's registrar (which runs before auto-configuration conditions are evaluated), so the auto-configuration backs off entirely when the plugin is not active — e.g. the jar is on the classpath but the plugin is excluded — keeping it in lockstep with the descriptor.

The gate could not survive verbatim: grailsCacheConfiguration is now declared in this same beans block rather than by the registrar, so it would be conditioning on a bean the same class contributes. But the condition it expressed has gone with it. With only @ConditionalOnBooleanProperty(name = 'grails.cache.enabled') left, a build with grails-cache on the classpath but the plugin not loaded now gets grailsCacheConfiguration, grailsCacheAdminService, customCacheKeyGenerator and grailsCacheManager registered anyway — exactly the case the deleted comment named.

Is that deliberate, i.e. is jar-on-the-classpath now sufficient for the cache beans, the way it is for an ordinary Boot starter? If so the class javadoc should say it: it explains the back-off design carefully but is silent on the lockstep that was dropped. If not, the descriptor no longer contributes anything for the generated configuration to gate on, so restoring it needs a different anchor — either way better decided explicitly than by omission.

Two smaller notes on the same move. environment.getProperty('grails.cache.enabled', Boolean, true) and @ConditionalOnBooleanProperty do not agree on non-canonical values: Spring's Boolean conversion accepts yes/on/1, the condition matches only true/false, so grails.cache.enabled=no used to disable the plugin and now leaves it enabled. And the log.warn('Cache plugin is disabled') that accompanied the old gate is gone, so disabling it is now silent.

[codeconsole]

Deliberate, and now stated in the class javadoc (33c9ee771d) rather than left to omission: the jar being present is sufficient, as for an ordinary Boot starter. The gate cannot be restated once grailsCacheConfiguration is declared in this same block — it would condition on a bean the class contributes — and the plugin declares no profiles or environments, so it is active wherever its jar is. That is what makes it a change of mechanism rather than of which applications get the beans. The javadoc says a descriptor that later becomes conditionally inactive needs a new anchor.

On the property: real, but the direction is the other way round. Comparing @ConditionalOnBooleanProperty against config.getProperty(..., Boolean, true):

value	condition	old conversion
no / off / 0	disabled	disabled
yes / on / 1	disabled	enabled

So =no is unchanged; =yes is the regression. And it was worse than a disagreement: doWithApplicationContext re-read the flag with the relaxed conversion, so on =yes it believed caching was on and asked for grailsCacheConfiguration — which the condition had just declined to register. Startup failure.

That hook is now keyed on applicationContext.containsBean(...), which cannot drift from the condition that decided it. The log.warn is restored with it.

Covered in 9f18a77067: three unrolled cases for yes/on/1 asserting the beans are absent and the hook backs off. Against the previous implementation all three fail with NoSuchBeanDefinitionException, and a fourth case runs the hook on the enabled context so the back-off cannot pass by being taken unconditionally.

[jdaugherty]

Carrying this forward from the scope thread so it does not get lost with it, since that thread's actual question — one story for the nine declarations — is settled.

Nothing reads @GrailsBeans at runtime. The transform consumes it at canonicalization, and it is not among the annotations moved to the generated sibling, so it stays on the source class where it is inert. RetentionPolicy.CLASS would leave every compile-time use working while keeping it out of the runtime image — which matters slightly more now that grails-core declares grails-beans-dsl as api and so puts it, and its own spring-context/spring-boot-autoconfigure api dependencies, on every application's runtime classpath.

Not a blocker, and I am fine with either answer. If RUNTIME is deliberate — leaving room for a runtime consumer later, say — a line on the annotation saying so is enough to close it.

[codeconsole]

Changed to CLASS in 4e51a2556a, with a comment on the annotation recording why.

Nothing reads it: every converted module passes with it invisible, and ExampleBeans — which declares it explicitly — reports only @AutoConfiguration at runtime. It is a new annotation on an unreleased branch, so there is no compatibility cost, and your point about grails-core declaring the module api is what tipped it.

[testlens-app]

✅ All tests passed ✅

🏷️ Commit: 9f18a77
▶️ Tests: 66861 executed
⚪️ Checks: 62/62 completed

---

Learn more about TestLens at testlens.app.