Package com.kazforge.jsonapi.mapping

Class IncludedResources

java.lang.Object
com.kazforge.jsonapi.mapping.IncludedResources
public final class IncludedResources extends Object
Independently bound included resources of a domain document envelope.

On an envelope, null represents an absent included member; a non-null instance whose resources() list is empty preserves a present "included": [] member.

resources() preserves wire order. find(ResourceIdentity) resolves a bound DTO instance by structured identity; resources carrying both id and lid are indexed under both ResourceIdentity.ofId(String, String) and ResourceIdentity.ofLid(String, String) keys pointing to the same instance.

Instances are immutable: the wire-order list and the identity index are defensively copied at construction, and mutating a construction-time source or a returned resources() list never changes wire order or find(ResourceIdentity) results.

Assemble instances with of(List, List). The identity index is derived from the identities declared for each wire-order position, so find(identity) can only return the DTO at the position that declared that identity: inconsistent states are unrepresentable. Duplicate identities across positions, length mismatches, and null elements are rejected at construction. The current backend readers build the declarations from validated documents through caller-configured Jackson, so wire order and identity lookup always agree.

  • Method Details

    • of

      public static IncludedResources of(List<Object> resources, List<Set<com.kazforge.jsonapi.core.model.ResourceIdentity>> identitiesByPosition)
      Creates an instance from wire-ordered bound DTOs and the identities declared for each wire-order position.

      identitiesByPosition must have exactly one entry per resource, in the same order. The identity index is derived from the declarations, so every declared identity resolves to the position that declared it and no identity can resolve to an undeclared position.

      All arguments are defensively copied.

      Throws:
      NullPointerException - when an argument, a resource, an identity set, or an identity is null
      IllegalArgumentException - when identitiesByPosition has a different size than resources, or the same identity is declared for more than one position

    • resources

      public List<Object> resources()
      Bound DTOs in wire order; unmodifiable.

    • find

      public Optional<Object> find(com.kazforge.jsonapi.core.model.ResourceIdentity identity)
      Returns the bound DTO indexed under the given identity, if any.