Package org.apache.axis2.transport.udp

Transport implementation for the UDP protocol.

This package contains a transport implementation allowing Axis to send and receive UDP packets. It is an implementation of "raw" UDP in the sense that the message is directly extracted from the UDP payload without any intermediate application protocol. This has several important implications:

  • The only way to route the incoming message to the appropriate Axis service is to bind the service a specific UDP port. The port number must be explicitly defined in the service configuration. This is different from protocols such as HTTP where the message can be routed based on the URL in the request.
  • The transport has no way to detect the content type of an incoming message. Indeed, there is no equivalent to HTTP's Content-Type header. Again the expected content type must be configured explicitly for the service.
  • Since UDP doesn't provide any mean to correlate responses to requests, the transport can only be used for asynchronous communication.
See the documentation of org.apache.synapse.transport.udp.UDPListener for more information about how to configure a service to accept UDP packets. Endpoint references for the UDP transport are assumed to follow the following syntax: 
 udp://host:port?contentType=...

The UDP transport can be enabled in the Axis configuration as follows: 

 <transportReceiver name="udp" class="org.apache.synapse.transport.udp.UDPListener"/>
 <transportSender name="udp" class="org.apache.synapse.transport.udp.UDPSender"/>
It should be noted that given its characteristics, UDP is not a suitable transport protocol for SOAP, except maybe in very particular circumstances. Indeed, UDP is an unreliable protocol:
  • There is no delivery guarantee, i.e. packets may be lost.
  • Messages may arrive out of order.
  • Messages may be duplicated, i.e. delivered twice.
However the unit tests show an example of how to use this transport with SOAP and WS-Addressing to achieve two-way asynchronous communication. Note that the transport has not been designed to implement the SOAP over UDP specification and will probably not be interoperable.

The main purpose of this transport implementation is to integrate Axis (and in particular Synapse) with existing UDP based protocols. See org.apache.synapse.format.syslog for an example of this kind of protocol.

Known issues and limitations

  • Packets longer than the configured maximum packet size are silently truncated. Packet truncation should be detected and trigger an error.
  • The listener doesn't implement all management operations specified by org.apache.synapse.transport.base.ManagementSupport.
  • The listener assumes that services are bound to unique UDP ports and predispatches incoming requests based on port numbers. When SOAP with WS-Addressing is used, the packets could be received on a single port and dispatched based on the To header. This is not supported.
  • It might be useful to allow configuration of the content type at the transport level rather than the service level. In this case, the contentType parameter would not be included in the endpoint reference. This is necessary for interoperability with the SOAP over UDP standard.
  • Technically, it would be quite easy to support binding several UDP ports to the same service. However, the way endpoints are configured at the service level doesn't allow this for the moment. Indeed, using simple text properties only allows to specify the configuration of a single endpoint.
  • The transport sender uses a randomly chosen UDP source port. Some UDP based services may check the source port and discard the packet. Also, in two-way communication scenarios, stateful firewalls will not be able to correlate the exchanged packets and may drop some of them.