Package com.azure.json

Class JsonReader

java.lang.Object

com.azure.json.JsonReader

All Implemented Interfaces:

Closeable, AutoCloseable

public abstract class JsonReader
extends Object
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.

See Also:

• com.azure.json
• JsonProvider
• JsonProviders

Constructor Summary

Constructors

Constructor	Description
JsonReader()	Creates an instance of JsonReader.

Method Summary

Modifier and Type	Method	Description
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 JsonToken.STRING token.
abstract boolean	getBoolean()	Gets the boolean value if the reader is currently pointing to a JsonToken.BOOLEAN token.
abstract double	getDouble()	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.
abstract float	getFloat()	Gets the float value if the reader is currently pointing to a JsonToken.NUMBER or JsonToken.STRING.
abstract int	getInt()	Gets the int value if the reader is currently pointing to a JsonToken.NUMBER or JsonToken.STRING.
abstract long	getLong()	Gets the long value if the reader is currently pointing to a JsonToken.NUMBER or JsonToken.STRING.
final <T> T	getNullable(ReadValueCallback<JsonReader,T> nonNullGetter)	Convenience method to read a nullable type.
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 JsonToken.BOOLEAN, JsonToken.NULL, JsonToken.NUMBER, or JsonToken.STRING.
final String	getText()	Gets the text value for the currentToken().
final boolean	isEndArrayOrObject()	Whether the currentToken() is JsonToken.END_ARRAY or JsonToken.END_OBJECT.
abstract boolean	isResetSupported()	Indicates whether the JsonReader supports resetting.
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(ReadValueCallback<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(ReadValueCallback<JsonReader,T> valueReaderFunc)	Reads a JSON map.
final <T> T	readObject(ReadValueCallback<JsonReader,T> objectReaderFunc)	Reads a JSON object.
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 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

Constructor Details

JsonReader

public JsonReader()

Creates an instance of 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()
                             throws IOException

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.

close

public abstract void close()
                    throws IOException

Closes the JSON stream.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

Throws:

IOException - If the underlying content store fails to close.

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.

getBinary

public abstract byte[] getBinary()
                          throws IOException

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.

IOException - If the next value cannot be read as binary.

getBoolean

public abstract boolean getBoolean()
                            throws IOException

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 getNullable(ReadValueCallback).

Returns:

The boolean value based on the JsonToken.BOOLEAN.

Throws:

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

IOException - If the next value cannot be read as a boolean.

getFloat

public abstract float getFloat()
                        throws IOException

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 getNullable(ReadValueCallback).

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.

IOException - If the next value cannot be read as a float.

getDouble

public abstract double getDouble()
                          throws IOException

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 getNullable(ReadValueCallback).

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.

IOException - If the next value cannot be read as a double.

getInt

public abstract int getInt()
                    throws IOException

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 getNullable(ReadValueCallback).

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.

IOException - If the next value cannot be read as an int.

getLong

public abstract long getLong()
                      throws IOException

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 getNullable(ReadValueCallback).

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.

IOException - If the next value cannot be read as a long.

getString

public abstract String getString()
                          throws IOException

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.

IOException - If the next value cannot be read as a String.

getFieldName

public abstract String getFieldName()
                             throws IOException

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.

IOException - If the next value cannot be read as a field name.

getNullable

public final <T> T getNullable(ReadValueCallback<JsonReader,T> nonNullGetter)
                        throws IOException

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.

Throws:

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

skipChildren

public abstract void skipChildren()
                           throws IOException

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.

Throws:

IOException - If the children cannot be skipped.

bufferObject

public abstract JsonReader bufferObject()
                                 throws IOException

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 JsonToken.START_OBJECT or JsonToken.FIELD_NAME an IllegalStateException will be thrown.

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

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

IOException - If the child object cannot be buffered.

isResetSupported

public abstract boolean isResetSupported()

Indicates whether the JsonReader supports resetting.

Returns:

Whether reset() is supported.

reset

public abstract JsonReader reset()
                          throws IOException

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:

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

IOException - If the JsonReader cannot be reset.

readChildren

public final String readChildren()
                          throws IOException

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

If the currentToken() isn't JsonToken.START_OBJECT or JsonToken.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)
                        throws IOException

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 currentToken() isn't JsonToken.START_OBJECT or JsonToken.START_ARRAY nothing will be read.

Parameters:

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

Throws:

NullPointerException - If buffer is null.

IOException - If the children cannot be read.

readRemainingFieldsAsJsonObject

public final String readRemainingFieldsAsJsonObject()
                                             throws IOException

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

If the currentToken() is JsonToken.START_OBJECT this functions the same as readChildren(). If the currentToken() is JsonToken.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 JsonToken.START_OBJECT or JsonToken.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)
                                           throws IOException

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

If the currentToken() is JsonToken.START_OBJECT this functions the same as readChildren(StringBuilder). If the currentToken() is JsonToken.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 JsonToken.START_OBJECT or JsonToken.FIELD_NAME nothing will be read.

Parameters:

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

Throws:

NullPointerException - If buffer is null.

IOException - If the remaining JSON fields cannot be read.

readObject

public final <T> T readObject(ReadValueCallback<JsonReader,T> objectReaderFunc)
                       throws IOException

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(ReadValueCallback) or if a JSON map should be read use readMap(ReadValueCallback).

Type Parameters:

T - The value element type.

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

Throws:

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

IOException - If the object cannot be read.

readArray

public final <T> List<T> readArray(ReadValueCallback<JsonReader,T> elementReaderFunc)
                            throws IOException

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(ReadValueCallback) or if a JSON map should be read use readMap(ReadValueCallback).

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.

IOException - If the array cannot be read.

readMap

public final <T> Map<String,T> readMap(ReadValueCallback<JsonReader,T> valueReaderFunc)
                                throws IOException

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(ReadValueCallback) or if a JSON array should be read use readArray(ReadValueCallback).

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.

IOException - If the map cannot be read.

readUntyped

public final Object readUntyped()
                         throws IOException

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, BigInteger, double, or BigDecimal if the starting token is JsonToken.NUMBER, the smallest containing value will be used
• 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.

IOException - If the untyped cannot be read.

getText

public final String getText()
                     throws IOException

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 getBoolean()
• JsonToken.NULL -> "null"
• JsonToken.STRING -> getString()
• JsonToken.NUMBER -> String.valueOf getString()

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.

IOException - If the text cannot be read.

getRawText

public String getRawText()
                  throws IOException

Gets the raw 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() retaining JSON encoded and quoted characters
• JsonToken.BOOLEAN -> String.valueOf getBoolean()
• JsonToken.NULL -> "null"
• JsonToken.STRING -> getString() retaining JSON encoded and quoted characters
• JsonToken.NUMBER -> String.valueOf getString()

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

Returns:

The raw text value for the currentToken().

Throws:

IllegalStateException - If the current token is null.

IOException - If the text cannot be read.