Package com.kazforge.jsonapi.mapping

Interface ResourceDecorator<T>

Type Parameters:
T - the application domain type
Functional Interface:
This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.
@FunctionalInterface public interface ResourceDecorator<T>
Backend-independent application-provided decoration for JSON:API resource links during domain writes. A registered decorator is invoked by the shared backend-neutral decoration phase after the basic write; each adapter resolves the effective runtime type and supplies the configured registry through caller-configured construction.

Decorators are application/runtime collaborators, not domain-model metadata. They are supplied through mapper construction so dependency-injected, request-aware, or tenant-aware link builders remain possible without the library knowing how dependencies are produced. They are not declared on JSON:API annotations.

A decorator may contribute only:

  • ResourceObject.links, and
  • Relationship.links for already-mapped relationships
All other resource semantics — type, id/lid, attributes, relationship data/linkage, resource meta, relationship meta, identifier meta, included membership, sparse-fieldset provenance, and document-level links — remain owned by normal mapping.

Relationship decoration is keyed by the logical application-property identity, i.e. the Jackson logical property name (the internal name derived from the Java field/record component/getter, e.g. "comments"). The mapper resolves that identity through the configured-Jackson external property name (for example @JsonProperty("article-comments")) and applies the decoration under the final JSON:API wire member name automatically. Decorators must not repeat the external or wire name.

Returning null or a decoration containing null keys/values is invalid and fails with a stable mapping diagnostic. Unknown or non-relationship targets also fail deterministically. An empty decoration (ResourceDecoration.empty()) means no decoration.

Decorators are invoked during mapping and may be called concurrently when a JsonApiResourceMapper is shared. A decorator supplied to a shared mapper must be safe for concurrent invocation; the mapper and its ResourceDecoratorRegistry do not provide per-call isolation.