org.jboss.xnio.channels
Interface ReadableAllocatedMessageChannel

All Superinterfaces:

Channel, Closeable, CloseableChannel, Configurable, SuspendableReadChannel

public interface ReadableAllocatedMessageChannel
extends SuspendableReadChannel

A channel that can receive messages. Such a channel receives whole messages only; the messages are stored in pre-filled and pre-sized buffers.

Field Summary

static ByteBuffer	EMPTY The special marker indicating an empty message.
static ByteBuffer	EOF The special marker for end-of-file.
static ByteBuffer	GIANT The special marker indicating that the input buffer was overrun.
static ByteBuffer	RUNT The special marker indicating that the input message was shorter than its declared length.
static ByteBuffer	WOULD_BLOCK The special marker indicating that the receive request would block.

Method Summary

ChannelListener.Setter<? extends ReadableAllocatedMessageChannel>	getCloseSetter() Get the setter which can be used to change the close listener for this channel.
ChannelListener.Setter<? extends ReadableAllocatedMessageChannel>	getReadSetter() Get the setter which can be used to change the read listener for this channel.
ByteBuffer	receive() Receive a message.

Methods inherited from interface org.jboss.xnio.channels.SuspendableReadChannel

awaitReadable, awaitReadable, resumeReads, shutdownReads, suspendReads

Methods inherited from interface java.nio.channels.Channel

close, isOpen

Methods inherited from interface org.jboss.xnio.channels.Configurable

getOption, setOption, supportsOption

Field Detail

EOF

static final ByteBuffer EOF

The special marker for end-of-file.

WOULD_BLOCK

static final ByteBuffer WOULD_BLOCK

The special marker indicating that the receive request would block.

GIANT

static final ByteBuffer GIANT

The special marker indicating that the input buffer was overrun. The next receive will return the first part of the received message.

RUNT

static final ByteBuffer RUNT

The special marker indicating that the input message was shorter than its declared length. The next receive will return the message in a buffer whose limit is the actual length, and whose capacity was the expected length. If the original size would have made the message a giant, the capacity will be set to no greater than the maximum message size.

EMPTY

static final ByteBuffer EMPTY

The special marker indicating an empty message. This buffer can be used as a regular buffer as well, so it can be tested for either by identity comparison, or by checking the remaining size which will always be zero.

Method Detail

receive

ByteBuffer receive()
                   throws IOException

Receive a message. The returned buffer's position is 0, the mark is not set, the limit is the size of the received message, and the capacity is some value greater than or equal to the limit. If the request would block, WOULD_BLOCK is returned. If the channel is closed from a read direction, EOF is returned. If an oversized message was received, the special GIANT marker is returned, followed by the truncated message. If a zero-length message is received, EMPTY is returned.

Returns:

a buffer containing the received message

Throws:

IOException - if an I/O error occurs

getReadSetter

ChannelListener.Setter<? extends ReadableAllocatedMessageChannel> getReadSetter()

Get the setter which can be used to change the read listener for this channel. When the listener is called, additional notifications are automatically suspended.

Specified by:

getReadSetter in interface SuspendableReadChannel

Returns:

the setter

getCloseSetter

ChannelListener.Setter<? extends ReadableAllocatedMessageChannel> getCloseSetter()

Get the setter which can be used to change the close listener for this channel. If the channel is already closed, then the listener will not be called.

Specified by:

getCloseSetter in interface CloseableChannel

Specified by:

getCloseSetter in interface SuspendableReadChannel

Returns:

the setter