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 parent().

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.

Release resources

It is important to call close() or close(ChannelPromise) to release all resources once you are done with the Channel. This ensures all resources are released in a proper way, i.e. filehandles.

Nested and Inner Type Summary

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

Method Summary

Modifier and Type	Method and Description
public ByteBufAllocator	alloc() Return the assigned `ByteBufAllocator` which will be used to allocate `ByteBuf`s.
public long	bytesBeforeUnwritable() Get how many bytes can be written until `isWritable()` returns `false`.
public long	bytesBeforeWritable() Get how many bytes must be drained from underlying buffers until `isWritable()` returns `true`.
public ChannelFuture	closeFuture() Returns the `ChannelFuture` which will be notified when this channel is closed.
public ChannelConfig	config() Returns the configuration of this channel.
public EventLoop	eventLoop() Return the `EventLoop` this `Channel` was registered to.
public Channel	flush() Redeclares io.netty.channel.ChannelOutboundInvoker.flush. Request to flush all pending messages via this ChannelOutboundInvoker.
public ChannelId	id() Returns the globally unique identifier of this `Channel`.
public boolean	isActive() Return `true` if the `Channel` is active and so connected.
public boolean	isOpen() Returns `true` if the `Channel` is open and may get active later
public boolean	isRegistered() Returns `true` if the `Channel` is registered with an `EventLoop`.
public boolean	isWritable() Returns `true` if and only if the I/O thread will perform the requested write operation immediately.
public SocketAddress	Returns: the local address of this channel. `null` if this channel is not bound. localAddress() Returns the local address where this channel is bound to.
public ChannelMetadata	metadata() Return the `ChannelMetadata` of the `Channel` which describe the nature of the `Channel`.
public Channel	Returns: the parent channel. `null` if this channel does not have a parent channel. parent() Returns the parent of this channel.
public ChannelPipeline	pipeline() Return the assigned `ChannelPipeline`.
public Channel	read() Redeclares io.netty.channel.ChannelOutboundInvoker.read. Request to Read data from the `Channel` into the first inbound buffer, triggers an `ChannelInboundHandler#channelRead(ChannelHandlerContext, Object)` event if data was read, and triggers a `channelReadComplete` event so the handler can decide to continue reading.
public SocketAddress	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 `DatagramPacket#recipient()` to determine the origination of the received message as this method will return `null`. remoteAddress() Returns the remote address where this channel is connected to.
public Channel.Unsafe	unsafe() Returns an internal-use-only object that provides unsafe operations.

Method Detail

alloc	back to summary
public ByteBufAllocator alloc() Return the assigned `ByteBufAllocator` which will be used to allocate `ByteBuf`s.

bytesBeforeUnwritable	back to summary
public long bytesBeforeUnwritable() Get how many bytes can be written until `isWritable()` returns `false`. This quantity will always be non-negative. If `isWritable()` is `false` then 0.

bytesBeforeWritable	back to summary
public long bytesBeforeWritable() Get how many bytes must be drained from underlying buffers until `isWritable()` returns `true`. This quantity will always be non-negative. If `isWritable()` is `true` then 0.

closeFuture	back to summary
public ChannelFuture closeFuture() Returns the `ChannelFuture` which will be notified when this channel is closed. This method always returns the same future instance.

config	back to summary
public ChannelConfig config() Returns the configuration of this channel.

eventLoop	back to summary
public EventLoop eventLoop() Return the `EventLoop` this `Channel` was registered to.

flush	back to summary
public Channel flush() Redeclares io.netty.channel.ChannelOutboundInvoker.flush. Doc from io.netty.channel.ChannelOutboundInvoker.flush. Request to flush all pending messages via this ChannelOutboundInvoker. Annotations @Override

flush

back to summary

public Channel flush()

Redeclares io.netty.channel.ChannelOutboundInvoker.flush.

Doc from io.netty.channel.ChannelOutboundInvoker.flush.

Request to flush all pending messages via this ChannelOutboundInvoker.

Annotations

@Override

id	back to summary
public ChannelId id() Returns the globally unique identifier of this `Channel`.

isActive	back to summary
public boolean isActive() Return `true` if the `Channel` is active and so connected.

isOpen	back to summary
public boolean isOpen() Returns `true` if the `Channel` is open and may get active later

isRegistered	back to summary
public boolean isRegistered() Returns `true` if the `Channel` is registered with an `EventLoop`.

isWritable	back to summary
public boolean isWritable() Returns `true` if and only if the I/O thread will perform the requested write operation immediately. Any write requests made when this method returns `false` are queued until the I/O thread is ready to process the queued write requests.

localAddress back to summary

localAddress	back to summary
public 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:SocketAddress the local address of this channel. `null` if this channel is not bound.

public 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:SocketAddress: the local address of this channel. null if this channel is not bound.

metadata	back to summary
public ChannelMetadata metadata() Return the `ChannelMetadata` of the `Channel` which describe the nature of the `Channel`.

parent back to summary

parent	back to summary
public Channel parent() Returns the parent of this channel. Returns:Channel the parent channel. `null` if this channel does not have a parent channel.

public Channel parent()

Returns the parent of this channel.

Returns:Channel: the parent channel. null if this channel does not have a parent channel.

pipeline	back to summary
public ChannelPipeline pipeline() Return the assigned `ChannelPipeline`.

read back to summary

read	back to summary
public Channel read() Redeclares io.netty.channel.ChannelOutboundInvoker.read. Doc from io.netty.channel.ChannelOutboundInvoker.read. Request to Read data from the `Channel` into the first inbound buffer, triggers an `ChannelInboundHandler#channelRead(ChannelHandlerContext, Object)` event if data was read, and triggers a `channelReadComplete` event so the handler can decide to continue reading. If there's a pending read operation already, this method does nothing. This will result in having the `ChannelOutboundHandler#read(ChannelHandlerContext)` method called of the next `ChannelOutboundHandler` contained in the `ChannelPipeline` of the `Channel`. Annotations @Override

public Channel read()

Redeclares io.netty.channel.ChannelOutboundInvoker.read.

Doc from io.netty.channel.ChannelOutboundInvoker.read.

Request to Read data from the Channel into the first inbound buffer, triggers an ChannelInboundHandler#channelRead(ChannelHandlerContext, Object) event if data was read, and triggers a channelReadComplete event so the handler can decide to continue reading. If there's a pending read operation already, this method does nothing.

This will result in having the ChannelOutboundHandler#read(ChannelHandlerContext) method called of the next ChannelOutboundHandler contained in the ChannelPipeline of the Channel.

Annotations

@Override

remoteAddress back to summary

remoteAddress	back to summary
public 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:SocketAddress 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 `DatagramPacket#recipient()` to determine the origination of the received message as this method will return `null`.

public 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:SocketAddress: 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 DatagramPacket#recipient() to determine the origination of the received message as this method will return null.

unsafe	back to summary
public Channel.Unsafe unsafe() Returns an internal-use-only object that provides unsafe operations.

io.netty.channel back to summary

public Interface Channel.Unsafe

Known Direct Subinterfaces: io.netty.channel.nio.AbstractNioChannel.NioUnsafe
Known Direct Implementers: io.netty.channel.AbstractChannel.AbstractUnsafe

Unsafe operations that should never be called from user-code. These methods are only provided to implement the actual transport, and must be invoked from an I/O thread except for the following methods:

Method Summary

Modifier and Type	Method and Description
public void	beginRead() Schedules a read operation that fills the inbound buffer of the first `ChannelInboundHandler` in the `ChannelPipeline`.
public void	bind(SocketAddress localAddress, ChannelPromise promise) Bind the `SocketAddress` to the `Channel` of the `ChannelPromise` and notify it once its done.
public void	close(ChannelPromise promise) Close the `Channel` of the `ChannelPromise` and notify the `ChannelPromise` once the operation was complete.
public void	closeForcibly() Closes the `Channel` immediately without firing any events.
public void	connect(SocketAddress remoteAddress, SocketAddress localAddress, ChannelPromise promise) Connect the `Channel` of the given `ChannelFuture` with the given remote `SocketAddress`.
public void	deregister(ChannelPromise promise) Deregister the `Channel` of the `ChannelPromise` from `EventLoop` and notify the `ChannelPromise` once the operation was complete.
public void	disconnect(ChannelPromise promise) Disconnect the `Channel` of the `ChannelFuture` and notify the `ChannelPromise` once the operation was complete.
public void	flush() Flush out all write operations scheduled via `write(Object, ChannelPromise)`.
public SocketAddress	localAddress() Return the `SocketAddress` to which is bound local or `null` if none.
public ChannelOutboundBuffer	outboundBuffer() Returns the `ChannelOutboundBuffer` of the `Channel` where the pending write requests are stored.
public RecvByteBufAllocator.Handle	recvBufAllocHandle() Deprecated as a consequence of `RecvByteBufAllocator.Handle` being deprecated. Return the assigned `RecvByteBufAllocator.Handle` which will be used to allocate `ByteBuf`'s when receiving data.
public void	register(EventLoop eventLoop, ChannelPromise promise) Register the `Channel` of the `ChannelPromise` and notify the `ChannelFuture` once the registration was complete.
public SocketAddress	remoteAddress() Return the `SocketAddress` to which is bound remote or `null` if none is bound yet.
public ChannelPromise	voidPromise() Return a special ChannelPromise which can be reused and passed to the operations in `Unsafe`.
public void	write(Object msg, ChannelPromise promise) Schedules a write operation.

Method Detail

beginRead	back to summary
public void beginRead() Schedules a read operation that fills the inbound buffer of the first `ChannelInboundHandler` in the `ChannelPipeline`. If there's already a pending read operation, this method does nothing.

bind	back to summary
public void bind(SocketAddress localAddress, ChannelPromise promise) Bind the `SocketAddress` to the `Channel` of the `ChannelPromise` and notify it once its done.

close	back to summary
public void close(ChannelPromise promise) Close the `Channel` of the `ChannelPromise` and notify the `ChannelPromise` once the operation was complete.

closeForcibly	back to summary
public void closeForcibly() Closes the `Channel` immediately without firing any events. Probably only useful when registration attempt failed.

connect	back to summary
public void connect(SocketAddress remoteAddress, SocketAddress localAddress, ChannelPromise promise) Connect the `Channel` of the given `ChannelFuture` with the given remote `SocketAddress`. If a specific local `SocketAddress` should be used it need to be given as argument. Otherwise just pass `null` to it. The `ChannelPromise` will get notified once the connect operation was complete.

deregister	back to summary
public void deregister(ChannelPromise promise) Deregister the `Channel` of the `ChannelPromise` from `EventLoop` and notify the `ChannelPromise` once the operation was complete.

disconnect	back to summary
public void disconnect(ChannelPromise promise) Disconnect the `Channel` of the `ChannelFuture` and notify the `ChannelPromise` once the operation was complete.

flush	back to summary
public void flush() Flush out all write operations scheduled via `write(Object, ChannelPromise)`.

localAddress	back to summary
public SocketAddress localAddress() Return the `SocketAddress` to which is bound local or `null` if none.

outboundBuffer	back to summary
public ChannelOutboundBuffer outboundBuffer() Returns the `ChannelOutboundBuffer` of the `Channel` where the pending write requests are stored.

recvBufAllocHandle	back to summary
public RecvByteBufAllocator.Handle recvBufAllocHandle() Deprecated as a consequence of `RecvByteBufAllocator.Handle` being deprecated. See corresponding docs for further information. Return the assigned `RecvByteBufAllocator.Handle` which will be used to allocate `ByteBuf`'s when receiving data.

register	back to summary
public void register(EventLoop eventLoop, ChannelPromise promise) Register the `Channel` of the `ChannelPromise` and notify the `ChannelFuture` once the registration was complete.

remoteAddress	back to summary
public SocketAddress remoteAddress() Return the `SocketAddress` to which is bound remote or `null` if none is bound yet.

voidPromise	back to summary
public ChannelPromise voidPromise() Return a special ChannelPromise which can be reused and passed to the operations in `Unsafe`. It will never be notified of a success or error and so is only a placeholder for operations that take a `ChannelPromise` as argument but for which you not want to get notified.

write	back to summary
public void write(Object msg, ChannelPromise promise) Schedules a write operation.