org.jgroups.protocols

## Class UDP

- java.lang.Object
- - org.jgroups.stack.Protocol
  - - org.jgroups.protocols.TP
    - - org.jgroups.protocols.UDP

    public class UDP
    extends TP

IP multicast transport based on UDP. Messages to the group (msg.dest == null) will be multicast (to all group members), whereas point-to-point messages (msg.dest != null) will be unicast to a single member. Uses a multicast and a unicast socket.

The following properties are read by the UDP protocol:

- param mcast_addr - the multicast address to use; default is 228.8.8.8.
- param mcast_port - (int) the port that the multicast is sent on; default is 7600
- param ip_mcast - (boolean) flag whether to use IP multicast; default is true.
- param ip_ttl - the default time-to-live for multicast packets sent out on this socket; default is 32.
- param use_packet_handler - boolean, defaults to false. If set, the mcast and ucast receiver threads just put the datagram's payload (a byte buffer) into a queue, from where a separate thread will dequeue and handle them (unmarshal and pass up). This frees the receiver threads from having to do message unmarshalling; this time can now be spent receiving packets. If you have lots of retransmissions because of network input buffer overflow, consider setting this property to true.

Author:
  Bela Ban

### Nested Class Summary

Nested Classes
`class` `UDP.PacketReceiver`

### Nested classes/interfaces inherited from class org.jgroups.protocols.TP

`TP.Bundler, TP.DiagnosticsHandler, TP.ProbeHandler, TP.ProtocolAdapter`

### Field Summary

Fields
`protected boolean` `disable_loopback`
`protected boolean` `ip_mcast`
`protected int` `ip_ttl`
`protected IpAddress` `mcast_addr` The multicast address (mcast address and port) this member uses
`protected java.net.InetAddress` `mcast_group_addr`
`protected int` `mcast_port`
`protected UDP.PacketReceiver` `mcast_receiver` Runnable to receive multicast packets
`protected int` `mcast_recv_buf_size`
`protected int` `mcast_send_buf_size`
`protected java.net.MulticastSocket` `mcast_sock` IP multicast socket for receiving multicast packets
`protected java.net.DatagramSocket` `sock` Socket used for sending unicast and multicast packets and receiving unicast packets The address of this socket will be our local address (`local_addr`)
`protected int` `tos` Traffic class for sending unicast and multicast datagrams.
`protected UDP.PacketReceiver` `ucast_receiver` Runnable to receive unicast packets
`protected int` `ucast_recv_buf_size`
`protected int` `ucast_send_buf_size`

### Fields inherited from class org.jgroups.protocols.TP

`bind_addr, bind_interface_str, bind_port, bundler, bundler_capacity, bundler_type, can_bind_to_mcast_addr, channel_name, connect_count, connectLock, default_thread_factory, diag_handler, diagnostics_addr, diagnostics_port, discard_incompatible_packets, enable_bundling, enable_diagnostics, enable_unicast_bundling, f, global_thread_factory, header, last_discovery_request, LIST, local_addr, log_discard_msgs, logical_addr_cache, logical_addr_cache_expiration, logical_addr_cache_max_size, loopback, max_bundle_size, max_bundle_timeout, members, MULTICAST, num_bytes_received, num_bytes_sent, num_incoming_msgs_received, num_msgs_received, num_msgs_sent, num_oob_msgs_received, OOB, oob_thread_factory, oob_thread_pool, oob_thread_pool_enabled, oob_thread_pool_keep_alive_time, oob_thread_pool_max_threads, oob_thread_pool_min_threads, oob_thread_pool_queue, oob_thread_pool_queue_enabled, oob_thread_pool_queue_max_size, pool_thread_group, port_range, preregistered_probe_handlers, print_function, receive_interfaces, receive_on_all_interfaces, singleton_name, socket_factory, thread_naming_pattern, thread_pool, thread_pool_enabled, thread_pool_keep_alive_time, thread_pool_max_threads, thread_pool_min_threads, thread_pool_queue, thread_pool_queue_enabled, thread_pool_queue_max_size, thread_pool_rejection_policy, tick_time, timer, timer_keep_alive_time, timer_max_threads, timer_min_threads, timer_queue_max_size, timer_thread_factory, timer_type, up_prots, wheel_size, who_has_cache`

### Fields inherited from class org.jgroups.stack.Protocol

`down_prot, ergonomics, id, log, name, stack, stats, up_prot`

### Constructor Summary

Constructors
Constructor and Description
`UDP()` Creates the UDP protocol, and initializes the state variables, does however not start any sockets or threads.

### Method Summary

Methods
`protected void` `_send(java.net.InetAddress dest, int port, boolean mcast, byte[] data, int offset, int length)`
`protected void` `bindToInterfaces(java.util.List<java.net.NetworkInterface> interfaces, java.net.MulticastSocket s, java.net.InetAddress mcastAddr)`
`protected void` `closeUnicastSocket()`
`protected java.net.DatagramSocket` `createDatagramSocketWithBindPort()` Creates a DatagramSocket when bind_port > 0.
`protected java.net.DatagramSocket` `createEphemeralDatagramSocket()` Creates a DatagramSocket with a random port.
`protected IpAddress` `createLocalAddress()`
`protected void` `createSockets()` Create UDP sender and receiver sockets.
`void` `destroy()` This method is called on a `Channel.close()`.
`protected void` `destroySockets()`
`protected java.lang.String` `dumpSocketInfo()`
`java.lang.String` `getInfo()`
`java.net.InetAddress` `getMulticastAddress()`
`int` `getMulticastPort()`
`int` `getMulticastTTL()` Getter for current multicast TTL
`protected PhysicalAddress` `getPhysicalAddress()`
`protected void` `handleConfigEvent(java.util.Map<java.lang.String,java.lang.Object> map)`
`protected void` `handleConnect()`
`protected void` `handleDisconnect()`
`void` `sendMulticast(byte[] data, int offset, int length)` Send to all members in the group.
`void` `sendUnicast(PhysicalAddress dest, byte[] data, int offset, int length)` Send a unicast to 1 member.
`protected void` `setBufferSize(java.net.DatagramSocket sock, int send_buf_size, int recv_buf_size)`
`void` `setMcastPort(int mcast_port)`
`void` `setMulticastAddress(java.net.InetAddress addr)`
`void` `setMulticastPort(int mcast_port)`
`void` `setMulticastTTL(int ttl)` Set the ttl for multicast socket
`void` `start()` Creates the unicast and multicast sockets and starts the unicast and multicast receiver threads
`void` `stop()` This method is called on a `Channel.disconnect()`.
`boolean` `supportsMulticasting()` Whether or not hardware multicasting is supported

### Methods inherited from class org.jgroups.protocols.TP

`addPhysicalAddressToCache, clearLogicalAddressCache, createThreadPool, dispatchToThreadPool, doSend, down, dumpTimerTasks, evictLogicalAddressCache, fetchLocalAddresses, getBindAddress, getBindAddressAsInetAddress, getBindPort, getBindToAllInterfaces, getBundlerBufferSize, getDefaultThreadPool, getDefaultThreadPoolThreadFactory, getLogDiscardMessages, getMaxBundleSize, getMaxBundleTimeout, getNumBytesReceived, getNumBytesSent, getNumMessagesReceived, getNumMessagesSent, getNumTimerTasks, getOOBMaxQueueSize, getOOBMessages, getOOBPoolSize, getOOBQueueSize, getOOBThreadPool, getOOBThreadPoolKeepAliveTime, getOOBThreadPoolMaxThreads, getOOBThreadPoolMinThreads, getOOBThreadPoolThreadFactory, getPhysicalAddressFromCache, getPoolThreadGroup, getPortRange, getReceiveInterfaces, getRegularMaxQueueSize, getRegularMessages, getRegularPoolSize, getRegularQueueSize, getSendInterfaces, getSingletonName, getSocketFactory, getThreadFactory, getThreadNamingPattern, getThreadPoolKeepAliveTime, getThreadPoolMaxThreads, getThreadPoolMinThreads, getTimer, getTimerClass, getTimerKeepAliveTime, getTimerMaxThreads, getTimerMinThreads, getTimerQueueSize, getTimerThreadFactory, getTimerThreads, getUpProtocols, handleDownEvent, init, isDefaulThreadPoolEnabled, isDiscardIncompatiblePackets, isEnableBundling, isEnableUnicastBundling, isLoopback, isOOBThreadPoolEnabled, isReceiveOnAllInterfaces, isSendOnAllInterfaces, isSingleton, isUseIncomingPacketHandler, parseRejectionPolicy, passMessageUp, passToAllUpProtocols, printLogicalAddressCache, readMessage, readMessageList, receive, registerLocalAddress, registerProbeHandler, removeLogicalAddressFromCache, resetStats, send, sendToAllPhysicalAddresses, sendToSingleMember, setBindAddress, setBindPort, setBindToAllInterfaces, setDefaultThreadPool, setDefaultThreadPoolThreadFactory, setDiscardIncompatiblePackets, setEnableBundling, setEnableUnicastBundling, setInAllThreadFactories, setLogDiscardMessages, setLoopback, setMaxBundleSize, setMaxBundleTimeout, setOOBRejectionPolicy, setOOBThreadPool, setOOBThreadPoolKeepAliveTime, setOOBThreadPoolMaxThreads, setOOBThreadPoolMinThreads, setOOBThreadPoolThreadFactory, setPortRange, setRegularRejectionPolicy, setSocketFactory, setSourceAddress, setThreadFactory, setThreadNames, setThreadPoolKeepAliveTime, setThreadPoolMaxThreads, setThreadPoolMinThreads, setThreadPoolQueueEnabled, setTimerKeepAliveTime, setTimerMaxThreads, setTimerMinThreads, setTimerThreadFactory, setUseConcurrentStack, shutdownThreadPool, toString, unregisterProbeHandler, unsetThreadNames, up, verifyRejectionPolicy, writeMessage, writeMessageList`

### Methods inherited from class org.jgroups.stack.Protocol

`downThreadEnabled, dumpStats, enableStats, getConfigurableObjects, getDownProtocol, getId, getLevel, getName, getProperties, getProtocolStack, getTransport, getUpProtocol, getValue, isErgonomics, printStats, providedDownServices, providedUpServices, requiredDownServices, requiredUpServices, setDownProtocol, setErgonomics, setId, setLevel, setProperties, setPropertiesInternal, setProperty, setProtocolStack, setUpProtocol, setValue, setValues, statsEnabled, upThreadEnabled`

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

### Field Detail

#### tos

    protected int tos

Traffic class for sending unicast and multicast datagrams. Valid values are (check `DatagramSocket.setTrafficClass(int)` ); for details):

- `IPTOS_LOWCOST (0x02)`, decimal 2
- `IPTOS_RELIABILITY (0x04)`<, decimal 4/LI>
- `IPTOS_THROUGHPUT (0x08)`, decimal 8
- `IPTOS_LOWDELAY (0x10)`, decimal 16

#### mcast_group_addr

    protected java.net.InetAddress mcast_group_addr

#### mcast_port

    protected int mcast_port

#### ip_mcast

    protected boolean ip_mcast

#### ip_ttl

    protected int ip_ttl

#### mcast_send_buf_size

    protected int mcast_send_buf_size

#### mcast_recv_buf_size

    protected int mcast_recv_buf_size

#### ucast_send_buf_size

    protected int ucast_send_buf_size

#### ucast_recv_buf_size

    protected int ucast_recv_buf_size

#### disable_loopback

    protected boolean disable_loopback

#### mcast_addr

    protected IpAddress mcast_addr

The multicast address (mcast address and port) this member uses

#### sock

    protected java.net.DatagramSocket sock

Socket used for

1. sending unicast and multicast packets and
2. receiving unicast packets

The address of this socket will be our local address (`local_addr`)

#### mcast_sock

    protected java.net.MulticastSocket mcast_sock

IP multicast socket for receiving multicast packets

#### mcast_receiver

    protected UDP.PacketReceiver mcast_receiver

Runnable to receive multicast packets

#### ucast_receiver

    protected UDP.PacketReceiver ucast_receiver

Runnable to receive unicast packets

### Constructor Detail

#### UDP

    public UDP()

Creates the UDP protocol, and initializes the state variables, does however not start any sockets or threads.

### Method Detail

#### supportsMulticasting

    public boolean supportsMulticasting()

Description copied from class: `TP`
Whether or not hardware multicasting is supported

Specified by:
  `supportsMulticasting` in class `TP`

#### setMulticastAddress

    public void setMulticastAddress(java.net.InetAddress addr)

#### getMulticastAddress

    public java.net.InetAddress getMulticastAddress()

#### getMulticastPort

    public int getMulticastPort()

#### setMulticastPort

    public void setMulticastPort(int mcast_port)

#### setMcastPort

    public void setMcastPort(int mcast_port)

#### setMulticastTTL

    public void setMulticastTTL(int ttl)
                         throws java.io.IOException

Set the ttl for multicast socket

Parameters:
  `ttl` - the time to live for the socket.
Throws:
  `java.io.IOException`

#### getMulticastTTL

    public int getMulticastTTL()

Getter for current multicast TTL

Returns:

#### getInfo

    public java.lang.String getInfo()

Specified by:
  `getInfo` in class `TP`

#### sendMulticast

    public void sendMulticast(byte[] data,
                     int offset,
                     int length)
                       throws java.lang.Exception

Description copied from class: `TP`
Send to all members in the group. UDP would use an IP multicast message, whereas TCP would send N messages, one for each member

Specified by:
  `sendMulticast` in class `TP`
Parameters:
  `data` - The data to be sent. This is not a copy, so don't modify it
Throws:
  `java.lang.Exception`

#### sendUnicast

    public void sendUnicast(PhysicalAddress dest,
                   byte[] data,
                   int offset,
                   int length)
                     throws java.lang.Exception

Description copied from class: `TP`
Send a unicast to 1 member. Note that the destination address is a *physical*, not a logical address

Specified by:
  `sendUnicast` in class `TP`
Parameters:
  `dest` - Must be a non-null unicast address
  `data` - The data to be sent. This is not a copy, so don't modify it
Throws:
  `java.lang.Exception`

#### _send

    protected void _send(java.net.InetAddress dest,
             int port,
             boolean mcast,
             byte[] data,
             int offset,
             int length)
                  throws java.lang.Exception

Throws:
  `java.lang.Exception`

#### start

    public void start()
               throws java.lang.Exception

Creates the unicast and multicast sockets and starts the unicast and multicast receiver threads

Overrides:
  `start` in class `TP`
Throws:
  `java.lang.Exception` - Thrown if protocol cannot be started successfully. This will cause the ProtocolStack to fail, so `Channel.connect(String)` will throw an exception

#### stop

    public void stop()

Description copied from class: `Protocol`
This method is called on a `Channel.disconnect()`. Stops work (e.g. by closing multicast socket). Will be called from top to bottom. This means that at the time of the method invocation the neighbor protocol below is still working. This method will replace the STOP, STOP_OK, CLEANUP and CLEANUP_OK events. The ProtocolStack guarantees that when this method is called all messages in the down queue will have been flushed

Overrides:
  `stop` in class `TP`

#### destroy

    public void destroy()

Description copied from class: `Protocol`
This method is called on a `Channel.close()`. Does some cleanup; after the call the VM will terminate

Overrides:
  `destroy` in class `TP`

#### handleConnect

    protected void handleConnect()
                          throws java.lang.Exception

Overrides:
  `handleConnect` in class `TP`
Throws:
  `java.lang.Exception`

#### handleDisconnect

    protected void handleDisconnect()

Overrides:
  `handleDisconnect` in class `TP`

#### createSockets

    protected void createSockets()
                          throws java.lang.Exception

Create UDP sender and receiver sockets. Currently there are 2 sockets (sending and receiving). This is due to Linux's non-BSD compatibility in the JDK port (see DESIGN).

Throws:
  `java.lang.Exception`

#### destroySockets

    protected void destroySockets()

#### createLocalAddress

    protected IpAddress createLocalAddress()

#### getPhysicalAddress

    protected PhysicalAddress getPhysicalAddress()

Specified by:
  `getPhysicalAddress` in class `TP`

#### bindToInterfaces

    protected void bindToInterfaces(java.util.List<java.net.NetworkInterface> interfaces,
                        java.net.MulticastSocket s,
                        java.net.InetAddress mcastAddr)

Parameters:
  `interfaces` - List<NetworkInterface>. Guaranteed to have no duplicates
  `s` -
  `mcastAddr` -
Throws:
  `java.io.IOException`

#### createEphemeralDatagramSocket

    protected java.net.DatagramSocket createEphemeralDatagramSocket()
                                                             throws java.net.SocketException

Creates a DatagramSocket with a random port. Because in certain operating systems, ports are reused, we keep a list of the n last used ports, and avoid port reuse

Throws:
  `java.net.SocketException`

#### createDatagramSocketWithBindPort

    protected java.net.DatagramSocket createDatagramSocketWithBindPort()
                                                                throws java.lang.Exception

Creates a DatagramSocket when bind_port > 0. Attempts to allocate the socket with port == bind_port, and increments until it finds a valid port, or until port_range has been exceeded

Returns:
  DatagramSocket The newly created socket
Throws:
  `java.lang.Exception`

#### dumpSocketInfo

    protected java.lang.String dumpSocketInfo()
                                       throws java.lang.Exception

Throws:
  `java.lang.Exception`

#### setBufferSize

    protected void setBufferSize(java.net.DatagramSocket sock,
                     int send_buf_size,
                     int recv_buf_size)

#### closeUnicastSocket

    protected void closeUnicastSocket()

#### handleConfigEvent

    protected void handleConfigEvent(java.util.Map<java.lang.String,java.lang.Object> map)