Class JacksonStream

java.lang.Object
ca.marcusdunn.jsonlens.jackson.JacksonStream
public final class JacksonStream extends Object

A JSON document that a Jackson streaming JsonParser reads on demand, with no tree.

The document reads tokens only when a query needs them. A query such as $.a reads only up to the first member a, and $.items[0].id never reads items[1]. The document keeps each value that it has read, so a query can visit a value again. The input can be any format that a Jackson parser reads, for example JSON, CBOR, or Smile.

JsonMapper mapper = JsonMapper.builder().build();
JsonParser parser = mapper.createParser("""
        {"first": {"id": 1}, "rest": [{"id": 2}, {"id": 3}]}""");
JacksonStream stream = JacksonStream.open(parser).orElse(null);

// The query reads only up to the first member "first".
JsonPathQuery query = JsonPathParser.standard().parse("$.first.id").orElse(null);
Result<List<Node<JacksonStreamNode>>, EvaluationError> result =
        JsonPathEvaluator.standard().evaluate(query, stream.root(), stream.model());

// After the query: an error of the parser ends the document early.
Maybe<StreamError> failure = stream.failure(); // None

Errors during a query

A JsonModel method cannot report an error, but a parser can fail in the middle of the input. Then the document ends each value that is still open at the failure, and keeps the error. After a query, check failure(): if it is present, the result came from a document that ended early. To check the whole input before a query, use readFully(JsonParser).

Duplicate member names

The parser gives each member, so the document keeps duplicate names. JsonModel.member(Object, JsonString) gives the first member with the name, and JsonModel.hasDuplicate(Object, JsonString) finds the duplicates.

Threads

A document reads its parser under a lock, so several threads can query it. The document does not close the parser.

  • Method Details

    • open

      public static Result<JacksonStream, StreamError> open(tools.jackson.core.JsonParser parser)
      Starts to read a document. The method reads only the first token.
      Parameters:
      parser - a parser before the first token of the document
      Returns:
      the document, or an error if the input has no value or the first token fails

    • readFully

      public static Result<JacksonStream, StreamError> readFully(tools.jackson.core.JsonParser parser)
      Reads a whole document, and checks it: the input must be exactly one value.
      Parameters:
      parser - a parser before the first token of the document
      Returns:
      the document, or the first error

    • root

      public JacksonStreamNode root()
      Returns the root value.
      Returns:
      the root node

    • model

      public JsonModel<JacksonStreamNode> model()

      Returns the model for the nodes of this document.

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

      Returns:
      the model

    • failure

      public Maybe<StreamError> failure()
      Returns the error that ended the document early, if any.
      Returns:
      the first error of the parser, or Maybe.None if the document has read without an error so far