Package com.google.gson.annotations

Annotation Interface JsonAdapter

@Retention(RUNTIME)
@Target({TYPE,FIELD})
public @interface JsonAdapter

An annotation that indicates the Gson 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:

1. If a custom InstanceCreator has been registered for the adapter class, it will be used to create the instance
2. Otherwise, if the adapter class has a no-args constructor (regardless of which visibility), it will be invoked to create the instance
3. Otherwise, JDK Unsafe will be used to create the instance; see GsonBuilder.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

Modifier and Type	Required Element	Description
Class<?>	value	Either a TypeAdapter or TypeAdapterFactory, or one or both of JsonDeserializer or JsonSerializer.

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element	Description
boolean	nullSafe	Whether the adapter referenced by value() should be made null-safe.

Element Details

value

Class<?> value

Either a TypeAdapter or TypeAdapterFactory, or one or both of JsonDeserializer or JsonSerializer.

nullSafe

boolean nullSafe

Whether the adapter referenced by value() should be made null-safe.

If true (the default), it will be made null-safe and Gson will handle null Java objects on serialization and JSON null on deserialization without calling the adapter. If false, the adapter will have to handle the null values.

Default:

true