Skip to content

Most visited

Recently visited

navigation
Added in API level 1

DatagramChannel

public abstract class DatagramChannel
extends AbstractSelectableChannel implements ByteChannel, ScatteringByteChannel, GatheringByteChannel

java.lang.Object
   ↳ java.nio.channels.spi.AbstractInterruptibleChannel
     ↳ java.nio.channels.SelectableChannel
       ↳ java.nio.channels.spi.AbstractSelectableChannel
         ↳ java.nio.channels.DatagramChannel


A DatagramChannel is a selectable channel that represents a partial abstraction of a datagram socket. The socket method of this class can return the related DatagramSocket instance, which can handle the socket.

A datagram channel is open but not connected when created with the open() method. After it is connected, it will keep the connected status until it is disconnected or closed. The benefit of a connected channel is the reduced effort of security checks during send and receive. When invoking read or write, a connected channel is required.

Datagram channels are thread-safe; only one thread can read or write at the same time.

Summary

Protected constructors

DatagramChannel(SelectorProvider selectorProvider)

Constructs a new DatagramChannel.

Public methods

abstract DatagramChannel connect(SocketAddress address)

Connects the socket of this channel to a remote address, which is the only communication peer for getting and sending datagrams after being connected.

abstract DatagramChannel disconnect()

Disconnects the socket of this channel, which has been connected before in order to send and receive datagrams.

abstract boolean isConnected()

Returns whether this channel's socket is connected or not.

static DatagramChannel open()

Creates an opened and not-connected datagram channel.

abstract int read(ByteBuffer target)

Reads a datagram from this channel into the byte buffer.

abstract long read(ByteBuffer[] targets, int offset, int length)

Reads a datagram from this channel into an array of byte buffers.

final long read(ByteBuffer[] targets)

Reads a datagram from this channel into an array of byte buffers.

abstract SocketAddress receive(ByteBuffer target)

Gets a datagram from this channel.

abstract int send(ByteBuffer source, SocketAddress address)

Sends a datagram through this channel.

abstract DatagramSocket socket()

Returns the related datagram socket of this channel, which does not define additional public methods to those defined by DatagramSocket.

final int validOps()

Gets the valid operations of this channel.

abstract long write(ByteBuffer[] sources, int offset, int length)

Writes a datagram from the byte buffers to this channel.

abstract int write(ByteBuffer source)

Writes a datagram from the byte buffer to this channel.

final long write(ByteBuffer[] sources)

Writes a datagram from the byte buffers to this channel.

Inherited methods

From class java.nio.channels.spi.AbstractSelectableChannel
From class java.nio.channels.SelectableChannel
From class java.nio.channels.spi.AbstractInterruptibleChannel
From class java.lang.Object
From interface java.nio.channels.Channel
From interface java.nio.channels.InterruptibleChannel
From interface java.nio.channels.ScatteringByteChannel
From interface java.nio.channels.GatheringByteChannel
From interface java.io.Closeable
From interface java.nio.channels.ReadableByteChannel
From interface java.nio.channels.WritableByteChannel
From interface java.lang.AutoCloseable

Protected constructors

DatagramChannel

Added in API level 1
DatagramChannel (SelectorProvider selectorProvider)

Constructs a new DatagramChannel.

Parameters
selectorProvider SelectorProvider: an instance of SelectorProvider.

Public methods

connect

Added in API level 1
DatagramChannel connect (SocketAddress address)

Connects the socket of this channel to a remote address, which is the only communication peer for getting and sending datagrams after being connected.

This method can be called at any time without affecting the read and write operations being processed at the time the method is called. The connection status does not change until the channel is disconnected or closed.

This method executes the same security checks as the connect method of the DatagramSocket class.

Parameters
address SocketAddress: the address to be connected to.
Returns
DatagramChannel this channel.
Throws
ClosedChannelException if the channel is already closed.
AsynchronousCloseException if the channel is closed by another thread while this method is in operation.
ClosedByInterruptException if another thread interrupts the calling thread while the operation is in progress. The calling thread will have the interrupt state set and the channel will be closed.
IOException if some other I/O error occurs.

disconnect

Added in API level 1
DatagramChannel disconnect ()

Disconnects the socket of this channel, which has been connected before in order to send and receive datagrams.

This method can be called at any time without affecting the read and write operations being underway. It does not have any effect if the socket is not connected or the channel is closed.

Returns
DatagramChannel this channel.
Throws
IOException some other I/O error occurs.

isConnected

Added in API level 1
boolean isConnected ()

Returns whether this channel's socket is connected or not.

Returns
boolean true if this channel's socket is connected; false otherwise.

open

Added in API level 1
DatagramChannel open ()

Creates an opened and not-connected datagram channel.

This channel is created by calling the openDatagramChannel method of the default SelectorProvider instance.

Returns
DatagramChannel the new channel which is open but not connected.
Throws
IOException if some I/O error occurs.

read

Added in API level 1
int read (ByteBuffer target)

Reads a datagram from this channel into the byte buffer.

The precondition for calling this method is that the channel is connected and the incoming datagram is from the connected address. If the buffer is not big enough to store the datagram, the part of the datagram that does not fit in the buffer is discarded. Otherwise, this method has the same behavior as the read method in the ReadableByteChannel interface.

Parameters
target ByteBuffer: the byte buffer to store the received datagram.
Returns
int a non-negative number as the number of bytes read, or -1 as the read operation reaches the end of stream.
Throws
NotYetConnectedException if the channel is not connected yet.
ClosedChannelException if the channel is already closed.
AsynchronousCloseException if the channel is closed by another thread while this method is in operation.
ClosedByInterruptException if another thread interrupts the calling thread while the operation is in progress. The calling thread will have the interrupt state set and the channel will be closed.
IOException some other I/O error occurs.

See also:

read

Added in API level 1
long read (ByteBuffer[] targets, 
                int offset, 
                int length)

Reads a datagram from this channel into an array of byte buffers.

The precondition for calling this method is that the channel is connected and the incoming datagram is from the connected address. If the buffers do not have enough remaining space to store the datagram, the part of the datagram that does not fit in the buffers is discarded. Otherwise, this method has the same behavior as the read method in the ScatteringByteChannel interface.

Parameters
targets ByteBuffer: the byte buffers to store the received datagram.
offset int: a non-negative offset in the array of buffers, pointing to the starting buffer to store the bytes transferred, must not be bigger than targets.length.
length int: a non-negative length to indicate the maximum number of buffers to be filled, must not be bigger than targets.length - offset.
Returns
long a non-negative number as the number of bytes read, or -1 if the read operation reaches the end of stream.
Throws
NotYetConnectedException if the channel is not connected yet.
ClosedChannelException if the channel is already closed.
AsynchronousCloseException if the channel is closed by another thread while this method is in operation.
ClosedByInterruptException if another thread interrupts the calling thread while the operation is in progress. The calling thread will have the interrupt state set and the channel will be closed.
IOException some other I/O error occurs.

See also:

read

Added in API level 1
long read (ByteBuffer[] targets)

Reads a datagram from this channel into an array of byte buffers.

The precondition for calling this method is that the channel is connected and the incoming datagram is from the connected address. If the buffers do not have enough remaining space to store the datagram, the part of the datagram that does not fit in the buffers is discarded. Otherwise, this method has the same behavior as the read method in the ScatteringByteChannel interface.

Parameters
targets ByteBuffer: the byte buffers to store the received datagram.
Returns
long a non-negative number as the number of bytes read, or -1 if the read operation reaches the end of stream.
Throws
NotYetConnectedException if the channel is not connected yet.
ClosedChannelException if the channel is already closed.
AsynchronousCloseException if the channel is closed by another thread while this method is in operation.
ClosedByInterruptException if another thread interrupts the calling thread while the operation is in progress. The calling thread will have the interrupt state set and the channel will be closed.
IOException some other I/O error occurs.

See also:

receive

Added in API level 1
SocketAddress receive (ByteBuffer target)

Gets a datagram from this channel.

This method transfers a datagram from the channel into the target byte buffer. If this channel is in blocking mode, it waits for the datagram and returns its address when it is available. If this channel is in non-blocking mode and no datagram is available, it returns null immediately. The transfer starts at the current position of the buffer, and if there is not enough space remaining in the buffer to store the datagram then the part of the datagram that does not fit is discarded.

This method can be called at any time and it will block if there is another thread that has started a read operation on the channel.

This method executes the same security checks as the receive method of the DatagramSocket class.

Parameters
target ByteBuffer: the byte buffer to store the received datagram.
Returns
SocketAddress the address of the datagram if the transfer is performed, or null if the channel is in non-blocking mode and no datagram is available.
Throws
ClosedChannelException if the channel is already closed.
AsynchronousCloseException if the channel is closed by another thread while this method is in operation.
ClosedByInterruptException if another thread interrupts the calling thread while the operation is in progress. The calling thread will have the interrupt state set and the channel will be closed.
IOException some other I/O error occurs.

send

Added in API level 1
int send (ByteBuffer source, 
                SocketAddress address)

Sends a datagram through this channel. The datagram consists of the remaining bytes in source.

If this channel is in blocking mode then the datagram is sent as soon as there is enough space in the underlying output buffer. If this channel is in non-blocking mode then the datagram is only sent if there is enough space in the underlying output buffer at that moment. The transfer action is just like a regular write operation.

This method can be called at any time and it will block if another thread has started a send operation on this channel.

This method executes the same security checks as the send method of the DatagramSocket class.

Parameters
source ByteBuffer: the byte buffer with the datagram to be sent.
address SocketAddress: the destination address for the datagram.
Returns
int the number of bytes sent. This is the number of bytes remaining in source or zero if the channel is in non-blocking mode and there is not enough space for the datagram in the underlying output buffer.
Throws
ClosedChannelException if the channel is already closed.
AsynchronousCloseException if the channel is closed by another thread while this method is in operation.
ClosedByInterruptException if another thread interrupts the calling thread while the operation is in progress. The calling thread will have the interrupt state set and the channel will be closed.
IOException some other I/O error occurs.

socket

Added in API level 1
DatagramSocket socket ()

Returns the related datagram socket of this channel, which does not define additional public methods to those defined by DatagramSocket.

Returns
DatagramSocket the related DatagramSocket instance.

validOps

Added in API level 1
int validOps ()

Gets the valid operations of this channel. Datagram channels support read and write operations, so this method returns ( SelectionKey.OP_READ | SelectionKey.OP_WRITE ).

Returns
int valid operations in bit-set.

See also:

write

Added in API level 1
long write (ByteBuffer[] sources, 
                int offset, 
                int length)

Writes a datagram from the byte buffers to this channel.

The precondition of calling this method is that the channel is connected and the datagram is sent to the connected address. Otherwise, this method has the same behavior as the write method in the GatheringByteChannel interface.

Parameters
sources ByteBuffer: the byte buffers as the source of the datagram.
offset int: a non-negative offset in the array of buffers, pointing to the starting buffer to be retrieved, must be no larger than sources.length.
length int: a non-negative length to indicate the maximum number of buffers to be submitted, must be no bigger than sources.length - offset.
Returns
long the number of bytes written. If this method is called, it returns the number of bytes that where remaining in the byte buffers. If the channel is in non-blocking mode and there was not enough space for the datagram in the buffer, it may return zero.
Throws
NotYetConnectedException if the channel is not connected yet.
ClosedChannelException if the channel is already closed.
AsynchronousCloseException if the channel is closed by another thread while this method is in operation.
ClosedByInterruptException if another thread interrupts the calling thread while the operation is in progress. The calling thread will have the interrupt state set and the channel will be closed.
IOException some other I/O error occurs.

See also:

write

Added in API level 1
int write (ByteBuffer source)

Writes a datagram from the byte buffer to this channel.

The precondition of calling this method is that the channel is connected and the datagram is sent to the connected address. Otherwise, this method has the same behavior as the write method in the WritableByteChannel interface.

Parameters
source ByteBuffer: the byte buffer as the source of the datagram.
Returns
int a non-negative number of bytes written.
Throws
NotYetConnectedException if the channel is not connected yet.
ClosedChannelException if the channel is already closed.
AsynchronousCloseException if the channel is closed by another thread while this method is in operation.
ClosedByInterruptException if another thread interrupts the calling thread while the operation is in progress. The calling thread will have the interrupt state set and the channel will be closed.
IOException some other I/O error occurs.

See also:

write

Added in API level 1
long write (ByteBuffer[] sources)

Writes a datagram from the byte buffers to this channel.

The precondition of calling this method is that the channel is connected and the datagram is sent to the connected address. Otherwise, this method has the same behavior as the write method in the GatheringByteChannel interface.

Parameters
sources ByteBuffer: the byte buffers as the source of the datagram.
Returns
long the number of bytes written. If this method is called, it returns the number of bytes that where remaining in the byte buffer. If the channel is in non-blocking mode and there was not enough space for the datagram in the buffer, it may return zero.
Throws
NotYetConnectedException if the channel is not connected yet.
ClosedChannelException if the channel is already closed.
AsynchronousCloseException if the channel is closed by another thread while this method is in operation.
ClosedByInterruptException if another thread interrupts the calling thread while the operation is in progress. The calling thread will have the interrupt state set and the channel will be closed.
IOException some other I/O error occurs.

See also:

This site uses cookies to store your preferences for site-specific language and display options.

Hooray!

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.