KeyIndex Collections

@KeyIndex Collections

A collection of entities, each carrying a @KeyIndex field, is stored as a section keyed by the index value instead of a positional array. The index value becomes the key and is omitted from each entry's body; on read the section key is the sole authority for the index.

This is automatic: setValue detects that the element type carries @KeyIndex and writes the keyed layout, and getList detects it (plus the stored node's shape) and reads it back. There are no dedicated methods.

Write & read

class Account {
    @KeyIndex public String name;
    public int balance;

    public Account() {}
    public Account(String name, int balance) { this.name = name; this.balance = balance; }
}

cfg.setValue("accounts", Arrays.asList(
        new Account("alice", 100),
        new Account("bob", 50)));   // auto key-major: Account carries @KeyIndex

cfg.save();

accounts:
  alice:
    balance: 100
  bob:
    balance: 50

List<Account> back = cfg.getList("accounts", Account.class);
// back = [Account(alice, 100), Account(bob, 50)] — ids restored from the section keys

A collection whose element type does not carry @KeyIndex is stored as an ordinary array. On read, getList discriminates by the stored node's shape: an object section is read key-major, a plain array is read positionally — so a @KeyIndex type stored (legacy) as an array still binds, ids coming from the body.

Why a keyed section

• Stable identity. Entries are addressed by their index value, not position — reordering the file or hand-editing one entry doesn't disturb the others.
• Readable & diffable. accounts.alice.balance is a real path you can read with the dynamic API.
• The key wins. On read, the section key is the index value; a stray name inside a body is ignored.

@KeyIndex types

@KeyIndex may be String, a boxed/primitive numeric (int, long, …), boolean, or UUID. The value is rendered as the key token and cast back on read.

class World { @KeyIndex public UUID id; public String name; }
cfg.setValue("worlds", Arrays.asList(new World(uuid, "overworld")));
List<World> worlds = cfg.getList("worlds", World.class);   // uuid restored from the key

Issues & validation

• A duplicate index value in the collection (two entries with the same key), or a type with two @KeyIndex fields or an unsupported @KeyIndex type, is rejected with a BindException on setValue.
• On a lenient read, a per-entry problem (e.g. a body index value disagreeing with its section key, which the key wins) is recorded as a LoadIssue. The plain getList discards those issues; getListResult returns them with the list.

BindResult<List<Account>> result = cfg.getListResult("accounts", Account.class);
List<Account> back = result.value();
if (result.hasIssues()) {
    for (LoadIssue issue : result.issues()) { /* report or log */ }
}

result.issues() is an unmodifiable snapshot taken for that read.

→ See also Entity Binding · Annotations