spring-projects/spring-framework

spring-context

Active contributors: Juergen Hoeller, Sam Brannen, Sébastien Deleuze

Purpose

spring-context provides the ApplicationContext — Spring's user-facing container interface. It composes spring-beans with messaging, events, resource loading, AOP, validation, scheduling, caching, and Java-config processing into a complete IoC platform. It is the module application code most often interacts with.

Directory layout

spring-context/
└── src/main/java/org/springframework/context/
    ├── ApplicationContext.java
    ├── ApplicationContextAware.java
    ├── ApplicationEvent.java
    ├── ApplicationListener.java
    ├── ConfigurableApplicationContext.java
    ├── Lifecycle.java / SmartLifecycle.java
    ├── MessageSource.java
    ├── annotation/                                # @Configuration, @Bean, @ComponentScan, @Import, …
    ├── aot/                                       # AOT processing for @Configuration classes
    ├── config/                                    # XML namespace handlers
    ├── event/                                     # ApplicationEventMulticaster, @EventListener
    ├── expression/                                # SpEL integration with bean factory
    ├── i18n/                                      # LocaleContextHolder, TimeZone aware
    ├── index/                                     # CandidateComponentsIndexLoader
    ├── support/                                   # AbstractApplicationContext, Generic*Context, …
    └── weaving/                                   # LTW agent wiring
spring-context/src/main/java/org/springframework/
    ├── cache/                                     # Cache abstraction
    ├── ejb/                                       # AbstractRemoteSlsbInvokerInterceptor
    ├── ejb-jca/                                   # legacy
    ├── ejb-utility/                               # legacy
    ├── format/                                    # Formatter, FormatterRegistry
    ├── instrument/                                # ClassFileTransformer support
    ├── jmx/                                       # JMX exporter and proxy
    ├── jndi/                                      # JndiLocator, JndiObjectFactoryBean
    ├── remoting/                                  # legacy remoting (mostly deprecated)
    ├── scheduling/                                # @Async, @Scheduled, TaskScheduler
    ├── stereotype/                                # @Component, @Service, @Repository, @Controller
    ├── ui/                                        # Model, ModelMap, Concurrent
    └── validation/                                # Errors, Validator, BindingResult

Key abstractions

Type	File	Role
`ApplicationContext`	`spring-context/src/main/java/org/springframework/context/ApplicationContext.java`	The container interface app code uses
`ConfigurableApplicationContext`	`spring-context/src/main/java/org/springframework/context/ConfigurableApplicationContext.java`	Adds lifecycle (refresh, close) and configuration
`AbstractApplicationContext`	`spring-context/src/main/java/org/springframework/context/support/AbstractApplicationContext.java`	Shared `refresh()` template implementation
`AnnotationConfigApplicationContext`	`spring-context/src/main/java/org/springframework/context/annotation/AnnotationConfigApplicationContext.java`	The Java-config entry point
`GenericApplicationContext`	`spring-context/src/main/java/org/springframework/context/support/GenericApplicationContext.java`	Programmatic context with optional scanning
`ConfigurationClassPostProcessor`	`spring-context/src/main/java/org/springframework/context/annotation/ConfigurationClassPostProcessor.java`	Processes `@Configuration` classes
`ApplicationEvent` / `ApplicationListener`	`spring-context/src/main/java/org/springframework/context/`	Pub-sub event model
`EventListenerMethodProcessor`	`spring-context/src/main/java/org/springframework/context/event/EventListenerMethodProcessor.java`	Discovers `@EventListener` methods
`MessageSource` / `ResourceBundleMessageSource`	`spring-context/src/main/java/org/springframework/context/`	Internationalization
`ApplicationEventMulticaster`	`spring-context/src/main/java/org/springframework/context/event/ApplicationEventMulticaster.java`	Dispatches events to listeners
`LifecycleProcessor` / `SmartLifecycle`	`spring-context/src/main/java/org/springframework/context/`	Coordinated start/stop
`@Async`, `@Scheduled`	`spring-context/src/main/java/org/springframework/scheduling/annotation/`	Background execution
`Cache` / `CacheManager`	`spring-context/src/main/java/org/springframework/cache/`	Cache abstraction

How it works

`refresh()`: the canonical bootstrap

Every ApplicationContext walks through AbstractApplicationContext.refresh(). This is the single most important method in the module:

graph TD
    R[refresh] --> PR[prepareRefresh]
    PR --> OB[obtainFreshBeanFactory]
    OB --> PB[prepareBeanFactory]
    PB --> POBFP[postProcessBeanFactory]
    POBFP --> IBFP[invokeBeanFactoryPostProcessors]
    IBFP --> RBPP[registerBeanPostProcessors]
    RBPP --> IMS[initMessageSource]
    IMS --> IAEM[initApplicationEventMulticaster]
    IAEM --> ON[onRefresh]
    ON --> RL[registerListeners]
    RL --> FBI[finishBeanFactoryInitialization]
    FBI --> FR[finishRefresh]

invokeBeanFactoryPostProcessors is where ConfigurationClassPostProcessor runs: it parses @Configuration classes, expanding @Bean/@Import/@ComponentScan into BeanDefinitions.
finishBeanFactoryInitialization instantiates all non-lazy singletons.
finishRefresh publishes ContextRefreshedEvent and starts SmartLifecycle beans.

Configuration class processing

graph LR
    CONFIG[Configuration class] -->|"parse"| CCPP[ConfigurationClassPostProcessor]
    CCPP -->|"@Bean methods"| BD[BeanDefinitions]
    CCPP -->|"@Import"| IMPORT[Imported configs / ImportSelector / Registrar]
    CCPP -->|"@ComponentScan"| SCAN[Component scanner]
    SCAN -->|"finds @Component, @Service, …"| BD
    IMPORT --> BD
    CCPP -->|"@PropertySource"| PS[PropertySource added to Environment]
    BD -->|"register"| BF[BeanFactory]

The output is a populated BeanFactory ready for instantiation.

Event publication

sequenceDiagram
    participant Bean
    participant Ctx as ApplicationContext
    participant Multi as ApplicationEventMulticaster
    participant Listener
    Bean->>Ctx: publishEvent(MyEvent)
    Ctx->>Multi: multicastEvent(MyEvent)
    Multi->>Listener: onApplicationEvent(MyEvent)
    Note over Multi,Listener: Optionally async via TaskExecutor

@EventListener methods are discovered by EventListenerMethodProcessor and registered as ApplicationListener adapters at startup.

Scheduling and async

@EnableScheduling and @EnableAsync import infrastructure beans:

ScheduledAnnotationBeanPostProcessor discovers @Scheduled methods and registers tasks with a TaskScheduler.
AsyncAnnotationBeanPostProcessor wraps @Async-annotated beans with an AOP advisor that dispatches to a TaskExecutor.

Cache abstraction

The cache abstraction (org.springframework.cache.*) defines Cache and CacheManager interfaces with @Cacheable, @CachePut, @CacheEvict annotations. Spring ships in-memory implementations; Caffeine, EhCache, JCache, Redis are pluggable via spring-context-support and Spring Boot starters.

Integration points

Builds on: spring-core, spring-beans, spring-aop, spring-expression (all api deps).
Used by: spring-context-support, all data-access modules (transaction support uses AOP from context), all web modules (web stacks build their own context types).
Optional ties: spring-instrument for load-time weaving, JSR-303 validators (Jakarta Bean Validation).

Entry points for modification

Adding a new context type — Subclass AbstractApplicationContext or GenericApplicationContext. Web stacks do this (AnnotationConfigServletWebApplicationContext, etc.).
Custom configuration class semantics — Implement ImportSelector or ImportBeanDefinitionRegistrar and reference from @Import.
Custom event delivery — Replace the applicationEventMulticaster bean (the multicaster is itself a bean and can be swapped).
Custom @Scheduled/@Async infrastructure — Provide a TaskScheduler / TaskExecutor bean with the standard names (taskScheduler, taskExecutor).

Notable internals

AnnotationMetadata (from spring-core) is used heavily here to inspect classes without loading them.
@Conditional and friends — The framework supports conditional bean registration; Spring Boot's @ConditionalOn* annotations build on this.
PropertySourcesPlaceholderConfigurer — Resolves ${...} placeholders in @Value and XML.
StandardEnvironment / StandardServletEnvironment / StandardReactiveWebEnvironment — Environment variants for different runtime models.