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 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

🎨 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 ApplicationShutdownHandlerHook is 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.
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.