Converts Java objects to and from JSON.

Defining a type's JSON form

By default Gson converts application classes to JSON using its built-in type adapters. If Gson's default JSON conversion isn't appropriate for a type, extend this class to customize the conversion. Here's an example of a type adapter for an (X,Y) coordinate point:

public class PointAdapter extends TypeAdapter<Point> {
  public Point read(JsonReader reader) throws IOException {
    if (reader.peek() == JsonToken.NULL) {
      reader.nextNull();
      return null;
    }
    String xy = reader.nextString();
    String[] parts = xy.split(",");
    int x = Integer.parseInt(parts[0]);
    int y = Integer.parseInt(parts[1]);
    return new Point(x, y);
  }
  public void write(JsonWriter writer, Point value) throws IOException {
    if (value == null) {
      writer.nullValue();
      return;
    }
    String xy = value.getX() + "," + value.getY();
    writer.value(xy);
  }
}

With this type adapter installed, Gson will convert Points to JSON as strings like "5,8" rather than objects like {"x":5,"y":8}. In this case the type adapter binds a rich Java class to a compact JSON value.

The read() method must read exactly one value and write() must write exactly one value. For primitive types this is means readers should make exactly one call to nextBoolean(), nextDouble(), nextInt(), nextLong(), nextString() or nextNull(). Writers should make exactly one call to one of value() or nullValue(). For arrays, type adapters should start with a call to beginArray(), convert all elements, and finish with a call to endArray(). For objects, they should start with beginObject(), convert the object, and finish with endObject(). Failing to convert a value or converting too many values may cause the application to crash.

Type adapters should be prepared to read null from the stream and write it to the stream. Alternatively, they should use nullSafe() method while registering the type adapter with Gson. If your Gson instance has been configured to GsonBuilder#serializeNulls(), these nulls will be written to the final document. Otherwise the value (and the corresponding name when writing to a JSON object) will be omitted automatically. In either case your type adapter must handle null.

Type adapters should be stateless and thread-safe, otherwise the thread-safety guarantees of Gson might not apply.

To use a custom type adapter with Gson, you must register it with a GsonBuilder:

GsonBuilder builder = new GsonBuilder();
builder.registerTypeAdapter(Point.class, new PointAdapter());
// if PointAdapter didn't check for nulls in its read/write methods, you should instead use
// builder.registerTypeAdapter(Point.class, new PointAdapter().nullSafe());
...
Gson gson = builder.create();

Modifier and Type	Class and Description
private class	TypeAdapter.NullSafeTypeAdapter

Constructor Summary

Access	Constructor and Description
public	TypeAdapter()

Method Summary

Modifier and Type	Method and Description
public final T	Returns: the converted Java object. May be `null`. fromJson(Reader in) Converts the JSON document in `in` to a Java object.
public final T	Returns: the converted Java object. May be `null`. fromJson(String json) Converts the JSON document in `json` to a Java object.
public final T	Returns: the converted Java object. May be `null`. fromJsonTree(JsonElement the JSON element to convert. May be `JsonNull`. jsonTree) Converts `jsonTree` to a Java object.
public final TypeAdapter<T>	nullSafe() This wrapper method is used to make a type adapter null tolerant.
public abstract T	Returns: the converted Java object. May be `null`. read(JsonReader in) Reads one JSON value (an array, object, string, number, boolean or null) and converts it to a Java object.
public final void	toJson(Writer out, T the Java object to convert. May be `null`. value) Converts `value` to a JSON document and writes it to `out`.
public final String	toJson(T the Java object to convert. May be `null`. value) Converts `value` to a JSON document.
public final JsonElement	Returns: the converted JSON tree. May be `JsonNull`. toJsonTree(T the Java object to convert. May be `null`. value) Converts `value` to a JSON tree.
public abstract void	write(JsonWriter out, T the Java object to write. May be null. value) Writes one JSON value (an array, object, string, number, boolean or null) for `value`.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Constructor Detail

TypeAdapter	back to summary
public TypeAdapter()

Method Detail

fromJson back to summary

fromJson	back to summary
public final T fromJson(Reader in) throws IOException Converts the JSON document in `in` to a Java object. A `JsonReader` with default configuration (that is with `Strictness#LEGACY_STRICT` as strictness) is used for reading the JSON data. To customize this behavior, create a `JsonReader`, configure it and then use `read(JsonReader)` instead. No exception is thrown if the JSON data has multiple top-level JSON elements, or if there is trailing data. Returns:T the converted Java object. May be `null`. Since 2.2

public final T fromJson(Reader in) throws IOException

Converts the JSON document in in to a Java object.

A JsonReader with default configuration (that is with Strictness#LEGACY_STRICT as strictness) is used for reading the JSON data. To customize this behavior, create a JsonReader, configure it and then use read(JsonReader) instead.

No exception is thrown if the JSON data has multiple top-level JSON elements, or if there is trailing data.

Returns:T: the converted Java object. May be null.
Since: 2.2

fromJson back to summary

fromJson	back to summary
public final T fromJson(String json) throws IOException Converts the JSON document in `json` to a Java object. A `JsonReader` with default configuration (that is with `Strictness#LEGACY_STRICT` as strictness) is used for reading the JSON data. To customize this behavior, create a `JsonReader`, configure it and then use `read(JsonReader)` instead. No exception is thrown if the JSON data has multiple top-level JSON elements, or if there is trailing data. Returns:T the converted Java object. May be `null`. Since 2.2

public final T fromJson(String json) throws IOException

Converts the JSON document in json to a Java object.

No exception is thrown if the JSON data has multiple top-level JSON elements, or if there is trailing data.

Returns:T: the converted Java object. May be null.
Since: 2.2

fromJsonTree back to summary

fromJsonTree	back to summary
public final T fromJsonTree(JsonElement jsonTree) Converts `jsonTree` to a Java object. Parameters jsonTree:JsonElement the JSON element to convert. May be `JsonNull`. Returns:T the converted Java object. May be `null`. Exceptions JsonIOException: wrapping `IOException`s thrown by `read(JsonReader)` Since 2.2

public final T fromJsonTree(JsonElement jsonTree)

Converts jsonTree to a Java object.

Parameters

jsonTree:JsonElement: the JSON element to convert. May be JsonNull.

Returns:T

the converted Java object. May be null.

Exceptions

JsonIOException:: wrapping IOExceptions thrown by read(JsonReader)

Since

2.2

nullSafe back to summary

nullSafe	back to summary
public final TypeAdapter<T> nullSafe() This wrapper method is used to make a type adapter null tolerant. In general, a type adapter is required to handle nulls in write and read methods. Here is how this is typically done: `Gson gson = new GsonBuilder().registerTypeAdapter(Foo.class, new TypeAdapter<Foo>() { public Foo read(JsonReader in) throws IOException { if (in.peek() == JsonToken.NULL) { in.nextNull(); return null; } // read a Foo from in and return it } public void write(JsonWriter out, Foo src) throws IOException { if (src == null) { out.nullValue(); return; } // write src as JSON to out } }).create();` You can avoid this boilerplate handling of nulls by wrapping your type adapter with this method. Here is how we will rewrite the above example: `Gson gson = new GsonBuilder().registerTypeAdapter(Foo.class, new TypeAdapter<Foo>() { public Foo read(JsonReader in) throws IOException { // read a Foo from in and return it } public void write(JsonWriter out, Foo src) throws IOException { // write src as JSON to out } }.nullSafe()).create();` Note that we didn't need to check for nulls in our type adapter after we used nullSafe.

public final TypeAdapter<T> nullSafe()

This wrapper method is used to make a type adapter null tolerant. In general, a type adapter is required to handle nulls in write and read methods. Here is how this is typically done:

Gson gson = new GsonBuilder().registerTypeAdapter(Foo.class,
  new TypeAdapter<Foo>() {
    public Foo read(JsonReader in) throws IOException {
      if (in.peek() == JsonToken.NULL) {
        in.nextNull();
        return null;
      }
      // read a Foo from in and return it
    }
    public void write(JsonWriter out, Foo src) throws IOException {
      if (src == null) {
        out.nullValue();
        return;
      }
      // write src as JSON to out
    }
  }).create();

You can avoid this boilerplate handling of nulls by wrapping your type adapter with this method. Here is how we will rewrite the above example:

Gson gson = new GsonBuilder().registerTypeAdapter(Foo.class,
  new TypeAdapter<Foo>() {
    public Foo read(JsonReader in) throws IOException {
      // read a Foo from in and return it
    }
    public void write(JsonWriter out, Foo src) throws IOException {
      // write src as JSON to out
    }
  }.nullSafe()).create();

Note that we didn't need to check for nulls in our type adapter after we used nullSafe.

read back to summary

read	back to summary
public abstract T read(JsonReader in) throws IOException Reads one JSON value (an array, object, string, number, boolean or null) and converts it to a Java object. Returns the converted object. Returns:T the converted Java object. May be `null`.

public abstract T read(JsonReader in) throws IOException

Reads one JSON value (an array, object, string, number, boolean or null) and converts it to a Java object. Returns the converted object.

Returns:T: the converted Java object. May be null.

toJson back to summary

toJson	back to summary
public final void toJson(Writer out, T value) throws IOException Converts `value` to a JSON document and writes it to `out`. A `JsonWriter` with default configuration is used for writing the JSON data. To customize this behavior, create a `JsonWriter`, configure it and then use `write(JsonWriter, Object)` instead. Parameters value:T the Java object to convert. May be `null`. Since 2.2

public final void toJson(Writer out, T value) throws IOException

Converts value to a JSON document and writes it to out.

A JsonWriter with default configuration is used for writing the JSON data. To customize this behavior, create a JsonWriter, configure it and then use write(JsonWriter, Object) instead.

Parameters

value:T: the Java object to convert. May be null.

Since

2.2

toJson back to summary

toJson	back to summary
public final String toJson(T value) Converts `value` to a JSON document. A `JsonWriter` with default configuration is used for writing the JSON data. To customize this behavior, create a `JsonWriter`, configure it and then use `write(JsonWriter, Object)` instead. Parameters value:T the Java object to convert. May be `null`. Exceptions JsonIOException: wrapping `IOException`s thrown by `write(JsonWriter, Object)` Since 2.2

public final String toJson(T value)

Converts value to a JSON document.

A JsonWriter with default configuration is used for writing the JSON data. To customize this behavior, create a JsonWriter, configure it and then use write(JsonWriter, Object) instead.

Parameters

value:T: the Java object to convert. May be null.

Exceptions

JsonIOException:: wrapping IOExceptions thrown by write(JsonWriter, Object)

Since

2.2

toJsonTree back to summary

toJsonTree	back to summary
public final JsonElement toJsonTree(T value) Converts `value` to a JSON tree. Parameters value:T the Java object to convert. May be `null`. Returns:JsonElement the converted JSON tree. May be `JsonNull`. Exceptions JsonIOException: wrapping `IOException`s thrown by `write(JsonWriter, Object)` Since 2.2

public final JsonElement toJsonTree(T value)

Converts value to a JSON tree.

Parameters

value:T: the Java object to convert. May be null.

Returns:JsonElement

the converted JSON tree. May be JsonNull.

Exceptions

JsonIOException:: wrapping IOExceptions thrown by write(JsonWriter, Object)

Since

2.2

write back to summary

write	back to summary
public abstract void write(JsonWriter out, T value) throws IOException Writes one JSON value (an array, object, string, number, boolean or null) for `value`. Parameters value:T the Java object to write. May be null.

public abstract void write(JsonWriter out, T value) throws IOException

Writes one JSON value (an array, object, string, number, boolean or null) for value.

Parameters

value:T: the Java object to write. May be null.

com.google.gson back to summary

private final Class TypeAdapter.NullSafeTypeAdapter

Class Inheritance

extends TypeAdapter<T>

java.lang.Object
com.google.gson.TypeAdapter
com.google.gson.TypeAdapter.NullSafeTypeAdapter

Constructor Summary

Access	Constructor and Description
private	NullSafeTypeAdapter()

Method Summary

Modifier and Type	Method and Description
public T	read(JsonReader reader) Implements abstract com.google.gson.TypeAdapter.read. Reads one JSON value (an array, object, string, number, boolean or null) and converts it to a Java object.
public String	toString() Overrides java.lang.Object.toString. Returns a string representation of the object.
public void	write(JsonWriter out, T value) Implements abstract com.google.gson.TypeAdapter.write. Writes one JSON value (an array, object, string, number, boolean or null) for `value`.

Inherited from com.google.gson.TypeAdapter:: fromJson fromJson fromJsonTree nullSafe toJson toJson toJsonTree

Constructor Detail

NullSafeTypeAdapter	back to summary
private NullSafeTypeAdapter()

Method Detail

read	back to summary
public T read(JsonReader reader) throws IOException Implements abstract com.google.gson.TypeAdapter.read. Doc from com.google.gson.TypeAdapter.read. Reads one JSON value (an array, object, string, number, boolean or null) and converts it to a Java object. Returns the converted object. Annotations @Override

read

back to summary

public T read(JsonReader reader) throws IOException

Implements abstract com.google.gson.TypeAdapter.read.

Doc from com.google.gson.TypeAdapter.read.

Reads one JSON value (an array, object, string, number, boolean or null) and converts it to a Java object. Returns the converted object.

Annotations

@Override

toString back to summary

toString	back to summary
public String toString() Overrides java.lang.Object.toString. Doc from java.lang.Object.toString. Returns a string representation of the object. Satisfying this method's contract implies a non-`null` result must be returned. Annotations @Override

public String toString()

Overrides java.lang.Object.toString.

Doc from java.lang.Object.toString.

Returns a string representation of the object. Satisfying this method's contract implies a non-null result must be returned.

Annotations

@Override

write back to summary

write	back to summary
public void write(JsonWriter out, T value) throws IOException Implements abstract com.google.gson.TypeAdapter.write. Doc from com.google.gson.TypeAdapter.write. Writes one JSON value (an array, object, string, number, boolean or null) for `value`. Annotations @Override

public void write(JsonWriter out, T value) throws IOException

Implements abstract com.google.gson.TypeAdapter.write.

Doc from com.google.gson.TypeAdapter.write.

Writes one JSON value (an array, object, string, number, boolean or null) for value.

Annotations

@Override

public abstract Class TypeAdapter<T>

Defining a type's JSON form

Nested and Inner Type Summary

Constructor Summary

Method Summary

Constructor Detail

Method Detail

private final Class TypeAdapter.NullSafeTypeAdapter

Constructor Summary

Method Summary

Constructor Detail

Method Detail