0
# Core Auto-Configuration
1

2
The core auto-configuration system provides the foundational annotations, classes, and mechanisms that enable Spring Boot's automatic configuration capabilities.
3

4
## Capabilities
5

6
### @SpringBootApplication Annotation
7

8
The primary annotation that combines configuration, component scanning, and auto-configuration enabling.
9

10
```java { .api }
11
/**
12
 * Convenience annotation that combines @SpringBootConfiguration, @EnableAutoConfiguration, and @ComponentScan
13
 * This is the standard way to bootstrap a Spring Boot application
14
 */
15
@Target(ElementType.TYPE)
16
@Retention(RetentionPolicy.RUNTIME)
17
@Documented
18
@Inherited
19
@SpringBootConfiguration
20
@EnableAutoConfiguration
21
@ComponentScan(excludeFilters = {
22
    @Filter(type = FilterType.CUSTOM, classes = TypeExcludeFilter.class),
23
    @Filter(type = FilterType.CUSTOM, classes = AutoConfigurationExcludeFilter.class)
24
})
25
public @interface SpringBootApplication {
26
    /**
27
     * Exclude specific auto-configuration classes
28
     * @return the classes to exclude
29
     */
30
    @AliasFor(annotation = EnableAutoConfiguration.class)
31
    Class<?>[] exclude() default {};
32
    
33
    /**
34
     * Exclude specific auto-configuration class names
35
     * @return the class names to exclude
36
     */
37
    @AliasFor(annotation = EnableAutoConfiguration.class)
38
    String[] excludeName() default {};
39
    
40
    /**
41
     * Base packages to scan for annotated components
42
     * @return base packages to scan
43
     */
44
    @AliasFor(annotation = ComponentScan.class, attribute = "basePackages")
45
    String[] scanBasePackages() default {};
46
    
47
    /**
48
     * Type-safe alternative to scanBasePackages
49
     * @return base package classes to scan
50
     */
51
    @AliasFor(annotation = ComponentScan.class, attribute = "basePackageClasses")
52
    Class<?>[] scanBasePackageClasses() default {};
53
    
54
    /**
55
     * Bean name generator for detected components
56
     * @return BeanNameGenerator class to use
57
     */
58
    @AliasFor(annotation = ComponentScan.class, attribute = "nameGenerator")
59
    Class<? extends BeanNameGenerator> nameGenerator() default BeanNameGenerator.class;
60
    
61
    /**
62
     * Whether to proxy @Bean methods for lifecycle behavior
63
     * @return whether to proxy @Bean methods
64
     */
65
    @AliasFor(annotation = Configuration.class)
66
    boolean proxyBeanMethods() default true;
67
}
68
```
69

70
**Usage Examples:**
71

72
```java
73
// Basic usage - most common pattern
74
@SpringBootApplication
75
public class MyApplication {
76
    public static void main(String[] args) {
77
        SpringApplication.run(MyApplication.class, args);
78
    }
79
}
80

81
// Excluding specific auto-configurations
82
@SpringBootApplication(exclude = {DataSourceAutoConfiguration.class})
83
public class MyApplication {
84
    // Application without DataSource auto-configuration
85
}
86

87
// Custom component scanning
88
@SpringBootApplication(scanBasePackages = {"com.example.app", "com.example.shared"})
89
public class MyApplication {
90
    // Scans specified packages for components
91
}
92
```
93

94
### @EnableAutoConfiguration Annotation
95

96
Enables Spring Boot's auto-configuration mechanism, attempting to guess and configure beans based on classpath contents.
97

98
```java { .api }
99
/**
100
 * Enable auto-configuration of the Spring Application Context
101
 * Auto-configuration classes are applied based on classpath and defined beans
102
 */
103
@Target(ElementType.TYPE)
104
@Retention(RetentionPolicy.RUNTIME)
105
@Documented
106
@Inherited
107
@AutoConfigurationPackage
108
@Import(AutoConfigurationImportSelector.class)
109
public @interface EnableAutoConfiguration {
110
    /**
111
     * Environment property to override auto-configuration
112
     */
113
    String ENABLED_OVERRIDE_PROPERTY = "spring.boot.enableautoconfiguration";
114
    
115
    /**
116
     * Exclude specific auto-configuration classes
117
     * @return the classes to exclude
118
     */
119
    Class<?>[] exclude() default {};
120
    
121
    /**
122
     * Exclude specific auto-configuration class names
123
     * @return the class names to exclude
124
     */
125
    String[] excludeName() default {};
126
}
127
```
128

129
### @AutoConfiguration Annotation
130

131
Indicates that a class provides auto-configuration for a specific technology or framework.
132

133
```java { .api }
134
/**
135
 * Indicates that a class provides auto-configuration
136
 * Regular @Configuration with proxyBeanMethods always false
137
 */
138
@Target(ElementType.TYPE)
139
@Retention(RetentionPolicy.RUNTIME)
140
@Documented
141
@Configuration(proxyBeanMethods = false)
142
@AutoConfigureBefore
143
@AutoConfigureAfter
144
public @interface AutoConfiguration {
145
    /**
146
     * Explicitly specify the Spring bean definition name
147
     * Alias for @Configuration.value()
148
     * @return the explicit component name, if any
149
     */
150
    @AliasFor(annotation = Configuration.class)
151
    String value() default "";
152
    
153
    /**
154
     * Auto-configuration classes that should have not yet been applied
155
     * @return classes to apply before this auto-configuration
156
     */
157
    @AliasFor(annotation = AutoConfigureBefore.class, attribute = "value")
158
    Class<?>[] before() default {};
159
    
160
    /**
161
     * Names of auto-configuration classes that should have not yet been applied
162
     * @return class names to apply before this auto-configuration
163
     */
164
    @AliasFor(annotation = AutoConfigureBefore.class, attribute = "name")
165
    String[] beforeName() default {};
166
    
167
    /**
168
     * Auto-configuration classes that should have already been applied
169
     * @return classes to apply after this auto-configuration
170
     */
171
    @AliasFor(annotation = AutoConfigureAfter.class, attribute = "value")
172
    Class<?>[] after() default {};
173
    
174
    /**
175
     * Names of auto-configuration classes that should have already been applied
176
     * @return class names to apply after this auto-configuration
177
     */
178
    @AliasFor(annotation = AutoConfigureAfter.class, attribute = "name")
179
    String[] afterName() default {};
180
}
181
```
182

183
### Auto-Configuration Ordering Annotations
184

185
Control the order in which auto-configurations are applied.
186

187
```java { .api }
188
/**
189
 * Specifies that an auto-configuration should be applied after specific classes
190
 */
191
@Target(ElementType.TYPE)
192
@Retention(RetentionPolicy.RUNTIME)
193
@Documented
194
public @interface AutoConfigureAfter {
195
    /**
196
     * Auto-configuration classes that should be applied before this one
197
     * @return classes to apply before this auto-configuration
198
     */
199
    Class<?>[] value() default {};
200
    
201
    /**
202
     * Names of auto-configuration classes that should be applied before this one
203
     * @return class names to apply before this auto-configuration
204
     */
205
    String[] name() default {};
206
}
207

208
/**
209
 * Specifies that an auto-configuration should be applied before specific classes
210
 */
211
@Target(ElementType.TYPE)
212
@Retention(RetentionPolicy.RUNTIME)
213
@Documented
214
public @interface AutoConfigureBefore {
215
    /**
216
     * Auto-configuration classes that should be applied after this one
217
     * @return classes to apply after this auto-configuration
218
     */
219
    Class<?>[] value() default {};
220
    
221
    /**
222
     * Names of auto-configuration classes that should be applied after this one
223
     * @return class names to apply after this auto-configuration
224
     */
225
    String[] name() default {};
226
}
227

228
/**
229
 * Defines explicit ordering for auto-configuration classes
230
 */
231
@Target(ElementType.TYPE)
232
@Retention(RetentionPolicy.RUNTIME)
233
@Documented
234
public @interface AutoConfigureOrder {
235
    /**
236
     * The order value - lower values have higher priority
237
     * @return the order value
238
     */
239
    int value();
240
}
241
```
242

243
### @ImportAutoConfiguration Annotation
244

245
Import and apply specific auto-configuration classes, useful for selective configuration and testing scenarios.
246

247
```java { .api }
248
/**
249
 * Import and apply the specified auto-configuration classes
250
 * Applies same ordering rules as @EnableAutoConfiguration but restricts to specified set
251
 */
252
@Target(ElementType.TYPE)
253
@Retention(RetentionPolicy.RUNTIME)
254
@Documented
255
@Inherited
256
@Import(ImportAutoConfigurationImportSelector.class)
257
public @interface ImportAutoConfiguration {
258
    /**
259
     * The auto-configuration classes that should be imported (alias for classes)
260
     * @return the classes to import
261
     */
262
    @AliasFor("classes")
263
    Class<?>[] value() default {};
264
    
265
    /**
266
     * The auto-configuration classes that should be imported
267
     * When empty, classes specified using META-INF/spring/*.imports files
268
     * @return the classes to import
269
     */
270
    @AliasFor("value")
271
    Class<?>[] classes() default {};
272
    
273
    /**
274
     * Exclude specific auto-configuration classes
275
     * @return the classes to exclude
276
     */
277
    Class<?>[] exclude() default {};
278
}
279
```
280

281
**Usage Examples:**
282

283
```java
284
// Import specific auto-configurations for testing
285
@TestConfiguration
286
@ImportAutoConfiguration({DataSourceAutoConfiguration.class, JpaAutoConfiguration.class})
287
public class TestConfig {
288
    // Only imports specified auto-configurations
289
}
290

291
// Import with exclusions
292
@ImportAutoConfiguration(value = {WebMvcAutoConfiguration.class}, exclude = {ErrorMvcAutoConfiguration.class})
293
public class CustomWebConfig {
294
    // Imports web config but excludes error handling
295
}
296
```
297

298
### @AutoConfigurationPackage Annotation
299

300
Registers packages for auto-configuration scanning and processing.
301

302
```java { .api }
303
/**
304
 * Registers packages for auto-configuration scanning
305
 * Automatically applied by @EnableAutoConfiguration
306
 */
307
@Target(ElementType.TYPE)
308
@Retention(RetentionPolicy.RUNTIME)
309
@Documented
310
@Inherited
311
@Import(AutoConfigurationPackages.Registrar.class)
312
public @interface AutoConfigurationPackage {
313
    /**
314
     * Base packages to register for auto-configuration
315
     * @return base packages to register
316
     */
317
    String[] basePackages() default {};
318
    
319
    /**
320
     * Type-safe alternative to basePackages
321
     * @return base package classes to register
322
     */
323
    Class<?>[] basePackageClasses() default {};
324
}
325
```
326

327
### AutoConfigurationImportSelector
328

329
The core class responsible for selecting which auto-configuration classes to import.
330

331
```java { .api }
332
/**
333
 * ImportSelector implementation that determines which auto-configuration classes to import
334
 * This class is responsible for loading auto-configuration metadata and applying conditional logic
335
 */
336
public class AutoConfigurationImportSelector implements DeferredImportSelector, BeanClassLoaderAware, 
337
        ResourceLoaderAware, BeanFactoryAware, EnvironmentAware, Ordered {
338
    
339
    /**
340
     * Select imports based on annotation metadata and environment conditions
341
     * @param annotationMetadata metadata of the importing class
342
     * @return array of class names to import
343
     */
344
    public String[] selectImports(AnnotationMetadata annotationMetadata);
345
    
346
    /**
347
     * Get auto-configuration class names from all spring.factories files
348
     * @return list of auto-configuration class names
349
     */
350
    protected List<String> getCandidateConfigurations(AnnotationMetadata metadata, AnnotationAttributes attributes);
351
    
352
    /**
353
     * Remove duplicate auto-configuration classes
354
     * @param configurations list of configuration class names
355
     * @return list with duplicates removed
356
     */
357
    protected final List<String> removeDuplicates(List<String> configurations);
358
    
359
    /**
360
     * Get exclusions based on annotation attributes and environment properties
361
     * @param metadata annotation metadata
362
     * @param attributes EnableAutoConfiguration attributes
363
     * @return set of class names to exclude
364
     */
365
    protected Set<String> getExclusions(AnnotationMetadata metadata, AnnotationAttributes attributes);
366
}
367
```
368

369
### AutoConfigurationPackages Utility
370

371
Utility class for registering and accessing auto-configuration packages.
372

373
```java { .api }
374
/**
375
 * Utility for registering and accessing auto-configuration packages
376
 * Used to determine which packages should be scanned for components
377
 */
378
public abstract class AutoConfigurationPackages {
379
    
380
    /**
381
     * Get the auto-configuration packages for the given bean factory
382
     * @param beanFactory the bean factory to query
383
     * @return list of package names
384
     */
385
    public static List<String> get(BeanFactory beanFactory);
386
    
387
    /**
388
     * Check if auto-configuration packages have been registered
389
     * @param beanFactory the bean factory to check
390
     * @return true if packages are registered
391
     */
392
    public static boolean has(BeanFactory beanFactory);
393
    
394
    /**
395
     * Register auto-configuration packages with the given registry
396
     * @param registry the bean definition registry
397
     * @param packageNames the package names to register
398
     */
399
    public static void register(BeanDefinitionRegistry registry, String... packageNames);
400
    
401
    /**
402
     * Register auto-configuration packages using class package names
403
     * @param registry the bean definition registry
404
     * @param packageClasses classes whose packages should be registered
405
     */
406
    public static void register(BeanDefinitionRegistry registry, Class<?>... packageClasses);
407
}
408
```
409

410
### AutoConfigurations Collection
411

412
Collection class for grouping related auto-configuration classes.
413

414
```java { .api }
415
/**
416
 * Collection of auto-configuration classes that can be imported
417
 * Provides a convenient way to group and reference related auto-configurations
418
 */
419
public final class AutoConfigurations extends Configurations {
420
    
421
    /**
422
     * Create AutoConfigurations from the specified classes
423
     * @param classes the auto-configuration classes
424
     * @return AutoConfigurations instance
425
     */
426
    public static AutoConfigurations of(Class<?>... classes);
427
    
428
    /**
429
     * Get the configuration classes
430
     * @return collection of configuration classes
431
     */
432
    public Collection<Class<?>> getClasses();
433
    
434
    /**
435
     * Merge with other configurations
436
     * @param other other configurations to merge
437
     * @return merged configurations
438
     */
439
    protected AutoConfigurations merge(Set<Class<?>> mergedClasses);
440
}
441
```
442

443
## Usage Examples
444

445
### Custom Auto-Configuration Class
446

447
```java
448
@AutoConfiguration
449
@ConditionalOnClass(MyService.class)
450
@ConditionalOnMissingBean(MyService.class)
451
public class MyServiceAutoConfiguration {
452
    
453
    @Bean
454
    @ConditionalOnMissingBean
455
    public MyService myService(MyServiceProperties properties) {
456
        return new MyService(properties.getApiKey());
457
    }
458
    
459
    @Bean
460
    @ConditionalOnMissingBean
461
    public MyServiceProperties myServiceProperties() {
462
        return new MyServiceProperties();
463
    }
464
}
465

466
@ConfigurationProperties(prefix = "myservice")
467
public class MyServiceProperties {
468
    private String apiKey;
469
    // getters and setters
470
}
471
```
472

473
### Excluding Auto-Configurations
474

475
```java
476
// Using @SpringBootApplication
477
@SpringBootApplication(exclude = {DataSourceAutoConfiguration.class, JmsAutoConfiguration.class})
478
public class MyApplication {
479
    // Auto-configurations excluded at annotation level
480
}
481

482
// Using properties
483
# application.properties
484
spring.autoconfigure.exclude=org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration,\
485
  org.springframework.boot.autoconfigure.jms.JmsAutoConfiguration
486
```
487

488
### Conditional Auto-Configuration
489

490
```java
491
@AutoConfiguration
492
@ConditionalOnClass({DataSource.class, JdbcTemplate.class})
493
@ConditionalOnProperty(prefix = "app.database", name = "enabled", havingValue = "true", matchIfMissing = true)
494
@AutoConfigureAfter(DataSourceAutoConfiguration.class)
495
public class CustomDatabaseAutoConfiguration {
496
    
497
    @Bean
498
    @ConditionalOnMissingBean
499
    public DatabaseService databaseService(JdbcTemplate jdbcTemplate) {
500
        return new DatabaseService(jdbcTemplate);
501
    }
502
}
503
```