Guide to MapStruct @IterableMapping

1. Overview

MapStruct is one of the most powerful tools for generating Java bean mappers. Sometimes we need more granular control over lists and other iterables, especially when each element requires specific formatting or custom mapping logic. This is where @IterableMapping comes into play.

In this tutorial, we’ll highlight how to handle collection mappings in MapStruct using the @IterableMapping annotation.

2. What is @IterableMapping?

Typically, @IterableMapping, as the name implies, is used to configure how Java collections are converted from one type to another.

MapStruct may reach its limits when our mapping requirements go beyond simple type conversion. The most common use cases for this annotation are applying custom formatting, ensuring null safety, and resolving mapping ambiguities.

3. Practical Examples

Applying @IterableMapping is straightforward and follows the same declarative style as other MapStruct annotations. To use it, we place the annotation directly on the method responsible for converting one iterable type into another.

3.1. Customizing Element Mapping

Here, we assume that we have a list of string dates that we want to map to a list of LocalDate objects. To do that, we can use the dateFormat attribute to ensure the conversion happens correctly:

public interface DateMapper {
    @IterableMapping(dateFormat = "yyyy-MM-dd")
    List<LocalDate> stringsToLocalDates(List<String> dates);
}

Now, let’s create a test case to make sure that each element is mapped as expected:

@Test
void givenStringDatewhenDateFormatIsUsed_thenMapToLocalDate() {
    DateMapper mapper = Mappers.getMapper(DateMapper.class);
    assertThat(mapper.stringsToLocalDates(List.of("2025-05-10", "2024-12-25")))
      .containsExactly(LocalDate.of(2025, 5, 10), LocalDate.of(2024, 12, 25));
}

The dateFormat attribute is the core of the @IterableMapping logic in this example. It eliminates the need to write a manual loop to handle date formatting. MapStruct generates that boilerplate for us.

Now, let’s attempt to use a date string that doesn’t respect the provided date format and see what happens:

@Test
void givenStringDatewhenDateFormatIsNotRespected_thenThrowException() {
    DateMapper mapper = Mappers.getMapper(DateMapper.class);
    
    assertThatThrownBy(() -> mapper.stringsToLocalDates(List.of("2025/05/10")))
      .isInstanceOf(DateTimeParseException.class);
}

As we can see, the test case fails with DateTimeParseException.

3.2. Selecting a Specific Qualified Method

In many real-world scenarios, a basic type conversion isn’t always enough. For instance, we may need to exclude a specific attribute from the mapping because it contains sensitive data or it’s too complex to convert.

In this case, we need a clear way to tell MapStruct which custom method should be applied to each element of the collection. To address this, @IterableMapping provides the qualifiedByName attribute to denote the exact mapping method.

For example, let’s consider a User class with a sensitive data password:

public class User {

    private String login;
    private String password;

    //standard full arguments constructor and getters
}

The idea here is to exclude the user password from the mapping logic. So, let’s create a user DTO that holds only the login property:

public class UserDto {

    private String login;

    //standard full arguments constructor and getters
}

Now, we need to leverage a specialized mapping method to bypass the password attribute entirely:

public interface UserMapper {
    
    @IterableMapping(qualifiedByName = "mapLoginOnly") 
    List<UserDto> toDto(List<User> users);
    
    @Named("mapLoginOnly") 
    default UserDto mapLoginOnly(User user) { 
        return user != null ? new UserDto(user.getLogin()) : null; 
    }
}

By using qualifiedByName, we instruct MapStruct to use the mapLoginOnly() method to map each element of the provided list:

@Test
void givenUserWithPasswordwhenExcludePassword_thenConvertLoginOnly() {
    UserMapper mapper = Mappers.getMapper(UserMapper.class);
    List<UserDto> result = mapper.toDto(List.of(new User("admin", "@admin@2026")));
		
    assertThat(result.get(0)).usingRecursiveComparison().isEqualTo(new UserDto("admin"));
}

The test case proves that qualifiedByName is actually routing each user through the mapLoginOnly() method.

4. Handling Null Collections

By default, MapStruct returns null if the given collection is null. However, we can override this behavior by using the nullValueMappingStrategy attribute.

Typically, we can use NullValueMappingStrategy.RETURN_DEFAULT to return an empty collection instead of null. This is particularly useful for preventing NullPointerException in downstream logic.

For instance, let’s update the @IterableMapping annotation used on the toDto() method:

@IterableMapping(qualifiedByName = "mapLoginOnly",
  nullValueMappingStrategy = NullValueMappingStrategy.RETURN_DEFAULT)

Now, let’s attempt to pass a null value:

@Test
void whenListIsNull_thenReturnEmptyCollection() {
    UserMapper mapper = Mappers.getMapper(UserMapper.class);
		
    assertThat(mapper.toDto(null)).isEmpty();
}

As expected, the new test case runs successfully, confirming that our method returns an empty collection instead of null.

5. Conclusion

In this article, we explained how @IterableMapping provides granular control over collection mapping. We illustrated how this annotation offers the necessary hooks for custom formatting, method selection, and null safety.

The full source is available over on GitHub.