Mastering Context in MapStruct: Leveraging @Context for Complex Source Mappings

1. Overview

In this tutorial, we’ll discuss the @Context annotation in the MapStruct library, which helps populate target POJO attributes using external sources or services. Additionally, it can be used to pass on state variables.

In most straightforward POJO-to-POJO mappings, the source and target attributes of the @Mapping annotation are sufficient. However, there are cases where we need finer control to pass additional arguments to custom services to derive a few target attribute values.

This is where the @Context attribute in the mapper class becomes valuable. Let’s discuss this in detail.

2. Mapping Use Case

Let’s start with a scenario where the mapping logic depends on an additional parameter beyond the source POJO:

Let’s imagine a stock trading application that receives trade requests from an upstream client. It forwards them to a downstream exchange after resolving the Security ID in the Trade Request into a Standard ID. Hence, it fetches a standard identifier such as a CUSIP, ISIN, or SEDOL corresponding to the Security ID.

Since this information isn’t available directly in the original trade request, the application’s mapper program must rely on an external Security Lookup Service. Eventually, the Mapper program creates a Trade Dto object from the Trade Request object. Finally, the Trade Service program sends the Trade Dto object to the exchange to execute the order.

Further, for the rest of the article, we’ll refer to the source POJO as Trade and the target POJO as TradeDto:

The context in the Mapper#toTradeDto() method can be an identifier type or a look-up service class like SecurityService.

Let’s explore how the @Context annotation can help implement this use case.

3. Context in Method Decorated With @BeforeMapping Annotation

The context values are available to the @BeforeMapping methods and the Java expressions declared in the @Mapping#expression attribute. The BeforeMapping methods are called at the beginning of the mapping implementation. Ideally, we use it to carry out the initialization processes. For our use case, we’ll initialize the security service class with the exchange code:

@Mapper
public abstract class TradeMapperWithBeforeMapping {
    protected SecurityService securityService;

    public static TradeMapperWithBeforeMapping getInstance() {
        return Mappers.getMapper(TradeMapperWithBeforeMapping.class);
    }

    @BeforeMapping
    protected void initialize(@Context Integer exchangeCode) {
        securityService = new SecurityService(exchangeCode);
    }

    @Mapping(target="securityIdentifier", 
      expression = "java(securityService.getSecurityIdentifierOfType(trade.getSecurityID(), identifierType))")
    protected abstract TradeDto toTradeDto(Trade trade, @Context String identifierType, @Context Integer exchangeCode);
}

First, we’ve used two context arguments in the toTradeDto() method. The second context argument exchangeCode is available to the initialize() method decorated with the @BeforeMapping annotation. The context arguments are also available to the Java expressions defined in the @Mapping#expression attribute.

Therefore, we’ve used the first context argument, identifierType, in the @Mapping#expression attribute. Further, to populate the target POJO’s TradeDto#securityIdentifier attribute, we’ve invoked SecurityService#getSecurityIdentifierOfType() in the expression:

public String getSecurityIdentifierOfType(String securityID, String identifierType) {
    return switch (identifierType.toUpperCase()) {
        case "ISIN" -> "US0378331005";
        case "CUSIP" -> "037833100";
        case "SEDOL" -> "B1Y8QX7";
        default -> null;
    };
}

The getSecurityIdentifierOfType() is simply a simulation, which, in real-world applications, would make a downstream call to fetch the right identifier.

Finally, let’s invoke the mapper to see if it works:

void givenBeforeMappingMethod_whenSecurityIdInTradeObject_thenSetSecurityIdentifierInTradeDto() {
    Trade trade = createTradeObject();

    TradeDto tradeDto = TradeMapperWithBeforeMapping.getInstance()
      .toTradeDto(trade, "CUSIP", 6464);

    assertEquals("037833100", tradeDto.getSecurityIdentifier());
}

First, we create a sample source Trade object by calling the createTradeObject() method. The method returns a Trade object with the securityIdentifier, quantity, and price attributes set to AAPL, 100, and 150.0, respectively:

Trade createTradeObject() {
    return new Trade("AAPL", 100, 150.0);
}

Later, the mapper successfully populates the CUSIP equivalent of Trade#SecurityID into TradeDto#SecurityIdentifier.

We’ll reuse this createTradeObject() to create a sample Trade object in our other examples.

4. Context in Method Decorated With @AfterMapping Annotation

At times, we may want to populate attributes based on external context after completing the initial mapping. In such cases, we can use the @AfterMapping annotation on methods to call them toward the end of the mapping operation. Importantly, such methods have access to the context arguments declared in the original mapping method in the mapper class:

@Mapper
public abstract class TradeMapperWithAfterMapping {
    public static TradeMapperWithAfterMapping getInstance() {
        return Mappers.getMapper(TradeMapperWithAfterMapping.class);
    }

    protected abstract TradeDto toTradeDto(Trade trade, @Context String identifierType);

    @AfterMapping
    protected TradeDto convertToIdentifier(Trade trade, 
      @MappingTarget TradeDto tradeDto, @Context String identifierType) {
        SecurityService securityService = new SecurityService();
        tradeDto.setSecurityIdentifier(
          securityService.getSecurityIdentifierOfType(trade.getSecurityID(), identifierType)
         );
        return tradeDto;
    }
}

In this example, we’ve applied the @AfterMapping annotation to the convertToIdentifier() method. In addition to the @Context annotation on the argument indentifierType, it has @MappingTarget annotation on the argument tradeDto.

Moreover, the @MappingTarget annotation helps provide access to the source Trade object. The method invokes SecurityService#getSecurityIdentifierOfType() to populate the TradeDto#securityIdentifier attribute.

Finally, let’s run the mapper and verify the results:

void givenAfterMappingMethod_whenSecurityIdInTradeObject_thenSetSecurityIdentifierInTradeDto() {
    Trade trade = createTradeObject();

    TradeDto tradeDto = TradeMapperWithAfterMapping.getInstance()
      .toTradeDto(trade, "CUSIP");

    assertEquals("037833100", tradeDto.getSecurityIdentifier());
}

As expected, the target TradeDto#securityIdentifier attribute gets populated with the CUSIP equivalent of the source Trade#SecurityID.

5. Context in Method Decorated With @ObjectFactory Annotation

MapStruct provides a fine-grained control to customize the mapping operations with the @ObjectFactory annotation. Like other features, context arguments are also available to methods annotated with @ObjectFactory.

Moving on, let’s define one of such @ObjectFactory annotated methods in a class that creates the target TradeDto object:

public class TradeDtoFactory {
    private static final Logger logger = LoggerFactory.getLogger(TradeFactory.class);

    @ObjectFactory
    public TradeDto createTradeDto(Trade trade, @Context String identifierType) {
        SecurityService securityService = new SecurityService();
        String securityIdentifier = securityService.getSecurityIdentifierOfType(trade.getSecurityID(), identifierType);
        TradeDto tradeDto = new TradeDto(securityIdentifier);
        return tradeDto;
    }
}

First, the TradeFactory#createTradeDto() instantiates the SecurityService class and then invokes its getSecurityIdentifierOfType() method to fetch the SecurityIdentifier. Finally, it returns the Trade object after creating the TradeDto object by passing the securityIdentifier to the constructor.

Now, in the mapper class, we must assign TradeFactory.class to @Mapper#uses attribute:

@Mapper(uses = TradeDtoFactory.class)
public abstract class TradeMapperUsingObjectFactory {
    public static TradeMapperUsingObjectFactory getInstance() {
        return Mappers.getMapper(TradeMapperUsingObjectFactory.class);
    }

    protected abstract TradeDto toTradeDto(Trade trade, @Context String identifierType);
}

After compilation, the generated implementation TradeMapperUsingObjectFactoryImpl#toTradeDto() method invokes the factory instead of  TradeDto‘s constructor. Later, in the implementation method, the rest of the target attributes are populated from the Trade#quantity and Trade#price attributes.

Moving on, let’s run the mapper program and validate the result:

void whenGivenSecurityIDInTradeObject_thenUseObjectFactoryToCreateTradeDto() {
    Trade trade = createTradeObject();

    TradeDto tradeDto = TradeMapperUsingObjectFactory.getInstance()
      .toTradeDto(trade, "SEDOL");

    assertEquals("B1Y8QX7", tradeDto.getSecurityIdentifier());
}

As expected, the program TradeMapperUsingObjectFactory#toTradeDto() successfully populates the TradeDto#SecurityIdentifier attribute with the SEDOL equivalent of Trade#securityID.

6. Conclusion

In this article, we learned how to use MapStruct’s @Context annotation to map target attributes that depend on external contexts. The feature is extremely important to provide a fine-grained control over the mapping operation. It helps pass context or state parameters to external services that retrieve target attribute values from other sources.

Moreover, they augment and complement the current features such as @AfterMapping, @BeforeMapping, @ObjectFactory annotations, and @Mapping#expression attribute.