#3172 Add mapping between Locale and String

documentation/src/main/asciidoc/chapter-5-data-type-conversions.asciidoc

@@ -130,6 +130,9 @@ public interface CarMapper {
 * Between `java.net.URL` and `String`.
 ** When converting from a `String`, the value needs to be a valid https://en.wikipedia.org/wiki/URL[URL] otherwise a `MalformedURLException` is thrown.
 
+* Between `java.util.Locale` and `String`.
+** When converting from a `Locale`, the resulting `String` will be a well-formed IETF BCP 47 language tag representing the locale. When converting from a `String`, the locale that best represents the language tag will be returned. See https://docs.oracle.com/javase/8/docs/api/java/util/Locale.html#forLanguageTag-java.lang.String-[Locale.forLanguageTag()] and https://docs.oracle.com/javase/8/docs/api/java/util/Locale.html#toLanguageTag--[Locale.toLanguageTag()] for more information.
+
 [[mapping-object-references]]
 === Mapping object references
 

processor/src/main/java/org/mapstruct/ap/internal/conversion/Conversions.java

@@ -21,6 +21,7 @@ import java.util.Calendar;
 import java.util.Currency;
 import java.util.Date;
 import java.util.HashMap;
+import java.util.Locale;
 import java.util.Map;
 import java.util.Objects;
 import java.util.UUID;
@@ -198,6 +199,7 @@ public class Conversions {
         register( Currency.class, String.class, new CurrencyToStringConversion() );
 
         register( UUID.class, String.class, new UUIDToStringConversion() );
+        register( Locale.class, String.class, new LocaleToStringConversion() );
 
         registerURLConversion();
     }

processor/src/main/java/org/mapstruct/ap/internal/conversion/LocaleToStringConversion.java

@@ -0,0 +1,37 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct.ap.internal.conversion;
+
+import java.util.Locale;
+import java.util.Set;
+
+import org.mapstruct.ap.internal.model.common.ConversionContext;
+import org.mapstruct.ap.internal.model.common.Type;
+import org.mapstruct.ap.internal.util.Collections;
+
+import static org.mapstruct.ap.internal.conversion.ConversionUtils.locale;
+
+/**
+ * Conversion between {@link java.util.Locale} and {@link String}.
+ *
+ * @author Jason Bodnar
+ */
+public class LocaleToStringConversion extends SimpleConversion {
+    @Override
+    protected String getToExpression(ConversionContext conversionContext) {
+        return "<SOURCE>.toLanguageTag()";
+    }
+
+    @Override
+    protected String getFromExpression(ConversionContext conversionContext) {
+        return locale( conversionContext ) + ".forLanguageTag( <SOURCE> )";
+    }
+
+    @Override
+    protected Set<Type> getFromConversionImportTypes(final ConversionContext conversionContext) {
+        return Collections.asSet( conversionContext.getTypeFactory().getType( Locale.class ) );
+    }
+}

processor/src/test/java/org/mapstruct/ap/test/conversion/locale/LocaleConversionTest.java

@@ -0,0 +1,46 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct.ap.test.conversion.locale;
+
+import java.util.Locale;
+
+import org.mapstruct.ap.testutil.IssueKey;
+import org.mapstruct.ap.testutil.ProcessorTest;
+import org.mapstruct.ap.testutil.WithClasses;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+/**
+ * Tests conversions between {@link Locale} and String.
+ *
+ * @author Jason Bodnar
+ */
+@IssueKey("3172")
+@WithClasses({ LocaleSource.class, LocaleTarget.class, LocaleMapper.class })
+public class LocaleConversionTest {
+
+    @ProcessorTest
+    public void shouldApplyLocaleConversion() {
+        LocaleSource source = new LocaleSource();
+        source.setLocaleA( Locale.getDefault() );
+
+        LocaleTarget target = LocaleMapper.INSTANCE.sourceToTarget( source );
+
+        assertThat( target ).isNotNull();
+        assertThat( target.getLocaleA() ).isEqualTo( source.getLocaleA().toLanguageTag() );
+    }
+
+    @ProcessorTest
+    public void shouldApplyReverseLocaleConversion() {
+        LocaleTarget target = new LocaleTarget();
+        target.setLocaleA( Locale.getDefault().toLanguageTag() );
+
+        LocaleSource source = LocaleMapper.INSTANCE.targetToSource( target );
+
+        assertThat( source ).isNotNull();
+        assertThat( source.getLocaleA() ).isEqualTo( Locale.forLanguageTag( target.getLocaleA() ) );
+    }
+}

processor/src/test/java/org/mapstruct/ap/test/conversion/locale/LocaleMapper.java

@@ -0,0 +1,19 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct.ap.test.conversion.locale;
+
+import org.mapstruct.Mapper;
+import org.mapstruct.factory.Mappers;
+
+@Mapper
+public interface LocaleMapper {
+
+    LocaleMapper INSTANCE = Mappers.getMapper( LocaleMapper.class );
+
+    LocaleTarget sourceToTarget(LocaleSource source);
+
+    LocaleSource targetToSource(LocaleTarget target);
+}

processor/src/test/java/org/mapstruct/ap/test/conversion/locale/LocaleSource.java

@@ -0,0 +1,23 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct.ap.test.conversion.locale;
+
+import java.util.Locale;
+
+/**
+ * @author Jason Bodnar
+ */
+public class LocaleSource {
+    private Locale localeA;
+
+    public Locale getLocaleA() {
+        return localeA;
+    }
+
+    public void setLocaleA(Locale localeA) {
+        this.localeA = localeA;
+    }
+}

processor/src/test/java/org/mapstruct/ap/test/conversion/locale/LocaleTarget.java

@@ -0,0 +1,21 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct.ap.test.conversion.locale;
+
+/**
+ * @author Jason Bodnar
+ */
+public class LocaleTarget {
+    private String localeA;
+
+    public String getLocaleA() {
+        return localeA;
+    }
+
+    public void setLocaleA(String localeA) {
+        this.localeA = localeA;
+    }
+}