Interface Channel
- All Superinterfaces:
AttributeMap
,ChannelOutboundInvoker
,Comparable<Channel>
- All Known Subinterfaces:
DatagramChannel
,DomainDatagramChannel
,DomainSocketChannel
,DuplexChannel
,Http2StreamChannel
,ServerChannel
,ServerDomainSocketChannel
,ServerSocketChannel
,SocketChannel
,UnixChannel
- All Known Implementing Classes:
AbstractChannel
,AbstractEpollChannel
,AbstractEpollServerChannel
,AbstractEpollStreamChannel
,AbstractHttp2StreamChannel
,AbstractKQueueChannel
,AbstractKQueueDatagramChannel
,AbstractKQueueServerChannel
,AbstractKQueueStreamChannel
,AbstractNioByteChannel
,AbstractNioChannel
,AbstractNioMessageChannel
,AbstractOioByteChannel
,AbstractOioChannel
,AbstractOioMessageChannel
,AbstractServerChannel
,EmbeddedChannel
,EpollDatagramChannel
,EpollDomainDatagramChannel
,EpollDomainSocketChannel
,EpollServerDomainSocketChannel
,EpollServerSocketChannel
,EpollSocketChannel
,FailedChannel
,Http2MultiplexCodec.Http2MultiplexCodecStreamChannel
,Http2MultiplexHandler.Http2MultiplexHandlerStreamChannel
,KQueueDatagramChannel
,KQueueDomainDatagramChannel
,KQueueDomainSocketChannel
,KQueueServerDomainSocketChannel
,KQueueServerSocketChannel
,KQueueSocketChannel
,LocalChannel
,LocalServerChannel
,NioDatagramChannel
,NioServerSocketChannel
,NioSocketChannel
,OioByteStreamChannel
,OioDatagramChannel
,OioServerSocketChannel
,OioSocketChannel
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 ChannelOutboundInvoker.close()
or ChannelOutboundInvoker.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 Class Summary
Nested ClassesModifier and TypeInterfaceDescriptionstatic interface
Unsafe operations that should never be called from user-code. -
Method Summary
Modifier and TypeMethodDescriptionalloc()
Return the assignedByteBufAllocator
which will be used to allocateByteBuf
s.long
Get how many bytes can be written untilisWritable()
returnsfalse
.long
Get how many bytes must be drained from underlying buffers untilisWritable()
returnstrue
.Returns theChannelFuture
which will be notified when this channel is closed.config()
Returns the configuration of this channel.flush()
Request to flush all pending messages via this ChannelOutboundInvoker.id()
Returns the globally unique identifier of thisChannel
.boolean
isActive()
Returntrue
if theChannel
is active and so connected.boolean
isOpen()
Returnstrue
if theChannel
is open and may get active laterboolean
boolean
Returnstrue
if and only if the I/O thread will perform the requested write operation immediately.Returns the local address where this channel is bound to.metadata()
parent()
Returns the parent of this channel.pipeline()
Return the assignedChannelPipeline
.read()
Request to Read data from theChannel
into the first inbound buffer, triggers anChannelInboundHandler.channelRead(ChannelHandlerContext, Object)
event if data was read, and triggers achannelReadComplete
event so the handler can decide to continue reading.Returns the remote address where this channel is connected to.unsafe()
Returns an internal-use-only object that provides unsafe operations.Methods inherited from interface io.netty.util.AttributeMap
attr, hasAttr
Methods inherited from interface io.netty.channel.ChannelOutboundInvoker
bind, bind, close, close, connect, connect, connect, connect, deregister, deregister, disconnect, disconnect, newFailedFuture, newProgressivePromise, newPromise, newSucceededFuture, voidPromise, write, write, writeAndFlush, writeAndFlush
Methods inherited from interface java.lang.Comparable
compareTo
-
Method Details
-
id
ChannelId id()Returns the globally unique identifier of thisChannel
. -
eventLoop
EventLoop eventLoop() -
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. -
isOpen
boolean isOpen()Returnstrue
if theChannel
is open and may get active later -
isRegistered
boolean isRegistered() -
isActive
boolean isActive()Returntrue
if theChannel
is active and so connected. -
metadata
ChannelMetadata metadata() -
localAddress
SocketAddress localAddress()Returns the local address where this channel is bound to. The returnedSocketAddress
is supposed to be down-cast into more concrete type such asInetSocketAddress
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 returnedSocketAddress
is supposed to be down-cast into more concrete type such asInetSocketAddress
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
, useDefaultAddressedEnvelope.recipient()
to determine the origination of the received message as this method will returnnull
.
-
closeFuture
ChannelFuture closeFuture()Returns theChannelFuture
which will be notified when this channel is closed. This method always returns the same future instance. -
isWritable
boolean isWritable()Returnstrue
if and only if the I/O thread will perform the requested write operation immediately. Any write requests made when this method returnsfalse
are queued until the I/O thread is ready to process the queued write requests. -
bytesBeforeUnwritable
long bytesBeforeUnwritable()Get how many bytes can be written untilisWritable()
returnsfalse
. This quantity will always be non-negative. IfisWritable()
isfalse
then 0. -
bytesBeforeWritable
long bytesBeforeWritable()Get how many bytes must be drained from underlying buffers untilisWritable()
returnstrue
. This quantity will always be non-negative. IfisWritable()
istrue
then 0. -
unsafe
Channel.Unsafe unsafe()Returns an internal-use-only object that provides unsafe operations. -
pipeline
ChannelPipeline pipeline()Return the assignedChannelPipeline
. -
alloc
ByteBufAllocator alloc()Return the assignedByteBufAllocator
which will be used to allocateByteBuf
s. -
read
Channel read()Description copied from interface:ChannelOutboundInvoker
Request to Read data from theChannel
into the first inbound buffer, triggers anChannelInboundHandler.channelRead(ChannelHandlerContext, Object)
event if data was read, and triggers achannelReadComplete
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 nextChannelOutboundHandler
contained in theChannelPipeline
of theChannel
.- Specified by:
read
in interfaceChannelOutboundInvoker
-
flush
Channel flush()Description copied from interface:ChannelOutboundInvoker
Request to flush all pending messages via this ChannelOutboundInvoker.- Specified by:
flush
in interfaceChannelOutboundInvoker
-