PodRegistrar class abstract interface

A contract in JetLeaf for components that can register pods into the application’s dependency container.

A PodRegistrar is responsible for describing how specific pods should be registered with the `PodRegistry`.
Implementations are automatically instantiated by the JetLeaf pod factory at startup, so any class implementing this interface must provide a no-argument constructor. Failure to do so will prevent automatic registration of pods.

Lifecycle & Workflow

When the JetLeaf application context starts:

1. Registrar Discovery

   • The pod factory scans for all classes implementing PodRegistrar.
   • It instantiates each registrar using the no-arg constructor.

2. Registration Phase

   • The register method of each registrar is called with:
     • PodRegistry: the central registry for managing pods.
     • Environment: access to runtime properties, profiles, and configuration.

3. Pod Declaration

   • Within register, implementers declare the pods that should exist in the container:
     • Either via registry.registerPod(...) for individual pod registration.
     • Or by delegating to other registrars if needed.

4. Initialization

   • Once registration is complete, the pod factory resolves dependencies, initializes pods according to their lifecycle (singleton, prototype, etc.), and applies ordering if the registrars implement Ordered.

Implementation Guidelines

• Must have a public no-arg constructor because the pod factory must not have been initialized creates instances reflectively.
• Can optionally implement Ordered to control registration order relative to other registrars.
• Use the Environment parameter to conditionally register pods based on configuration, profiles, or system properties.
• Registrars should focus on declaration, not business logic.

Example

@Component() // If to be discovered by the scanner. Any stereotype annotation can suffice
class MyServiceRegistrar implements PodRegistrar {
  // No-arg constructor is required for reflection-based instantiation
  MyServiceRegistrar();

  @override
  void register(PodRegistry registry, Environment env) {
    // Register a singleton pod
    registry.registerPod(Class<MyService>(), customizer: (spec) {
      spec.namedAs('myService').withScope(ScopeType.singleton);
    });

    // Conditionally register based on environment
    if (env.getPropertyAs<bool>('featureX.enabled', Class<bool>()) == true) {
      registry.registerPod(Class<FeatureXService>());
    }
  }
}

Notes

• JetLeaf guarantees that all discovered registrars are invoked once during startup.
• Registration is performed before any pod dependencies are injected.
• Improper constructors (e.g., missing no-arg constructor) will cause registrars to be skipped.