RuntimeTypeAdapterFactory

public final class RuntimeTypeAdapterFactory<T> implements TypeAdapterFactory

Adapts values whose runtime type may differ from their declaration type. This is necessary when a field's type is not the same type that GSON should create when deserializing that field. For example, consider these types:

   {@code * abstract class Shape { * int x; * int y; * } * class Circle extends Shape { * int radius; * } * class Rectangle extends Shape { * int width; * int height; * } * class Diamond extends Shape { * int width; * int height; * } * class Drawing { * Shape bottomShape; * Shape topShape; * } * }

Without additional type information, the serialized JSON is ambiguous. Is the bottom shape in this drawing a rectangle or a diamond?

   {@code * { * "bottomShape": { * "width": 10, * "height": 5, * "x": 0, * "y": 0 * }, * "topShape": { * "radius": 2, * "x": 4, * "y": 1 * } * }}

This class addresses this problem by adding type information to the serialized JSON and honoring that type information when the JSON is deserialized:

   {@code * { * "bottomShape": { * "type": "Diamond", * "width": 10, * "height": 5, * "x": 0, * "y": 0 * }, * "topShape": { * "type": "Circle", * "radius": 2, * "x": 4, * "y": 1 * } * }}

Both the type field name ({@code "type"}) and the type labels ({@code * "Rectangle"}) are configurable. Registering Types Create a {@code RuntimeTypeAdapterFactory} by passing the base type and type field name to the of factory method. If you don't supply an explicit type field name, {@code "type"} will be used.

   {@code * RuntimeTypeAdapterFactoryshapeAdapterFactory
 *       = RuntimeTypeAdapterFactory.of(Shape.class, "type");
 * }

Next register all of your subtypes. Every subtype must be explicitly registered. This protects your application from injection attacks. If you don't supply an explicit type label, the type's simple name will be used.

   {@code * shapeAdapterFactory.registerSubtype(Rectangle.class, "Rectangle"); * shapeAdapterFactory.registerSubtype(Circle.class, "Circle"); * shapeAdapterFactory.registerSubtype(Diamond.class, "Diamond"); * }

Finally, register the type adapter factory in your application's GSON builder:

{@code * Gson gson = new GsonBuilder() * .registerTypeAdapterFactory(shapeAdapterFactory) * .create(); * }

Like {@code GsonBuilder}, this API supports chaining:

   {@code * RuntimeTypeAdapterFactoryshapeAdapterFactory = RuntimeTypeAdapterFactory.of(Shape.class)
 *       .registerSubtype(Rectangle.class)
 *       .registerSubtype(Circle.class)
 *       .registerSubtype(Diamond.class);
 * }

Serialization and deserialization In order to serialize and deserialize a polymorphic object, you must specify the base type explicitly.

{@code * Diamond diamond = new Diamond(); * String json = gson.toJson(diamond, Shape.class); * }

And then:

{@code * Shape shape = gson.fromJson(json, Shape.class); * }

Functions

create

TypeAdapter<R> create<R>(Gson gson, TypeToken<R> type)

static RuntimeTypeAdapterFactory<T> of<T>(Class<T> baseType)

Creates a new runtime type adapter for {@code baseType} using {@code "type"} as the type field name.

static RuntimeTypeAdapterFactory<T> of<T>(Class<T> baseType, String typeFieldName)

Creates a new runtime type adapter using for {@code baseType} using {@code * typeFieldName} as the type field name.

static RuntimeTypeAdapterFactory<T> of<T>(Class<T> baseType, String typeFieldName, boolean maintainType)

Creates a new runtime type adapter using for {@code baseType} using {@code * typeFieldName} as the type field name.

registerSubtype

RuntimeTypeAdapterFactory<T> registerSubtype(Class<? extends T> type)

Registers {@code type} identified by its simple name.

RuntimeTypeAdapterFactory<T> registerSubtype(Class<? extends T> type, String label)

Registers {@code type} identified by {@code label}.