CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-com-typesafe--config

Configuration library for JVM languages using HOCON files

—

Pending
Overview
Eval results
Files

values.mddocs/

Configuration Values

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.

Value Hierarchy

ConfigValue Interface

Base interface for all configuration values.

public interface ConfigValue extends ConfigMergeable {
    ConfigValueType valueType();
    Object unwrapped();
    String render();
    String render(ConfigRenderOptions options);
    ConfigOrigin origin();
    ConfigValue withOrigin(ConfigOrigin origin);
    Config atPath(String path);
    Config atKey(String key);
}

Usage Examples:

ConfigValue value = config.getValue("app.settings");

// Check value type
ConfigValueType type = value.valueType();
if (type == ConfigValueType.OBJECT) {
    ConfigObject obj = (ConfigObject) value;
}

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

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

// Get origin information
ConfigOrigin origin = value.origin();
String filename = origin.filename();
int lineNumber = origin.lineNumber();

ConfigObject Interface

Represents object/map values in configuration.

public interface ConfigObject extends ConfigValue, Map<String, ConfigValue> {
    Config toConfig();
    ConfigObject withOnlyKey(String key);
    ConfigObject withoutKey(String key);
    ConfigObject withValue(String key, ConfigValue value);
    ConfigObject withOnlyPath(String path);
    ConfigObject withoutPath(String path);
    ConfigObject withValue(String path, ConfigValue value);
    Map<String, Object> unwrapped();
}

Usage Examples:

ConfigObject serverObj = config.getObject("server");

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

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

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

// Unwrap to plain Map
Map<String, Object> serverMap = serverObj.unwrapped();

ConfigList Interface

Represents list/array values in configuration.

public interface ConfigList extends List<ConfigValue>, ConfigValue {
    List<Object> unwrapped();
}

Usage Examples:

ConfigList serverList = config.getList("load-balancer.servers");

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

// Iterate over values
for (ConfigValue server : serverList) {
    if (server.valueType() == ConfigValueType.OBJECT) {
        ConfigObject serverObj = (ConfigObject) server;
        Config serverConfig = serverObj.toConfig();
        String host = serverConfig.getString("host");
    }
}

// Unwrap to plain List
List<Object> unwrappedList = serverList.unwrapped();

Value Types

ConfigValueType Enum

Enumeration of all possible configuration value types.

public enum ConfigValueType {
    OBJECT,     // ConfigObject - maps/objects
    LIST,       // ConfigList - arrays/lists  
    NUMBER,     // Numbers (int, long, double)
    BOOLEAN,    // Boolean values
    NULL,       // Null values
    STRING      // String values
}

Usage Examples:

ConfigValue value = config.getValue("some.path");

switch (value.valueType()) {
    case OBJECT:
        ConfigObject obj = (ConfigObject) value;
        break;
    case LIST:
        ConfigList list = (ConfigList) value;
        break;
    case NUMBER:
        Number num = (Number) value.unwrapped();
        break;
    case BOOLEAN:
        Boolean bool = (Boolean) value.unwrapped();
        break;
    case STRING:
        String str = (String) value.unwrapped();
        break;
    case NULL:
        // Handle null value
        break;
}

Value Creation

ConfigValueFactory Class

Factory for creating ConfigValue instances from Java objects.

public final class ConfigValueFactory {
    public static ConfigValue fromAnyRef(Object object);
    public static ConfigValue fromAnyRef(Object object, String originDescription);
    public static ConfigObject fromMap(Map<String, ?> values);
    public static ConfigObject fromMap(Map<String, ?> values, String originDescription);
    public static ConfigList fromIterable(Iterable<?> values);
    public static ConfigList fromIterable(Iterable<?> values, String originDescription);
}

Usage Examples:

// Create values from Java objects
ConfigValue stringValue = ConfigValueFactory.fromAnyRef("hello world");
ConfigValue numberValue = ConfigValueFactory.fromAnyRef(42);
ConfigValue boolValue = ConfigValueFactory.fromAnyRef(true);

// Create from collections
Map<String, Object> serverMap = Map.of(
    "host", "localhost",
    "port", 8080,
    "ssl", true
);
ConfigObject serverObj = ConfigValueFactory.fromMap(serverMap);

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

// Create with origin description
ConfigValue documented = ConfigValueFactory.fromAnyRef(
    "production-value", 
    "created programmatically"
);

Value Rendering

ConfigRenderOptions Class

Options for controlling how configuration values are rendered to strings.

public final class ConfigRenderOptions {
    public static ConfigRenderOptions defaults();
    public static ConfigRenderOptions concise();
    public ConfigRenderOptions setComments(boolean value);
    public ConfigRenderOptions setOriginComments(boolean value);
    public ConfigRenderOptions setFormatted(boolean value);
    public ConfigRenderOptions setJson(boolean value);
    public ConfigRenderOptions setShowEnvVariableValues(boolean value);
}

Usage Examples:

ConfigValue value = config.getValue("database");

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

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

// Formatted HOCON without comments
String clean = value.render(
    ConfigRenderOptions.defaults()
        .setComments(false)
        .setFormatted(true)
);

// Include origin information in comments
String withOrigins = value.render(
    ConfigRenderOptions.defaults()
        .setOriginComments(true)
);

// Hide environment variable values (show ${VAR} instead of actual value)
String secure = value.render(
    ConfigRenderOptions.defaults()
        .setShowEnvVariableValues(false)
);

Origin Tracking

ConfigOrigin Interface

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

public interface ConfigOrigin {
    String description();
    String filename();
    URL url();
    String resource();
    int lineNumber();
    List<String> comments();
    ConfigOrigin withComments(List<String> comments);
    ConfigOrigin withLineNumber(int lineNumber);
}

Usage Examples:

ConfigValue value = config.getValue("server.port");
ConfigOrigin origin = value.origin();

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

// Create modified origin
ConfigOrigin withComments = origin.withComments(
    List.of("Modified programmatically", "Added validation")
);

ConfigOriginFactory Class

Factory for creating ConfigOrigin instances.

public final class ConfigOriginFactory {
    public static ConfigOrigin newSimple(String description);
    public static ConfigOrigin newFile(String filename);
    public static ConfigOrigin newURL(URL url);
}

Usage Examples:

// Create simple origin
ConfigOrigin simple = ConfigOriginFactory.newSimple("programmatic config");

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

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

// Use with value creation
ConfigValue valueWithOrigin = ConfigValueFactory
    .fromAnyRef("test-value")
    .withOrigin(simple);

Special Value Types

ConfigMemorySize Class

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

public final class ConfigMemorySize {
    public static ConfigMemorySize ofBytes(long bytes);
    public static ConfigMemorySize ofBytes(BigInteger bytes);
    public long toBytes();
    public BigInteger toBytesBigInteger();
    public String toString();
    public boolean equals(Object other);
    public int hashCode();
}

Usage Examples:

// Get memory size from config
ConfigMemorySize maxHeap = config.getMemorySize("jvm.max-heap");

// Convert to bytes
long bytes = maxHeap.toBytes();
BigInteger bigBytes = maxHeap.toBytesBigInteger();

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

// String representation
String readable = maxHeap.toString(); // e.g., "512 MB"

Unwrapping Behavior

Automatic Unwrapping

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

  • ConfigObject → Map<String, Object>
  • ConfigList → List<Object>
  • STRING → String
  • NUMBER → Number (Integer, Long, Double, or BigDecimal)
  • BOOLEAN → Boolean
  • NULL → null

Usage Examples:

// Object unwrapping
ConfigObject obj = config.getObject("database");
Map<String, Object> dbMap = obj.unwrapped();
String host = (String) dbMap.get("host");
Integer port = (Integer) dbMap.get("port");

// List unwrapping
ConfigList list = config.getList("servers");
List<Object> serverList = list.unwrapped();
for (Object server : serverList) {
    if (server instanceof Map) {
        Map<String, Object> serverMap = (Map<String, Object>) server;
    }
}

// Deep unwrapping of nested structures
Object fullyUnwrapped = config.root().unwrapped();
Map<String, Object> configMap = (Map<String, Object>) fullyUnwrapped;

Best Practices

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

Install with Tessl CLI

npx tessl i tessl/maven-com-typesafe--config

docs

access.md

exceptions.md

index.md

loading.md

options.md

resolution.md

values.md

tile.json