spring-beans

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

Purpose

spring-beans defines what a "bean" is and how the container creates one. It contains the BeanFactory hierarchy, the BeanDefinition model, the property-binding machinery, and all the post-processors that wire dependencies and call lifecycle callbacks. It is the lowest layer of the IoC container; spring-context builds an ApplicationContext on top of it.

Directory layout

spring-beans/
└── src/main/java/org/springframework/beans/
    ├── BeanUtils.java
    ├── BeanWrapper.java
    ├── BeanWrapperImpl.java
    ├── PropertyAccessor.java
    ├── annotation/                                # @Order, @Required (legacy)
    ├── factory/
    │   ├── BeanFactory.java                       # the core lookup interface
    │   ├── annotation/                            # @Autowired, @Qualifier, @Value processors
    │   ├── config/                                # BeanDefinition, BeanPostProcessor
    │   ├── parsing/                               # XML/Groovy bean DSL parsing
    │   ├── support/                               # default factory implementations
    │   ├── xml/                                   # XML bean definition parsing
    │   ├── groovy/                                # Groovy DSL
    │   └── aot/                                   # AOT-time BeanRegistrationContributor
    ├── propertyeditors/                           # PropertyEditor implementations
    └── support/                                   # ResourceEditorRegistrar, etc.

Key abstractions

Type	File	Role
BeanFactory	spring-beans/src/main/java/org/springframework/beans/factory/BeanFactory.java	The minimal interface for getting beans
ListableBeanFactory	spring-beans/src/main/java/org/springframework/beans/factory/ListableBeanFactory.java	Adds enumeration: list bean names by type
HierarchicalBeanFactory	spring-beans/src/main/java/org/springframework/beans/factory/HierarchicalBeanFactory.java	Parent/child factory relationships
ConfigurableBeanFactory	spring-beans/src/main/java/org/springframework/beans/factory/config/ConfigurableBeanFactory.java	Configuration of post-processors, scopes, etc.
DefaultListableBeanFactory	spring-beans/src/main/java/org/springframework/beans/factory/support/DefaultListableBeanFactory.java	The full, default BeanFactory implementation
BeanDefinition	spring-beans/src/main/java/org/springframework/beans/factory/config/BeanDefinition.java	Metadata describing how to create a bean
RootBeanDefinition / GenericBeanDefinition	spring-beans/src/main/java/org/springframework/beans/factory/support/	Common implementations
BeanPostProcessor	spring-beans/src/main/java/org/springframework/beans/factory/config/BeanPostProcessor.java	Wraps/modifies beans during initialization
BeanFactoryPostProcessor	spring-beans/src/main/java/org/springframework/beans/factory/config/BeanFactoryPostProcessor.java	Modifies BeanDefinitions before instantiation
AutowiredAnnotationBeanPostProcessor	spring-beans/src/main/java/org/springframework/beans/factory/annotation/AutowiredAnnotationBeanPostProcessor.java	Processes @Autowired, @Inject, @Value
BeanWrapper	spring-beans/src/main/java/org/springframework/beans/BeanWrapper.java	Bulk property access with type conversion
Scope	spring-beans/src/main/java/org/springframework/beans/factory/config/Scope.java	Pluggable scope SPI (singleton, prototype, request, …)

How it works

Bean lifecycle

The lifecycle of a singleton bean is the framework's most important state machine.

graph TD
    DEF[BeanDefinition registered] --> BFPP[BeanFactoryPostProcessors run]
    BFPP --> INST[Instantiation]
    INST --> POPULATE[Populate properties]
    POPULATE --> AWARE[Aware callbacks]
    AWARE --> BPP_BEFORE[BeanPostProcessor.postProcessBeforeInitialization]
    BPP_BEFORE --> INIT[Init: @PostConstruct, InitializingBean.afterPropertiesSet, init-method]
    INIT --> BPP_AFTER[BeanPostProcessor.postProcessAfterInitialization]
    BPP_AFTER --> READY[Ready for use]
    READY -.context close.-> DESTROY[Destroy: @PreDestroy, DisposableBean.destroy, destroy-method]

Several BeanPostProcessors contribute features:

• AutowiredAnnotationBeanPostProcessor — handles @Autowired, @Inject, @Value
• CommonAnnotationBeanPostProcessor — handles @Resource, @PostConstruct, @PreDestroy
• AnnotationAwareAspectJAutoProxyCreator (in spring-aop) — installs AOP proxies
• ConfigurationClassPostProcessor (in spring-context) — processes @Configuration classes

Bean definition sources

Bean definitions enter the factory from several places:

Source	How
XML	XmlBeanDefinitionReader parses <bean> elements
@Configuration classes	ConfigurationClassPostProcessor (in spring-context)
@ComponentScan	ClassPathBeanDefinitionScanner
Groovy DSL	GroovyBeanDefinitionReader
Programmatic	BeanDefinitionRegistry.registerBeanDefinition(...)
AOT (build-time)	Generated BeanRegistrationsAotContribution classes

All of them write to the same BeanDefinitionRegistry (which DefaultListableBeanFactory implements).

Autowiring

@Autowired resolution proceeds:

1. By type — find candidates whose BeanDefinition's class is assignable.
2. Filter by @Qualifier — if the injection point has a qualifier, narrow.
3. @Primary and @Order — if multiple candidates remain, pick the primary or the highest-priority.
4. Generics matching — for parameterized types, narrow by ResolvableType match.
5. Fallback — if required = false, accept zero matches; otherwise fail.

The implementation lives in DefaultListableBeanFactory.doResolveDependency(...) and is one of the more complex algorithms in the framework. It's also a hot spot for AOT, because reflection on injection points must be replayed at runtime in native images.

Property binding

BeanWrapper/BeanWrapperImpl provide bulk property setters with type conversion. Used internally for XML property binding and externally available as a public utility. The default BeanWrapperImpl registers ~30 PropertyEditors for common types (URL, Date, Charset, File, …).

The newer ConversionService (in spring-core) is the preferred SPI for new code; PropertyEditor is the legacy API but still active.

Integration points

• Inputs: Resource (XML/Groovy bean definitions), classpath scanning, programmatic registration.
• Outputs: A BeanFactory that anyone (spring-context, applications, tests) can query.
• Extensions: Implement BeanPostProcessor for runtime behavior, or BeanFactoryPostProcessor to transform definitions, or BeanDefinitionRegistryPostProcessor to add/remove definitions before any are realized.

Entry points for modification

• New annotation processor for injection — Subclass or imitate AutowiredAnnotationBeanPostProcessor.
• Alternative bean factory — Subclass DefaultListableBeanFactory. The AbstractAutowireCapableBeanFactory parent contains the bulk of the lifecycle code.
• New scope — Implement Scope and register it via ConfigurableBeanFactory.registerScope(name, scope).
• Adding metadata to a bean — Use BeanMetadataAttribute and BeanMetadataAttributeAccessor.

See also

• spring-context — ApplicationContext builds on BeanFactory
• features/dependency-injection — End-to-end DI walkthrough
• spring-aop — How AOP plugs into the bean lifecycle