Android
java.nio.channels
public abstract class

java.nio.channels.DatagramChannel

java.lang.Object
java.nio.channels.spi.AbstractInterruptibleChannel Channel InterruptibleChannel
java.nio.channels.SelectableChannel Channel
java.nio.channels.spi.AbstractSelectableChannel
java.nio.channels.DatagramChannel ByteChannel GatheringByteChannel ScatteringByteChannel

A DatagramChannel is a selectable channel for part abstraction of 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 by open method. After connected, it will keep the connected status before disconnecting or closing. 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, no more than one thread can read or write at given time.

Summary

Protected Constructors

            DatagramChannel(SelectorProvider selectorProvider)
Constructor for this class.

Public Methods

abstract          DatagramChannel  connect(SocketAddress address)
Connect the socket of this channel to a remote address, which is the only communication peer of getting and sending datagrams after connected.
abstract          DatagramChannel  disconnect()
Disconnect the socket of this channel, which is connected before for getting and sending datagrams.
abstract          boolean  isConnected()
Answer whether this channel's socket is connected or not.
      static    DatagramChannel  open()
Create a open and not-connected datagram channel.
abstract          long  read(ByteBuffer[] targets, int offset, int length)
Reads datagram from the channel into the byte buffer.
abstract          int  read(ByteBuffer target)
Reads datagram from the channel into the byte buffer.
  synchronized  final      long  read(ByteBuffer[] targets)
Reads datagram from the channel into the byte buffer.
abstract          SocketAddress  receive(ByteBuffer target)
Get a datagram from this channel.
abstract          int  send(ByteBuffer source, SocketAddress address)
Sends out a datagram by the channel.
abstract          DatagramSocket  socket()
Return the related datagram socket of this channel, which won't declare public methods that not declared in DatagramSocket.
    final      int  validOps()
Get the valid operations of this channel.
abstract          long  write(ByteBuffer[] sources, int offset, int length)
Write datagram from the byte buffer into the channel.
  synchronized  final      long  write(ByteBuffer[] sources)
Write datagram from the byte buffer into the channel.
abstract          int  write(ByteBuffer source)
Write datagram from the byte buffer into the channel.
Methods inherited from class java.nio.channels.spi.AbstractSelectableChannel
Methods inherited from class java.nio.channels.SelectableChannel
Methods inherited from class java.nio.channels.spi.AbstractInterruptibleChannel
Methods inherited from class java.lang.Object
Methods inherited from interface java.io.Closeable
Methods inherited from interface java.nio.channels.Channel
Methods inherited from interface java.nio.channels.GatheringByteChannel
Methods inherited from interface java.nio.channels.InterruptibleChannel
Methods inherited from interface java.nio.channels.ReadableByteChannel
Methods inherited from interface java.nio.channels.ScatteringByteChannel
Methods inherited from interface java.nio.channels.WritableByteChannel

Details

Protected Constructors

protected DatagramChannel(SelectorProvider selectorProvider)

Constructor for this class.

Parameters

selectorProvider A instance of SelectorProvider

Public Methods

public abstract DatagramChannel connect(SocketAddress address)

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

This method can be called at any moment, and won't affect the processing read and write operation. The connect status won't changed before disconnected and closed.

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

Parameters

address The address to be connected.

Returns

  • 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.
SecurityException If there is a security manager, and the address is not permitted to access.
IOException Some other IO error occurred.

public abstract DatagramChannel disconnect()

Disconnect the socket of this channel, which is connected before for getting and sending datagrams.

This method can be called at any moment, and won't affect the processing read and write operation. It won't has any effect if the socket is not connected or the channel is closed.

Returns

  • This channel.

Throws

IOException Some other IO error occurred.

public abstract boolean isConnected()

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

Returns

  • true for this channel's socket is connected; false otherwise.

public static DatagramChannel open()

Create a open and not-connected datagram channel.

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

Returns

  • The new created channel which is open but not-connected.

Throws

IOException If some IO problem occurs.

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

Reads datagram from the channel into the byte buffer.

The precondition of calling this method is that the channel is connected and the coming datagram is from the connected address. If the buffer is not enough to store the datagram, the residual part of the datagram is ignored. Otherwise, this method has the same behavior as the read method in the ScatteringByteChannel interface.

Parameters

targets The byte buffers to store the received datagram.
offset A non-negative offset in the array of buffer, pointing to the starting buffer to store the byte transferred, must no larger than targets.length.
length A non-negative length to indicate the maximum number of byte to be read, must no larger than targets.length - offset.

Returns

  • 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 IO error occurred.

public abstract int read(ByteBuffer target)

Reads datagram from the channel into the byte buffer.

The precondition of calling this method is that the channel is connected and the coming datagram is from the connected address. If the buffer is not enough to store the datagram, the residual part of the datagram is ignored. Otherwise, this method has the same behavior as the read method in the ReadableByteChannel interface.

Parameters

target The byte buffer to store the received datagram.

Returns

  • 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 IO error occurred.

public final synchronized long read(ByteBuffer[] targets)

Reads datagram from the channel into the byte buffer.

The precondition of calling this method is that the channel is connected and the coming datagram is from the connected address. If the buffer is not enough to store the datagram, the residual part of the datagram is ignored. Otherwise, this method has the same behavior as the read method in the ScatteringByteChannel interface.

Parameters

targets The byte buffers to store the received datagram.

Returns

  • 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 IO error occurred.

public abstract SocketAddress receive(ByteBuffer target)

Get a datagram from this channel.

This method transfers the datagram from the channel into the target byte buffer and return the address of the datagram, if the datagram is available or will be available as this channel is in blocking mode. This method returns null if the datagram is not available now and the channel is in non-blocking mode. The transfer start at the current position of the buffer, and the residual part of the datagram will be ignored if there is no efficient remaining in the buffer to store the datagram.

This method can be called at any moment, and will block if there is another thread started a read operation on the channel.

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

Parameters

target The byte buffer to store the received datagram.

Returns

  • Address of the datagram if the transfer is performed, or null if the channel is in non-blocking mode and the datagram are unavailable.

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.
SecurityException If there is a security manager, and the address is not permitted to access.
IOException Some other IO error occurred.

public abstract int send(ByteBuffer source, SocketAddress address)

Sends out a datagram by the channel.

The precondition of sending is that whether the channel is in blocking mode and enough byte buffer space will be available, or the channel is in non-blocking mode and byte buffer space is enough. The transfer action is just like a regular write operation.

This method can be called at any moment, and will block if there is another thread started a read operation on the channel.

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

Parameters

source The byte buffer with the datagram to be sent.
address The address to be sent.

Returns

  • The number of sent bytes. If this method is called, it returns the number of bytes that remaining in the byte buffer. If the channel is in non-blocking mode and no enough space for the datagram in the buffer, it may returns zero.

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.
SecurityException If there is a security manager, and the address is not permitted to access.
IOException Some other IO error occurred.

public abstract DatagramSocket socket()

Return the related datagram socket of this channel, which won't declare public methods that not declared in DatagramSocket.

Returns

  • The related DatagramSocket instance.

public final int validOps()

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

Returns

  • Valid operations in bit-set.

See Also

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

Write datagram from the byte buffer into the 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 The byte buffers as the source of the datagram.
offset A non-negative offset in the array of buffer, pointing to the starting buffer to be retrieved, must no larger than sources.length.
length A non-negative length to indicate the maximum number of byte to be written, must no larger than sources.length - offset.

Returns

  • The number of written bytes. If this method is called, it returns the number of bytes that remaining in the byte buffer. If the channel is in non-blocking mode and no enough space for the datagram in the buffer, it may returns 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 IO error occurred.

public final synchronized long write(ByteBuffer[] sources)

Write datagram from the byte buffer into the 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 The byte buffers as the source of the datagram.

Returns

  • The number of written bytes. If this method is called, it returns the number of bytes that remaining in the byte buffer. If the channel is in non-blocking mode and no enough space for the datagram in the buffer, it may returns 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 IO error occurred.

public abstract int write(ByteBuffer source)

Write datagram from the byte buffer into the 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 The byte buffer as the source of the datagram.

Returns

  • 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 IO error occurred.
Copyright 2007 Google Inc. Build 0.9_r1-98467 - 14 Aug 2008 18:56