Using Multiple Source Objects With MapStruct

1. Overview

MapStruct is a compile-time code generator that simplifies mapping between Java bean types while keeping the resulting mappings explicit and type-safe. As applications evolve, mapping logic often needs to combine data from different sources or apply additional transformation rules.

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

2. Single Source Object

A common use case for MapStruct involves mapping one object to another. This pattern appears frequently when converting domain entities into data transfer objects.

Let’s consider a simple Customer class:

class Customer {

    private String firstName;
    private String lastName;

    // getters and setters

}

We can assume there’s a corresponding CustomerDto DTO class that uses different property names:

class CustomerDto {

    private String forename;
    private String surname;

    // getters and setters

}

Of course, a mapper interface can define how these two types relate to each other:

@Mapper
public interface CustomerDtoMapper {

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

}

In this example, MapStruct generates the mapping implementation at compile time. Each target property explicitly references its corresponding source property, which keeps the mapping clear and easy to maintain.

3. Multiple Source Objects

In some scenarios, a target object needs to combine data from more than one source object. This situation often arises when assembling view models or transfer objects that span multiple domain concepts.

For instance, a shopping application might need to construct a delivery address for shipping purposes:

class DeliveryAddress {

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

    // getters and setters

}

A customer may have multiple addresses, such as a home address or a work address. Each address can be represented respectively:

class Address {

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

    // getters and setters

}

Thus, a mapper combines data from both a Customer and an Address to create a DeliveryAddress. MapStruct supports this by including multiple source parameters in a mapping method:

@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);

}

In this mapping, properties from each source parameter are referenced using dot notation. The parameter name becomes part of the mapping path, which makes the origin of each value explicit.

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());

This approach scales beyond two source objects. A mapping method may declare any number of source parameters, as long as the target properties reference them unambiguously.

4. Update Existing Objects With @MappingTarget

Additionally, in some cases, an existing object already exists, and only selected fields need to be updated based on new input. MapStruct supports this scenario by providing a way to mark the method parameters as a mapping target.

For that, we can use the parameter annotated with @MappingTarget to represent the instance that receives the updated values.

Let’s see a mapper that updates address-related fields on an existing DeliveryAddress instance using data from an Address object:

@Mapper
interface DeliveryAddressMapper {

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

}

In this mapping, only the properties defined in the annotations are updated. All other fields on the target instance remain unchanged.

Now, let’s verify the behavior in a test scenario:

// 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());

This approach avoids unnecessary object creation and keeps update logic centralized within the mapper definition.

5. Passing Additional Parameters to a Mapper With @Context

Furthermore, mapping logic depends on additional information that doesn’t belong to the source or target object. This situation often arises when formatting, normalization, or auxiliary services participate in the mapping process.

MapStruct supports such a use case through context parameters. A parameter annotated with @Context is passed to the mapping method and becomes available to lifecycle callbacks such as @BeforeMapping and @AfterMapping.

For example, let’s see a helper class that represents a simple context to normalize names:

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

The mapper can then accept the context parameter and apply it during the mapping process:

@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, the context instance is provided alongside the source object:

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());

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

6. Mapping Several Source Fields to a Single Target Field

Sometimes, we derive a target property from multiple source fields. MapStruct doesn’t natively support mapping multiple source properties directly to a single target property. However, there are several ways to achieve this.

6.1. Using @Mapping With an Expression

One approach is to use the expression attribute of the @Mapping annotation. The expression enables writing custom Java code for the mapping:

@Mapping(
    target = "author",
    expression = "java(book.getAuthor().getFirstName() + \" \" + book.getAuthor().getLastName())"
)
BookDTO toDTO(Book book);

In this example, the author field of the DTO is constructed by concatenating two source fields from the Book entity.

6.2. Using @AfterMapping to Combine Fields

Another approach is to use a lifecycle callback without a context parameter. The target property can be ignored in the main mapping and set explicitly in an @AfterMapping method:

@Mapper
public interface BookMapper {

    BookMapper INSTANCE = Mappers.getMapper(BookMapper.class);

    @Mapping(target = "author", ignore = true)
    BookDTO toDTO(Book book);

    @AfterMapping
    default void setBookAuthor(@MappingTarget BookDTO bookDTO, Book book) {
        Author author = book.getAuthor();
        bookDTO.setAuthor(author.getFirstName() + " " + author.getLastName());
    }
}

This way, we can create more complex logic or multiple computations while keeping the mapping definition readable.

6.3. Using a Helper Method With @Named and Qualified Mapping

A third approach uses a helper class and @Named methods. The mapper references the helper via qualifiedByName to delegate computation:

public class MappingHelper {

    @Named("mapDetails")
    public static String mapDetails(Request request) {
        // custom logic to derive details
        return request.getTransaction().getProcess().getDetails();
    }
}

@Mapper(uses = { MappingHelper.class })
public interface MyMapper {

    @Mappings({
        @Mapping(
            target = "transaction.process.details",
            source = "request",
            qualifiedByName = "mapDetails"
        )
    })
    Response requestToResponse(Request request);
}

In this approach, MapStruct generates intermediary methods and delegates the complex mapping to the helper. It also enables the use of qualified methods for multiple fields across different mapping methods.

7. Conclusion

In this article, we explored how MapStruct handles more advanced mapping scenarios. Multiple source parameters can combine data from different objects into a single target, while @MappingTarget supports updating existing instances in place.