0
# Spring Beans - IoC Container and Dependency Injection
1

2
Spring Beans is a core module of the Spring Framework that provides comprehensive Inversion of Control (IoC) container and dependency injection capabilities. This library forms the foundation for Spring's dependency injection system, enabling developers to build loosely coupled, testable applications by managing object creation, wiring, and lifecycle automatically.
3

4
## Package Information
5

6
- **Package Name**: org.springframework:spring-beans
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Version**: 6.2.8
10
- **Installation**: Add to Maven `pom.xml`:
11

12
```xml
13
<dependency>
14
    <groupId>org.springframework</groupId>
15
    <artifactId>spring-beans</artifactId>
16
    <version>6.2.8</version>
17
</dependency>
18
```
19

20
## Core Imports
21

22
```java
23
import org.springframework.beans.factory.BeanFactory;
24
import org.springframework.beans.factory.config.BeanDefinition;
25
import org.springframework.beans.factory.support.DefaultListableBeanFactory;
26
import org.springframework.beans.factory.xml.XmlBeanDefinitionReader;
27
```
28

29
For property binding and type conversion:
30

31
```java
32
import org.springframework.beans.BeanWrapper;
33
import org.springframework.beans.BeanWrapperImpl;
34
import org.springframework.beans.PropertyAccessor;
35
```
36

37
## Basic Usage
38

39
```java
40
import org.springframework.beans.factory.BeanFactory;
41
import org.springframework.beans.factory.support.DefaultListableBeanFactory;
42
import org.springframework.beans.factory.xml.XmlBeanDefinitionReader;
43
import org.springframework.core.io.ClassPathResource;
44

45
// Create a bean factory
46
DefaultListableBeanFactory factory = new DefaultListableBeanFactory();
47

48
// Load bean definitions from XML
49
XmlBeanDefinitionReader reader = new XmlBeanDefinitionReader(factory);
50
reader.loadBeanDefinitions(new ClassPathResource("beans.xml"));
51

52
// Retrieve beans
53
MyService service = factory.getBean("myService", MyService.class);
54

55
// Property binding example
56
BeanWrapper wrapper = new BeanWrapperImpl(new MyBean());
57
wrapper.setPropertyValue("name", "Spring");
58
wrapper.setPropertyValue("active", true);
59
```
60

61
## Architecture
62

63
Spring Beans is built around several key architectural patterns:
64

65
- **BeanFactory**: Core interface for accessing and managing beans in the IoC container
66
- **BeanDefinition**: Metadata describing how beans should be created and configured
67
- **Property Access**: Comprehensive system for binding and converting property values
68
- **Bean Lifecycle**: Complete lifecycle management including initialization, destruction, and scope handling
69
- **XML Configuration**: Extensible XML parsing and namespace handling for bean definitions
70
- **Annotation Support**: Integration with annotations for dependency injection and configuration
71
- **AOT Compilation**: Ahead-of-time compilation support for native image generation
72

73
This design provides a flexible, extensible foundation for dependency injection that supports multiple configuration approaches (XML, annotations, Java configuration) while maintaining high performance and modularity.
74

75
## Capabilities
76

77
### Bean Factory and Container
78

79
Core IoC container functionality for managing bean definitions, lifecycle, and dependency injection. Provides the fundamental infrastructure for creating and managing application objects.
80

81
```java { .api }
82
interface BeanFactory {
83
    String FACTORY_BEAN_PREFIX = "&";
84
    
85
    Object getBean(String name) throws BeansException;
86
    <T> T getBean(String name, Class<T> requiredType) throws BeansException;
87
    <T> T getBean(Class<T> requiredType) throws BeansException;
88
    Object getBean(String name, Object... args) throws BeansException;
89
    <T> T getBean(Class<T> requiredType, Object... args) throws BeansException;
90
    boolean containsBean(String name);
91
    boolean isSingleton(String name) throws NoSuchBeanDefinitionException;
92
    boolean isPrototype(String name) throws NoSuchBeanDefinitionException;
93
    boolean isTypeMatch(String name, Class<?> typeToMatch) throws NoSuchBeanDefinitionException;
94
    boolean isTypeMatch(String name, ResolvableType typeToMatch) throws NoSuchBeanDefinitionException;
95
    Class<?> getType(String name) throws NoSuchBeanDefinitionException;
96
    Class<?> getType(String name, boolean allowFactoryBeanInit) throws NoSuchBeanDefinitionException;
97
    String[] getAliases(String name);
98
    <T> ObjectProvider<T> getBeanProvider(Class<T> requiredType);
99
    <T> ObjectProvider<T> getBeanProvider(ResolvableType requiredType);
100
}
101

102
interface HierarchicalBeanFactory extends BeanFactory {
103
    BeanFactory getParentBeanFactory();
104
    boolean containsLocalBean(String name);
105
}
106

107
interface ListableBeanFactory extends BeanFactory {
108
    boolean containsBeanDefinition(String beanName);
109
    int getBeanDefinitionCount();
110
    String[] getBeanDefinitionNames();
111
    String[] getBeanNamesForType(Class<?> type);
112
    String[] getBeanNamesForType(ResolvableType type);
113
    <T> Map<String, T> getBeansOfType(Class<T> type) throws BeansException;
114
    String[] getBeanNamesForAnnotation(Class<? extends Annotation> annotationType);
115
    Map<String, Object> getBeansWithAnnotation(Class<? extends Annotation> annotationType) throws BeansException;
116
    <A extends Annotation> A findAnnotationOnBean(String beanName, Class<A> annotationType) throws NoSuchBeanDefinitionException;
117
}
118

119
interface AutowireCapableBeanFactory extends BeanFactory {
120
    int AUTOWIRE_NO = 0;
121
    int AUTOWIRE_BY_NAME = 1;
122
    int AUTOWIRE_BY_TYPE = 2;
123
    int AUTOWIRE_CONSTRUCTOR = 3;
124
    String ORIGINAL_INSTANCE_SUFFIX = ".ORIGINAL";
125
    
126
    <T> T createBean(Class<T> beanClass) throws BeansException;
127
    void autowireBean(Object existingBean) throws BeansException;
128
    Object configureBean(Object existingBean, String beanName) throws BeansException;
129
    Object initializeBean(Object existingBean, String beanName) throws BeansException;
130
    Object applyBeanPostProcessorsBeforeInitialization(Object existingBean, String beanName) throws BeansException;
131
    Object applyBeanPostProcessorsAfterInitialization(Object existingBean, String beanName) throws BeansException;
132
    void destroyBean(Object existingBean);
133
    <T> NamedBeanHolder<T> resolveNamedBean(Class<T> requiredType) throws BeansException;
134
    Object resolveBeanByName(String name, DependencyDescriptor descriptor) throws BeansException;
135
    Object resolveDependency(DependencyDescriptor descriptor, String requestingBeanName) throws BeansException;
136
    Object resolveDependency(DependencyDescriptor descriptor, String requestingBeanName, Set<String> autowiredBeanNames, TypeConverter typeConverter) throws BeansException;
137
}
138
```
139

140
[Bean Factory and Container](./bean-factory.md)
141

142
### Property Access and Type Conversion
143

144
Powerful property binding system with automatic type conversion, nested property access, and comprehensive editor support for converting between string representations and Java objects.
145

146
```java { .api }
147
interface PropertyAccessor {
148
    void setPropertyValue(String propertyName, Object value) throws BeansException;
149
    void setPropertyValue(PropertyValue pv) throws BeansException;
150
    Object getPropertyValue(String propertyName) throws BeansException;
151
    PropertyDescriptor[] getPropertyDescriptors();
152
    PropertyDescriptor getPropertyDescriptor(String propertyName) throws InvalidPropertyException;
153
}
154

155
interface BeanWrapper extends PropertyAccessor {
156
    void setWrappedInstance(Object object);
157
    Object getWrappedInstance();
158
    Class<?> getWrappedClass();
159
}
160
```
161

162
[Property Access and Type Conversion](./property-access.md)
163

164
### Bean Definition and Configuration
165

166
Bean definition infrastructure supporting multiple configuration sources (XML, annotations, programmatic) with comprehensive metadata management and validation.
167

168
```java { .api }
169
interface BeanDefinition extends AttributeAccessor, BeanMetadataElement {
170
    String getBeanClassName();
171
    void setBeanClassName(String beanClassName);
172
    String getScope();
173
    void setScope(String scope);
174
    boolean isLazyInit();
175
    void setLazyInit(boolean lazyInit);
176
    String[] getDependsOn();
177
    void setDependsOn(String... dependsOn);
178
}
179

180
interface BeanDefinitionRegistry extends AliasRegistry {
181
    void registerBeanDefinition(String beanName, BeanDefinition beanDefinition)
182
        throws BeanDefinitionStoreException;
183
    void removeBeanDefinition(String beanName) throws NoSuchBeanDefinitionException;
184
    BeanDefinition getBeanDefinition(String beanName) throws NoSuchBeanDefinitionException;
185
}
186
```
187

188
[Bean Definition and Configuration](./bean-definition.md)
189

190
### Annotation-Based Configuration
191

192
Comprehensive annotation support for dependency injection, lifecycle callbacks, and bean configuration with automatic detection and processing.
193

194
```java { .api }
195
@interface Autowired {
196
    boolean required() default true;
197
}
198

199
@interface Qualifier {
200
    String value() default "";
201
}
202

203
@interface Value {
204
    String value();
205
}
206

207
class AutowiredAnnotationBeanPostProcessor implements BeanPostProcessor {
208
    void setAutowiredAnnotationType(Class<? extends Annotation> autowiredAnnotationType);
209
    void postProcessMergedBeanDefinition(RootBeanDefinition beanDefinition, Class<?> beanType, String beanName);
210
}
211
```
212

213
[Annotation-Based Configuration](./annotation-config.md)
214

215
### XML Configuration Support
216

217
Extensible XML parsing framework with namespace support, custom schema handling, and comprehensive bean definition loading from XML configuration files.
218

219
```java { .api }
220
class XmlBeanDefinitionReader extends AbstractBeanDefinitionReader {
221
    int loadBeanDefinitions(Resource resource) throws BeanDefinitionStoreException;
222
    void setValidationMode(int validationMode);
223
    void setNamespaceAware(boolean namespaceAware);
224
}
225

226
interface NamespaceHandler {
227
    void init();
228
    BeanDefinition parse(Element element, ParserContext parserContext);
229
    BeanDefinitionHolder decorate(Node node, BeanDefinitionHolder definition, ParserContext parserContext);
230
}
231
```
232

233
[XML Configuration Support](./xml-config.md)
234

235
### AOT and Native Compilation
236

237
Ahead-of-time compilation support for native image generation, providing build-time optimization and reflection-free bean instantiation.
238

239
```java { .api }
240
interface BeanRegistrationAotProcessor {
241
    BeanRegistrationAotContribution processAheadOfTime(RegisteredBean registeredBean);
242
}
243

244
interface BeanFactoryInitializationAotProcessor {
245
    BeanFactoryInitializationAotContribution processAheadOfTime(ConfigurableListableBeanFactory beanFactory);
246
}
247

248
class InstanceSupplierCodeGenerator {
249
    CodeBlock generateCode(RegisteredBean registeredBean, Executable constructorOrFactoryMethod);
250
}
251
```
252

253
[AOT and Native Compilation](./aot-support.md)
254

255
### Bean Lifecycle and Processing
256

257
Comprehensive bean lifecycle management including initialization, destruction, and post-processing hooks for customizing bean creation and configuration.
258

259
```java { .api }
260
interface InitializingBean {
261
    void afterPropertiesSet() throws Exception;
262
}
263

264
interface DisposableBean {
265
    void destroy() throws Exception;
266
}
267

268
interface BeanPostProcessor {
269
    default Object postProcessBeforeInitialization(Object bean, String beanName) throws BeansException {
270
        return bean;
271
    }
272
    default Object postProcessAfterInitialization(Object bean, String beanName) throws BeansException {
273
        return bean;
274
    }
275
}
276

277
interface InstantiationAwareBeanPostProcessor extends BeanPostProcessor {
278
    default Object postProcessBeforeInstantiation(Class<?> beanClass, String beanName) throws BeansException {
279
        return null;
280
    }
281
    default boolean postProcessAfterInstantiation(Object bean, String beanName) throws BeansException {
282
        return true;
283
    }
284
    default PropertyValues postProcessProperties(PropertyValues pvs, Object bean, String beanName) throws BeansException {
285
        return null;
286
    }
287
}
288
```
289

290
### Factory Bean Support
291

292
Support for custom factory beans that create objects through specialized factory logic rather than direct instantiation.
293

294
```java { .api }
295
interface FactoryBean<T> {
296
    T getObject() throws Exception;
297
    Class<?> getObjectType();
298
    default boolean isSingleton() {
299
        return true;
300
    }
301
}
302

303
interface SmartFactoryBean<T> extends FactoryBean<T> {
304
    default boolean isPrototype() {
305
        return false;
306
    }
307
    default boolean isEagerInit() {
308
        return false;
309
    }
310
}
311
```
312

313
## Common Types
314

315
```java { .api }
316
// Exception Hierarchy
317
class BeansException extends RuntimeException {
318
    public BeansException(String msg);
319
    public BeansException(String msg, Throwable cause);
320
}
321

322
class BeanCreationException extends BeansException {
323
    public BeanCreationException(String beanName, String msg);
324
    public BeanCreationException(String beanName, String msg, Throwable cause);
325
    public String getBeanName();
326
}
327

328
class NoSuchBeanDefinitionException extends BeansException {
329
    public NoSuchBeanDefinitionException(String name);
330
    public NoSuchBeanDefinitionException(Class<?> type);
331
    public NoSuchBeanDefinitionException(ResolvableType type);
332
    public String getBeanName();
333
    public Class<?> getBeanType();
334
    public ResolvableType getResolvableType();
335
}
336

337
class NoUniqueBeanDefinitionException extends NoSuchBeanDefinitionException {
338
    public NoUniqueBeanDefinitionException(Class<?> type, int numberOfBeansFound, String message);
339
    public NoUniqueBeanDefinitionException(Class<?> type, Collection<String> beanNamesFound);
340
    public int getNumberOfBeansFound();
341
    public Collection<String> getBeanNamesFound();
342
}
343

344
class BeanDefinitionStoreException extends BeansException {
345
    public BeanDefinitionStoreException(String msg);
346
    public BeanDefinitionStoreException(String resourceDescription, String msg);
347
    public BeanDefinitionStoreException(String resourceDescription, String beanName, String msg);
348
    public String getResourceDescription();
349
    public String getBeanName();
350
}
351

352
// Core Interfaces and Types
353
interface ObjectProvider<T> extends ObjectFactory<T>, Iterable<T> {
354
    T getObject() throws BeansException;
355
    T getIfAvailable() throws BeansException;
356
    T getIfAvailable(Supplier<T> defaultSupplier) throws BeansException;
357
    void ifAvailable(Consumer<T> dependencyConsumer) throws BeansException;
358
    T getIfUnique() throws BeansException;
359
    T getIfUnique(Supplier<T> defaultSupplier) throws BeansException;
360
    void ifUnique(Consumer<T> dependencyConsumer) throws BeansException;
361
    Stream<T> stream();
362
    Stream<T> orderedStream();
363
}
364

365
interface ObjectFactory<T> {
366
    T getObject() throws BeansException;
367
}
368

369
class NamedBeanHolder<T> implements BeanNameAware {
370
    public NamedBeanHolder(String beanName, T beanInstance);
371
    public String getBeanName();
372
    public T getBeanInstance();
373
}
374

375
class DependencyDescriptor implements Serializable {
376
    public DependencyDescriptor(Field field, boolean required);
377
    public DependencyDescriptor(MethodParameter methodParameter, boolean required);
378
    public boolean isRequired();
379
    public boolean isEager();
380
    public Class<?> getDependencyType();
381
    public String getDependencyName();
382
    public ResolvableType getResolvableType();
383
}
384

385
// Property Value Classes
386
class PropertyValue {
387
    public PropertyValue(String name, Object value);
388
    public String getName();
389
    public Object getValue();
390
    public boolean isOptional();
391
    public boolean isConverted();
392
    public Object getConvertedValue();
393
}
394

395
class MutablePropertyValues implements PropertyValues {
396
    public MutablePropertyValues();
397
    public MutablePropertyValues(PropertyValues original);
398
    public MutablePropertyValues addPropertyValue(PropertyValue pv);
399
    public MutablePropertyValues addPropertyValue(String propertyName, Object propertyValue);
400
    public void addPropertyValues(PropertyValues other);
401
    public PropertyValue[] getPropertyValues();
402
    public PropertyValue getPropertyValue(String propertyName);
403
    public boolean contains(String propertyName);
404
    public boolean isEmpty();
405
}
406

407
// Lifecycle Interfaces
408
interface InitializingBean {
409
    void afterPropertiesSet() throws Exception;
410
}
411

412
interface DisposableBean {
413
    void destroy() throws Exception;
414
}
415

416
interface BeanNameAware {
417
    void setBeanName(String name);
418
}
419

420
interface BeanFactoryAware {
421
    void setBeanFactory(BeanFactory beanFactory) throws BeansException;
422
}
423

424
interface BeanClassLoaderAware {
425
    void setBeanClassLoader(ClassLoader classLoader);
426
}
427

428
// Bean Post Processing
429
interface BeanPostProcessor {
430
    default Object postProcessBeforeInitialization(Object bean, String beanName) throws BeansException {
431
        return bean;
432
    }
433
    default Object postProcessAfterInitialization(Object bean, String beanName) throws BeansException {
434
        return bean;
435
    }
436
}
437

438
interface InstantiationAwareBeanPostProcessor extends BeanPostProcessor {
439
    default Object postProcessBeforeInstantiation(Class<?> beanClass, String beanName) throws BeansException {
440
        return null;
441
    }
442
    default boolean postProcessAfterInstantiation(Object bean, String beanName) throws BeansException {
443
        return true;
444
    }
445
    default PropertyValues postProcessProperties(PropertyValues pvs, Object bean, String beanName) throws BeansException {
446
        return null;
447
    }
448
}
449

450
interface DestructionAwareBeanPostProcessor extends BeanPostProcessor {
451
    void postProcessBeforeDestruction(Object bean, String beanName) throws BeansException;
452
    default boolean requiresDestruction(Object bean) {
453
        return true;
454
    }
455
}
456

457
// Factory Bean Support
458
interface FactoryBean<T> {
459
    T getObject() throws Exception;
460
    Class<?> getObjectType();
461
    default boolean isSingleton() {
462
        return true;
463
    }
464
}
465

466
interface SmartFactoryBean<T> extends FactoryBean<T> {
467
    default boolean isPrototype() {
468
        return false;
469
    }
470
    default boolean isEagerInit() {
471
        return false;
472
    }
473
}
474

475
// Utility Support
476
interface Mergeable {
477
    boolean isMergeEnabled();
478
    Object merge(Object parent);
479
}
480

481
interface AttributeAccessor {
482
    void setAttribute(String name, Object value);
483
    Object getAttribute(String name);
484
    Object removeAttribute(String name);
485
    boolean hasAttribute(String name);
486
    String[] attributeNames();
487
}
488

489
interface BeanMetadataElement {
490
    default Object getSource() {
491
        return null;
492
    }
493
}
494

495
interface AliasRegistry {
496
    void registerAlias(String name, String alias);
497
    void removeAlias(String alias);
498
    boolean isAlias(String name);
499
    String[] getAliases(String name);
500
}
501
```
502

503
// Spring Core Types (from spring-core dependency)
504
class ResolvableType {
505
    public static ResolvableType forClass(Class<?> clazz);
506
    public static ResolvableType forType(Type type);
507
    public static ResolvableType forMethodParameter(MethodParameter methodParameter);
508
    public static ResolvableType forField(Field field);
509
    public Class<?> resolve();
510
    public Class<?> resolve(Class<?> fallback);
511
    public ResolvableType[] getGenerics();
512
    public boolean isAssignableFrom(ResolvableType other);
513
    public boolean hasGenerics();
514
}
515

516
class MethodParameter {
517
    public MethodParameter(Method method, int parameterIndex);
518
    public MethodParameter(Constructor<?> constructor, int parameterIndex);
519
    public Method getMethod();
520
    public Constructor<?> getConstructor();
521
    public Class<?> getParameterType();
522
    public Type getGenericParameterType();
523
    public String getParameterName();
524
    public int getParameterIndex();
525
}
526

527
// JavaBeans Types (from java.beans)
528
class PropertyDescriptor {
529
    public String getName();
530
    public Method getReadMethod();
531
    public Method getWriteMethod();
532
    public Class<?> getPropertyType();
533
    public boolean isBound();
534
    public boolean isConstrained();
535
}
536

537
// Type Conversion Support
538
interface ConversionService {
539
    boolean canConvert(Class<?> sourceType, Class<?> targetType);
540
    boolean canConvert(TypeDescriptor sourceType, TypeDescriptor targetType);
541
    <T> T convert(Object source, Class<T> targetType);
542
    Object convert(Object source, TypeDescriptor sourceType, TypeDescriptor targetType);
543
}
544

545
class TypeDescriptor {
546
    public static TypeDescriptor valueOf(Class<?> type);
547
    public static TypeDescriptor forObject(Object object);
548
    public Class<?> getType();
549
    public ResolvableType getResolvableType();
550
    public boolean isCollection();
551
    public boolean isArray();
552
    public boolean isMap();
553
}
554

555
// Additional Support Interfaces
556
interface Ordered {
557
    int HIGHEST_PRECEDENCE = Integer.MIN_VALUE;
558
    int LOWEST_PRECEDENCE = Integer.MAX_VALUE;
559
    
560
    int getOrder();
561
}
562

563
interface Scope {
564
    Object get(String name, ObjectFactory<?> objectFactory);
565
    Object remove(String name);
566
    void registerDestructionCallback(String name, Runnable callback);
567
    Object resolveContextualObject(String key);
568
    String getConversationId();
569
}
570

571
interface StringValueResolver {
572
    String resolveStringValue(String strVal);
573
}
574

575
interface BeanExpressionResolver {
576
    Object evaluate(String value, BeanExpressionContext evalContext) throws BeansException;
577
}
578

579
class BeanExpressionContext {
580
    public BeanExpressionContext(ConfigurableBeanFactory beanFactory, Scope scope);
581
    public ConfigurableBeanFactory getBeanFactory();
582
    public Scope getScope();
583
    public boolean containsObject(String key);
584
    public Object getObject(String key);
585
}
586

587
// Property Editor Support
588
abstract class PropertyEditorSupport implements PropertyEditor {
589
    public PropertyEditorSupport();
590
    public PropertyEditorSupport(Object source);
591
    public void setValue(Object value);
592
    public Object getValue();
593
    public boolean isPaintable();
594
    public void paintValue(Graphics gfx, Rectangle box);
595
    public String getJavaInitializationString();
596
    public String getAsText();
597
    public void setAsText(String text) throws IllegalArgumentException;
598
    public String[] getTags();
599
    public Component getCustomEditor();
600
    public boolean supportsCustomEditor();
601
    public void addPropertyChangeListener(PropertyChangeListener listener);
602
    public void removePropertyChangeListener(PropertyChangeListener listener);
603
    public void firePropertyChange();
604
}
605

606
interface PropertyEditorRegistry {
607
    void registerCustomEditor(Class<?> requiredType, PropertyEditor propertyEditor);
608
    void registerCustomEditor(Class<?> requiredType, String propertyPath, PropertyEditor propertyEditor);
609
    PropertyEditor findCustomEditor(Class<?> requiredType, String propertyPath);
610
}
611

612
interface PropertyEditorRegistrar {
613
    void registerCustomEditors(PropertyEditorRegistry registry);
614
}
615