Issue29 expose external conversions (#32)

* New attribute externalConversions for converters declared outside the scope of this spring config.

* Documentation for new attribute

Author: Chessray

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

@@ -0,0 +1,19 @@
+package org.mapstruct.extensions.spring;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Allows the specification of a conversion that is available via the {@link
+ * org.springframework.core.convert.ConversionService ConversionService}, but is <em>not</em>
+ * declared as a MapStruct mapper within the scope of the {@link SpringMapperConfig}.
+ */
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.SOURCE)
+public @interface ExternalConversion {
+  Class<?> sourceType();
+
+  Class<?> targetType();
+}

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

@@ -6,43 +6,53 @@
 import java.lang.annotation.Target;
 
 /**
- * Marks a class or interface as configuration source for the Spring extension. There can be only <em>one</em>
- * annotated type in each compiled module.
+ * Marks a class or interface as configuration source for the Spring extension. There can be only
+ * <em>one</em> annotated type in each compiled module.
  *
  * @author Raimund Klein
  */
 @Target(ElementType.TYPE)
 @Retention(RetentionPolicy.SOURCE)
 public @interface SpringMapperConfig {
-    /**
-     * The package name for the generated Adapter between the MapStruct mappers and Spring's
-     * {@link org.springframework.core.convert.ConversionService}. If omitted or empty, the package name will be the
-     * same as the one for the annotated type.
-     *
-     * @return The package name for the generated Adapter.
-     */
-    String conversionServiceAdapterPackage() default "";
+  /**
+   * The package name for the generated Adapter between the MapStruct mappers and Spring's {@link
+   * org.springframework.core.convert.ConversionService}. If omitted or empty, the package name will
+   * be the same as the one for the annotated type.
+   *
+   * @return The package name for the generated Adapter.
+   */
+  String conversionServiceAdapterPackage() default "";
 
-    /**
-     * The class name for the generated Adapter between the MapStruct mappers and Spring's
-     * {@link org.springframework.core.convert.ConversionService}.
-     *
-     * @return The class name for the generated Adapter.
-     */
-    String conversionServiceAdapterClassName() default "ConversionServiceAdapter";
+  /**
+   * The class name for the generated Adapter between the MapStruct mappers and Spring's {@link
+   * org.springframework.core.convert.ConversionService}.
+   *
+   * @return The class name for the generated Adapter.
+   */
+  String conversionServiceAdapterClassName() default "ConversionServiceAdapter";
 
-    /**
-     * The bean name for the Spring {@link org.springframework.core.convert.ConversionService} to use.
-     *
-     * @return The bean name for the Spring {@link org.springframework.core.convert.ConversionService}.
-     */
-    String conversionServiceBeanName() default "";
+  /**
+   * The bean name for the Spring {@link org.springframework.core.convert.ConversionService} to use.
+   *
+   * @return The bean name for the Spring {@link
+   *     org.springframework.core.convert.ConversionService}.
+   */
+  String conversionServiceBeanName() default "";
 
-    /**
-     * To set if the Lazy annotation will be added to the
-     * ConversionService's usage in the ConversionServiceAdapter.  Defaults to true.
-     *
-     * @return true to add the Lazy annotation
-     */
-    boolean lazyAnnotatedConversionServiceBean() default true;
+  /**
+   * To set if the Lazy annotation will be added to the ConversionService's usage in the
+   * ConversionServiceAdapter. Defaults to true.
+   *
+   * @return true to add the Lazy annotation
+   */
+  boolean lazyAnnotatedConversionServiceBean() default true;
+
+  /**
+   * Additional {@link ExternalConversion conversions} which should be made available through the
+   * generated Adapter.
+   *
+   * @return Additional {@link ExternalConversion conversions} which should be made available
+   *     through the generated Adapter.
+   */
+  ExternalConversion[] externalConversions() default {};
 }

build.gradle

@@ -1,11 +1,3 @@
-/*
- * This file was generated by the Gradle 'init' task.
- *
- * This generated file contains a sample Java Library project to get you started.
- * For more details take a look at the Java Libraries chapter in the Gradle
- * User Manual available at https://docs.gradle.org/5.6.2/userguide/java_library_plugin.html
- */
-
 plugins {
     id 'java-library'
     id 'jacoco'
@@ -14,6 +6,7 @@ plugins {
     id "com.github.ben-manes.versions" version "0.39.0"
     id "org.springframework.boot" version "2.5.1" apply false
     id "io.spring.dependency-management" version "1.0.11.RELEASE" apply false
+    id "org.asciidoctor.jvm.convert" version "3.3.2" apply false
 }
 
 def isNonStable = { String version ->

docs/build.gradle

@@ -1,6 +1,4 @@
-plugins {
-    id 'org.asciidoctor.jvm.convert' version '3.3.2'
-}
+apply plugin: "org.asciidoctor.jvm.convert"
 
 asciidoctor {
     baseDirFollowsSourceDir()

docs/src/docs/asciidoc/chapter-3-mapper-as-converter.asciidoc

@@ -32,6 +32,7 @@ This allows using the Mapper indirectly via the `ConversionService`:
 All this can be achieved already with MapStruct's core functionality. However, when a Mapper wants to https://mapstruct.org/documentation/stable/reference/html/#invoking-other-mappers[invoke] another one, it can't take the route via the `ConversionService`, because the latter's `convert` method does not match the signature that MapStruct expects for a mapping method. Thus, the developer still has to add every invoked Mapper to the invoking Mapper's `uses` element. This creates (aside from a potentially long list) a tight coupling between Mappers that the `ConversionService` wants to avoid.
 
 This is where MapStruct Spring Extensions can help. Including the two artifacts in your build will generate an Adapter class that _can_ be used by an invoking Mapper. Let's say that the above CarMapper is accompanied by a SeatConfigurationMapper:
+
 ====
 [source, java, linenums]
 [subs="verbatim,attributes"]
@@ -118,4 +119,54 @@ import org.mapstruct.extensions.spring.SpringMapperConfig;
 public interface MapperSpringConfig {
 }
 ----
+====
+[[externalConversions]]
+=== External Conversions
+Spring ships with a variety of https://github.com/spring-projects/spring-framework/tree/main/spring-core/src/main/java/org/springframework/core/convert/support[builtin conversions], e.g. `String` to `Locale` or `Object` to `Optional`. In order to use these (or your own conversions from another module) in the same fashion, you can add them as `externalConversions` to your `SpringMapperConfig`:
+====
+[source, java, linenums]
+[subs="verbatim,attributes"]
+----
+import org.mapstruct.MapperConfig;
+import org.mapstruct.extensions.spring.ExternalConversion;
+import org.mapstruct.extensions.spring.SpringMapperConfig;
+
+import java.util.Locale;
+
+@MapperConfig(componentModel = "spring")
+@SpringMapperConfig(
+    externalConversions = @ExternalConversion(sourceType = String.class, targetType = Locale.class))
+public interface MapstructConfig {}
+----
+====
+
+The processor will add the corresponding methods to the generated adapter so MapStruct can use them in the same fashion as the ones for the Converter Mappers in the same module:
+====
+[source, java, linenums]
+[subs="verbatim,attributes"]
+----
+import java.lang.String;
+import java.util.Locale;
+import javax.annotation.Generated;
+import org.springframework.context.annotation.Lazy;
+import org.springframework.core.convert.ConversionService;
+import org.springframework.stereotype.Component;
+
+@Generated(
+    value = "org.mapstruct.extensions.spring.converter.ConversionServiceAdapterGenerator",
+    date = "2021-06-25T18:51:21.585Z"
+)
+@Component
+public class ConversionServiceAdapter {
+  private final ConversionService conversionService;
+
+  public ConversionServiceAdapter(@Lazy final ConversionService conversionService) {
+    this.conversionService = conversionService;
+  }
+
+  public Locale mapStringToLocale(final String source) {
+    return conversionService.convert(source, Locale.class);
+  }
+}
+----
 ====

examples/external-conversions/build.gradle

@@ -0,0 +1,13 @@
+dependencies {
+    annotationProcessor project(":extensions")
+    implementation projects.examples.model
+    implementation projects.annotations
+
+    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/external-conversions/src/main/java/org/mapstruct/extensions/spring/example/externalconversions/LocaleInfo.java

@@ -0,0 +1,15 @@
+package org.mapstruct.extensions.spring.example.externalconversions;
+
+import java.util.Locale;
+
+public class LocaleInfo {
+    private Locale locale;
+
+    public Locale getLocale() {
+        return locale;
+    }
+
+    public void setLocale(Locale locale) {
+        this.locale = locale;
+    }
+}

examples/external-conversions/src/main/java/org/mapstruct/extensions/spring/example/externalconversions/LocaleInfoDto.java

@@ -0,0 +1,13 @@
+package org.mapstruct.extensions.spring.example.externalconversions;
+
+public class LocaleInfoDto {
+    private String locale;
+
+    public String getLocale() {
+        return locale;
+    }
+
+    public void setLocale(String locale) {
+        this.locale = locale;
+    }
+}

examples/external-conversions/src/main/java/org/mapstruct/extensions/spring/example/externalconversions/LocaleInfoDtoMapper.java

@@ -0,0 +1,10 @@
+package org.mapstruct.extensions.spring.example.externalconversions;
+
+import org.mapstruct.Mapper;
+import org.springframework.core.convert.converter.Converter;
+
+@Mapper(config = MapstructConfig.class, uses = ConversionServiceAdapter.class)
+public interface LocaleInfoDtoMapper extends Converter<LocaleInfoDto, LocaleInfo> {
+    @Override
+    LocaleInfo convert(LocaleInfoDto source);
+}

examples/external-conversions/src/main/java/org/mapstruct/extensions/spring/example/externalconversions/MapstructConfig.java

@@ -0,0 +1,12 @@
+package org.mapstruct.extensions.spring.example.externalconversions;
+
+import org.mapstruct.MapperConfig;
+import org.mapstruct.extensions.spring.ExternalConversion;
+import org.mapstruct.extensions.spring.SpringMapperConfig;
+
+import java.util.Locale;
+
+@MapperConfig(componentModel = "spring")
+@SpringMapperConfig(
+    externalConversions = @ExternalConversion(sourceType = String.class, targetType = Locale.class))
+public interface MapstructConfig {}