INT-3556: Payload Conversion Documentation

JIRA: https://jira.spring.io/browse/INT-3556

Clarify when a `GenericConverter` might be needed rather
than a simple `Converter`.

spring-integration-core/src/test/java/org/springframework/integration/channel/DatatypeChannelTests.java

@@ -16,13 +16,17 @@
 
 package org.springframework.integration.channel;
 
+import static org.hamcrest.Matchers.instanceOf;
 import static org.junit.Assert.assertEquals;
 import static org.junit.Assert.assertNotNull;
 import static org.junit.Assert.assertSame;
+import static org.junit.Assert.assertThat;
 import static org.junit.Assert.assertTrue;
 
 import java.util.Collections;
 import java.util.Date;
+import java.util.HashSet;
+import java.util.Set;
 
 import org.junit.Test;
 
@@ -31,13 +35,16 @@ import org.springframework.beans.factory.support.BeanDefinitionBuilder;
 import org.springframework.context.support.ConversionServiceFactoryBean;
 import org.springframework.context.support.GenericApplicationContext;
 import org.springframework.core.convert.ConversionService;
+import org.springframework.core.convert.TypeDescriptor;
 import org.springframework.core.convert.converter.Converter;
+import org.springframework.core.convert.converter.GenericConverter;
 import org.springframework.core.convert.support.DefaultConversionService;
 import org.springframework.core.convert.support.GenericConversionService;
 import org.springframework.integration.context.IntegrationContextUtils;
 import org.springframework.integration.support.converter.DefaultDatatypeChannelMessageConverter;
 import org.springframework.integration.support.utils.IntegrationUtils;
 import org.springframework.integration.test.util.TestUtils;
+import org.springframework.messaging.Message;
 import org.springframework.messaging.MessageChannel;
 import org.springframework.messaging.MessageDeliveryException;
 import org.springframework.messaging.MessagingException;
@@ -199,6 +206,23 @@ public class DatatypeChannelTests {
 		channel.send(new ErrorMessage(new Exception("test")));
 	}
 
+	@Test
+	public void genericConverters() {
+		QueueChannel channel = createChannel(Foo.class);
+		DefaultConversionService conversionService = new DefaultConversionService();
+		conversionService.addConverter(new StringToBarConverter());
+		conversionService.addConverter(new IntegerToBazConverter());
+		DefaultDatatypeChannelMessageConverter converter = new DefaultDatatypeChannelMessageConverter();
+		converter.setConversionService(conversionService);
+		channel.setMessageConverter(converter);
+		assertTrue(channel.send(new GenericMessage<String>("foo")));
+		Message<?> out = channel.receive(0);
+		assertThat(out.getPayload(), instanceOf(Bar.class));
+		assertTrue(channel.send(new GenericMessage<Integer>(42)));
+		out = channel.receive(0);
+		assertThat(out.getPayload(), instanceOf(Baz.class));
+	}
+
 
 	private static QueueChannel createChannel(Class<?> ... datatypes) {
 		QueueChannel channel = new QueueChannel();
@@ -207,4 +231,50 @@ public class DatatypeChannelTests {
 		return channel;
 	}
 
+	private static class Foo {
+
+	}
+
+	private static class Bar extends Foo {
+
+	}
+
+	private static class Baz extends Foo {
+
+	}
+
+	private static class StringToBarConverter implements GenericConverter {
+
+		@Override
+		public Set<ConvertiblePair> getConvertibleTypes() {
+			Set<ConvertiblePair> pairs = new HashSet<ConvertiblePair>();
+			pairs.add(new ConvertiblePair(String.class, Foo.class));
+			pairs.add(new ConvertiblePair(String.class, Bar.class));
+			return pairs;
+		}
+
+		@Override
+		public Object convert(Object source, TypeDescriptor sourceType, TypeDescriptor targetType) {
+			return new Bar();
+		}
+
+	}
+
+	private static class IntegerToBazConverter implements GenericConverter {
+
+		@Override
+		public Set<ConvertiblePair> getConvertibleTypes() {
+			Set<ConvertiblePair> pairs = new HashSet<ConvertiblePair>();
+			pairs.add(new ConvertiblePair(Integer.class, Foo.class));
+			pairs.add(new ConvertiblePair(Integer.class, Baz.class));
+			return pairs;
+		}
+
+		@Override
+		public Object convert(Object source, TypeDescriptor sourceType, TypeDescriptor targetType) {
+			return new Baz();
+		}
+
+	}
+
 }