KeyIndex Collections

@KeyIndex Collections

A collection of entities, each carrying a @KeyIndex field, can be 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.

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.writeKeyIndexCollection("accounts", Arrays.asList(
        new Account("alice", 100),
        new Account("bob", 50)), codec);

cfg.save();

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

List<Account> back = cfg.readKeyIndexCollection("accounts", Account.class, codec);
// back = [Account(alice, 100), Account(bob, 50)]

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.writeKeyIndexCollection("worlds", Arrays.asList(new World(uuid, "overworld")), codec);
List<World> worlds = cfg.readKeyIndexCollection("worlds", World.class, codec);   // uuid restored from the key

Issues & validation

• A collection of entities with no @KeyIndex, two @KeyIndex fields, or an unsupported @KeyIndex type is rejected with a BindException when you call writeKeyIndexCollection.
• On a lenient read, any per-entry problems (e.g. a body index value disagreeing with its key) are recorded and exposed via cfg.lastKeyIndexCollectionIssues().

List<LoadIssue> issues = cfg.lastKeyIndexCollectionIssues();   // from the most recent readKeyIndexCollection

readKeyIndexCollectionResult returns the list and its issues together in a BindResult<List<T>>, so the issues travel with the value instead of living in a getter a later read could overwrite.

BindResult<List<Account>> result = cfg.readKeyIndexCollectionResult("accounts", Account.class, codec);
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; the stateful lastKeyIndexCollectionIssues() still works and returns the same issues.

→ See also Entity Binding · Annotations