tessl/maven-com-typesafe--config
Configuration library for JVM languages using HOCON files
—
Pending
access.mddocs/
Configuration Access
Configuration access provides the core API for retrieving values from Config objects using dot-separated path expressions. The Config interface offers type-safe getters with automatic conversion and comprehensive support for nested structures.
Path-Based Access
Basic Value Getters
Retrieve primitive configuration values with automatic type conversion.
public boolean getBoolean(String path);
public Number getNumber(String path);
public int getInt(String path);
public long getLong(String path);
public double getDouble(String path);
public String getString(String path);
public <T extends Enum<T>> T getEnum(Class<T> enumClass, String path);Usage Examples:
Config config = ConfigFactory.load();
// Basic value access
boolean debugMode = config.getBoolean("app.debug");
int serverPort = config.getInt("server.port");
String dbUrl = config.getString("database.url");
double timeout = config.getDouble("client.timeout");
// Enum access
LogLevel level = config.getEnum(LogLevel.class, "logging.level");Duration and Time Access
Retrieve time-based values with support for various time units and formats.
public Duration getDuration(String path);
public Duration getDuration(String path, TimeUnit unit);
public long getDuration(String path, TimeUnit unit);
public Period getPeriod(String path);
public TemporalAmount getTemporal(String path);Usage Examples:
// Duration access (supports formats like "30 seconds", "5 minutes", "2 hours")
Duration cacheTimeout = config.getDuration("cache.timeout");
Duration connectTimeout = config.getDuration("http.connect-timeout");
// Duration in specific units
long timeoutMillis = config.getDuration("timeout", TimeUnit.MILLISECONDS);
long retryDelaySeconds = config.getDuration("retry.delay", TimeUnit.SECONDS);
// Period access (supports formats like "2 days", "1 week", "3 months")
Period archiveAfter = config.getPeriod("data.archive-after");
// Temporal amount (Duration or Period)
TemporalAmount interval = config.getTemporal("scheduler.interval");Memory Size Access
Retrieve memory/byte size values with automatic unit conversion.
public Long getBytes(String path);
public ConfigMemorySize getMemorySize(String path);Usage Examples:
// Memory size access (supports formats like "128MB", "4GB", "1024KB")
Long maxHeapBytes = config.getBytes("jvm.max-heap");
ConfigMemorySize bufferSize = config.getMemorySize("buffer.size");
// ConfigMemorySize provides additional methods
long bufferBytes = bufferSize.toBytes();Structured Data Access
Access nested configuration objects and convert to Config instances.
public Object getAnyRef(String path);
public ConfigValue getValue(String path);
public ConfigObject getObject(String path);
public Config getConfig(String path);Usage Examples:
// Nested config access
Config dbConfig = config.getConfig("database");
String dbHost = dbConfig.getString("host");
int dbPort = dbConfig.getInt("port");
// Raw value access
ConfigValue rawValue = config.getValue("app.feature-flags");
Object unwrapped = config.getAnyRef("external-service.config");
// Object access
ConfigObject serverObj = config.getObject("server");List Access
Typed List Getters
Retrieve lists of specific types with automatic element conversion.
public ConfigList getList(String path);
public List<Boolean> getBooleanList(String path);
public List<Number> getNumberList(String path);
public List<Integer> getIntList(String path);
public List<Long> getLongList(String path);
public List<Double> getDoubleList(String path);
public List<String> getStringList(String path);
public <T extends Enum<T>> List<T> getEnumList(Class<T> enumClass, String path);Usage Examples:
// String lists
List<String> allowedHosts = config.getStringList("security.allowed-hosts");
List<String> enabledFeatures = config.getStringList("app.features");
// Numeric lists
List<Integer> ports = config.getIntList("server.ports");
List<Double> coefficients = config.getDoubleList("algorithm.coefficients");
// Boolean lists
List<Boolean> featureToggles = config.getBooleanList("features.enabled");
// Enum lists
List<Protocol> protocols = config.getEnumList(Protocol.class, "network.protocols");Advanced List Access
Access lists of complex objects and mixed types.
public List<Object> getAnyRefList(String path);
public List<ConfigValue> getConfigValueList(String path);
public List<ConfigObject> getObjectList(String path);
public List<Config> getConfigList(String path);Usage Examples:
// Lists of objects
List<Config> servers = config.getConfigList("load-balancer.servers");
for (Config server : servers) {
String host = server.getString("host");
int port = server.getInt("port");
double weight = server.getDouble("weight");
}
// Lists of raw objects
List<Object> mixedValues = config.getAnyRefList("data.mixed-array");
// Lists of ConfigObjects
List<ConfigObject> policies = config.getObjectList("security.policies");Duration and Memory Lists
Access lists of time and memory values.
public List<Duration> getDurationList(String path);
public List<Duration> getDurationList(String path, TimeUnit unit);
public List<Long> getDurationList(String path, TimeUnit unit);
public List<Long> getBytesList(String path);
public List<ConfigMemorySize> getMemorySizeList(String path);Usage Examples:
// Duration lists
List<Duration> retryIntervals = config.getDurationList("retry.intervals");
List<Long> timeoutsMs = config.getDurationList("timeouts", TimeUnit.MILLISECONDS);
// Memory size lists
List<Long> cacheSizes = config.getBytesList("cache.sizes");
List<ConfigMemorySize> bufferSizes = config.getMemorySizeList("buffers");Path Existence and Navigation
Path Checking
Check for path existence and null values.
public boolean hasPath(String path);
public boolean hasPathOrNull(String path);
public boolean getIsNull(String path);
public boolean isEmpty();Usage Examples:
// Check if path exists and is not null
if (config.hasPath("optional.feature")) {
boolean enabled = config.getBoolean("optional.feature");
}
// Check if path exists (including null values)
if (config.hasPathOrNull("nullable.setting")) {
if (config.getIsNull("nullable.setting")) {
// Handle null case
} else {
String value = config.getString("nullable.setting");
}
}
// Check if config is empty
if (config.isEmpty()) {
// Handle empty configuration
}Structure Navigation
Navigate and inspect configuration structure.
public ConfigObject root();
public ConfigOrigin origin();
public Set<Map.Entry<String, ConfigValue>> entrySet();Usage Examples:
// Get root object
ConfigObject root = config.root();
// Get all entries as path-value pairs
Set<Map.Entry<String, ConfigValue>> entries = config.entrySet();
for (Map.Entry<String, ConfigValue> entry : entries) {
String path = entry.getKey();
ConfigValue value = entry.getValue();
System.out.println(path + " = " + value.render());
}
// Get origin information
ConfigOrigin origin = config.origin();
String description = origin.description();
String filename = origin.filename();
int lineNumber = origin.lineNumber();Configuration Manipulation
Path-Based Manipulation
Create new Config instances with modified paths.
public Config withOnlyPath(String path);
public Config withoutPath(String path);
public Config withValue(String path, ConfigValue value);
public Config atPath(String path);
public Config atKey(String key);Usage Examples:
// Extract subset of configuration
Config dbConfig = config.withOnlyPath("database");
// Remove specific path
Config withoutDebug = config.withoutPath("debug");
// Add/update value
Config updated = config.withValue("server.port", ConfigValueFactory.fromAnyRef(9090));
// Wrap config at path
Config wrapped = config.atPath("application");
// Wrap config at key
Config keyWrapped = config.atKey("myapp");Merging and Fallbacks
Combine configurations with fallback semantics.
public Config withFallback(ConfigMergeable other);Usage Examples:
// Merge with fallback (current config takes precedence)
Config defaults = ConfigFactory.parseResources("defaults.conf");
Config merged = config.withFallback(defaults);
// Chain multiple fallbacks
Config complete = config
.withFallback(ConfigFactory.parseResources("reference.conf"))
.withFallback(ConfigFactory.systemProperties())
.withFallback(ConfigFactory.systemEnvironment());Error Handling
Configuration access methods throw specific exceptions for different error conditions:
ConfigException.Missing
Thrown when a required path is not found.
try {
String value = config.getString("missing.path");
} catch (ConfigException.Missing e) {
// Handle missing configuration
String path = e.path(); // Get the missing path
}ConfigException.Null
Thrown when a path exists but has a null value (extends ConfigException.Missing).
try {
String value = config.getString("nullable.path");
} catch (ConfigException.Null e) {
// Handle null value
} catch (ConfigException.Missing e) {
// Handle missing path
}ConfigException.WrongType
Thrown when requesting a value with incompatible type.
try {
int value = config.getInt("string.value");
} catch (ConfigException.WrongType e) {
// Handle type mismatch
ConfigValueType actual = e.actual();
ConfigValueType expected = e.expected();
}Best Practices
- Use hasPath() for optional values: Check existence before accessing optional configuration
- Prefer specific getters: Use typed getters (getInt, getString) instead of getAnyRef when possible
- Handle exceptions appropriately: Distinguish between missing, null, and wrong-type errors
- Cache expensive operations: Store Config objects and avoid repeated path lookups
- Use meaningful path names: Follow dot-notation conventions (e.g., "database.connection.timeout")
- Group related settings: Use nested objects for related configuration (e.g., "server.http.port", "server.https.port")
Install with Tessl CLI
npx tessl i tessl/maven-com-typesafe--config