TypeAdapter
Date: 2016-11-03

com.google.gson

## Class TypeAdapter<T>

- java.lang.Object
- - com.google.gson.TypeAdapter<T>

- Direct Known Subclasses:
    ArrayTypeAdapter, DateTypeAdapter, ObjectTypeAdapter, ReflectiveTypeAdapterFactory.Adapter, SqlDateTypeAdapter, TimeTypeAdapter, TreeTypeAdapter

      public abstract class TypeAdapter<T>
      extends java.lang.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);
           }
         }

  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.

  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 and Description
    `TypeAdapter()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `T` | `fromJson(java.io.Reader in)` Converts the JSON document in `in` to a Java object.
    `T` | `fromJson(java.lang.String json)` Converts the JSON document in `json` to a Java object.
    `T` | `fromJsonTree(JsonElement jsonTree)` Converts `jsonTree` 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.
    `java.lang.String` | `toJson(T value)` Converts `value` to a JSON document.
    `void` | `toJson(java.io.Writer out, T value)` Converts `value` to a JSON document and writes it to `out`.
    `JsonElement` | `toJsonTree(T value)` Converts `value` to a JSON tree.
    `abstract void` | `write(JsonWriter out, T value)` Writes one JSON value (an array, object, string, number, boolean or null) for `value`.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### TypeAdapter

          public TypeAdapter()

  - ### Method Detail

    - #### write

          public abstract void write(JsonWriter out,
                   T value)
                              throws java.io.IOException

      Writes one JSON value (an array, object, string, number, boolean or null) for `value`.
      Parameters:
        `value` - the Java object to write. May be null.
      Throws:
        `java.io.IOException`

    - #### toJson

          public final void toJson(java.io.Writer out,
                    T value)
                            throws java.io.IOException

      Converts `value` to a JSON document and writes it to `out`. Unlike Gson's similar `toJson` method, this write is strict. Create a `lenient` `JsonWriter` and call `write(com.google.gson.stream.JsonWriter, Object)` for lenient writing.
      Parameters:
        `value` - the Java object to convert. May be null.
      Throws:
        `java.io.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();

      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 {
                 // 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();

      Note that we didn't need to check for nulls in our type adapter after we used nullSafe.

    - #### toJson

          public final java.lang.String toJson(T value)

      Converts `value` to a JSON document. Unlike Gson's similar `toJson` method, this write is strict. Create a `lenient` `JsonWriter` and call `write(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)

      Converts `value` 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 java.io.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:
        `java.io.IOException`

    - #### fromJson

          public final T fromJson(java.io.Reader in)
                           throws java.io.IOException

      Converts the JSON document in `in` to a Java object. Unlike Gson's similar `fromJson` method, this read is strict. Create a `lenient` `JsonReader` and call `read(JsonReader)` for lenient reading.
      Returns:
        the converted Java object. May be null.
      Throws:
        `java.io.IOException`
      Since:
        2.2

    - #### fromJson

          public final T fromJson(java.lang.String json)
                           throws java.io.IOException

      Converts the JSON document in `json` to a Java object. Unlike Gson's similar `fromJson` method, this read is strict. Create a `lenient` `JsonReader` and call `read(JsonReader)` for lenient reading.
      Returns:
        the converted Java object. May be null.
      Throws:
        `java.io.IOException`
      Since:
        2.2

    - #### fromJsonTree

          public final T fromJsonTree(JsonElement jsonTree)

      Converts `jsonTree` to a Java object.
      Parameters:
        `jsonTree` - the Java object to convert. May be `JsonNull`.
      Since:
        2.2