API Cheat Sheet

API Cheat Sheet

A one-page reference. See the linked pages for detail.

Open / lifecycle — Lifecycle, Reload & Watching

Config cfg = Config.open(path, codec);   // ABSENT / EMPTY / PARSE_FAILED_BACKED_UP / OK
Config cfg = Config.open("settings.yml");             // codec from the extension (String|File|Path)
Config cfg = Config.open(path, codec, Backend.Durability.FSYNC);  // OS_CACHE (default) | FSYNC
cfg.save();  cfg.saveIfDirty();  cfg.saveAsync();
cfg.reload();                            // OK / ABSENT / PARSE_FAILED_KEPT
cfg.onReload(runnable).withAutoReload(Duration.ofSeconds(2));  cfg.stopAutoReload();
cfg.withAutoReload(Duration.ofSeconds(2), true);      // also hash content (catch same-size edits)
cfg.close();                             // AutoCloseable
cfg.lastLoadStatus();  cfg.isDivergedFromDisk();  cfg.getLastModified();  cfg.hasBeenModified();

open(String|File|Path) derives the codec from the file-name extension and throws CodecException on a missing/unknown one — it never guesses. Pass a codec to override.

Set / remove — The Dynamic API

cfg.setValue(path, value);               // null value deletes; auto-vivifies objects
cfg.setValue(path, value, comment);
cfg.removeValue(path);               // boolean

Typed getters

getString  getInt  getLong  getDouble  getBoolean  getStringList  getList  getUUID   // + (path, default) forms
getValue(path)        // unwrapped scalar / node
getNode(path)         // raw JsonNode or null

Keys / sections

cfg.contains(path);
cfg.getKeys();  cfg.getKeys(path);  cfg.getKeys(path, true /*deep*/);
cfg.getConfigSection(path);          // always a view; use cfg.contains(path) for existence
cfg.getRoot();                       // live ObjectNode escape hatch

Defaults & comments — Default Values & Comments

cfg.getOrSetValueIfAbsent(path, def);
cfg.getOrSetValueIfAbsent(path, def, comment);   // seeds comment if absent
cfg.setComment(path, text);                     // authoritative (CommentType.BLOCK default)
cfg.setDefaultComment(path, text);              // set-if-absent
cfg.getComment(path);  cfg.getComment(path, CommentType.SIDE);
cfg.migrateKey(oldPath, newPath);               // moves data + the key's whole comment subtree

Binding — Entity Binding

T pojo = cfg.loadAs(Type.class, codec);                 // bind whole tree + @PostLoad
T sub  = cfg.getValue("a.b", Type.class);            // bind a subtree (codec from open())
T sub  = cfg.getValue("a.b", Type.class, codec);    // ... or an explicit codec
EntityBinder<T> b = cfg.bind(Type.class[, codec][, opts]); // b.read(""); b.write("", pojo); b.lastLoadIssues();
cfg.setValue(path, pojo);                               // a POJO setValue MERGES into the tree

BindResult<T> r = cfg.loadAsResult(Type.class, codec);  // also: b.readResult("")
r.value();  r.issues();  r.hasIssues();                 // issues travel with the value

BindOptions.defaults()
    .withCoercion(BindOptions.Coercion.STRICT)          // or LENIENT (default)
    .withObsoletePolicy(BindOptions.ObsoletePolicy.COMMENT_OUT);  // PRESERVE (default) | REMOVE | COMMENT_OUT

getValue's 2-arg form needs a codec from open() (else IllegalStateException); an absent path binds the type's defaults, a root path (""/null) binds the whole tree. COMMENT_OUT keeps the obsolete key but stamps a deprecation block comment — LOSSLESS codecs only (degrades to PRESERVE on a NONE/LOSSY codec).

@Id collections — @Id Collections

cfg.writeIdCollection(path, collection, codec);
List<T> back = cfg.readIdCollection(path, Type.class, codec);
BindResult<List<T>> r = cfg.readIdCollectionResult(path, Type.class, codec);  // issues with the list
cfg.lastIdCollectionIssues();

Annotations — Annotations

@Key(value, transformCase)   @Comment(value, mode)   @Section("a.b")   @Id   @PostLoad
KeyTransformCase.{NONE, KEBAB_CASE, SNAKE_CASE, CAMEL_CASE, UPPER_CAMEL_CASE}
CommentMode.{OVERRIDE, SET_IF_ABSENT}

@JsonNaming(KeyCaseStrategy.Kebab.class)   // class-wide case (or .Snake); a field @Key overrides it
@JsonNaming(KeyCaseStrategy.Snake.class)

Codecs — Codecs & Formats

new YamlCodec()   // LOSSLESS   yml, yaml
new JsonCodec()   // NONE       json
new TomlCodec()   // LOSSLESS   toml   (no null)
new JsoncCodec()  // LOSSY      jsonc

CodecRegistry.defaults().forFile("a.toml");   // resolve by extension