Skip to main content

juneau-config

Maven
<dependency>
    <groupId>org.apache.juneau</groupId>
    <artifactId>juneau-config</artifactId>
    <version>${juneau.version}</version>
</dependency>
Jarjuneau-config-10.0.0.jar
OSGiorg.apache.juneau.config_10.0.0.jar
LinksMaven Central · Javadocs · Source

Contents/Features​

The juneau-config library contains a powerful API for creating and using INI-style config files.

See the guide: Externalize config with INI/YAML and variables

Key Capabilities:

  • Support for storing and retrieving any of the following data types:
    • Primitives
    • POJOs
    • Beans
    • Arrays, Maps, and Collections of anything
    • Binary data
  • Transactional modifications with commit/rollback capabilities
  • A listener API
  • Filesystem watcher integration allowing changes on the file system to be reflected in real-time
  • Modifications through the Config class (e.g. add/remove/modify sections and keys, add/remove comments and whitespace, etc...) DO NOT cause loss of formatting in the file - all existing whitespace and comments are preserved
  • Value encoding for added security
  • Support for SVL variables
  • Directly populate beans from config sections
  • Accessing config sections through Java interface proxies
  • An extensible storage API allows you to write your own config storage (e.g. storage in databases or the cloud)

Overview​

Example configuration file
# A set of entries
[Section1]

# An integer
key1 = 1

# A boolean
key2 = true

# An array
key3 = 1,2,3

# A POJO
key4 = http://bar

Config files are accessed through the Config class which are created through the Config.Builder class.

The config language may look simple but it is a very powerful feature with many capabilities. See Config Overview for a walk-through of creating a Config and reading values.

Serializing configs​

The following methods are used for serializing Config objects back into their text form:

ConfigwriteTo(Writer)toString()

Both methods are thread safe.

Writing to a Writer​

writeTo(Writer) appends the current contents of the config to the specified writer and returns that same writer. The writer is not closed by this method.

Example
Config config = Config.create("MyConfig.cfg").build();

// Dump the config to a string.
StringWriter sw = new StringWriter();
config.writeTo(sw);
String contents = sw.toString();

// Or write it straight to a file.
try (Writer w = new FileWriter("MyConfig-copy.cfg")) {
    config.writeTo(w);
}

toString() returns the same text that writeTo(Writer) produces.

The output reflects the in-memory state of the config, including changes that have been made but not yet committed (see Config Stores for where committed changes go).

Output format​

Serialization goes through the config's ConfigFormat. The format is auto-detected from the config name (a name ending in .yml or .yaml selects YAML, anything else selects INI), or set explicitly with Config.Builder.ini(), Config.Builder.yaml() or Config.Builder.format(ConfigFormat). See INI Config Format and YAML Config Files.

Example
// A config named with a .yaml extension serializes as YAML.
Config yamlConfig = Config.create("MyConfig.yaml").build();
String yamlText = yamlConfig.toString();

// Force INI output regardless of the name.
Config iniConfig = Config.create("MyConfig.txt").ini().build();
String iniText = iniConfig.toString();

See also​

In This Section​