Package com.google.gson

Class JsonElement

java.lang.Object

com.google.gson.JsonElement

Direct Known Subclasses:

JsonArray, JsonNull, JsonObject, JsonPrimitive

public abstract class JsonElement
extends Object

A class representing an element of JSON. It could either be 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 example getAsJsonObject()

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 a JsonElement subclass, for example:

   JsonObject jsonObject = gson.fromJson("{}", JsonObject.class);
   

To convert a 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);
   

The TypeAdapter class provides corresponding methods as well:

• TypeAdapter.fromJsonTree(JsonElement)
• TypeAdapter.toJsonTree(Object)

Constructor Summary

Constructors

Constructor	Description
JsonElement()	Deprecated. Creating custom JsonElement subclasses is highly discouraged and can lead to undefined behavior. This constructor is only kept for backward compatibility.

Method Summary

Modifier and Type	Method	Description
abstract JsonElement	deepCopy()	Returns a deep copy of this element.
BigDecimal	getAsBigDecimal()	Convenience method to get this element as a BigDecimal.
BigInteger	getAsBigInteger()	Convenience method to get this element as a BigInteger.
boolean	getAsBoolean()	Convenience method to get this element as a boolean value.
byte	getAsByte()	Convenience method to get this element as a primitive byte value.
char	getAsCharacter()	Deprecated. This method is misleading, as it does not get this element as a char but rather as a string's first character.
double	getAsDouble()	Convenience method to get this element as a primitive double value.
float	getAsFloat()	Convenience method to get this element as a primitive float value.
int	getAsInt()	Convenience method to get this element as a primitive integer value.
JsonArray	getAsJsonArray()	Convenience method to get this element as a JsonArray.
JsonNull	getAsJsonNull()	Convenience method to get this element as a JsonNull.
JsonObject	getAsJsonObject()	Convenience method to get this element as a JsonObject.
JsonPrimitive	getAsJsonPrimitive()	Convenience method to get this element as a JsonPrimitive.
long	getAsLong()	Convenience method to get this element as a primitive long value.
Number	getAsNumber()	Convenience method to get this element as a Number.
short	getAsShort()	Convenience method to get this element as a primitive short value.
String	getAsString()	Convenience method to get this element as a string value.
boolean	isJsonArray()	Provides a check for verifying if this element is a JSON array or not.
boolean	isJsonNull()	Provides a check for verifying if this element represents a null value or not.
boolean	isJsonObject()	Provides a check for verifying if this element is a JSON object or not.
boolean	isJsonPrimitive()	Provides a check for verifying if this element is a primitive or not.
String	toString()	Converts this element to a JSON string.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Details

JsonElement

@Deprecated
public JsonElement()

Deprecated.

Creating custom JsonElement subclasses is highly discouraged and can lead to undefined behavior.
This constructor is only kept for backward compatibility.

Method Details

deepCopy

public abstract JsonElement 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

public JsonObject getAsJsonObject()

Convenience method to get this element as a JsonObject. If this element is of some other type, an IllegalStateException will result. Hence it is best to use this method after ensuring that this element is of the desired type by calling isJsonObject() first.

Returns:

this element as a JsonObject.

Throws:

IllegalStateException - if this element is of another type.

getAsJsonArray

public JsonArray getAsJsonArray()

Convenience method to get this element as a JsonArray. If this element is of some other type, an IllegalStateException will result. Hence it is best to use this method after ensuring that this element is of the desired type by calling isJsonArray() first.

Returns:

this element as a JsonArray.

Throws:

IllegalStateException - if this element is of another type.

getAsJsonPrimitive

public JsonPrimitive getAsJsonPrimitive()

Convenience method to get this element as a JsonPrimitive. If this element is of some other type, an IllegalStateException will result. Hence it is best to use this method after ensuring that this element is of the desired type by calling isJsonPrimitive() first.

Returns:

this element as a JsonPrimitive.

Throws:

IllegalStateException - if this element is of another type.

getAsJsonNull

@CanIgnoreReturnValue
public JsonNull getAsJsonNull()

Convenience method to get this element as a JsonNull. If this element is of some other type, an IllegalStateException will result. Hence it is best to use this method after ensuring that this element is of the desired type by calling isJsonNull() 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 a JsonPrimitive or JsonArray.

IllegalStateException - if this element is of the type JsonArray but contains more than a single element.

getAsNumber

public Number getAsNumber()

Convenience method to get this element as a Number.

Returns:

this element as a Number.

Throws:

UnsupportedOperationException - if this element is not a JsonPrimitive or JsonArray, or cannot be converted to a number.

IllegalStateException - if this element is of the type JsonArray but contains more than a single element.

getAsString

public String 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 a JsonPrimitive or JsonArray.

IllegalStateException - if this element is of the type JsonArray 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 a JsonPrimitive or JsonArray.

NumberFormatException - if the value contained is not a valid double.

IllegalStateException - if this element is of the type JsonArray 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 a JsonPrimitive or JsonArray.

NumberFormatException - if the value contained is not a valid float.

IllegalStateException - if this element is of the type JsonArray 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 a JsonPrimitive or JsonArray.

NumberFormatException - if the value contained is not a valid long.

IllegalStateException - if this element is of the type JsonArray 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 a JsonPrimitive or JsonArray.

NumberFormatException - if the value contained is not a valid integer.

IllegalStateException - if this element is of the type JsonArray 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 a JsonPrimitive or JsonArray.

NumberFormatException - if the value contained is not a valid byte.

IllegalStateException - if this element is of the type JsonArray but contains more than a single element.

Since:

1.3

getAsCharacter

@Deprecated
public char 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 a JsonPrimitive or JsonArray, or if its string value is empty.

IllegalStateException - if this element is of the type JsonArray but contains more than a single element.

Since:

1.3

getAsBigDecimal

public BigDecimal getAsBigDecimal()

Convenience method to get this element as a BigDecimal.

Returns:

this element as a BigDecimal.

Throws:

UnsupportedOperationException - if this element is not a JsonPrimitive or JsonArray.

NumberFormatException - if this element is not a valid BigDecimal.

IllegalStateException - if this element is of the type JsonArray but contains more than a single element.

Since:

1.2

getAsBigInteger

public BigInteger getAsBigInteger()

Convenience method to get this element as a BigInteger.

Returns:

this element as a BigInteger.

Throws:

UnsupportedOperationException - if this element is not a JsonPrimitive or JsonArray.

NumberFormatException - if this element is not a valid BigInteger.

IllegalStateException - if this element is of the type JsonArray 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 a JsonPrimitive or JsonArray.

NumberFormatException - if the value contained is not a valid short.

IllegalStateException - if this element is of the type JsonArray but contains more than a single element.

toString

public String 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 contain NaN or Infinity 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 intermediate String first, use Gson.toJson(JsonElement, ...).

To get the contained String value (without enclosing " and without escaping), use getAsString() instead:

 JsonPrimitive jsonPrimitive = new JsonPrimitive("with \" quote");
 String json = jsonPrimitive.toString();
 // json: "with \" quote"
 String value = jsonPrimitive.getAsString();
 // value: with " quote
 

Overrides:

toString in class Object