org.mapstruct.control.MappingControl Maven / Gradle / Ivy
Show all versions of mapstruct Show documentation
/*
* Copyright MapStruct Authors.
*
* Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
*/
package org.mapstruct.control;
import java.lang.annotation.ElementType;
import java.lang.annotation.Repeatable;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
* Controls which means of mapping are considered between the source and the target in mappings.
*
*
* There are several applications of MappingControl conceivable. One application, "deep cloning" is
* explained below in the example.
*
*
*
* Another application is controlling so called "complex mappings", which are not always desirable and sometimes lead to
* unexpected behaviour and prolonged compilation time.
*
*
* Example:Cloning of an object
*
* When all methods are allowed, MapStruct would make a shallow copy. It would take the ShelveDTO in
* the FridgeDTO and directly enter that as target on the target FridgeDTO. By disabling all
* other kinds of mappings apart from {@link MappingControl.Use#MAPPING_METHOD}, see {@link DeepClone} MapStruct is
* forced to generate mapping methods all through the object graph `FridgeDTO` and hence create a deep clone.
*
*
* public class FridgeDTO {
*
* private ShelveDTO shelve;
*
* public ShelveDTO getShelve() {
* return shelve;
* }
*
* public void setShelve(ShelveDTO shelve) {
* this.shelve = shelve;
* }
* }
*
*
* public class ShelveDTO {
*
* private CoolBeerDTO coolBeer;
*
* public CoolBeerDTO getCoolBeer() {
* return coolBeer;
* }
*
* public void setCoolBeer(CoolBeerDTO coolBeer) {
* this.coolBeer = coolBeer;
* }
* }
*
*
* public class CoolBeerDTO {
*
* private String beerCount;
*
* public String getBeerCount() {
* return beerCount;
* }
*
* public void setBeerCount(String beerCount) {
* this.beerCount = beerCount;
* }
* }
*
*
*
* @Mapper(mappingControl = DeepClone.class)
* public interface CloningMapper {
*
* CloningMapper INSTANCE = Mappers.getMapper( CloningMapper.class );
*
* FridgeDTO clone(FridgeDTO in);
*
* }
*
*
* @author Sjaak Derksen
*
* @since 1.4
*/
@Retention(RetentionPolicy.CLASS)
@Repeatable(MappingControls.class)
@Target( ElementType.ANNOTATION_TYPE )
@MappingControl( MappingControl.Use.DIRECT )
@MappingControl( MappingControl.Use.BUILT_IN_CONVERSION )
@MappingControl( MappingControl.Use.MAPPING_METHOD )
@MappingControl( MappingControl.Use.COMPLEX_MAPPING )
public @interface MappingControl {
Use value();
enum Use {
/**
* Controls the mapping, allows for type conversion from source type to target type
*
* Type conversions are typically supported directly in Java. The "toString()" is such an example,
* which allows for mapping for instance a {@link java.lang.Number} type to a {@link java.lang.String}.
*
* Please refer to the MapStruct guide for more info.
*
* @since 1.4
*/
BUILT_IN_CONVERSION,
/**
* Controls the mapping from source to target type, allows mapping by calling:
*
* - A type conversion, passed into a mapping method
* - A mapping method, passed into a type conversion
* - A mapping method passed into another mapping method
*
*
* @since 1.4
*/
COMPLEX_MAPPING,
/**
* Controls the mapping, allows for a direct mapping from source type to target type.
*
* This means if source type and target type are of the same type, MapStruct will not perform
* any mappings anymore and assign the target to the source direct.
*
* An exception are types from the package {@code java}, which will be mapped always directly.
*
* @since 1.4
*/
DIRECT,
/**
* Controls the mapping, allows for Direct Mapping from source type to target type.
*
* The mapping method can be either a custom referred mapping method, or a MapStruct built in
* mapping method.
*
* @since 1.4
*/
MAPPING_METHOD
}
}