Class JsonReader
- All Implemented Interfaces:
Closeable
,AutoCloseable
Instances of JsonReader
are created using an instance of JsonProvider
or using the utility methods
in JsonProviders
.
- See Also:
-
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionabstract JsonReader
Reads and returns the current JSON object theJsonReader
is pointing to.abstract void
close()
Closes the JSON stream.abstract JsonToken
Gets theJsonToken
that the reader currently points.abstract byte[]
Gets the binary value if the reader is currently pointing to aJsonToken.STRING
token.abstract boolean
Gets the boolean value if the reader is currently pointing to aJsonToken.BOOLEAN
token.abstract double
Gets the double value if the reader is currently pointing to aJsonToken.NUMBER
orJsonToken.STRING
.abstract String
Gets the field name if the reader is currently pointing to aJsonToken.FIELD_NAME
.abstract float
getFloat()
Gets the float value if the reader is currently pointing to aJsonToken.NUMBER
orJsonToken.STRING
.abstract int
getInt()
Gets the int value if the reader is currently pointing to aJsonToken.NUMBER
orJsonToken.STRING
.abstract long
getLong()
Gets the long value if the reader is currently pointing to aJsonToken.NUMBER
orJsonToken.STRING
.final <T> T
getNullable
(ReadValueCallback<JsonReader, T> nonNullGetter) Convenience method to read a nullable type.abstract String
Gets the String value if the reader is currently pointing to aJsonToken.BOOLEAN
,JsonToken.NULL
,JsonToken.NUMBER
, orJsonToken.STRING
.final String
getText()
Gets the text value for thecurrentToken()
.final boolean
abstract boolean
Indicates whether theJsonReader
supportsresetting
.final boolean
abstract JsonToken
Iterates to and returns the nextJsonToken
in the JSON encoded value.final <T> List<T>
readArray
(ReadValueCallback<JsonReader, T> elementReaderFunc) Reads a JSON array.final String
Recursively reads the JSON token sub-stream if the current token is eitherJsonToken.START_ARRAY
orJsonToken.START_OBJECT
.final void
readChildren
(StringBuilder buffer) Recursively reads the JSON token sub-stream if the current token is eitherJsonToken.START_ARRAY
orJsonToken.START_OBJECT
into the passedStringBuilder
.readMap
(ReadValueCallback<JsonReader, T> valueReaderFunc) Reads a JSON map.final <T> T
readObject
(ReadValueCallback<JsonReader, T> objectReaderFunc) Reads a JSON object.final String
Reads the remaining fields in the current JSON object as a JSON object.final void
Reads the remaining fields in the current JSON object as a JSON object.final Object
Reads an untyped object.abstract JsonReader
reset()
Creates a newJsonReader
reset to the beginning of the JSON stream.abstract void
Recursively skips the JSON token sub-stream if the current token is eitherJsonToken.START_ARRAY
orJsonToken.START_OBJECT
.
-
Constructor Details
-
JsonReader
public JsonReader()Creates an instance ofJsonReader
.
-
-
Method Details
-
currentToken
Gets theJsonToken
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
Iterates to and returns the nextJsonToken
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
Closes the JSON stream.- Specified by:
close
in interfaceAutoCloseable
- Specified by:
close
in interfaceCloseable
- Throws:
IOException
- If the underlying content store fails to close.
-
isStartArrayOrObject
public final boolean isStartArrayOrObject()- Returns:
- Whether the
currentToken()
isJsonToken.START_ARRAY
orJsonToken.START_OBJECT
.
-
isEndArrayOrObject
public final boolean isEndArrayOrObject()- Returns:
- Whether the
currentToken()
isJsonToken.END_ARRAY
orJsonToken.END_OBJECT
.
-
getBinary
Gets the binary value if the reader is currently pointing to aJsonToken.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 anIllegalStateException
will be thrown.- Returns:
- The binary value based on whether the current token is
JsonToken.STRING
orJsonToken.NULL
. - Throws:
IllegalStateException
- If the reader isn't pointing to eitherJsonToken.STRING
orJsonToken.NULL
.IOException
- If the next value cannot be read as binary.
-
getBoolean
Gets the boolean value if the reader is currently pointing to aJsonToken.BOOLEAN
token.If the reader is pointing to any other token type an
IllegalStateException
will be thrown.If
Boolean
should be read usegetNullable(ReadValueCallback)
.- Returns:
- The boolean value based on the
JsonToken.BOOLEAN
. - Throws:
IllegalStateException
- If the reader isn't pointing toJsonToken.BOOLEAN
.IOException
- If the next value cannot be read as a boolean.
-
getFloat
Gets the float value if the reader is currently pointing to aJsonToken.NUMBER
orJsonToken.STRING
.JsonToken.STRING
will throw aNumberFormatException
if the underlying string value cannot be converted to a float.All other
JsonToken
types will throw anIllegalStateException
.If
Float
should be read usegetNullable(ReadValueCallback)
.- Returns:
- The float value based on the current token.
- Throws:
NumberFormatException
- If the current token is aJsonToken.STRING
and cannot be converted to a float.IllegalStateException
- If the current token isn't aJsonToken.NUMBER
orJsonToken.STRING
.IOException
- If the next value cannot be read as a float.
-
getDouble
Gets the double value if the reader is currently pointing to aJsonToken.NUMBER
orJsonToken.STRING
.JsonToken.STRING
will throw aNumberFormatException
if the underlying string value cannot be converted to a double.All other
JsonToken
types will throw anIllegalStateException
.If
Double
should be read usegetNullable(ReadValueCallback)
.- Returns:
- The double value based on the current token.
- Throws:
NumberFormatException
- If the current token is aJsonToken.STRING
and cannot be converted to a double.IllegalStateException
- If the current token isn't aJsonToken.NUMBER
orJsonToken.STRING
.IOException
- If the next value cannot be read as a double.
-
getInt
Gets the int value if the reader is currently pointing to aJsonToken.NUMBER
orJsonToken.STRING
.JsonToken.STRING
will throw aNumberFormatException
if the underlying string value cannot be converted to an int.All other
JsonToken
types will throw anIllegalStateException
.If
Integer
should be read usegetNullable(ReadValueCallback)
.- Returns:
- The int value based on the current token.
- Throws:
NumberFormatException
- If the current token is aJsonToken.STRING
and cannot be converted to an int.IllegalStateException
- If the current token isn't aJsonToken.NUMBER
orJsonToken.STRING
.IOException
- If the next value cannot be read as an int.
-
getLong
Gets the long value if the reader is currently pointing to aJsonToken.NUMBER
orJsonToken.STRING
.JsonToken.STRING
will throw aNumberFormatException
if the underlying string value cannot be converted to a long.All other
JsonToken
types will throw anIllegalStateException
.If
Long
should be read usegetNullable(ReadValueCallback)
.- Returns:
- The long value based on the current token.
- Throws:
NumberFormatException
- If the current token is aJsonToken.STRING
and cannot be converted to a long.IllegalStateException
- If the current token isn't aJsonToken.NUMBER
orJsonToken.STRING
.IOException
- If the next value cannot be read as a long.
-
getString
Gets the String value if the reader is currently pointing to aJsonToken.BOOLEAN
,JsonToken.NULL
,JsonToken.NUMBER
, orJsonToken.STRING
.If the current token is a
JsonToken.BOOLEAN
, orJsonToken.NUMBER
the String representation of the value will be returned. If the current token isJsonToken.NULL
null will be returned.All other
JsonToken
types will throw anIllegalStateException
.- Returns:
- The String value based on the current token.
- Throws:
IllegalStateException
- If the current token isn't aJsonToken.BOOLEAN
,JsonToken.NULL
,JsonToken.NUMBER
, orJsonToken.STRING
.IOException
- If the next value cannot be read as a String.
-
getFieldName
Gets the field name if the reader is currently pointing to aJsonToken.FIELD_NAME
.All other
JsonToken
types will throw anIllegalStateException
.- Returns:
- The field name based on the current token.
- Throws:
IllegalStateException
- If the current token isn't aJsonToken.FIELD_NAME
.IOException
- If the next value cannot be read as a field name.
-
getNullable
Convenience method to read a nullable type.If the
currentToken()
isJsonToken.NULL
null will be returned, otherwise thisJsonReader
will be passed into thenonNullGetter
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()
isJsonToken.NULL
or the value returned bynonNullGetter
. - Throws:
IOException
- If the next value cannot be read as a nullable.
-
skipChildren
Recursively skips the JSON token sub-stream if the current token is eitherJsonToken.START_ARRAY
orJsonToken.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
Reads and returns the current JSON object theJsonReader
is pointing to. This will mutate the current location of thisJsonReader
.If the
currentToken()
isn'tJsonToken.START_OBJECT
orJsonToken.FIELD_NAME
anIllegalStateException
will be thrown.If the
currentToken()
isJsonToken.FIELD_NAME
this will create a JSON object where the first JSON field is thecurrentToken()
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 bereset()
to replay the underlying JSON stream.- Returns:
- The buffered JSON object the
JsonReader
was pointing to. - Throws:
IllegalStateException
- If thecurrentToken()
isn'tJsonToken.START_OBJECT
orJsonToken.FIELD_NAME
followed byJsonToken.START_OBJECT
IOException
- If the child object cannot be buffered.
-
isResetSupported
public abstract boolean isResetSupported()Indicates whether theJsonReader
supportsresetting
.- Returns:
- Whether
reset()
is supported.
-
reset
Creates a newJsonReader
reset to the beginning of the JSON stream.Use
isResetSupported()
to determine whether theJsonReader
can be reset. If resetting is called and it isn't supported anIllegalStateException
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 theJsonReader
cannot be reset.
-
readChildren
Recursively reads the JSON token sub-stream if the current token is eitherJsonToken.START_ARRAY
orJsonToken.START_OBJECT
.If the
currentToken()
isn'tJsonToken.START_OBJECT
orJsonToken.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
Recursively reads the JSON token sub-stream if the current token is eitherJsonToken.START_ARRAY
orJsonToken.START_OBJECT
into the passedStringBuilder
.If the
currentToken()
isn'tJsonToken.START_OBJECT
orJsonToken.START_ARRAY
nothing will be read.- Parameters:
buffer
- TheStringBuilder
where the read sub-stream will be written.- Throws:
NullPointerException
- Ifbuffer
is null.IOException
- If the children cannot be read.
-
readRemainingFieldsAsJsonObject
Reads the remaining fields in the current JSON object as a JSON object.If the
currentToken()
isJsonToken.START_OBJECT
this functions the same asreadChildren()
. If thecurrentToken()
isJsonToken.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'tJsonToken.START_OBJECT
orJsonToken.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
Reads the remaining fields in the current JSON object as a JSON object.If the
currentToken()
isJsonToken.START_OBJECT
this functions the same asreadChildren(StringBuilder)
. If thecurrentToken()
isJsonToken.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'tJsonToken.START_OBJECT
orJsonToken.FIELD_NAME
nothing will be read.- Parameters:
buffer
- TheStringBuilder
where the remaining JSON fields will be written.- Throws:
NullPointerException
- Ifbuffer
is null.IOException
- If the remaining JSON fields cannot be read.
-
readObject
Reads a JSON object.If the
currentToken()
is null this willread the next token
. If the starting token is still null orJsonToken.NULL
null will be returned. If the token is anything other thanJsonToken.START_OBJECT
anIllegalStateException
will be thrown.Once the JSON stream is prepared for object reading this will get the next token and pass this
JsonReader
into theobjectReaderFunc
to handle reading the object.If a JSON array should be read use
readArray(ReadValueCallback)
or if a JSON map should be read usereadMap(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 orJsonToken.NULL
. - Throws:
IllegalStateException
- If the token isn'tJsonToken.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 IOExceptionReads a JSON array.If the
currentToken()
is null this willread the next token
. If the starting token is still null orJsonToken.NULL
null will be returned. If the token is anything other thanJsonToken.START_ARRAY
anIllegalStateException
will be thrown.Once the JSON stream is prepared for element reading this will get the element token and pass this
JsonReader
into theelementReaderFunc
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 usereadMap(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 orJsonToken.NULL
. - Throws:
IllegalStateException
- If the token isn'tJsonToken.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 IOExceptionReads a JSON map.If the
currentToken()
is null this willread the next token
. If the starting token is still null orJsonToken.NULL
null will be returned. If the token is anything other thanJsonToken.START_OBJECT
anIllegalStateException
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 thevalueReaderFunc
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 usereadArray(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 orJsonToken.NULL
. - Throws:
IllegalStateException
- If the token isn'tJsonToken.START_OBJECT
,JsonToken.NULL
, or null.IOException
- If the map cannot be read.
-
readUntyped
Reads an untyped object.If the
currentToken()
is null this willread the next token
.If the starting token is
JsonToken.END_ARRAY
,JsonToken.END_OBJECT
, orJsonToken.FIELD_NAME
anIllegalStateException
will be thrown as these are invalid starting points for reading an unknown type. If the untyped object is deeply nested anIllegalStateException
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 isJsonToken.END_ARRAY
,JsonToken.END_OBJECT
, orJsonToken.FIELD_NAME
or if the untyped object is deeply nested.IOException
- If the untyped cannot be read.
- null if the starting token is null or
-
getText
Gets the text value for thecurrentToken()
.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.valueOfgetBoolean()
JsonToken.NULL
-> "null"JsonToken.STRING
->getString()
JsonToken.NUMBER
-> String.valueOfgetString()
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.
-