Deduction-Based Polymorphism in Jackson 2.12

1. Overview

In this tutorial, we’ll explore how we can use the deduction-based polymorphism feature from the Jackson library.

2. Name-based Polymorphism

Let’s imagine we have a structure of classes like the one described in the following image.

First, the NamedCharacter and ImperialSpy classes implement the Character interface. Secondly, the King and Knight classes are implementing the NamedCharacter class. Lastly, we have a ControlledCharacter class, which contains a reference to a character that the player controls.

We would like to parse JSON objects into Java objects, without having to modify the structure of the received JSON.

So let’s take a look at the definition of the classes. Notice that for the base interface, we’ll have to use the Jackson annotations to declare which deduction we will want to use. Also, we’ll have to add the @JsonSubTypes annotations to declare which classes we want to deduct.

@JsonTypeInfo(use = Id.NAME)
@JsonSubTypes({ @Type(ImperialSpy.class), @Type(King.class), @Type(Knight.class) })
public interface Character {
}

Furthermore, we can also have an intermediary class between the interface Character and King and Knight classes. Hence, Jackson, we’ll also know how to deduct the polymorphism in this case as well:

public class NamedCharacter implements Character {
    private String name;

    // standard setters and getters
}

Subsequently, we’ll implement the subclasses of the Character interface. We already declared these subclasses as subtypes in the previous code example. Consequently, the implementation does not have any dependencies on the Jackson library:

public class ImperialSpy implements Character {
}

public class King extends NamedCharacter {
    private String land;

    // standard setters and getters
}

public class Knight extends NamedCharacter {
    private String weapon;

    // standard setters and getters
}

An example of a JSON that we would like to map is the following:

{
    "name": "Old King Allant",
    "land": "Boletaria",
}

Firstly, if we try to read the above JSON structure, Jackson would throw a runtime exception with the message Could not resolve subtype of [simple type, class com.baeldung.jackson.deductionbasedpolymorphism.Character]: missing type id property ‘@type’:

@Test
void givenAKingWithoutType_whenMapping_thenExpectAnError() {
    String kingJson = formatJson("{'name': 'Old King Allant', 'land':'Boletaria'}");
    assertThrows(InvalidTypeIdException.class, () -> objectMapper.readValue(kingJson, Character.class));
}

In addition, the formatJson utility method helps us keep the code in the test simple, by converting the quote characters to double quotes, as JSON requires:

public static String formatJson(String input) {
    return input.replaceAll("'", "\"");
}

Consequently, to be able to polymorphically deduct the type of our character, we’ll have to modify the JSON structure and explicitly add the type of the object. Therefore, we would have to couple the polymorphic behavior with our JSON structure:

{
    "@type": "King"
    "name": "Old King Allant",
    "land": "Boletaria",
}

@Test
void givenAKing_whenMapping_thenExpectAKingType() throws Exception {
    String kingJson = formatJson("{'name': 'Old King Allant', 'land':'Boletaria', '@type':'King'}");

    Character character = objectMapper.readValue(kingJson, Character.class);
    assertTrue(character instanceof King);
    assertSame(character.getClass(), King.class);
    King king = (King) character;
    assertEquals("Boletaria", king.getLand());
}

3. Deduction-based Polymorphism

To activate the deduction-based polymorphism, the only change we have to do is to use @JsonTypeInfo(use = Id.DEDUCTION):

@JsonTypeInfo(use = Id.DEDUCTION)
@JsonSubTypes({ @Type(ImperialSpy.class), @Type(King.class), @Type(Knight.class) })
public interface Character {
}

4. Simple Inference

Let’s explore how we can read JSON in a polymorphic way with simple inference. The object that we want to read is the following:

{
    "name": "Ostrava, of Boletaria",
    "weapon": "Rune Sword",
}

Firstly, we’ll read the value in a Character object. Then, we’ll test that Jackson deducted correctly the type of the JSON:

@Test
void givenAKnight_whenMapping_thenExpectAKnightType() throws Exception {
    String knightJson = formatJson("{'name':'Ostrava, of Boletaria', 'weapon':'Rune Sword'}");

    Character character = objectMapper.readValue(knightJson, Character.class);

    assertTrue(character instanceof Knight);
    assertSame(character.getClass(), Knight.class);
    Knight king = (Knight) character;
    assertEquals("Ostrava, of Boletaria", king.getName());
    assertEquals("Rune Sword", king.getWeapon());
}

Moreover, if the JSON is an empty object, Jackson will interpret it as an ImperialSpy, which is a class with no attributes:

@Test
void givenAnEmptyObject_whenMapping_thenExpectAnImperialSpy() throws Exception {
    String imperialSpyJson = "{}";

    Character character = objectMapper.readValue(imperialSpyJson, Character.class);

    assertTrue(character instanceof ImperialSpy);
}

Also, a null JSON object will be deducted as a null object by Jackson as well:

@Test
void givenANullObject_whenMapping_thenExpectANullObject() throws Exception {
    Character character = objectMapper.readValue("null", Character.class);

    assertNull(character);
}

5. Case Insensitive Inference

Jackson can also deduct the polymorphism, even if the case of attributes does not match. First, we’ll instantiate an object mapper with the ACCEPT_CASE_INSENSITIVE_PROPERTIES enabled:

ObjectMapper objectMapper = JsonMapper.builder().configure(MapperFeature.ACCEPT_CASE_INSENSITIVE_PROPERTIES, true).build();

Then, using the instantiated objectMapper, we can test that the polymorphism is deducted correctly:

{
    "NaMe": "Ostrava, of Boletaria",
    "WeaPON": "Rune Sword",
}

@Test
void givenACaseInsensitiveKnight_whenMapping_thenExpectKnight() throws Exception {
    String knightJson = formatJson("{'NaMe':'Ostrava, of Boletaria', 'WeaPON':'Rune Sword'}");

    Character character = objectMapper.readValue(knightJson, Character.class);

    assertTrue(character instanceof Knight);
    assertSame(character.getClass(), Knight.class);
    Knight knight = (Knight) character;
    assertEquals("Ostrava, of Boletaria", knight.getName());
    assertEquals("Rune Sword", knight.getWeapon());
}

6. Contained Inference

We can also deduct the polymorphism of objects that are contained in other objects. We will use the ControlledCharacter class definition to demonstrate the mapping of the following JSON:

{
    "character": {
        "name": "Ostrava, of Boletaria",
        "weapon": "Rune Sword"
    }
}

@Test
void givenAKnightControlledCharacter_whenMapping_thenExpectAControlledCharacterWithKnight() throws Exception {
    String controlledCharacterJson = formatJson("{'character': {'name': 'Ostrava, of Boletaria', 'weapon': 'Rune Sword'}}");

    ControlledCharacter controlledCharacter = objectMapper.readValue(controlledCharacterJson, ControlledCharacter.class);
    Character character = controlledCharacter.getCharacter();

    assertTrue(character instanceof Knight);
    assertSame(character.getClass(), Knight.class);
    Knight knight = (Knight) character;
    assertEquals("Ostrava, of Boletaria", knight.getName());
    assertEquals("Rune Sword", knight.getWeapon());
}

7. Conclusion

In this tutorial, we have explored how we can use deduction-based polymorphism using the Jackson library.