Annotations

Annotations

FinalConfig's binding annotations live in br.com.finalcraft.finalconfig.annotation. They layer on top of plain Jackson, so native @Json* annotations keep working too (see Entity Binding).

@Key — rename + case transform

Renames a field's key and/or applies a case transform. Resolution order: @Key → @JsonProperty → field name.

@Key(transformCase = KeyTransformCase.KEBAB_CASE)
public int maxPoolSize;          // -> "max-pool-size"

@Key("custom-host")
public String host;              // -> "custom-host"

@Key(transformCase = KeyTransformCase.SNAKE_CASE)
public int ttlSeconds;           // -> "ttl_seconds"

KeyTransformCase: NONE, KEBAB_CASE, SNAKE_CASE, CAMEL_CASE, UPPER_CAMEL_CASE.

@Comment — documentation, two modes

On a field it seeds a block comment; on a type it seeds the file header. String[] value = multi-line.

@Comment({"First line", "second line"})        // OVERRIDE (default): re-seeded every save
public int timeout = 30;

@Comment(value = "tune me", mode = CommentMode.SET_IF_ABSENT)   // written only if absent
public int retries = 3;

• CommentMode.OVERRIDE (default) — a doc fix in code propagates to existing files.
• CommentMode.SET_IF_ABSENT — a user-edited comment wins.
• A class-level @Comment becomes the file header (use SET_IF_ABSENT to preserve a user's header).
• On a NONE-fidelity codec the seed is a no-op (no comment emitted). See Default Values & Comments.

@Section — place a flat field under a nested path

@Section("database.pool")
@Key(transformCase = KeyTransformCase.KEBAB_CASE)
public int maxSize = 50;          // written at database.pool.max-size, surfaced back on read

Top-level fields only. A flat field is relocated to the nested path on write and brought back on read. A @Section on a field of a nested POJO is not relocated. With sections present, the merge forces ObsoletePolicy.PRESERVE for that type (the schema is flat while the tree is nested).

@Id — collection indexing

Marks the field whose value becomes the section key for writeIdCollection / readIdCollection.

class Account {
    @Id public String name;
    public int balance;
}

Exactly one @Id per class; valid types are String, the boxed/primitive numerics, boolean, and UUID. See @Id Collections.

@PostInject — run after binding

A method (no args, or a single List<LoadIssue>) invoked once after a bind completes. Use it to validate or derive state.

class Cfg {
    public int port = 25565;

    @PostInject
    void validate() {
        if (port < 1 || port > 65535) throw new IllegalStateException("bad port");
    }

    @PostInject
    void check(List<LoadIssue> issues) {   // receives the lenient-bind issues
        if (!issues.isEmpty()) log.warn("config had {} issues", issues.size());
    }
}

• Inherited @PostInject methods (super + sub) all run, de-duplicated by method name.
• An exception thrown inside is wrapped in a BindException (a BindException thrown inside propagates as-is).

→ See also Entity Binding · @Id Collections