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.