Jackson – Bidirectional Relationships

1. Overview

In this tutorial, we’ll examine the best ways to deal with bidirectional relationships in Jackson.

First, we’ll discuss the Jackson JSON infinite recursion problem. Then we’ll see how to serialize entities with bidirectional relationships. Finally, we’ll deserialize them.

2. Infinite Recursion

Let’s take a look at the Jackson infinite recursion problem. In the following example, we have two entities, “User” and “Item,” with a simple one-to-many relationship:

The “User” entity:

public class User {
    public int id;
    public String name;
    public List<Item> userItems;
}

The “Item” entity:

public class Item {
    public int id;
    public String itemName;
    public User owner;
}

When we try to serialize an instance of “Item,” Jackson will throw a JsonMappingException exception:

@Test(expected = JsonMappingException.class)
public void givenBidirectionRelation_whenSerializing_thenException()
  throws JsonProcessingException {
 
    User user = new User(1, "John");
    Item item = new Item(2, "book", user);
    user.addItem(item);

    new ObjectMapper().writeValueAsString(item);
}

The full exception is:

com.fasterxml.jackson.databind.JsonMappingException:
Infinite recursion (StackOverflowError) 
(through reference chain: 
org.baeldung.jackson.bidirection.Item["owner"]
->org.baeldung.jackson.bidirection.User["userItems"]
->java.util.ArrayList[0]
->org.baeldung.jackson.bidirection.Item["owner"]
->…..

We’ll see over the course of the next few sections how to solve this problem.

3. Use @JsonManagedReference, @JsonBackReference

First, let’s annotate the relationship with @JsonManagedReference, and @JsonBackReference to allow Jackson to better handle the relation:

Here’s the “User” entity:

public class User {
    public int id;
    public String name;

    @JsonManagedReference
    public List<Item> userItems;
}

And the “Item“:

public class Item {
    public int id;
    public String itemName;

    @JsonBackReference
    public User owner;
}

Now let’s test out the new entities:

@Test
public void givenBidirectionRelation_whenUsingJacksonReferenceAnnotationWithSerialization_thenCorrect() throws JsonProcessingException {
    final User user = new User(1, "John");
    final Item item = new Item(2, "book", user);
    user.addItem(item);

    final String itemJson = new ObjectMapper().writeValueAsString(item);
    final String userJson = new ObjectMapper().writeValueAsString(user);

    assertThat(itemJson, containsString("book"));
    assertThat(itemJson, not(containsString("John")));

    assertThat(userJson, containsString("John"));
    assertThat(userJson, containsString("userItems"));
    assertThat(userJson, containsString("book"));
}

Here’s the output of serializing the Item object:

{
 "id":2,
 "itemName":"book"
}

And here’s the output of serializing the User object:

{
 "id":1,
 "name":"John",
 "userItems":[{
   "id":2,
   "itemName":"book"}]
}

Note that:

• @JsonManagedReference is the forward part of reference, the one that gets serialized normally.
• @JsonBackReference is the back part of reference; it’ll be omitted from serialization.
• The serialized Item object doesn’t contain a reference to the User object.

Also note that we can’t switch around the annotations. The following will work for the serialization:

@JsonBackReference
public List<Item> userItems;

@JsonManagedReference
public User owner;

But when we attempt to deserialize the object, it’ll throw an exception, as @JsonBackReference can’t be used on a collection.

If we want to have the serialized Item object contain a reference to the User, we need to use @JsonIdentityInfo. We’ll look at this in the next section.

4. Use @JsonIdentityInfo

Now, let’s learn how we can help with the serialization of entities with bidirectional relationships using @JsonIdentityInfo.

We’ll add the class-level annotation to our “User” entity:

@JsonIdentityInfo(
  generator = ObjectIdGenerators.PropertyGenerator.class, 
  property = "id")
public class User { ... }

And to the “Item” entity:

@JsonIdentityInfo(
  generator = ObjectIdGenerators.PropertyGenerator.class, 
  property = "id")
public class Item { ... }

Time for the test:

@Test
public void givenBidirectionRelation_whenUsingJsonIdentityInfo_thenCorrect()
  throws JsonProcessingException {
 
    User user = new User(1, "John");
    Item item = new Item(2, "book", user);
    user.addItem(item);

    String result = new ObjectMapper().writeValueAsString(item);

    assertThat(result, containsString("book"));
    assertThat(result, containsString("John"));
    assertThat(result, containsString("userItems"));
}

Here’s the output of serialization:

{
 "id":2,
 "itemName":"book",
 "owner":
    {
        "id":1,
        "name":"John",
        "userItems":[2]
    }
}

5. Use @JsonIgnore

Alternatively, we can use the @JsonIgnore annotation to simply ignore one of the sides of the relationship, thus breaking the chain.

In the following example, we’ll prevent the infinite recursion by ignoring the “User” property “userItems” from serialization:

Here’s the “User” entity:

public class User {
    public int id;
    public String name;

    @JsonIgnore
    public List<Item> userItems;
}

And here’s our test:

@Test
public void givenBidirectionRelation_whenUsingJsonIgnore_thenCorrect()
  throws JsonProcessingException {
 
    User user = new User(1, "John");
    Item item = new Item(2, "book", user);
    user.addItem(item);

    String result = new ObjectMapper().writeValueAsString(item);

    assertThat(result, containsString("book"));
    assertThat(result, containsString("John"));
    assertThat(result, not(containsString("userItems")));
}

Finally, here’s the output of serialization:

{
 "id":2,
 "itemName":"book",
 "owner":
    {
        "id":1,
        "name":"John"
    }
}

6. Use @JsonView

We can also use the newer @JsonView annotation to exclude one side of the relationship.

In the following example, we’ll use two JSON Views, Public and Internal, where Internal extends Public:

public class Views {
    public static class Public {}

    public static class Internal extends Public {}
}

We’ll include all User and Item fields in the Public View except the User field userItems, which will be included in the Internal View:

Here’s our “User” entity:

public class User {
    @JsonView(Views.Public.class)
    public int id;

    @JsonView(Views.Public.class)
    public String name;

    @JsonView(Views.Internal.class)
    public List<Item> userItems;
}

And here’s our “Item” entity:

public class Item {
    @JsonView(Views.Public.class)
    public int id;

    @JsonView(Views.Public.class)
    public String itemName;

    @JsonView(Views.Public.class)
    public User owner;
}

When we serialize using the Public view, it works correctly because we excluded userItems from being serialized:

@Test
public void givenBidirectionRelation_whenUsingPublicJsonView_thenCorrect() 
  throws JsonProcessingException {
 
    User user = new User(1, "John");
    Item item = new Item(2, "book", user);
    user.addItem(item);

    String result = new ObjectMapper().writerWithView(Views.Public.class)
      .writeValueAsString(item);

    assertThat(result, containsString("book"));
    assertThat(result, containsString("John"));
    assertThat(result, not(containsString("userItems")));
}

But if we serialize using an Internal view, JsonMappingException is thrown because all the fields are included:

@Test(expected = JsonMappingException.class)
public void givenBidirectionRelation_whenUsingInternalJsonView_thenException()
  throws JsonProcessingException {
 
    User user = new User(1, "John");
    Item item = new Item(2, "book", user);
    user.addItem(item);

    new ObjectMapper()
      .writerWithView(Views.Internal.class)
      .writeValueAsString(item);
}

7. Use a Custom Serializer

Next, we’ll see how to serialize entities with bidirectional relationships using a custom serializer.

In the following example, we’ll use a custom serializer to serialize the “User” property “userItems“.

Here’s the “User” entity:

public class User {
    public int id;
    public String name;

    @JsonSerialize(using = CustomListSerializer.class)
    public List<Item> userItems;
}

And here’s the “CustomListSerializer“:

public class CustomListSerializer extends StdSerializer<List<Item>>{

   public CustomListSerializer() {
        this(null);
    }

    public CustomListSerializer(Class<List> t) {
        super(t);
    }

    @Override
    public void serialize(
      List<Item> items, 
      JsonGenerator generator, 
      SerializerProvider provider) 
      throws IOException, JsonProcessingException {
        
        List<Integer> ids = new ArrayList<>();
        for (Item item : items) {
            ids.add(item.id);
        }
        generator.writeObject(ids);
    }
}

Now, let’s test out the serializer. As we can see, the right kind of output is being produced:

@Test
public void givenBidirectionRelation_whenUsingCustomSerializer_thenCorrect()
  throws JsonProcessingException {
    User user = new User(1, "John");
    Item item = new Item(2, "book", user);
    user.addItem(item);

    String result = new ObjectMapper().writeValueAsString(item);

    assertThat(result, containsString("book"));
    assertThat(result, containsString("John"));
    assertThat(result, containsString("userItems"));
}

Here’s the final output of the serialization with the custom serializer:

{
 "id":2,
 "itemName":"book",
 "owner":
    {
        "id":1,
        "name":"John",
        "userItems":[2]
    }
}

8. Deserialize With @JsonIdentityInfo

Now, let’s see how to deserialize entities with bidirectional relationships using @JsonIdentityInfo.

Here’s the “User” entity:

@JsonIdentityInfo(
  generator = ObjectIdGenerators.PropertyGenerator.class, 
  property = "id")
public class User { ... }

And the “Item” entity:

@JsonIdentityInfo(
  generator = ObjectIdGenerators.PropertyGenerator.class, 
  property = "id")
public class Item { ... }

We’ll write a quick test, starting with some manual JSON data we want to parse, and finishing with the correctly constructed entity:

@Test
public void givenBidirectionRelation_whenDeserializingWithIdentity_thenCorrect() 
  throws JsonProcessingException, IOException {
    String json = 
      "{\"id\":2,\"itemName\":\"book\",\"owner\":{\"id\":1,\"name\":\"John\",\"userItems\":[2]}}";

    ItemWithIdentity item
      = new ObjectMapper().readerFor(ItemWithIdentity.class).readValue(json);
    
    assertEquals(2, item.id);
    assertEquals("book", item.itemName);
    assertEquals("John", item.owner.name);
}

9. Use Custom Deserializer

Finally, let’s deserialize the entities with a bidirectional relationship using a custom deserializer.

In the following example, we’ll use a custom deserializer to parse the “User” property “userItems“.

Here’s the “User” entity:

public class User {
    public int id;
    public String name;

    @JsonDeserialize(using = CustomListDeserializer.class)
    public List<Item> userItems;
}

And here’s our “CustomListDeserializer“:

public class CustomListDeserializer extends StdDeserializer<List<Item>>{

    public CustomListDeserializer() {
        this(null);
    }

    public CustomListDeserializer(Class<?> vc) {
        super(vc);
    }

    @Override
    public List<Item> deserialize(
      JsonParser jsonparser, 
      DeserializationContext context) 
      throws IOException, JsonProcessingException {
        
        return new ArrayList<>();
    }
}

Finally, here’s the simple test:

@Test
public void givenBidirectionRelation_whenUsingCustomDeserializer_thenCorrect()
  throws JsonProcessingException, IOException {
    String json = 
      "{\"id\":2,\"itemName\":\"book\",\"owner\":{\"id\":1,\"name\":\"John\",\"userItems\":[2]}}";

    Item item = new ObjectMapper().readerFor(Item.class).readValue(json);
 
    assertEquals(2, item.id);
    assertEquals("book", item.itemName);
    assertEquals("John", item.owner.name);
}

10. Resolving Jackson Exception

When we use multiple bidirectional relationships in the same entity, we might encounter an exception during serialization:

com.fasterxml.jackson.databind.JsonMappingException: Multiple back-reference properties with name 'defaultReference'

This happens because Jackson assigns the default reference name ‘defaultReference‘ to every @JsonBackReference unless we explicitly provide a value. If an entity has more than one back-reference without specifying a unique name, Jackson doesn’t know how to distinguish them.

Suppose we have a User with two lists of items: wishlist and soldItems. Both reference the User as the owner:

public class User {
    public int id;
    public String name;

    @JsonManagedReference
    public List wishlist = new ArrayList<>();

    @JsonManagedReference
    public List soldItems = new ArrayList<>();
}

public class Item {
    public int id;
    public String itemName;

    @JsonBackReference
    public User owner;
}

This will cause Jackson to throw a JsonMappingException during serialization because it cannot distinguish between multiple back-references that share the same default name.

To resolve this, we need to give each pair of references a unique name via the value attribute:

public class User {
    public int id;
    public String name;

    @JsonManagedReference(value="wishlistRef")
    public List wishlist = new ArrayList<>();

    @JsonManagedReference(value="soldItemsRef")
    public List soldItems = new ArrayList<>();
}

public class Item {
    public int id;
    public String itemName;

    @JsonBackReference(value="wishlistRef")
    public User wishlistOwner;

    @JsonBackReference(value="soldItemsRef")
    public User soldOwner;
}

Now, Jackson knows exactly which back-reference corresponds to which managed reference, and serialization works correctly.

We can write a test example to demonstrate how using named @JsonManagedReference and @JsonBackReference annotations allows Jackson to correctly serialize objects with multiple back-references without throwing an exception:

@Test
public void givenMultipleBackReferencesOnWishlist_whenNamedReference_thenNoException() throws JsonProcessingException {
    User user = new User();
    user.id = 1;
    user.name = "Alice";

    Item item1 = new Item();
    item1.id = 101;
    item1.itemName = "Book";
    item1.wishlistOwner = user;

    Item item2 = new Item();
    item2.id = 102;
    item2.itemName = "Pen";
    item2.wishlistOwner = user;

    user.wishlist = List.of(item1, item2);

    Item item3 = new Item();
    item3.id = 201;
    item3.itemName = "Laptop";
    item3.soldOwner = user;

    Item item4 = new Item();
    item4.id = 202;
    item4.itemName = "Phone";
    item4.soldOwner = user;

    user.soldItems = List.of(item3, item4);

    String json = new ObjectMapper().writeValueAsString(user);
    assertThat(json, containsString("Alice"));
    assertThat(json, containsString("Book"));
    assertThat(json, containsString("Pen"));
}

11. Conclusion

In this article, we illustrated how to serialize/deserialize entities with bidirectional relationships using Jackson.