0
# Configuration Management
1

2
Runtime configuration management including property rebinding, environment configuration, and validation of configuration properties. The management system provides mechanisms for dynamic configuration updates and comprehensive validation reporting.
3

4
## Capabilities
5

6
### Configuration Properties Environment Manager
7

8
Primary manager for handling configuration property rebinding and environment setup during runtime configuration changes.
9

10
```java { .api }
11
public class CasConfigurationPropertiesEnvironmentManager {
12
    /**
13
     * Constructor with configuration properties binding post processor.
14
     *
15
     * @param binder the configuration properties binding post processor
16
     */
17
    public CasConfigurationPropertiesEnvironmentManager(ConfigurationPropertiesBindingPostProcessor binder);
18
    
19
    /**
20
     * Rebind CAS configuration properties using instance binder.
21
     *
22
     * @param applicationContext the application context
23
     * @return the application context
24
     */
25
    public ApplicationContext rebindCasConfigurationProperties(ApplicationContext applicationContext);
26
}
27
```
28

29
### Static Configuration Management Methods
30

31
```java { .api }
32
public class CasConfigurationPropertiesEnvironmentManager {
33
    /**
34
     * Rebind CAS configuration properties using provided binder.
35
     *
36
     * @param binder             the configuration properties binding post processor
37
     * @param applicationContext the application context
38
     * @return the application context
39
     */
40
    public static ApplicationContext rebindCasConfigurationProperties(
41
        ConfigurationPropertiesBindingPostProcessor binder,
42
        ApplicationContext applicationContext);
43
    
44
    /**
45
     * Configure environment property sources with native composite source.
46
     *
47
     * @param environment the configurable environment
48
     * @return composite property source with native sources
49
     */
50
    public static CompositePropertySource configureEnvironmentPropertySources(ConfigurableEnvironment environment);
51
}
52
```
53

54
### Configuration Properties Validator
55

56
Comprehensive validation system for CAS configuration properties that reports unbound and invalid property configurations.
57

58
```java { .api }
59
public class CasConfigurationPropertiesValidator {
60
    /**
61
     * Constructor with application context.
62
     *
63
     * @param applicationContext the configurable application context
64
     */
65
    public CasConfigurationPropertiesValidator(ConfigurableApplicationContext applicationContext);
66
    
67
    /**
68
     * Validate CAS configuration properties and return validation results.
69
     *
70
     * @return list of validation error messages
71
     */
72
    public List<String> validate();
73
}
74
```
75

76
## Usage Examples
77

78
### Configuration Rebinding
79

80
```java
81
import org.apereo.cas.configuration.CasConfigurationPropertiesEnvironmentManager;
82
import org.springframework.boot.context.properties.ConfigurationPropertiesBindingPostProcessor;
83

84
// Get the binding post processor from application context
85
ConfigurationPropertiesBindingPostProcessor binder = 
86
    applicationContext.getBean(ConfigurationPropertiesBindingPostProcessor.class);
87

88
// Create environment manager
89
CasConfigurationPropertiesEnvironmentManager manager = 
90
    new CasConfigurationPropertiesEnvironmentManager(binder);
91

92
// Rebind configuration properties after changes
93
ApplicationContext updatedContext = manager.rebindCasConfigurationProperties(applicationContext);
94
```
95

96
### Static Configuration Rebinding
97

98
```java
99
// Static method approach for one-time rebinding
100
ApplicationContext updatedContext = CasConfigurationPropertiesEnvironmentManager
101
    .rebindCasConfigurationProperties(binder, applicationContext);
102

103
// Verify rebinding was successful
104
CasConfigurationProperties config = updatedContext.getBean(CasConfigurationProperties.class);
105
System.out.println("Configuration rebound: " + config.getClass().getName());
106
```
107

108
### Environment Property Sources Configuration
109

110
```java
111
import org.springframework.core.env.ConfigurableEnvironment;
112
import org.springframework.core.env.CompositePropertySource;
113

114
// Configure native property sources for environment
115
ConfigurableEnvironment environment = (ConfigurableEnvironment) applicationContext.getEnvironment();
116
CompositePropertySource nativeSource = CasConfigurationPropertiesEnvironmentManager
117
    .configureEnvironmentPropertySources(environment);
118

119
// Native source includes:
120
// - commandLineArgs (if present)
121
// - systemProperties
122
// - systemEnvironment
123
```
124

125
### Configuration Validation
126

127
```java
128
import org.apereo.cas.configuration.CasConfigurationPropertiesValidator;
129

130
// Create validator with application context
131
CasConfigurationPropertiesValidator validator = 
132
    new CasConfigurationPropertiesValidator(applicationContext);
133

134
// Validate all CAS configuration properties
135
List<String> validationResults = validator.validate();
136

137
if (validationResults.isEmpty()) {
138
    System.out.println("Configuration validation passed successfully");
139
} else {
140
    System.err.println("Configuration validation failed:");
141
    validationResults.forEach(System.err::println);
142
}
143
```
144

145
### Complete Configuration Management Workflow
146

147
```java
148
import org.apereo.cas.configuration.CasConfigurationPropertiesEnvironmentManager;
149
import org.apereo.cas.configuration.CasConfigurationPropertiesValidator;
150

151
// Step 1: Configure environment property sources
152
ConfigurableEnvironment environment = (ConfigurableEnvironment) applicationContext.getEnvironment();
153
CompositePropertySource nativeSource = CasConfigurationPropertiesEnvironmentManager
154
    .configureEnvironmentPropertySources(environment);
155

156
// Step 2: Rebind configuration properties
157
ConfigurationPropertiesBindingPostProcessor binder = 
158
    applicationContext.getBean(ConfigurationPropertiesBindingPostProcessor.class);
159
ApplicationContext updatedContext = CasConfigurationPropertiesEnvironmentManager
160
    .rebindCasConfigurationProperties(binder, applicationContext);
161

162
// Step 3: Validate configuration
163
CasConfigurationPropertiesValidator validator = 
164
    new CasConfigurationPropertiesValidator((ConfigurableApplicationContext) updatedContext);
165
List<String> validationResults = validator.validate();
166

167
// Step 4: Handle validation results
168
if (!validationResults.isEmpty()) {
169
    String errorMessage = String.join("\n", validationResults);
170
    System.err.println("Configuration validation errors:\n" + errorMessage);
171
    // Handle validation failures appropriately
172
}
173
```
174

175
## Configuration Management Process
176

177
### Property Rebinding Process
178

179
1. **Retrieve Configuration Bean**: Get existing `CasConfigurationProperties` bean from application context
180
2. **Create Bean Name**: Generate unique name using `CasConfigurationProperties.PREFIX` and class name
181
3. **Pre-Initialize**: Call `postProcessBeforeInitialization` on the configuration bean
182
4. **Initialize Bean**: Initialize the bean using application context's autowire capability
183
5. **Autowire Dependencies**: Autowire the bean to inject all dependencies
184
6. **Log Completion**: Log successful configuration reload
185

186
### Environment Property Source Configuration
187

188
The native composite property source includes these sources in order of precedence:
189

190
1. **Command Line Arguments** (`commandLineArgs`) - Highest precedence
191
2. **System Properties** (`systemProperties`) - JVM system properties
192
3. **System Environment** (`systemEnvironment`) - Operating system environment variables
193

194
### Configuration Validation Process
195

196
1. **Discover Configuration Beans**: Find all beans of type `CasConfigurationProperties` in application context
197
2. **Extract Property Sources**: Get all property sources from environment
198
3. **Create Binder**: Set up Spring Boot configuration binder with property sources and conversion service
199
4. **Validate Each Bean**: For each configuration bean:
200
   - Create `ConfigurationPropertiesBean` wrapper
201
   - Extract binding target and annotation information
202
   - Attempt to bind properties using `NoUnboundElementsBindHandler`
203
   - Collect any binding exceptions and unbound properties
204
5. **Generate Results**: Return list of validation error messages
205

206
### Validation Error Reporting
207

208
Validation errors include detailed information about:
209
- **Unbound Properties**: Properties that don't match any configuration binding
210
- **Property Origins**: Source location of problematic properties
211
- **Property Values**: Current values of unbound properties
212
- **Binding Errors**: Detailed error messages from Spring Boot binding process
213

214
## Constants
215

216
```java { .api }
217
/**
218
 * Default bean name for configuration properties environment manager.
219
 */
220
String BEAN_NAME = "configurationPropertiesEnvironmentManager";
221
```
222

223
## Error Handling
224

225
### Rebinding Error Handling
226

227
The rebinding process includes comprehensive error handling:
228
- Logs successful reloads with bean names
229
- Handles missing configuration beans gracefully
230
- Preserves application context state on failures
231

232
### Validation Error Handling
233

234
The validation system provides detailed error reporting:
235
- Catches and processes binding exceptions
236
- Extracts unbound configuration properties with origins
237
- Formats error messages with property names, values, and sources
238
- Continues validation even when individual beans fail
239

240
### Property Source Error Handling
241

242
Environment configuration handles missing property sources:
243
- Checks for existence of each property source before adding
244
- Uses `FunctionUtils.doIfNotNull` for safe null handling
245
- Gracefully handles missing command line arguments or system properties