0
# Auto-Configuration System
1

2
Spring Boot's intelligent automatic configuration system that provides convention-over-configuration setup based on classpath detection and conditional logic.
3

4
## Capabilities
5

6
### Core Auto-Configuration Annotations
7

8
Enable and control Spring Boot's auto-configuration mechanism.
9

10
```java { .api }
11
/**
12
 * Enable auto-configuration of the Spring Application Context, attempting 
13
 * to guess and configure beans that you are likely to need
14
 */
15
@Target(ElementType.TYPE)
16
@Retention(RetentionPolicy.RUNTIME)
17
@interface EnableAutoConfiguration {
18
    /**
19
     * Exclude specific auto-configuration classes that should not be applied
20
     * @return the classes to exclude
21
     */
22
    Class<?>[] exclude() default {};
23
    
24
    /**
25
     * Exclude specific auto-configuration class names that should not be applied
26
     * @return the class names to exclude  
27
     */
28
    String[] excludeName() default {};
29
}
30

31
/**
32
 * Indicates that a class provides configuration that can be automatically applied
33
 */
34
@Target(ElementType.TYPE)
35
@Retention(RetentionPolicy.RUNTIME)
36
@interface AutoConfiguration {
37
    /**
38
     * Auto-configuration classes that should be applied after this one
39
     * @return the after classes
40
     */
41
    String[] after() default {};
42
    
43
    /**
44
     * Auto-configuration classes that should be applied before this one  
45
     * @return the before classes
46
     */
47
    String[] before() default {};
48
    
49
    /**
50
     * Auto-configuration class names that should be applied after this one
51
     * @return the after class names
52
     */
53
    Class<?>[] afterName() default {};
54
    
55
    /**
56
     * Auto-configuration class names that should be applied before this one
57
     * @return the before class names
58
     */
59
    Class<?>[] beforeName() default {};
60
}
61

62
/**
63
 * Import and apply the specified auto-configuration classes
64
 */
65
@Target(ElementType.TYPE)
66
@Retention(RetentionPolicy.RUNTIME)  
67
@interface ImportAutoConfiguration {
68
    /**
69
     * The auto-configuration classes that should be imported
70
     * @return the classes to import
71
     */
72
    Class<?>[] value() default {};
73
    
74
    /**
75
     * The auto-configuration classes that should be imported
76
     * @return the classes to import
77
     */
78
    Class<?>[] classes() default {};
79
    
80
    /**
81
     * Exclude specific auto-configuration classes from being imported
82
     * @return the classes to exclude
83
     */
84
    Class<?>[] exclude() default {};
85
}
86
```
87

88
### Auto-Configuration Ordering
89

90
Control the order in which auto-configuration classes are applied.
91

92
```java { .api }
93
/**
94
 * Hint for that an auto-configuration should be applied after other specified classes
95
 */
96
@Target({ElementType.TYPE})
97
@Retention(RetentionPolicy.RUNTIME)
98
@interface AutoConfigureAfter {
99
    /**
100
     * The auto-configuration classes that should be applied before this one
101
     * @return the classes that should be applied first
102
     */
103
    Class<?>[] value() default {};
104
    
105
    /**
106
     * The names of the auto-configuration classes that should be applied before this one
107
     * @return the class names that should be applied first
108
     */
109
    String[] name() default {};
110
}
111

112
/**
113
 * Hint for that an auto-configuration should be applied before other specified classes
114
 */
115
@Target({ElementType.TYPE})
116
@Retention(RetentionPolicy.RUNTIME)
117
@interface AutoConfigureBefore {
118
    /**
119
     * The auto-configuration classes that should be applied after this one
120
     * @return the classes that should be applied after
121
     */
122
    Class<?>[] value() default {};
123
    
124
    /**
125
     * The names of the auto-configuration classes that should be applied after this one
126
     * @return the class names that should be applied after
127
     */
128
    String[] name() default {};
129
}
130

131
/**
132
 * Auto-configuration specific variant of Spring's @Order annotation
133
 */
134
@Target({ElementType.TYPE, ElementType.METHOD})
135
@Retention(RetentionPolicy.RUNTIME)
136
@interface AutoConfigureOrder {
137
    /**
138
     * The order value for this auto-configuration
139
     * @return the order value
140
     */
141
    int value() default Ordered.LOWEST_PRECEDENCE;
142
}
143
```
144

145
### Conditional Configuration Annotations
146

147
Conditional annotations that control when auto-configuration classes are applied.
148

149
#### Bean-Based Conditionals
150

151
```java { .api }
152
/**
153
 * Conditional that only matches when beans meeting the specified requirements are already present
154
 */
155
@Target({ElementType.TYPE, ElementType.METHOD})
156
@Retention(RetentionPolicy.RUNTIME)
157
@interface ConditionalOnBean {
158
    /**
159
     * The class types of beans that should be checked
160
     * @return the class types to check
161
     */
162
    Class<?>[] value() default {};
163
    
164
    /**
165
     * The class type names of beans that should be checked
166
     * @return the class type names to check  
167
     */
168
    String[] type() default {};
169
    
170
    /**
171
     * The annotation types that should be checked
172
     * @return the annotation types to check
173
     */
174
    Class<? extends Annotation>[] annotation() default {};
175
    
176
    /**
177
     * The names of beans to check
178
     * @return the bean names to check
179
     */
180
    String[] name() default {};
181
    
182
    /**
183
     * Strategy to decide if the application context hierarchy should be considered
184
     * @return the search strategy
185
     */
186
    SearchStrategy search() default SearchStrategy.ALL;
187
}
188

189
/**
190
 * Conditional that only matches when no beans meeting the specified requirements are already present
191
 */
192
@Target({ElementType.TYPE, ElementType.METHOD})
193
@Retention(RetentionPolicy.RUNTIME)
194
@interface ConditionalOnMissingBean {
195
    /**
196
     * The class types of beans that should be checked
197
     * @return the class types to check
198
     */
199
    Class<?>[] value() default {};
200
    
201
    /**
202
     * The class type names of beans that should be checked
203
     * @return the class type names to check
204
     */
205
    String[] type() default {};
206
    
207
    /**
208
     * The annotation types that should be checked  
209
     * @return the annotation types to check
210
     */
211
    Class<? extends Annotation>[] annotation() default {};
212
    
213
    /**
214
     * The names of beans to check
215
     * @return the bean names to check
216
     */
217
    String[] name() default {};
218
    
219
    /**
220
     * Strategy to decide if the application context hierarchy should be considered
221
     * @return the search strategy
222
     */
223
    SearchStrategy search() default SearchStrategy.ALL;
224
    
225
    /**
226
     * Additional classes that may contain the specified bean types within their generic parameters
227
     * @return the parameterized container classes
228
     */
229
    Class<?>[] parameterizedContainer() default {};
230
}
231
```
232

233
#### Class-Based Conditionals
234

235
```java { .api }
236
/**
237
 * Conditional that only matches when the specified classes are on the classpath
238
 */
239
@Target({ElementType.TYPE, ElementType.METHOD})
240
@Retention(RetentionPolicy.RUNTIME)
241
@interface ConditionalOnClass {
242
    /**
243
     * The classes that must be present  
244
     * @return the classes that must be present
245
     */
246
    Class<?>[] value() default {};
247
    
248
    /**
249
     * The class names that must be present
250
     * @return the class names that must be present
251
     */
252
    String[] name() default {};
253
}
254

255
/**
256
 * Conditional that only matches when the specified classes are not on the classpath
257
 */
258
@Target({ElementType.TYPE, ElementType.METHOD})
259
@Retention(RetentionPolicy.RUNTIME)
260
@interface ConditionalOnMissingClass {
261
    /**
262
     * The class names that must not be present
263
     * @return the class names that must not be present
264
     */
265
    String[] value() default {};
266
}
267
```
268

269
#### Property-Based Conditionals
270

271
```java { .api }
272
/**
273
 * Conditional that checks if the specified properties have a specific value
274
 */
275
@Target({ElementType.TYPE, ElementType.METHOD})
276
@Retention(RetentionPolicy.RUNTIME)
277
@interface ConditionalOnProperty {
278
    /**
279
     * Alias for name()
280
     * @return the property names to check
281
     */
282
    String[] value() default {};
283
    
284
    /**
285
     * A prefix that should be applied to each property
286
     * @return the prefix to apply
287
     */
288
    String prefix() default "";
289
    
290
    /**
291
     * The name of the properties to test
292
     * @return the property names to test
293
     */
294
    String[] name() default {};
295
    
296
    /**
297
     * The string representation of the expected value for the properties
298
     * @return the expected value
299
     */
300
    String havingValue() default "";
301
    
302
    /**
303
     * Specify if the condition should match if the property is not set
304
     * @return whether to match if missing
305
     */
306
    boolean matchIfMissing() default false;
307
}
308
```
309

310
#### Environment & Web Application Conditionals
311

312
```java { .api }
313
/**
314
 * Conditional that only matches when the application is a web application
315
 */
316
@Target({ElementType.TYPE, ElementType.METHOD})
317
@Retention(RetentionPolicy.RUNTIME)
318
@interface ConditionalOnWebApplication {
319
    /**
320
     * The required type of the web application
321
     * @return the required web application type
322
     */
323
    Type type() default Type.ANY;
324
    
325
    /**
326
     * Available application types
327
     */
328
    enum Type {
329
        /**
330
         * Any web application will match
331
         */
332
        ANY,
333
        
334
        /**
335
         * Only servlet-based web applications will match
336
         */
337
        SERVLET,
338
        
339
        /**
340
         * Only reactive web applications will match  
341
         */
342
        REACTIVE
343
    }
344
}
345

346
/**
347
 * Conditional that only matches when the application is not a web application
348
 */
349
@Target({ElementType.TYPE, ElementType.METHOD})
350
@Retention(RetentionPolicy.RUNTIME)
351
@interface ConditionalOnNotWebApplication {
352
}
353

354
/**
355
 * Conditional that matches based on the JVM version the application is running on
356
 */
357
@Target({ElementType.TYPE, ElementType.METHOD})
358
@Retention(RetentionPolicy.RUNTIME)
359
@interface ConditionalOnJava {
360
    /**
361
     * Configures the comparison with the specified Java version
362
     * @return the comparison range
363
     */
364
    Range range() default Range.EQUAL_OR_NEWER;
365
    
366
    /**
367
     * The Java version to check for
368
     * @return the java version
369
     */
370
    JavaVersion value();
371
    
372
    /**
373
     * Range options for Java version checks
374
     */
375
    enum Range {
376
        /**
377
         * Equal to, or newer than the specified version
378
         */
379
        EQUAL_OR_NEWER,
380
        
381
        /**
382
         * Older than the specified version
383
         */
384
        OLDER_THAN
385
    }
386
}
387

388
/**
389
 * Conditional that only matches when the specified resources are on the classpath  
390
 */
391
@Target({ElementType.TYPE, ElementType.METHOD})
392
@Retention(RetentionPolicy.RUNTIME)
393
@interface ConditionalOnResource {
394
    /**
395
     * The resources that must be present
396
     * @return the resources that must be present
397
     */
398
    String[] resources() default {};
399
}
400
```
401

402
### Package Management
403

404
Manage packages for auto-configuration scanning.
405

406
```java { .api }
407
/**
408
 * Indicates that the package containing the annotated class should be registered with AutoConfigurationPackages
409
 */
410
@Target(ElementType.TYPE)
411
@Retention(RetentionPolicy.RUNTIME)
412
@interface AutoConfigurationPackage {
413
    /**
414
     * Base packages to scan
415
     * @return the base packages
416
     */
417
    String[] basePackages() default {};
418
    
419
    /**
420
     * Base package classes to scan
421
     * @return the base package classes
422
     */
423
    Class<?>[] basePackageClasses() default {};
424
}
425

426
/**
427
 * Class for storing auto-configuration packages for reference later
428
 */
429
public abstract class AutoConfigurationPackages {
430
    /**
431
     * Return the auto-configuration base packages for the given bean factory
432
     * @param beanFactory the source bean factory
433
     * @return a list of auto-configuration packages
434
     */
435
    public static List<String> get(BeanFactory beanFactory);
436
    
437
    /**
438
     * Determine if auto-configuration base packages are available for the given bean factory
439
     * @param beanFactory the source bean factory
440
     * @return true if packages are available
441
     */
442
    public static boolean has(BeanFactory beanFactory);
443
    
444
    /**
445
     * Register the specified auto-configuration package names
446
     * @param registry the source registry
447
     * @param packageNames the package names to register
448
     */
449
    public static void register(BeanDefinitionRegistry registry, String... packageNames);
450
}
451
```
452

453
**Usage Examples:**
454

455
```java
456
// Basic auto-configuration class
457
@AutoConfiguration
458
@ConditionalOnClass(DataSource.class)
459
@ConditionalOnMissingBean(DataSource.class)
460
@EnableConfigurationProperties(DataSourceProperties.class)
461
public class DataSourceAutoConfiguration {
462
    
463
    @Bean
464
    @ConditionalOnProperty(prefix = "spring.datasource", name = "url")
465
    public DataSource dataSource(DataSourceProperties properties) {
466
        return DataSourceBuilder.create()
467
            .url(properties.getUrl())
468
            .username(properties.getUsername())
469
            .password(properties.getPassword())
470
            .build();
471
    }
472
}
473

474
// Conditional configuration based on properties
475
@Configuration
476
@ConditionalOnProperty(
477
    prefix = "app.feature", 
478
    name = "enabled", 
479
    havingValue = "true", 
480
    matchIfMissing = false
481
)
482
public class FeatureConfiguration {
483
    
484
    @Bean
485
    @ConditionalOnMissingBean  
486
    public FeatureService featureService() {
487
        return new DefaultFeatureService();
488
    }
489
}
490

491
// Web application conditional configuration
492
@Configuration
493
@ConditionalOnWebApplication(type = ConditionalOnWebApplication.Type.SERVLET)
494
@ConditionalOnClass(DispatcherServlet.class)
495
public class WebMvcAutoConfiguration {
496
    
497
    @Bean
498
    @ConditionalOnMissingBean(ViewResolver.class)
499
    public InternalResourceViewResolver viewResolver() {
500
        return new InternalResourceViewResolver();
501
    }
502
}
503
```