0
# Typesafe Config
1

2
Typesafe Config is a comprehensive configuration management library for JVM applications that provides a thread-safe, immutable API for loading, parsing, and accessing configuration data. It supports HOCON (Human-Optimized Config Object Notation), JSON, and Java Properties formats with advanced features including variable substitution, configuration merging, type conversion, and validation.
3

4
## Package Information
5

6
- **Package Name**: com.typesafe:config
7
- **Package Type**: Maven
8
- **Language**: Java
9
- **Installation**: `<dependency><groupId>com.typesafe</groupId><artifactId>config</artifactId><version>1.4.3</version></dependency>`
10

11
## Core Imports
12

13
```java
14
import com.typesafe.config.Config;
15
import com.typesafe.config.ConfigFactory;
16
import com.typesafe.config.ConfigValue;
17
import com.typesafe.config.ConfigObject;
18
```
19

20
## Basic Usage
21

22
```java
23
import com.typesafe.config.Config;
24
import com.typesafe.config.ConfigFactory;
25

26
// Load default application configuration
27
Config config = ConfigFactory.load();
28

29
// Access configuration values
30
String dbUrl = config.getString("database.url");
31
int port = config.getInt("server.port");
32
boolean enableDebug = config.getBoolean("app.debug");
33

34
// Work with nested configuration
35
Config dbConfig = config.getConfig("database");
36
String username = dbConfig.getString("username");
37
```
38

39
## Architecture
40

41
Typesafe Config is built around several key components:
42

43
- **Config Interface**: Main API for accessing configuration values using dot-separated paths
44
- **ConfigValue Hierarchy**: Type-safe value objects (ConfigObject, ConfigList) with automatic conversion
45
- **Factory Pattern**: ConfigFactory for loading and parsing, ConfigValueFactory for creating values
46
- **Immutable Design**: All configuration objects are immutable and thread-safe
47
- **Resolution System**: Variable substitution with ${path} syntax and environment variable support
48
- **Merge Semantics**: Configuration layering with fallback chains and override capabilities
49
- **Multi-format Support**: HOCON, JSON, and Properties parsing with consistent API
50

51
## Capabilities
52

53
### Configuration Loading and Parsing
54

55
Primary factory methods for loading configurations from various sources including classpath resources, files, URLs, and in-memory structures.
56

57
```java { .api }
58
public static Config load();
59
public static Config load(String resourceBasename);
60
public static Config parseString(String hoconString);
61
public static Config parseFile(File file);
62
public static Config parseURL(URL url);
63
```
64

65
[Configuration Loading](./loading.md)
66

67
### Configuration Access and Type Conversion
68

69
Core API for accessing configuration values with automatic type conversion and path-based navigation through configuration trees.
70

71
```java { .api }
72
public interface Config extends ConfigMergeable {
73
    boolean getBoolean(String path);
74
    int getInt(String path);
75
    long getLong(String path);
76
    double getDouble(String path);
77
    String getString(String path);
78
    Duration getDuration(String path);
79
    ConfigObject getObject(String path);
80
    Config getConfig(String path);
81
}
82
```
83

84
[Configuration Access](./access.md)
85

86
### Configuration Values and Objects
87

88
Value system providing type-safe access to configuration data with support for objects, lists, and primitive types.
89

90
```java { .api }
91
public interface ConfigValue extends ConfigMergeable {
92
    ConfigValueType valueType();
93
    Object unwrapped();
94
    String render();
95
    ConfigOrigin origin();
96
}
97

98
public interface ConfigObject extends ConfigValue, Map<String, ConfigValue> {
99
    Config toConfig();
100
    ConfigObject withValue(String key, ConfigValue value);
101
}
102
```
103

104
[Configuration Values](./values.md)
105

106
### Resolution and Substitution
107

108
Variable substitution system supporting ${path} syntax, environment variables, and custom resolvers for dynamic configuration values.
109

110
```java { .api }
111
public Config resolve();
112
public Config resolve(ConfigResolveOptions options);
113
public Config resolveWith(Config source);
114
public boolean isResolved();
115
```
116

117
[Resolution and Substitution](./resolution.md)
118

119
### Configuration Options and Customization
120

121
Comprehensive options system for controlling parsing, resolution, and rendering behavior with support for custom includers and resolvers.
122

123
```java { .api }
124
public final class ConfigParseOptions {
125
    public static ConfigParseOptions defaults();
126
    public ConfigParseOptions setSyntax(ConfigSyntax syntax);
127
    public ConfigParseOptions setIncluder(ConfigIncluder includer);
128
}
129

130
public final class ConfigResolveOptions {
131
    public static ConfigResolveOptions defaults();
132
    public ConfigResolveOptions setUseSystemEnvironment(boolean value);
133
    public ConfigResolveOptions appendResolver(ConfigResolver resolver);
134
}
135
```
136

137
[Options and Customization](./options.md)
138

139
### Exception Handling
140

141
Comprehensive exception hierarchy for handling configuration errors with specific exception types for different error conditions.
142

143
```java { .api }
144
public abstract class ConfigException extends RuntimeException {
145
    public static class Missing extends ConfigException { }
146
    public static class WrongType extends ConfigException { }
147
    public static class Parse extends ConfigException { }
148
    public static class UnresolvedSubstitution extends ConfigException { }
149
}
150
```
151

152
[Exception Handling](./exceptions.md)
153

154
### JavaBean Integration
155

156
Automatic JavaBean creation from configuration objects with validation and type conversion.
157

158
```java { .api }
159
public class ConfigBeanFactory {
160
    public static <T> T create(Config config, Class<T> clazz);
161
}
162
```
163

164
## Common Types
165

166
```java { .api }
167
import java.net.URL;
168
import java.util.List;
169
public enum ConfigValueType {
170
    OBJECT, LIST, NUMBER, BOOLEAN, NULL, STRING
171
}
172

173
public enum ConfigSyntax {
174
    JSON,        // Strict JSON format
175
    CONF,        // HOCON format (default)  
176
    PROPERTIES   // Java Properties format
177
}
178

179
public interface ConfigOrigin {
180
    String description();
181
    String filename();
182
    URL url();
183
    String resource();  
184
    int lineNumber();
185
    List<String> comments();
186
    ConfigOrigin withComments(List<String> comments);
187
    ConfigOrigin withLineNumber(int lineNumber);
188
}
189

190
public final class ConfigMemorySize {
191
    public static ConfigMemorySize ofBytes(long bytes);
192
    public long toBytes();
193
}
194

195
public final class ConfigUtil {
196
    public static String quoteString(String s);
197
    public static String joinPath(String... elements);
198
    public static String joinPath(List<String> elements);
199
    public static List<String> splitPath(String path);
200
}
201
```