Contact Us 1-800-596-4880
  1. Homepage
  2. Mule Runtime (3.8)
  3. Reference
  4. Transports Reference

  5. UDP Transport Reference

UDP Transport Reference

Mule runtime engine version 3.8 reached its End of Life on November 16, 2021. For more information, contact your Customer Success Manager to determine how to migrate to the latest Mule version.

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

Transport Info

Feature Value Description

Transport

UDP

The name/protocol of the transport

Doc

JavaDoc, SchemaDoc

Links to the JavaDoc and SchemaDoc for the transport

Inbound

check

Whether the transport can receive inbound events and can be used for an inbound endpoint.

Outbound

check

Whether the transport can produce outbound events and be used with an outbound endpoint.

Request

check

Whether this endpoint can be queried directly with a request call (via MuleClient or the EventContext)

Transactions

error

Whether transactions are supported by the transport. Transports that support transactions can be configured in either local or distributed two-phase commit (XA) transaction.

Streaming

check

Whether this transport can process messages that come in on an input stream. This allows for very efficient processing of large data. For more information, see Streaming.

Retries

error

Whether this transport supports retry policies. Note that all transports can be configured with Retry policies, but only the ones marked here are officially supported by MuleSoft.

MEPs

one-way, request-response

Message Exchange Patterns supported by this transport.

Default MEP

request-response

The default MEP for endpoints that use this transport that do not explicitly configure a MEP.

Maven Artifact

org.mule.transport:mule-transport-udp

The group name a artifact name for this transport in Maven

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.8/mule-udp.xsd

Connector syntax:

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

Endpoint syntax:

You can define your endpoints two different 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, you can use the UDP transport 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"/> (1)

<flow name="copy">
    <udp:inbound-endpoint host="localhost" port="4444" exchange-pattern="one-way"/> (2)
    <udp:outbound-endpoint host="remote" port="5555" exchange-pattern="one-way" /> (3)
</flow>
1 The connector uses all default properties.
2 The inbound endpoint receives datagrams.
3 The connector copies the datagrams to the outbound endpoint.

Configuration Options

UDP connector attributes:

Name Description Default

broadcast

Set to true to allow sending to broadcast ports

false

keepSendSocketOpen

Whether to keep the the socket open after sending a message

false

receiveBufferSize

Size of the largest (in bytes) datagram that can be received.

16 Kbytes

sendBufferSize

Size of the network send buffer

16 Kbytes

timeout

Timeout used for both sending and receiving

system default

UDP Transport Configuration Reference

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

Connector

Attributes of <connector…​>

Name Description

receiveBufferSize

The size of the receiving buffer for the socket.

Type: integer
Required: no
Default: none

timeout

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

Type: long
Required: no
Default: none

sendBufferSize

The size of the sending buffer for the socket.

Type: integer
Required: no
Default: none

broadcast

Whether to enable the socket to send broadcast data.

Type: boolean
Required: no
Default: none

keepSendSocketOpen

Whether to keep the Sending socket open.

Type: boolean
Required: no
Default: none

No Child Elements of <connector…​>

Inbound Endpoint

Attributes of <inbound-endpoint…​>

Name Type Require Default Description

host

string

no

port

port number

no

No Child Elements of <inbound-endpoint…​>

Outbound Endpoint

Attributes of <outbound-endpoint…​>

Name Type Require Default Description

host

string

no

port

port number

no

No Child Elements of <outbound-endpoint…​>

Endpoint

Attributes of <endpoint…​>

Name Type Require Default Description

host

string

no

port

port number

no

No Child Elements of <endpoint…​>

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.8.1</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.