0
# Configuration Values
1

2
Configuration values provide the type-safe foundation for the Typesafe Config library. The ConfigValue hierarchy includes interfaces for different value types (objects, lists, primitives) with support for unwrapping, rendering, and origin tracking.
3

4
## Value Hierarchy
5

6
### ConfigValue Interface
7

8
Base interface for all configuration values.
9

10
```java { .api }
11
public interface ConfigValue extends ConfigMergeable {
12
    ConfigValueType valueType();
13
    Object unwrapped();
14
    String render();
15
    String render(ConfigRenderOptions options);
16
    ConfigOrigin origin();
17
    ConfigValue withOrigin(ConfigOrigin origin);
18
    Config atPath(String path);
19
    Config atKey(String key);
20
}
21
```
22

23
**Usage Examples:**
24

25
```java
26
ConfigValue value = config.getValue("app.settings");
27

28
// Check value type
29
ConfigValueType type = value.valueType();
30
if (type == ConfigValueType.OBJECT) {
31
    ConfigObject obj = (ConfigObject) value;
32
}
33

34
// Unwrap to plain Java object
35
Object unwrapped = value.unwrapped();
36

37
// Render as string
38
String rendered = value.render();
39
String json = value.render(ConfigRenderOptions.concise().setJson(true));
40

41
// Get origin information
42
ConfigOrigin origin = value.origin();
43
String filename = origin.filename();
44
int lineNumber = origin.lineNumber();
45
```
46

47
### ConfigObject Interface
48

49
Represents object/map values in configuration.
50

51
```java { .api }
52
public interface ConfigObject extends ConfigValue, Map<String, ConfigValue> {
53
    Config toConfig();
54
    ConfigObject withOnlyKey(String key);
55
    ConfigObject withoutKey(String key);
56
    ConfigObject withValue(String key, ConfigValue value);
57
    ConfigObject withOnlyPath(String path);
58
    ConfigObject withoutPath(String path);
59
    ConfigObject withValue(String path, ConfigValue value);
60
    Map<String, Object> unwrapped();
61
}
62
```
63

64
**Usage Examples:**
65

66
```java
67
ConfigObject serverObj = config.getObject("server");
68

69
// Convert to Config for path-based access
70
Config serverConfig = serverObj.toConfig();
71
int port = serverConfig.getInt("port");
72

73
// Map-based access (key-based, not path-based)
74
ConfigValue portValue = serverObj.get("port");
75

76
// Manipulation (returns new instances)
77
ConfigObject withHttps = serverObj.withValue("https.enabled", ConfigValueFactory.fromAnyRef(true));
78
ConfigObject httpOnly = serverObj.withOnlyKey("http");
79
ConfigObject withoutSsl = serverObj.withoutKey("ssl");
80

81
// Unwrap to plain Map
82
Map<String, Object> serverMap = serverObj.unwrapped();
83
```
84

85
### ConfigList Interface
86

87
Represents list/array values in configuration.
88

89
```java { .api }
90
public interface ConfigList extends List<ConfigValue>, ConfigValue {
91
    List<Object> unwrapped();
92
}
93
```
94

95
**Usage Examples:**
96

97
```java
98
ConfigList serverList = config.getList("load-balancer.servers");
99

100
// List operations (immutable)
101
int size = serverList.size();
102
ConfigValue firstServer = serverList.get(0);
103

104
// Iterate over values
105
for (ConfigValue server : serverList) {
106
    if (server.valueType() == ConfigValueType.OBJECT) {
107
        ConfigObject serverObj = (ConfigObject) server;
108
        Config serverConfig = serverObj.toConfig();
109
        String host = serverConfig.getString("host");
110
    }
111
}
112

113
// Unwrap to plain List
114
List<Object> unwrappedList = serverList.unwrapped();
115
```
116

117
## Value Types
118

119
### ConfigValueType Enum
120

121
Enumeration of all possible configuration value types.
122

123
```java { .api }
124
public enum ConfigValueType {
125
    OBJECT,     // ConfigObject - maps/objects
126
    LIST,       // ConfigList - arrays/lists  
127
    NUMBER,     // Numbers (int, long, double)
128
    BOOLEAN,    // Boolean values
129
    NULL,       // Null values
130
    STRING      // String values
131
}
132
```
133

134
**Usage Examples:**
135

136
```java
137
ConfigValue value = config.getValue("some.path");
138

139
switch (value.valueType()) {
140
    case OBJECT:
141
        ConfigObject obj = (ConfigObject) value;
142
        break;
143
    case LIST:
144
        ConfigList list = (ConfigList) value;
145
        break;
146
    case NUMBER:
147
        Number num = (Number) value.unwrapped();
148
        break;
149
    case BOOLEAN:
150
        Boolean bool = (Boolean) value.unwrapped();
151
        break;
152
    case STRING:
153
        String str = (String) value.unwrapped();
154
        break;
155
    case NULL:
156
        // Handle null value
157
        break;
158
}
159
```
160

161
## Value Creation
162

163
### ConfigValueFactory Class
164

165
Factory for creating ConfigValue instances from Java objects.
166

167
```java { .api }
168
public final class ConfigValueFactory {
169
    public static ConfigValue fromAnyRef(Object object);
170
    public static ConfigValue fromAnyRef(Object object, String originDescription);
171
    public static ConfigObject fromMap(Map<String, ?> values);
172
    public static ConfigObject fromMap(Map<String, ?> values, String originDescription);
173
    public static ConfigList fromIterable(Iterable<?> values);
174
    public static ConfigList fromIterable(Iterable<?> values, String originDescription);
175
}
176
```
177

178
**Usage Examples:**
179

180
```java
181
// Create values from Java objects
182
ConfigValue stringValue = ConfigValueFactory.fromAnyRef("hello world");
183
ConfigValue numberValue = ConfigValueFactory.fromAnyRef(42);
184
ConfigValue boolValue = ConfigValueFactory.fromAnyRef(true);
185

186
// Create from collections
187
Map<String, Object> serverMap = Map.of(
188
    "host", "localhost",
189
    "port", 8080,
190
    "ssl", true
191
);
192
ConfigObject serverObj = ConfigValueFactory.fromMap(serverMap);
193

194
List<String> hosts = List.of("web1", "web2", "web3");
195
ConfigList hostList = ConfigValueFactory.fromIterable(hosts);
196

197
// Create with origin description
198
ConfigValue documented = ConfigValueFactory.fromAnyRef(
199
    "production-value", 
200
    "created programmatically"
201
);
202
```
203

204
## Value Rendering
205

206
### ConfigRenderOptions Class
207

208
Options for controlling how configuration values are rendered to strings.
209

210
```java { .api }
211
public final class ConfigRenderOptions {
212
    public static ConfigRenderOptions defaults();
213
    public static ConfigRenderOptions concise();
214
    public ConfigRenderOptions setComments(boolean value);
215
    public ConfigRenderOptions setOriginComments(boolean value);
216
    public ConfigRenderOptions setFormatted(boolean value);
217
    public ConfigRenderOptions setJson(boolean value);
218
    public ConfigRenderOptions setShowEnvVariableValues(boolean value);
219
}
220
```
221

222
**Usage Examples:**
223

224
```java
225
ConfigValue value = config.getValue("database");
226

227
// Default rendering (HOCON with comments)
228
String hocon = value.render();
229

230
// Concise JSON output
231
String json = value.render(ConfigRenderOptions.concise().setJson(true));
232

233
// Formatted HOCON without comments
234
String clean = value.render(
235
    ConfigRenderOptions.defaults()
236
        .setComments(false)
237
        .setFormatted(true)
238
);
239

240
// Include origin information in comments
241
String withOrigins = value.render(
242
    ConfigRenderOptions.defaults()
243
        .setOriginComments(true)
244
);
245

246
// Hide environment variable values (show ${VAR} instead of actual value)
247
String secure = value.render(
248
    ConfigRenderOptions.defaults()
249
        .setShowEnvVariableValues(false)
250
);
251
```
252

253
## Origin Tracking
254

255
### ConfigOrigin Interface
256

257
Tracks where configuration values came from for error reporting and debugging.
258

259
```java { .api }
260
public interface ConfigOrigin {
261
    String description();
262
    String filename();
263
    URL url();
264
    String resource();
265
    int lineNumber();
266
    List<String> comments();
267
    ConfigOrigin withComments(List<String> comments);
268
    ConfigOrigin withLineNumber(int lineNumber);
269
}
270
```
271

272
**Usage Examples:**
273

274
```java
275
ConfigValue value = config.getValue("server.port");
276
ConfigOrigin origin = value.origin();
277

278
// Get origin information
279
String desc = origin.description();          // Human-readable description
280
String file = origin.filename();             // Filename if from file
281
URL url = origin.url();                      // URL if from URL
282
String resource = origin.resource();         // Resource name if from classpath
283
int line = origin.lineNumber();              // Line number (-1 if not available)
284
List<String> comments = origin.comments();   // Associated comments
285

286
// Create modified origin
287
ConfigOrigin withComments = origin.withComments(
288
    List.of("Modified programmatically", "Added validation")
289
);
290
```
291

292
### ConfigOriginFactory Class
293

294
Factory for creating ConfigOrigin instances.
295

296
```java { .api }
297
public final class ConfigOriginFactory {
298
    public static ConfigOrigin newSimple(String description);
299
    public static ConfigOrigin newFile(String filename);
300
    public static ConfigOrigin newURL(URL url);
301
}
302
```
303

304
**Usage Examples:**
305

306
```java
307
// Create simple origin
308
ConfigOrigin simple = ConfigOriginFactory.newSimple("programmatic config");
309

310
// Create file origin
311
ConfigOrigin fileOrigin = ConfigOriginFactory.newFile("/etc/myapp/config.conf");
312

313
// Create URL origin
314
ConfigOrigin urlOrigin = ConfigOriginFactory.newURL(
315
    new URL("https://config.example.com/app.conf")
316
);
317

318
// Use with value creation
319
ConfigValue valueWithOrigin = ConfigValueFactory
320
    .fromAnyRef("test-value")
321
    .withOrigin(simple);
322
```
323

324
## Special Value Types
325

326
### ConfigMemorySize Class
327

328
Represents memory/byte size values with unit parsing and conversion.
329

330
```java { .api }
331
public final class ConfigMemorySize {
332
    public static ConfigMemorySize ofBytes(long bytes);
333
    public static ConfigMemorySize ofBytes(BigInteger bytes);
334
    public long toBytes();
335
    public BigInteger toBytesBigInteger();
336
    public String toString();
337
    public boolean equals(Object other);
338
    public int hashCode();
339
}
340
```
341

342
**Usage Examples:**
343

344
```java
345
// Get memory size from config
346
ConfigMemorySize maxHeap = config.getMemorySize("jvm.max-heap");
347

348
// Convert to bytes
349
long bytes = maxHeap.toBytes();
350
BigInteger bigBytes = maxHeap.toBytesBigInteger();
351

352
// Create memory sizes
353
ConfigMemorySize size1 = ConfigMemorySize.ofBytes(1024 * 1024 * 128); // 128MB
354
ConfigMemorySize size2 = ConfigMemorySize.ofBytes(new BigInteger("4294967296")); // 4GB
355

356
// String representation
357
String readable = maxHeap.toString(); // e.g., "512 MB"
358
```
359

360
## Unwrapping Behavior
361

362
### Automatic Unwrapping
363

364
ConfigValue.unwrapped() converts configuration values to plain Java objects:
365

366
- **ConfigObject** → `Map<String, Object>`
367
- **ConfigList** → `List<Object>`
368
- **STRING** → `String`
369
- **NUMBER** → `Number` (Integer, Long, Double, or BigDecimal)
370
- **BOOLEAN** → `Boolean`
371
- **NULL** → `null`
372

373
**Usage Examples:**
374

375
```java
376
// Object unwrapping
377
ConfigObject obj = config.getObject("database");
378
Map<String, Object> dbMap = obj.unwrapped();
379
String host = (String) dbMap.get("host");
380
Integer port = (Integer) dbMap.get("port");
381

382
// List unwrapping
383
ConfigList list = config.getList("servers");
384
List<Object> serverList = list.unwrapped();
385
for (Object server : serverList) {
386
    if (server instanceof Map) {
387
        Map<String, Object> serverMap = (Map<String, Object>) server;
388
    }
389
}
390

391
// Deep unwrapping of nested structures
392
Object fullyUnwrapped = config.root().unwrapped();
393
Map<String, Object> configMap = (Map<String, Object>) fullyUnwrapped;
394
```
395

396
## Best Practices
397

398
1. **Use typed access methods**: Prefer `config.getString()` over `config.getValue().unwrapped()`
399
2. **Check value types**: Use `valueType()` before casting ConfigValue instances
400
3. **Preserve origin information**: Keep origin data for debugging and error reporting
401
4. **Use appropriate rendering**: Choose JSON for APIs, HOCON for human-readable output
402
5. **Handle null values**: Check for ConfigValueType.NULL when processing raw values
403
6. **Create values with origins**: Always provide meaningful origin descriptions when creating values programmatically