Annotation Type JsonAdapter
TypeAdapter
to use with a class or field.
Here is an example of how this annotation is used:
@JsonAdapter(UserJsonAdapter.class) public class User { public final String firstName, lastName; private User(String firstName, String lastName) { this.firstName = firstName; this.lastName = lastName; } } public class UserJsonAdapter extends TypeAdapter<User> { @Override public void write(JsonWriter out, User user) throws IOException { // implement write: combine firstName and lastName into name out.beginObject(); out.name("name"); out.value(user.firstName + " " + user.lastName); out.endObject(); } @Override public User read(JsonReader in) throws IOException { // implement read: split name into firstName and lastName in.beginObject(); in.nextName(); String[] nameParts = in.nextString().split(" "); in.endObject(); return new User(nameParts[0], nameParts[1]); } }Since
User
class specified UserJsonAdapter.class
in @JsonAdapter
annotation, it will automatically be invoked to serialize/deserialize User
instances.
Here is an example of how to apply this annotation to a field.
private static final class Gadget { @JsonAdapter(UserJsonAdapter.class) final User user; Gadget(User user) { this.user = user; } }It's possible to specify different type adapters on a field, that field's type, and in the
GsonBuilder
. Field annotations take precedence over GsonBuilder
-registered type
adapters, which in turn take precedence over annotated types.
The class referenced by this annotation must be either a TypeAdapter
or a TypeAdapterFactory
, or must implement one or both of JsonDeserializer
or JsonSerializer
. Using TypeAdapterFactory
makes it possible to delegate to the enclosing
Gson
instance. By default the specified adapter will not be called for null
values; set nullSafe()
to false
to let the adapter handle null
values
itself.
The type adapter is created in the same way Gson creates instances of custom classes during deserialization, that means:
- If a custom
InstanceCreator
has been registered for the adapter class, it will be used to create the instance - Otherwise, if the adapter class has a no-args constructor (regardless of which visibility), it will be invoked to create the instance
- Otherwise, JDK
Unsafe
will be used to create the instance; seeGsonBuilder.disableJdkUnsafe()
for the unexpected side-effects this might have
Gson
instances might cache the adapter they create for a @JsonAdapter
annotation. It is not guaranteed that a new adapter is created every time the annotated class or
field is serialized or deserialized.
- Since:
- 2.3
-
Required Element Summary
Required Elements -
Optional Element Summary
Optional Elements
-
Element Details
-
value
Class<?> value -
nullSafe
boolean nullSafeWhether the adapter referenced byvalue()
should be made null-safe.If
true
(the default), it will be made null-safe and Gson will handlenull
Java objects on serialization and JSONnull
on deserialization without calling the adapter. Iffalse
, the adapter will have to handle thenull
values.- Default:
true
-