Module java.base
Package java.net

Class DatagramSocket

java.lang.Object
java.net.DatagramSocket
All Implemented Interfaces:
Closeable, AutoCloseable
Direct Known Subclasses:
MulticastSocket
public class DatagramSocket extends Object implements Closeable
This class represents a socket for sending and receiving datagram packets.

A datagram socket is the sending or receiving point for a packet delivery service. Each packet sent or received on a datagram socket is individually addressed and routed. Multiple packets sent from one machine to another may be routed differently, and may arrive in any order.

Where possible, a newly constructed DatagramSocket has the SO_BROADCAST socket option enabled so as to allow the transmission of broadcast datagrams. In order to receive broadcast packets a DatagramSocket should be bound to the wildcard address. In some implementations, broadcast packets may also be received when a DatagramSocket is bound to a more specific address.

Example: 


              DatagramSocket s = new DatagramSocket(null);
              s.bind(new InetSocketAddress(8888));
Which is equivalent to: 

              DatagramSocket s = new DatagramSocket(8888);
Both cases will create a DatagramSocket able to receive broadcasts on UDP port 8888.

The DatagramSocket class defines convenience methods to set and get several socket options. This class also defines the setOption and getOption methods to set and query socket options. A DatagramSocket supports the following socket options:

Socket options
Option Name Description
SO_SNDBUF The size of the socket send buffer in bytes
SO_RCVBUF The size of the socket receive buffer in bytes
SO_REUSEADDR Re-use address
SO_BROADCAST Allow transmission of broadcast datagrams
IP_TOS The Type of Service (ToS) octet in the Internet Protocol (IP) header

In addition, the DatagramSocket class defines methods to join and leave a multicast group, and supports multicast options which are useful when joining, leaving, or sending datagrams to a multicast group. The following multicast options are supported:

Multicast options
Option Name Description
IP_MULTICAST_IF The network interface for Internet Protocol (IP) multicast datagrams
IP_MULTICAST_TTL The time-to-live for Internet Protocol (IP) multicast datagrams
IP_MULTICAST_LOOP Loopback for Internet Protocol (IP) multicast datagrams
An implementation may also support additional options.

API Note:
Multicasting with DatagramSocket

DatagramChannel implements the MulticastChannel interface and provides an alternative API for sending and receiving multicast datagrams. The MulticastChannel API supports both any-source and source-specific multicast. Consider using DatagramChannel for multicasting.

DatagramSocket can be used directly for multicasting. However, contrarily to MulticastSocket, DatagramSocket doesn't call the setReuseAddress(boolean) method to enable the SO_REUSEADDR socket option by default. If creating a DatagramSocket intended to later join a multicast group, the caller should consider explicitly enabling the SO_REUSEADDR option.

An instance of DatagramSocket can be used to send or receive multicast datagram packets. It is not necessary to join a multicast group in order to send multicast datagrams. Before sending out multicast datagram packets however, the default outgoing interface for sending multicast datagram should first be configured using setOption and StandardSocketOptions.IP_MULTICAST_IF: 


    DatagramSocket sender = new DatagramSocket(new InetSocketAddress(0));
    NetworkInterface outgoingIf = NetworkInterface.getByName("en0");
    sender.setOption(StandardSocketOptions.IP_MULTICAST_IF, outgoingIf);

    // optionally configure multicast TTL; the TTL defines the scope of a
    // multicast datagram, for example, confining it to host local (0) or
    // link local (1) etc...
    int ttl = ...; // a number between 0 and 255
    sender.setOption(StandardSocketOptions.IP_MULTICAST_TTL, ttl);

    // send a packet to a multicast group
    byte[] msgBytes = ...;
    InetAddress mcastaddr = InetAddress.getByName("228.5.6.7");
    int port = 6789;
    InetSocketAddress dest = new InetSocketAddress(mcastaddr, port);
    DatagramPacket hi = new DatagramPacket(msgBytes, msgBytes.length, dest);
    sender.send(hi);

An instance of DatagramSocket can also be used to receive multicast datagram packets. A DatagramSocket that is created with the intent of receiving multicast datagrams should be created unbound. Before binding the socket, setReuseAddress(true) should be configured: 


    DatagramSocket socket = new DatagramSocket(null); // unbound
    socket.setReuseAddress(true); // set reuse address before binding
    socket.bind(new InetSocketAddress(6789)); // bind

    // joinGroup 228.5.6.7
    InetAddress mcastaddr = InetAddress.getByName("228.5.6.7");
    InetSocketAddress group = new InetSocketAddress(mcastaddr, 0);
    NetworkInterface netIf = NetworkInterface.getByName("en0");
    socket.joinGroup(group, netIf);
    byte[] msgBytes = new byte[1024]; // up to 1024 bytes
    DatagramPacket packet = new DatagramPacket(msgBytes, msgBytes.length);
    socket.receive(packet);
    ....
    // eventually leave group
    socket.leaveGroup(group, netIf);

Platform dependencies

The multicast implementation is intended to map directly to the native multicasting facility. Consequently, the following items should be considered when developing an application that receives IP multicast datagrams:

  1. Contrarily to DatagramChannel, the constructors of DatagramSocket do not allow to specify the ProtocolFamily of the underlying socket. Consequently, the protocol family of the underlying socket may not correspond to the protocol family of the multicast groups that the DatagramSocket will attempt to join.
    There is no guarantee that a DatagramSocket with an underlying socket created in one protocol family can join and receive multicast datagrams when the address of the multicast group corresponds to another protocol family. For example, it is implementation specific if a DatagramSocket to an IPv6 socket can join an IPv4 multicast group and receive multicast datagrams sent to the group.
  2. Before joining a multicast group, the DatagramSocket should be bound to the wildcard address. If the socket is bound to a specific address, rather than the wildcard address then it is implementation specific if multicast datagrams are received by the socket.
  3. The SO_REUSEADDR option should be enabled prior to binding the socket. This is required to allow multiple members of the group to bind to the same address.

Since:
1.0
See Also: