INT-3883: UDP: destination and socket expressions

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

UDP Outbound Channel Adapter is able to use given UDP Inbound Adapters
server socket (outgoing packets will have source port same as incoming
packets destination port).

* Introduce `destinationExpression` instead of hard-coded `host/port` logic in the `DatagramPacketMessageMapper`
* Make `UnicastSendingMessageHandler.destinationExpression` mutually exclusive with `host/port` pair
* Move `socketExpression` to the setter as it is absolutely different option from the `destination`
* Make `UnicastSendingMessageHandler` expressions logic based on the `requestMessage`

INT-3883 Code review fixes.

Further polishing

Polishing according PR comments

Rework the String socket address logic just to the expected `URI` style.
Accept `2016` for changed classes.

src/reference/asciidoc/ip.adoc

@@ -99,6 +99,43 @@ For even more reliable networking, TCP can be used.
 
 Starting with _version 4.3_, the `ackPort` can be set to `0`, in which case the Operating System chooses the port.
 
+Also starting with _version 4.3_, the `destination-expression` and `socket-expression` options are available
+for the `<int-ip:udp-outbound-channel-adapter>` (`UnicastSendingMessageHandler`).
+
+The `destination-expression` can be used as a runtime alternative to the hardcoded `host`/`port` pair to determine
+the destination address for the outgoing datagram packet against `requestMessage` as a root object for evaluation context.
+The expression must evaluate to `URI`, or `String` in the URI style (see http://www.ietf.org/rfc/rfc2396.txt[RFC-2396])
+or `SocketAddress`.
+The new `IpHeaders.PACKET_ADDRESS` header can be used for this expression as well.
+In the Framework this header is populated by the `DatagramPacketMessageMapper`, when we receive datagrams in the
+`UnicastReceivingChannelAdapter` and convert them to messages.
+The header value is exactly the result of `DatagramPacket.getSocketAddress()` of incoming datagram.
+
+With the `socket-expression` help the Outbound Channel Adapter can use e.g. Inbound Channel Adapter socket
+to send datagrams through same port which they were received.
+It's useful in a scenario when our application works as a UDP server and clients operate behind the NAT.
+This expression must evaluate to the `DatagramSocket`.
+The `requestMessage` is used as a root object for evaluation context.
+The `socket-expression` parameter cannot be used with parameters like `multicast` and `acknowledge`.
+
+[source,xml]
+----
+<int-ip:udp-inbound-channel-adapter id="inbound" port="0" channel="in" />
+
+<int:channel id="in" />
+
+<int:transformer expression="new String(payload).toUpperCase()"
+                       input-channel="in" output-channel="out"/>
+
+<int:channel id="out" />
+
+<int-ip:udp-outbound-channel-adapter id="outbound"
+                        socket-expression="@inbound.socket"
+                        destination-expression="headers['ip_packetAddress']"
+                        channel="out" />
+----
+
+
 [source,xml]
 ----
 <int-ip:udp-inbound-channel-adapter id="udpReceiver"
@@ -1220,6 +1257,13 @@ For a multicast adapter it is also used to determine which interface the multica
 If not supplied, an internal single threaded executor will be used.
 Needed on some platforms that require the use of specific task executors such as a WorkManagerTaskExecutor.
 One thread will be dedicated to handling acknowledgments (if the acknowledge option is true).
+| destination-expression
+| SpEL expression
+| A SpEL expression to be evaluated to determine which `SocketAddress` to use as a destination address for the
+outgoing UDP packets.
+| socket-expression
+| SpEL expression
+| A SpEL expression to be evaluated to determine which datagram socket use for sending outgoing UDP packets.
 |===
 
 .TCP Inbound Channel Adapter Attributes
@@ -1407,7 +1451,7 @@ For example, when using SSL, properties of the `SSLSession` can be added by obta
 [[ip-annotation]]
 === Annotation-Based Configuration
 
-The following example from the samples respository is used to illustrate some of the configuration options when using
+The following example from the samples repository is used to illustrate some of the configuration options when using
 annotations instead of XML.
 
 [source, java]

src/reference/asciidoc/whats-new.adoc

@@ -43,3 +43,7 @@ for more information.
 
 A new `TcpConnectionServerListeningEvent` is emitted when a server connection factory is started.
 See <<tcp-events>> for more information.
+
+The `destination-expression` and `socket-expression` are now available for the `<int-ip:udp-outbound-channel-adapter>`.
+See <<udp-adapters>> for more information.
+