#1355: Adds Implicit Conversion Between java.util.Currency <~> String (#1381)

* #1355: Setting up the test(s) for new conversion between java.util.Currency and String

* #1355: Added SimpleConversion subclass to convert a Currency object to a String object and vice-versa, and registered the class to Conversions

* #1355: Initial tests written, may need to re-write some test files for readability and/or add more test case(s). Basic tests are passing at this time

* #1355: Added copyright statement, added documentation for new implicit conversion

* #1355: Added clarity to documentation

* #1355: Replaced use of one letter variables

* #1355: Resolved CheckStyle errors

* #1355: Fixes license header spacing so the license plugin no longer fails the build

* Small cleanups

documentation/src/main/asciidoc/mapstruct-reference-guide.asciidoc

@@ -817,6 +817,9 @@ public interface CarMapper {
 
 * When converting from a `String`, omitting `Mapping#dateFormat`, it leads to usage of the default pattern and date format symbols for the default locale. An exception to this rule is `XmlGregorianCalendar` which results in parsing the `String` according to http://www.w3.org/TR/xmlschema-2/#dateTime[XML Schema 1.0 Part 2, Section 3.2.7-14.1, Lexical Representation].
 
+* Between `java.util.Currency` and `String`.
+** When converting from a `String`, the value needs to be a valid https://en.wikipedia.org/wiki/ISO_4217[ISO-4217] alphabetic code otherwise an `IllegalArgumentException` is thrown
+
 [[mapping-object-references]]
 === Mapping object references
 

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

@@ -25,6 +25,7 @@ import java.math.BigInteger;
 import java.sql.Time;
 import java.sql.Timestamp;
 import java.util.Calendar;
+import java.util.Currency;
 import java.util.Date;
 import java.util.HashMap;
 import java.util.Map;
@@ -194,6 +195,9 @@ public class Conversions {
         register( Date.class, Time.class, new DateToSqlTimeConversion() );
         register( Date.class, java.sql.Date.class, new DateToSqlDateConversion() );
         register( Date.class, Timestamp.class, new DateToSqlTimestampConversion() );
+
+        // java.util.Currency <~> String
+        register( Currency.class, String.class, new CurrencyToStringConversion() );
     }
 
     private void registerJodaConversions() {

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

@@ -0,0 +1,46 @@
+/**
+ *  Copyright 2012-2017 Gunnar Morling (http://www.gunnarmorling.de/)
+ *  and/or other contributors as indicated by the @authors tag. See the
+ *  copyright.txt file in the distribution for a full listing of all
+ *  contributors.
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+package org.mapstruct.ap.internal.conversion;
+
+import org.mapstruct.ap.internal.model.common.ConversionContext;
+import org.mapstruct.ap.internal.model.common.Type;
+import org.mapstruct.ap.internal.util.Collections;
+
+import java.util.Currency;
+import java.util.Set;
+
+/**
+ * @author Darren Rambaud
+ */
+public class CurrencyToStringConversion extends SimpleConversion {
+    @Override
+    protected String getToExpression(final ConversionContext conversionContext) {
+        return "<SOURCE>.getCurrencyCode()";
+    }
+
+    @Override
+    protected String getFromExpression(final ConversionContext conversionContext) {
+        return "Currency.getInstance( <SOURCE> )";
+    }
+
+    @Override
+    protected Set<Type> getFromConversionImportTypes(final ConversionContext conversionContext) {
+        return Collections.asSet( conversionContext.getTypeFactory().getType( Currency.class ) );
+    }
+}

processor/src/test/java/org/mapstruct/ap/test/conversion/currency/CurrencyConversionTest.java

@@ -0,0 +1,73 @@
+/**
+ *  Copyright 2012-2017 Gunnar Morling (http://www.gunnarmorling.de/)
+ *  and/or other contributors as indicated by the @authors tag. See the
+ *  copyright.txt file in the distribution for a full listing of all
+ *  contributors.
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+package org.mapstruct.ap.test.conversion.currency;
+
+import java.util.Currency;
+import java.util.HashSet;
+import java.util.Set;
+
+import org.junit.Test;
+import org.junit.runner.RunWith;
+import org.mapstruct.ap.internal.util.Collections;
+import org.mapstruct.ap.testutil.IssueKey;
+import org.mapstruct.ap.testutil.WithClasses;
+import org.mapstruct.ap.testutil.runner.AnnotationProcessorTestRunner;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+/**
+ * @author Darren Rambaud
+ */
+@WithClasses({ CurrencyMapper.class, CurrencySource.class, CurrencyTarget.class })
+@IssueKey("1355")
+@RunWith(AnnotationProcessorTestRunner.class)
+public class CurrencyConversionTest {
+
+    @Test
+    public void shouldApplyCurrencyConversions() {
+        final CurrencySource source = new CurrencySource();
+        source.setCurrencyA( Currency.getInstance( "USD" ) );
+        Set<Currency> currencies = new HashSet<Currency>();
+        currencies.add( Currency.getInstance( "EUR" ) );
+        currencies.add( Currency.getInstance( "CHF" ) );
+        source.setUniqueCurrencies( currencies );
+
+        CurrencyTarget target = CurrencyMapper.INSTANCE.currencySourceToCurrencyTarget( source );
+
+        assertThat( target ).isNotNull();
+        assertThat( target.getCurrencyA() ).isEqualTo( "USD" );
+        assertThat( target.getUniqueCurrencies() )
+            .isNotEmpty()
+            .containsExactlyInAnyOrder( "EUR", "CHF" );
+    }
+
+    @Test
+    public void shouldApplyReverseConversions() {
+        final CurrencyTarget target = new CurrencyTarget();
+        target.setCurrencyA( "USD" );
+        target.setUniqueCurrencies( Collections.asSet( "JPY" ) );
+
+        CurrencySource source = CurrencyMapper.INSTANCE.currencyTargetToCurrencySource( target );
+
+        assertThat( source ).isNotNull();
+        assertThat( source.getCurrencyA().getCurrencyCode() ).isEqualTo( Currency.getInstance( "USD" )
+            .getCurrencyCode() );
+        assertThat( source.getUniqueCurrencies() ).containsExactlyInAnyOrder( Currency.getInstance( "JPY" ) );
+    }
+}

processor/src/test/java/org/mapstruct/ap/test/conversion/currency/CurrencyMapper.java

@@ -0,0 +1,34 @@
+/**
+ *  Copyright 2012-2017 Gunnar Morling (http://www.gunnarmorling.de/)
+ *  and/or other contributors as indicated by the @authors tag. See the
+ *  copyright.txt file in the distribution for a full listing of all
+ *  contributors.
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+package org.mapstruct.ap.test.conversion.currency;
+
+import org.mapstruct.Mapper;
+import org.mapstruct.factory.Mappers;
+
+/**
+ * @author Darren Rambaud
+ */
+@Mapper
+public interface CurrencyMapper {
+    CurrencyMapper INSTANCE = Mappers.getMapper( CurrencyMapper.class );
+
+    CurrencyTarget currencySourceToCurrencyTarget(CurrencySource source);
+
+    CurrencySource currencyTargetToCurrencySource(CurrencyTarget target);
+}

processor/src/test/java/org/mapstruct/ap/test/conversion/currency/CurrencySource.java

@@ -0,0 +1,47 @@
+/**
+ *  Copyright 2012-2017 Gunnar Morling (http://www.gunnarmorling.de/)
+ *  and/or other contributors as indicated by the @authors tag. See the
+ *  copyright.txt file in the distribution for a full listing of all
+ *  contributors.
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+package org.mapstruct.ap.test.conversion.currency;
+
+import java.util.Currency;
+import java.util.Set;
+
+/**
+ * @author Darren Rambaud
+ */
+public class CurrencySource {
+
+    private Currency currencyA;
+    private Set<Currency> uniqueCurrencies;
+
+    public Currency getCurrencyA() {
+        return this.currencyA;
+    }
+
+    public void setCurrencyA(final Currency currencyA) {
+        this.currencyA = currencyA;
+    }
+
+    public Set<Currency> getUniqueCurrencies() {
+        return this.uniqueCurrencies;
+    }
+
+    public void setUniqueCurrencies(final Set<Currency> uniqueCurrencies) {
+        this.uniqueCurrencies = uniqueCurrencies;
+    }
+}

processor/src/test/java/org/mapstruct/ap/test/conversion/currency/CurrencyTarget.java

@@ -0,0 +1,46 @@
+/**
+ *  Copyright 2012-2017 Gunnar Morling (http://www.gunnarmorling.de/)
+ *  and/or other contributors as indicated by the @authors tag. See the
+ *  copyright.txt file in the distribution for a full listing of all
+ *  contributors.
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+package org.mapstruct.ap.test.conversion.currency;
+
+import java.util.Set;
+
+/**
+ * @author Darren Rambaud
+ */
+public class CurrencyTarget {
+
+    private String currencyA;
+    private Set<String> uniqueCurrencies;
+
+    public String getCurrencyA() {
+        return this.currencyA;
+    }
+
+    public void setCurrencyA(final String currencyA) {
+        this.currencyA = currencyA;
+    }
+
+    public Set<String> getUniqueCurrencies() {
+        return this.uniqueCurrencies;
+    }
+
+    public void setUniqueCurrencies(final Set<String> uniqueCurrencies) {
+        this.uniqueCurrencies = uniqueCurrencies;
+    }
+}