Set the Null Value for a Target Property in MapStruct

1. Introduction

In this article, we’ll explore ways to consistently set a property to null when mapping objects with MapStruct.

2. Creating the Models

To illustrate mapping, we’ll create two model classes: one that represents a persisted entity, article, and another that represents an article update object.

First, the persisted Article class:

public class Article {
    private String id;
    private String reviewedBy;

    // no-arg and all-arg constructors
    // getters and setters
}

And the ArticleDTO class, which mutates an entity:

public class ArticleDTO {
    private String title;

    // no-arg and all-arg constructors
    // getters and setters
}

The idea is that each time we update an article using the ArticleDTO, we also update the Article’s reviewedBy field to null.

3. Mapping an ArticleDTO to Article

We’ll use MapStruct to map the DTO to a new entity that we want to save. The first step is to create the ArticleMapper interface annotated with @Mapper:

@Mapper
public interface ArticleMapper {
}

With that, we can add abstract mapper methods to it, and MapStruct will automatically generate the implementation for us.

3.1. Using the expression Property

MapStruct allows us to define Java expressions as strings in our mappers, so it will copy that same expression into the generated implementation code. Hence, one way to set reviewedBy to null is to define an expression that evaluates to null:

@Mapping(target = "title", source = "dto.title")
@Mapping(target = "id", source = "persisted.id")
@Mapping(target = "reviewedBy", expression = "java(null)")
Article toArticleUsingExpression(ArticleDTO dto, Article persisted);

We can also do that by creating a custom default method that returns null:

@Mapping(target = "title", source = "dto.title")
@Mapping(target = "id", source = "persisted.id")
@Mapping(target = "reviewedBy", expression = "java(getReviewedBy())")
Article toArticleUsingExpressionMethod(ArticleDTO dto, Article persisted);

default String getReviewedBy() {
    return null;
}

Both achieve the same functionality, as noted with the test:

@Test
void givenArticleDTO_whenToArticleUsingExpression_thenReturnsArticleWithNullStatus() {
    Article oldArticle1 = new Article("Title 1", "John Doe");
    Article oldArticle2 = new Article("Title 2", "John Doe");

    Article result1 = articleMapper.toArticleUsingExpression(new ArticleDTO("Updated article title"), oldArticle1);
    Article result2 = articleMapper.toArticleUsingExpressionMethod(new ArticleDTO("Updated article title"), oldArticle2);

    assertThat(result1.getReviewedBy()).isNull();
    assertThat(result2.getReviewedBy()).isNull();
    assertThat(result1.getTitle()).isEqualTo("Updated article title");
    assertThat(result2.getTitle()).isEqualTo("Updated article title");
}

The expression using the getReviewedBy() method could be more advantageous if we need to apply any additional logic before returning the null value, favoring reusability.

3.2. Using the qualifiedBy Property

Similarly to expression, we can favor reusability and define a default named method that returns null. Then, we can use it in the qualifiedBy property in the @Mapping annotation:

@Mapping(target = "title", source = "dto.title")
@Mapping(target = "id", source = "persisted.id")
@Mapping(target = "reviewedBy", qualifiedByName = "toNull")
Article toArticleUsingQualifiedBy(ArticleDTO dto, Article persisted);

@Named("toNull")
default String mapToNull(String property) {
    return null;
}

With qualifiedByName, we can name a method using @Named and reuse it in the annotated mapper method. Notably, we named our method toNull and passed it to the @Mapping annotation. That also gives us the correct result:

@Test
void givenArticleDTO_whenToArticleUsingQualifiedBy_thenReturnsArticleWithNullStatus() {
    Article oldArticle1 = new Article("Title 1", "John Doe");

    Article result1 = articleMapper.toArticleUsingQualifiedBy(new ArticleDTO("Updated article 1 title"), oldArticle1);

    assertThat(result1.getReviewedBy()).isNull();
    assertThat(result1.getTitle()).isEqualTo("Updated article 1 title");
}

3.3. Using the ignore Property

We can also use the ignore property of the Mapper annotation to ignore its serialization. Thus, since the target object is a new one created by MapStruct, and all its fields are initialized as null, then ignoring a property will leave its fields with the null value.

To do that, we can modify our mapper to:

@Mapping(target = "title", source = "dto.title")
@Mapping(target = "id", source = "persisted.id")
@Mapping(target = "reviewedBy", ignore = true)
Article toArticleUsingIgnore(ArticleDTO dto, Article persisted);

That also gives us the correct result:

@Test
void givenArticleDTO_whenToArticleUsingIgnore_thenReturnsArticleWithNullReviewedBy() {
    Article oldArticle1 = new Article("Title 1", "John Doe");

    Article result1 = articleMapper.toArticleUsingIgnore(new ArticleDTO("Updated article 1 title"), oldArticle1);

    assertThat(result1.getReviewedBy()).isNull();
    assertThat(result1.getTitle()).isEqualTo("Updated article 1 title");
}

3.4. Using the @AfterMapping Annotation

MapStruct lets us define a default method to run after mapping completes using the @AfterMapping annotation. Hence, we can define an annotated method that sets the reviewedBy field to null when the mapping target is of Article type:

@AfterMapping
default void setNullReviewedBy(@MappingTarget Article article) {
    article.setReviewedBy(null);
}

@Mapping(target = "title", source = "dto.title")
@Mapping(target = "id", source = "persisted.id")
Article toArticleUsingAfterMapping(ArticleDTO dto, Article persisted);

Which also gives us the expected result:

@Test
void givenArticleDTO_whenToArticleWithNullStatus_thenReturnsArticleWithNullStatus() {
    Article oldArticle1 = new Article("Title 1", "John Doe");

    Article result1 = articleMapper.toArticleUsingAfterMapping(new ArticleDTO("Updated article 1 title"), oldArticle1);

    assertThat(result1.getReviewedBy()).isNull();
    assertThat(result1.getTitle()).isEqualTo("Updated article 1 title");
}

With that approach, whenever we use a mapper method (from the same class that AfterMapping is defined) that produces an Article type, the setNullReviewedBy() method runs and sets reviewedBy to null.

Hence, its usage depends on the specific scenario we’re dealing with. If we must always produce Articles with reviewedBy as null, it’s a good fit.

Otherwise, it could cause side effects on other methods of the given mapper class and produce unwanted results.

4. Generalizing to Polymorphic Types

After MapStruct 1.5.0, we can also define mappers for polymorphic supertypes, allowing the mapping behavior to be automatically passed to their subtypes.

To combine this with the behavior of setting the reviewedBy field to null, we can create a generic mapper that sets the reviewedBy to all subtypes of a base entity using MapStruct subtypes.

4.1. Creating the New Class Structure

To illustrate generic mapping, let’s use a new class structure that has two base types. One is the Reviewable type:

public class Reviewable{
    protected String title;
    protected String reviewedBy;

    // getters, setters, and constructors
}

And the other is the ReviewableDTO:

public class ReviewableDTO {
    private String title;
    
    // getters, setters. and constructors
}

With that, we can create Reviewable subclasses:

public class Article extends Reviewable {
    private String title;

    // getter, setter, and constructors
}

public class WeeklyNews extends Reviewable {
    //getters setters constructors
}

And the ReviewableDTO subclasses:

public class ArticleDTO extends ReviewableDTO {
    private String title;

    // getters, setters, and constructors
}

public class WeeklyNewsDTO extends ReviewableDTO {
    private String title;

    // getters, setters, and constructors
}

4.2. Mapping Subtypes

Given the new class structure, we can define the ReviewableMapper:

@Mapper
public interface ReviewableMapper {
    @SubclassMapping(source = ArticleDTO.class, target = Article.class)
    @SubclassMapping(source = WeeklyNewsDTO.class, target = WeeklyNews.class)
    @Mapping(target = "reviewedBy", expression = "java(null)")
    Reviewable toReviewable(ReviewableDTO dto);
}

Notably, the new mapper uses the @SubclassMapping annotation to accept all subclasses of ReviewableDTO and return all subclasses of Reviewable. Additionally, we retained the expression=java(null) for mapping reviewedBy, but we could have chosen any of the forms presented in this article.

Let’s verify the desired behavior:

@Test
void givenArticleDTO_whenToReviewableUsingMapper_thenReturnsArticleWithNullStatus() {
    Reviewable result1 = reviewableMapper.toReviewable(new ArticleDTO("Updated article 1 title"));
    Reviewable result2 = reviewableMapper.toReviewable(new WeeklyNewsDTO());

    assertThat(result1).isInstanceOf(Article.class);
    assertThat(result2).isInstanceOf(WeeklyNews.class);
    assertThat(result1.getReviewedBy()).isNull();
    assertThat(result2.getReviewedBy()).isNull();
}

Noticeably, the mapper accepts both ReviewableDTO subtypes and maps them to the respective Reviewable subtype as verified by AssertJ’s isInstanceOf() method. Additionally, we got the desired behavior of always setting reviewedBy to null using ReviewableMapper.

5. Conclusion

In this article, we’ve learned different ways to always set a specific object field to null using MapStruct using the expression, qualifiedBy, and ignore properties from the @Mapper annotation. In addition, we’ve explored how to achieve this using @AfterMapping.

Finally, we’ve learned how to generalize the behavior for polymorphic types using MapStruct’s @SubclassMapping.

As always, the source code is available over on GitHub.