Interface Channel

All Superinterfaces:
AttributeMap, ChannelOutboundInvoker, Comparable<Channel>
All Known Subinterfaces:
DatagramChannel, DomainDatagramChannel, DomainSocketChannel, DuplexChannel, Http2StreamChannel, SctpChannel, SctpServerChannel, 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, NioDomainSocketChannel, NioSctpChannel, NioSctpServerChannel, NioServerDomainSocketChannel, NioServerSocketChannel, NioSocketChannel, OioByteStreamChannel, OioDatagramChannel, OioSctpChannel, OioSctpServerChannel, OioServerSocketChannel, OioSocketChannel

public interface Channel extends AttributeMap, ChannelOutboundInvoker, 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, 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.

  • Method Details

    • id

      ChannelId id()
      Returns the globally unique identifier of this Channel.
    • eventLoop

      EventLoop eventLoop()
      Return the EventLoop this Channel was registered to.
    • 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()
      Returns true if the Channel is open and may get active later
    • isRegistered

      boolean isRegistered()
      Returns true if the Channel is registered with an EventLoop.
    • isActive

      boolean isActive()
      Return true if the Channel is active and so connected.
    • metadata

      ChannelMetadata metadata()
      Return the ChannelMetadata of the Channel which describe the nature of the Channel.
    • localAddress

      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:
      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 returned SocketAddress is supposed to be down-cast into more concrete type such as InetSocketAddress 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, use DefaultAddressedEnvelope.recipient() to determine the origination of the received message as this method will return null.
    • closeFuture

      ChannelFuture closeFuture()
      Returns the ChannelFuture which will be notified when this channel is closed. This method always returns the same future instance.
    • isWritable

      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. WriteBufferWaterMark can be used to configure on which condition the write buffer would cause this channel to change writability.
    • bytesBeforeUnwritable

      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. WriteBufferWaterMark can be used to define writability settings.
    • bytesBeforeWritable

      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. 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 assigned ChannelPipeline.
    • alloc

      Return the assigned ByteBufAllocator which will be used to allocate ByteBufs.
    • read

      Channel read()
      Description copied from interface: ChannelOutboundInvoker
      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.

      Specified by:
      read in interface ChannelOutboundInvoker
    • flush

      Channel flush()
      Description copied from interface: ChannelOutboundInvoker
      Request to flush all pending messages via this ChannelOutboundInvoker.
      Specified by:
      flush in interface ChannelOutboundInvoker