Skip to main content

Setting Values

The following methods allow you to add, remove, and modify entries and sections in a config file:

Configset(String,Object)set(String,Object,Serializer)set(String,Object,Serializer,String,String,List)set(String,String)remove(String)setSection(String,List)setSection(String,List,Map)removeSection(String) 
// Construct the sample config file programmatically
Config config = Config.create("MyConfig.cfg").build()
    .set("key1", 1)
    .set("key2", true)
    .set("key3", new int[]{1,2,3})
    .set("key4", new URI("http://foo"))
    .set("Section1/key1", 2)
    .set("Section1/key2", false)
    .set("Section1/key3", new int[]{4,5,6})
    .set("Section1/key4", new URI("http://bar"))
    .commit();

The method Config.set(String,Object,Serializer,String,String,List) can be used for adding comments and pre-lines to entries, and specifying encoded values.

// Set an encoded value with some comments.
config.set("key1", 1, null, "*", "Same-line comment",
    Arrays.asList(
        "# Comment 1", "", "# Comment 2"
    )
);
# Comment 1
# Comment 2
key1 = 1 # Same-line comment

The last 4 arguments in Config.set(String,Object,Serializer,String,String,List) are optional in that if you pass null, the current value will not be overwritten.

To unset the same-line comment, you should pass in a blank string.

To remove pre-lines, you should pass in an empty list.

Fluent entry builder​

Because the 6-argument set(...) overload packs several different "leave-unchanged versus clear" sentinel conventions into one call (a null comment leaves the existing comment untouched while a blank comment clears it; a null pre-lines list leaves the existing pre-lines untouched while an empty list clears them), the recommended ergonomic alternative is the fluent entry builder returned by Config.entry(String).

Each facet is expressed explicitly, so no sentinels are needed:

  • Not calling a facet method leaves that facet untouched.
  • An explicit setter (comment(String), preLines(List), serializer(Serializer), modifiers(String)) sets that facet.
  • An explicit clear (clearComment(), clearPreLines()) intentionally clears that facet.
  • A terminal set(Object) (or value(Object).set()) performs the write.
// Equivalent to the 6-arg set(...) call above.
config.entry("key1")
    .modifiers("*")
    .comment("Same-line comment")
    .preLines(List.of("# Comment 1", "", "# Comment 2"))
    .set(1);

// Update only the comment on an existing entry, leaving the value and pre-lines untouched.
config.entry("key1")
    .comment("Updated comment")
    .set();

// Explicitly clear the comment (rather than passing a magic blank string).
config.entry("key1")
    .clearComment()
    .set();

The fluent path produces a result identical to the equivalent Config.set(String,Object,Serializer,String,String,List) call, and the legacy set(...) overloads remain available.

Sections can be added with optional pre-lines using the setSection methods:

// Set an encoded value with some comments.
config.setSection("NewSection",
    Arrays.asList(
        "# Section comment 1", "", "# Section comment 2"
    )
);
# Section comment 1
# Section comment 2
[NewSection]

Changes made to the configuration are transactional in nature. They are kept in memory until you call the Config.commit() method. Until then, you still see the modified values when you call any of the getters but the modified values exist only in memory.

Changes can be rolled back using the Config.rollback() method.

Custom entry serialization​

Setter methods that take in a Serializer can be used to provide custom serialization of entries instead of using the predefined serializer.

// Set an XML value instead of JSON.
config.set("key1", myAddress, XmlSerializer.DEFAULT_SQ_READABLE);
key1 =
    123 Main Street
    Anywhere
    NY
    12345

The value can then be retrieved using the equivalent parser:

Address myAddress = config.get("key1").as(XmlParser.DEFAULT, Address.class).orElse(null);

Setting values in bulk​

The following methods can be used to bulk-load configuration values:

ConfigsetSection(String,List,Map)load(Map)load(Reader,boolean)load(String,boolean)

Changes can then be committed using the Config.commit() method.

In This Section​