Class TypeAdapter<T>
- Direct Known Subclasses:
ArrayTypeAdapter
,CollectionTypeAdapterFactory.Adapter
,DefaultDateTypeAdapter
,EnumTypeAdapter
,InterceptorFactory.InterceptorAdapter
,JsonElementTypeAdapter
,MapTypeAdapterFactory.Adapter
,NumberTypeAdapter
,ObjectTypeAdapter
,PostConstructAdapterFactory.PostConstructAdapter
,ReflectiveTypeAdapterFactory.Adapter
,SerializationDelegatingTypeAdapter
,SqlDateTypeAdapter
,SqlTimestampTypeAdapter
,SqlTimeTypeAdapter
,TypeAdapter.NullSafeTypeAdapter
,TypeAdapterRuntimeTypeWrapper
,UtcDateTypeAdapter
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();
- Since:
- 2.1
-
Nested Class Summary
Nested Classes -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionfinal T
Converts the JSON document inin
to a Java object.final T
Converts the JSON document injson
to a Java object.final T
fromJsonTree
(JsonElement jsonTree) ConvertsjsonTree
to a Java object.final 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.final void
Convertsvalue
to a JSON document and writes it toout
.final String
Convertsvalue
to a JSON document.final 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
.
-
Constructor Details
-
TypeAdapter
public TypeAdapter()
-
-
Method Details
-
write
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
Convertsvalue
to a JSON document and writes it toout
.A
JsonWriter
with default configuration is used for writing the JSON data. To customize this behavior, create aJsonWriter
, configure it and then usewrite(JsonWriter, Object)
instead.- Parameters:
value
- the Java object to convert. May benull
.- Throws:
IOException
- Since:
- 2.2
-
toJson
Convertsvalue
to a JSON document.A
JsonWriter
with default configuration is used for writing the JSON data. To customize this behavior, create aJsonWriter
, configure it and then usewrite(JsonWriter, Object)
instead.- Parameters:
value
- the Java object to convert. May benull
.- Throws:
JsonIOException
- wrappingIOException
s thrown bywrite(JsonWriter, Object)
- Since:
- 2.2
-
toJsonTree
Convertsvalue
to a JSON tree.- Parameters:
value
- the Java object to convert. May benull
.- Returns:
- the converted JSON tree. May be
JsonNull
. - Throws:
JsonIOException
- wrappingIOException
s thrown bywrite(JsonWriter, Object)
- Since:
- 2.2
-
read
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
Converts the JSON document inin
to a Java object.A
JsonReader
with default configuration (that is withStrictness.LEGACY_STRICT
as strictness) is used for reading the JSON data. To customize this behavior, create aJsonReader
, configure it and then useread(JsonReader)
instead.No exception is thrown if the JSON data has multiple top-level JSON elements, or if there is trailing data.
- Returns:
- the converted Java object. May be
null
. - Throws:
IOException
- Since:
- 2.2
-
fromJson
Converts the JSON document injson
to a Java object.A
JsonReader
with default configuration (that is withStrictness.LEGACY_STRICT
as strictness) is used for reading the JSON data. To customize this behavior, create aJsonReader
, configure it and then useread(JsonReader)
instead.No exception is thrown if the JSON data has multiple top-level JSON elements, or if there is trailing data.
- Returns:
- the converted Java object. May be
null
. - Throws:
IOException
- Since:
- 2.2
-
fromJsonTree
ConvertsjsonTree
to a Java object.- Parameters:
jsonTree
- the JSON element to convert. May beJsonNull
.- Returns:
- the converted Java object. May be
null
. - Throws:
JsonIOException
- wrappingIOException
s thrown byread(JsonReader)
- Since:
- 2.2
-
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:
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 { 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();
Note that we didn't need to check for nulls in our type adapter after we used nullSafe.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();
-