Package com.squareup.moshi.adapters

Class PolymorphicJsonAdapterFactory<T>

  • All Implemented Interfaces:
    com.squareup.moshi.JsonAdapter.Factory
    public final class PolymorphicJsonAdapterFactory<T>
extends java.lang.Object
implements com.squareup.moshi.JsonAdapter.Factory
    A JsonAdapter factory for objects that include type information in the JSON. When decoding JSON Moshi uses this type information to determine which class to decode to. When encoding Moshi uses the object’s class to determine what type information to include.

    Suppose we have an interface, its implementations, and a class that uses them: 

    
 interface HandOfCards {
 }

 class BlackjackHand implements HandOfCards {
   Card hidden_card;
   List<Card> visible_cards;
 }

 class HoldemHand implements HandOfCards {
   Set<Card> hidden_cards;
 }

 class Player {
   String name;
   HandOfCards hand;
 }

    We want to decode the following JSON into the player model above: 

    
 {
   "name": "Jesse",
   "hand": {
     "hand_type": "blackjack",
     "hidden_card": "9D",
     "visible_cards": ["8H", "4C"]
   }
 }

    Left unconfigured, Moshi would incorrectly attempt to decode the hand object to the abstract HandOfCards interface. We configure it to use the appropriate subtype instead: 

    
 Moshi moshi = new Moshi.Builder()
     .add(PolymorphicJsonAdapterFactory.of(HandOfCards.class, "hand_type")
         .withSubtype(BlackjackHand.class, "blackjack")
         .withSubtype(HoldemHand.class, "holdem"))
     .build();

    This class imposes strict requirements on its use:

    • Base types may be classes or interfaces.
    • Subtypes must encode as JSON objects.
    • Type information must be in the encoded object. Each message must have a type label like hand_type whose value is a string like blackjack that identifies which type to use.
    • Each type identifier must be unique.

    For best performance type information should be the first field in the object. Otherwise Moshi must reprocess the JSON stream once it knows the object's type.

    If an unknown subtype is encountered when decoding:

    If an unknown type is encountered when encoding:

    If the same subtype has multiple labels the first one is used when encoding.

    • Method Detail

      • of

        @CheckReturnValue
public static <T> PolymorphicJsonAdapterFactory<T> of​(java.lang.Class<T> baseType,
                                                      java.lang.String labelKey)
        Parameters:
        baseType - The base type for which this factory will create adapters. Cannot be Object.
        labelKey - The key in the JSON object whose value determines the type to which to map the JSON object.

      • withSubtype

        public PolymorphicJsonAdapterFactory<T> withSubtype​(java.lang.Class<? extends T> subtype,
                                                    java.lang.String label)
        Returns a new factory that decodes instances of subtype.

      • withFallbackJsonAdapter

        public PolymorphicJsonAdapterFactory<T> withFallbackJsonAdapter​(@Nullable
                                                                com.squareup.moshi.JsonAdapter<java.lang.Object> fallbackJsonAdapter)
        Returns a new factory that with default to fallbackJsonAdapter.fromJson(reader) upon decoding of unrecognized labels.

        The JsonReader instance will not be automatically consumed, so sure to consume it within your implementation of JsonAdapter.fromJson(JsonReader)

      • withDefaultValue

        public PolymorphicJsonAdapterFactory<T> withDefaultValue​(@Nullable
                                                         T defaultValue)
        Returns a new factory that will default to defaultValue upon decoding of unrecognized labels. The default value should be immutable.

      • create

        public com.squareup.moshi.JsonAdapter<?> create​(java.lang.reflect.Type type,
                                                java.util.Set<? extends java.lang.annotation.Annotation> annotations,
                                                com.squareup.moshi.Moshi moshi)
        Specified by:
        create in interface com.squareup.moshi.JsonAdapter.Factory