tessl/maven-com-typesafe--config
Configuration library for JVM languages using HOCON files
—
Pending
loading.mddocs/
Configuration Loading
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.
Core Loading Methods
Default Loading
Load default application configuration with automatic resource discovery and fallback chain.
public static Config load();
public static Config load(ClassLoader loader);
public static Config load(String resourceBasename);
public static Config load(String resourceBasename, ConfigParseOptions parseOptions, ConfigResolveOptions resolveOptions);
public static Config load(Config config);Usage Examples:
// Load default configuration (application.conf with reference.conf fallback)
Config config = ConfigFactory.load();
// Load specific resource
Config config = ConfigFactory.load("myapp");
// Load with custom classloader
Config config = ConfigFactory.load(MyClass.class.getClassLoader());Default Configuration Components
Access individual components of the default configuration loading process.
public static Config defaultReference();
public static Config defaultReference(ClassLoader loader);
public static Config defaultApplication();
public static Config defaultApplication(ClassLoader loader);
public static Config defaultOverrides();
public static Config defaultOverrides(ClassLoader loader);Usage Examples:
// Get reference configuration (reference.conf)
Config reference = ConfigFactory.defaultReference();
// Get application configuration (application.conf)
Config application = ConfigFactory.defaultApplication();
// Get system overrides (system properties + environment variables)
Config overrides = ConfigFactory.defaultOverrides();System Configuration
Access system properties and environment variables as Config objects.
public static Config systemProperties();
public static Config systemEnvironment();Usage Examples:
// System properties as Config
Config sysProps = ConfigFactory.systemProperties();
String javaHome = sysProps.getString("java.home");
// Environment variables as Config
Config env = ConfigFactory.systemEnvironment();
String path = env.getString("PATH");Parsing Methods
String Parsing
Parse configuration from strings in various formats.
public static Config parseString(String s);
public static Config parseString(String s, ConfigParseOptions options);Usage Examples:
// Parse HOCON string
String hocon = """
database {
url = "jdbc:postgresql://localhost:5432/mydb"
username = "user"
password = ${?DB_PASSWORD}
}
""";
Config config = ConfigFactory.parseString(hocon);
// Parse JSON string
String json = """
{
"server": {
"port": 8080,
"host": "localhost"
}
}
""";
Config config = ConfigFactory.parseString(json, ConfigParseOptions.defaults().setSyntax(ConfigSyntax.JSON));File Parsing
Parse configuration from files.
public static Config parseFile(File file);
public static Config parseFile(File file, ConfigParseOptions options);
public static Config parseFileAnySyntax(File file);
public static Config parseFileAnySyntax(File file, ConfigParseOptions options);Usage Examples:
// Parse specific file
File configFile = new File("/etc/myapp/config.conf");
Config config = ConfigFactory.parseFile(configFile);
// Parse with auto-detection of format
Config config = ConfigFactory.parseFileAnySyntax(configFile);
// Parse with specific options
Config config = ConfigFactory.parseFile(configFile,
ConfigParseOptions.defaults()
.setAllowMissing(false)
.setSyntax(ConfigSyntax.CONF));URL Parsing
Parse configuration from URLs.
public static Config parseURL(URL url);
public static Config parseURL(URL url, ConfigParseOptions options);Usage Examples:
// Parse from URL
URL configUrl = new URL("https://example.com/config.json");
Config config = ConfigFactory.parseURL(configUrl);
// Parse with options
Config config = ConfigFactory.parseURL(configUrl,
ConfigParseOptions.defaults().setSyntax(ConfigSyntax.JSON));Reader Parsing
Parse configuration from Reader objects.
public static Config parseReader(Reader reader);
public static Config parseReader(Reader reader, ConfigParseOptions options);Usage Examples:
// Parse from Reader
try (FileReader reader = new FileReader("config.properties")) {
Config config = ConfigFactory.parseReader(reader,
ConfigParseOptions.defaults().setSyntax(ConfigSyntax.PROPERTIES));
}Resource Parsing
Parse configuration from classpath resources.
public static Config parseResources(String resource);
public static Config parseResources(String resource, ConfigParseOptions options);
public static Config parseResources(Class<?> klass, String resource);
public static Config parseResources(Class<?> klass, String resource, ConfigParseOptions options);
public static Config parseResourcesAnySyntax(String resource);
public static Config parseResourcesAnySyntax(String resource, ConfigParseOptions options);Usage Examples:
// Parse classpath resource
Config config = ConfigFactory.parseResources("application.conf");
// Parse with class context
Config config = ConfigFactory.parseResources(MyApp.class, "/config/app.conf");
// Parse any syntax (tries .conf, .json, .properties)
Config config = ConfigFactory.parseResourcesAnySyntax("myconfig");Data Structure Parsing
Properties Parsing
Convert Java Properties to Config.
public static Config parseProperties(Properties properties);
public static Config parseProperties(Properties properties, ConfigParseOptions options);Usage Examples:
// Convert Properties to Config
Properties props = new Properties();
props.setProperty("app.name", "MyApp");
props.setProperty("app.version", "1.0");
Config config = ConfigFactory.parseProperties(props);Map Parsing
Convert Map structures to Config.
public static Config parseMap(Map<String, ?> values);
public static Config parseMap(Map<String, ?> values, String originDescription);Usage Examples:
// Convert Map to Config
Map<String, Object> configMap = Map.of(
"database", Map.of(
"url", "jdbc:h2:mem:test",
"driver", "org.h2.Driver"
),
"server", Map.of(
"port", 8080,
"host", "localhost"
)
);
Config config = ConfigFactory.parseMap(configMap);Utility Methods
Empty Configuration
Create empty configuration objects.
public static Config empty();
public static Config empty(String originDescription);Usage Examples:
// Create empty config
Config empty = ConfigFactory.empty();
// Create empty config with origin description
Config empty = ConfigFactory.empty("programmatic config");Cache Management
Manage internal configuration caches.
public static void invalidateCaches();Usage Examples:
// Clear all internal caches (useful in testing)
ConfigFactory.invalidateCaches();Configuration Strategy
Custom Loading Strategy
Override default loading behavior using system property.
public interface ConfigLoadingStrategy {
Config parseApplicationConfig(ConfigParseOptions parseOptions);
}Usage:
Set system property config.strategy to fully qualified class name of your ConfigLoadingStrategy implementation to customize how application configuration is loaded.
Error Handling
Loading methods can throw various ConfigException subtypes:
- ConfigException.IO: File/network I/O errors
- ConfigException.Parse: Syntax errors in configuration files
- ConfigException.Missing: Required resources not found (when allowMissing=false)
- ConfigException.BadPath: Invalid path expressions in configuration
Best Practices
- Use load() for applications: The default load() method handles the common case of loading application.conf with reference.conf fallback
- Use parseResources() for libraries: Libraries should typically load their own reference.conf using parseResources()
- Handle missing files gracefully: Use setAllowMissing(true) in ConfigParseOptions when files are optional
- Specify syntax explicitly: Use setSyntax() when parsing files with ambiguous extensions
- Cache configurations: Config objects are immutable and expensive to create, so cache them when possible
Install with Tessl CLI
npx tessl i tessl/maven-com-typesafe--config