Collection and Map Mapping

/**
 * Configures the mapping of one iterable- or array-typed attribute.
 */
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.CLASS)
@interface IterableMapping {
    /** Date format string for Date to String conversion of elements */
    String dateFormat() default "";
    
    /** Number format string for Number to String conversion of elements */
    String numberFormat() default "";
    
    /** Qualifiers for element mapping method selection */
    Class<? extends Annotation>[] qualifiedBy() default {};
    
    /** String-based qualifiers for element mapping method selection */
    String[] qualifiedByName() default {};
    
    /** Target type of iterable elements */
    Class<?> elementTargetType() default void.class;
    
    /** Strategy when null is passed as source argument */
    NullValueMappingStrategy nullValueMappingStrategy() default NullValueMappingStrategy.RETURN_NULL;
    
    /** Allows detailed control over element mapping process */
    Class<? extends Annotation> elementMappingControl() default MappingControl.class;
}

@Mapper
public interface CollectionMapper {
    // Basic list mapping
    List<PersonDto> toPersonDtos(List<Person> persons);
    
    // Iterable mapping with date formatting
    @IterableMapping(dateFormat = "yyyy-MM-dd")
    List<String> toDateStrings(List<LocalDate> dates);
    
    // Mapping with custom element type
    @IterableMapping(elementTargetType = SpecialDto.class)
    List<SpecialDto> toSpecialDtos(List<BaseEntity> entities);
    
    // Mapping with qualified element mapper
    @IterableMapping(qualifiedByName = "toSummary")
    List<SummaryDto> toSummaryDtos(List<DetailedEntity> entities);
    
    @Named("toSummary")
    SummaryDto entityToSummary(DetailedEntity entity);
    
    // Set mapping with null handling
    @IterableMapping(nullValueMappingStrategy = NullValueMappingStrategy.RETURN_DEFAULT)
    Set<CategoryDto> toCategoryDtos(Set<Category> categories);
    
    // Array mapping
    PersonDto[] toPersonDtoArray(Person[] persons);
}

/**
 * Configures the mapping of one map-typed attribute.
 */
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.CLASS)
@interface MapMapping {
    /** Date format string for Date to String conversion of keys */
    String keyDateFormat() default "";
    
    /** Date format string for Date to String conversion of values */
    String valueDateFormat() default "";
    
    /** Number format string for Number to String conversion of keys */
    String keyNumberFormat() default "";
    
    /** Number format string for Number to String conversion of values */
    String valueNumberFormat() default "";
    
    /** Qualifiers for key mapping method selection */
    Class<? extends Annotation>[] keyQualifiedBy() default {};
    
    /** String-based qualifiers for key mapping method selection */
    String[] keyQualifiedByName() default {};
    
    /** Qualifiers for value mapping method selection */
    Class<? extends Annotation>[] valueQualifiedBy() default {};
    
    /** String-based qualifiers for value mapping method selection */
    String[] valueQualifiedByName() default {};
    
    /** Target type of map keys */
    Class<?> keyTargetType() default void.class;
    
    /** Target type of map values */
    Class<?> valueTargetType() default void.class;
    
    /** Strategy when null is passed as source argument */
    NullValueMappingStrategy nullValueMappingStrategy() default NullValueMappingStrategy.RETURN_NULL;
}

@Mapper
public interface MapMapper {
    // Basic map mapping
    Map<String, PersonDto> toPersonDtoMap(Map<String, Person> personMap);
    
    // Map mapping with date formatting for values
    @MapMapping(valueDateFormat = "yyyy-MM-dd HH:mm:ss")
    Map<String, String> toTimestampMap(Map<String, LocalDateTime> timestampMap);
    
    // Map mapping with custom key/value types
    @MapMapping(
        keyTargetType = Long.class,
        valueTargetType = ProductSummaryDto.class
    )
    Map<Long, ProductSummaryDto> toProductSummaryMap(Map<String, Product> productMap);
    
    // Map mapping with qualified mappers
    @MapMapping(
        keyQualifiedByName = "stringToId",
        valueQualifiedByName = "toDetailedDto"
    )
    Map<Long, DetailedDto> toDetailedMap(Map<String, Entity> entityMap);
    
    @Named("stringToId")
    Long stringToId(String value);
    
    @Named("toDetailedDto")
    DetailedDto entityToDetailed(Entity entity);
    
    // Map with null value strategy
    @MapMapping(nullValueMappingStrategy = NullValueMappingStrategy.RETURN_DEFAULT)
    Map<String, CategoryDto> toCategoryMap(Map<String, Category> categoryMap);
}

/**
 * Strategy for propagating the value of collection-typed properties.
 */
enum CollectionMappingStrategy {
    /** Only JavaBeans accessor methods (getters/setters) will be used */
    ACCESSOR_ONLY,
    
    /** Prefer setter methods, but also consider adder methods */
    SETTER_PREFERRED,
    
    /** Prefer adder methods for each collection element */
    ADDER_PREFERRED,
    
    /** Target collection is immutable, create new instance */
    TARGET_IMMUTABLE
}

@Mapper(collectionMappingStrategy = CollectionMappingStrategy.ADDER_PREFERRED)
public interface OrderMapper {
    // Will prefer using addOrderLine() methods if available
    OrderDto toOrderDto(Order order);
}

@Mapper
public interface ImmutableMapper {
    // Method-level strategy override
    @BeanMapping(collectionMappingStrategy = CollectionMappingStrategy.TARGET_IMMUTABLE)
    ImmutableOrderDto toImmutableOrderDto(Order order);
}

// Example target class with adder methods
public class OrderDto {
    private List<OrderLineDto> orderLines = new ArrayList<>();
    
    // Setter method (SETTER_PREFERRED, ACCESSOR_ONLY)
    public void setOrderLines(List<OrderLineDto> orderLines) {
        this.orderLines = orderLines;
    }
    
    // Adder method (ADDER_PREFERRED)
    public void addOrderLine(OrderLineDto orderLine) {
        this.orderLines.add(orderLine);
    }
}

@Mapper
public interface StreamMapper {
    // Stream to List
    List<PersonDto> streamToList(Stream<Person> personStream);
    
    // List to Stream
    Stream<PersonDto> listToStream(List<Person> persons);
    
    // Array to List
    List<PersonDto> arrayToList(Person[] persons);
    
    // List to Array
    PersonDto[] listToArray(List<Person> persons);
    
    // Set transformations
    Set<PersonDto> toPersonDtoSet(Set<Person> persons);
    
    // Collection interface mapping
    Collection<PersonDto> toPersonDtoCollection(Collection<Person> persons);
}

@Mapper
public interface NestedCollectionMapper {
    // List of Lists
    List<List<PersonDto>> toNestedPersonDtos(List<List<Person>> nestedPersons);
    
    // Map with List values
    Map<String, List<OrderLineDto>> toOrderLineMap(Map<String, List<OrderLine>> orderLineMap);
    
    // Complex nested structure
    Map<String, Set<List<TagDto>>> toComplexTagStructure(Map<String, Set<List<Tag>>> tagStructure);
}

// Supporting entities
public class Order {
    private Map<String, List<OrderLine>> orderLinesByCategory;
    // ...
}

public class OrderDto {
    private Map<String, List<OrderLineDto>> orderLinesByCategory;
    // ...
}

@Mapper
public interface NullHandlingCollectionMapper {
    // Return null for null input (default)
    @IterableMapping(nullValueMappingStrategy = NullValueMappingStrategy.RETURN_NULL)
    List<PersonDto> toPersonDtos(List<Person> persons);
    
    // Return empty collection for null input
    @IterableMapping(nullValueMappingStrategy = NullValueMappingStrategy.RETURN_DEFAULT)
    List<PersonDto> toPersonDtosWithDefault(List<Person> persons);
    
    // Map null handling
    @MapMapping(nullValueMappingStrategy = NullValueMappingStrategy.RETURN_DEFAULT)
    Map<String, PersonDto> toPersonDtoMap(Map<String, Person> personMap);
    
    // Method to provide default collection
    default List<PersonDto> getDefaultPersonDtos() {
        return new ArrayList<>();
    }
}