Package com.google.gson
Class JsonElement
java.lang.Object
com.google.gson.JsonElement
- Direct Known Subclasses:
JsonArray
,JsonNull
,JsonObject
,JsonPrimitive
A class representing an element of JSON. It could either be a Converting
There are two ways to parse JSON data as a
JsonObject
, a JsonArray
, a JsonPrimitive
or a JsonNull
.
This class provides multiple getAs
methods which allow
- obtaining the represented primitive value, for example
getAsString()
- casting to the
JsonElement
subclasses in a convenient way, for examplegetAsJsonObject()
Converting JsonElement
from / to JSON
There are two ways to parse JSON data as a JsonElement
:
JsonParser
, for example:JsonObject jsonObject = JsonParser.parseString("{}").getAsJsonObject();
Gson.fromJson(..., JsonElement.class)
It is possible to directly specify aJsonElement
subclass, for example:JsonObject jsonObject = gson.fromJson("{}", JsonObject.class);
JsonElement
to JSON either JsonElement.toString()
or the
method Gson.toJson(JsonElement)
and its overloads can be used.
It is also possible to obtain the TypeAdapter
for JsonElement
from a Gson
instance and then use it for conversion from and to JSON:
TypeAdapter<JsonElement> adapter = gson.getAdapter(JsonElement.class);
JsonElement value = adapter.fromJson("{}");
String json = adapter.toJson(value);
JsonElement
as JSON data
JsonElement
can also be treated as JSON data, allowing to deserialize from a
JsonElement
and serializing to a JsonElement
. The Gson
class offers these
methods for this:
Gson.fromJson(JsonElement, ...)
, for example:JsonObject jsonObject = ...; MyClass myObj = gson.fromJson(jsonObject, MyClass.class);
Gson.toJsonTree(Object)
, for example:MyClass myObj = ...; JsonElement json = gson.toJsonTree(myObj);
TypeAdapter
class provides corresponding methods as well:
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionabstract JsonElement
deepCopy()
Returns a deep copy of this element.Convenience method to get this element as aBigDecimal
.Convenience method to get this element as aBigInteger
.boolean
Convenience method to get this element as a boolean value.byte
Convenience method to get this element as a primitive byte value.char
Deprecated.This method is misleading, as it does not get this element as a char but rather as a string's first character.double
Convenience method to get this element as a primitive double value.float
Convenience method to get this element as a primitive float value.int
getAsInt()
Convenience method to get this element as a primitive integer value.Convenience method to get this element as aJsonArray
.Convenience method to get this element as aJsonNull
.Convenience method to get this element as aJsonObject
.Convenience method to get this element as aJsonPrimitive
.long
Convenience method to get this element as a primitive long value.Convenience method to get this element as aNumber
.short
Convenience method to get this element as a primitive short value.Convenience method to get this element as a string value.boolean
Provides a check for verifying if this element is a JSON array or not.boolean
Provides a check for verifying if this element represents a null value or not.boolean
Provides a check for verifying if this element is a JSON object or not.boolean
Provides a check for verifying if this element is a primitive or not.toString()
Converts this element to a JSON string.
-
Constructor Details
-
JsonElement
Deprecated.Creating customJsonElement
subclasses is highly discouraged and can lead to undefined behavior.
This constructor is only kept for backward compatibility.
-
-
Method Details
-
deepCopy
Returns a deep copy of this element. Immutable elements like primitives and nulls are not copied.- Since:
- 2.8.2
-
isJsonArray
public boolean isJsonArray()Provides a check for verifying if this element is a JSON array or not.- Returns:
- true if this element is of type
JsonArray
, false otherwise.
-
isJsonObject
public boolean isJsonObject()Provides a check for verifying if this element is a JSON object or not.- Returns:
- true if this element is of type
JsonObject
, false otherwise.
-
isJsonPrimitive
public boolean isJsonPrimitive()Provides a check for verifying if this element is a primitive or not.- Returns:
- true if this element is of type
JsonPrimitive
, false otherwise.
-
isJsonNull
public boolean isJsonNull()Provides a check for verifying if this element represents a null value or not.- Returns:
- true if this element is of type
JsonNull
, false otherwise. - Since:
- 1.2
-
getAsJsonObject
Convenience method to get this element as aJsonObject
. If this element is of some other type, anIllegalStateException
will result. Hence it is best to use this method after ensuring that this element is of the desired type by callingisJsonObject()
first.- Returns:
- this element as a
JsonObject
. - Throws:
IllegalStateException
- if this element is of another type.
-
getAsJsonArray
Convenience method to get this element as aJsonArray
. If this element is of some other type, anIllegalStateException
will result. Hence it is best to use this method after ensuring that this element is of the desired type by callingisJsonArray()
first.- Returns:
- this element as a
JsonArray
. - Throws:
IllegalStateException
- if this element is of another type.
-
getAsJsonPrimitive
Convenience method to get this element as aJsonPrimitive
. If this element is of some other type, anIllegalStateException
will result. Hence it is best to use this method after ensuring that this element is of the desired type by callingisJsonPrimitive()
first.- Returns:
- this element as a
JsonPrimitive
. - Throws:
IllegalStateException
- if this element is of another type.
-
getAsJsonNull
Convenience method to get this element as aJsonNull
. If this element is of some other type, anIllegalStateException
will result. Hence it is best to use this method after ensuring that this element is of the desired type by callingisJsonNull()
first.- Returns:
- this element as a
JsonNull
. - Throws:
IllegalStateException
- if this element is of another type.- Since:
- 1.2
-
getAsBoolean
public boolean getAsBoolean()Convenience method to get this element as a boolean value.- Returns:
- this element as a primitive boolean value.
- Throws:
UnsupportedOperationException
- if this element is not aJsonPrimitive
orJsonArray
.IllegalStateException
- if this element is of the typeJsonArray
but contains more than a single element.
-
getAsNumber
Convenience method to get this element as aNumber
.- Returns:
- this element as a
Number
. - Throws:
UnsupportedOperationException
- if this element is not aJsonPrimitive
orJsonArray
, or cannot be converted to a number.IllegalStateException
- if this element is of the typeJsonArray
but contains more than a single element.
-
getAsString
Convenience method to get this element as a string value.- Returns:
- this element as a string value.
- Throws:
UnsupportedOperationException
- if this element is not aJsonPrimitive
orJsonArray
.IllegalStateException
- if this element is of the typeJsonArray
but contains more than a single element.
-
getAsDouble
public double getAsDouble()Convenience method to get this element as a primitive double value.- Returns:
- this element as a primitive double value.
- Throws:
UnsupportedOperationException
- if this element is not aJsonPrimitive
orJsonArray
.NumberFormatException
- if the value contained is not a valid double.IllegalStateException
- if this element is of the typeJsonArray
but contains more than a single element.
-
getAsFloat
public float getAsFloat()Convenience method to get this element as a primitive float value.- Returns:
- this element as a primitive float value.
- Throws:
UnsupportedOperationException
- if this element is not aJsonPrimitive
orJsonArray
.NumberFormatException
- if the value contained is not a valid float.IllegalStateException
- if this element is of the typeJsonArray
but contains more than a single element.
-
getAsLong
public long getAsLong()Convenience method to get this element as a primitive long value.- Returns:
- this element as a primitive long value.
- Throws:
UnsupportedOperationException
- if this element is not aJsonPrimitive
orJsonArray
.NumberFormatException
- if the value contained is not a valid long.IllegalStateException
- if this element is of the typeJsonArray
but contains more than a single element.
-
getAsInt
public int getAsInt()Convenience method to get this element as a primitive integer value.- Returns:
- this element as a primitive integer value.
- Throws:
UnsupportedOperationException
- if this element is not aJsonPrimitive
orJsonArray
.NumberFormatException
- if the value contained is not a valid integer.IllegalStateException
- if this element is of the typeJsonArray
but contains more than a single element.
-
getAsByte
public byte getAsByte()Convenience method to get this element as a primitive byte value.- Returns:
- this element as a primitive byte value.
- Throws:
UnsupportedOperationException
- if this element is not aJsonPrimitive
orJsonArray
.NumberFormatException
- if the value contained is not a valid byte.IllegalStateException
- if this element is of the typeJsonArray
but contains more than a single element.- Since:
- 1.3
-
getAsCharacter
Deprecated.This method is misleading, as it does not get this element as a char but rather as a string's first character.Convenience method to get the first character of the string value of this element.- Returns:
- the first character of the string value.
- Throws:
UnsupportedOperationException
- if this element is not aJsonPrimitive
orJsonArray
, or if its string value is empty.IllegalStateException
- if this element is of the typeJsonArray
but contains more than a single element.- Since:
- 1.3
-
getAsBigDecimal
Convenience method to get this element as aBigDecimal
.- Returns:
- this element as a
BigDecimal
. - Throws:
UnsupportedOperationException
- if this element is not aJsonPrimitive
orJsonArray
.NumberFormatException
- if this element is not a validBigDecimal
.IllegalStateException
- if this element is of the typeJsonArray
but contains more than a single element.- Since:
- 1.2
-
getAsBigInteger
Convenience method to get this element as aBigInteger
.- Returns:
- this element as a
BigInteger
. - Throws:
UnsupportedOperationException
- if this element is not aJsonPrimitive
orJsonArray
.NumberFormatException
- if this element is not a validBigInteger
.IllegalStateException
- if this element is of the typeJsonArray
but contains more than a single element.- Since:
- 1.2
-
getAsShort
public short getAsShort()Convenience method to get this element as a primitive short value.- Returns:
- this element as a primitive short value.
- Throws:
UnsupportedOperationException
- if this element is not aJsonPrimitive
orJsonArray
.NumberFormatException
- if the value contained is not a valid short.IllegalStateException
- if this element is of the typeJsonArray
but contains more than a single element.
-
toString
Converts this element to a JSON string.For example:
JsonObject object = new JsonObject(); object.add("a", JsonNull.INSTANCE); JsonArray array = new JsonArray(); array.add(1); object.add("b", array); String json = object.toString(); // json: {"a":null,"b":[1]}
If this element or any nested elements containNaN
orInfinity
that value is written to JSON, even though the JSON specification does not permit these values.To customize formatting or to directly write to an
Appendable
instead of creating an intermediateString
first, useGson.toJson(JsonElement, ...)
.To get the contained String value (without enclosing
"
and without escaping), usegetAsString()
instead:JsonPrimitive jsonPrimitive = new JsonPrimitive("with \" quote"); String json = jsonPrimitive.toString(); // json: "with \" quote" String value = jsonPrimitive.getAsString(); // value: with " quote
-
JsonElement
subclasses is highly discouraged and can lead to undefined behavior.This constructor is only kept for backward compatibility.