Interface Channel
-
- All Superinterfaces:
AttributeMap
,ChannelOutboundInvoker
,java.lang.Comparable<Channel>
- All Known Subinterfaces:
DatagramChannel
,DomainDatagramChannel
,DomainSocketChannel
,DuplexChannel
,Http2StreamChannel
,SctpChannel
,SctpServerChannel
,ServerChannel
,ServerDomainSocketChannel
,ServerSocketChannel
,SocketChannel
,UdtChannel
,UdtServerChannel
,UnixChannel
- All Known Implementing Classes:
AbstractChannel
,AbstractEpollServerChannel
,AbstractEpollStreamChannel
,AbstractKQueueServerChannel
,AbstractKQueueStreamChannel
,AbstractNioByteChannel
,AbstractNioChannel
,AbstractNioMessageChannel
,AbstractOioByteChannel
,AbstractOioChannel
,AbstractOioMessageChannel
,AbstractServerChannel
,EmbeddedChannel
,EpollDatagramChannel
,EpollDomainDatagramChannel
,EpollDomainSocketChannel
,EpollServerDomainSocketChannel
,EpollServerSocketChannel
,EpollSocketChannel
,IoUringDatagramChannel
,IoUringServerSocketChannel
,IoUringSocketChannel
,KQueueDatagramChannel
,KQueueDomainDatagramChannel
,KQueueDomainSocketChannel
,KQueueServerDomainSocketChannel
,KQueueServerSocketChannel
,KQueueSocketChannel
,LocalChannel
,LocalServerChannel
,NioDatagramChannel
,NioDomainSocketChannel
,NioSctpChannel
,NioSctpServerChannel
,NioServerDomainSocketChannel
,NioServerSocketChannel
,NioSocketChannel
,NioUdtAcceptorChannel
,NioUdtByteAcceptorChannel
,NioUdtByteConnectorChannel
,NioUdtByteRendezvousChannel
,NioUdtMessageAcceptorChannel
,NioUdtMessageConnectorChannel
,NioUdtMessageRendezvousChannel
,OioByteStreamChannel
,OioDatagramChannel
,OioSctpChannel
,OioSctpServerChannel
,OioServerSocketChannel
,OioSocketChannel
,RxtxChannel
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
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, aSocketChannel
, that was accepted byServerSocketChannel
, will return theServerSocketChannel
as its parent onparent()
.The semantics of the hierarchical structure depends on the transport implementation where the
Channel
belongs to. For example, you could write a newChannel
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 byDatagramChannel
.Release resources
It is important to call
close()
orclose(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 interface
Channel.Unsafe
Unsafe operations that should never be called from user-code.
-
Method Summary
All Methods Instance Methods Abstract Methods Default Methods Modifier and Type Method Description default ByteBufAllocator
alloc()
Return the assignedByteBufAllocator
which will be used to allocateByteBuf
s.default ChannelFuture
bind(java.net.SocketAddress localAddress)
Request to bind to the givenSocketAddress
and notify theChannelFuture
once the operation completes, either because the operation was successful or because of an error.default ChannelFuture
bind(java.net.SocketAddress localAddress, ChannelPromise promise)
Request to bind to the givenSocketAddress
and notify theChannelFuture
once the operation completes, either because the operation was successful or because of an error.default long
bytesBeforeUnwritable()
Get how many bytes can be written untilisWritable()
returnsfalse
.default long
bytesBeforeWritable()
Get how many bytes must be drained from underlying buffers untilisWritable()
returnstrue
.default ChannelFuture
close()
Request to close theChannel
and notify theChannelFuture
once the operation completes, either because the operation was successful or because of an error.default ChannelFuture
close(ChannelPromise promise)
Request to close theChannel
and notify theChannelFuture
once the operation completes, either because the operation was successful or because of an error.ChannelFuture
closeFuture()
Returns theChannelFuture
which will be notified when this channel is closed.ChannelConfig
config()
Returns the configuration of this channel.default ChannelFuture
connect(java.net.SocketAddress remoteAddress)
Request to connect to the givenSocketAddress
and notify theChannelFuture
once the operation completes, either because the operation was successful or because of an error.default ChannelFuture
connect(java.net.SocketAddress remoteAddress, ChannelPromise promise)
Request to connect to the givenSocketAddress
and notify theChannelFuture
once the operation completes, either because the operation was successful or because of an error.default ChannelFuture
connect(java.net.SocketAddress remoteAddress, java.net.SocketAddress localAddress)
Request to connect to the givenSocketAddress
while bind to the localAddress and notify theChannelFuture
once the operation completes, either because the operation was successful or because of an error.default ChannelFuture
connect(java.net.SocketAddress remoteAddress, java.net.SocketAddress localAddress, ChannelPromise promise)
Request to connect to the givenSocketAddress
while bind to the localAddress and notify theChannelFuture
once the operation completes, either because the operation was successful or because of an error.default ChannelFuture
deregister()
Request to deregister from the previous assignedEventExecutor
and notify theChannelFuture
once the operation completes, either because the operation was successful or because of an error.default ChannelFuture
deregister(ChannelPromise promise)
Request to deregister from the previous assignedEventExecutor
and notify theChannelFuture
once the operation completes, either because the operation was successful or because of an error.default ChannelFuture
disconnect()
Request to disconnect from the remote peer and notify theChannelFuture
once the operation completes, either because the operation was successful or because of an error.default ChannelFuture
disconnect(ChannelPromise promise)
Request to disconnect from the remote peer and notify theChannelFuture
once the operation completes, either because the operation was successful or because of an error.EventLoop
eventLoop()
default Channel
flush()
Request to flush all pending messages via this ChannelOutboundInvoker.default <T> T
getOption(ChannelOption<T> option)
Return the value of the givenChannelOption
ChannelId
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
isRegistered()
default boolean
isWritable()
Returnstrue
if and only if the I/O thread will perform the requested write operation immediately.java.net.SocketAddress
localAddress()
Returns the local address where this channel is bound to.ChannelMetadata
metadata()
default ChannelFuture
newFailedFuture(java.lang.Throwable cause)
Create a newChannelFuture
which is marked as failed already.default ChannelProgressivePromise
newProgressivePromise()
Return an newChannelProgressivePromise
default ChannelPromise
newPromise()
Return a newChannelPromise
.default ChannelFuture
newSucceededFuture()
Create a newChannelFuture
which is marked as succeeded already.Channel
parent()
Returns the parent of this channel.ChannelPipeline
pipeline()
Return the assignedChannelPipeline
.default Channel
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.java.net.SocketAddress
remoteAddress()
Returns the remote address where this channel is connected to.default <T> boolean
setOption(ChannelOption<T> option, T value)
Sets a configuration property with the specified name and value.Channel.Unsafe
unsafe()
Returns an internal-use-only object that provides unsafe operations.default ChannelPromise
voidPromise()
Return a special ChannelPromise which can be reused for different operations.default ChannelFuture
write(java.lang.Object msg)
Request to write a message via thisChannelHandlerContext
through theChannelPipeline
.default ChannelFuture
write(java.lang.Object msg, ChannelPromise promise)
Request to write a message via thisChannelHandlerContext
through theChannelPipeline
.default ChannelFuture
writeAndFlush(java.lang.Object msg)
Shortcut for callChannelOutboundInvoker.write(Object)
andChannelOutboundInvoker.flush()
.default ChannelFuture
writeAndFlush(java.lang.Object msg, ChannelPromise promise)
Shortcut for callChannelOutboundInvoker.write(Object, ChannelPromise)
andChannelOutboundInvoker.flush()
.-
Methods inherited from interface io.netty.util.AttributeMap
attr, hasAttr
-
-
-
-
Method Detail
-
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
java.net.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
java.net.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
default 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.WriteBufferWaterMark
can be used to configure on which condition the write buffer would cause this channel to change writability.
-
bytesBeforeUnwritable
default long bytesBeforeUnwritable()
Get how many bytes can be written untilisWritable()
returnsfalse
. This quantity will always be non-negative. IfisWritable()
isfalse
then 0.WriteBufferWaterMark
can be used to define writability settings.
-
bytesBeforeWritable
default 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.WriteBufferWaterMark
can be used to define writability settings.
-
unsafe
Channel.Unsafe unsafe()
Returns an internal-use-only object that provides unsafe operations.
-
pipeline
ChannelPipeline pipeline()
Return the assignedChannelPipeline
.
-
alloc
default ByteBufAllocator alloc()
Return the assignedByteBufAllocator
which will be used to allocateByteBuf
s.
-
getOption
default <T> T getOption(ChannelOption<T> option)
Return the value of the givenChannelOption
-
setOption
default <T> boolean setOption(ChannelOption<T> option, T value)
Sets a configuration property with the specified name and value. To override this method properly, you must call the super class:public boolean setOption(ChannelOption<T> option, T value) { if (super.setOption(option, value)) { return true; } if (option.equals(additionalOption)) { .... return true; } return false; }
- Returns:
true
if and only if the property has been set
-
read
default 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
default Channel flush()
Description copied from interface:ChannelOutboundInvoker
Request to flush all pending messages via this ChannelOutboundInvoker.- Specified by:
flush
in interfaceChannelOutboundInvoker
-
writeAndFlush
default ChannelFuture writeAndFlush(java.lang.Object msg)
Description copied from interface:ChannelOutboundInvoker
Shortcut for callChannelOutboundInvoker.write(Object)
andChannelOutboundInvoker.flush()
.- Specified by:
writeAndFlush
in interfaceChannelOutboundInvoker
-
writeAndFlush
default ChannelFuture writeAndFlush(java.lang.Object msg, ChannelPromise promise)
Description copied from interface:ChannelOutboundInvoker
Shortcut for callChannelOutboundInvoker.write(Object, ChannelPromise)
andChannelOutboundInvoker.flush()
.- Specified by:
writeAndFlush
in interfaceChannelOutboundInvoker
-
write
default ChannelFuture write(java.lang.Object msg, ChannelPromise promise)
Description copied from interface:ChannelOutboundInvoker
Request to write a message via thisChannelHandlerContext
through theChannelPipeline
. This method will not request to actual flush, so be sure to callChannelOutboundInvoker.flush()
once you want to request to flush all pending data to the actual transport.- Specified by:
write
in interfaceChannelOutboundInvoker
-
write
default ChannelFuture write(java.lang.Object msg)
Description copied from interface:ChannelOutboundInvoker
Request to write a message via thisChannelHandlerContext
through theChannelPipeline
. This method will not request to actual flush, so be sure to callChannelOutboundInvoker.flush()
once you want to request to flush all pending data to the actual transport.- Specified by:
write
in interfaceChannelOutboundInvoker
-
deregister
default ChannelFuture deregister(ChannelPromise promise)
Description copied from interface:ChannelOutboundInvoker
Request to deregister from the previous assignedEventExecutor
and notify theChannelFuture
once the operation completes, either because the operation was successful or because of an error. The givenChannelPromise
will be notified.This will result in having the
ChannelOutboundHandler.deregister(ChannelHandlerContext, ChannelPromise)
method called of the nextChannelOutboundHandler
contained in theChannelPipeline
of theChannel
.- Specified by:
deregister
in interfaceChannelOutboundInvoker
-
close
default ChannelFuture close(ChannelPromise promise)
Description copied from interface:ChannelOutboundInvoker
Request to close theChannel
and notify theChannelFuture
once the operation completes, either because the operation was successful or because of an error. After it is closed it is not possible to reuse it again. The givenChannelPromise
will be notified.This will result in having the
ChannelOutboundHandler.close(ChannelHandlerContext, ChannelPromise)
method called of the nextChannelOutboundHandler
contained in theChannelPipeline
of theChannel
.- Specified by:
close
in interfaceChannelOutboundInvoker
-
disconnect
default ChannelFuture disconnect(ChannelPromise promise)
Description copied from interface:ChannelOutboundInvoker
Request to disconnect from the remote peer and notify theChannelFuture
once the operation completes, either because the operation was successful or because of an error. The givenChannelPromise
will be notified.This will result in having the
ChannelOutboundHandler.disconnect(ChannelHandlerContext, ChannelPromise)
method called of the nextChannelOutboundHandler
contained in theChannelPipeline
of theChannel
.- Specified by:
disconnect
in interfaceChannelOutboundInvoker
-
connect
default ChannelFuture connect(java.net.SocketAddress remoteAddress, java.net.SocketAddress localAddress, ChannelPromise promise)
Description copied from interface:ChannelOutboundInvoker
Request to connect to the givenSocketAddress
while bind to the localAddress and notify theChannelFuture
once the operation completes, either because the operation was successful or because of an error. The givenChannelPromise
will be notified and also returned.This will result in having the
ChannelOutboundHandler.connect(ChannelHandlerContext, SocketAddress, SocketAddress, ChannelPromise)
method called of the nextChannelOutboundHandler
contained in theChannelPipeline
of theChannel
.- Specified by:
connect
in interfaceChannelOutboundInvoker
-
connect
default ChannelFuture connect(java.net.SocketAddress remoteAddress, ChannelPromise promise)
Description copied from interface:ChannelOutboundInvoker
Request to connect to the givenSocketAddress
and notify theChannelFuture
once the operation completes, either because the operation was successful or because of an error. The givenChannelFuture
will be notified.If the connection fails because of a connection timeout, the
ChannelFuture
will get failed with aConnectTimeoutException
. If it fails because of connection refused aConnectException
will be used.This will result in having the
ChannelOutboundHandler.connect(ChannelHandlerContext, SocketAddress, SocketAddress, ChannelPromise)
method called of the nextChannelOutboundHandler
contained in theChannelPipeline
of theChannel
.- Specified by:
connect
in interfaceChannelOutboundInvoker
-
bind
default ChannelFuture bind(java.net.SocketAddress localAddress, ChannelPromise promise)
Description copied from interface:ChannelOutboundInvoker
Request to bind to the givenSocketAddress
and notify theChannelFuture
once the operation completes, either because the operation was successful or because of an error. The givenChannelPromise
will be notified.This will result in having the
ChannelOutboundHandler.bind(ChannelHandlerContext, SocketAddress, ChannelPromise)
method called of the nextChannelOutboundHandler
contained in theChannelPipeline
of theChannel
.- Specified by:
bind
in interfaceChannelOutboundInvoker
-
deregister
default ChannelFuture deregister()
Description copied from interface:ChannelOutboundInvoker
Request to deregister from the previous assignedEventExecutor
and notify theChannelFuture
once the operation completes, either because the operation was successful or because of an error.This will result in having the
ChannelOutboundHandler.deregister(ChannelHandlerContext, ChannelPromise)
method called of the nextChannelOutboundHandler
contained in theChannelPipeline
of theChannel
.- Specified by:
deregister
in interfaceChannelOutboundInvoker
-
close
default ChannelFuture close()
Description copied from interface:ChannelOutboundInvoker
Request to close theChannel
and notify theChannelFuture
once the operation completes, either because the operation was successful or because of an error. After it is closed it is not possible to reuse it again.This will result in having the
ChannelOutboundHandler.close(ChannelHandlerContext, ChannelPromise)
method called of the nextChannelOutboundHandler
contained in theChannelPipeline
of theChannel
.- Specified by:
close
in interfaceChannelOutboundInvoker
-
disconnect
default ChannelFuture disconnect()
Description copied from interface:ChannelOutboundInvoker
Request to disconnect from the remote peer and notify theChannelFuture
once the operation completes, either because the operation was successful or because of an error.This will result in having the
ChannelOutboundHandler.disconnect(ChannelHandlerContext, ChannelPromise)
method called of the nextChannelOutboundHandler
contained in theChannelPipeline
of theChannel
.- Specified by:
disconnect
in interfaceChannelOutboundInvoker
-
connect
default ChannelFuture connect(java.net.SocketAddress remoteAddress, java.net.SocketAddress localAddress)
Description copied from interface:ChannelOutboundInvoker
Request to connect to the givenSocketAddress
while bind to the localAddress and notify theChannelFuture
once the operation completes, either because the operation was successful or because of an error.This will result in having the
ChannelOutboundHandler.connect(ChannelHandlerContext, SocketAddress, SocketAddress, ChannelPromise)
method called of the nextChannelOutboundHandler
contained in theChannelPipeline
of theChannel
.- Specified by:
connect
in interfaceChannelOutboundInvoker
-
connect
default ChannelFuture connect(java.net.SocketAddress remoteAddress)
Description copied from interface:ChannelOutboundInvoker
Request to connect to the givenSocketAddress
and notify theChannelFuture
once the operation completes, either because the operation was successful or because of an error.If the connection fails because of a connection timeout, the
ChannelFuture
will get failed with aConnectTimeoutException
. If it fails because of connection refused aConnectException
will be used.This will result in having the
ChannelOutboundHandler.connect(ChannelHandlerContext, SocketAddress, SocketAddress, ChannelPromise)
method called of the nextChannelOutboundHandler
contained in theChannelPipeline
of theChannel
.- Specified by:
connect
in interfaceChannelOutboundInvoker
-
bind
default ChannelFuture bind(java.net.SocketAddress localAddress)
Description copied from interface:ChannelOutboundInvoker
Request to bind to the givenSocketAddress
and notify theChannelFuture
once the operation completes, either because the operation was successful or because of an error.This will result in having the
ChannelOutboundHandler.bind(ChannelHandlerContext, SocketAddress, ChannelPromise)
method called of the nextChannelOutboundHandler
contained in theChannelPipeline
of theChannel
.- Specified by:
bind
in interfaceChannelOutboundInvoker
-
newPromise
default ChannelPromise newPromise()
Description copied from interface:ChannelOutboundInvoker
Return a newChannelPromise
.- Specified by:
newPromise
in interfaceChannelOutboundInvoker
-
newProgressivePromise
default ChannelProgressivePromise newProgressivePromise()
Description copied from interface:ChannelOutboundInvoker
Return an newChannelProgressivePromise
- Specified by:
newProgressivePromise
in interfaceChannelOutboundInvoker
-
newSucceededFuture
default ChannelFuture newSucceededFuture()
Description copied from interface:ChannelOutboundInvoker
Create a newChannelFuture
which is marked as succeeded already. SoFuture.isSuccess()
will returntrue
. AllFutureListener
added to it will be notified directly. Also every call of blocking methods will just return without blocking.- Specified by:
newSucceededFuture
in interfaceChannelOutboundInvoker
-
newFailedFuture
default ChannelFuture newFailedFuture(java.lang.Throwable cause)
Description copied from interface:ChannelOutboundInvoker
Create a newChannelFuture
which is marked as failed already. SoFuture.isSuccess()
will returnfalse
. AllFutureListener
added to it will be notified directly. Also every call of blocking methods will just return without blocking.- Specified by:
newFailedFuture
in interfaceChannelOutboundInvoker
-
voidPromise
default ChannelPromise voidPromise()
Description copied from interface:ChannelOutboundInvoker
Return a special ChannelPromise which can be reused for different operations.It's only supported to use it for
ChannelOutboundInvoker.write(Object, ChannelPromise)
.Be aware that the returned
Be aware this is an expert feature and should be used with care!ChannelPromise
will not support most operations and should only be used if you want to save an object allocation for every write operation. You will not be able to detect if the operation was complete, only if it failed as the implementation will callChannelPipeline.fireExceptionCaught(Throwable)
in this case.- Specified by:
voidPromise
in interfaceChannelOutboundInvoker
-
-