Interface Channel
-
- All Superinterfaces:
AttributeMap,ChannelOutboundInvoker,java.lang.Comparable<Channel>
- All Known Subinterfaces:
DatagramChannel,DuplexChannel,Http2StreamChannel,ServerChannel,ServerSocketChannel,SocketChannel
- All Known Implementing Classes:
AbstractChannel,AbstractHttp2StreamChannel,AbstractNioByteChannel,AbstractNioChannel,AbstractNioMessageChannel,AbstractOioByteChannel,AbstractOioChannel,AbstractOioMessageChannel,AbstractServerChannel,EmbeddedChannel,FailedChannel,Http2MultiplexCodec.Http2MultiplexCodecStreamChannel,Http2MultiplexHandler.Http2MultiplexHandlerStreamChannel,LocalChannel,LocalServerChannel,NioDatagramChannel,NioServerSocketChannel,NioSocketChannel,OioByteStreamChannel,OioDatagramChannel,OioServerSocketChannel,OioSocketChannel
public interface Channel extends AttributeMap, ChannelOutboundInvoker, java.lang.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
ChannelPipelinewhich 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
ChannelFutureinstance which will notify you when the requested I/O operation has succeeded, failed, or canceled.Channels are hierarchical
A
Channelcan have a parent depending on how it was created. For instance, aSocketChannel, that was accepted byServerSocketChannel, will return theServerSocketChannelas its parent onparent().The semantics of the hierarchical structure depends on the transport implementation where the
Channelbelongs to. For example, you could write a newChannelimplementation 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
Channelto sub-type to invoke such operations. For example, with the old I/O datagram transport, multicast join / leave operations are provided byDatagramChannel.Release resources
It is important to call
ChannelOutboundInvoker.close()orChannelOutboundInvoker.close(ChannelPromise)to release all resources once you are done with theChannel. This ensures all resources are released in a proper way, i.e. filehandles.
-
-
Nested Class Summary
Nested Classes Modifier and Type Interface Description static interfaceChannel.UnsafeUnsafe operations that should never be called from user-code.
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description ByteBufAllocatoralloc()Return the assignedByteBufAllocatorwhich will be used to allocateByteBufs.longbytesBeforeUnwritable()Get how many bytes can be written untilisWritable()returnsfalse.longbytesBeforeWritable()Get how many bytes must be drained from underlying buffers untilisWritable()returnstrue.ChannelFuturecloseFuture()Returns theChannelFuturewhich will be notified when this channel is closed.ChannelConfigconfig()Returns the configuration of this channel.EventLoopeventLoop()Channelflush()Request to flush all pending messages via this ChannelOutboundInvoker.ChannelIdid()Returns the globally unique identifier of thisChannel.booleanisActive()Returntrueif theChannelis active and so connected.booleanisOpen()Returnstrueif theChannelis open and may get active laterbooleanisRegistered()booleanisWritable()Returnstrueif and only if the I/O thread will perform the requested write operation immediately.java.net.SocketAddresslocalAddress()Returns the local address where this channel is bound to.ChannelMetadatametadata()Channelparent()Returns the parent of this channel.ChannelPipelinepipeline()Return the assignedChannelPipeline.Channelread()Request to Read data from theChannelinto the first inbound buffer, triggers anChannelInboundHandler.channelRead(ChannelHandlerContext, Object)event if data was read, and triggers achannelReadCompleteevent so the handler can decide to continue reading.java.net.SocketAddressremoteAddress()Returns the remote address where this channel is connected to.Channel.Unsafeunsafe()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
-
-
-
-
Method Detail
-
eventLoop
EventLoop eventLoop()
-
parent
Channel parent()
Returns the parent of this channel.- Returns:
- the parent channel.
nullif this channel does not have a parent channel.
-
config
ChannelConfig config()
Returns the configuration of this channel.
-
isOpen
boolean isOpen()
Returnstrueif theChannelis open and may get active later
-
isRegistered
boolean isRegistered()
-
isActive
boolean isActive()
Returntrueif theChannelis active and so connected.
-
metadata
ChannelMetadata metadata()
-
localAddress
java.net.SocketAddress localAddress()
Returns the local address where this channel is bound to. The returnedSocketAddressis supposed to be down-cast into more concrete type such asInetSocketAddressto retrieve the detailed information.- Returns:
- the local address of this channel.
nullif this channel is not bound.
-
remoteAddress
java.net.SocketAddress remoteAddress()
Returns the remote address where this channel is connected to. The returnedSocketAddressis supposed to be down-cast into more concrete type such asInetSocketAddressto retrieve the detailed information.- Returns:
- the remote address of this channel.
nullif 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 theChannelFuturewhich will be notified when this channel is closed. This method always returns the same future instance.
-
isWritable
boolean isWritable()
Returnstrueif and only if the I/O thread will perform the requested write operation immediately. Any write requests made when this method returnsfalseare 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()isfalsethen 0.
-
bytesBeforeWritable
long bytesBeforeWritable()
Get how many bytes must be drained from underlying buffers untilisWritable()returnstrue. This quantity will always be non-negative. IfisWritable()istruethen 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 assignedByteBufAllocatorwhich will be used to allocateByteBufs.
-
read
Channel read()
Description copied from interface:ChannelOutboundInvokerRequest to Read data from theChannelinto the first inbound buffer, triggers anChannelInboundHandler.channelRead(ChannelHandlerContext, Object)event if data was read, and triggers achannelReadCompleteevent 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 nextChannelOutboundHandlercontained in theChannelPipelineof theChannel.- Specified by:
readin interfaceChannelOutboundInvoker
-
flush
Channel flush()
Description copied from interface:ChannelOutboundInvokerRequest to flush all pending messages via this ChannelOutboundInvoker.- Specified by:
flushin interfaceChannelOutboundInvoker
-
-