Package uk.blankaspect.common.json

Class JsonParser

java.lang.Object
uk.blankaspect.common.json.JsonParser
public class JsonParser extends Object

This class implements a parser that transforms JSON text into either a tree of nodes or a tree of XML elements:

  • The parse(…) methods transform JSON text into a tree of nodes. Each node corresponds to a JSON value.
  • The parseToXml(…) methods transform JSON text into a tree of XML elements. Each XML element corresponds to a JSON value.

The input text of the parser is expected to conform to the JSON grammar as specified in IETF RFC 8259.

The parser is implemented as a finite-state machine (FSM) that terminates with an exception at the first error in the input text. The FSM combines the lexical analysis and parsing of the input text with the generation of the output (a tree of nodes or XML elements that correspond to JSON values).

  • Method Details

    • builder

      public static JsonParser.Builder builder()
      Creates and returns a new instance of a builder for a JSON parser.
      Returns:
      a new instance of a builder for a JSON parser.

    • parse

      public AbstractNode parse(CharSequence text) throws JsonParser.ParseException
      Parses the specified text. If the text conforms to the JSON grammar, the JSON text is transformed into a tree of nodes that correspond to JSON values, and the root of the tree is returned.
      Parameters:
      text - the text that will be parsed as JSON text.
      Returns:
      the root of the tree of nodes that was created from parsing the JSON text that was read from text.
      Throws:
      IllegalArgumentException - if text is null.
      JsonParser.ParseException - if an error occurs when parsing the input text.

    • parse

      public AbstractNode parse(InputStream inputStream) throws JsonParser.ParseException
      Parses the text that is composed of characters that are read from the specified byte stream using the UTF-8 character encoding. If the text conforms to the JSON grammar, the JSON text is transformed into a tree of nodes that correspond to JSON values, and the root of the tree is returned.
      Parameters:
      inputStream - the byte stream from which the JSON text will be read.
      Returns:
      the root of the tree of nodes that was created from parsing the JSON text that was read from inputStream.
      Throws:
      IllegalArgumentException - if inputStream is null.
      JsonParser.ParseException - if an error occurs when parsing the input text.

    • parse

      public AbstractNode parse(InputStream inputStream, Charset encoding) throws JsonParser.ParseException
      Parses the text that is composed of characters that are read from the specified byte stream using the specified character encoding. If the text conforms to the JSON grammar, the JSON text is transformed into a tree of nodes that correspond to JSON values, and the root of the tree is returned.
      Parameters:
      inputStream - the byte stream from which the JSON text will be read.
      encoding - the character encoding of inputStream; if null, the UTF-8 encoding will be used.
      Returns:
      the root of the tree of nodes that was created from parsing the JSON text that was read from inputStream.
      Throws:
      IllegalArgumentException - if inputStream is null.
      JsonParser.ParseException - if an error occurs when parsing the input text.

    • parse

      public AbstractNode parse(Reader reader) throws JsonParser.ParseException
      Parses the text that is read from a character stream by the specified reader. If the text conforms to the JSON grammar, the JSON text is transformed into a tree of nodes that correspond to JSON values, and the root of the tree is returned.
      Parameters:
      reader - the reader of the character stream that is the source of the JSON text.
      Returns:
      the root of the tree of nodes that was created from parsing the JSON text that was read from inputStream.
      Throws:
      IllegalArgumentException - if reader is null.
      JsonParser.ParseException - if an error occurs when parsing the input text.

    • parseToXml

      public Element parseToXml(CharSequence text) throws JsonParser.ParseException
      Parses the specified text. If the text conforms to the JSON grammar, the JSON text is transformed into a tree of XML elements that correspond to JSON values, and the root of the tree is returned.
      Parameters:
      text - the text that will be parsed as JSON text.
      Returns:
      the root of the tree of XML elements that was created from parsing the JSON text that was read from text.
      Throws:
      IllegalArgumentException - if text is null.
      IllegalStateException - if no XML element facade has been set on this parser.
      JsonParser.ParseException - if an error occurs when parsing the input text.

    • parseToXml

      public Element parseToXml(InputStream inputStream) throws JsonParser.ParseException
      Parses the text that is composed of characters that are read from the specified byte stream using the UTF-8 character encoding. If the text conforms to the JSON grammar, the JSON text is transformed into a tree of XML elements that correspond to JSON values, and the root of the tree is returned.
      Parameters:
      inputStream - the byte stream from which the JSON text will be read.
      Returns:
      the root of the tree of XML elements that was created from parsing the JSON text that was read from inputStream.
      Throws:
      IllegalArgumentException - if inputStream is null.
      IllegalStateException - if no XML element facade has been set on this parser.
      JsonParser.ParseException - if an error occurs when parsing the input text.

    • parseToXml

      public Element parseToXml(InputStream inputStream, Charset encoding) throws JsonParser.ParseException
      Parses the text that is composed of characters that are read from the specified byte stream using the specified character encoding. If the text conforms to the JSON grammar, the JSON text is transformed into a tree of XML elements that correspond to JSON values, and the root of the tree is returned.
      Parameters:
      inputStream - the byte stream from which the JSON text will be read.
      encoding - the character encoding of inputStream; if null, the UTF-8 encoding will be used.
      Returns:
      the root of the tree of XML elements that was created from parsing the JSON text that was read from inputStream.
      Throws:
      IllegalArgumentException - if inputStream is null.
      IllegalStateException - if no XML element facade has been set on this parser.
      JsonParser.ParseException - if an error occurs when parsing the input text.

    • parseToXml

      public Element parseToXml(Reader reader) throws JsonParser.ParseException
      Parses the text that is read from a character stream by the specified reader. If the text conforms to the JSON grammar, the JSON text is transformed into a tree of XML elements that correspond to JSON values, and the root of the tree is returned.
      Parameters:
      reader - the reader of the character stream that is the source of the JSON text.
      Returns:
      the root of the tree of XML elements that was created from parsing the JSON text that was read from inputStream.
      Throws:
      IllegalArgumentException - if reader is null.
      IllegalStateException - if no XML element facade has been set on this parser.
      JsonParser.ParseException - if an error occurs when parsing the input text.