Module io.helidon.json

Package io.helidon.json

Interface JsonParser

All Known Implementing Classes:

JsonParserBase, ObjectStartParser

public interface JsonParser

A JSON parser interface for parsing JSON data from various sources.

The parser operates on a byte-by-byte basis, providing low-level access to JSON tokens and values.

This module is incubating. These APIs may change in any version of Helidon, including backward incompatible changes.

Method Summary

Modifier and Type	Method	Description
boolean	checkNull()	Checks if the current position contains a null value.
void	clearMark()	Clears the current mark.
static JsonParser	create(byte[] json)	Create a new JSON parser from a byte array.
static JsonParser	create(byte[] json, int start, int length)	Create a new JSON parser from a byte array.
static JsonParser	create(JsonValue value)	Create a new JSON parser from a pre-parsed JsonValue.
static JsonParser	create(InputStream inputStream)	Create a new JSON parser from an input stream with default buffer size.
static JsonParser	create(InputStream inputStream, int bufferSize)	Create a new JSON parser from an input stream with specified buffer size.
static JsonParser	create(Reader reader)	Create a new JSON parser from a reader.
static JsonParser	create(String json)	Create a new JSON parser from a JSON string.
JsonException	createException(String message)	Create a JsonException with the given message.
default JsonException	createException(String message, byte c)	Create a JsonException with the given message and found byte information.
byte	currentByte()	Return the last byte that was read from the stream.
boolean	hasNext()	Checks if there are more tokens available in the JSON stream.
void	mark()	Marks the current position in the JSON.
byte	nextToken()	Reads the next JSON token without consuming it.
BigDecimal	readBigDecimal()	Reads a numeric value as BigDecimal.
BigInteger	readBigInteger()	Reads a numeric value as BigInteger.
byte[]	readBinary()	Reads a binary value.
boolean	readBoolean()	Reads a boolean value from the current position.
byte	readByte()	Reads a numeric value as a byte.
char	readChar()	Reads a char value from the current position.
double	readDouble()	Reads a numeric value as a double.
float	readFloat()	Reads a numeric value as a float.
int	readInt()	Reads a numeric value as an int.
JsonArray	readJsonArray()	Reads a JSON array from the current position.
JsonNumber	readJsonNumber()	Reads a JSON number value from the current position.
JsonObject	readJsonObject()	Reads a JSON object from the current position.
JsonString	readJsonString()	Reads a JSON string value from the current position.
JsonValue	readJsonValue()	Reads a complete JSON value from the current position.
long	readLong()	Reads a numeric value as a long.
short	readShort()	Reads a numeric value as a short.
String	readString()	Reads a string value from the current position.
int	readStringAsHash()	Reads a string value and returns its FNV-1a hash.
void	resetToMark()	Resets the parser position to the previously marked position.
void	skip()	Skips the current JSON value without parsing it.

Method Details

create

static JsonParser create(String json)

Create a new JSON parser from a JSON string.

This method creates an in-memory parser that processes the entire JSON string at once. Suitable for parsing small to medium-sized JSON content.

Parameters:

json - the JSON string to parse

Returns:

a new JsonParser instance

create

static JsonParser create(byte[] json)

Create a new JSON parser from a byte array.

This method creates an in-memory parser that processes the entire JSON byte array at once. Suitable for parsing small to medium-sized JSON content.

Parameters:

json - the JSON byte array to parse

Returns:

a new JsonParser instance

create

static JsonParser create(byte[] json,
 int start,
 int length)

Create a new JSON parser from a byte array.

This method creates an in-memory parser that processes the entire JSON byte array at once. Suitable for parsing small to medium-sized JSON content.

Parameters:

json - the JSON byte array to parse

start - start index of the json

length - length of the json

Returns:

a new JsonParser instance

create

static JsonParser create(InputStream inputStream)

Create a new JSON parser from an input stream with default buffer size.

This method creates a streaming parser that reads JSON content from the input stream incrementally. Suitable for parsing large JSON content or streaming sources.

Parameters:

inputStream - the input stream containing JSON data

Returns:

a new JsonParser instance

create

static JsonParser create(InputStream inputStream,
 int bufferSize)

Create a new JSON parser from an input stream with specified buffer size.

This method creates a streaming parser with a custom buffer size for reading JSON content from the input stream. Use this when you need to control memory usage for large JSON documents.

Parameters:

inputStream - the input stream containing JSON data

bufferSize - the buffer size in bytes for reading from the stream

Returns:

a new JsonParser instance

create

static JsonParser create(JsonValue value)

Create a new JSON parser from a pre-parsed JsonValue.

This method wraps an existing JsonValue in a parser interface, allowing JsonValue objects to be used wherever a JsonParser is expected.

Parameters:

value - the JsonValue to wrap in a parser

Returns:

a new JsonParser instance

create

static JsonParser create(Reader reader)

Create a new JSON parser from a reader.

This method creates a streaming parser that reads JSON content from the reader incrementally. Suitable for parsing large JSON content or streaming sources.

Parameters:

reader - the reader containing JSON data

Returns:

a new JsonParser instance

hasNext

boolean hasNext()

Checks if there are more tokens available in the JSON stream.

This method should be called before attempting to read any tokens to avoid exceptions when reaching the end of the JSON content.

Returns:

true if more tokens are available, false if end of stream is reached

nextToken

byte nextToken()

Reads the next JSON token without consuming it.

This method advances the parser to the next significant token (skipping whitespace) but does not consume it. The token can then be read using appropriate read methods.

Returns:

the byte value of the next token

Throws:

JsonException - if no more tokens are available or parsing fails

currentByte

byte currentByte()

Return the last byte that was read from the stream.

This method can be used to inspect the current parser position without advancing it. Useful for debugging or conditional parsing logic.

Returns:

the last byte read, or 0 if no bytes have been read yet

readJsonValue

JsonValue readJsonValue()

Reads a complete JSON value from the current position.

This method parses and returns the next complete JSON value (object, array, string, number, boolean, or null) from the current parser position.

Returns:

the parsed JsonValue

Throws:

JsonException - if parsing fails or no value is available

See Also:

• JsonValue

readJsonObject

JsonObject readJsonObject()

Reads a JSON object from the current position.

This method expects the next token to be an object start ('{') and parses the complete object including all nested values.

Returns:

the parsed JsonObject

Throws:

JsonException - if the next token is not an object or parsing fails

See Also:

• JsonObject

readJsonArray

JsonArray readJsonArray()

Reads a JSON array from the current position.

This method expects the next token to be an array start ('[') and parses the complete array including all nested values.

Returns:

the parsed JsonArray

Throws:

JsonException - if the next token is not an array or parsing fails

See Also:

• JsonArray

readJsonString

JsonString readJsonString()

Reads a JSON string value from the current position.

This method expects the next token to be a string and returns the parsed string value.

Returns:

the parsed JsonString

Throws:

JsonException - if the next token is not a string or parsing fails

See Also:

• JsonString

readJsonNumber

JsonNumber readJsonNumber()

Reads a JSON number value from the current position.

This method expects the next token to be a number and returns the parsed numeric value.

Returns:

the parsed JsonNumber

Throws:

JsonException - if the next token is not a number or parsing fails

See Also:

• JsonNumber

readString

String readString()

Reads a string value from the current position. The value has to start and end with the ".

This method expects the next token to be a string and returns the string content as a Java String.

Returns:

the string value

Throws:

JsonException - if the next token is not a string or parsing fails

readStringAsHash

int readStringAsHash()

Reads a string value and returns its FNV-1a hash.

This method is optimized for performance when only string comparison is needed, avoiding string object allocation.

Returns:

the hash of the string value

Throws:

JsonException - if the next token is not a string or parsing fails

readChar

char readChar()

Reads a char value from the current position. The value has to start and end with the ".

This method expects the next token to be a string and returns the string content as a Java char value. It has to be one character.

Returns:

the char value

Throws:

JsonException - if the next token is not a string or parsing fails

readBoolean

boolean readBoolean()

Reads a boolean value from the current position.

This method expects the next token to be a boolean (true/false) and returns the corresponding Java boolean value.

Returns:

the boolean value

Throws:

JsonException - if the next token is not a boolean or parsing fails

readByte

byte readByte()

Reads a numeric value as a byte.

This method expects the next token to be a number and converts it to a byte.

Returns:

the byte value

Throws:

JsonException - if parsing fails

readShort

short readShort()

Reads a numeric value as a short.

This method expects the next token to be a number and converts it to a short.

Returns:

the short value

Throws:

JsonException - if parsing fails

readInt

int readInt()

Reads a numeric value as an int.

This method expects the next token to be a number and converts it to an int.

Returns:

the int value

Throws:

JsonException - if parsing fails

readLong

long readLong()

Reads a numeric value as a long.

This method expects the next token to be a number and converts it to a long.

Returns:

the long value

Throws:

JsonException - if parsing fails

readFloat

float readFloat()

Reads a numeric value as a float.

This method expects the next token to be a number and converts it to a float.

Returns:

the float value

Throws:

JsonException - if parsing fails

readDouble

double readDouble()

Reads a numeric value as a double.

This method expects the next token to be a number and converts it to a double.

Returns:

the double value

Throws:

JsonException - if parsing fails

readBigInteger

BigInteger readBigInteger()

Reads a numeric value as BigInteger.

Returns:

the big integer value

readBigDecimal

BigDecimal readBigDecimal()

Reads a numeric value as BigDecimal.

Returns:

the big decimal value

readBinary

byte[] readBinary()

Reads a binary value.

Returns:

the decoded binary value

checkNull

boolean checkNull()

Checks if the current position contains a null value.

This method peeks at the next value to determine if it's null and advances the parser position if it is.

Returns:

true if the next value is null, false otherwise

Throws:

JsonException - if parsing fails

skip

void skip()

Skips the current JSON value without parsing it.

This method advances the parser past the current value (object, array, string, number, boolean, or null) without constructing Java objects. Useful for skipping unwanted parts of large JSON documents.

Throws:

JsonException - if parsing fails

createException

JsonException createException(String message)

Create a JsonException with the given message.

Parameters:

message - the exception message

Returns:

a JsonException

createException

default JsonException createException(String message,
 byte c)

Create a JsonException with the given message and found byte information.

Parameters:

message - the exception message

c - the byte that caused the exception

Returns:

a JsonException

mark

void mark()

Marks the current position in the JSON.

This method saves the current parser position so it can be returned to later using resetToMark(). Useful for backtracking during parsing operations.

clearMark

void clearMark()

Clears the current mark.

This method clears any previously set mark. Should be always called when backtracking is no longer needed.

resetToMark

void resetToMark()

Resets the parser position to the previously marked position.

This method restores the parser to the position that was saved with mark(). Allows for backtracking to a previous parsing state.