How to Do Nested Mapping in Mapstruct?

1. Overview

In this tutorial, we’ll utilize the MapStruct library to map nested properties from a source POJO to the properties of a target POJO. Similarly, we may use the same technique discussed in this tutorial to map the source entity attribute values to the nested attribute values of the target entity.

Mapstruct uses annotations to help define the mapping between the POJOs’ attributes. Further, its Maven plugin auto-generates the mapper utility by reading metadata defined in the annotations. Additionally, the library allows custom mapper utilities to be defined to support fine-grained control.

We’ll demonstrate how to map nested properties from a hierarchical source entity to a flat target entity using the MapStruct library.

2. Use Case

Let’s consider a source entity, Order, and a target entity OrderDto, to demonstrate the MapStruct library’s ability to perform nested mapping:

The source entity Order represents a complex object with nested structures, including a Customer and a Product:

public class Order {
    private Customer customer;
    private Product product;
    
    //..Standard getters and setters
}

public class Customer {
    private String name;
    private Address address;
    
    //..Standard getters and setters
}

public class Product {
    private String name;
    private double price;
    
    //..Standard getters and setters
}

Furthermore, the Customer entity has an address attribute of type Address:

public class Address {
    private String city;
    private String zipCode;
    
    //..Standard getters and setters
}

The target entity OrderDto is a simplified, flattened version of the Order entity. It contains fields like customerName, customerCity, customerZipCode, productName, and productPrice, which are the nested fields of the Order entity:

public class OrderDto {
    private String customerName;
    private String customerCity;
    private String customerZipCode;
    private String productName;
    private double productPrice;
    
    //..Standard getters and setters
}

Further, in the upcoming section, we’ll learn to create the OrderDto from the Order object using the MapStruct library.

3. Map Nested Properties Using @Mapping Annotation

Cases that merely need a one-to-one mapping and don’t demand customization can be handled simply with the @Mapping annotation.

First, we must define the mapper interface decorated with the @Mapper annotation as per the MapStruct library’s convention:

@Mapper
public interface OrderMapper {
    OrderMapper INSTANCE = Mappers.getMapper(OrderMapper.class);

    @Mapping(source = "customer.name", target = "customerName")
    @Mapping(source = "product.name", target = "productName")
    @Mapping(source = "product.price", target = "productPrice")
    @Mapping(source = "customer.address.city", target = "customerCity")
    @Mapping(expression = "java(order.getCustomer().getAddress().getZipCode())", 
      target = "customerZipCode")
    OrderDto orderToOrderDto(Order order);
}

In the OrderMapper interface, the orderToOrderDto() method converts an Order object to an OrderDto object. The @Mapping annotations on the mapper method help define the mapping from the Order object attributes, including the nested ones, to the target OrderDto attributes.

Further, we employ the dot notation to access the properties of attributes like Order#customer and Order#product. Similarly, we access the city property of the Customer#address attribute. Further, we have the freedom to use Java expressions as well. Hence, we used it to populate the OrderDto#customerZipCode attribute.

Finally, when we build the code, the Maven plugin MapStruct Processor generates the OrderMapperImpl class:

public class OrderMapperImpl implements OrderMapper {
    @Override
    public OrderDto orderToOrderDto(Order order) {
        if ( order == null ) {
            return null;
        }

        OrderDto orderDto = new OrderDto();

        orderDto.setCustomerName( orderCustomerName( order ) );
        orderDto.setProductName( orderProductName( order ) );
        orderDto.setProductPrice( orderProductPrice( order ) );
        orderDto.setCustomerCity( orderCustomerAddressCity( order ) );
        orderDto.setCustomerZipCode( order.getCustomer().getAddress().getZipCode() );
        return orderDto;
    }

    private String orderCustomerName(Order order) {
        Customer customer = order.getCustomer();
        if ( customer == null ) {
            return null;
        }
        return customer.getName();
    }

    private String orderCustomerAddressCity(Order order) {
        Customer customer = order.getCustomer();
        if ( customer == null ) {
            return null;
        }
        Address address = customer.getAddress();
        if ( address == null ) {
            return null;
        }
        return address.getCity();
    }

    //..Other private methods
}

The Maven plugin parses the Mapping annotations and intelligently generates the orderToOrderDto() and other supporting private methods to extract the Order object’s nested properties. However, populating the OrderDto#customerZipCode attribute directly uses the Java expression from the annotation. Unlike the other cases, here we don’t have any null checks.

Moving on, let’s invoke the generated mapper class:

void givenOrder_whenMapToOrderDto_thenMapNestedAttributes() {
     Order order = createSampleOrderObject();

     OrderDto orderDto = OrderMapper.INSTANCE.orderToOrderDto(order);

     assertEquals("John Doe", orderDto.getCustomerName());
     assertEquals("New York", orderDto.getCustomerCity());
     assertEquals("10001", orderDto.getCustomerZipCode());
     assertEquals("Laptop", orderDto.getProductName());
     assertEquals(1200.00, orderDto.getProductPrice());
 }

The createSampleOrder() method helps create a sample Order object, which is passed as an argument to the mapper orderToOrderDto() method. Finally, we verify that all the nested properties are mapped correctly to the target OrderDto object.

4. Map Nested Properties Using Abstract Mapper

The @Mapping annotation may not offer enough flexibility to achieve the desired outcomes during the mapping process. For such cases, we may have to use an abstract mapper class:

@Mapper
public abstract class AbstractOrderMapper {
    public static final AbstractOrderMapper INSTANCE = Mappers.getMapper(AbstractOrderMapper.class);

    public OrderDto orderToOrderDto(Order order) {
        OrderDto orderDto = applyCustomMappings(order);
        orderDto = mapCustomer(order);
        mapProduct(order, orderDto);
        return orderDto;
    }

    @Mapping(source = "customer.name", target = "customerName")
    @Mapping(source = "customer.address.city", target = "customerCity")
    @Mapping(source = "customer.address.zipCode", target = "customerZipCode")
    protected abstract OrderDto mapCustomer(Order order);

    @Mapping(source = "product.name", target = "productName")
    @Mapping(source = "product.price", target = "productPrice")
    protected abstract void mapProduct(Order order, @MappingTarget OrderDto orderDto);
}

First, the orderToOrderDto() method invokes the applyCustomMappings() method to initialize the OrderDto object. Moreover, applyCustomMappings() may implement some logic or invoke downstream services to create the OrderDto object. After that, we invoke the abstract methods like mapCustomer() and mapProduct(). These abstract methods have the basic @Mapping annotations similar to those we discussed in the earlier section. They help update the properties of the customer and product attributes in the OrderDto object from the Order object.

In a different scenario, we can choose which methods to keep abstract and which to implement concretely for customization. Additionally, we may use other MapStruct features or annotations like @ObjectFactory to implement customization requiring fine-grained control.

Moving on, let’s build the class to generate the AbstractOrderMapperImpl class:

public class AbstractOrderMapperImpl extends AbstractOrderMapper {
    @Override
    protected OrderDto mapCustomer(Order order) {
        if ( order == null ) {
            return null;
        }

        OrderDto orderDto = new OrderDto();

        orderDto.setCustomerName( orderCustomerName( order ) );
        orderDto.setCustomerCity( orderCustomerAddressCity( order ) );
        orderDto.setCustomerZipCode( orderCustomerAddressZipCode( order ) );

        return orderDto;
    }

    @Override
    protected void mapProduct(Order order, OrderDto orderDto) {
        if ( order == null ) {
            return;
        }

        orderDto.setProductName( orderProductName( order ) );
        orderDto.setProductPrice( orderProductPrice( order ) );
    }

    private String orderCustomerName(Order order) {
        Customer customer = order.getCustomer();
        if ( customer == null ) {
            return null;
        }
        return customer.getName();
    }
    //..Other generated private methods deriving the attribute
    //..values from the nested properties of Order object	
}

The Maven plugin parsed metadata from the @Mapping annotations on the mapCustomer() and mapProduct() methods, generating their implementations. The AbstractOrderMapperImpl#orderToOrderDto() method inherited from the parent AbstractOrderMapper class invokes these implemented methods.

Finally, we can now run the AbstractOrderMapper#orderToOrderDto() method and validate the mapping:

void givenOrder_whenMapToOrderDto_thenMapNestedAttributesWithAbstractMapper() {
    Order order = createSampleOrderObject();

    OrderDto orderDto = AbstractOrderMapper.INSTANCE.orderToOrderDto(order);

    assertEquals("John Doe", orderDto.getCustomerName());
    assertEquals("New York", orderDto.getCustomerCity());
    assertEquals("10001", orderDto.getCustomerZipCode());
    assertEquals("Laptop", orderDto.getProductName());
    assertEquals(1200.00, orderDto.getProductPrice());
}

First, we created the sample Order object by invoking the createSampleOrderObject() method. Then we instantiated the AbstractOrderMapper implementation class. Next, we passed the sample OrderDto object to the AbstractOrderMapper#orderToOrderDto() method. Finally, we verified the values of the OrderDto object’s attributes.

5. Conclusion

In this article, we learned how to map nested properties of source entities to target entities. This is an important requirement frequently encountered in data transformation applications. Hence, it’s a significant feature of the MapStruct library. Moreover, the ability to customize to handle complex scenarios makes it considerably powerful.