context library

🌱 Jetleaf Application Context Subsystem

This library provides the core application context abstractions for the Jetleaf framework. The ApplicationContext is the central coordinating engine that provides:

  • IoC Container Management: Instantiating, configuring, and wiring pods.
  • Event Multicasting: Decoupled publisher-subscriber event bus infrastructure.
  • Lifecycle Orchestration: Coordinated startup and shutdown phases.
  • Environment Integration: Access to active profiles and property sources.
  • Resource & Type Discovery: Type filtering, classpath scanning, and module modularization.

πŸ”„ Application Context Lifecycle Phases

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚                 Application Context Lifecycle               β”‚
β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
β”‚ 1. Bootstrap Phase      Create context & bind Environment   β”‚
β”‚                               β”‚                             β”‚
β”‚ 2. Configuration Phase  Register modules & definitions      β”‚
β”‚                               β”‚                             β”‚
β”‚ 3. Processor Phase      Run PodFactoryPostProcessors        β”‚
β”‚                               β”‚                             β”‚
β”‚ 4. Singleton Phase      Pre-instantiate singleton pods      β”‚
β”‚                               β”‚                             β”‚
β”‚ 5. Start Phase          Publish ContextRefreshedEvent       β”‚
β”‚                               β”‚                             β”‚
β”‚                      >>> CONTEXT RUNNING <<<                β”‚
β”‚                               β”‚                             β”‚
β”‚ 6. Shutdown Phase       Run @PreDestroy & DisposablePods    β”‚
β”‚                               β”‚                             β”‚
β”‚ 7. Closed Phase         Publish ContextClosedEvent          β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

πŸ“¦ Exports Categorization

πŸ›οΈ Context Implementations

πŸ“’ Event-Driven Messaging

πŸ”„ Lifecycle Processors

  • Lifecycle β€” common interface defining methods for start/stop lifecycle control.
  • LifecycleProcessor β€” strategy interface for processing lifecycle beans within the context.

πŸ” Type Filtering


🎯 Usage Example: Bootstrapping Context & Event Dispatch

import 'package:jetleaf_core/context.dart';
import 'package:jetleaf_core/pod.dart';
import 'package:jetleaf_core/lang.dart';

// Custom domain event
class OrderPlacedEvent extends ApplicationEvent {
  final String orderId;
  OrderPlacedEvent(super.source, this.orderId);
}

void main() async {
  // 1. Create context
  final context = AnnotationConfigApplicationContext();

  // 2. Register event listener
  context.addApplicationListener<OrderPlacedEvent>((event) {
    print('Event received: Order #${event.orderId} processed.');
  });

  // 3. Initialize and refresh context
  await context.refresh();

  // 4. Publish custom event over the bus
  context.publishEvent(OrderPlacedEvent(context, 'ORD-8821'));

  // 5. Cleanly shut down context
  await context.close();
}

Classes

AbstractApplicationContext
The base implementation of a configurable Jetleaf Application Context.
AnnotationConfigApplicationContext
ApplicationContext implementation that supports annotation-based configuration.
AnnotationConfigRegistry
Annotation-Based Configuration Registry
AnnotationTypeFilter
A TypeFilter that matches classes based on the presence of specific annotations.
ApplicationAnnotatedLifecycleProcessor
Processor for application lifecycle annotations that discovers and invokes methods annotated with @OnApplicationStopping and @OnApplicationStopped.
ApplicationContext
The central interface for a Jetleaf application context.
ApplicationContextEvent
A base class for all events that are published within the context of an ApplicationContext.
ApplicationContextInitializer<T extends ConfigurableApplicationContext>
Strategy interface for initializing an ApplicationContext before it is refreshed.
ApplicationConversionService
A Jetleaf-managed, application-wide conversion service responsible for managing and coordinating all registered type converters.
ApplicationEnvironment
A concrete environment for standard Jetleaf applications.
ApplicationEvent
A base class for application-specific events within the Jetleaf framework.
ApplicationEventBus
Defines the contract for an event multicaster that manages the registration, removal, and dispatching of ApplicationEvents to ApplicationListeners.
ApplicationEventListener<E extends ApplicationEvent>
A listener for a specific type of ApplicationEvent.
ApplicationEventMethodAdapter
An adapter class in Jetleaf that bridges ApplicationEvents with listener methods.
ApplicationModule
An interface in Jetleaf that defines a configurable application module.
AssignableTypeFilter
A TypeFilter that matches classes assignable to a specific target type.
CompletedInitializationEvent
Event published when the ApplicationContext has completed its initialization phase.
ConfigurableApplicationContext
A specialized ApplicationContext that allows for full configuration and lifecycle management.
ContextClosedEvent
Event published when an ApplicationContext is closed.
ContextFailedEvent
Event published when the ApplicationContext fails to start or refresh.
ContextReadyEvent
Event published when the ApplicationContext is ready.
ContextRestartedEvent
Event published when the ApplicationContext is restarted.
ContextSetupEvent
Event published when the ApplicationContext is refreshed or initialized.
ContextStartedEvent
Event published when the ApplicationContext is started or restarted.
ContextStoppedEvent
Event published when the ApplicationContext is explicitly stopped.
ConversionServiceConfigurer
A Jetleaf extension interface for programmatically configuring type conversion within the application’s ConversionService.
EventObject
A base class for all framework-level events.
ExitCodeEvent
An ApplicationEvent that signals the application should exit with a specific exit code.
ExitCodeExceptionHandler
A strategy interface for mapping a specific Exception to a process exit code.
ExitCodeGenerator
Strategy interface for determining the exit code returned from a Jetleaf application or a process.
ExitCodeGenerators
A container and manager for multiple ExitCodeGenerator instances.
GenericApplicationContext
Generic ApplicationContext implementation that holds a single internal DefaultListablePodFactory instance and does not assume a specific pod definition format.
ImportClass
🫘 Represents a logical import entry with qualification and enablement metadata.
ImportSelector
🫘 A strategy interface for selecting which imports should be applied.
KeepAlive
A lifecycle-aware component that keeps the Dart VM alive as long as the ApplicationContext is running.
Lifecycle
A common interface defining methods for start/stop lifecycle control.
LifecycleProcessor
Defines a contract for components that participate in the application lifecycle.
Phased
Interface for objects that may participate in a phased process such as lifecycle management.
PodFactoryCustomizer<T extends ConfigurablePodFactory>
A lifecycle hook interface for customizing the PodFactory before it is fully initialized or configured within the Jetleaf framework.
PodFactoryPostProcessor
Factory hook that allows for custom modification of an application context's pod definitions, adapting the pod property values of the context's underlying pod factory.
PodPostProcessorManager
Manager for coordinating pod factory post-processors and pod-aware processors with proper ordering and lifecycle management.
PodRegistrar
A contract in Jetleaf for components that can register pods into the application’s dependency container.
PodRegistry
A contract in Jetleaf that provides methods for managing pods in the container.
PodSpec<T>
A concrete implementation of the `Spec` API in Jetleaf.
PodSpecContext
An implementation of `SpecContext` in Jetleaf that resolves dependencies during pod creation and supplier evaluation.
RegexPatternTypeFilter
A TypeFilter that matches classes based on regular expression patterns against class names.
SimpleApplicationEventBus
A straightforward implementation of ApplicationEventBus that manages application event listeners.
SmartLifecycle
An extension of the Lifecycle interface for those objects that require to be started upon ApplicationContext refresh and/or shutdown in a particular order.
Spec<T>
A Jetleaf definition describing how a pod should be instantiated, configured, and managed inside the container.
SpecContext
A context object in Jetleaf provided to suppliers and pod definitions for resolving dependencies at runtime.
TypeFilter
Abstract base class for type filtering strategies used in component scanning.

Enums

ApplicationType
Enumeration of types of applications that can be run in a Jetleaf environment.