88 generate additional delegating mappers for inheritinverseconfiguration (#94)

* WIP: Working quite well, but for some reason the example now generates two separate converter adapters in different packages.

* WIP: Unified into single Processor; however, we are still getting a separate adapter class for the second round.

We need some type of marker mechanism in order to prevent generating a second (meaningless) adapter in the second round.

* WIP: Seems to work now by using Filer.createResource instead of Filer.createSourceFile. Still requires polishing, integration tests and documentation.

* WIP: Switched to generating full class instead of abstract class, because the implementation generation was suppressed. Generated converters are still in the adapter. Requires polishing, integration tests and documentation.

* WIP: Resource generation meant that there were no class files, but this now works as long as the generated clas is NOT annotated as a @Mapper so the adapter generation does not get retriggered. Requires polishing, integration tests and documentation.

* Documentation completed

* Self-review: No need to change mapstruct core to implementation scope.

* Self-review: No new processor after all

Author: Chessray

annotations/src/main/java/org/mapstruct/extensions/spring/DelegatingConverter.java

@@ -0,0 +1,16 @@
+package org.mapstruct.extensions.spring;
+
+import static java.lang.annotation.ElementType.METHOD;
+import static java.lang.annotation.RetentionPolicy.SOURCE;
+
+import java.lang.annotation.Retention;
+import java.lang.annotation.Target;
+
+/**
+ * Indicates that the system should generate a delegating {@link
+ * org.springframework.core.convert.converter.Converter} that will call the annotated method in its
+ * own {@link org.springframework.core.convert.converter.Converter#convert(Object)}.
+ */
+@Target(METHOD)
+@Retention(SOURCE)
+public @interface DelegatingConverter {}

docs/src/docs/asciidoc/chapter-6-delegating-converters.asciidoc

@@ -0,0 +1,62 @@
+[[delegatingConverters]]
+== Delegating Converters
+
+Applying MapStruct's https://mapstruct.org/documentation/stable/reference/html/#inverse-mappings[inverse mappings] requires a second mapping method inside a `@Mapper`-annotated interface or abstract class.
+Since this is not how Spring sees `Converter` s, this inverted mapping method will be "invisible" to the `ConversionService`.
+Adding the annotation `@DelegatingConverter` to the same method will lead to the generation of a separate class which implements `Converter` and does nothing more than call the annotated method in its own `convert`.
+This class will have a method counterpart in the generated Adapter just like the ones annotated with `@Mapper`.
+
+Take this `Converter` for example:
+
+====
+[source,java,linenums]
+[subs="verbatim,attributes"]
+----
+@Mapper(config = MapperSpringConfig.class)
+public interface CarMapper extends Converter<Car, CarDto> {
+    @Mapping(target = "seats", source = "seatConfiguration")
+    CarDto convert(Car car);
+
+    @InheritInverseConfiguration
+    @DelegatingConverter
+    Car invertConvert(CarDto carDto);
+}
+----
+====
+
+Notice the combination of `@InheritInverseConfiguration` and `@DelegatingConverter` on the `invertConvert` method.
+The `@DelegatingConverter` will lead to a class like this:
+
+====
+[source,java,linenums]
+[subs="verbatim,attributes"]
+----
+@Component
+public class CarDtoToCarConverter implements Converter<CarDto, Car> {
+  private CarMapper delegateMapper;
+
+  public CarDtoToCarConverter(@Autowired final CarMapper delegateMapper) {
+    this.delegateMapper = delegateMapper;
+  }
+
+  @Override
+  public Car convert(final CarDto source) {
+    return delegateMapper.invertConvert(source);
+  }
+}
+----
+====
+
+The generated Adapter will contain a method counterpart like this:
+
+====
+[source,java,linenums]
+[subs="verbatim,attributes"]
+----
+  public Car mapCarDtoToCar(final CarDto source) {
+    return (Car) conversionService.convert(source, TypeDescriptor.valueOf(CarDto.class), TypeDescriptor.valueOf(Car.class));
+  }
+----
+====
+
+Please note: The behaviour of `@DelegatingConverter` is _not_ tied to `@InheritInverseConfiguration`; however, this is the only use case we are aware of where it provides meaningful value.

docs/src/docs/asciidoc/mapstruct-spring-extensions-reference-guide.asciidoc

@@ -26,4 +26,6 @@ include::chapter-3-mapper-as-converter.asciidoc[]
 
 include::chapter-4-external-conversions.asciidoc[]
 
-include::chapter-5-test-extensions.asciidoc[]
+include::chapter-5-test-extensions.asciidoc[]
+
+include::chapter-6-delegating-converters.asciidoc[]

examples/delegatingconverter/build.gradle

@@ -0,0 +1,14 @@
+dependencies {
+    annotationProcessor project(":extensions")
+    implementation projects.examples.model
+    implementation projects.annotations
+
+    testImplementation projects.testExtensions
+    testImplementation libs.assertj
+    testImplementation libs.bundles.junit.jupiter
+    implementation libs.mapstruct.core
+    annotationProcessor libs.mapstruct.processor
+    implementation libs.spring.context
+    implementation libs.spring.core
+    testImplementation libs.spring.test
+}

examples/delegatingconverter/src/main/java/org/mapstruct/extensions/spring/example/delegatingconverter/CarMapper.java

@@ -0,0 +1,19 @@
+package org.mapstruct.extensions.spring.example.delegatingconverter;
+
+import org.mapstruct.InheritInverseConfiguration;
+import org.mapstruct.Mapper;
+import org.mapstruct.Mapping;
+import org.mapstruct.extensions.spring.DelegatingConverter;
+import org.mapstruct.extensions.spring.example.Car;
+import org.mapstruct.extensions.spring.example.CarDto;
+import org.springframework.core.convert.converter.Converter;
+
+@Mapper(config = MapperSpringConfig.class)
+public interface CarMapper extends Converter<Car, CarDto> {
+    @Mapping(target = "seats", source = "seatConfiguration")
+    CarDto convert(Car car);
+
+    @InheritInverseConfiguration
+    @DelegatingConverter
+    Car invertConvert(CarDto carDto);
+}

examples/delegatingconverter/src/main/java/org/mapstruct/extensions/spring/example/delegatingconverter/MapperSpringConfig.java

@@ -0,0 +1,8 @@
+package org.mapstruct.extensions.spring.example.delegatingconverter;
+
+import org.mapstruct.MapperConfig;
+import org.mapstruct.extensions.spring.SpringMapperConfig;
+
+@MapperConfig(componentModel = "spring", uses = ConversionServiceAdapter.class)
+@SpringMapperConfig
+public interface MapperSpringConfig {}

examples/delegatingconverter/src/main/java/org/mapstruct/extensions/spring/example/delegatingconverter/SeatConfigurationMapper.java

@@ -0,0 +1,20 @@
+package org.mapstruct.extensions.spring.example.delegatingconverter;
+
+import org.mapstruct.InheritInverseConfiguration;
+import org.mapstruct.Mapper;
+import org.mapstruct.Mapping;
+import org.mapstruct.extensions.spring.DelegatingConverter;
+import org.mapstruct.extensions.spring.example.SeatConfiguration;
+import org.mapstruct.extensions.spring.example.SeatConfigurationDto;
+import org.springframework.core.convert.converter.Converter;
+
+@Mapper(config = MapperSpringConfig.class)
+public interface SeatConfigurationMapper extends Converter<SeatConfiguration, SeatConfigurationDto> {
+    @Mapping(target = "seatCount", source = "numberOfSeats")
+    @Mapping(target = "material", source = "seatMaterial")
+    SeatConfigurationDto convert(SeatConfiguration seatConfiguration);
+
+    @InheritInverseConfiguration
+    @DelegatingConverter
+    SeatConfiguration invertConvert(SeatConfigurationDto seatConfigurationDto);
+}

examples/delegatingconverter/src/main/java/org/mapstruct/extensions/spring/example/delegatingconverter/WheelMapper.java

@@ -0,0 +1,20 @@
+package org.mapstruct.extensions.spring.example.delegatingconverter;
+
+import org.mapstruct.InheritInverseConfiguration;
+import org.mapstruct.Mapper;
+import org.mapstruct.extensions.spring.AdapterMethodName;
+import org.mapstruct.extensions.spring.DelegatingConverter;
+import org.mapstruct.extensions.spring.example.Wheel;
+import org.mapstruct.extensions.spring.example.WheelDto;
+import org.springframework.core.convert.converter.Converter;
+
+@Mapper(config = MapperSpringConfig.class)
+@AdapterMethodName("toDto")
+public interface WheelMapper extends Converter<Wheel, WheelDto> {
+    @Override
+    WheelDto convert(Wheel source);
+
+    @InheritInverseConfiguration
+    @DelegatingConverter
+    Wheel invertConvert(WheelDto wheelDto);
+}

examples/delegatingconverter/src/main/java/org/mapstruct/extensions/spring/example/delegatingconverter/WheelsDtoListMapper.java

@@ -0,0 +1,13 @@
+package org.mapstruct.extensions.spring.example.delegatingconverter;
+
+import java.util.List;
+import org.mapstruct.Mapper;
+import org.mapstruct.extensions.spring.example.WheelDto;
+import org.mapstruct.extensions.spring.example.Wheels;
+import org.springframework.core.convert.converter.Converter;
+
+@Mapper(config = MapperSpringConfig.class)
+public interface WheelsDtoListMapper extends Converter<List<WheelDto>, Wheels> {
+    @Override
+    Wheels convert(List<WheelDto> source);
+}

examples/delegatingconverter/src/main/java/org/mapstruct/extensions/spring/example/delegatingconverter/WheelsMapper.java

@@ -0,0 +1,14 @@
+package org.mapstruct.extensions.spring.example.delegatingconverter;
+
+import java.util.List;
+import org.mapstruct.Mapper;
+import org.mapstruct.extensions.spring.example.Wheel;
+import org.mapstruct.extensions.spring.example.WheelDto;
+import org.mapstruct.extensions.spring.example.Wheels;
+import org.springframework.core.convert.converter.Converter;
+
+@Mapper(config = MapperSpringConfig.class, imports = Wheel.class)
+public interface WheelsMapper extends Converter<Wheels, List<WheelDto>> {
+    @Override
+    List<WheelDto> convert(Wheels source);
+}