Map Iterable to Object Containing Iterable With Mapstruct

1. Introduction

In this tutorial, we’ll explore an interesting Java problem: mapping an Iterable to an object containing an Iterable using MapStruct.

MapStruct is a Java library that simplifies the process of mapping between different object models. However, it has limitations. This tutorial assumes that we already have a basic understanding of MapStruct. If not, we recommend starting with a quick guide to familiarize ourselves with its basic usage.

2. Understand the Use Case

Let’s begin with a simple example to explain the scenario. Consider a list of Employee objects and a Department object containing a list of employees. We’ll start by creating those classes:

public class Employee {

    private String name;
    private String phoneNumber;

    // getters and setters
}

public class Department {

    private List<Employee> employees;

    // getters and setters
}

Now, let’s assume we want to map the list of Employee objects to a Department. We’ll create an interface, mark it as a mapper, and create a method annotated with the @Mapping annotation:

@Mapper
public interface DepartmentMapper {

    @Mapping(target = "employees", source = "employees")
    Department map(List<Employee> employees);
}

In the code above, we intuitively tried to define the source as our input list of employees and the target as the Employees of our Department class. Although this may seem like a straightforward approach, we’ll encounter an error that prevents our code from compiling. To resolve this issue, we’ll need to adjust our approach to ensure that the source type aligns with the target type.

3. Map Iterable to Non-Iterable Type

Let’s understand the root cause of this issue by looking at the error thrown by MapStruct:

java: Can't generate mapping method from iterable type from java stdlib to non-iterable type.

The error above indicates that we’re trying to map an iterable type (such as List, Set, or any Collection from the standard Java library) and a non-iterable type (a single object or primitive type). Such mapping is not natively supported and requires additional context or specific instructions.

There are a few practical reasons for this that the JVM and the MapStruct library are simply unable to solve independently:

• How to match elements between source and target
• Whether to remove or add unmatched elements
• How to handle multiple matches

Additionally, we also need to consider how to maintain the correct sorting of elements.

4. Solution

When mapping an iterable to a non-iterable type using MapStruct, there isn’t a straightforward, one-size-fits-all solution. However, there are practical workarounds available that can help us achieve the desired outcome.

4.1. Default Interface Method

The first approach involves creating a default interface method within the mapper. This method will manually handle the conversion by taking our iterable and setting it as the field value within the target object. By doing this, we ensure that the mapping is handled as expected.

Let’s look at this approach in practice:

default Department map(List<Employee> employees) {
    Department department = new Department();
    department.setEmployees(employees);
    return department;
}

4.2. Multiple Sources

Another method involves changing the mapping method by adding additional parameters. When we introduce another argument, MapStruct gains better context for what we’re trying to accomplish. Having multiple parameters, in other words, means we have multiple sources, so it will be easier to identify what needs to be mapped.

First, let’s introduce a new attribute to our Department class. That parameter will be of type Employee named manager:

public class Department {

    private List<Employee> employees;
    private Employee manager;

    // omitted getters and setters

}

Next, let’s create a mapping method including this parameter as a source:

@Mapping(target = "employees", source = "employees")
@Mapping(target = "manager", source = "departmentManager")
Department mapWithManager(List<Employee> employees, Employee departmentManager);

Since we’re no longer trying to map an iterable to a non-iterable type, the mapping works as expected. The MapStruct library now has sufficient context to generate a mapper implementation, which is why no errors are thrown during the code compilation step.

Note that even though this approach is clean and functional, it’s case-specific. We’re not always able to add new parameters in favor of mapping.

5. Conclusion

In this article, we discussed the challenges and solutions involved in using MapStruct to map an iterable to an object containing an iterable type. Although MapStruct is a powerful object mapping tool, it has limitations that require alternative approaches.

We explored several methods to handle these scenarios, including adding default interface methods that give us full control over the mapping process. Furthermore, we noticed that while multiple source mapping doesn’t encounter the issues mentioned in this article, it isn’t a helpful approach for every use case.

As always, full code examples are available over on GitHub.