java.nio.channels
public
abstract
class
java.nio.channels.DatagramChannel
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
Public Methods
clone,
equals,
finalize,
getClass,
hashCode,
notify,
notifyAll,
toString,
wait,
wait,
wait
Details
Protected Constructors
protected
DatagramChannel(SelectorProvider selectorProvider)
Constructor for this class.
Parameters
selectorProvider
| A instance of SelectorProvider
|
Public Methods
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. |
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.