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

  5. UDP Transport Reference

UDP Transport Reference

Mule Runtime Engine versions 3.5, 3.6, and 3.7 reached End of Life on or before January 25, 2020. For more information, contact your Customer Success Manager to determine how you can 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

Transport Doc Inbound Outbound Request Transactions Streaming Retries MEPs Default MEP Maven Artifact

UDP

JavaDoc
 SchemaDoc

check

check

check

error

check

error

one-way, request-response

request-response

org.mule.transport:mule-transport-udp

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.6/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"/> ❶

<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 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

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.

Child Elements of <connector…​>

Name Cardinality Description

Inbound endpoint

Attributes of <inbound-endpoint…​>

Name Type Required Default Description

host

string

no

port

port number

no

Child Elements of <inbound-endpoint…​>

Name Cardinality Description

Outbound endpoint

Attributes of <outbound-endpoint…​>

Name Type Required Default Description

host

string

no

port

port number

no

Child Elements of <outbound-endpoint…​>

Name Cardinality Description

Endpoint

Attributes of <endpoint…​>

Name Type Required Default Description

host

string

no

port

port number

no

Child Elements of <endpoint…​>

Name Cardinality Description

Schema

Namespace "http://www.mulesoft.org/schema/mule/udp"

Targeting Schemas (1):

mule-udp.xsd

Targeting Components:

4 global elements, 4 complexTypes, 1 attribute group

Schema Summary

mule-udp.xsd

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

connector

Type: udpConnectorType

Content: complex, 9 attributes, attr. wildcard, 6 elements

Subst.Gr: may substitute for element mule:abstract-connector

Defined: globally in mule-udp.xsd; see XML source

Used:never

endpoint

Type: globalEndpointType

Content: complex, 13 attributes, attr. wildcard, 16 elements

Subst.Gr: may substitute for element mule:abstract-global-endpoint

Defined: globally in mule-udp.xsd; see XML source

Used: never

inbound-endpoint

Type: inboundEndpointType

Content: complex, 13 attributes, attr. wildcard, 16 elements

Subst.Gr: may substitute for element mule:abstract-global-connector

Defined: globally in mule-udp.xsd; see XML source

Used: never

outbound-endpoint

Type: outboundEndpointType

Content: complex, 13 attributes, attr. wildcard, 16 elements

Subst.Gr: may substitute for element mule:abstract-outbound-endpoint

Defined: globally in mule-udp.xsd; see XML source

Used: never
Complex Type Summary

globalEndpointType

Content: complex, 13 attributes, attr. wildcard, 16 elements

Defined: globally in mule-udp.xsd; see XML source

Used: at 1 location

inboundEndpointType

Content: complex, 13 attributes, attr. wildcard, 16 elements

Defined: globally in mule-udp.xsd; see XML source

Used: at 1 location

outboundEndpointType

Content: complex, 13 attributes, attr. wildcard, 16 elements

Defined: globally in mule-udp.xsd; see XML source

Used: at 1 location

udpConnectorType

Content: complex, 9 attributes, attr. wildcard, 6 elements

Defined: globally in mule-udp.xsd; see XML source

Includes: definition of 5 attributes

Used: at 2 location
Attribute Group Summary

addressAttributes

Content: 2 attributes

Defined: globally in mule-udp.xsd; see XML source

Includes: definition of 2 attributes

Used: at 3 location

XML schema documentation generated with DocFlex/XML RE 1.8.5 using DocFlex/XML XSDDoc 2.5.0 template set. All content model diagrams generated by Altova XMLSpy via DocFlex/XML XMLSpy Integration.

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.6.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.