0
# Configuration Loading
1

2
Configuration loading provides factory methods for creating Config instances from various sources including classpath resources, files, URLs, and in-memory data structures. The ConfigFactory class is the primary entry point for loading configurations.
3

4
## Core Loading Methods
5

6
### Default Loading
7

8
Load default application configuration with automatic resource discovery and fallback chain.
9

10
```java { .api }
11
public static Config load();
12
public static Config load(ClassLoader loader);
13
public static Config load(String resourceBasename);
14
public static Config load(String resourceBasename, ConfigParseOptions parseOptions, ConfigResolveOptions resolveOptions);
15
public static Config load(Config config);
16
```
17

18
**Usage Examples:**
19

20
```java
21
// Load default configuration (application.conf with reference.conf fallback)
22
Config config = ConfigFactory.load();
23

24
// Load specific resource
25
Config config = ConfigFactory.load("myapp");
26

27
// Load with custom classloader
28
Config config = ConfigFactory.load(MyClass.class.getClassLoader());
29
```
30

31
### Default Configuration Components
32

33
Access individual components of the default configuration loading process.
34

35
```java { .api }
36
public static Config defaultReference();
37
public static Config defaultReference(ClassLoader loader);
38
public static Config defaultApplication();
39
public static Config defaultApplication(ClassLoader loader);
40
public static Config defaultOverrides();
41
public static Config defaultOverrides(ClassLoader loader);
42
```
43

44
**Usage Examples:**
45

46
```java
47
// Get reference configuration (reference.conf)
48
Config reference = ConfigFactory.defaultReference();
49

50
// Get application configuration (application.conf)
51
Config application = ConfigFactory.defaultApplication();
52

53
// Get system overrides (system properties + environment variables)
54
Config overrides = ConfigFactory.defaultOverrides();
55
```
56

57
### System Configuration
58

59
Access system properties and environment variables as Config objects.
60

61
```java { .api }
62
public static Config systemProperties();
63
public static Config systemEnvironment();
64
```
65

66
**Usage Examples:**
67

68
```java
69
// System properties as Config
70
Config sysProps = ConfigFactory.systemProperties();
71
String javaHome = sysProps.getString("java.home");
72

73
// Environment variables as Config  
74
Config env = ConfigFactory.systemEnvironment();
75
String path = env.getString("PATH");
76
```
77

78
## Parsing Methods
79

80
### String Parsing
81

82
Parse configuration from strings in various formats.
83

84
```java { .api }
85
public static Config parseString(String s);
86
public static Config parseString(String s, ConfigParseOptions options);
87
```
88

89
**Usage Examples:**
90

91
```java
92
// Parse HOCON string
93
String hocon = """
94
    database {
95
        url = "jdbc:postgresql://localhost:5432/mydb"
96
        username = "user"
97
        password = ${?DB_PASSWORD}
98
    }
99
    """;
100
Config config = ConfigFactory.parseString(hocon);
101

102
// Parse JSON string
103
String json = """
104
    {
105
        "server": {
106
            "port": 8080,
107
            "host": "localhost"
108
        }
109
    }
110
    """;
111
Config config = ConfigFactory.parseString(json, ConfigParseOptions.defaults().setSyntax(ConfigSyntax.JSON));
112
```
113

114
### File Parsing
115

116
Parse configuration from files.
117

118
```java { .api }
119
public static Config parseFile(File file);
120
public static Config parseFile(File file, ConfigParseOptions options);
121
public static Config parseFileAnySyntax(File file);
122
public static Config parseFileAnySyntax(File file, ConfigParseOptions options);
123
```
124

125
**Usage Examples:**
126

127
```java
128
// Parse specific file
129
File configFile = new File("/etc/myapp/config.conf");
130
Config config = ConfigFactory.parseFile(configFile);
131

132
// Parse with auto-detection of format
133
Config config = ConfigFactory.parseFileAnySyntax(configFile);
134

135
// Parse with specific options
136
Config config = ConfigFactory.parseFile(configFile, 
137
    ConfigParseOptions.defaults()
138
        .setAllowMissing(false)
139
        .setSyntax(ConfigSyntax.CONF));
140
```
141

142
### URL Parsing
143

144
Parse configuration from URLs.
145

146
```java { .api }
147
public static Config parseURL(URL url);
148
public static Config parseURL(URL url, ConfigParseOptions options);
149
```
150

151
**Usage Examples:**
152

153
```java
154
// Parse from URL
155
URL configUrl = new URL("https://example.com/config.json");
156
Config config = ConfigFactory.parseURL(configUrl);
157

158
// Parse with options
159
Config config = ConfigFactory.parseURL(configUrl,
160
    ConfigParseOptions.defaults().setSyntax(ConfigSyntax.JSON));
161
```
162

163
### Reader Parsing
164

165
Parse configuration from Reader objects.
166

167
```java { .api }
168
public static Config parseReader(Reader reader);
169
public static Config parseReader(Reader reader, ConfigParseOptions options);
170
```
171

172
**Usage Examples:**
173

174
```java
175
// Parse from Reader
176
try (FileReader reader = new FileReader("config.properties")) {
177
    Config config = ConfigFactory.parseReader(reader,
178
        ConfigParseOptions.defaults().setSyntax(ConfigSyntax.PROPERTIES));
179
}
180
```
181

182
### Resource Parsing
183

184
Parse configuration from classpath resources.
185

186
```java { .api }
187
public static Config parseResources(String resource);
188
public static Config parseResources(String resource, ConfigParseOptions options);
189
public static Config parseResources(Class<?> klass, String resource);
190
public static Config parseResources(Class<?> klass, String resource, ConfigParseOptions options);
191
public static Config parseResourcesAnySyntax(String resource);
192
public static Config parseResourcesAnySyntax(String resource, ConfigParseOptions options);
193
```
194

195
**Usage Examples:**
196

197
```java
198
// Parse classpath resource
199
Config config = ConfigFactory.parseResources("application.conf");
200

201
// Parse with class context
202
Config config = ConfigFactory.parseResources(MyApp.class, "/config/app.conf");
203

204
// Parse any syntax (tries .conf, .json, .properties)
205
Config config = ConfigFactory.parseResourcesAnySyntax("myconfig");
206
```
207

208
## Data Structure Parsing
209

210
### Properties Parsing
211

212
Convert Java Properties to Config.
213

214
```java { .api }
215
public static Config parseProperties(Properties properties);
216
public static Config parseProperties(Properties properties, ConfigParseOptions options);
217
```
218

219
**Usage Examples:**
220

221
```java
222
// Convert Properties to Config
223
Properties props = new Properties();
224
props.setProperty("app.name", "MyApp");
225
props.setProperty("app.version", "1.0");
226
Config config = ConfigFactory.parseProperties(props);
227
```
228

229
### Map Parsing
230

231
Convert Map structures to Config.
232

233
```java { .api }
234
public static Config parseMap(Map<String, ?> values);
235
public static Config parseMap(Map<String, ?> values, String originDescription);
236
```
237

238
**Usage Examples:**
239

240
```java
241
// Convert Map to Config
242
Map<String, Object> configMap = Map.of(
243
    "database", Map.of(
244
        "url", "jdbc:h2:mem:test",
245
        "driver", "org.h2.Driver"
246
    ),
247
    "server", Map.of(
248
        "port", 8080,
249
        "host", "localhost"
250
    )
251
);
252
Config config = ConfigFactory.parseMap(configMap);
253
```
254

255
## Utility Methods
256

257
### Empty Configuration
258

259
Create empty configuration objects.
260

261
```java { .api }
262
public static Config empty();
263
public static Config empty(String originDescription);
264
```
265

266
**Usage Examples:**
267

268
```java
269
// Create empty config
270
Config empty = ConfigFactory.empty();
271

272
// Create empty config with origin description
273
Config empty = ConfigFactory.empty("programmatic config");
274
```
275

276
### Cache Management
277

278
Manage internal configuration caches.
279

280
```java { .api }
281
public static void invalidateCaches();
282
```
283

284
**Usage Examples:**
285

286
```java
287
// Clear all internal caches (useful in testing)
288
ConfigFactory.invalidateCaches();
289
```
290

291
## Configuration Strategy
292

293
### Custom Loading Strategy
294

295
Override default loading behavior using system property.
296

297
```java { .api }
298
public interface ConfigLoadingStrategy {
299
    Config parseApplicationConfig(ConfigParseOptions parseOptions);
300
}
301
```
302

303
**Usage:**
304

305
Set system property `config.strategy` to fully qualified class name of your ConfigLoadingStrategy implementation to customize how application configuration is loaded.
306

307
## Error Handling
308

309
Loading methods can throw various ConfigException subtypes:
310

311
- **ConfigException.IO**: File/network I/O errors
312
- **ConfigException.Parse**: Syntax errors in configuration files
313
- **ConfigException.Missing**: Required resources not found (when allowMissing=false)
314
- **ConfigException.BadPath**: Invalid path expressions in configuration
315

316
## Best Practices
317

318
1. **Use load() for applications**: The default load() method handles the common case of loading application.conf with reference.conf fallback
319
2. **Use parseResources() for libraries**: Libraries should typically load their own reference.conf using parseResources()
320
3. **Handle missing files gracefully**: Use setAllowMissing(true) in ConfigParseOptions when files are optional
321
4. **Specify syntax explicitly**: Use setSyntax() when parsing files with ambiguous extensions
322
5. **Cache configurations**: Config objects are immutable and expensive to create, so cache them when possible