Using Multiple Source Objects with MapStruct

1. Overview

In this tutorial, we’ll see how to use multiple source objects with MapStruct.

2. Single Source Object

The most common use case for MapStruct is to map one object to another. Let’s assume we have a Customer class:

class Customer {

    private String firstName;
    private String lastName;

    // getters and setters

}

Let’s further assume that there’s a corresponding CustomerDto:

class CustomerDto {

    private String forename;
    private String surname;

    // getters and setters

}

We can now define a mapper that maps a Customer object to a CustomerDto object:

@Mapper
public interface CustomerDtoMapper {

    @Mapping(source = "firstName", target = "forename")
    @Mapping(source = "lastName", target = "surname")
    CustomerDto from(Customer customer);

}

3. Multiple Source Objects

Sometimes we want the target object having properties from multiple source objects. Let’s imagine we write a shopping application.

We need to construct a delivery address to ship our goods:

class DeliveryAddress {

    private String forename;
    private String surname;
    private String street;
    private String postalcode;
    private String county;

    // getters and setters

}

Each customer can have multiple addresses. One can be a home address. Another can be a work address:

class Address {

    private String street;
    private String postalcode;
    private String county;

    // getters and setters

}

We now need a mapper which creates the delivery address out of a customer and one of its addresses. MapStruct supports this by having multiple source objects:

@Mapper
interface DeliveryAddressMapper {

    @Mapping(source = "customer.firstName", target = "forename")
    @Mapping(source = "customer.lastName", target = "surname")
    @Mapping(source = "address.street", target = "street")
    @Mapping(source = "address.postalcode", target = "postalcode")
    @Mapping(source = "address.county", target = "county")
    DeliveryAddress from(Customer customer, Address address);

}

Let’s see this in action by writing a small test:

// given a customer
Customer customer = new Customer().setFirstName("Max")
  .setLastName("Powers");

// and some address
Address homeAddress = new Address().setStreet("123 Some Street")
  .setCounty("Nevada")
  .setPostalcode("89123");

// when calling DeliveryAddressMapper::from
DeliveryAddress deliveryAddress = deliveryAddressMapper.from(customer, homeAddress);

// then a new DeliveryAddress is created, based on the given customer and his home address
assertEquals(deliveryAddress.getForename(), customer.getFirstName());
assertEquals(deliveryAddress.getSurname(), customer.getLastName());
assertEquals(deliveryAddress.getStreet(), homeAddress.getStreet());
assertEquals(deliveryAddress.getCounty(), homeAddress.getCounty());
assertEquals(deliveryAddress.getPostalcode(), homeAddress.getPostalcode());

When we have more than one parameter, we can address them with dot-notation within the @Mapping annotation. For instance, to address the property firstName of the parameter named customer we simply write “customer.firstName“.

However, we are not limited to two source objects. Any number will do.

4. Update Existing Objects with @MappingTarget

Till now, we had mappers that create new instances of the target class. With multiple source objects, we can now also provide an instance to be updated.

For example, let’s assume that we want to update the customer-related properties of a delivery address. All we need is to have one of the parameters be the same type as returned by the method and annotate it with @MappingTarget:

@Mapper
interface DeliveryAddressMapper {

    @Mapping(source = "address.postalcode", target = "postalcode")
    @Mapping(source = "address.county", target = "county")
    DeliveryAddress updateAddress(@MappingTarget DeliveryAddress deliveryAddress, Address address);

}

So, let’s go ahead and do a quick test with an instance of DeliveryAddress:

// given a delivery address
DeliveryAddress deliveryAddress = new DeliveryAddress().setForename("Max")
  .setSurname("Powers")
  .setStreet("123 Some Street")
  .setCounty("Nevada")
  .setPostalcode("89123");

// and some new address
Address newAddress = new Address().setStreet("456 Some other street")
  .setCounty("Arizona")
  .setPostalcode("12345");

// when calling DeliveryAddressMapper::updateAddress
DeliveryAddress updatedDeliveryAddress = deliveryAddressMapper.updateAddress(deliveryAddress, newAddress);

// then the *existing* delivery address is updated
assertSame(deliveryAddress, updatedDeliveryAddress);

assertEquals(deliveryAddress.getStreet(), newAddress.getStreet());
assertEquals(deliveryAddress.getCounty(), newAddress.getCounty());
assertEquals(deliveryAddress.getPostalcode(), newAddress.getPostalcode());

5. Passing Additional Parameters to a Mapper with @Context

Sometimes, we want to pass in an extra object to help with the mapping, like a utility class to format names. MapStruct lets us do this using @Context.

Let’s say we have a helper class:

public class MappingContext {
    public String normalizeName(String name) {
        return name == null ? null : name.trim().toUpperCase();
    }
}

We update the mapper to use this context:

@Mapper
public interface CustomerDtoMapper {

    @Mapping(source = "firstName", target = "forename")
    @Mapping(source = "lastName", target = "surname")
    CustomerDto from(Customer customer, @Context MappingContext context);

    @AfterMapping
    default void normalize(@MappingTarget CustomerDto dto, @Context MappingContext context) {
        dto.setForename(context.normalizeName(dto.getForename()));
        dto.setSurname(context.normalizeName(dto.getSurname()));
    }
}

When invoking the mapper, we pass in the MappingContext instance:

Customer customer = new Customer();
customer.setFirstName(" max ");
customer.setLastName(" powers ");

MappingContext context = new MappingContext();
CustomerDto dto = customerDtoMapper.from(customer, context);

We can verify the results using JUnit assertions:

assertEquals("MAX", dto.getForename());
assertEquals("POWERS", dto.getSurname());

This approach allows us to inject helper logic (like normalization or formatting) without cluttering the mapper with unrelated responsibilities.

6. Conclusion

MapStruct allows us to pass more than one source parameter to mapping methods. For example, this comes handy when we want to combine multiple entities into one.

Another use case is to have the target object itself being one of the source parameters. Using the @MappingTarget annotation the given object can be updated in place.