JsonReader Class

Package:

com.azure.json

Maven Artifact:

com.azure:azure-json:1.1.0

• java.lang.Object
• • com.azure.json.JsonReader

Implements

Closeable

public abstract class JsonReader
implements Closeable

Reads a JSON value as a stream of tokens.

Instances of JsonReader are created using an instance of JsonProvider or using the utility methods in JsonProviders.

Constructor Summary

Constructor	Description
JsonReader()	Creates an instance of JsonReader.

Method Summary

Modifier and Type	Method and Description
final T	getNullable(ReadValueCallback<JsonReader,T> nonNullGetter) Convenience method to read a nullable type.
final List<T>	readArray(ReadValueCallback<JsonReader,T> elementReaderFunc) Reads a JSON array.
final Map<String,T>	readMap(ReadValueCallback<JsonReader,T> valueReaderFunc) Reads a JSON map.
final T	readObject(ReadValueCallback<JsonReader,T> objectReaderFunc) Reads a JSON object.
abstract JsonReader	bufferObject() Reads and returns the current JSON object the JsonReader is pointing to.
abstract void	close() Closes the JSON stream.
abstract JsonToken	currentToken() Gets the JsonToken that the reader currently points.
abstract byte[]	getBinary() Gets the binary value if the reader is currently pointing to a STRING token.
abstract boolean	getBoolean() Gets the boolean value if the reader is currently pointing to a BOOLEAN token.
abstract double	getDouble() Gets the double value if the reader is currently pointing to a NUMBER or STRING.
abstract String	getFieldName() Gets the field name if the reader is currently pointing to a FIELD_NAME.
abstract float	getFloat() Gets the float value if the reader is currently pointing to a NUMBER or STRING.
abstract int	getInt() Gets the int value if the reader is currently pointing to a NUMBER or STRING.
abstract long	getLong() Gets the long value if the reader is currently pointing to a NUMBER or STRING.
String	getRawText() Gets the raw text value for the currentToken().
abstract String	getString() Gets the String value if the reader is currently pointing to a BOOLEAN, NULL, NUMBER, or STRING.
final String	getText() Gets the text value for the currentToken().
final boolean	isEndArrayOrObject() Whether the currentToken() is END_ARRAY or END_OBJECT.
abstract boolean	isResetSupported() Indicates whether the JsonReader supports reset().
final boolean	isStartArrayOrObject() Whether the currentToken() is START_ARRAY or START_OBJECT.
abstract JsonToken	nextToken() Iterates to and returns the next JsonToken in the JSON encoded value.
final String	readChildren() Recursively reads the JSON token sub-stream if the current token is either START_ARRAY or START_OBJECT.
final void	readChildren(StringBuilder buffer) Recursively reads the JSON token sub-stream if the current token is either START_ARRAY or START_OBJECT into the passed StringBuilder.
final String	readRemainingFieldsAsJsonObject() Reads the remaining fields in the current JSON object as a JSON object.
final void	readRemainingFieldsAsJsonObject(StringBuilder buffer) Reads the remaining fields in the current JSON object as 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 void	skipChildren() Recursively skips the JSON token sub-stream if the current token is either START_ARRAY or START_OBJECT.

Methods inherited from java.lang.Object

clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Constructor Details

JsonReader

public JsonReader()

Creates an instance of JsonReader.

Method Details

getNullable

public final T getNullable(ReadValueCallback nonNullGetter)

Convenience method to read a nullable type.

If the currentToken() is 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.

Parameters:

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

Returns:

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

Throws:

IOException

- If the next value cannot be read as a nullable.

readArray

public final List readArray(ReadValueCallback elementReaderFunc)

Reads a JSON array.

If the currentToken() is null this will nextToken(). If the starting token is still null or NULL null will be returned. If the token is anything other than 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(ReadValueCallback<JsonReader,T> objectReaderFunc) or if a JSON map should be read use readMap(ReadValueCallback<JsonReader,T> valueReaderFunc).

Parameters:

elementReaderFunc - Function that reads each element of the array.

Returns:

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

Throws:

IOException

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

readMap

public final Map readMap(ReadValueCallback valueReaderFunc)

Reads a JSON map.

If the currentToken() is null this will nextToken(). If the starting token is still null or NULL null will be returned. If the token is anything other than 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(ReadValueCallback<JsonReader,T> objectReaderFunc) or if a JSON array should be read use readArray(ReadValueCallback<JsonReader,T> elementReaderFunc).

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 NULL.

Throws:

IOException

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

readObject

public final T readObject(ReadValueCallback objectReaderFunc)

Reads a JSON object.

If the currentToken() is null this will nextToken(). If the starting token is still null or NULL null will be returned. If the token is anything other than 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(ReadValueCallback<JsonReader,T> elementReaderFunc) or if a JSON map should be read use readMap(ReadValueCallback<JsonReader,T> valueReaderFunc).

Parameters:

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

Returns:

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

Throws:

IOException

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

bufferObject

public abstract JsonReader bufferObject()

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

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

If the currentToken() is FIELD_NAME this will create a JSON object where the first JSON field is the currentToken() field, meaning this can be called from the middle of a JSON object to create a new JSON object with only a subset of fields (those remaining from when the method is called).

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:

IOException

- If the #currentToken() isn't JsonToken#START_OBJECT or JsonToken#FIELD_NAME followed by JsonToken#START_OBJECT

close

public abstract void close()

Closes the JSON stream.

Throws:

IOException

- If the underlying content store fails to close.

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.

getBinary

public abstract byte[] getBinary()

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

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

If the reader is pointing to a 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 STRING or NULL.

Throws:

IOException

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

getBoolean

public abstract boolean getBoolean()

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

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

If Boolean should be read use getNullable(ReadValueCallback<JsonReader,T> nonNullGetter).

Returns:

The boolean value based on the BOOLEAN.

Throws:

IOException

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

getDouble

public abstract double getDouble()

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

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 getNullable(ReadValueCallback<JsonReader,T> nonNullGetter).

Returns:

The double value based on the current token.

Throws:

IOException

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

getFieldName

public abstract String getFieldName()

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

All other JsonToken types will throw an IllegalStateException.

Returns:

The field name based on the current token.

Throws:

IOException

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

getFloat

public abstract float getFloat()

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

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 getNullable(ReadValueCallback<JsonReader,T> nonNullGetter).

Returns:

The float value based on the current token.

Throws:

IOException

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

getInt

public abstract int getInt()

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

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 getNullable(ReadValueCallback<JsonReader,T> nonNullGetter).

Returns:

The int value based on the current token.

Throws:

IOException

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

getLong

public abstract long getLong()

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

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 getNullable(ReadValueCallback<JsonReader,T> nonNullGetter).

Returns:

The long value based on the current token.

Throws:

IOException

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

getRawText

public String getRawText()

Gets the raw text value for the currentToken().

The following is how each JsonToken type is handled:

• START_OBJECT -> {
• END_OBJECT -> }
• START_ARRAY -> [
• END_ARRAY -> ]
• FIELD_NAME -> getFieldName() retaining JSON encoded and quoted characters
• BOOLEAN -> String.valueOf getBoolean()
• NULL -> "null"
• STRING -> getString() retaining JSON encoded and quoted characters
• NUMBER -> String.valueOf getString()

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

Returns:

The raw text value for the currentToken().

Throws:

IOException

- If the current token is null.

getString

public abstract String getString()

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

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

All other JsonToken types will throw an IllegalStateException.

Returns:

The String value based on the current token.

Throws:

IOException

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

getText

public final String getText()

Gets the text value for the currentToken().

The following is how each JsonToken type is handled:

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

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

Returns:

The text value for the currentToken().

Throws:

IOException

- If the current token is null.

isEndArrayOrObject

public final boolean isEndArrayOrObject()

Whether the currentToken() is END_ARRAY or END_OBJECT.

Returns:

Whether the currentToken() is END_ARRAY or END_OBJECT.

isResetSupported

public abstract boolean isResetSupported()

Indicates whether the JsonReader supports reset().

Returns:

Whether reset() is supported.

isStartArrayOrObject

public final boolean isStartArrayOrObject()

Whether the currentToken() is START_ARRAY or START_OBJECT.

Returns:

Whether the currentToken() is START_ARRAY or START_OBJECT.

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.

Throws:

IOException

- If the next token cannot be determined.

readChildren

public final String readChildren()

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

If the currentToken() isn't START_OBJECT or START_ARRAY nothing will be read.

Returns:

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

Throws:

IOException

- If the children cannot be read.

readChildren

public final void readChildren(StringBuilder buffer)

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

If the currentToken() isn't START_OBJECT or START_ARRAY nothing will be read.

Parameters:

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

Throws:

IOException

- If buffer is null.

readRemainingFieldsAsJsonObject

public final String readRemainingFieldsAsJsonObject()

Reads the remaining fields in the current JSON object as a JSON object.

If the currentToken() is START_OBJECT this functions the same as readChildren(). If the currentToken() is FIELD_NAME this creates a JSON object where the first field is the current field and reads the remaining fields in the JSON object.

If the currentToken() isn't START_OBJECT or FIELD_NAME nothing will be read.

Returns:

The raw textual value of the remaining JSON fields.

Throws:

IOException

- If the remaining JSON fields cannot be read.

readRemainingFieldsAsJsonObject

public final void readRemainingFieldsAsJsonObject(StringBuilder buffer)

Reads the remaining fields in the current JSON object as a JSON object.

If the currentToken() is START_OBJECT this functions the same as readChildren(StringBuilder buffer). If the currentToken() is FIELD_NAME this creates a JSON object where the first field is the current field and reads the remaining fields in the JSON object.

If the currentToken() isn't START_OBJECT or FIELD_NAME nothing will be read.

Parameters:

buffer - The StringBuilder where the remaining JSON fields will be written.

Throws:

IOException

- If buffer is null.

readUntyped

public final Object readUntyped()

Reads an untyped object.

If the currentToken() is null this will nextToken().

If the starting token is END_ARRAY, END_OBJECT, or 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 NULL
• true or false if the starting token is BOOLEAN
• One of int, long, float, or double is the starting token is NUMBER, the smallest containing value will be used if the number is an integer
• An array of untyped elements if the starting point is START_ARRAY
• A map of String-untyped value if the starting point is START_OBJECT

Returns:

The untyped value based on the outlined return types above.

Throws:

IOException

- 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.

reset

public abstract JsonReader reset()

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

Use isResetSupported() 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:

IOException

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

skipChildren

public abstract void skipChildren()

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

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

Throws:

IOException

- If the children cannot be skipped.