public interface Channel extends AttributeMap, java.lang.Comparable<Channel>
A channel provides a user:
ChannelPipeline
which handles all I/O events and requests associated with the channel.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.
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.
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
.
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.
Modifier and Type | Interface and Description |
---|---|
static interface |
Channel.Unsafe
Unsafe operations that should never be called from user-code.
|
Modifier and Type | Method and Description |
---|---|
ByteBufAllocator |
alloc()
Return the assigned ByteBufAllocator which will be used to allocate ByteBuf s.
|
ChannelFuture |
bind(java.net.SocketAddress localAddress)
Request to bind to the given SocketAddress and notify the ChannelFuture once the operation completes, either because the operation was successful or because of an error.
|
ChannelFuture |
bind(java.net.SocketAddress localAddress, ChannelPromise promise)
Request to bind to the given SocketAddress and notify the ChannelFuture once the operation completes, either because the operation was successful or because of an error.
|
ChannelFuture |
close()
Request to close this Channel and notify the ChannelFuture once the operation completes, either because the operation was successful or because of an error.
|
ChannelFuture |
close(ChannelPromise promise)
Request to close this Channel and notify the ChannelFuture once the operation completes, either because the operation was successful or because of an error.
|
ChannelFuture |
closeFuture()
Returns the ChannelFuture which will be notified when this channel is closed.
|
ChannelConfig |
config()
Returns the configuration of this channel.
|
ChannelFuture |
connect(java.net.SocketAddress remoteAddress)
Request to connect to the given SocketAddress and notify the ChannelFuture once the operation completes, either because the operation was successful or because of an error.
|
ChannelFuture |
connect(java.net.SocketAddress remoteAddress, ChannelPromise promise)
Request to connect to the given SocketAddress and notify the ChannelFuture once the operation completes, either because the operation was successful or because of an error.
|
ChannelFuture |
connect(java.net.SocketAddress remoteAddress, java.net.SocketAddress localAddress)
Request to connect to the given SocketAddress while bind to the localAddress and notify the ChannelFuture once the operation completes, either because the operation was successful or because of an error.
|
ChannelFuture |
connect(java.net.SocketAddress remoteAddress, java.net.SocketAddress localAddress, ChannelPromise promise)
Request to connect to the given SocketAddress while bind to the localAddress and notify the ChannelFuture once the operation completes, either because the operation was successful or because of an error.
|
ChannelFuture |
deregister()
Request to deregister this Channel from the previous assigned EventExecutor and notify the ChannelFuture once the operation completes, either because the operation was successful or because of an error.
|
ChannelFuture |
deregister(ChannelPromise promise)
Request to deregister this Channel from the previous assigned EventExecutor and notify the ChannelFuture once the operation completes, either because the operation was successful or because of an error.
|
ChannelFuture |
disconnect()
Request to disconnect from the remote peer and notify the ChannelFuture once the operation completes, either because the operation was successful or because of an error.
|
ChannelFuture |
disconnect(ChannelPromise promise)
Request to disconnect from the remote peer and notify the ChannelFuture once the operation completes, either because the operation was successful or because of an error.
|
EventLoop |
eventLoop()
|
Channel |
flush()
Request to flush all pending messages.
|
boolean |
isActive()
Return true if the Channel is active and so connected.
|
boolean |
isOpen()
Returns true if the Channel is open and may get active later
|
boolean |
isRegistered()
|
boolean |
isWritable()
Returns true 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()
|
ChannelFuture |
newFailedFuture(java.lang.Throwable cause)
Create a new ChannelFuture which is marked as failed already.
|
ChannelProgressivePromise |
newProgressivePromise()
Return an new ChannelProgressivePromise .
|
ChannelPromise |
newPromise()
Return a new ChannelPromise .
|
ChannelFuture |
newSucceededFuture()
Create a new ChannelFuture which is marked as succeeded already.
|
Channel |
parent()
Returns the parent of this channel.
|
ChannelPipeline |
pipeline()
Return the assigned ChannelPipeline .
|
Channel |
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.
|
java.net.SocketAddress |
remoteAddress()
Returns the remote address where this channel is connected to.
|
Channel.Unsafe |
unsafe()
Returns an internal-use-only object that provides unsafe operations.
|
ChannelPromise |
voidPromise()
Return a special ChannelPromise which can be reused for different operations.
|
ChannelFuture |
write(java.lang.Object msg)
Request to write a message via this Channel through the ChannelPipeline .
|
ChannelFuture |
write(java.lang.Object msg, ChannelPromise promise)
Request to write a message via this Channel through the ChannelPipeline .
|
ChannelFuture |
writeAndFlush(java.lang.Object msg)
Shortcut for call write(Object) and flush() .
|
ChannelFuture |
writeAndFlush(java.lang.Object msg, ChannelPromise promise)
Shortcut for call write(Object, ChannelPromise) and flush() .
|
attr
EventLoop eventLoop()
Channel parent()
null
if this channel does not have a parent channel.
ChannelConfig config()
boolean isOpen()
true
if the Channel
is open and may get active later
boolean isRegistered()
boolean isActive()
true
if the Channel
is active and so connected.
ChannelMetadata metadata()
java.net.SocketAddress localAddress()
SocketAddress
is supposed to be down-cast into more concrete type such as InetSocketAddress
to retrieve the detailed information.
null
if this channel is not bound.
java.net.SocketAddress remoteAddress()
SocketAddress
is supposed to be down-cast into more concrete type such as InetSocketAddress
to retrieve the detailed information.
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 DefaultAddressedEnvelope.recipient()
to determine the origination of the received message as this method will return null
.
ChannelFuture closeFuture()
ChannelFuture
which will be notified when this channel is closed. This method always returns the same future instance.
boolean isWritable()
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.
Channel.Unsafe unsafe()
ChannelPipeline pipeline()
ChannelPipeline
.
ByteBufAllocator alloc()
ByteBufAllocator
which will be used to allocate ByteBuf
s.
ChannelPromise newPromise()
ChannelPromise
.
ChannelProgressivePromise newProgressivePromise()
ChannelProgressivePromise
.
ChannelFuture newSucceededFuture()
ChannelFuture
which is marked as succeeded already. So Future.isSuccess()
will return true
. All FutureListener
added to it will be notified directly. Also every call of blocking methods will just return without blocking.
ChannelFuture newFailedFuture(java.lang.Throwable cause)
ChannelFuture
which is marked as failed already. So Future.isSuccess()
will return false
. All FutureListener
added to it will be notified directly. Also every call of blocking methods will just return without blocking.
ChannelPromise voidPromise()
It's only supported to use it for write(Object, ChannelPromise)
.
Be aware that the returned 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 call ChannelPipeline.fireExceptionCaught(Throwable)
in this case.
ChannelFuture bind(java.net.SocketAddress localAddress)
SocketAddress
and notify the ChannelFuture
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 next ChannelOutboundHandler
contained in the ChannelPipeline
of the Channel
.
ChannelFuture connect(java.net.SocketAddress remoteAddress)
SocketAddress
and notify the ChannelFuture
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 a ConnectTimeoutException
. If it fails because of connection refused a ConnectException
will be used.
This will result in having the ChannelOutboundHandler.connect(ChannelHandlerContext, SocketAddress, SocketAddress, ChannelPromise)
method called of the next ChannelOutboundHandler
contained in the ChannelPipeline
of the Channel
.
ChannelFuture connect(java.net.SocketAddress remoteAddress, java.net.SocketAddress localAddress)
SocketAddress
while bind to the localAddress and notify the ChannelFuture
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 next ChannelOutboundHandler
contained in the ChannelPipeline
of the Channel
.
ChannelFuture disconnect()
ChannelFuture
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 next ChannelOutboundHandler
contained in the ChannelPipeline
of the Channel
.
ChannelFuture close()
Channel
and notify the ChannelFuture
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 next ChannelOutboundHandler
contained in the ChannelPipeline
of the Channel
.
ChannelFuture deregister()
Channel
from the previous assigned EventExecutor
and notify the ChannelFuture
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 next ChannelOutboundHandler
contained in the ChannelPipeline
of the Channel
.
ChannelFuture bind(java.net.SocketAddress localAddress, ChannelPromise promise)
SocketAddress
and notify the ChannelFuture
once the operation completes, either because the operation was successful or because of an error. The given ChannelPromise
will be notified.
This will result in having the ChannelOutboundHandler.bind(ChannelHandlerContext, SocketAddress, ChannelPromise)
method called of the next ChannelOutboundHandler
contained in the ChannelPipeline
of the Channel
.
ChannelFuture connect(java.net.SocketAddress remoteAddress, ChannelPromise promise)
SocketAddress
and notify the ChannelFuture
once the operation completes, either because the operation was successful or because of an error. The given ChannelFuture
will be notified.
If the connection fails because of a connection timeout, the ChannelFuture
will get failed with a ConnectTimeoutException
. If it fails because of connection refused a ConnectException
will be used.
This will result in having the ChannelOutboundHandler.connect(ChannelHandlerContext, SocketAddress, SocketAddress, ChannelPromise)
method called of the next ChannelOutboundHandler
contained in the ChannelPipeline
of the Channel
.
ChannelFuture connect(java.net.SocketAddress remoteAddress, java.net.SocketAddress localAddress, ChannelPromise promise)
SocketAddress
while bind to the localAddress and notify the ChannelFuture
once the operation completes, either because the operation was successful or because of an error. The given ChannelPromise
will be notified and also returned.
This will result in having the ChannelOutboundHandler.connect(ChannelHandlerContext, SocketAddress, SocketAddress, ChannelPromise)
method called of the next ChannelOutboundHandler
contained in the ChannelPipeline
of the Channel
.
ChannelFuture disconnect(ChannelPromise promise)
ChannelFuture
once the operation completes, either because the operation was successful or because of an error. The given ChannelPromise
will be notified.
This will result in having the ChannelOutboundHandler.disconnect(ChannelHandlerContext, ChannelPromise)
method called of the next ChannelOutboundHandler
contained in the ChannelPipeline
of the Channel
.
ChannelFuture close(ChannelPromise promise)
Channel
and notify the ChannelFuture
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 given ChannelPromise
will be notified.
This will result in having the ChannelOutboundHandler.close(ChannelHandlerContext, ChannelPromise)
method called of the next ChannelOutboundHandler
contained in the ChannelPipeline
of the Channel
.
ChannelFuture deregister(ChannelPromise promise)
Channel
from the previous assigned EventExecutor
and notify the ChannelFuture
once the operation completes, either because the operation was successful or because of an error. The given ChannelPromise
will be notified.
This will result in having the ChannelOutboundHandler.deregister(ChannelHandlerContext, ChannelPromise)
method called of the next ChannelOutboundHandler
contained in the ChannelPipeline
of the Channel
.
Channel read()
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
.
ChannelFuture write(java.lang.Object msg)
Channel
through the ChannelPipeline
. This method will not request to actual flush, so be sure to call flush()
once you want to request to flush all pending data to the actual transport.
ChannelFuture write(java.lang.Object msg, ChannelPromise promise)
Channel
through the ChannelPipeline
. This method will not request to actual flush, so be sure to call flush()
once you want to request to flush all pending data to the actual transport.
Channel flush()
ChannelFuture writeAndFlush(java.lang.Object msg, ChannelPromise promise)
write(Object, ChannelPromise)
and flush()
.
ChannelFuture writeAndFlush(java.lang.Object msg)
write(Object)
and flush()
.
Copyright © 2008–2018 The Netty Project. All rights reserved.