For instance, let’s imagine that we have an app that calculates the user’s body mass index (BMI) report. To calculate BMI, we have to collect the user’s body values. To convert imperial units to metric units, we can use the custom mapper methods.

There are two ways of using a custom mapper with MapStruct. We can either call the custom method by typing it inside the @Mapping annotation’s qualifiedByName property, or we can create an annotation for it.

Before we start, we have to define a DTO class to hold imperial values:

public class UserBodyImperialValuesDTO {
    private int inch;
    private int pound;
    // constructor, getters, and setters
Next, we’ll define a DTO class to hold metric values:
public class UserBodyValues {
    private double kilogram;
    private double centimeter;
    // constructor, getters, and setters
3.1. Custom Mapper With Method
To start using custom mappers, we’ll create an interface with the @Mapper annotation:

@Mapper 
public interface UserBodyValuesMapper {
    //...
Then we’ll create our custom method with the return type we want, and the argument we need to convert. We have to use the @Named annotation with the value parameter to inform MapStruct about the custom mapper method:
@Mapper
public interface UserBodyValuesMapper {
    @Named("inchToCentimeter")
    public static double inchToCentimeter(int inch) {
        return inch * 2.54;
    //...
And finally, we’ll define the mapper interface method with the @Mapping annotation. Within this annotation, we’ll tell MapStruct about the source type, target type, and the method it’ll use:
@Mapper
public interface UserBodyValuesMapper {
    UserBodyValuesMapper INSTANCE = Mappers.getMapper(UserBodyValuesMapper.class);
    @Mapping(source = "inch", target = "centimeter", qualifiedByName = "inchToCentimeter")
    public UserBodyValues userBodyValuesMapper(UserBodyImperialValuesDTO dto);
    @Named("inchToCentimeter") 
    public static double inchToCentimeter(int inch) { 
        return inch * 2.54; 
Let’s test our custom mapper:
UserBodyImperialValuesDTO dto = new UserBodyImperialValuesDTO();
dto.setInch(10);
UserBodyValues obj = UserBodyValuesMapper.INSTANCE.userBodyValuesMapper(dto);
assertNotNull(obj);
assertEquals(25.4, obj.getCentimeter(), 0);
3.2. Custom Mapper With an Annotation
To use a custom mapper with an annotation, we have to define an annotation instead of the @Named annotation. Then we have to inform MapStruct about the newly created annotation by specifying the @Mapping annotation’s qualifiedByName parameter.
Let’s see how we define the annotation:

@Qualifier
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.CLASS)
public @interface PoundToKilogramMapper {
We’ll add the @PoundToKilogramMapper annotation to our poundToKilogram method:
@PoundToKilogramMapper
public static double poundToKilogram(int pound) {
    return pound * 0.4535;
Now we’ll define the mapper interface method with the @Mapping annotation. Within the mapping annotation, we’ll tell MapStruct about the source type, the target type, and the annotation class that it’ll use:
@Mapper
public interface UserBodyValuesMapper {
    UserBodyValuesMapper INSTANCE = Mappers.getMapper(UserBodyValuesMapper.class);
    @Mapping(source = "pound", target = "kilogram", qualifiedBy = PoundToKilogramMapper.class)
    public UserBodyValues userBodyValuesMapper(UserBodyImperialValuesDTO dto);
    @PoundToKilogramMapper
    public static double poundToKilogram(int pound) {
        return pound * 0.4535;
Finally, we’ll test our custom mapper:
UserBodyImperialValuesDTO dto = new UserBodyImperialValuesDTO();
dto.setPound(100);
UserBodyValues obj = UserBodyValuesMapper.INSTANCE.userBodyValuesMapper(dto);
assertNotNull(obj);
assertEquals(45.35, obj.getKilogram(), 0);
4. Conclusion
In this article, we demonstrated how to use a custom mapper with the MapStruct library.
The implementations of these examples and tests are available over on GitHub.
Partner – Bellsoft – NPI EA (cat = Spring)


Looking for the ideal Linux distro for running modern Spring
apps in the cloud?
Meet Alpaquita Linux: lightweight, secure, and powerful
enough to handle heavy workloads.
This distro is specifically designed for running Java
apps. It builds upon Alpine and features significant
enhancements to excel in high-density container environments while
meeting enterprise-grade security standards.
Specifically, the container image size is ~30% smaller than
standard options, and it consumes up to 30% less RAM:
Alpaquita Containers now.

Partner – Bellsoft – NPI EA (cat = Spring)


Just published a new writeup on how to run a standard Java/Boot
application as a Docker container, using the Liberica JDK on top of
Alpaquita Linux:
Spring Boot Application on Liberica Runtime Container.

Partner – Aegik AB – NPI EA (tag = SQL)


Slow MySQL query performance is all too common. Of course
it is.
The Jet Profiler was built entirely for MySQL, so it's
fine-tuned for it and does advanced everything with relaly minimal
impact and no server changes.
out the Profiler

Partner – Codium – NPI EA (cat = Testing)


Explore the secure, reliable, and high-performance Test
Execution Cloud built for scale. Right in your IDE:
CodiumAI. Meaningful Code Tests for Busy Devs

Basically, write code that works the way you meant it to.
Course – LS (cat=Java)

Get started with Spring Boot and with core Spring,
through the Learn Spring course:
>> CHECK OUT THE
COURSE
res – REST with Spring (eBook) (everywhere)

Learning to build your API

with Spring?
Download the E-book
Starting to test with Mockito?
Download the Guide
eBook – Video Security – NPI EA (cat=Spring Security)

Security basics for a REST API
access to the video
eBook – Persistence – NPI EA (cat=Persistence)

Download
the E-book