BeanRegistrar

A BeanRegistrar registers beans in code, deciding at startup how many beans, which ones and under which names.

Why

Annotations declare a fixed set of beans. A registrar decides in code, based on the configuration:

• a library that registers one bean per configured entry;
• a bean that exists only when a property is set;
• an implementation picked from a property.

Most applications do not need one. @Profile and @Conditional cover the usual cases.

Use a registrar in one of two ways:

• put the class in @Import on a configuration class. The generator creates it with its no-argument constructor;
• pass an instance to context.register(...) before refresh().

register runs once, while the modules load. No bean exists yet. It runs right after the importing class's @Bean methods are registered, and only when that class is registered: the class's conditions decide for the class and its imports together. Every later class and auto-configuration sees the beans, so their @ConditionalOnMissingBean backs off. The registrar can read the environment, including the @PropertySource files loaded so far.

The supplier creates the bean when it is needed. It receives a DependencyResolver to get the bean's own dependencies: context.dependency<Clock>(), context.optionalDependency<Clock>(), context.dependencyList<Handler>(), context.value<int>(r'${port:8080}').

Two lower-level forms exist:

• ImportSelector returns the BeanModules to load, chosen at startup. DeferredImportSelector runs after every other module, so its beans can back off.
• ImportBeanDefinitionRegistrar registers full BeanDefinitions and can see, replace or remove the ones already registered.

Example

import 'package:spring_core_dart/spring_core_dart.dart';

abstract interface class Clock {
  DateTime now();
}

class SystemClock implements Clock {
  @override
  DateTime now() => DateTime.now();
}

abstract interface class Mailer {
  void send(String to, String text);
}

class SmtpMailer implements Mailer {
  SmtpMailer(this.host, this.clock);
  final String host;
  final Clock clock;

  @override
  void send(String to, String text) {}
}

class Tenant {
  Tenant(this.id);
  final String id;
}

// A clock always; an SMTP mailer only when a mail host is configured;
// one Tenant bean per entry of `tenants`.
class MessagingRegistrar implements BeanRegistrar {
  const MessagingRegistrar();

  @override
  void register(BeanRegistry registry, Environment environment) {
    registry.registerBean<Clock>((_) => SystemClock(), name: 'clock');

    final host = environment.getProperty('mail.host');
    if (host != null) {
      registry.registerBean<Mailer>(
        (context) => SmtpMailer(host, context.dependency<Clock>()),
        name: 'mailer',
        primary: true,
        lazy: true,
        description: 'SMTP mailer',
      );
    }

    final tenants = environment.getProperty('tenants') ?? '';
    for (final id in tenants.split(',').where((id) => id.isNotEmpty)) {
      registry.registerBean<Tenant>((_) => Tenant(id), name: 'tenant-$id');
    }
  }
}

@Configuration()
@Import([MessagingRegistrar])
class AppConfig {}

Outside a registrar, AnnotationConfigApplicationContext.registerBean takes the same options:

final context = AnnotationConfigApplicationContext([appBeans])
  ..registerBean<Clock>((_) => SystemClock(), name: 'clock')
  ..refresh();

Members

BeanRegistrar:

BeanRegistry:

Options of registerBean:

In Spring (Java)

Spring 7's BeanRegistrar:

class MessagingRegistrar implements BeanRegistrar {
  @Override
  public void register(BeanRegistry registry, Environment env) {
    registry.registerBean("clock", SystemClock.class);
    if (env.containsProperty("mail.host")) {
      registry.registerBean("mailer", Mailer.class, spec -> spec
          .supplier(context -> new SmtpMailer(context.bean(Clock.class)))
          .primary().lazyInit().description("SMTP mailer"));
    }
  }
}

@Configuration
@Import(MessagingRegistrar.class)
class AppConfig {}

Differences that matter:

• The supplier is required. Dart has no reflection to call a constructor.
• The options are named parameters instead of a Spec builder.
• An ImportSelector returns BeanModules, not class names, and receives no annotation metadata of the importing class.

See also

• @Import
• BeanModule
• BeanFactoryPostProcessor (BeanDefinitionRegistryPostProcessor)
• @Conditional
• @Profile
• ApplicationContext (register, registerBean)
• Environment