Java NIO DatagramChannel

1. Overview

In this tutorial, we'll explore the DatagramChannel class that allows us to send and receive UDP packets.

2. DatagramChannel

Among various protocols supported on the internet, TCP and UDP are the most common.

While TCP is a connection-oriented protocol, UDP is a datagram-oriented protocol that is highly performant and less reliable. UDP is often used in sending broadcast or multicast data transmissions due to its unreliable nature.

The DatagramChannel class of Java's NIO module provides a selectable channel for the datagram-oriented sockets. In other words, it allows creating a datagram channel to send and receive the datagrams (UDP packets).

Let's use the DatagramChannel class to create a client that sends the datagrams over the local IP address and a server that receives the datagram.

3. Open and Bind

First, let's create the DatagramChannelBuilder class with the openChannel method that provides an opened but unconnected datagram channel:

public class DatagramChannelBuilder {
    public static DatagramChannel openChannel() throws IOException {
        DatagramChannel datagramChannel = DatagramChannel.open();
        return datagramChannel;
    }
}

Then, we'll require to bind an opened channel to the local address for listening to the inbound UDP packets.

So, we'll add the bindChannel method that binds the DatagramChannel to the provided local address:

public static DatagramChannel bindChannel(SocketAddress local) throws IOException {
    return openChannel().bind(local); 
}

Now, we can use the DatagramChannelBuilder class to create the client/server that sends/receives the UDP packets on the configured socket address.

4. Client

First, let's create the DatagramClient class with the startClient method that uses the already discussed bindChannel method of the DatagramChannelBuilder class:

public class DatagramClient {
    public static DatagramChannel startClient() throws IOException {
        DatagramChannel client = DatagramChannelBuilder.bindChannel(null);
        return client;
    }
}

As the client doesn't require listening to the inbound UDP packets, we've provided a null value for the address while binding the channel.

Then, let's add the sendMessage method to send a datagram on the server address:

public static void sendMessage(DatagramChannel client, String msg, SocketAddress serverAddress) throws IOException {
    ByteBuffer buffer = ByteBuffer.wrap(msg.getBytes());
    client.send(buffer, serverAddress);
}

That's it! Now we're ready to send our message using the client:

DatagramChannel client = startClient();
String msg = "Hello, this is a Baeldung's DatagramChannel based UDP client!";
InetSocketAddress serverAddress = new InetSocketAddress("localhost", 7001);
sendMessage(client, msg, serverAddress);

Note: As we've sent our message to the localhost:7001 address, we must start our server using the same address.

5. Server

Similarly, let's create the DatagramServer class with the startServer method to start a server on the localhost:7001 address:

public class DatagramServer {
    public static DatagramChannel startServer() throws IOException {
        InetSocketAddress address = new InetSocketAddress("localhost", 7001);
        DatagramChannel server = DatagramChannelBuilder.bindChannel(address);
        System.out.println("Server started at #" + address);
        return server;
    }
}

Then, let's add the receiveMessage method that receives the datagrams from the client, extracts the message, and prints it:

public static void receiveMessage(DatagramChannel server) throws IOException {
    ByteBuffer buffer = ByteBuffer.allocate(1024);
    SocketAddress remoteAdd = server.receive(buffer);
    String message = extractMessage(buffer);
    System.out.println("Client at #" + remoteAdd + "  sent: " + message);
}

Also, to extract the client's message from the received buffer, we'll require to add the extractMessage method:

private static String extractMessage(ByteBuffer buffer) {
    buffer.flip();
    byte[] bytes = new byte[buffer.remaining()];
    buffer.get(bytes);
    String msg = new String(bytes);
    
    return msg;
}

Here, we've used the flip method on the ByteBuffer instance to flip it from reading from I/O to writing to I/O. Additionally, the flip method sets the limit to the current position and the position to zero to let us read from the beginning.

Now, we can start our server and receive a message from the client:

DatagramChannel server = startServer();
receiveMessage(server);

Therefore, the print output when the server receives our message will be:

Server started at #localhost/127.0.0.1:7001
Client at #/127.0.0.1:52580  sent: Hello, this is a Baeldung's DatagramChannel based UDP client!

6. DatagramChannelUnitTest

Now that we have both client and server ready, we can write a unit test to verify the end-to-end datagram (UDP packet) delivery:

@Test
public void whenClientSendsAndServerReceivesUDPPacket_thenCorrect() throws IOException {
    DatagramChannel server = DatagramServer.startServer();
    DatagramChannel client = DatagramClient.startClient();
    String msg1 = "Hello, this is a Baeldung's DatagramChannel based UDP client!";
    String msg2 = "Hi again!, Are you there!";
    InetSocketAddress serverAddress = new InetSocketAddress("localhost", 7001);
    
    DatagramClient.sendMessage(client, msg1, serverAddress);
    DatagramClient.sendMessage(client, msg2, serverAddress);
    
    assertEquals("Hello, this is a Baeldung's DatagramChannel based UDP client!", DatagramServer.receiveMessage(server));
    assertEquals("Hi again!, Are you there!", DatagramServer.receiveMessage(server));
}

First, we've started the server that binds the datagram channel to listen to the inbound message on localhost:7001. Then, we started the client and sent two messages.

Last, we received the inbound messages on the server and compared them with the messages we sent through the client.

7. Additional Methods

So far, we've used methods like open, bind, send, and receive provided by the DatagramChannel class. Now, let's quickly go through its other handy methods.

7.1. configureBlocking

By default, the datagram channel is blocking. We can use the configureBlocking method to make the channel non-blocking when passing the false value:

client.configureBlocking(false);

7.2. isConnected

The isConnected method returns the status of the datagram channel — that is, whether it's connected or disconnected.

7.3. socket

The socket method returns the object of the DatagramSocket class associated with the datagram channel.

7.4. close

Additionally, we can close the channel by calling the close method of the DatagramChannel class.

8. Conclusion

In this quick tutorial, we explored Java NIO's DatagramChannel class that allows the creation of a datagram channel to send/receive UDP packets.

First, we examined a few methods like open and bind that simultaneously allow the datagram channel to listen to the inbound UDP packets.

Then, we created a client and a server to explore the end-to-end UDP packet delivery using the DatagramChannel class.

As usual, the source code is available over on GitHub.