Core Mapping

/**
 * Marks an interface or abstract class as a mapper and activates the generation of a implementation of that type via MapStruct.
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.CLASS)
@interface Mapper {
    /** Other mapper types used by this mapper */
    Class<?>[] uses() default {};
    
    /** Additional types for import statements in generated mapper */
    Class<?>[] imports() default {};
    
    /** How unmapped properties of the source type should be reported */
    ReportingPolicy unmappedSourcePolicy() default ReportingPolicy.IGNORE;
    
    /** How unmapped properties of the target type should be reported */
    ReportingPolicy unmappedTargetPolicy() default ReportingPolicy.WARN;
    
    /** How lossy (narrowing) conversion should be reported */
    ReportingPolicy typeConversionPolicy() default ReportingPolicy.IGNORE;
    
    /** Specifies the component model for the generated mapper */
    String componentModel() default "default";
    
    /** Specifies the name of the implementation class */
    String implementationName() default "<CLASS_NAME>Impl";
    
    /** Specifies the target package for the generated implementation */
    String implementationPackage() default "<PACKAGE_NAME>";
    
    /** Class annotated with @MapperConfig to use as configuration template */
    Class<?> config() default void.class;
    
    /** Strategy for propagating collection-typed properties */
    CollectionMappingStrategy collectionMappingStrategy() default CollectionMappingStrategy.ACCESSOR_ONLY;
    
    /** Strategy when null is passed as source argument */
    NullValueMappingStrategy nullValueMappingStrategy() default NullValueMappingStrategy.RETURN_NULL;
    
    /** Strategy when null is passed as source argument to IterableMapping */
    NullValueMappingStrategy nullValueIterableMappingStrategy() default NullValueMappingStrategy.RETURN_NULL;
    
    /** Strategy when null is passed as source argument to MapMapping */
    NullValueMappingStrategy nullValueMapMappingStrategy() default NullValueMappingStrategy.RETURN_NULL;
    
    /** Strategy when source bean property is null or not present */
    NullValuePropertyMappingStrategy nullValuePropertyMappingStrategy() default NullValuePropertyMappingStrategy.SET_TO_NULL;
    
    /** Strategy for applying method-level configuration annotations */
    MappingInheritanceStrategy mappingInheritanceStrategy() default MappingInheritanceStrategy.EXPLICIT;
    
    /** When to include null check on source property value */
    NullValueCheckStrategy nullValueCheckStrategy() default NullValueCheckStrategy.ON_IMPLICIT_CONVERSION;
    
    /** How to handle missing implementation for super classes when using SubclassMapping */
    SubclassExhaustiveStrategy subclassExhaustiveStrategy() default SubclassExhaustiveStrategy.COMPILE_ERROR;
    
    /** Determines whether to use field or constructor injection */
    InjectionStrategy injectionStrategy() default InjectionStrategy.FIELD;
    
    /** Whether to disable automatic generation of sub-mapping methods */
    boolean disableSubMappingMethodsGeneration() default false;
    
    /** Builder configuration information */
    Builder builder() default @Builder;
    
    /** Allows detailed control over the mapping process */
    Class<? extends Annotation> mappingControl() default MappingControl.class;
    
    /** Exception to throw for unmapped enum values */
    Class<? extends Exception> unexpectedValueMappingException() default IllegalArgumentException.class;
    
    /** Whether to suppress timestamp in @Generated annotation */
    boolean suppressTimestampInGenerated() default false;
}

// Basic mapper
@Mapper
public interface CarMapper {
    CarMapper INSTANCE = Mappers.getMapper(CarMapper.class);
    
    CarDto toCarDto(Car car);
}

// Mapper with Spring integration
@Mapper(componentModel = "spring")
public interface UserMapper {
    @Mapping(source = "fullName", target = "name")
    UserDto toUserDto(User user);
}

// Mapper with custom configuration
@Mapper(
    uses = DateMapper.class,
    unmappedTargetPolicy = ReportingPolicy.ERROR,
    nullValueMappingStrategy = NullValueMappingStrategy.RETURN_DEFAULT
)
public interface OrderMapper {
    OrderDto toOrderDto(Order order);
}

/**
 * Configures the mapping of one bean attribute.
 */
@Repeatable(Mappings.class)
@Retention(RetentionPolicy.CLASS)
@Target({ElementType.METHOD, ElementType.ANNOTATION_TYPE})
@interface Mapping {
    /** The target name of the configured property */
    String target();
    
    /** The source name of the configured property */
    String source() default "";
    
    /** Date format string for Date to String conversion */
    String dateFormat() default "";
    
    /** Number format string for Number to String conversion */
    String numberFormat() default "";
    
    /** Constant String value to set target property to */
    String constant() default "";
    
    /** Java expression to compute target property value */
    String expression() default "";
    
    /** Default expression if source property is null */
    String defaultExpression() default "";
    
    /** Whether the target property should be ignored */
    boolean ignore() default false;
    
    /** Qualifiers for mapper method selection */
    Class<? extends Annotation>[] qualifiedBy() default {};
    
    /** String-based qualifiers for mapper method selection */
    String[] qualifiedByName() default {};
    
    /** Qualifiers for condition method selection */
    Class<? extends Annotation>[] conditionQualifiedBy() default {};
    
    /** String-based qualifiers for condition method selection */
    String[] conditionQualifiedByName() default {};
    
    /** Condition expression for property mapping */
    String conditionExpression() default "";
    
    /** Result type for mapping method selection */
    Class<?> resultType() default void.class;
    
    /** Properties on which this mapped property depends */
    String[] dependsOn() default {};
    
    /** Default value if source property is null */
    String defaultValue() default "";
    
    /** When to include null check on source property */
    NullValueCheckStrategy nullValueCheckStrategy() default NullValueCheckStrategy.ON_IMPLICIT_CONVERSION;
    
    /** Strategy when source property is null or not present */
    NullValuePropertyMappingStrategy nullValuePropertyMappingStrategy() default NullValuePropertyMappingStrategy.SET_TO_NULL;
    
    /** Allows detailed control over the mapping process */
    Class<? extends Annotation> mappingControl() default MappingControl.class;
}

@Mapper
public interface PersonMapper {
    // Basic property mapping
    @Mapping(source = "firstName", target = "name")
    PersonDto toPersonDto(Person person);
    
    // Multiple mappings with different strategies
    @Mapping(source = "birthDate", target = "dateOfBirth", dateFormat = "yyyy-MM-dd")
    @Mapping(source = "salary", target = "income", numberFormat = "#,###.00")
    @Mapping(target = "status", constant = "ACTIVE")
    @Mapping(target = "id", ignore = true)
    PersonDto toDetailedPersonDto(Person person);
    
    // Expression-based mapping
    @Mapping(target = "fullName", expression = "java(person.getFirstName() + \" \" + person.getLastName())")
    @Mapping(target = "age", expression = "java(java.time.Period.between(person.getBirthDate(), java.time.LocalDate.now()).getYears())")
    PersonSummaryDto toPersonSummaryDto(Person person);
    
    // Conditional mapping
    @Mapping(target = "email", conditionExpression = "java(person.getEmail() != null && person.getEmail().contains(\"@\"))")
    ContactDto toContactDto(Person person);
    
    // Default values
    @Mapping(source = "nickname", target = "displayName", defaultValue = "Unknown")
    @Mapping(source = "country", target = "location", defaultExpression = "java(\"Unknown Location\")")
    DisplayDto toDisplayDto(Person person);
}

/**
 * Configures the mapping between two bean types.
 */
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.CLASS)
@interface BeanMapping {
    /** Result type to select in case multiple mapping methods qualify */
    Class<?> resultType() default void.class;
    
    /** Qualifiers for factory method selection */
    Class<? extends Annotation>[] qualifiedBy() default {};
    
    /** String-based qualifiers for factory method selection */
    String[] qualifiedByName() default {};
    
    /** Strategy when null is passed as source argument */
    NullValueMappingStrategy nullValueMappingStrategy() default NullValueMappingStrategy.RETURN_NULL;
    
    /** Strategy when source bean property is null or not present */
    NullValuePropertyMappingStrategy nullValuePropertyMappingStrategy() default NullValuePropertyMappingStrategy.SET_TO_NULL;
    
    /** When to include null check on source property value */
    NullValueCheckStrategy nullValueCheckStrategy() default NullValueCheckStrategy.ON_IMPLICIT_CONVERSION;
    
    /** Whether to ignore all mappings by default */
    boolean ignoreByDefault() default false;
    
    /** Unmapped source properties to ignore in reporting */
    String[] ignoreUnmappedSourceProperties() default {};
    
    /** Builder configuration for this mapping */
    Builder builder() default @Builder;
    
    /** Allows detailed control over the mapping process */
    Class<? extends Annotation> mappingControl() default MappingControl.class;
    
    /** How to handle missing implementation for super classes */
    SubclassExhaustiveStrategy subclassExhaustiveStrategy() default SubclassExhaustiveStrategy.COMPILE_ERROR;
}

@Mapper
public interface OrderMapper {
    // Bean mapping with null value strategy
    @BeanMapping(nullValueMappingStrategy = NullValueMappingStrategy.RETURN_DEFAULT)
    OrderDto toOrderDto(Order order);
    
    // Ignore unmapped properties by default
    @BeanMapping(ignoreByDefault = true)
    @Mapping(target = "id", source = "orderId")
    @Mapping(target = "total", source = "amount")
    SimpleOrderDto toSimpleOrderDto(Order order);
    
    // Ignore specific unmapped source properties
    @BeanMapping(ignoreUnmappedSourceProperties = {"internalNotes", "auditInfo"})
    PublicOrderDto toPublicOrderDto(Order order);
}

/**
 * Is used to hold multiple @Mapping annotations as Java 8 introduces repeating annotations.
 */
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.CLASS)
@interface Mappings {
    /** The mapping configurations */
    Mapping[] value();
}

@Mapper
public interface LegacyMapper {
    // Pre-Java 8 style multiple mappings
    @Mappings({
        @Mapping(source = "firstName", target = "name"),
        @Mapping(source = "birthDate", target = "dateOfBirth", dateFormat = "yyyy-MM-dd"),
        @Mapping(target = "id", ignore = true)
    })
    PersonDto toPersonDto(Person person);
}

/**
 * Marks a class or interface as configuration source for generated mappers.
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.CLASS)
@interface MapperConfig {
    /** Other mapper types used by mappers using this configuration */
    Class<?>[] uses() default {};
    
    /** Additional types for import statements */
    Class<?>[] imports() default {};
    
    /** How unmapped properties of the source type should be reported */
    ReportingPolicy unmappedSourcePolicy() default ReportingPolicy.IGNORE;
    
    /** How unmapped properties of the target type should be reported */
    ReportingPolicy unmappedTargetPolicy() default ReportingPolicy.WARN;
    
    /** How lossy conversion should be reported */
    ReportingPolicy typeConversionPolicy() default ReportingPolicy.IGNORE;
    
    /** Component model for generated mappers */
    String componentModel() default "default";
    
    /** Name of implementation class */
    String implementationName() default "<CLASS_NAME>Impl";
    
    /** Target package for generated implementation */
    String implementationPackage() default "<PACKAGE_NAME>";
    
    /** Strategy for collection-typed properties */
    CollectionMappingStrategy collectionMappingStrategy() default CollectionMappingStrategy.ACCESSOR_ONLY;
    
    /** Strategy when null is passed as source argument */
    NullValueMappingStrategy nullValueMappingStrategy() default NullValueMappingStrategy.RETURN_NULL;
    
    /** Strategy when null is passed to IterableMapping */
    NullValueMappingStrategy nullValueIterableMappingStrategy() default NullValueMappingStrategy.RETURN_NULL;
    
    /** Strategy when null is passed to MapMapping */
    NullValueMappingStrategy nullValueMapMappingStrategy() default NullValueMappingStrategy.RETURN_NULL;
    
    /** Strategy when source bean property is null or not present */
    NullValuePropertyMappingStrategy nullValuePropertyMappingStrategy() default NullValuePropertyMappingStrategy.SET_TO_NULL;
    
    /** Strategy for applying method-level configuration annotations */
    MappingInheritanceStrategy mappingInheritanceStrategy() default MappingInheritanceStrategy.EXPLICIT;
    
    /** When to include null check on source property value */
    NullValueCheckStrategy nullValueCheckStrategy() default NullValueCheckStrategy.ON_IMPLICIT_CONVERSION;
    
    /** How to handle missing implementation for super classes */
    SubclassExhaustiveStrategy subclassExhaustiveStrategy() default SubclassExhaustiveStrategy.COMPILE_ERROR;
    
    /** Whether to use field or constructor injection */
    InjectionStrategy injectionStrategy() default InjectionStrategy.FIELD;
    
    /** Whether to disable automatic generation of sub-mapping methods */
    boolean disableSubMappingMethodsGeneration() default false;
    
    /** Builder configuration */
    Builder builder() default @Builder;
    
    /** Exception to throw for unmapped enum values */
    Class<? extends Exception> unexpectedValueMappingException() default IllegalArgumentException.class;
    
    /** Whether to suppress timestamp in @Generated annotation */
    boolean suppressTimestampInGenerated() default false;
}

// Shared configuration
@MapperConfig(
    componentModel = "spring",
    unmappedTargetPolicy = ReportingPolicy.ERROR,
    uses = {DateMapper.class, StringMapper.class}
)
public interface CentralConfig {
}

// Mappers using the configuration
@Mapper(config = CentralConfig.class)
public interface UserMapper {
    UserDto toUserDto(User user);
}

@Mapper(config = CentralConfig.class)
public interface OrderMapper {
    OrderDto toOrderDto(Order order);
}