core library
π± Jetleaf Core Subsystem
This library provides the fundamental application runtime kernel for Jetleaf, encapsulating:
- Application Context Abstractions: Lifecycle-aware execution environments.
- Application Availability & Health: Standardized
LivenessStateandReadinessStateprobing. - Conditional Infrastructure: Fine-grained evaluation of
@Conditionalpredicates. - Failure Diagnostics: Automated analysis and human-readable reporting of startup failures.
- Ordering & Precedence: Annotation-aware comparator contracts.
π¦ Availability State Machine
Jetleaf models application availability using two distinct lifecycle dimensions:
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Application Availability β
ββββββββββββββββββββββββββββββββ¬βββββββββββββββββββββββββββββββ€
β LivenessState β ReadinessState β
ββββββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββ€
β β’ CORRECT β β’ ACCEPTING_TRAFFIC β
β (Internal state is valid) β (Ready to serve requests) β
β β β
β β’ BROKEN β β’ REFUSING_TRAFFIC β
β (Fatal error, must restart)β (Warmup, draining, busy) β
ββββββββββββββββββββββββββββββββ΄βββββββββββββββββββββββββββββββ
π¦ Exports Categorization
π¦ Availability & Health Probing
- ApplicationAvailability β interface for querying active liveness and readiness states.
AvailabilityChangeEventβ published when application availability changes.- LivenessState, ReadinessState β standard availability status enums.
π Conditional Component Registration
- Condition β functional contract determining whether a component definition should register.
- ConditionEvaluator β evaluates conditions against active environment properties and container state.
Conditionsβ built-in condition strategies (e.g., conditional on property, profile, or pod presence).
π©Ί Diagnostics & Failure Analysis
- ExceptionDiagnoser β analyzes raw exceptions and produces structured ApplicationDiagnostics.
- ExceptionReporter β renders diagnostic analysis to logs, consoles, or monitoring sinks.
- LoggableExceptionDiagnosisReporter β formatted diagnostic output engine.
π·οΈ Scopes & Order
- ScopeMetadataResolver β resolves lifecycle scopes from class annotations.
- AnnotationAwareOrderComparator β sorts pods and interceptors honoring
@Ordersemantics.
π― Usage Example: Probing Availability & Handling Diagnostics
import 'package:jetleaf_core/core.dart';
void main() async {
final context = AnnotationConfigApplicationContext();
await context.refresh();
// Query application availability
final availability = context.getPod<ApplicationAvailability>();
if (availability != null) {
print('Liveness: ${availability.getLivenessState()}');
print('Readiness: ${availability.getReadinessState()}');
// Change availability state (e.g. during maintenance or warmup)
AvailabilityChangeEvent.publish(
context,
ReadinessState.REFUSING_TRAFFIC,
);
}
await context.close();
}
Classes
- AbstractApplicationContext
- The base implementation of a configurable Jetleaf Application Context.
-
AbstractExceptionDiagnoser<
E extends Exception> -
Base class for creating typed exception diagnosers that target a
specific exception type
E. - AbstractMessageSource
- Base implementation of MessageSource providing common functionality.
- AbstractMethodDispatcher
- A foundational implementation of MethodInterceptorDispatcher and MethodInterceptor providing a unified interception pipeline for Jetleaf's runtime and AOP subsystems.
- AfterInvocationInterceptor
- Defines an interceptor that executes after method completion, regardless of whether the invocation succeeded or failed.
- AfterReturningInterceptor
- An interceptor that executes after a method successfully returns a value, without throwing an exception.
- AfterThrowingInterceptor
- An interceptor triggered when a target method throws an exception.
- AnnotatedScopeMetadataResolver
-
A Jetleaf-provided implementation of ScopeMetadataResolver that
determines scope metadata based on the presence of the
@Scopeannotation. - AnnotationAwareOrderComparator
-
A Jetleaf-provided OrderComparator implementation that determines ordering
based on the presence of the
@Orderannotation or the Ordered interface. - AnnotationConfigApplicationContext
- ApplicationContext implementation that supports annotation-based configuration.
- AnnotationConfigRegistry
- Annotation-Based Configuration Registry
-
AnnotationFormatterFactory<
A extends ReflectableAnnotation, T> - A contextual SPI (Service Provider Interface) factory responsible for dynamically generating tailored FormatPrinter and FormatParser instances based on declarative metadata ReflectableAnnotations.
- 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
@OnApplicationStoppingand@OnApplicationStopped. - ApplicationAvailability
- Defines the contract for accessing and tracking an application's availability information, including both its liveness and readiness states.
- ApplicationAvailabilityAutoConfiguration
- Provides the default auto-configuration for managing and tracking application availability statesβincluding both liveness and readiness.
- ApplicationContext
- The central interface for a Jetleaf application context.
- ApplicationContextAware
- π« Interface for components that need access to the ApplicationContext.
- 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.
- ApplicationDiagnostics
- High-level diagnostics orchestrator combining both:
- 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 toApplicationListeners. - ApplicationEventBusAware
- π« Interface for components that need access to the ApplicationEventBus.
-
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.
- AroundMethodInterceptor
- A comprehensive interceptor that wraps the entire method invocation process, allowing developers to control when and how the target method executes.
- AssignableTypeFilter
- A TypeFilter that matches classes assignable to a specific target type.
- AutoConfiguration
- Declares a class as a source of automatic configuration.
- Autowired
- Autowired annotation for dependency injection
- AutowiredIgnore
- An annotation used to mark a field as ignored by the dependency injection container.
-
AvailabilityEvent<
Available extends AvailabilityState> - Represents an application-level event that conveys a change or report regarding an application's availability state.
- AvailabilityState
- A marker interface representing any application availability state.
- Cleanup
- Marks a method to be invoked after a pod is destroyed.
- CompletedInitializationEvent
- Event published when the ApplicationContext has completed its initialization phase.
- Component
- Component annotation for generic Jetleaf components
- ComponentScan
- Annotation for Jetleaf component scanning.
- ComponentScanFilter
- Represents a filter definition for component scanning.
- Condition
- The base interface for all Jetleaf condition evaluators.
- Conditional
- An annotation that conditionally enables or disables Jetleaf-managed constructs such as Component, Pod, or configuration classes based on one or more declarative Condition evaluators.
- ConditionalContext
- Represents the conditional evaluation context in Jetleaf applications.
- ConditionalOnAsset
- An annotation that conditionally activates a Component, Pod, or configuration class based on the presence of a specific asset in the application's resources.
- ConditionalOnClass
- An annotation that conditionally activates a Component, Pod, or configuration class only if specific classes are present in the Dart runtime or compilation environment.
- ConditionalOnDart
- An annotation that conditionally activates a Component, Pod, or configuration class based on the current Dart SDK version.
- ConditionalOnExpression
- An annotation that conditionally activates a Component, Pod, or configuration class based on the evaluation of a custom expression.
- ConditionalOnMissingClass
- An annotation that conditionally activates a Component, Pod, or configuration class only if certain classes are absent from the Dart runtime or compilation environment.
- ConditionalOnMissingPod
- An annotation that activates a component only when specific pods are absent from the ConditionalContext.
- ConditionalOnPod
- An annotation that conditionally activates a Component, Pod, or configuration class based on the presence of other pods within the current ConditionalContext.
- ConditionalOnProfile
- An annotation that conditionally activates a Component, Pod, or configuration class based on the currently active profiles in the ConditionalContext.
- ConditionalOnProperty
- An annotation that conditionally enables a Component, Pod, or configuration class based on the value(s) of one or more properties.
- ConditionEvaluator
-
The
ConditionEvaluatorin Jetleaf is responsible for evaluating conditional annotations (e.g., Conditional, ConditionalOnClass, ConditionalOnPod) and determining whether a given source (class, method, or configuration) should be included in the Jetleaf application context. - ConfigurableApplicationContext
- A specialized ApplicationContext that allows for full configuration and lifecycle management.
- ConfigurableMessageSource
- Main implementation of MessageSource that supports loading messages from multiple resources and formats.
- Configuration
- Configuration annotation for configuration classes
- ConfigurationProperty
- Annotation used to bind externalized configuration properties from the Environment into a Dart object.
- 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.
- ConversionServiceAware
- π« Interface for components that need access to a ConversionService.
- ConversionServiceConfigurer
- A Jetleaf extension interface for programmatically configuring type conversion within the applicationβs ConversionService.
- DateTimeFormat
- A declarative metadata annotation instructing type conversion pipelines, object-document mappers (ODMs), and presentation layer data binders on how to serialize, deserialize, parse, and print chronological properties.
- DefaultMethodInterceptor
- Default implementation of MethodInterceptorRegistry and related intercept processing.
- DependsOn
- A Jetleaf annotation that declares explicit dependencies between pods.
- Description
- Provides a human-readable description of a class or method.
- DurationFormat
- A declarative aspect-oriented metadata annotation instructing structural type conversion registries, data binders, and serialization encoders on how to process, format, and reconstruct Duration domain model properties.
- EntryApplicationAware
- π Interface for components that need access to the entry application class.
- EnvironmentAware
- π« Interface for components that can be configured with an Environment.
- EventListener
- Annotation to mark a method that should run when the application is listening to a specific type of ApplicationEvent.
- EventObject
- A base class for all framework-level events.
-
EventType<
T extends ApplicationEvent> - π« Represents a typed application event associated with a specific package.
- ExceptionDiagnoser
- Defines the contract for components capable of analyzing exceptions and producing structured diagnostic information.
- ExceptionDiagnosis
- Represents a structured diagnostic report for an exception, providing human-readable context, optional recommended actions, and the originating exception itself.
- ExceptionDiagnosisReporter
- Defines the contract for components responsible for handling and reporting structured exception diagnoses.
- ExceptionReporter
- Provides an abstraction for reporting, logging, or forwarding exceptions that occur within the application.
- 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.
-
FormatParser<
T> - An abstraction responsible for parsing a localized text string and reconstructing a strongly typed domain object or structural primitive.
-
FormatPrinter<
T> - An abstraction responsible for converting a strongly typed domain object or structural primitive into a localized, human-readable text string representation.
-
Formatter<
T> - A unified symmetric interface combining both FormatPrinter and FormatParser contracts to manage bidirectional type-to-string lifecycle mappings.
- FormatterRegistrar
- An orchestration interface wrapper allowing independent system modules, plugins, or domain packages to isolate and declare their unique parsing and formatting infrastructure configurations cleanly.
- FormatterRegistry
- A specialized structural registry configuration management subsystem extending ConverterRegistry to coordinate, cache, and resolve bidirectional localization formatting abstractions.
- GenericApplicationContext
- Generic ApplicationContext implementation that holds a single internal DefaultListablePodFactory instance and does not assume a specific pod definition format.
- Import
-
The
Importannotation in Jetleaf is used to import other configuration classes. - ImportClass
- π« Represents a logical import entry with qualification and enablement metadata.
- ImportSelector
- π« A strategy interface for selecting which imports should be applied.
- Interceptable
- Provides runtime interception support for method invocations within Jetleaf-managed components.
- InterceptorDependencyCycle
- A DependencyCycle implementation that represents a circular dependency between method interceptors in the interceptor chain.
- KeepAlive
- A lifecycle-aware component that keeps the Dart VM alive as long as the ApplicationContext is running.
-
KeyValueOf<
K, V> - KeyValueOf Annotation
- Lazy
- Indicates that a pod should be lazily initialized.
- Lifecycle
- A common interface defining methods for start/stop lifecycle control.
- LifecycleProcessor
- Defines a contract for components that participate in the application lifecycle.
- LoggableExceptionDiagnosisReporter
- An implementation of ExceptionDiagnosisReporter that outputs structured exception diagnosis information using the Jetleaf logging system.
- MessageSource
- Interface for resolving messages, with support for parameterization and internationalization.
- MessageSourceAware
- π« Interface for components that need access to a MessageSource.
- MessageSourceLoader
- Interface for loading messages from different resource formats.
- MethodBeforeInterceptor
- Defines an interceptor that executes logic before the target method invocation begins.
- MethodInterceptor
- Defines the core interception contract for Jetleafβs AOP (Aspect-Oriented Programming) framework, allowing runtime interception and augmentation of method invocations.
- MethodInterceptorConfigurer
- Strategy interface for configuring method interceptors in Jetleaf intercept.
- MethodInterceptorDispatcher
- Defines an advanced interception dispatcher that coordinates multiple method interceptors.
- MethodInterceptorRegistry
- Central registry for managing method-level interceptors and their dispatching.
-
MethodInvocation<
T> - Represents a reflective method invocation within the interception pipeline.
- Named
- Explicitly specifies a name for a Pod (Dependency Injection component) that overrides all other naming mechanisms in the Jetleaf framework.
- NumberFormat
- A declarative, aspect-oriented metadata annotation instructing structural type conversion registries, data binders, and serialization encoders on how to format, print, and parse primitive numerical types and custom numeric wrapper structures.
- OnApplicationFailed
- Annotation to mark a method that should run when the application fails to start or refresh.
- OnApplicationReady
- Annotation to mark a method that should run when the application is fully ready to serve requests.
- OnApplicationStarted
- Annotation to mark a method that should run when the application has started, meaning the context is refreshed but the app is not yet fully ready.
- OnApplicationStarting
- Annotation to mark a method that should run when the application is starting, before the context refresh occurs.
- OnApplicationStopped
- Annotation to mark a method that should run when the application has fully stopped.
- OnApplicationStopping
- Annotation to mark a method that should run when the application is stopping.
- OnAssetCondition
- A Condition implementation that determines whether an annotated component, configuration, or pod should be activated based on the presence of a specific asset within the application's resource path.
- OnClassCondition
- A Condition implementation that evaluates the presence or absence of classes in the current runtime to determine if a component, pod, or configuration should be activated.
- OnContextLoaded
- Annotation to mark a method that should run when the application context has been loaded, but before it is fully refreshed.
- OnContextPrepared
- Annotation to mark a method that should run when the application context has been prepared.
- OnDartCondition
- A Condition implementation that evaluates the current Dart SDK version to determine whether an annotated component, configuration, or pod should be activated.
- OnEnvironmentPrepared
- Annotation to mark a method that should run when the application environment has been prepared, but before the context is loaded.
- OnExpressionCondition
- A Condition implementation that dynamically evaluates an expression to determine whether a component, configuration, or pod should be activated.
- OnPodCondition
- A Condition implementation that evaluates the presence or absence of pods in the current ConditionalContext to determine whether a component, configuration, or definition should be activated.
- OnProfileCondition
- A Condition implementation that evaluates the application's currently active profiles to determine whether a component, configuration, or pod should be activated.
- OnPropertyCondition
- A Condition implementation that evaluates whether a component or pod should be activated based on the presence and value of properties in the current ConditionalContext.environment.
- Order
- Specifies the order of precedence for a class when processed by the framework or runtime system.
- Phased
- Interface for objects that may participate in a phased process such as lifecycle management.
- Pod
- Marks a method as a pod provider, enabling it to participate in the dependency injection (DI) lifecycle of the application.
- PodFactoryAware
- π« Interface for components that need access to the PodFactory.
-
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.
- PodNameAware
- π« Interface for components that need to know their assigned pod name.
- 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. - PostConstruct
- Marks a method to be invoked after a pod has been fully constructed and its dependencies injected, but before it is made available for use in the context.
- PreConstruct
- Marks a method to be invoked before a pod has been fully constructed and its dependencies injected, but before it is made available for use in the context.
- PreDestroy
- Marks a method to be invoked before a pod is destroyed.
- Primary
- Primary annotation for marking a primary pod
- Profile
- Profile annotation for profile-specific pods
- Qualifier
- A Jetleaf annotation used to disambiguate injection targets when multiple candidate pods of the same type exist.
- RegexPatternTypeFilter
- A TypeFilter that matches classes based on regular expression patterns against class names.
- Repository
- Marks a class as a Repository Component for data access and persistence.
- RequiredAll
- An annotation used for dependency injection that automatically injects all eligible fields into a class.
-
Resource<
Key, Value> - A generic abstraction for Jetleaf-compatible resource.
- Role
- Declares the design role of a class or method within a Jetleaf application.
- RunAfter
- A reflective annotation that declares that the annotated interceptor, filter, or handler should execute after one or more specified targets within the Jetleaf request processing pipeline.
- RunBefore
- A reflective annotation that declares that the annotated interceptor, filter, or handler should execute before one or more specified targets within the Jetleaf request processing pipeline.
- Scope
- Annotation that specifies the scope of a pod within the Jetleaf container.
- ScopeMetadataResolver
- Strategy interface for resolving scope metadata for a given class in Jetleaf.
- Service
- Service annotation for service layer components
- SimpleApplicationEventBus
- A straightforward implementation of ApplicationEventBus that manages application event listeners.
-
SimpleMethodInvocation<
T> - Represents a reflective invocation of a method on a target object, forming the core join point within Jetleafβs interception system.
- 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.
- StartupEvent
- An applicationβlevel event signaling that the Jetleaf application has completed its startup sequence.
-
TargetType<
T> - TargetType Annotation
- TypeFilter
- Abstract base class for type filtering strategies used in component scanning.
- Value
- Value annotation for property injection
- WhenConditional
- The base class for all annotations that are eligible for conditional evaluation in the Jetleaf framework.
Enums
- ApplicationType
- Enumeration of types of applications that can be run in a Jetleaf environment.
- DateTimeFormatIso
- Common standard ISO-8601 date-time format patterns supported natively by the DateTimeFormat annotation framework.
- DurationFormatStyle
- Defines the structural strategies available for formatting and parsing Duration string representations.
- DurationFormatUnit
- A comprehensive structural enumeration mapping out the supported execution units for duration parsing, formatting, and mathematical conversion layers.
- FilterType
- Enumeration of supported filter types for component scanning.
- LivenessState
- Represents the liveness state of an application.
- NumberFormatStyle
- Defines the structural strategies available for formatting and parsing numerical representations, aligning with localized internationalization standards and enterprise metadata-driven architectures.
- ReadinessState
- Represents the readiness state of an application.
Typedefs
-
AsyncMethodInvocator<
T> = Future< T> Function() - Represents a deferred executable function that performs a method invocation.
Exceptions / Errors
- MessageSourceException
- An exception that occurs when resolving messages from a MessageSource.