Package gov.nasa.jpl.aerie.json

Interface JsonParser<T>

Type Parameters:
T - the type of domain object convertible with JSON
All Known Subinterfaces:
JsonObjectParser<T>
All Known Implementing Classes:
PathJsonParser, ProductParsers.EmptyProductParser, ProductParsers.VariadicProductParser
public interface JsonParser<T>
An interface for two-way conversion between JSON documents and domain objects.

This interface is designed for the composition of complex JSON parsers by building them up from simpler ones. For instance, a parser for a primitive data type like an integer might be used as an element of a parser for an object with one or more integer fields.

This interface helps avoid the situation in which a parser is modified without making analogous changes to the corresponding unparser (printer), since both capabilities are implemented by the same object. Moreover, since the parser is defined separately from the domain type it represents, parsers can be defined for types not owned by the developer of the parser, or for types that may be serialized to multiple other formats depending on the context.

We encourage a style of composition emphasizing the overall structure of the supported JSON documents, which is consolidated into a single co-located grammar. A developer should not build a parser by implementing this interface, but rather by building a parser up from pre-existing parsers and combinators. New parsers for leaf-level data types may be defined, of course, but they should be the exception, not the rule.

See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    default javax.json.JsonObject
    getSchema()
    Produces a JSON Schema document describing the format of JSON documents produced by unparse(T).
    javax.json.JsonObject
    getSchema(SchemaCache anchors)
    Produces a JSON Schema document fragment describing the format of JSON documents accepted by parse(JsonValue) and produced by unparse(T).
    default <S> JsonParser<S>
    map(Convert<T,S> transform)
    Adapts this parser losslessly from one domain type to another with a two-way conversion.
    default <S> JsonParser<S>
    map(Function<T,S> from, Function<S,T> to)
    Adapts this parser losslessly from one domain type to another.
    JsonParseResult<T>
    parse(javax.json.JsonValue json)
    Attempts to parse a JSON document into the domain type T.
    javax.json.JsonValue
    unparse(T value)
    Produces a JSON document representing the given value.

  • Method Details

    • getSchema

      javax.json.JsonObject getSchema(SchemaCache anchors)
      Produces a JSON Schema document fragment describing the format of JSON documents accepted by parse(JsonValue) and produced by unparse(T).

      The anchors parameter is an accumulator for visited sub-parsers, tracking a JSON Schema identifier for each. An implementations may add to the set of anchors, but may not alter or remove an existing anchor, and must not add itself. This allows an arbitrary caller to make the choice of whether to inline a definition at all use-sites or reference a single copy.

      This method is primarily meant for use from other parsers. To generate a top-level schema for a root-level parser, use getSchema().

      Parameters:
      anchors - a mutable collection of JSON Schema identifiers for previously-visited parsers
      Returns:
      a JSON Schema document describing the format of JSON documents supported by this parser.

    • parse

      JsonParseResult<T> parse(javax.json.JsonValue json)
      Attempts to parse a JSON document into the domain type T.

      This method must successfully parse any document generated by unparse(T), and the resulting domain value must be equal to the one that produced that document. No guarantees are made for documents not generated by the unparse method. See getSchema() for more on the relationships among these methods.

      Parameters:
      json - the JSON document to parse into a domain value
      Returns:
      a wrapped domain value if parsing succeeds, or failure information otherwise

    • unparse

      javax.json.JsonValue unparse(T value)
      Produces a JSON document representing the given value.

      The document produced by this method must validate against the schema returned by getSchema(), and must be parsed successfully by parse(JsonValue) into a value equal to the one given here.

      Parameters:
      value - a domain value to encode in JSON
      Returns:
      a JSON document representing the given value

    • getSchema

      default javax.json.JsonObject getSchema()
      Produces a JSON Schema document describing the format of JSON documents produced by unparse(T).

      All documents returned from unparse(T) must validate against this schema. However, parse(JsonValue) is only required to faithfully parse documents generated by unparse(T). The parse method may reject other documents that validate relative to the schema (for instance, if the document does not maintain invariants required of the domain type), and may accept other documents that do not validate.

      Individual parsers may make stronger guarantees about the behavior of the parse method. Absent such guarantees, clients of the parse method should treat this schema as advisory only: if a document does not validate, then it definitely isn't something that unparse would produce.

      Returns:
      a JSON Schema document describing the format of JSON documents supported by this parser.

    • map

      default <S> JsonParser<S> map(Convert<T,S> transform)
      Adapts this parser losslessly from one domain type to another with a two-way conversion.

      The data types most convenient for building parsers are not always the ones we actually want to end up with in the business domain. This method turns a parser that works with one (parsing-relevant) type into a parser that works with another (domain-relevant) type (typically the domain-relevant one).

      To do this, we need to know the precise relationship between the two types. Specifically, we need a way to turn any value of one into a value of the other, and vice versa. This is captured by the Convert parameter, which provides a pair of forward and backward transformations.

      Type Parameters:
      S - the new domain type to convert to
      Parameters:
      transform - the reversible transformation faithfully mapping between T objects and S objects
      Returns:
      a parser supporting the same JSON documents as this parser, but for domain type S.

    • map

      default <S> JsonParser<S> map(Function<T,S> from, Function<S,T> to)
      Adapts this parser losslessly from one domain type to another.

      The data types most convenient for building parsers are not always the ones we actually want to end up with in the business domain. This method turns a parser that works with one (parsing-relevant) type into a parser that works with another (domain-relevant) type (typically the domain-relevant one).

      To do this, we need to know the precise relationship between the two types. Specifically, we need a way to turn any value of one into a value of the other, and vice versa.

      Type Parameters:
      S - the new domain type to convert to
      Parameters:
      from - an infallible transformation from the source type to the target type
      to - an infallible transformation to the source type from the target type
      Returns:
      a parser supporting the same JSON documents as this parser, but for domain type S.