0
# Property Source Location
1

2
Core functionality for locating and loading configuration properties from multiple sources with defined precedence order. The property source location system supports standalone files, configuration directories, classpath resources, system properties, environment variables, and Docker secrets integration.
3

4
## Capabilities
5

6
### Core Property Source Locator Interface
7

8
Primary interface for discovering configuration properties from various sources with defined precedence handling.
9

10
```java { .api }
11
@FunctionalInterface
12
public interface CasConfigurationPropertiesSourceLocator {
13
    /**
14
     * Locate property sources for CAS via the given environment and other resources.
15
     *
16
     * @param environment    the environment
17
     * @param resourceLoader the resource loader
18
     * @return the property source
19
     */
20
    Optional<PropertySource<?>> locate(Environment environment, ResourceLoader resourceLoader);
21
}
22
```
23

24
### Static Utility Methods
25

26
```java { .api }
27
public interface CasConfigurationPropertiesSourceLocator {
28
    /**
29
     * Gets standalone profile configuration directory.
30
     *
31
     * @param environment the environment
32
     * @return the standalone profile configuration directory
33
     */
34
    static File getStandaloneProfileConfigurationDirectory(Environment environment);
35
    
36
    /**
37
     * Gets standalone profile configuration file.
38
     *
39
     * @param environment the environment
40
     * @return the standalone profile configuration file
41
     */
42
    static File getStandaloneProfileConfigurationFile(Environment environment);
43
    
44
    /**
45
     * Gets application name.
46
     *
47
     * @param environment the environment
48
     * @return the application name
49
     */
50
    static String getApplicationName(Environment environment);
51
    
52
    /**
53
     * Gets configuration name.
54
     *
55
     * @param environment the environment
56
     * @return the configuration name
57
     */
58
    static String getConfigurationName(Environment environment);
59
    
60
    /**
61
     * Gets configuration properties loaders using ServiceLoader.
62
     *
63
     * @return the configuration properties loaders
64
     */
65
    static List<CasConfigurationPropertiesLoader> getConfigurationPropertiesLoaders();
66
}
67
```
68

69
### Default Property Source Locator
70

71
Standard implementation that locates properties from multiple sources with defined precedence order: system properties → configuration files → classpath resources.
72

73
```java { .api }
74
public class DefaultCasConfigurationPropertiesSourceLocator implements CasConfigurationPropertiesSourceLocator {
75
    /**
76
     * Constructor with cipher executor for encryption support.
77
     *
78
     * @param casConfigurationCipherExecutor the cipher executor
79
     */
80
    public DefaultCasConfigurationPropertiesSourceLocator(CipherExecutor<String, String> casConfigurationCipherExecutor);
81
    
82
    /**
83
     * Locate configuration property sources with precedence handling.
84
     *
85
     * @param environment    the environment
86
     * @param resourceLoader the resource loader
87
     * @return composite property source
88
     */
89
    @Override
90
    public Optional<PropertySource<?>> locate(Environment environment, ResourceLoader resourceLoader);
91
    
92
    /**
93
     * Load embedded properties from classpath resources.
94
     *
95
     * @param resourceLoader the resource loader
96
     * @param environment    the environment
97
     * @return the property source
98
     */
99
    protected PropertySource<?> loadEmbeddedProperties(ResourceLoader resourceLoader, Environment environment);
100
}
101
```
102

103
#### Usage Example
104

105
```java
106
import org.apereo.cas.configuration.DefaultCasConfigurationPropertiesSourceLocator;
107
import org.apereo.cas.configuration.support.CasConfigurationJasyptCipherExecutor;
108

109
// Create cipher executor
110
CasConfigurationJasyptCipherExecutor cipherExecutor = 
111
    new CasConfigurationJasyptCipherExecutor(environment);
112

113
// Create default locator
114
DefaultCasConfigurationPropertiesSourceLocator locator = 
115
    new DefaultCasConfigurationPropertiesSourceLocator(cipherExecutor);
116

117
// Locate properties with precedence handling
118
Optional<PropertySource<?>> properties = locator.locate(environment, resourceLoader);
119
```
120

121
### Standalone Configuration File Locator
122

123
High-precedence locator for standalone configuration files specified via environment properties.
124

125
```java { .api }
126
@Order(Ordered.HIGHEST_PRECEDENCE)
127
public class StandaloneConfigurationFilePropertiesSourceLocator implements CasConfigurationPropertiesSourceLocator {
128
    /**
129
     * Constructor with cipher executor.
130
     *
131
     * @param casConfigurationCipherExecutor the cipher executor
132
     */
133
    public StandaloneConfigurationFilePropertiesSourceLocator(CipherExecutor<String, String> casConfigurationCipherExecutor);
134
    
135
    /**
136
     * Locate standalone configuration file properties.
137
     *
138
     * @param environment    the environment
139
     * @param resourceLoader the resource loader
140
     * @return the property source if standalone file exists
141
     */
142
    @Override
143
    public Optional<PropertySource<?>> locate(Environment environment, ResourceLoader resourceLoader);
144
}
145
```
146

147
#### Usage Example
148

149
```java
150
// Create standalone file locator (highest precedence)
151
StandaloneConfigurationFilePropertiesSourceLocator standaloneLocator = 
152
    new StandaloneConfigurationFilePropertiesSourceLocator(cipherExecutor);
153

154
// Will only return properties if cas.standalone.configuration-file is set
155
Optional<PropertySource<?>> standaloneProps = standaloneLocator.locate(environment, resourceLoader);
156
```
157

158
### Docker Secrets Property Source Locator
159

160
Locator for Docker secrets when running in containerized environments.
161

162
```java { .api }
163
public class DockerSecretsPropertySourceLocator implements CasConfigurationPropertiesSourceLocator {
164
    /**
165
     * Locate Docker secrets as property source.
166
     *
167
     * @param environment    the environment
168
     * @param resourceLoader the resource loader
169
     * @return property source with secrets
170
     */
171
    @Override
172
    public Optional<PropertySource<?>> locate(Environment environment, ResourceLoader resourceLoader);
173
    
174
    /**
175
     * Load all Docker secrets from secrets directory.
176
     *
177
     * @return map of secret names and values
178
     */
179
    protected Map<String, Object> loadSecrets();
180
}
181
```
182

183
#### Usage Example
184

185
```java
186
// Set environment variable to enable Docker secrets
187
System.setProperty("CONTAINER", "true");
188

189
// Create Docker secrets locator
190
DockerSecretsPropertySourceLocator dockerLocator = new DockerSecretsPropertySourceLocator();
191

192
// Load secrets from /run/secrets/ directory
193
Optional<PropertySource<?>> dockerSecrets = dockerLocator.locate(environment, resourceLoader);
194
```
195

196
### Configuration File Discovery
197

198
The system automatically discovers configuration files based on application name, configuration name, active profiles, and file extensions.
199

200
#### File Discovery Pattern
201

202
```java
203
// Base configuration files (in order of precedence)
204
String[] baseFiles = {
205
    "application.yml", "application.yaml", "application.properties",
206
    "cas.yml", "cas.yaml", "cas.properties",
207
    "CAS.yml", "CAS.yaml", "CAS.properties"
208
};
209

210
// Profile-specific files
211
String[] profilePatterns = {
212
    "application-{profile}.{extension}",
213
    "{profile}.{extension}",
214
    "{appName}-{profile}.{extension}"
215
};
216
```
217

218
#### Supported File Extensions
219

220
- `.yml` - YAML format (highest precedence)
221
- `.yaml` - YAML format  
222
- `.properties` - Java Properties format
223
- `.groovy` - Groovy configuration scripts
224

225
## Constants
226

227
```java { .api }
228
// Bean name for bootstrap property locator
229
String BOOTSTRAP_PROPERTY_LOCATOR_BEAN_NAME = "casCoreBootstrapPropertySourceLocator";
230

231
// Property names for configuration paths
232
String PROPERTY_CAS_STANDALONE_CONFIGURATION_FILE = "cas.standalone.configuration-file";
233
String PROPERTY_CAS_STANDALONE_CONFIGURATION_DIRECTORY = "cas.standalone.configuration-directory";
234

235
// Default configuration directories (checked in order)
236
List<File> DEFAULT_CAS_CONFIG_DIRECTORIES = List.of(
237
    new File("/etc/cas/config"),
238
    new File("/opt/cas/config"),
239
    new File("/var/cas/config")
240
);
241

242
// Configuration profiles
243
String PROFILE_STANDALONE = "standalone";
244
String PROFILE_NATIVE = "native";
245
String PROFILE_EMBEDDED = "embedded";
246
String PROFILE_NONE = "none";
247

248
// Docker secrets configuration
249
String DEFAULT_SECRETS_DIR = "/run/secrets/";
250
String VAR_CAS_DOCKER_SECRETS_DIRECTORY = "CAS_DOCKER_SECRETS_DIRECTORY";
251
String VAR_CONTAINER = "CONTAINER";
252
```
253

254
## Property Source Precedence Order
255

256
1. **System Properties and Environment Variables** (highest precedence)
257
2. **Standalone Configuration File** (if specified via `cas.standalone.configuration-file`)
258
3. **Configuration Directory Files** (profile-specific override base configurations)
259
4. **Docker Secrets** (when `CONTAINER=true`)
260
5. **Embedded Classpath Resources** (lowest precedence)
261

262
Within each category, profile-specific configurations override base configurations, and later profiles override earlier profiles.