ApplicationContext class abstract

The central interface for a JetLeaf application context.

An ApplicationContext is the core container that provides:

  • Dependency Injection: Access to managed pods via ListablePodFactory and HierarchicalPodFactory
  • Environment Management: Configuration and profile handling via EnvironmentCapable
  • Internationalization: Message resolution and localization via MessageSource
  • Event System: Application-wide event publication through publishEvent
  • Lifecycle Management: Context state tracking and lifecycle operations

This interface serves as the primary entry point for configuring, bootstrapping, and interacting with a JetLeaf application at runtime.

Core Responsibilities:

  • Container Management: Hosts and manages the complete dependency injection container
  • Configuration Centralization: Provides unified access to application configuration
  • Lifecycle Coordination: Manages context lifecycle from startup to shutdown
  • Event Distribution: Facilitates loose coupling through event-driven architecture
  • Resource Access: Provides access to framework and application resources

Basic Usage Example:

void main() async {
  // Create and configure application context
  final context = MyApplicationContext();
  
  // Initialize the context (loads pods, processes configurations)
  await context.refresh();

  // Publish application startup event
  context.publishEvent(ApplicationStartedEvent(context));

  // Access context information
  print("Application '${context.getApplicationName()}' started at: ${context.getStartTime()}");
  print("Context ID: ${context.getId()}");
  
  // Use the context throughout application lifetime
  final userService = context.getPod<UserService>();
  await userService.initialize();
  
  // Properly close context on shutdown
  await context.close();
}

Context Hierarchy:

Application contexts can form parent-child relationships where child contexts inherit configuration and can delegate pod lookups to their parents. This enables:

  • Modular Applications: Separate contexts for different application modules
  • Testing Scenarios: Isolated test contexts with shared parent services
  • Multi-tenant Systems: Tenant-specific contexts with common infrastructure

Thread Safety:

Implementations should be thread-safe for concurrent access, particularly for read operations like pod retrieval and configuration access. Lifecycle operations (refresh, start, stop, close) should be properly synchronized.

See also:

Implemented types
Implementers

Constructors

ApplicationContext()

Properties

hashCode → int
The hash code for this object.
no setterinherited
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited

Methods

addPodProcessor(PodProcessor processor) → void
Registers a new pod-aware processor.
inherited
addSingletonCallback(String name, Class type, Consumer<Object> callback) → void
Add a callback to be executed when the singleton associated with name is initialized.
inherited
clearMetadataCache() → void
Clears the internal metadata cache.
inherited
clearSingletonCache() → void
Clears all cached singleton pods.
inherited
containsDefinition(String name) → bool
Returns true if this registry contains a pod with the given name.
inherited
containsLocalPod(String podName) → Future<bool>
Checks if a pod with the given name is registered locally in this factory.
inherited
containsPod(String podName) → Future<bool>
Checks if a pod with the given name is registered in the factory.
inherited
containsSingleton(String name) → bool
Returns true if this registry contains a pod with the given name.
inherited
containsType(Class type, [bool allowPodProviderInit = false]) → Future<bool>
Checks if the factory contains a pod of the specified type.
inherited
copyConfigurationFrom(ConfigurablePodFactory otherFactory) → void
Copies configuration from another factory.
inherited
destroyPod(String podName, Object podInstance) → Future<void>
Destroys a pod instance by name and instance.
inherited
destroyScopedPod(String podName) → void
Destroys all pods in the specified scope.
inherited
destroySingletons() → void
Destroys all singleton pods in the factory.
inherited
findAllAnnotationsOnPod<A>(String podName, Class<A> type) → Future<Set<A>>
Finds all annotations of the specified type on a pod.
inherited
findAnnotationOnPod<A>(String podName, Class<A> type) → Future<A?>
Finds a specific annotation on a pod.
inherited
get<T>(Class<T> type, [List<ArgumentValue>? args]) → Future<T>
Retrieves a pod instance by its type with optional arguments.
inherited
getAlias(String name) → String?
Retrieves the primary name associated with the given alias.
inherited
getAliases(String podName) → List<String>
Retrieves all alias names for the specified pod.
inherited
getAllowCircularReferences() → bool
Retrieves the current circular reference setting.
inherited
getAllowDefinitionOverriding() → bool
Retrieves the current definition overriding setting.
inherited
getAllowRawInjection() → bool
Retrieves the current raw injection despite wrapping setting.
inherited
getApplicationName() → String
Returns the name of this application.
getApplicationStartup() → ApplicationStartup
Defines a contract for components that are aware of and can interact with an ApplicationStartup strategy.
inherited
getConversionService() → ConversionService
Retrieves the currently assigned ConversionService.
inherited
getDefinition(String name) → PodDefinition
Retrieve the pod registered under name.
inherited
getDefinitionByClass(Class type) → PodDefinition
Returns the pod definition for the specified class type.
inherited
getDefinitionNames() → List<String>
Returns a list of all pod names currently registered.
inherited
getDisplayName() → String
Returns the display name of this application context.
getEnvironment() → Environment
🫘 Returns the Environment associated with the current context.
getId() → String
Returns a unique identifier for this application context.
getLifecycleProcessor() → LifecycleProcessor
🆕 Returns the LifecycleProcessor associated with the current context.
getMainApplicationClass() → Class<Object>
Returns the main application class.
getMergedPodDefinition(String podName) → RootPodDefinition
Retrieves the merged pod definition for the specified pod name.
inherited
getMessage(String code, {List<Object>? args, Locale? locale, String? defaultMessage}) → String
Retrieve a message for the given code.
inherited
getNamedObject(String podName, [List<ArgumentValue>? args]) → Future<Object>
Retrieves a pod as a generic Object by its name with optional arguments.
inherited
getNumberOfPodDefinitions() → int
Returns the total number of pods registered.
inherited
getObject(Class<Object> type, [List<ArgumentValue>? args]) → Future<Object>
Retrieves a pod as a generic Object by its type with optional arguments.
inherited
getPackageName() → String
Represents an abstraction for identifying the package that an object, resource, or service belongs to.
inherited
getParent() → ApplicationContext?
Returns the parent context, if any.
getParentFactory() → PodFactory?
Retrieves the parent factory in the hierarchy, if any.
inherited
getPod<T>(String podName, [List<ArgumentValue>? args, Class<T>? type]) → Future<T>
Retrieves a pod instance by its name with optional arguments.
inherited
getPodClass(String podName) → Future<Class>
Retrieves the Class object for the specified pod name.
inherited
getPodExpressionResolver() → PodExpressionResolver?
Retrieves the current expression resolver.
inherited
getPodFactory() → ConfigurableListablePodFactory
🫘 Returns the underlying ConfigurableListablePodFactory.
getPodNames(Class type, {bool includeNonSingletons = false, bool allowEagerInit = false}) → Future<List<String>>
Retrieves all pod names for pods of the specified type.
inherited
getPodNamesForAnnotation<A>(Class<A> type) → Future<List<String>>
Retrieves pod names for pods annotated with the specified annotation type.
inherited
getPodNamesIterator() → Iterator<String>
Returns an iterator over all pod names in the factory.
inherited
getPodProcessorCount() → int
Gets the number of registered pod-aware processors.
inherited
getPodProcessors() → List<PodProcessor>
Retrieves all registered pod-aware processors.
inherited
getPodsOf<T>(Class<T> type, {bool includeNonSingletons = false, bool allowEagerInit = false}) → Future<Map<String, T>>
Retrieves all pods of the specified type as a map of name to instance.
inherited
getPodsWithAnnotation<A>(Class<A> type) → Future<Map<String, Object>>
Retrieves pods with the specified annotation as a map of name to instance.
inherited
getProvider<T>(Class<T> type, {String? podName, bool allowEagerInit = false}) → Future<ObjectProvider<T>>
Retrieves a provider for a pod, allowing for lazy or eager initialization.
inherited
getRegisteredScope(String scopeName) → PodScope?
Retrieves a registered scope by name.
inherited
getRegisteredScopeNames() → List<String>
Retrieves all registered scope names.
inherited
getSingleton(String name, {bool allowEarlyReference = true, ObjectFactory<Object>? factory}) → Future<Object?>
Retrieve the pod registered under name.
inherited
getSingletonCount() → int
Returns the total number of pods registered.
inherited
getSingletonNames() → List<String>
Returns a list of all pod names currently registered.
inherited
getStartTime() → DateTime
Returns the startup time of this context as a DateTime.
getSupportingEnvironment() → AbstractEnvironment
Returns the Environment that supports this component or context.
isActive() → bool
Returns whether this application context is currently active.
isActuallyInCreation(String podName) → bool
Checks if a pod with the given name is currently being created.
inherited
isAlias(String name) → bool
Checks whether the given name is registered as an alias.
inherited
isAutowireCandidate(String podName, DependencyDescriptor descriptor) → bool
Checks if a pod is a candidate for autowiring for the given dependency.
inherited
isCachePodMetadata() → bool
Checks if pod metadata caching is enabled.
inherited
isClosed() → bool
Returns whether this application context has been closed.
isNameInUse(String name) → Future<bool>
Returns true if name is currently in use in this registry.
inherited
isPodProvider(String podName, [RootPodDefinition? rpd]) → Future<bool>
Checks if the specified pod name refers to a pod provider.
inherited
isPrototype(String podName) → Future<bool>
Checks if the specified pod is configured as a prototype.
inherited
isSingleton(String podName) → Future<bool>
Checks if the specified pod is configured as a singleton.
inherited
isTypeMatch(String name, Class typeToMatch, [bool allowPodProviderInit = false]) → Future<bool>
Checks if the pod with the specified name matches the given type.
inherited
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
preInstantiateSingletons() → Future<void>
Pre-instantiates all singleton pods.
inherited
publishEvent(ApplicationEvent event) → Future<void>
Publishes the given event to all registered ApplicationEventListeners.
register(PodRegistrar registrar) → Future<void>
Registers a registrar that declares pods into this registry.
inherited
registerAlias(String name, String alias) → void
Registers an alias for an existing name in the registry.
inherited
registerDefinition(String name, PodDefinition pod) → Future<void>
Register a new pod under the given name.
inherited
registerIgnoredDependency(Class type) → void
Registers a dependency type that should be ignored during autowiring.
inherited
registerPod<T>(Class<T> podClass, {Consumer<Spec<T>>? customizer, String? name}) → Future<void>
Registers a pod of type T in the registry.
inherited
registerResolvableDependency(Class type, [Object? autowiredValue]) → void
Registers a resolvable dependency for autowiring.
inherited
registerScope(String scopeName, PodScope scope) → void
Registers a new scope with the given name.
inherited
registerSingleton(String name, Class type, {ObjectHolder<Object>? object, ObjectFactory<Object>? factory}) → Future<void>
Register a new pod under the given name.
inherited
removeAlias(String alias) → void
Removes an alias from the registry.
inherited
removeDefinition(String name) → Future<void>
Remove the pod associated with name.
inherited
removeSingleton(String name) → void
Remove the pod associated with name.
inherited
resolveDependency(DependencyDescriptor descriptor, [Set<String>? autowiredPods]) → Future<Object?>
Resolves a dependency based on the provided descriptor.
inherited
setAllowCircularReferences(bool value) → void
Allows or disallows circular references between pods.
inherited
setAllowDefinitionOverriding(bool value) → void
Allows or disallows overriding of pod definitions.
inherited
setAllowRawInjection(bool value) → void
Allows or disallows raw injection despite wrapping.
inherited
setApplicationStartup(ApplicationStartup applicationStartup) → void
Defines a contract for components that are aware of and can interact with an ApplicationStartup strategy.
inherited
setCachePodMetadata(bool cachePodMetadata) → void
Enables or disables caching of pod metadata for performance optimization.
inherited
setConversionService(ConversionService conversionService) → void
Sets an assigned ConversionService.
inherited
setEnvironment(Environment environment) → void
Sets the Environment that this component runs in.
inherited
setParentFactory(PodFactory? parentFactory) → void
Sets the parent factory for this hierarchical factory.
inherited
setPodExpressionResolver(PodExpressionResolver? valueResolver) → void
Sets the expression resolver for resolving expressions in pod definitions.
inherited
supports(ApplicationType applicationType) → bool
Returns whether this context supports the given applicationType.
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited