Package com.kazforge.jsonapi.diagnostic

Class MappingLocation

java.lang.Object
com.kazforge.jsonapi.diagnostic.MappingLocation
All Implemented Interfaces:
Serializable
public final class MappingLocation extends Object implements Serializable
A validated mapping-diagnostic location: a JSON Pointer (RFC 6901) that is absent (null) on the owning JsonApiMappingException when no member location applies. This is the structural building block behind the mapping-location contract; producers never assemble diagnostic pointers by raw string concatenation of unconstrained input.

Coordinate contract. Mapping producers address members of one resource object with resource-relative pointers such as /type, /id, /lid, /attributes/headline, /relationships/author/data, /meta, /relationships/author/meta, /relationships/author/data/meta, and /relationships/comments/data/0/meta. Typed-envelope composition prepends document-relative prefixes (/data, /data/<index>, /included/<index>) through append(MappingLocation), which cannot produce malformed syntax because both operands are built from validated, individually escaped, non-empty segments. Failures without a meaningful member location are represented as an absent location, never as "" or /.

Escaping. Segment-taking factories escape each segment independently per RFC 6901 (~ to ~0, then / to ~1); the pointer as a whole is never escaped as one string. parse(String) accepts only pointers that already satisfy this contract: leading /, no empty segments, and ~ only inside valid ~0 / ~1 escape sequences. Instances are immutable and safe for concurrent use.

See Also:

  • Method Details

    • of

      public static MappingLocation of(String firstSegment, String... moreSegments)
      Creates a location from one or more raw segments, escaping each segment per RFC 6901 before composition. For example of("attributes", "external/name") yields /attributes/external~1name.
      Throws:
      NullPointerException - when any segment is null
      IllegalArgumentException - when any segment is empty

    • parse

      public static MappingLocation parse(String pointer)
      Parses an already-escaped pointer string.
      Throws:
      IllegalArgumentException - when the pointer is null, does not start with /, contains an empty segment (//), or contains ~ outside a valid ~0 / ~1 escape sequence

    • append

      public MappingLocation append(String segment)
      Returns a location addressing segment inside this location, escaping the segment. The structural equivalent of appending one member without ever concatenating unvalidated input.
      Throws:
      NullPointerException - when the segment is null
      IllegalArgumentException - when the segment is empty

    • append

      public MappingLocation append(MappingLocation relative)
      Structurally joins a relative location under this location: a document prefix such as /data/2 plus a resource-relative suffix such as /attributes/title yields /data/2/attributes/title. Both operands are already validated, so the join can never produce malformed pointer syntax such as /datatitle.

    • pointer

      public String pointer()
      Returns the canonical pointer text; never empty, always starting with /.

    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object