Package jsonvalues.spec

Class JsObjSpecParser

java.lang.Object

jsonvalues.spec.JsObjSpecParser

public final class JsObjSpecParser
extends Object

The JsObjSpecParser class is responsible for creating JSON object parsers based on provided JSON specifications (specs). It allows you to define a JSON schema using a specification and then use that schema to parse JSON data into structured Java objects. This class is part of the JSONValues library, which focuses on providing a type-safe and functional approach to JSON parsing and manipulation.

A parser, in the context of this class, refers to an instance of JsParser that encapsulates the rules and constraints defined in a JSON specification. The parser ensures that the JSON data being parsed conforms to the specified schema, enforcing rules such as data types, required fields, and user-defined conditions.

Usage of this class typically involves creating an instance with a JSON specification and then using that instance to parse JSON data. If the JSON data does not adhere to the specified schema, a JsParserException will be raised, providing detailed information about the parsing code.

This class provides three main methods for parsing JSON data:

• parse(byte[] bytes): Parses a byte array representing JSON data into a JSON object.
• parse(String str): Parses a JSON string into a JSON object.
• parse(InputStream inputStream): Parses JSON data from an input stream into a JSON object. This method also handles potential I/O exceptions when reading from the stream.

It's important to note that the provided JSON specification should match the structure and constraints of the JSON data you expect to parse. The parser will enforce these constraints during parsing.

Method Summary

Modifier and Type	Method	Description
static JsObjSpecParser	of(JsSpec spec)	Creates a JSON object parser based on the provided JSON object specification (spec).
JsObj	parse(byte[] bytes)	Parses an array of bytes into a JSON object that must conform to the spec of the parser.
JsObj	parse(InputStream inputstream)	Parses an input stream of bytes into a JSON object that must conform to the spec of the parser.
JsObj	parse(String str)	Parses a string into a JSON object that must conform to the spec of the parser.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

of

public static JsObjSpecParser of(JsSpec spec)

Creates a JSON object parser based on the provided JSON object specification (spec). The parser will validate that every field in a JSON object adheres to the schema defined in the given specification.

Parameters:

spec - The JSON object specification that defines the expected schema for each field-value in the object.

Returns:

a Json object parser

parse

public JsObj parse(byte[] bytes)

Parses an array of bytes into a JSON object that must conform to the spec of the parser. If the array of bytes doesn't represent a well-formed JSON or is a well-formed JSON that doesn't conform to the spec of the parser, a ParsingException failure wrapped in a Try computation is returned.

Parameters:

bytes - A JSON object serialized as an array of bytes.

Returns:

A Try computation with the parsed JSON object or a ParsingException failure.

Throws:

NullPointerException - if the provided byte array is null.

JsParserException - If parsing fails due to JSON syntax errors or specification violations.

parse

public JsObj parse(String str)

Parses a string into a JSON object that must conform to the spec of the parser. If the string doesn't represent a well-formed JSON or is a well-formed JSON that doesn't conform to the spec of the parser, a ParsingException failure wrapped in a Try computation is returned.

Parameters:

str - A JSON object serialized as a string.

Returns:

A Try computation with the parsed JSON object or a ParsingException failure.

Throws:

NullPointerException - if the provided string is null.

JsParserException - If parsing fails due to JSON syntax errors or specification violations.

parse

public JsObj parse(InputStream inputstream)

Parses an input stream of bytes into a JSON object that must conform to the spec of the parser. If the input stream of bytes doesn't represent a well-formed JSON object or is a well-formed JSON that doesn't conform to the spec of the parser, a ParsingException failure wrapped in a Try computation is returned. Any I/O exception that occurs while processing the input stream is also wrapped in a Try computation.

Parameters:

inputstream - The input stream of bytes.

Returns:

A Try computation with the parsed JSON object or a ParsingException failure.

Throws:

NullPointerException - if the provided input stream is null.

JsParserException - If parsing fails due to JSON syntax errors or specification violations.