pod library Jetleaf
π« Jetleaf Pod Subsystem & Dependency Injection Container
This library provides the core dependency-injection (DI) and Inversion of Control (IoC) engine used throughout Jetleaf, built around Pods β lightweight, configurable, lifecycle-managed application components.
It exposes the complete pod lifecycle pipeline, container factory abstractions, scope boundaries, definition registries, aliasing mechanisms, name generation strategies, and startup hooks.
π Pod Lifecycle Sequence
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Pod Lifecycle Pipeline β
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β 1. Registration [PodDefinitionRegistry.registerDefinition] β
β β β
β 2. Instantiation [InstanceSupplier] / AOT Constructor Dispatch β
β β β
β 3. Dependency Wiring Constructor / Field / Setter Injection β
β β β
β 4. Aware Callbacks [ApplicationContextAware], [EnvironmentAware] β
β β β
β 5. Pre-Initialization [PodPostProcessor.postProcessBeforeInitialization]β
β β β
β 6. Lifecycle Ready [InitializingPod.onReady] / @PostConstruct β
β β β
β 7. Post-Initialization [PodPostProcessor.postProcessAfterInitialization] β
β β β
β >>> POD IS READY <<< β
β β β
β 8. Disposal [DisposablePod.onDestroy] / @PreDestroy β
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
π¦ Exports Categorization
π Core Container Factories
- PodFactory β the primary read-only interface for retrieving components from the container.
- ConfigurablePodFactory β configuration interface for scopes, converters, and customizers.
- ConfigurableListablePodFactory β combined interface for definition inspection and pre-instantiation.
- DefaultListablePodFactory β the standard, high-performance production IoC container.
π§± Pod Definitions & Registries
- PodDefinition β reflective blueprint describing creation, scope, and wiring rules for a pod.
- RootPodDefinition β standard concrete pod definition holder.
- PodDefinitionRegistry β interface for registering, querying, and managing definitions.
- SimplePodDefinitionRegistry β default in-memory registry implementation.
π·οΈ Alias & Name Management
- AliasRegistry β maintains symbolic aliases and indirect names for pods.
- SimpleAliasRegistry β default in-memory alias mapping registry.
- PodNameGenerator β strategy interface for naming unnamed component definitions.
- SimplePodNameGenerator β default decapitalized class name generator.
π Scopes & Post-Processors
- Scope β lifecycle scope boundary strategy (
singleton,prototype). PodPostProcessorβ allows custom modification of new pod instances before/after initialization.- PodFactoryPostProcessor β allows custom modification of the container's pod definitions.
- SmartInitializingSingleton β triggered after all singletons have been instantiated.
π― Usage Example: Programmatic Pod Definition & Injection
import 'package:jetleaf/pod.dart';
import 'package:jetleaf/lang.dart';
class DatabasePool {
final String url;
DatabasePool(this.url);
}
class UserRepository {
final DatabasePool pool;
UserRepository(this.pool);
}
Future<void> main() async {
final factory = DefaultListablePodFactory();
// 1. Register database pool singleton
await factory.registerSingleton(
'databasePool',
Class<DatabasePool>(),
object: ObjectHolder(DatabasePool('postgres://localhost:5432/main')),
);
// 2. Register repository with factory supplier
await factory.registerDefinition(
'userRepository',
RootPodDefinition(
type: Class<UserRepository>(),
instanceSupplier: (factory) async =>
UserRepository(await factory.get<DatabasePool>(Class<DatabasePool>())),
),
);
// 3. Pre-instantiate singletons and retrieve wired instance
await factory.preInstantiateSingletons();
final repo = await factory.getPod<UserRepository>('userRepository');
print('Connected to database: ${repo.pool.url}');
}
Classes
- AbstractAutowirePodFactory
- Abstract base class for pod factories that support autowiring capabilities.
- AbstractPodDefinition
- An abstract base class for pod definitions that extends PodDefinition.
- AbstractPodFactory
- Abstract base implementation of PodFactory that provides core functionality for pod creation, management, and lifecycle handling in the Jetleaf framework.
- AbstractPodProviderFactory
- Retrieves the PodProvider backing a pod.
- AliasRegistry
- An abstract interface for managing name aliases in a registry system.
- AliasRegistryAware
- Contract for objects that support alias registration.
- ApplicationStartup
- Instruments the application startup phase using StartupSteps.
- ApplicationStartupAware
- Defines a contract for components that are aware of and can interact with an ApplicationStartup strategy.
- ArgumentValue
- Holder for a constructor argument value, including its optional type and name metadata.
- ArgumentValueHolder
- Argument Value Holder
- AutowireCandidateDescriptor
- Describes whether a component is eligible for autowiring.
- AutowirePodFactory
- Extends PodFactory with automatic dependency injection capabilities.
- ConfigurableListablePodFactory
- The most comprehensive pod factory interface combining listing and configuration capabilities.
- ConfigurablePodFactory
- A comprehensive pod factory interface with configuration capabilities.
- ConstructorArgumentValues
- Holder for constructor argument values used when instantiating a pod.
- ConvertibleValue
- Abstraction for holding a raw value and its converted state.
- DefaultApplicationStartup
- A no-op implementation of ApplicationStartup that always returns a singleton DefaultStartupStep for any startup operation.
- DefaultListablePodFactory
- Default implementation of ConfigurableListablePodFactory that provides comprehensive pod management capabilities in the Jetleaf framework.
-
DefaultObjectProvider<
T> - Default implementation of ObjectProvider in Jetleaf.
- DefaultStartupStep
- A no-op implementation of StartupStep used by DefaultApplicationStartup.
- DefaultStartupStepTags
- A no-op, empty tag collection returned by DefaultStartupStep.
- DependencyCycle
- Represents a detected circular dependency within a dependency graph.
- DependencyDescriptor
- Describes a dependency required by a component or pod.
- DependencyDesign
- Describes a dependency required by a component or pod.
- DesignDescriptor
- Describes the design role configuration of a component.
- DisposablePod
- Interface to be implemented by pods that need to release resources or perform cleanup when being removed from the container or shut down.
- EmbeddedValueResolutionSupport
- A mixin-style infrastructure base support utility class designed to automate the mechanics of string value resolver capture and execution hooks.
- EmbeddedValueResolver
- An advanced structural string interpolation engine that orchestrates dynamic value extraction, property placeholder substitution, and expression evaluation within a component container framework.
- EmbeddedValueResolverAware
- An inversion-of-control (IoC) infrastructure contract indicating that a component or lifecycle instance requires access to an external StringValueResolver utility.
- ExecutableHolder
- Executable Holder
- ExecutableStrategy
- Executable Strategy
- FactoryAwareOrderSourceProvider
- An OrderSourceProvider implementation that is aware of the containerβs DefaultListablePodFactory.
- FactoryMethodDesign
- Describes a factory method used to create a pod (component).
- HierarchicalPodFactory
- Extends PodFactory with hierarchical capabilities for parent-child relationships.
- InitializingPod
- Interface to be implemented by pods that require initialization logic after their properties have been set by the container.
- LifecycleDesign
- Describes lifecycle behavior of a component, such as initialization and destruction methods.
- ListablePodDefinitionRegistry
- Interface for registries that provides additional functionality for listing and enumeration.
- ListablePodFactory
- Extends PodFactory with capabilities to list and query pods.
- Mergeable
- Interface for objects that can merge with other objects of the same type.
- MutablePropertyValues
- Mutable implementation of PropertyValues interface.
- NoOpDependencyCycle
- A no-op implementation of DependencyCycle.
- NullablePod
- A special marker pod instance that represents a nullable or absent pod value.
-
ObjectFactory<
T> -
A generic factory interface for producing instances of a given type
T. -
ObjectHolder<
T> - A generic container that holds an object along with optional metadata such as its package name and qualified name.
-
ObjectProvider<
T> - A flexible, functional-style provider interface for retrieving and interacting with pods or objects of a particular type.
- PodDefinition
- Defines the blueprint of a pod (component) in the dependency injection system.
- PodDefinitionRegistry
- Interface for registries that hold PodDefinition instances.
- PodDestructionProcessor
- Processor that provides hooks into the pod destruction and cleanup lifecycle.
-
PodExpression<
T> - Pod Expression Contract
- PodExpressionContext
- Context for evaluating expressions in a pod environment.
- PodExpressionResolver
- Strategy interface for resolving pod definition values and expressions.
- PodFactory
- The core factory interface for managing and retrieving pods (components) in Jetleaf.
- PodInitializationProcessor
- Processor that provides hooks into the pod initialization lifecycle phases.
- PodInstantiationProcessor
- Processor that provides hooks into the pod instantiation and property population lifecycle.
- PodNameGenerator
- Strategy interface for generating pod names for PodDefinitions.
- PodProcessor
- Abstract interface for processors that handle or manipulate pods in the Jetleaf framework.
-
PodProvider<
T> - Interface for objects that are themselves factories for other objects.
- PodScope
- Interface for pod scopes that manage object lifecycle and contextual storage.
- PodSmartInstantiationProcessor
- Advanced processor that provides sophisticated control over pod instantiation.
- PropertyValue
-
Represents a property with a
_nameand its associated_value. - PropertyValues
- Interface for accessing a collection of PropertyValue objects.
- RootPodDefinition
- A concrete implementation of AbstractPodDefinition that serves as the default pod definition in the system.
- ScopeDesign
- Describes the scope configuration of a component.
-
ScopedObjectFactory<
T> - An ObjectFactory implementation that retrieves objects from a specific PodScope.
- SimpleAliasRegistry
- A thread-safe implementation of AliasRegistry using LocalThread storage.
-
SimpleObjectFactory<
T> - Default implementation of the ObjectFactory interface that uses a creator function.
- SimplePodDefinitionRegistry
- A basic registry for managing pod definitions.
- SimplePodNameGenerator
- Default implementation of the PodNameGenerator interface.
- SingletonPodRegistry
- Interface for registries that hold singleton pod instances.
- SmartInitializingSingleton
- Callback interface triggered at the end of the singleton pre-instantiation phase.
- StandardStartupTracker
- Standard implementation of the {@macro startup} interface.
- StartupStep
- Step recording metrics about a particular phase or action happening during the ApplicationStartup.
- StartupStepTag
-
Attaches a static key/value
tagto this step. - StartupStepTags
- Returns the complete list of StartupStepTags associated with this step.
- StartupTracker
- Represents a startup lifecycle monitor for Jetleaf-based applications.
- StringValueResolver
- An architectural interface defining the contractual protocol for transforming, mapping, and expanding raw string expressions into fully resolved text values.
Enums
- AutowireMode
- Defines strategies for automatically wiring dependencies in a system.
- DependencyCheck
- Defines the type of dependency validation to be performed when initializing a component or system.
- DesignRole
- Defines the architectural role of a component within a system.
- ScopeType
- Defines the lifecycle scope of a component within a dependency injection container.
Typedefs
- CreatedPodHolder = (String, PodDefinition, Object)
- The holder for created pods
-
ObjectFactoryFunction<
T> = FutureOr< ObjectHolder< Function([List<T> >ArgumentValue> ? args]) -
A function that creates an instance of type
T. -
PodDefinitionHolder
= (String, PodDefinition, List<
String> ) - Type definition for a pod definition holder tuple.
- PodHolder = (Object, Class)
- A tuple representing a pod and its class.
-
PodInstanceSupplier<
T> = FutureOr< T> Function(PodFactory factory) - Direct compiled instance supplier function for AOT instantiation (zero reflection).
-
PodLifecycleInvoker<
T> = FutureOr< void> Function(T instance) - Direct compiled lifecycle invoker function for AOT @PostConstruct and @PreDestroy (zero reflection).
Exceptions / Errors
- CircularDependencyException
- Thrown when a circular dependency is detected within the framework's dependency graph, interceptor ordering, or initialization process.
- FatalPodException
- Base class for fatal pod-related exceptions that indicate unrecoverable errors.
- NoSuchPodDefinitionException
-
Exception thrown when a
PodFactoryis asked for a pod instance by name, and no definition for that pod name exists. - NoUniquePodDefinitionException
- Exception thrown when multiple pod definitions are found for a given type in the application context.
- PodCreationException
- Exception thrown when a pod cannot be created.
- PodCreationNotAllowedException
- Exception thrown when a pod creation is not allowed in the current context.
- PodCurrentlyInCreationException
- Exception thrown when a pod is currently in the process of being created.
- PodDefinitionOverrideException
- Exception thrown when a pod definition is overridden.
- PodDefinitionStoreException
- Exception thrown when a pod definition store error occurs.
- PodDefinitionValidationException
- Exception thrown when a pod definition is invalid during validation.
- PodException
- Base exception type for all pod-related errors in Jetleaf.
- PodIsAbstractException
- Exception thrown when attempting to instantiate a pod that is marked as abstract.
- PodIsNotAProviderException
- Exception thrown when a pod is expected to be a PodProvider but is not.
- PodNotOfRequiredTypeException
- Exception thrown when a pod retrieved from the context is not of the expected type.
- PodProviderNotInitializedException
- Exception thrown when attempting to use a PodProvider that hasn't been fully initialized.
- ScopeNotActiveException
- Exception thrown when a pod is requested from a scope that is not active.
- UnsatisfiedDependencyException
- Exception thrown when a dependency is not satisfied for a pod.