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

  5. UDP Transport Reference

UDP Transport Reference

Universal Datagram Protocol (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.

Transport Info

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

UDP

JavaDoc SchemaDoc

check

check

check

-

check

-

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.3/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 2 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, 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 will be received on inbound endpoints. The bytes in the datagram will become the message payload.

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

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

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.

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

Schema Summary

The VM transport is used for intra-VM communication between components managed by Mule.

Target Namespace:

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

Defined Components:

4 global elements, 4 Complex Type Summary, 1 attribute group

Default Namespace-Qualified Form:

Local Elements: qualified; Local Attributes: unqualified

Schema Location:

http://www.mulesoft.org/schema/mule/vm/3.3/mule-udp.xsd; see XML source

Imports Schemas (3):

mule-schemadoc.xsd, mule.xsd, xml.xsd

Imported by Schema (2):

_mule-all-included.xsd, -

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

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;

Includes:

definitions of 5 attributes

Used:

at 2 location

Attribute Group Summary

addressAttributes

Content:

2 attribute

Defined:

globally in mule-udp.xsd; see XML source

Includes:

definition of 2 attributes

Used:

at 3 locations

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