- java.lang.Object
-
- com.google.gson.TypeAdapter<T>
-
public abstract class TypeAdapter<T> extends Object
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); } }
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 andwrite()
must write exactly one value. For primitive types this is means readers should make exactly one call tonextBoolean()
,nextDouble()
,nextInt()
,nextLong()
,nextString()
ornextNull()
. Writers should make exactly one call to one ofvalue()
ornullValue()
. For arrays, type adapters should start with a call tobeginArray()
, convert all elements, and finish with a call toendArray()
. For objects, they should start withbeginObject()
, convert the object, and finish withendObject()
. 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 yourGson
instance has been configured toGsonBuilder.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.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();
- Since:
- 2.1
-
-
Constructor Summary
Constructors Constructor Description TypeAdapter()
-
Method Summary
All Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description T
fromJson(Reader in)
Converts the JSON document inin
to a Java object.T
fromJson(String json)
Converts the JSON document injson
to a Java object.T
fromJsonTree(JsonElement jsonTree)
ConvertsjsonTree
to a Java object.TypeAdapter<T>
nullSafe()
This wrapper method is used to make a type adapter null tolerant.abstract T
read(JsonReader in)
Reads one JSON value (an array, object, string, number, boolean or null) and converts it to a Java object.void
toJson(Writer out, T value)
Convertsvalue
to a JSON document and writes it toout
.String
toJson(T value)
Convertsvalue
to a JSON document.JsonElement
toJsonTree(T value)
Convertsvalue
to a JSON tree.abstract void
write(JsonWriter out, T value)
Writes one JSON value (an array, object, string, number, boolean or null) forvalue
.
-
-
-
Method Detail
-
write
public abstract void write(JsonWriter out, T value) throws IOException
Writes one JSON value (an array, object, string, number, boolean or null) forvalue
.- Parameters:
value
- the Java object to write. May be null.- Throws:
IOException
-
toJson
public final void toJson(Writer out, T value) throws IOException
Convertsvalue
to a JSON document and writes it toout
. Unlike Gson's similartoJson
method, this write is strict. Create alenient
JsonWriter
and callwrite(com.google.gson.stream.JsonWriter, Object)
for lenient writing.- Parameters:
value
- the Java object to convert. May be null.- Throws:
IOException
- Since:
- 2.2
-
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();
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();
-
toJson
public final String toJson(T value)
Convertsvalue
to a JSON document. Unlike Gson's similartoJson
method, this write is strict. Create alenient
JsonWriter
and callwrite(com.google.gson.stream.JsonWriter, Object)
for lenient writing.- Parameters:
value
- the Java object to convert. May be null.- Since:
- 2.2
-
toJsonTree
public final JsonElement toJsonTree(T value)
Convertsvalue
to a JSON tree.- Parameters:
value
- the Java object to convert. May be null.- Returns:
- the converted JSON tree. May be
JsonNull
. - Since:
- 2.2
-
read
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:
- the converted Java object. May be null.
- Throws:
IOException
-
fromJson
public final T fromJson(Reader in) throws IOException
Converts the JSON document inin
to a Java object. Unlike Gson's similarfromJson
method, this read is strict. Create alenient
JsonReader
and callread(JsonReader)
for lenient reading.- Returns:
- the converted Java object. May be null.
- Throws:
IOException
- Since:
- 2.2
-
fromJson
public final T fromJson(String json) throws IOException
Converts the JSON document injson
to a Java object. Unlike Gson's similarfromJson
method, this read is strict. Create alenient
JsonReader
and callread(JsonReader)
for lenient reading.- Returns:
- the converted Java object. May be null.
- Throws:
IOException
- Since:
- 2.2
-
fromJsonTree
public final T fromJsonTree(JsonElement jsonTree)
ConvertsjsonTree
to a Java object.- Parameters:
jsonTree
- the Java object to convert. May beJsonNull
.- Since:
- 2.2
-
-