Class MappedJson

java.lang.Object
ca.marcusdunn.jsonlens.mapped.MappedJson
public final class MappedJson extends Object

A JSON text in UTF-8 bytes, for example a memory-mapped file, with a read-only JsonModel.

open(Path) maps a file, and of(ByteBuffer) uses bytes that are already in memory. Both check the text once (RFC 8259 and UTF-8) and make a structural index: the kind and the position of each value, and the children of each array and object. They do not copy or decode the text. The index is on the heap. It uses 5 bytes for each value, 4 more bytes for each array element, 8 more bytes for each object member, and 4 bytes for each array and object.

The model() reads the bytes only when the evaluator needs a value:

  • A string is a JsonString that decodes UTF-8 and escapes while the evaluator reads it.
  • A number is a JsonNumber that reads its digits only for a comparison. Its exact value has no limit on the exponent.
  • A member name is also such a JsonString. JsonModel.member(Object, JsonString) compares the name bytes with the query name, and the member cursor of the model gives the names without a decoded copy.

A Normalized Path of a result keeps these names, and it reads the bytes when the caller reads the path, for example with toString(). Thus the paths are correct only while the bytes stay the same, and they keep the mapping in memory.

Duplicate member names

RFC 8259 permits duplicate names, but their meaning is not defined. This model keeps all members: JsonModel.member(Object, JsonString) gives the first member with the name, and JsonModel.memberCursor(Object) gives all members in document order. JsonModel.hasDuplicate(Object, ca.marcusdunn.jsonlens.model.JsonString) finds them, for example for JSON Pointer.

Limits and threads

A ByteBuffer has an int index, so a file can have at most 2 GiB. The caller must not change the bytes while the index is in use. A MappedJson and its model are safe for concurrent reads.

  • Method Details

    • open

      public static Result<MappedJson, MappedJsonError> open(Path path)
      Maps a file that holds a JSON text in UTF-8.
      Parameters:
      path - the file
      Returns:
      the JSON text, or an error if the file cannot be read, is larger than 2 GiB, or is not a JSON text in UTF-8

    • of

      public static Result<MappedJson, MappedJsonError> of(ByteBuffer bytes)

      Uses the bytes from the position to the limit of a buffer as a JSON text in UTF-8.

      The JSON text uses the bytes of the buffer; it does not copy them. The position and the limit of the buffer do not change.

      Parameters:
      bytes - the bytes of the JSON text
      Returns:
      the JSON text, or an error if the bytes are not a JSON text in UTF-8

    • root

      public MappedNode root()
      Returns the root value: the complete JSON text.
      Returns:
      the root node

    • model

      public JsonModel<MappedNode> model()

      Returns the model for the nodes of this JSON text.

      The model is read-only: it does not implement JsonFactory.

      Returns:
      the model