Listener configuration

The UDP transport listener is configured in axis2.xml using the following declaration:

<transportReceiver name="udp" class="org.apache.axis2.transport.udp.UDPListener"/>

Depending on how the UDP transport is set up, additional parameters may be required inside the transportReceiver element (see next section).

Endpoint configuration

Endpoints can be configured both at the transport level and at the service level. Each endpoint opens a local UDP port for listening. UDP packets received on a port that is configured on a service will be pre-dispatched to that service. Packets received by a port that is configured at the transport level need to be dispatched using WS-Addressing or some other mechanism implemented by a dispatcher configured in Axis2.

Endpoints are configured by adding parameter elements to the transportReceiver element in axis2.xml or to a service element in an services.xml file. The set of parameters is the same for both scenarios:

transport.udp.port (required)

Specifies the UDP port to bind to.

transport.udp.contentType (required)

Specifies the content type of the messages received on the endpoint. This parameter is necessary because in contrast to HTTP, the content type information is not part of the information exchanged on the wire.

transport.udp.maxPacketSize (optional, defaults to 1024)

The maximum UDP packet size.

Enabling SOAP over UDP at the transport level

The following declaration in axis2.xml enables SOAP over UDP on port 3333 and allows all services (for which UDP is in the list of exposed transports) to receive messages over that port:

<transportReceiver name="udp" class="org.apache.axis2.transport.udp.UDPListener">
  <parameter name="transport.udp.port">3333</parameter>
  <parameter name="transport.udp.contentType">text/xml</parameter>
  <parameter name="transport.udp.maxPacketSize">4096</parameter>
</transportReceiver>

For this to work, WS-Addressing must be enabled, and messages sent to port 3333 must have the relevant WS-Addressing headers.

<module ref="addressing"/>

With the configuration shown above, the UDP transport would generate bindings with the following EPR:

udp://localhost:3333/axis2/services/Version?contentType=text/xml

The following example shows a message that can be sent to the Version service over UDP:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
                   xmlns:wsa="http://www.w3.org/2005/08/addressing">
    <SOAP-ENV:Header>
        <wsa:MessageID>1234</wsa:MessageID>
        <wsa:To>udp://localhost:3333/axis2/services/Version?contentType=text/xml</wsa:To>
        <wsa:Action>urn:getVersion</wsa:Action>
    </SOAP-ENV:Header>
    <SOAP-ENV:Body>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

On most Linux/Unix systems (including Mac OS X), the nc utility is available to send UDP messages and can be used to test the transport. To do this, save the message into test-message.xml and execute the following command:

nc -u 127.0.0.1 3333 < test-message.xml