io.netty.channel

Interface Channel

All Superinterfaces:

io.netty.util.AttributeMap, ChannelFutureFactory, ChannelOutboundInvoker, Comparable<Channel>

All Known Subinterfaces:

DatagramChannel, SctpChannel, SctpServerChannel, ServerChannel, ServerSocketChannel, SocketChannel

All Known Implementing Classes:

AbstractChannel, AbstractEmbeddedChannel, AbstractNioChannel, AbstractServerChannel, AioServerSocketChannel, AioSocketChannel, EmbeddedByteChannel, EmbeddedMessageChannel, LocalChannel, LocalServerChannel, NioDatagramChannel, NioSctpChannel, NioSctpServerChannel, NioServerSocketChannel, NioSocketChannel, OioDatagramChannel, OioSctpChannel, OioSctpServerChannel, OioServerSocketChannel, OioSocketChannel

public interface Channel
extends io.netty.util.AttributeMap, ChannelOutboundInvoker, ChannelFutureFactory, Comparable<Channel>

A nexus to a network socket or a component which is capable of I/O operations such as read, write, connect, and bind.

A channel provides a user:

• the current state of the channel (e.g. is it open? is it connected?),
• the configuration parameters of the channel (e.g. receive buffer size),
• the I/O operations that the channel supports (e.g. read, write, connect, and bind), and
• the ChannelPipeline which handles all I/O events and requests associated with the channel.

All I/O operations are asynchronous.

All I/O operations in Netty are asynchronous. It means any I/O calls will return immediately with no guarantee that the requested I/O operation has been completed at the end of the call. Instead, you will be returned with a ChannelFuture instance which will notify you when the requested I/O operation has succeeded, failed, or canceled.

Channels are hierarchical

A Channel can have a parent depending on how it was created. For instance, a SocketChannel, that was accepted by ServerSocketChannel, will return the ServerSocketChannel as its parent on #getParent().

The semantics of the hierarchical structure depends on the transport implementation where the Channel belongs to. For example, you could write a new Channel implementation that creates the sub-channels that share one socket connection, as BEEP and SSH do.

Downcast to access transport-specific operations

Some transports exposes additional operations that is specific to the transport. Down-cast the Channel to sub-type to invoke such operations. For example, with the old I/O datagram transport, multicast join / leave operations are provided by DatagramChannel.

InterestOps

A Channel has a property called interestOps which is similar to that of NIO SelectionKey. It is represented as a bit field which is composed of the two flags.

• #OP_READ - If set, a message sent by a remote peer will be read immediately. If unset, the message from the remote peer will not be read until the #OP_READ flag is set again (i.e. read suspension).
• #OP_WRITE - If set, a write request will not be sent to a remote peer until the #OP_WRITE flag is cleared and the write request will be pending in a queue. If unset, the write request will be flushed out as soon as possible from the queue.
• #OP_READ_WRITE - This is a combination of #OP_READ and #OP_WRITE, which means only write requests are suspended.
• #OP_NONE - This is a combination of (NOT #OP_READ) and (NOT #OP_WRITE), which means only read operation is suspended.

You can set or clear the #OP_READ flag to suspend and resume read operation via #setReadable(boolean).

Please note that you cannot suspend or resume write operation just like you can set or clear #OP_READ. The #OP_WRITE flag is read only and provided simply as a mean to tell you if the size of pending write requests exceeded a certain threshold or not so that you don't issue too many pending writes that lead to an OutOfMemoryError. For example, the NIO socket transport uses the writeBufferLowWaterMark and writeBufferHighWaterMark properties in NioSocketChannelConfig to determine when to set or clear the #OP_WRITE flag.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	Channel.Unsafe Unsafe operations that should never be called from user-code.

Method Summary

Methods

Modifier and Type	Method and Description
ChannelFuture	closeFuture() Returns the ChannelFuture which will be notified when this channel is closed.
ChannelConfig	config() Returns the configuration of this channel.
EventLoop	eventLoop() Return the EventLoop this Channel was registered too.
Integer	id() Returns the unique integer ID of this channel.
boolean	isActive()
boolean	isOpen()
boolean	isRegistered()
SocketAddress	localAddress() Returns the local address where this channel is bound to.
ChannelMetadata	metadata() Return the ChannelMetadata of the Channel which describe the nature of the Channel.
io.netty.buffer.ByteBuf	outboundByteBuffer()
<T> io.netty.buffer.MessageBuf<T>	outboundMessageBuffer()
Channel	parent() Returns the parent of this channel.
ChannelPipeline	pipeline() Returns the ChannelPipeline which handles ChannelEvents associated with this channel.
SocketAddress	remoteAddress() Returns the remote address where this channel is connected to.
Channel.Unsafe	unsafe() Caution for transport implementations use only!

Methods inherited from interface io.netty.util.AttributeMap

attr

Methods inherited from interface io.netty.channel.ChannelOutboundInvoker

bind, bind, close, close, connect, connect, connect, connect, deregister, deregister, disconnect, disconnect, flush, flush, write, write

Methods inherited from interface io.netty.channel.ChannelFutureFactory

newFailedFuture, newFuture, newSucceededFuture

Methods inherited from interface java.lang.Comparable

compareTo

Method Detail

id

Integer id()

Returns the unique integer ID of this channel.

eventLoop

EventLoop eventLoop()

Return the EventLoop this Channel was registered too.

parent

Channel parent()

Returns the parent of this channel.

Returns:

the parent channel. null if this channel does not have a parent channel.

config

ChannelConfig config()

Returns the configuration of this channel.

pipeline

ChannelPipeline pipeline()

Returns the ChannelPipeline which handles ChannelEvents associated with this channel.

isOpen

boolean isOpen()

isRegistered

boolean isRegistered()

isActive

boolean isActive()

metadata

ChannelMetadata metadata()

Return the ChannelMetadata of the Channel which describe the nature of the Channel.

outboundByteBuffer

io.netty.buffer.ByteBuf outboundByteBuffer()

outboundMessageBuffer

<T> io.netty.buffer.MessageBuf<T> outboundMessageBuffer()

localAddress

SocketAddress localAddress()

Returns the local address where this channel is bound to. The returned SocketAddress is supposed to be down-cast into more concrete type such as InetSocketAddress to retrieve the detailed information.

Returns:

the local address of this channel. null if this channel is not bound.

remoteAddress

SocketAddress remoteAddress()

Returns the remote address where this channel is connected to. The returned SocketAddress is supposed to be down-cast into more concrete type such as InetSocketAddress to retrieve the detailed information.

Returns:

the remote address of this channel. null if this channel is not connected. If this channel is not connected but it can receive messages from arbitrary remote addresses (e.g. DatagramChannel, use MessageEvent#getRemoteAddress() to determine the origination of the received message as this method will return null.

closeFuture

ChannelFuture closeFuture()

Returns the ChannelFuture which will be notified when this channel is closed. This method always returns the same future instance.

unsafe

Channel.Unsafe unsafe()

Caution for transport implementations use only!