Package com.kazforge.jsonapi.diagnostic

Class JsonApiMappingException

java.lang.Object

java.lang.Throwable

java.lang.Exception

java.lang.RuntimeException

com.kazforge.jsonapi.diagnostic.JsonApiMappingException

All Implemented Interfaces:

Serializable

public final class JsonApiMappingException
extends RuntimeException

Backend-independent domain mapping, binding, registry, decoration, or representation failure. The current Jackson adapters produce it through caller-configured Jackson.

Every exception carries a stable MappingDiagnostic code, an optional resourceClass(), and an optional location() over JSON:API wire names. Adapter-produced locations follow one coordinate contract:

• Direct resource operations use resource-relative pointers such as /attributes/headline or /relationships/author/data. Typed-envelope readers prepend /data, /data/<index>, or /included/<index> so an escaping failure is document-relative.
• Each segment is escaped independently per RFC 6901. Configured-Jackson external names, rather than logical application-property identities, appear in the pointer.
• A failure without a meaningful member location carries null; absence is never encoded as "", /, or a class name.

location() is the canonical structural accessor; propertyPath() is its string view. Document decoding and core document validation failures use JsonApiDocumentReadException, not this family.

See Also:

• Serialized Form

Constructor Summary

Constructors

Constructor	Description
JsonApiMappingException(MappingDiagnostic diagnostic, @Nullable Class<?> resourceClass, @Nullable MappingLocation location)
JsonApiMappingException(MappingDiagnostic diagnostic, @Nullable Class<?> resourceClass, @Nullable MappingLocation location, String message)
JsonApiMappingException(MappingDiagnostic diagnostic, @Nullable Class<?> resourceClass, @Nullable MappingLocation location, String message, @Nullable Throwable cause)
JsonApiMappingException(MappingDiagnostic diagnostic, String message)	Convenience constructor for failures with neither a resource class nor a member location.

Method Summary

Modifier and Type	Method	Description
MappingDiagnostic	diagnostic()
@Nullable MappingLocation	location()	The mapping location: a valid resource-relative or document-relative JSON Pointer when the failure has a meaningful member location, otherwise null.
@Nullable String	propertyPath()	The pointer text of location() when present, otherwise null.
@Nullable Class<?>	resourceClass()
static JsonApiMappingException	withoutLocation(MappingDiagnostic diagnostic, @Nullable Class<?> resourceClass, String message)	Factory for failures that explicitly carry no member location (for example missing annotations or registry conflicts); identifying names belong in the message per the class contract.

Methods inherited from class java.lang.Throwable

addSuppressed, fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, getSuppressed, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString

Methods inherited from class java.lang.Object

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

Constructor Details

JsonApiMappingException

public JsonApiMappingException(MappingDiagnostic diagnostic,
 @Nullable Class<?> resourceClass,
 @Nullable MappingLocation location)

JsonApiMappingException

public JsonApiMappingException(MappingDiagnostic diagnostic,
 @Nullable Class<?> resourceClass,
 @Nullable MappingLocation location,
 String message)

JsonApiMappingException

public JsonApiMappingException(MappingDiagnostic diagnostic,
 @Nullable Class<?> resourceClass,
 @Nullable MappingLocation location,
 String message,
 @Nullable Throwable cause)

JsonApiMappingException

public JsonApiMappingException(MappingDiagnostic diagnostic,
 String message)

Convenience constructor for failures with neither a resource class nor a member location.

Method Details

withoutLocation

public static JsonApiMappingException withoutLocation(MappingDiagnostic diagnostic,
 @Nullable Class<?> resourceClass,
 String message)

Factory for failures that explicitly carry no member location (for example missing annotations or registry conflicts); identifying names belong in the message per the class contract.

diagnostic

public MappingDiagnostic diagnostic()

resourceClass

public @Nullable Class<?> resourceClass()

location

public @Nullable MappingLocation location()

The mapping location: a valid resource-relative or document-relative JSON Pointer when the failure has a meaningful member location, otherwise null. See the class documentation for the full coordinate contract.

propertyPath

public @Nullable String propertyPath()

The pointer text of location() when present, otherwise null.