org.mapstruct

Annotation Type Context

@Target(value=PARAMETER)
 @Retention(value=CLASS)
public @interface Context

Marks a parameter of a method to be treated as mapping context. Such parameters are passed to other mapping methods, @ObjectFactory methods or @BeforeMapping/@AfterMapping methods when applicable and can thus be used in custom code.

The type of an @Context parameter is also inspected for @BeforeMapping/@AfterMapping methods, which are called on the provided context parameter value if applicable.

Note: no null checks are performed before calling before/after mapping methods on context parameters. The caller needs to make sure that no null are passed in that case.

For generated code to call a method that is declared with @Context parameters, the declaration of the mapping method being generated needs to contain at least those (or assignable) @Context parameters as well. MapStruct will not create new instances of missing @Context parameters nor will it pass null instead.

Example 1: Using @Context parameters for passing data down to hand-written property mapping methods and @BeforeMapping methods:

 
 // multiple @Context parameters can be added
 public abstract CarDto toCar(Car car, @Context VehicleRegistration context, @Context Locale localeToUse);

 protected OwnerManualDto translateOwnerManual(OwnerManual ownerManual, @Context Locale locale) {
     // manually implemented logic to translate the OwnerManual with the given Locale
 }

 @BeforeMapping
 protected void registerVehicle(Vehicle mappedVehicle, @Context VehicleRegistration context) {
     context.register( mappedVehicle );
 }

 @BeforeMapping
 protected void notCalled(Vehicle mappedVehicle, @Context DifferentMappingContextType context) {
     // not called, because no context parameter of type DifferentMappingContextType is available
     // within toCar(Car, VehicleRegistration, Locale)
 }

 // generates:

 public CarDto toCar(Car car, VehicleRegistration context, Locale localeToUse) {
     registerVehicle( car, context );

     if ( car == null ) {
         return null;
     }

     CarDto carDto = new CarDto();

     carDto.setOwnerManual( translateOwnerManual( car.getOwnerManual(), localeToUse );
     // more generated mapping code

     return carDto;
 }
 
 

Example 2: Using an @Context parameter with a type that provides its own @ BeforeMapping methods to handle cycles in Graph structures:

 
 // type of the context parameter
 public class CyclicGraphContext {
     private Map<Object, Object> knownInstances = new IdentityHashMap<>();

     @BeforeMapping
     public <T extends NodeDto> T getMappedInstance(Object source, @TargetType Class<T> targetType) {
         return (T) knownInstances.get( source );
     }

     @BeforeMapping
     public void storeMappedInstance(Object source, @MappingTarget NodeDto target) {
         knownInstances.put( source, target );
     }
 }

 @Mapper
 public interface GraphMapper {
     NodeDto toNodeDto(Node node, @Context CyclicGraphContext cycleContext);
 }


 // generates:

 public NodeDto toNodeDto(Node node, CyclicGraphContext cycleContext) {
     NodeDto target = cycleContext.getMappedInstance( node, NodeDto.class );
     if ( target != null ) {
         return target;
     }

     if ( node == null ) {
         return null;
     }

     NodeDto nodeDto = new NodeDto();

     cycleContext.storeMappedInstance( node, nodeDto );

     nodeDto.setParent( toNodeDto( node.getParent(), cycleContext ) );
     List<NodeDto> list = nodeListToNodeDtoList( node.getChildren(), cycleContext );
     if ( list != null ) {
         nodeDto.setChildren( list );
     }

     // more mapping code

     return nodeDto;
 }
 
 

Since:

1.2

Author:

Andreas Gudian