Contact Us 1-800-596-4880
  1. Homepage
  2. Mule Runtime (3.2)
  3. Reference Materials for Mule ESB 3
  4. = Reference Materials for Mule ESB 3

  5. UDP Transport Reference

UDP Module Reference

Introduction

Universal Datagram Protocol, or UDP, is a stateless protocol for sending or receiving large numbers of messages (datagrams) quickly. The UDP transport in Mule allow sending messages to or receiving messages with Mule using UDP sockets.

Namespace and Syntax

XML namespace:

xmlns:udp="http://www.mulesoft.org/schema/mule/udp"

XML schema location:

http://www.mulesoft.org/schema/mule/udp  http://www.mulesoft.org/schema/mule/udp/3.2/mule-udp.xsd

Schema Structure

Connector syntax:

<udp:connector name="udpConnector" receiveBufferSize="1024" sendBufferSize="1024"
               timeout="0" keepSendSocketOpen="false" broadcast="false"/>

Endpoint syntax:
You can define your endpoints two ways:

  1. Prefixed endpoint:

    <udp:inbound-endpoint host="localhost" port="65433"/>

  2. Non-prefixed URI:

    <inbound-endpoint address="udp://localhost:65433"/>

See the sections below for more information.

Considerations

UDP is one of the standard communication protocols used on the Internet, and supports communication both across the internet and within a local area network. The Mule UDP module uses native Java socket support, adding no communication overhead to the classes in java.net, while allowing many of the advanced features of UDP programming to be specified in the Mule configuration rather than coded in Java.

Use this transport when communicating using low-level UDP datagrams. UDP is designed to maximize speed and scale over reliability, ordering or data integrity. UDP datagrams are not guaranteed to arrive with any particular speed, or at all, and they may arrive in a different order than they are sent in. If any of these guarantees are important to your application, use a different transport, such as [TCP].

Note: UDP provides no error checking, so you may want to perform additional validation or error handling in your application, if it is important.

As shown in the examples below, the UDP transport can be used to

  • Send messages to a UDP socket

  • Read messages from a UDP socket

Features

The UDP module allows a Mule application both to send and receive UDP datagrams, and to declaratively customize the following features of UDP (with the standard name for each feature, where applicable):

  • The timeout for sending or receiving messages (SO_TIMEOUT).

  • Whether to allow sending broadcast messages (SO_BROADCAST).

  • Whether to close a socket after sending a message.

  • The maximum size of messages that can be received.

UDP endpoints can be used in one of two ways:

  • To receive a UDP datagram, create an inbound UDP endpoint.

  • To send a UDP datagram, create an outbound UDP endpoint.

Usage

To use UDP endpoints

  1. Add the MULE UDP namespace to your configuration:

  2. Define one or more connectors for UDP endpoints.

    • Create a UDP connector:

      <udp:connector name="udpConnector"/>

  3. Create UDP endpoints.

    • Datagrams are received on inbound endpoints. The bytes in the datagram become the message payload.

    • Datagrams are sent to outbound endpoints. The bytes in the message payload become the datagram.

    • Both kinds of endpoints are identified by a host name and a port.

NOTE:UDP endpoints are always one-way.

Example Configurations

Copy datagrams from one port to another

<udp:connector name="connector"/> ❶

<flow name="copy">
    <udp:inbound-endpoint host="localhost" port="4444" exchange-pattern="one-way"/> ❷
    <udp:outbound-endpoint host="remote" port="5555" exchange-pattern="one-way" /> ❸
</flow>

The connector at ❶ uses all default properties. The inbound endpoint at ❷ receives datagrams and copies them to the outbound endpoint at ❸.

Configuration Options

UDP Connector attributes

Name Description Default

broadcast

set this to true to allow sending to broadcast ports

false

keepSendSocketOpen

Whether to keep the the socket open after sending a message

false

receiveBufferSize

This is the size of the largest (in bytes) datagram that can be received.

16 Kbytes

sendBufferSize

The size of the network send buffer

16 Kbytes

timeout

the timeout used for both sending and receiving

system default

Configuration Reference

Element Listing

UDP Transport

The UDP transport enables events to be sent and received as Datagram packets.

Connector

Attributes of <connector…​>

Name Type Required Default Description

receiveBufferSize

integer

no

The size of the receiving buffer for the socket.

timeout

long

no

The amount of time after which a Send or Receive call will time out.

sendBufferSize

integer

no

The size of the sending buffer for the socket.

broadcast

boolean

no

Whether to enable the socket to send broadcast data.

keepSendSocketOpen

boolean

no

Whether to keep the Sending socket open.

No Child Elements of <connector…​>

Inbound endpoint

Attributes of <inbound-endpoint…​>

Name Type Required Default Description

host

string

no

port

port number

no

No Child Elements of <inbound-endpoint…​>

Outbound endpoint

Attributes of <outbound-endpoint…​>

Name Type Required Default Description

host

string

no

port

port number

no

No Child Elements of <outbound-endpoint…​>

Endpoint

Attributes of <endpoint…​>

Name Type Required Default Description

host

string

no

port

port number

no

No Child Elements of <endpoint…​>

Schema

Javadoc API Reference

The Javadoc for this module can be found here: UDP

Maven

The UDP Module can be included with the following dependency:

<dependency>
  <groupId>org.mule.transports</groupId>
  <artifactId>mule-transport-udp</artifactId>
  <version>3.2.0</version>
</dependency>

Notes

Before Mule 3.1.1, there were two different attributes for setting timeout on UDP connectors, sendTimeout and receiveTimeout. It was necessary to set them to the same value.