Package com.azure.json

Class JsonReader

java.lang.Object

com.azure.json.JsonReader

All Implemented Interfaces:

Closeable, AutoCloseable

Direct Known Subclasses:

DefaultJsonReader, GsonJsonReader

public abstract class JsonReader
extends Object
implements Closeable

Reads a JSON encoded value as a stream of tokens.

Constructor Summary

Constructors

Constructor	Description
JsonReader()

Method Summary

Modifier and Type	Method	Description
abstract JsonReader	bufferObject()	Reads and returns the current JSON structure the JsonReader is pointing to.
abstract JsonToken	currentToken()	Gets the JsonToken that the reader currently points.
abstract byte[]	getBinaryValue()	Gets the binary value if the reader is currently pointing to a JsonToken.STRING token.
final Boolean	getBooleanNullableValue()	Gets the Boolean value if the reader is currently pointing to a JsonToken.BOOLEAN token or null if the reader is currently pointing to a JsonToken.NULL.
abstract boolean	getBooleanValue()	Gets the boolean value if the reader is currently pointing to a JsonToken.BOOLEAN token.
final Double	getDoubleNullableValue()	Gets the Double value if the reader is currently pointing to a JsonToken.NUMBER, JsonToken.STRING, or JsonToken.NULL.
abstract double	getDoubleValue()	Gets the double value if the reader is currently pointing to a JsonToken.NUMBER or JsonToken.STRING.
abstract String	getFieldName()	Gets the field name if the reader is currently pointing to a JsonToken.FIELD_NAME.
final Float	getFloatNullableValue()	Gets the Float value if the reader is currently pointing to a JsonToken.NUMBER, JsonToken.STRING, or JsonToken.NULL.
abstract float	getFloatValue()	Gets the float value if the reader is currently pointing to a JsonToken.NUMBER or JsonToken.STRING.
final Integer	getIntegerNullableValue()	Gets the Integer value if the reader is currently pointing to a JsonToken.NUMBER, JsonToken.STRING, or JsonToken.NULL.
abstract int	getIntValue()	Gets the int value if the reader is currently pointing to a JsonToken.NUMBER or JsonToken.STRING.
final Long	getLongNullableValue()	Gets the Long value if the reader is currently pointing to a JsonToken.NUMBER, JsonToken.STRING, or JsonToken.NULL.
abstract long	getLongValue()	Gets the long value if the reader is currently pointing to a JsonToken.NUMBER or JsonToken.STRING.
final <T> T	getNullableValue(Function<JsonReader,T> nonNullGetter)	Convenience method to read a nullable type.
abstract String	getStringValue()	Gets the String value if the reader is currently pointing to a JsonToken.BOOLEAN, JsonToken.NULL, JsonToken.NUMBER, or JsonToken.STRING.
final String	getTextValue()	Gets the text value for the currentToken().
final boolean	isEndArrayOrObject()	Whether the currentToken() is JsonToken.END_ARRAY or JsonToken.END_OBJECT.
final boolean	isStartArrayOrObject()	Whether the currentToken() is JsonToken.START_ARRAY or JsonToken.START_OBJECT.
abstract JsonToken	nextToken()	Iterates to and returns the next JsonToken in the JSON encoded value.
final <T> List<T>	readArray(Function<JsonReader,T> elementReaderFunc)	Reads a JSON array.
final String	readChildren()	Recursively reads the JSON token sub-stream if the current token is either JsonToken.START_ARRAY or JsonToken.START_OBJECT.
final void	readChildren(StringBuilder buffer)	Recursively reads the JSON token sub-stream if the current token is either JsonToken.START_ARRAY or JsonToken.START_OBJECT into the passed StringBuilder.
final <T> Map<String,T>	readMap(Function<JsonReader,T> valueReaderFunc)	Reads a JSON map.
final <T> T	readObject(Function<JsonReader,T> objectReaderFunc)	Reads a JSON object.
final Object	readUntyped()	Reads an untyped object.
abstract JsonReader	reset()	Creates a new JsonReader reset to the beginning of the JSON stream.
abstract boolean	resetSupported()	Indicates whether the JsonReader supports resetting.
abstract void	skipChildren()	Recursively skips the JSON token sub-stream if the current token is either JsonToken.START_ARRAY or JsonToken.START_OBJECT.

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.io.Closeable

close

Constructor Details

JsonReader

public JsonReader()

Method Details

currentToken

public abstract JsonToken currentToken()

Gets the JsonToken that the reader currently points.

Returns null if the reader isn't pointing to a token. This happens if the reader hasn't begun to read the JSON value or if reading of the JSON value has completed.

Returns:

The JsonToken that the reader currently points, or null if the reader isn't pointing to a token.

nextToken

public abstract JsonToken nextToken()

Iterates to and returns the next JsonToken in the JSON encoded value.

Returns null if iterating to the next token completes reading of the JSON encoded value.

Returns:

The next JsonToken in the JSON encoded value, or null if reading completes.

isStartArrayOrObject

public final boolean isStartArrayOrObject()

Whether the currentToken() is JsonToken.START_ARRAY or JsonToken.START_OBJECT.

Returns:

Whether the currentToken() is JsonToken.START_ARRAY or JsonToken.START_OBJECT.

isEndArrayOrObject

public final boolean isEndArrayOrObject()

Whether the currentToken() is JsonToken.END_ARRAY or JsonToken.END_OBJECT.

Returns:

Whether the currentToken() is JsonToken.END_ARRAY or JsonToken.END_OBJECT.

getBinaryValue

public abstract byte[] getBinaryValue()

Gets the binary value if the reader is currently pointing to a JsonToken.STRING token.

This returns the equivalent of Base64.getDecoder() Base64.Decoder.decode(String).

If the reader is pointing to a JsonToken.NULL null will be returned. If the reader is pointing to any other token type an IllegalStateException will be thrown.

Returns:

The binary value based on whether the current token is JsonToken.STRING or JsonToken.NULL.

Throws:

IllegalStateException - If the reader isn't pointing to either JsonToken.STRING or JsonToken.NULL.

getBooleanValue

public abstract boolean getBooleanValue()

Gets the boolean value if the reader is currently pointing to a JsonToken.BOOLEAN token.

If the reader is pointing to any other token type an IllegalStateException will be thrown.

If Boolean should be read use getBooleanNullableValue().

Returns:

The boolean value based on the JsonToken.BOOLEAN.

Throws:

IllegalStateException - If the reader isn't pointing to JsonToken.BOOLEAN.

getBooleanNullableValue

public final Boolean getBooleanNullableValue()

Gets the Boolean value if the reader is currently pointing to a JsonToken.BOOLEAN token or null if the reader is currently pointing to a JsonToken.NULL.

If the reader is pointing to any other token type an IllegalStateException will be thrown.

If boolean should be read use getBooleanValue().

Returns:

The Boolean value based on the current token.

Throws:

IllegalStateException - If the reader isn't pointing to JsonToken.BOOLEAN or JsonToken.NULL.

getFloatValue

public abstract float getFloatValue()

Gets the float value if the reader is currently pointing to a JsonToken.NUMBER or JsonToken.STRING.

JsonToken.STRING will throw a NumberFormatException if the underlying string value cannot be converted to a float.

All other JsonToken types will throw an IllegalStateException.

If Float should be read use getFloatNullableValue().

Returns:

The float value based on the current token.

Throws:

NumberFormatException - If the current token is a JsonToken.STRING and cannot be converted to a float.

IllegalStateException - If the current token isn't a JsonToken.NUMBER or JsonToken.STRING.

getFloatNullableValue

public final Float getFloatNullableValue()

Gets the Float value if the reader is currently pointing to a JsonToken.NUMBER, JsonToken.STRING, or JsonToken.NULL.

JsonToken.STRING will throw a NumberFormatException if the underlying string value cannot be converted to a float.

All other JsonToken types will throw an IllegalStateException.

If float should be read use getFloatValue().

Returns:

The Float value based on the current token.

Throws:

NumberFormatException - If the current token is a JsonToken.STRING and cannot be converted to a float.

IllegalStateException - If the current token isn't a JsonToken.NUMBER, JsonToken.STRING, or JsonToken.NULL.

getDoubleValue

public abstract double getDoubleValue()

Gets the double value if the reader is currently pointing to a JsonToken.NUMBER or JsonToken.STRING.

JsonToken.STRING will throw a NumberFormatException if the underlying string value cannot be converted to a double.

All other JsonToken types will throw an IllegalStateException.

If Double should be read use getDoubleNullableValue().

Returns:

The double value based on the current token.

Throws:

NumberFormatException - If the current token is a JsonToken.STRING and cannot be converted to a double.

IllegalStateException - If the current token isn't a JsonToken.NUMBER or JsonToken.STRING.

getDoubleNullableValue

public final Double getDoubleNullableValue()

Gets the Double value if the reader is currently pointing to a JsonToken.NUMBER, JsonToken.STRING, or JsonToken.NULL.

JsonToken.STRING will throw a NumberFormatException if the underlying string value cannot be converted to a double.

All other JsonToken types will throw an IllegalStateException.

If double should be read use getDoubleValue().

Returns:

The Double value based on the current token.

Throws:

NumberFormatException - If the current token is a JsonToken.STRING and cannot be converted to a double.

IllegalStateException - If the current token isn't a JsonToken.NUMBER, JsonToken.STRING, or JsonToken.NULL.

getIntValue

public abstract int getIntValue()

Gets the int value if the reader is currently pointing to a JsonToken.NUMBER or JsonToken.STRING.

JsonToken.STRING will throw a NumberFormatException if the underlying string value cannot be converted to an int.

All other JsonToken types will throw an IllegalStateException.

If Integer should be read use getIntegerNullableValue()

Returns:

The int value based on the current token.

Throws:

NumberFormatException - If the current token is a JsonToken.STRING and cannot be converted to an int.

IllegalStateException - If the current token isn't a JsonToken.NUMBER or JsonToken.STRING.

getIntegerNullableValue

public final Integer getIntegerNullableValue()

Gets the Integer value if the reader is currently pointing to a JsonToken.NUMBER, JsonToken.STRING, or JsonToken.NULL.

JsonToken.STRING will throw a NumberFormatException if the underlying string value cannot be converted to an int.

All other JsonToken types will throw an IllegalStateException.

If int should be read use getIntValue()

Returns:

The Integer value based on the current token.

Throws:

NumberFormatException - If the current token is a JsonToken.STRING and cannot be converted to an int.

IllegalStateException - If the current token isn't a JsonToken.NUMBER, JsonToken.STRING, or JsonToken.NULL.

getLongValue

public abstract long getLongValue()

Gets the long value if the reader is currently pointing to a JsonToken.NUMBER or JsonToken.STRING.

JsonToken.STRING will throw a NumberFormatException if the underlying string value cannot be converted to a long.

All other JsonToken types will throw an IllegalStateException.

If Long should be read use getLongNullableValue().

Returns:

The long value based on the current token.

Throws:

NumberFormatException - If the current token is a JsonToken.STRING and cannot be converted to a long.

IllegalStateException - If the current token isn't a JsonToken.NUMBER or JsonToken.STRING.

getLongNullableValue

public final Long getLongNullableValue()

Gets the Long value if the reader is currently pointing to a JsonToken.NUMBER, JsonToken.STRING, or JsonToken.NULL.

JsonToken.STRING will throw a NumberFormatException if the underlying string value cannot be converted to a long.

All other JsonToken types will throw an IllegalStateException.

If long should be read use getLongValue().

Returns:

The Long value based on the current token.

Throws:

NumberFormatException - If the current token is a JsonToken.STRING and cannot be converted to a long.

IllegalStateException - If the current token isn't a JsonToken.NUMBER, JsonToken.STRING, or JsonToken.NULL.

getStringValue

public abstract String getStringValue()

Gets the String value if the reader is currently pointing to a JsonToken.BOOLEAN, JsonToken.NULL, JsonToken.NUMBER, or JsonToken.STRING.

If the current token is a JsonToken.BOOLEAN, or JsonToken.NUMBER the String representation of the value will be returned. If the current token is JsonToken.NULL null will be returned.

All other JsonToken types will throw an IllegalStateException.

Returns:

The String value based on the current token.

Throws:

IllegalStateException - If the current token isn't a JsonToken.BOOLEAN, JsonToken.NULL, JsonToken.NUMBER, or JsonToken.STRING.

getFieldName

public abstract String getFieldName()

Gets the field name if the reader is currently pointing to a JsonToken.FIELD_NAME.

All other JsonToken types will throw an IllegalStateException.

Returns:

The field name based on the current token.

Throws:

IllegalStateException - If the current token isn't a JsonToken.FIELD_NAME.

getNullableValue

public final <T> T getNullableValue(Function<JsonReader,T> nonNullGetter)

Convenience method to read a nullable type.

If the currentToken() is JsonToken.NULL null will be returned, otherwise this JsonReader will be passed into the nonNullGetter function to get the value. Effectively, this is the generic form of the get*NullableValue methods.

Type Parameters:

T - Type returned by the function.

Parameters:

nonNullGetter - Function that reads the non-null JSON value.

Returns:

null if the currentToken() is JsonToken.NULL or the value returned by nonNullGetter.

skipChildren

public abstract void skipChildren()

Recursively skips the JSON token sub-stream if the current token is either JsonToken.START_ARRAY or JsonToken.START_OBJECT.

If the current token isn't the beginning of an array or object this method is a no-op.

bufferObject

public abstract JsonReader bufferObject()

Reads and returns the current JSON structure the JsonReader is pointing to. This will mutate the current location of this JsonReader.

If the currentToken() isn't JsonToken.START_OBJECT or JsonToken.FIELD_NAME an IllegalStateException will be thrown.

The returned JsonReader is able to be reset() to replay the underlying JSON stream.

Returns:

The buffered JSON object the JsonReader was pointing to.

Throws:

IllegalStateException - If the currentToken() isn't JsonToken.START_OBJECT or JsonToken.FIELD_NAME.

resetSupported

public abstract boolean resetSupported()

Indicates whether the JsonReader supports resetting.

Returns:

Whether reset() is supported.

reset

public abstract JsonReader reset()

Creates a new JsonReader reset to the beginning of the JSON stream.

Use resetSupported() to determine whether the JsonReader can be reset. If resetting is called and it isn't supported an IllegalStateException will be thrown.

Returns:

A new JsonReader reset to the beginning of the JSON stream.

Throws:

IllegalStateException - If resetting isn't supported by the current JsonReader.

readChildren

public final String readChildren()

Recursively reads the JSON token sub-stream if the current token is either JsonToken.START_ARRAY or JsonToken.START_OBJECT.

If the current token isn't the beginning of an array or object this method is a no-op.

Returns:

The raw textual value of the JSON token sub-stream.

readChildren

public final void readChildren(StringBuilder buffer)

Recursively reads the JSON token sub-stream if the current token is either JsonToken.START_ARRAY or JsonToken.START_OBJECT into the passed StringBuilder.

If the current token isn't the beginning of an array or object this method is a no-op.

Parameters:

buffer - The StringBuilder where the read sub-stream will be written.

readObject

public final <T> T readObject(Function<JsonReader,T> objectReaderFunc)

Reads a JSON object.

If the currentToken() is null this will read the next token. If the starting token is still null or JsonToken.NULL null will be returned. If the token is anything other than JsonToken.START_OBJECT an IllegalStateException will be thrown.

Once the JSON stream is prepared for object reading this will get the next token and pass this JsonReader into the objectReaderFunc to handle reading the object.

If a JSON array should be read use readArray(Function) or if a JSON map should be read use readMap(Function).

Type Parameters:

T - The value element type.

Parameters:

objectReaderFunc - Function that reads each value of the key-value pair.

Returns:

The read JSON map, or null if the JsonToken is null or JsonToken.NULL.

Throws:

IllegalStateException - If the token isn't JsonToken.START_OBJECT, JsonToken.NULL, or null.

readArray

public final <T> List<T> readArray(Function<JsonReader,T> elementReaderFunc)

Reads a JSON array.

If the currentToken() is null this will read the next token. If the starting token is still null or JsonToken.NULL null will be returned. If the token is anything other than JsonToken.START_ARRAY an IllegalStateException will be thrown.

Once the JSON stream is prepared for element reading this will get the element token and pass this JsonReader into the elementReaderFunc to handle reading the element of the array. If the array has no elements an empty list will be returned.

If a JSON object should be read use readObject(Function) or if a JSON map should be read use readMap(Function).

Type Parameters:

T - The array element type.

Parameters:

elementReaderFunc - Function that reads each element of the array.

Returns:

The read JSON array, or null if the JsonToken is null or JsonToken.NULL.

Throws:

IllegalStateException - If the token isn't JsonToken.START_ARRAY, JsonToken.NULL, or null.

readMap

public final <T> Map<String,T> readMap(Function<JsonReader,T> valueReaderFunc)

Reads a JSON map.

If the currentToken() is null this will read the next token. If the starting token is still null or JsonToken.NULL null will be returned. If the token is anything other than JsonToken.START_OBJECT an IllegalStateException will be thrown.

Once the JSON stream is prepared for key-value reading this will get the next token and read the field name as the key then get the next token after that and pass this JsonReader into the valueReaderFunc to handle reading the value of the key-value pair. If the object has no elements an empty map will be returned.

If a JSON object should be read use readObject(Function) or if a JSON array should be read use readArray(Function).

Type Parameters:

T - The value element type.

Parameters:

valueReaderFunc - Function that reads each value of the key-value pair.

Returns:

The read JSON map, or null if the JsonToken is null or JsonToken.NULL.

Throws:

IllegalStateException - If the token isn't JsonToken.START_OBJECT, JsonToken.NULL, or null.

readUntyped

public final Object readUntyped()

Reads an untyped object.

If the currentToken() is null this will read the next token.

If the starting token is JsonToken.END_ARRAY, JsonToken.END_OBJECT, or JsonToken.FIELD_NAME an IllegalStateException will be thrown as these are invalid starting points for reading an unknown type. If the untyped object is deeply nested an IllegalStateException will also be thrown to prevent a stack overflow exception.

The returned object will be one of the following:

• null if the starting token is null or JsonToken.NULL
• true or false if the starting token is JsonToken.BOOLEAN
• One of int, long, float, or double is the starting token is JsonToken.NUMBER, the smallest containing value will be used if the number is an integer
• An array of untyped elements if the starting point is JsonToken.START_ARRAY
• A map of String-untyped value if the starting point is JsonToken.START_OBJECT

Returns:

The untyped value based on the outlined return types above.

Throws:

IllegalStateException - If the starting point of the object is JsonToken.END_ARRAY, JsonToken.END_OBJECT, or JsonToken.FIELD_NAME or if the untyped object is deeply nested.

getTextValue

public final String getTextValue()

Gets the text value for the currentToken().

The following is how each JsonToken type is handled:

• JsonToken.START_OBJECT -> {
• JsonToken.END_OBJECT -> }
• JsonToken.START_ARRAY -> [
• JsonToken.END_ARRAY -> ]
• JsonToken.FIELD_NAME -> getFieldName()
• JsonToken.BOOLEAN -> String.valueOf getBooleanValue()
• JsonToken.NULL -> "null"
• JsonToken.STRING -> getStringValue()
• JsonToken.NUMBER -> String.valueOf getStringValue()

If the current token is null an IllegalStateException will be thrown.

Returns:

The text value for the currentToken().

Throws:

IllegalStateException - If the current token is null.