0
# Configuration Properties
1

2
Environment abstraction and property source management providing comprehensive configuration capabilities including profiles, property resolution, and type-safe configuration binding. This includes @ConfigurationProperties, Environment interfaces, and property source hierarchies.
3

4
## Capabilities
5

6
### Environment Interfaces
7

8
```java { .api }
9
/**
10
 * Interface representing the environment in which the current application is running.
11
 */
12
public interface Environment extends PropertyResolver {
13
    /**
14
     * Return the set of profiles explicitly made active for this environment.
15
     * @return the set of active profiles
16
     */
17
    String[] getActiveProfiles();
18
    
19
    /**
20
     * Return the set of profiles to be active by default when no active profiles have been set explicitly.
21
     * @return the set of default profiles
22
     */
23
    String[] getDefaultProfiles();
24
    
25
    /**
26
     * Return whether one or more of the given profiles is active or, in the case of no explicit active profiles, whether one or more of the given profiles is included in the set of default profiles.
27
     * @param profiles the profiles to test
28
     * @return whether the given profiles match
29
     */
30
    boolean acceptsProfiles(Profiles profiles);
31
}
32

33
/**
34
 * Configuration interface to be implemented by most if not all Environment types.
35
 */
36
public interface ConfigurableEnvironment extends Environment, ConfigurablePropertyResolver {
37
    /**
38
     * Specify the set of profiles active for this Environment.
39
     * @param profiles the set of active profile names
40
     */
41
    void setActiveProfiles(String... profiles);
42
    
43
    /**
44
     * Add a profile to the current set of active profiles.
45
     * @param profile the profile to add to the current set of active profiles
46
     */
47
    void addActiveProfile(String profile);
48
    
49
    /**
50
     * Specify the set of profiles to be made active by default if no other profiles are explicitly made active through setActiveProfiles(String...).
51
     * @param profiles the set of default profile names
52
     */
53
    void setDefaultProfiles(String... profiles);
54
    
55
    /**
56
     * Return the PropertySources for this Environment in mutable form.
57
     * @return the PropertySources
58
     */
59
    MutablePropertySources getPropertySources();
60
    
61
    /**
62
     * Return the value of System.getProperties() if allowed by the current SecurityManager, otherwise return a map implementation that will attempt to access individual keys using calls to System.getProperty(String).
63
     * @return the system properties
64
     */
65
    Map<String, Object> getSystemProperties();
66
    
67
    /**
68
     * Return the value of System.getenv() if allowed by the current SecurityManager, otherwise return a map implementation that will attempt to access individual keys using calls to System.getenv(String).
69
     * @return the system environment
70
     */
71
    Map<String, Object> getSystemEnvironment();
72
    
73
    /**
74
     * Append the given parent environment's active profiles, default profiles and property sources to this (child) environment's respective collections.
75
     * @param parent the environment to merge with
76
     */
77
    void merge(ConfigurableEnvironment parent);
78
}
79

80
/**
81
 * Interface for resolving properties against any underlying source.
82
 */
83
public interface PropertyResolver {
84
    /**
85
     * Return whether the given property key is available for resolution.
86
     * @param key the property name to resolve
87
     * @return whether the given property key is available for resolution
88
     */
89
    boolean containsProperty(String key);
90
    
91
    /**
92
     * Return the property value associated with the given key, or null if the key cannot be resolved.
93
     * @param key the property name to resolve
94
     * @return the property value or null
95
     */
96
    String getProperty(String key);
97
    
98
    /**
99
     * Return the property value associated with the given key, or defaultValue if the key cannot be resolved.
100
     * @param key the property name to resolve
101
     * @param defaultValue the default value to return if no value is found
102
     * @return the property value or defaultValue
103
     */
104
    String getProperty(String key, String defaultValue);
105
    
106
    /**
107
     * Return the property value associated with the given key, or null if the key cannot be resolved.
108
     * @param key the property name to resolve
109
     * @param targetType the expected type of the property value
110
     * @return the property value or null
111
     */
112
    <T> T getProperty(String key, Class<T> targetType);
113
    
114
    /**
115
     * Return the property value associated with the given key, or defaultValue if the key cannot be resolved.
116
     * @param key the property name to resolve
117
     * @param targetType the expected type of the property value
118
     * @param defaultValue the default value to return if no value is found
119
     * @return the property value or defaultValue
120
     */
121
    <T> T getProperty(String key, Class<T> targetType, T defaultValue);
122
    
123
    /**
124
     * Return the property value associated with the given key (never null).
125
     * @param key the property name to resolve
126
     * @return the property value
127
     * @throws IllegalStateException if the key cannot be resolved
128
     */
129
    String getRequiredProperty(String key) throws IllegalStateException;
130
    
131
    /**
132
     * Return the property value associated with the given key, converted to the given targetType (never null).
133
     * @param key the property name to resolve
134
     * @param targetType the expected type of the property value
135
     * @return the property value
136
     * @throws IllegalStateException if the given key cannot be resolved
137
     */
138
    <T> T getRequiredProperty(String key, Class<T> targetType) throws IllegalStateException;
139
    
140
    /**
141
     * Resolve ${...} placeholders in the given text, replacing them with corresponding property values as resolved by getProperty(String).
142
     * @param text the String to resolve
143
     * @return the resolved String (never null)
144
     * @throws IllegalArgumentException if given text is null or if any placeholders are unresolvable
145
     */
146
    String resolvePlaceholders(String text);
147
    
148
    /**
149
     * Resolve ${...} placeholders in the given text, replacing them with corresponding property values as resolved by getProperty(String).
150
     * @param text the String to resolve
151
     * @return the resolved String (never null)
152
     * @throws IllegalArgumentException if given text is null
153
     */
154
    String resolveRequiredPlaceholders(String text) throws IllegalArgumentException;
155
}
156
```
157

158
### Configuration Properties Annotation
159

160
```java { .api }
161
/**
162
 * Annotation for externalized configuration.
163
 */
164
@Target({ElementType.TYPE, ElementType.METHOD})
165
@Retention(RetentionPolicy.RUNTIME)
166
public @interface ConfigurationProperties {
167
    /**
168
     * The name prefix of the properties that are valid to bind to this object.
169
     * @return the name prefix of the properties to bind
170
     */
171
    @AliasFor("prefix")
172
    String value() default "";
173
    
174
    /**
175
     * The name prefix of the properties that are valid to bind to this object.
176
     * @return the name prefix of the properties to bind
177
     */
178
    @AliasFor("value")
179
    String prefix() default "";
180
    
181
    /**
182
     * Flag to indicate that when binding to this object invalid fields should be ignored.
183
     * @return flag to indicate that invalid fields should be ignored
184
     */
185
    boolean ignoreInvalidFields() default false;
186
    
187
    /**
188
     * Flag to indicate that when binding to this object unknown fields should be ignored.
189
     * @return flag to indicate that unknown fields should be ignored
190
     */
191
    boolean ignoreUnknownFields() default true;
192
}
193

194
/**
195
 * Enables support for @ConfigurationProperties annotated classes.
196
 */
197
@Target(ElementType.TYPE)
198
@Retention(RetentionPolicy.RUNTIME)
199
@Import(EnableConfigurationPropertiesRegistrar.class)
200
public @interface EnableConfigurationProperties {
201
    /**
202
     * The bean name of the configuration properties validator.
203
     * @return the validator bean name
204
     */
205
    String VALIDATOR_BEAN_NAME = "configurationPropertiesValidator";
206
    
207
    /**
208
     * Convenient way to quickly register @ConfigurationProperties annotated beans with Spring.
209
     * @return the configuration properties classes to register
210
     */
211
    Class<?>[] value() default {};
212
}
213
```
214

215
### Property Sources
216

217
```java { .api }
218
/**
219
 * Abstract base class for PropertySource implementations.
220
 */
221
public abstract class PropertySource<T> {
222
    /** The name of this PropertySource */
223
    protected final String name;
224
    
225
    /** The underlying source object */
226
    protected final T source;
227
    
228
    /**
229
     * Create a new PropertySource with the given name and source object.
230
     * @param name the associated name
231
     * @param source the source object
232
     */
233
    public PropertySource(String name, T source) {}
234
    
235
    /**
236
     * Return the name of this PropertySource.
237
     * @return the name of this PropertySource
238
     */
239
    public String getName() {}
240
    
241
    /**
242
     * Return the underlying source object for this PropertySource.
243
     * @return the underlying source object
244
     */
245
    public T getSource() {}
246
    
247
    /**
248
     * Return whether this PropertySource contains the given name.
249
     * @param name the property name to find
250
     * @return whether this PropertySource contains the given name
251
     */
252
    public boolean containsProperty(String name) {}
253
    
254
    /**
255
     * Return the value associated with the given name, or null if not found.
256
     * @param name the property to find
257
     * @return the associated value, or null if not found
258
     */
259
    public abstract Object getProperty(String name);
260
}
261

262
/**
263
 * Holder containing one or more PropertySource objects.
264
 */
265
public class MutablePropertySources implements PropertySources {
266
    private final List<PropertySource<?>> propertySourceList = new CopyOnWriteArrayList<>();
267
    
268
    /**
269
     * Create a new MutablePropertySources object.
270
     */
271
    public MutablePropertySources() {}
272
    
273
    /**
274
     * Create a new MutablePropertySources from the given propertySources object.
275
     * @param propertySources the PropertySources to copy from
276
     */
277
    public MutablePropertySources(PropertySources propertySources) {}
278
    
279
    /**
280
     * Add the given property source object with highest precedence.
281
     * @param propertySource the PropertySource to add
282
     */
283
    public void addFirst(PropertySource<?> propertySource) {}
284
    
285
    /**
286
     * Add the given property source object with lowest precedence.
287
     * @param propertySource the PropertySource to add
288
     */
289
    public void addLast(PropertySource<?> propertySource) {}
290
    
291
    /**
292
     * Add the given property source object with precedence immediately higher than the named relative property source.
293
     * @param propertySource the PropertySource to add
294
     * @param relativePropertySourceName the name of the existing property source that the new property source should be added before
295
     */
296
    public void addBefore(String relativePropertySourceName, PropertySource<?> propertySource) {}
297
    
298
    /**
299
     * Add the given property source object with precedence immediately lower than the named relative property source.
300
     * @param propertySource the PropertySource to add
301
     * @param relativePropertySourceName the name of the existing property source that the new property source should be added after
302
     */
303
    public void addAfter(String relativePropertySourceName, PropertySource<?> propertySource) {}
304
    
305
    /**
306
     * Return the precedence of the given property source, -1 if not found.
307
     * @param propertySource the PropertySource to find
308
     * @return the precedence of the given property source
309
     */
310
    public int precedenceOf(PropertySource<?> propertySource) {}
311
    
312
    /**
313
     * Remove and return the property source with the given name, null if not found.
314
     * @param name the name of the property source to remove
315
     * @return the removed PropertySource or null
316
     */
317
    public PropertySource<?> remove(String name) {}
318
    
319
    /**
320
     * Replace the property source with the given name with the given property source object.
321
     * @param name the name of the property source to replace
322
     * @param propertySource the replacement PropertySource
323
     */
324
    public void replace(String name, PropertySource<?> propertySource) {}
325
}
326
```
327

328
### Usage Examples
329

330
**Configuration Properties:**
331

332
```java
333
@ConfigurationProperties(prefix = "app")
334
@Component
335
public class ApplicationProperties {
336
    private String name;
337
    private String version;
338
    private Database database = new Database();
339
    private Security security = new Security();
340
    
341
    // Getters and setters
342
    
343
    public static class Database {
344
        private String url;
345
        private String username;
346
        private String password;
347
        private int maxConnections = 10;
348
        
349
        // Getters and setters
350
    }
351
    
352
    public static class Security {
353
        private boolean enabled = true;
354
        private List<String> allowedOrigins = new ArrayList<>();
355
        private Duration timeout = Duration.ofMinutes(30);
356
        
357
        // Getters and setters
358
    }
359
}
360

361
// application.properties:
362
// app.name=My Application
363
// app.version=1.0.0
364
// app.database.url=jdbc:mysql://localhost:3306/mydb
365
// app.database.username=user
366
// app.database.password=pass
367
// app.database.max-connections=20
368
// app.security.enabled=true
369
// app.security.allowed-origins=http://localhost:3000,http://localhost:4200
370
// app.security.timeout=PT45M
371

372
@Service
373
public class ConfigurationService {
374
    
375
    @Autowired
376
    private Environment environment;
377
    
378
    @Autowired
379
    private ApplicationProperties appProperties;
380
    
381
    public void printConfiguration() {
382
        // Using Environment
383
        String appName = environment.getProperty("app.name", "Default App");
384
        boolean debugMode = environment.getProperty("debug.mode", Boolean.class, false);
385
        
386
        // Using @ConfigurationProperties
387
        System.out.println("App: " + appProperties.getName());
388
        System.out.println("DB URL: " + appProperties.getDatabase().getUrl());
389
    }
390
}
391
```