main library Jetleaf
π Jetleaf Application Bootstrap, Context & Runner Kernel
This library provides the core bootstrap mechanisms, lifecycle runners, banner rendering, exception handling, and shutdown orchestration for Jetleaf applications:
- Application Bootstrap: JetleafApplication,
@JetleafApplicationStarter. - Execution Runners: CommandLineRunner, ApplicationRunner.
- Bootstrap Context: BootstrapContext, DefaultBootstrapContext,
BootstrapContextFactory. - Exception Handling: ApplicationExceptionHandler, ExceptionReporterManager.
- Shutdown Handling: ApplicationShutdownHandler, ApplicationShutdownHandlerHook.
- Banner Customization: Banner, DefaultBanner, BannerMode.
π Application Bootstrap Lifecycle
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Jetleaf Bootstrap Pipeline β
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β 1. Environment Preparation Property sources, profiles, and arguments β
β β β
β 2. Banner Output Console ASCII banner & version stamp β
β β β
β 3. Bootstrap Context Setup Pre-instantiation and initializers β
β β β
β 4. Application Context Init AnnotationConfigApplicationContext setup β
β β β
β 5. AOT Registry Loading Function-pointer tables registered β
β β β
β 6. Singleton Instantiation All eager singleton pods materialized β
β β β
β 7. Runners Execution CommandLineRunner / ApplicationRunner β
β β β
β >>> APPLICATION RUNNING <<< β
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
π¦ Exports Categorization
π Bootstrap & Starters
- JetleafApplication β primary bootstrap driver managing configuration, context, and shutdown.
@JetleafApplicationStarterβ root annotation marking the entry-point application class.- BootstrapContext β lightweight early context used during environment and logging setup.
π Runners & Entry Points
- CommandLineRunner β receives raw
List<String> argsafter container initialization. - ApplicationRunner β receives parsed ApplicationArguments with option flags.
π¨ Banner & Diagnostics
- Banner β contract for rendering the startup banner.
- DefaultBanner β standard Jetleaf ASCII banner with active version information.
- BannerMode β controls whether banner output is displayed or muted (
CONSOLE,OFF).
π― Usage Example: Customizing Runners and Shutdown Hooks
import 'package:jetleaf/main.dart';
@JetleafApplicationStarter()
class CliUtility implements ApplicationRunner {
@override
int getOrder() => 1;
@override
void run(ApplicationArguments args) {
if (args.containsOption('dry-run')) {
print('Running utility in dry-run mode.');
} else {
print('Executing batch changes...');
}
}
}
void main(List<String> args) async {
final app = JetleafApplication(CliUtility);
app.setBannerMode(BannerMode.CONSOLE);
app.setApplicationType(ApplicationType.NONE);
await app.create(args, null);
}
Classes
- ApplicationContextFactory
- A factory for creating Jetleaf application context and environment instances.
- ApplicationExceptionHandler
- A global, thread-safe handler for uncaught exceptions in Jetleaf applications.
- ApplicationHook
-
A hook interface for integrating with the lifecycle of a
Application. - ApplicationImportSelector
- π« Default ImportSelector implementation for Jetleaf.
- ApplicationInfoPropertySource
-
A MapPropertySource that exposes Jetleaf application metadata such as
version and process ID (
pid) to the environment system. - ApplicationLoggingListener
- Jetleaf's application-level LoggingListener implementation.
- ApplicationRunListener
- A listener for Jetleaf application lifecycle events during startup.
- ApplicationRunListeners
- Coordinates the execution of multiple ApplicationRunListener instances during the Jetleaf application lifecycle.
- ApplicationRunner
- A runner that receives parsed ApplicationArguments.
- ApplicationShutdownHandler
- Represents a registry of shutdown actions (tasks) that are executed when the application is in the process of shutting down.
- ApplicationShutdownHandlerHook
-
The
ApplicationShutdownHandlerHookis responsible for managing the graceful shutdown of a Jetleaf application, ensuring that all registered ConfigurableApplicationContext instances and shutdown handlers are executed in a predictable and safe order when the Dart process exits or receives a termination signal. - ApplicationTypeFilter
- A Jetleaf-specific TypeFilter implementation that determines whether a given class qualifies as an auto-configuration candidate.
- Banner
- A contract for printing a custom application banner during Jetleaf startup.
- BootstrapContext
- A context used during Jetleaf's bootstrapping phase for accessing and managing lazily-created instances by their reflected Class types.
- BootstrapContextClosedEvent
- An ApplicationEvent published when the BootstrapContext is closed, typically just before or during the early phase of starting a full ConfigurableApplicationContext.
-
BootstrapInstanceSupplier<
T> - A supplier that can create instances based on a BootstrapContext, with optional scoping support.
- BootstrapRegistry
- A registry interface for bootstrapping components during early phases of application startup.
- BootstrapRegistryInitializer
- Strategy interface used to programmatically register bootstrap instances into a BootstrapRegistry before the application context is refreshed.
- CommandLineRunner
- A runner that receives raw command-line arguments.
- ConfigurableBootstrapContext
- A configurable bootstrap context that acts as both a BootstrapRegistry and a BootstrapContext.
- DartConfigParser
- DartConfigParser - improved to accept any constructor/static factory that produces a JetleafProperty (heuristic-based), not only JetleafProperty.custom.
- DartEnvironmentParser
- Environment parser for .dart configuration files.
- DefaultApplicationContextFactory
- The default implementation of ApplicationContextFactory in Jetleaf.
- DefaultApplicationHook
- Default implementation of ApplicationHook in Jetleaf.
- DefaultBanner
- A fallback Banner implementation that attempts to load a custom banner from the application environment, but defaults to another banner if none is found.
- DefaultBootstrapContext
- The default implementation of ConfigurableBootstrapContext in Jetleaf.
- DefaultPropertiesPropertySource
- A specialized MapPropertySource representing a default set of properties that can be added to or merged with an existing Environment.
- EnableAutoConfiguration
- Core framework annotations for Jetleaf
- EnvEnvironmentParser
- Environment parser for .env configuration files.
- EnvironmentListener
- A listener that prepares and configures the application environment.
- EnvironmentParser
- Base interface for parsing configuration files into environment data.
- EnvironmentSource
- Represents a single raw source of environment configuration.
- ExceptionHandler
- Responsible for handling exceptions thrown during the application lifecycle (startup or runtime) in Jetleaf applications.
- ExceptionReporterManager
- Discovers, instantiates, and manages all available implementations of ExceptionReporter within the application's classpath.
- JetleafApplication
- Main entry point for Jetleaf framework applications.
- JetleafApplicationStarter
- A meta-annotation in Jetleaf used to bootstrap and configure the root application class.
- JetleafBanner
- A Banner implementation that displays a simple text-based banner with the Jetleaf logo and version information.
- JetleafConfigParser
- Parser for Jetleaf configuration files with strict validation.
- JetleafLoggingProperty
- Defines all Jetleaf framework logging-related configuration keys.
- JetleafPropertySourceOrderRule
- A Jetleafβspecific ordering rule that sorts property sources according to the official environmental precedence rules.
- JetleafVersion
- A utility class for retrieving the current version of the Jetleaf framework.
- JsonEnvironmentParser
- Environment parser for JSON configuration files.
- LifecycleRunListener
- A reflection-driven Jetleaf ApplicationRunListener that automatically discovers and invokes lifecycle-annotated methods across all loaded types.
- ParsedEnvironmentSource
- Represents the fully parsed result of an environment configuration source.
- PropertiesEnvironmentParser
- Environment parser for .properties configuration files.
- PropertySourceOrderingPodFactoryPostProcessor
- π Post-processor that reorders property sources for optimal resolution.
- Runner
- Base contract for application runners in Jetleaf.
- StartupLogger
- Logs application startup events in a structured and user-friendly format.
- YamlEnvironmentParser
- Environment parser for YAML configuration files.
Enums
- BannerMode
- An enumeration of possible values for configuring the Banner.
Extensions
-
ThrowingConsumerX
on ThrowingConsumer<
T> - Extension methods for ThrowingConsumer providing safe execution.
Typedefs
- AotPodRegistrar = JetleafAotRegistrar
- Backwards compatibility alias for JetleafAotRegistrar.
-
JetleafAotRegistrar
= FutureOr<
void> Function([DefaultListablePodFactory? factory]) - Function signature for compile-time generated AOT registration.
-
ThrowingConsumer<
T> = FutureOr< void> Function(T value) - A consumer function that can throw exceptions.
Exceptions / Errors
- JetleafException
- A RuntimeException thrown when the application context is considered "abandoned" during startup or shutdown.