Package com.kazforge.jsonapi.jackson3

Class JsonApiJackson3

java.lang.Object
com.kazforge.jsonapi.jackson3.JsonApiJackson3
public final class JsonApiJackson3 extends Object
Factory for Jackson 3 JSON:API document writers, readers, resource mappers, flat DTO binders, and presence-aware PATCH readers.

Callers supply an already-configured JsonMapper. Each canonical factory accepts that mapper first, followed by the policy, context, and collaborators required by its capability. Convenience factories select documented defaults and delegate to the canonical seam; mapper builders are intentionally not accepted. Factory construction never mutates or replaces the caller's configuration in place. Token-driven document reading uses the supplied mapper directly. Capabilities that need adapter-specific modules or isolated introspection state derive a mapper via JsonMapper.rebuild(). Public surface consists of Jackson3JsonApi, JsonApiDocumentWriter, JsonApiDocumentReader, JsonApiResourceMapper, JsonApiResourceBinder, JsonApiDomainDocumentReader, JsonApiPatchCommandReader, and JsonApiPatchDtoReader.

Ordinary application code should prefer the Level-1 configured runtime: jsonApi(JsonMapper) for documented defaults or builder(JsonMapper) for coherent application-lifetime configuration, including an optional resource-write jsonapi.version default. The capability factories below remain the advanced mechanism/control seams.

  • Method Summary

    Modifier and Type
    Method
    Description
    static Jackson3JsonApi.Builder
    builder(tools.jackson.databind.json.JsonMapper base)
    Returns a builder for a Level-1 configured runtime over the given configured mapper.
    static JsonApiDomainDocumentReader
    domainDocumentReader(tools.jackson.databind.json.JsonMapper base, com.kazforge.jsonapi.document.DocumentReadContext context, com.kazforge.jsonapi.mapping.ResourceTypeRegistry registry)
    Returns a typed domain envelope reader with default identifier conversion and no custom relationship linkage mappers.
    static JsonApiDomainDocumentReader
    domainDocumentReader(tools.jackson.databind.json.JsonMapper base, com.kazforge.jsonapi.document.DocumentReadContext context, com.kazforge.jsonapi.mapping.ResourceTypeRegistry registry, com.kazforge.jsonapi.mapping.IdentifierConverter identifierConverter)
    Returns a typed domain envelope reader with the given identifier converter and no custom relationship linkage mappers.
    static JsonApiDomainDocumentReader
    domainDocumentReader(tools.jackson.databind.json.JsonMapper base, com.kazforge.jsonapi.document.DocumentReadContext context, com.kazforge.jsonapi.mapping.ResourceTypeRegistry registry, com.kazforge.jsonapi.mapping.IdentifierConverter identifierConverter, Map<Class<?>,RelationshipLinkageMapper> linkageMappers)
    Returns a typed domain envelope reader with the given identifier converter and relationship linkage mappers keyed by relationship target class.
    static Jackson3JsonApi
    jsonApi(tools.jackson.databind.json.JsonMapper base)
    Returns a Level-1 configured runtime with documented defaults: default identifier conversion, no custom linkage mappers, the default representation policy, no resource decorators, and no resource-write jsonapi.version default.
    static JsonApiPatchCommandReader
    patchCommandReader(tools.jackson.databind.json.JsonMapper base)
    Returns a presence-aware PATCH command reader with ValidationContext.defaults(), default identifier conversion, and no custom relationship linkage mappers.
    static JsonApiPatchCommandReader
    patchCommandReader(tools.jackson.databind.json.JsonMapper base, com.kazforge.jsonapi.core.aggregate.ValidationContext validationContext)
    Returns a presence-aware PATCH command reader with the given validation context, default identifier conversion, and no custom relationship linkage mappers.
    static JsonApiPatchCommandReader
    patchCommandReader(tools.jackson.databind.json.JsonMapper base, com.kazforge.jsonapi.core.aggregate.ValidationContext validationContext, com.kazforge.jsonapi.mapping.IdentifierConverter identifierConverter)
    Returns a presence-aware PATCH command reader with the given validation context and identifier converter, and no custom relationship linkage mappers.
    static JsonApiPatchCommandReader
    patchCommandReader(tools.jackson.databind.json.JsonMapper base, com.kazforge.jsonapi.core.aggregate.ValidationContext validationContext, com.kazforge.jsonapi.mapping.IdentifierConverter identifierConverter, Map<Class<?>,RelationshipLinkageMapper> linkageMappers)
    Returns a presence-aware PATCH command reader with the given validation context, identifier converter, and relationship linkage mappers keyed by relationship target class.
    static JsonApiPatchDtoReader
    patchDtoReader(tools.jackson.databind.json.JsonMapper base)
    Returns a direct typed PATCH DTO reader with ValidationContext.defaults(), default identifier conversion, and no custom relationship linkage mappers.
    static JsonApiPatchDtoReader
    patchDtoReader(tools.jackson.databind.json.JsonMapper base, com.kazforge.jsonapi.core.aggregate.ValidationContext validationContext)
    Returns a direct typed PATCH DTO reader with the given validation context, default identifier conversion, and no custom relationship linkage mappers.
    static JsonApiPatchDtoReader
    patchDtoReader(tools.jackson.databind.json.JsonMapper base, com.kazforge.jsonapi.core.aggregate.ValidationContext validationContext, com.kazforge.jsonapi.mapping.IdentifierConverter identifierConverter)
    Returns a direct typed PATCH DTO reader with the given validation context and identifier converter, and no custom relationship linkage mappers.
    static JsonApiPatchDtoReader
    patchDtoReader(tools.jackson.databind.json.JsonMapper base, com.kazforge.jsonapi.core.aggregate.ValidationContext validationContext, com.kazforge.jsonapi.mapping.IdentifierConverter identifierConverter, Map<Class<?>,RelationshipLinkageMapper> linkageMappers)
    Returns a direct typed PATCH DTO reader with the given validation context, identifier converter, and relationship linkage mappers keyed by relationship target class.
    static JsonApiDocumentReader
    reader(tools.jackson.databind.json.JsonMapper base, com.kazforge.jsonapi.document.DocumentReadContext context)
    Returns a reader bound to the given read context.
    static JsonApiResourceBinder
    resourceBinder(tools.jackson.databind.json.JsonMapper base)
    Returns a flat DTO binder with default identifier conversion and no custom relationship linkage mappers.
    static JsonApiResourceBinder
    resourceBinder(tools.jackson.databind.json.JsonMapper base, com.kazforge.jsonapi.mapping.IdentifierConverter identifierConverter)
    Returns a flat DTO binder with the given identifier converter and no custom relationship linkage mappers.
    static JsonApiResourceBinder
    resourceBinder(tools.jackson.databind.json.JsonMapper base, com.kazforge.jsonapi.mapping.IdentifierConverter identifierConverter, Map<Class<?>,RelationshipLinkageMapper> linkageMappers)
    Returns a flat DTO binder with the given identifier converter and relationship linkage mappers keyed by relationship target class.
    static JsonApiResourceMapper
    resourceMapper(tools.jackson.databind.json.JsonMapper base)
    Returns a resource mapper with default identifier conversion.
    static JsonApiResourceMapper
    resourceMapper(tools.jackson.databind.json.JsonMapper base, com.kazforge.jsonapi.mapping.IdentifierConverter identifierConverter)
    Returns a resource mapper with the given identifier converter.
    static JsonApiResourceMapper
    resourceMapper(tools.jackson.databind.json.JsonMapper base, com.kazforge.jsonapi.mapping.IdentifierConverter identifierConverter, com.kazforge.jsonapi.mapping.ResourceDecoratorRegistry decorators)
    Returns a resource mapper with the given identifier converter and decoration registry.
    static JsonApiResourceMapper
    resourceMapper(tools.jackson.databind.json.JsonMapper base, com.kazforge.jsonapi.mapping.ResourceDecoratorRegistry decorators)
    Returns a resource mapper with default identifier conversion and the given decoration registry.
    static JsonApiDocumentWriter
    writer(tools.jackson.databind.json.JsonMapper base)
    Returns a writer that validates with ValidationContext.defaults() then serializes documents using a derived codec-configured mapper.
    static JsonApiDocumentWriter
    writer(tools.jackson.databind.json.JsonMapper base, com.kazforge.jsonapi.core.aggregate.ValidationContext context)
    Returns a writer that validates with the given context then serializes documents using a derived codec-configured mapper.

    Methods inherited from class java.lang.Object

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

  • Method Details

    • jsonApi

      public static Jackson3JsonApi jsonApi(tools.jackson.databind.json.JsonMapper base)
      Returns a Level-1 configured runtime with documented defaults: default identifier conversion, no custom linkage mappers, the default representation policy, no resource decorators, and no resource-write jsonapi.version default.

    • builder

      public static Jackson3JsonApi.Builder builder(tools.jackson.databind.json.JsonMapper base)
      Returns a builder for a Level-1 configured runtime over the given configured mapper. Only coherent application-lifetime configuration belongs on the builder; request-scoped values stay per-operation arguments on the resulting runtime.

    • writer

      public static JsonApiDocumentWriter writer(tools.jackson.databind.json.JsonMapper base)
      Returns a writer that validates with ValidationContext.defaults() then serializes documents using a derived codec-configured mapper.

    • writer

      public static JsonApiDocumentWriter writer(tools.jackson.databind.json.JsonMapper base, com.kazforge.jsonapi.core.aggregate.ValidationContext context)
      Returns a writer that validates with the given context then serializes documents using a derived codec-configured mapper.

    • reader

      public static JsonApiDocumentReader reader(tools.jackson.databind.json.JsonMapper base, com.kazforge.jsonapi.document.DocumentReadContext context)
      Returns a reader bound to the given read context. Decoding is token-driven and does not use document serializers, so the caller mapper is used as-is.

    • resourceMapper

      public static JsonApiResourceMapper resourceMapper(tools.jackson.databind.json.JsonMapper base)
      Returns a resource mapper with default identifier conversion. Derives a new mapper via JsonMapper.rebuild() and never mutates the caller's mapper.

    • resourceMapper

      public static JsonApiResourceMapper resourceMapper(tools.jackson.databind.json.JsonMapper base, com.kazforge.jsonapi.mapping.IdentifierConverter identifierConverter)
      Returns a resource mapper with the given identifier converter. Derives a new mapper via JsonMapper.rebuild() and never mutates the caller's mapper.

    • resourceMapper

      public static JsonApiResourceMapper resourceMapper(tools.jackson.databind.json.JsonMapper base, com.kazforge.jsonapi.mapping.ResourceDecoratorRegistry decorators)
      Returns a resource mapper with default identifier conversion and the given decoration registry. Derives a new mapper via JsonMapper.rebuild() and never mutates the caller's mapper.

      Relationship decoration is keyed by the mapped property identity (Jackson logical name), not the wire name; the mapper follows configured-Jackson renaming automatically.

    • resourceMapper

      public static JsonApiResourceMapper resourceMapper(tools.jackson.databind.json.JsonMapper base, com.kazforge.jsonapi.mapping.IdentifierConverter identifierConverter, com.kazforge.jsonapi.mapping.ResourceDecoratorRegistry decorators)
      Returns a resource mapper with the given identifier converter and decoration registry. Derives a new mapper via JsonMapper.rebuild() and never mutates the caller's mapper.

      Decorators add only ResourceObject.links and Relationship.links for mapped mapped relationships. They never replace type/id/attributes/linkage/meta/inclusion or resurrect a fieldset-omitted relationship.

    • resourceBinder

      public static JsonApiResourceBinder resourceBinder(tools.jackson.databind.json.JsonMapper base)
      Returns a flat DTO binder with default identifier conversion and no custom relationship linkage mappers. Derives a new mapper via JsonMapper.rebuild() and never mutates the caller's mapper.

    • resourceBinder

      public static JsonApiResourceBinder resourceBinder(tools.jackson.databind.json.JsonMapper base, com.kazforge.jsonapi.mapping.IdentifierConverter identifierConverter)
      Returns a flat DTO binder with the given identifier converter and no custom relationship linkage mappers. Derives a new mapper via JsonMapper.rebuild() and never mutates the caller's mapper.

    • resourceBinder

      public static JsonApiResourceBinder resourceBinder(tools.jackson.databind.json.JsonMapper base, com.kazforge.jsonapi.mapping.IdentifierConverter identifierConverter, Map<Class<?>,RelationshipLinkageMapper> linkageMappers)
      Returns a flat DTO binder with the given identifier converter and relationship linkage mappers keyed by relationship target class. Derives a new mapper via JsonMapper.rebuild() and never mutates the caller's mapper.

    • domainDocumentReader

      public static JsonApiDomainDocumentReader domainDocumentReader(tools.jackson.databind.json.JsonMapper base, com.kazforge.jsonapi.document.DocumentReadContext context, com.kazforge.jsonapi.mapping.ResourceTypeRegistry registry)
      Returns a typed domain envelope reader with default identifier conversion and no custom relationship linkage mappers. Document decoding/validation behaves exactly like reader(JsonMapper, DocumentReadContext); primary and included resources bind through the flat DTO binder after a ResourceTypeRegistry lookup, using a mapper derived via JsonMapper.rebuild() that never mutates the caller's mapper.

    • domainDocumentReader

      public static JsonApiDomainDocumentReader domainDocumentReader(tools.jackson.databind.json.JsonMapper base, com.kazforge.jsonapi.document.DocumentReadContext context, com.kazforge.jsonapi.mapping.ResourceTypeRegistry registry, com.kazforge.jsonapi.mapping.IdentifierConverter identifierConverter)
      Returns a typed domain envelope reader with the given identifier converter and no custom relationship linkage mappers. Derives a new mapper via JsonMapper.rebuild() and never mutates the caller's mapper.

    • domainDocumentReader

      public static JsonApiDomainDocumentReader domainDocumentReader(tools.jackson.databind.json.JsonMapper base, com.kazforge.jsonapi.document.DocumentReadContext context, com.kazforge.jsonapi.mapping.ResourceTypeRegistry registry, com.kazforge.jsonapi.mapping.IdentifierConverter identifierConverter, Map<Class<?>,RelationshipLinkageMapper> linkageMappers)
      Returns a typed domain envelope reader with the given identifier converter and relationship linkage mappers keyed by relationship target class. Derives a new mapper via JsonMapper.rebuild() and never mutates the caller's mapper.

    • patchCommandReader

      public static JsonApiPatchCommandReader patchCommandReader(tools.jackson.databind.json.JsonMapper base)
      Returns a presence-aware PATCH command reader with ValidationContext.defaults(), default identifier conversion, and no custom relationship linkage mappers. Forces DocumentUsage.UPDATE_REQUEST and PrimaryDataKind.RESOURCE for validate-on-read.

    • patchCommandReader

      public static JsonApiPatchCommandReader patchCommandReader(tools.jackson.databind.json.JsonMapper base, com.kazforge.jsonapi.core.aggregate.ValidationContext validationContext)
      Returns a presence-aware PATCH command reader with the given validation context, default identifier conversion, and no custom relationship linkage mappers. Forces update-request usage while preserving other context fields (including expected endpoint identity).

    • patchCommandReader

      public static JsonApiPatchCommandReader patchCommandReader(tools.jackson.databind.json.JsonMapper base, com.kazforge.jsonapi.core.aggregate.ValidationContext validationContext, com.kazforge.jsonapi.mapping.IdentifierConverter identifierConverter)
      Returns a presence-aware PATCH command reader with the given validation context and identifier converter, and no custom relationship linkage mappers.

    • patchCommandReader

      public static JsonApiPatchCommandReader patchCommandReader(tools.jackson.databind.json.JsonMapper base, com.kazforge.jsonapi.core.aggregate.ValidationContext validationContext, com.kazforge.jsonapi.mapping.IdentifierConverter identifierConverter, Map<Class<?>,RelationshipLinkageMapper> linkageMappers)
      Returns a presence-aware PATCH command reader with the given validation context, identifier converter, and relationship linkage mappers keyed by relationship target class. Snapshots the linkage-mapper map with Map.copyOf(java.util.Map<? extends K, ? extends V>); derives a binder mapper via JsonMapper.rebuild() and never mutates the caller's mapper.

    • patchDtoReader

      public static JsonApiPatchDtoReader patchDtoReader(tools.jackson.databind.json.JsonMapper base)
      Returns a direct typed PATCH DTO reader with ValidationContext.defaults(), default identifier conversion, and no custom relationship linkage mappers. Forces DocumentUsage.UPDATE_REQUEST and PrimaryDataKind.RESOURCE for validate-on-read. Derives a binder mapper via JsonMapper.rebuild() plus the internal PatchPresence module and never mutates the caller's mapper.

    • patchDtoReader

      public static JsonApiPatchDtoReader patchDtoReader(tools.jackson.databind.json.JsonMapper base, com.kazforge.jsonapi.core.aggregate.ValidationContext validationContext)
      Returns a direct typed PATCH DTO reader with the given validation context, default identifier conversion, and no custom relationship linkage mappers. Forces update-request usage while preserving other context fields (including expected endpoint identity).

    • patchDtoReader

      public static JsonApiPatchDtoReader patchDtoReader(tools.jackson.databind.json.JsonMapper base, com.kazforge.jsonapi.core.aggregate.ValidationContext validationContext, com.kazforge.jsonapi.mapping.IdentifierConverter identifierConverter)
      Returns a direct typed PATCH DTO reader with the given validation context and identifier converter, and no custom relationship linkage mappers.

    • patchDtoReader

      public static JsonApiPatchDtoReader patchDtoReader(tools.jackson.databind.json.JsonMapper base, com.kazforge.jsonapi.core.aggregate.ValidationContext validationContext, com.kazforge.jsonapi.mapping.IdentifierConverter identifierConverter, Map<Class<?>,RelationshipLinkageMapper> linkageMappers)
      Returns a direct typed PATCH DTO reader with the given validation context, identifier converter, and relationship linkage mappers keyed by relationship target class. Snapshots the linkage-mapper map with Map.copyOf(java.util.Map<? extends K, ? extends V>); derives a binder mapper via JsonMapper.rebuild() plus the internal PatchPresence module and never mutates the caller's mapper.