Package com.kazforge.jsonapi.jackson3

Class JsonApiResourceMapper

java.lang.Object

com.kazforge.jsonapi.jackson3.JsonApiResourceMapper

public final class JsonApiResourceMapper
extends Object

Maps annotated domain objects to JSON:API ResourceObject instances and documents.

Construct instances via JsonApiJackson3.resourceMapper(tools.jackson.databind.json.JsonMapper) or its overloads, never directly. The mapper is safe for concurrent use once created. Decorators supplied through a ResourceDecoratorRegistry are invoked during mapping and may be called concurrently; they must themselves be safe for concurrent invocation when the mapper is shared. Mapping uses Jackson's logical property model and caches resolved definitions by type and configuration identity. JSON:API annotations assign semantic roles; configured Jackson owns property discovery, visibility, external naming, mix-ins, creators, and value conversion. Unannotated Jackson-visible properties do not participate, except the conventional identifier whose Jackson external name is id. @JsonApiId maps only ResourceObject.id() and @JsonApiLocalId maps only ResourceObject.lid(); the two identity roles never fall back to each other.

Mapping is write-only: this mapper produces core model objects. Feed them to a JsonApiDocumentWriter for serialization. Read-side flat DTO binding is provided by JsonApiResourceBinder.

The convenience methods infer a root JavaType from the concrete runtime class. Use the overloads that accept a JavaType for a directly parameterized root such as Container<Thing>; the declared type is retained through mapping, relationship linkage, and compound inclusion. Concrete subclasses that bind a generic superclass can use the convenience methods when Jackson resolves those bindings. An unparameterized generic root fails at the mapped member that requires the missing declaration rather than inferring a type from runtime contents.

Compound inclusion is opt-in via RepresentationSelection and RepresentationPolicy on the mapper overloads that accept representation inputs. Relationship mapping alone never requests inclusion. Callers without an envelope pass null for the envelope argument.

Sparse fieldsets are applied only by toMappedDocument(Object, DocumentEnvelope, RepresentationSelection, RepresentationPolicy) and toMappedCollectionDocument(Iterable, DocumentEnvelope, RepresentationSelection, RepresentationPolicy). Those overloads return a MappedDocument carrying the identities of included resources whose inbound linkage was removed by an applied fieldset; a document writer composes that provenance into validation. The non-mapped representation overloads (with or without a declared JavaType) reject a non-empty fieldset map with MappingDiagnostic.FIELDSETS_REQUIRE_MAPPED_DOCUMENT.

For custom identifier conversion, supply an IdentifierConverter at construction time. The default converter delegates to Object.toString().

Method Summary

Modifier and Type	Method	Description
com.kazforge.jsonapi.core.model.JsonApiDocument	toCollectionDocument(Iterable<?> resources)	Maps domain objects to a resource-collection document without envelope members.
com.kazforge.jsonapi.core.model.JsonApiDocument	toCollectionDocument(Iterable<?> resources, @Nullable com.kazforge.jsonapi.document.DocumentEnvelope envelope)	Maps domain objects to a resource-collection document with optional envelope members.
com.kazforge.jsonapi.core.model.JsonApiDocument	toCollectionDocument(Iterable<?> resources, @Nullable com.kazforge.jsonapi.document.DocumentEnvelope envelope, com.kazforge.jsonapi.representation.RepresentationSelection selection, com.kazforge.jsonapi.representation.RepresentationPolicy policy)	Maps a primary collection to a document with optional envelope members and explicit compound inclusion from selection governed by policy.
com.kazforge.jsonapi.core.model.JsonApiDocument	toCollectionDocument(Iterable<?> resources, tools.jackson.databind.JavaType resourceType, @Nullable com.kazforge.jsonapi.document.DocumentEnvelope envelope)	Maps a homogeneous collection using a complete declared element type and optional envelope.
com.kazforge.jsonapi.core.model.JsonApiDocument	toCollectionDocument(Iterable<?> resources, tools.jackson.databind.JavaType resourceType, @Nullable com.kazforge.jsonapi.document.DocumentEnvelope envelope, com.kazforge.jsonapi.representation.RepresentationSelection selection, com.kazforge.jsonapi.representation.RepresentationPolicy policy)	Maps a homogeneous collection with explicit compound inclusion using the complete declared element type supplied by the caller.
com.kazforge.jsonapi.core.model.JsonApiDocument	toDocument(Object resource)	Maps a domain object to a single-resource document without envelope members.
com.kazforge.jsonapi.core.model.JsonApiDocument	toDocument(Object resource, @Nullable com.kazforge.jsonapi.document.DocumentEnvelope envelope)	Maps a domain object to a single-resource document with optional envelope members.
com.kazforge.jsonapi.core.model.JsonApiDocument	toDocument(Object resource, @Nullable com.kazforge.jsonapi.document.DocumentEnvelope envelope, com.kazforge.jsonapi.representation.RepresentationSelection selection, com.kazforge.jsonapi.representation.RepresentationPolicy policy)	Maps a domain object to a document with optional envelope members and explicit compound inclusion from selection governed by policy.
com.kazforge.jsonapi.core.model.JsonApiDocument	toDocument(Object resource, tools.jackson.databind.JavaType resourceType, @Nullable com.kazforge.jsonapi.document.DocumentEnvelope envelope)	Maps a domain object to a document using a complete declared type and optional envelope.
com.kazforge.jsonapi.core.model.JsonApiDocument	toDocument(Object resource, tools.jackson.databind.JavaType resourceType, @Nullable com.kazforge.jsonapi.document.DocumentEnvelope envelope, com.kazforge.jsonapi.representation.RepresentationSelection selection, com.kazforge.jsonapi.representation.RepresentationPolicy policy)	Maps a domain object to a document with explicit inclusion using the complete declared Jackson type supplied by the caller.
com.kazforge.jsonapi.mapping.MappedDocument	toMappedCollectionDocument(Iterable<?> resources, @Nullable com.kazforge.jsonapi.document.DocumentEnvelope envelope, com.kazforge.jsonapi.representation.RepresentationSelection selection, com.kazforge.jsonapi.representation.RepresentationPolicy policy)	Maps a primary collection with optional envelope members, compound inclusion, and sparse fieldsets from selection governed by policy.
com.kazforge.jsonapi.mapping.MappedDocument	toMappedCollectionDocument(Iterable<?> resources, tools.jackson.databind.JavaType resourceType, @Nullable com.kazforge.jsonapi.document.DocumentEnvelope envelope, com.kazforge.jsonapi.representation.RepresentationSelection selection, com.kazforge.jsonapi.representation.RepresentationPolicy policy)	Maps a homogeneous collection with inclusion and sparse fieldsets using a complete declared type.
com.kazforge.jsonapi.mapping.MappedDocument	toMappedCreateDocument(Object resource, @Nullable com.kazforge.jsonapi.document.DocumentEnvelope envelope, com.kazforge.jsonapi.representation.RepresentationSelection selection, com.kazforge.jsonapi.representation.RepresentationPolicy policy)	Maps a domain object for create-request authoring with optional envelope members, compound inclusion, and sparse fieldsets from selection governed by policy.
com.kazforge.jsonapi.mapping.MappedDocument	toMappedCreateDocument(Object resource, tools.jackson.databind.JavaType resourceType, @Nullable com.kazforge.jsonapi.document.DocumentEnvelope envelope, com.kazforge.jsonapi.representation.RepresentationSelection selection, com.kazforge.jsonapi.representation.RepresentationPolicy policy)	Maps a domain object for create-request authoring using a complete declared type.
com.kazforge.jsonapi.mapping.MappedDocument	toMappedDocument(Object resource, @Nullable com.kazforge.jsonapi.document.DocumentEnvelope envelope, com.kazforge.jsonapi.representation.RepresentationSelection selection, com.kazforge.jsonapi.representation.RepresentationPolicy policy)	Maps a domain object with optional envelope members, compound inclusion, and sparse fieldsets from selection governed by policy.
com.kazforge.jsonapi.mapping.MappedDocument	toMappedDocument(Object resource, tools.jackson.databind.JavaType resourceType, @Nullable com.kazforge.jsonapi.document.DocumentEnvelope envelope, com.kazforge.jsonapi.representation.RepresentationSelection selection, com.kazforge.jsonapi.representation.RepresentationPolicy policy)	Maps a domain object with inclusion and sparse fieldsets using a complete declared type.
com.kazforge.jsonapi.core.model.ResourceObject	toResource(Object resource)	Maps a domain object using a Jackson type inferred from its concrete runtime class.
com.kazforge.jsonapi.core.model.ResourceObject	toResource(Object resource, tools.jackson.databind.JavaType resourceType)	Maps a domain object using the complete declared Jackson type supplied by the caller.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

toResource

public com.kazforge.jsonapi.core.model.ResourceObject toResource(Object resource)

Maps a domain object using a Jackson type inferred from its concrete runtime class.

toResource

public com.kazforge.jsonapi.core.model.ResourceObject toResource(Object resource,
 tools.jackson.databind.JavaType resourceType)

Maps a domain object using the complete declared Jackson type supplied by the caller.

toDocument

public com.kazforge.jsonapi.core.model.JsonApiDocument toDocument(Object resource)

Maps a domain object to a single-resource document without envelope members.

toDocument

public com.kazforge.jsonapi.core.model.JsonApiDocument toDocument(Object resource,
 @Nullable com.kazforge.jsonapi.document.DocumentEnvelope envelope)

Maps a domain object to a single-resource document with optional envelope members.

toDocument

public com.kazforge.jsonapi.core.model.JsonApiDocument toDocument(Object resource,
 tools.jackson.databind.JavaType resourceType,
 @Nullable com.kazforge.jsonapi.document.DocumentEnvelope envelope)

Maps a domain object to a document using a complete declared type and optional envelope.

toDocument

public com.kazforge.jsonapi.core.model.JsonApiDocument toDocument(Object resource,
 @Nullable com.kazforge.jsonapi.document.DocumentEnvelope envelope,
 com.kazforge.jsonapi.representation.RepresentationSelection selection,
 com.kazforge.jsonapi.representation.RepresentationPolicy policy)

Maps a domain object to a document with optional envelope members and explicit compound inclusion from selection governed by policy. Rejects a non-empty fieldset map; use toMappedDocument(java.lang.Object, com.kazforge.jsonapi.document.DocumentEnvelope, com.kazforge.jsonapi.representation.RepresentationSelection, com.kazforge.jsonapi.representation.RepresentationPolicy) when applying sparse fieldsets.

toDocument

public com.kazforge.jsonapi.core.model.JsonApiDocument toDocument(Object resource,
 tools.jackson.databind.JavaType resourceType,
 @Nullable com.kazforge.jsonapi.document.DocumentEnvelope envelope,
 com.kazforge.jsonapi.representation.RepresentationSelection selection,
 com.kazforge.jsonapi.representation.RepresentationPolicy policy)

Maps a domain object to a document with explicit inclusion using the complete declared Jackson type supplied by the caller.

toMappedDocument

public com.kazforge.jsonapi.mapping.MappedDocument toMappedDocument(Object resource,
 @Nullable com.kazforge.jsonapi.document.DocumentEnvelope envelope,
 com.kazforge.jsonapi.representation.RepresentationSelection selection,
 com.kazforge.jsonapi.representation.RepresentationPolicy policy)

Maps a domain object with optional envelope members, compound inclusion, and sparse fieldsets from selection governed by policy. Returns a MappedDocument whose linkage exemptions name included resources whose linking relationship was omitted by an applied fieldset while inclusion still traversed it.

toMappedDocument

public com.kazforge.jsonapi.mapping.MappedDocument toMappedDocument(Object resource,
 tools.jackson.databind.JavaType resourceType,
 @Nullable com.kazforge.jsonapi.document.DocumentEnvelope envelope,
 com.kazforge.jsonapi.representation.RepresentationSelection selection,
 com.kazforge.jsonapi.representation.RepresentationPolicy policy)

Maps a domain object with inclusion and sparse fieldsets using a complete declared type.

toMappedCreateDocument

public com.kazforge.jsonapi.mapping.MappedDocument toMappedCreateDocument(Object resource,
 @Nullable com.kazforge.jsonapi.document.DocumentEnvelope envelope,
 com.kazforge.jsonapi.representation.RepresentationSelection selection,
 com.kazforge.jsonapi.representation.RepresentationPolicy policy)

Maps a domain object for create-request authoring with optional envelope members, compound inclusion, and sparse fieldsets from selection governed by policy. Unlike toMappedDocument(java.lang.Object, com.kazforge.jsonapi.document.DocumentEnvelope, com.kazforge.jsonapi.representation.RepresentationSelection, com.kazforge.jsonapi.representation.RepresentationPolicy), a primary resource with neither id nor lid value maps with both members absent instead of failing; core CREATE_REQUEST validation owns that leniency when the document is written. Compound inclusion likewise traverses an identity-less primary while included resources still require identity, and related linkage uses normal extraction. Returns a MappedDocument carrying sparse-fieldset linkage provenance like toMappedDocument(java.lang.Object, com.kazforge.jsonapi.document.DocumentEnvelope, com.kazforge.jsonapi.representation.RepresentationSelection, com.kazforge.jsonapi.representation.RepresentationPolicy).

toMappedCreateDocument

public com.kazforge.jsonapi.mapping.MappedDocument toMappedCreateDocument(Object resource,
 tools.jackson.databind.JavaType resourceType,
 @Nullable com.kazforge.jsonapi.document.DocumentEnvelope envelope,
 com.kazforge.jsonapi.representation.RepresentationSelection selection,
 com.kazforge.jsonapi.representation.RepresentationPolicy policy)

Maps a domain object for create-request authoring using a complete declared type.

toCollectionDocument

public com.kazforge.jsonapi.core.model.JsonApiDocument toCollectionDocument(Iterable<?> resources)

Maps domain objects to a resource-collection document without envelope members.

toCollectionDocument

public com.kazforge.jsonapi.core.model.JsonApiDocument toCollectionDocument(Iterable<?> resources,
 @Nullable com.kazforge.jsonapi.document.DocumentEnvelope envelope)

Maps domain objects to a resource-collection document with optional envelope members.

toCollectionDocument

public com.kazforge.jsonapi.core.model.JsonApiDocument toCollectionDocument(Iterable<?> resources,
 tools.jackson.databind.JavaType resourceType,
 @Nullable com.kazforge.jsonapi.document.DocumentEnvelope envelope)

Maps a homogeneous collection using a complete declared element type and optional envelope.

toCollectionDocument

public com.kazforge.jsonapi.core.model.JsonApiDocument toCollectionDocument(Iterable<?> resources,
 @Nullable com.kazforge.jsonapi.document.DocumentEnvelope envelope,
 com.kazforge.jsonapi.representation.RepresentationSelection selection,
 com.kazforge.jsonapi.representation.RepresentationPolicy policy)

Maps a primary collection to a document with optional envelope members and explicit compound inclusion from selection governed by policy. The iterable is materialized once and reused for type validation, primary mapping, and inclusion traversal. Rejects a non-empty fieldset map; use toMappedCollectionDocument(java.lang.Iterable<?>, com.kazforge.jsonapi.document.DocumentEnvelope, com.kazforge.jsonapi.representation.RepresentationSelection, com.kazforge.jsonapi.representation.RepresentationPolicy) when applying sparse fieldsets.

toCollectionDocument

public com.kazforge.jsonapi.core.model.JsonApiDocument toCollectionDocument(Iterable<?> resources,
 tools.jackson.databind.JavaType resourceType,
 @Nullable com.kazforge.jsonapi.document.DocumentEnvelope envelope,
 com.kazforge.jsonapi.representation.RepresentationSelection selection,
 com.kazforge.jsonapi.representation.RepresentationPolicy policy)

Maps a homogeneous collection with explicit compound inclusion using the complete declared element type supplied by the caller.

toMappedCollectionDocument

public com.kazforge.jsonapi.mapping.MappedDocument toMappedCollectionDocument(Iterable<?> resources,
 @Nullable com.kazforge.jsonapi.document.DocumentEnvelope envelope,
 com.kazforge.jsonapi.representation.RepresentationSelection selection,
 com.kazforge.jsonapi.representation.RepresentationPolicy policy)

Maps a primary collection with optional envelope members, compound inclusion, and sparse fieldsets from selection governed by policy. The iterable is materialized once. Returns a MappedDocument whose linkage exemptions fold fieldset-removed linking relationships across primary and included selective writes.

toMappedCollectionDocument

public com.kazforge.jsonapi.mapping.MappedDocument toMappedCollectionDocument(Iterable<?> resources,
 tools.jackson.databind.JavaType resourceType,
 @Nullable com.kazforge.jsonapi.document.DocumentEnvelope envelope,
 com.kazforge.jsonapi.representation.RepresentationSelection selection,
 com.kazforge.jsonapi.representation.RepresentationPolicy policy)

Maps a homogeneous collection with inclusion and sparse fieldsets using a complete declared type.