Channel (Netty/Transport 4.2.0.RC2 API)

All Superinterfaces:

io.netty.util.AttributeMap, ChannelOutboundInvoker, Comparable<Channel>

All Known Subinterfaces:

DatagramChannel, DuplexChannel, ServerChannel, ServerSocketChannel, SocketChannel

All Known Implementing Classes:

AbstractChannel, AbstractNioByteChannel, AbstractNioChannel, AbstractNioMessageChannel, AbstractOioByteChannel, AbstractOioChannel, AbstractOioMessageChannel, AbstractServerChannel, EmbeddedChannel, LocalChannel, LocalServerChannel, NioDatagramChannel, NioDomainSocketChannel, NioServerDomainSocketChannel, NioServerSocketChannel, NioSocketChannel, OioByteStreamChannel, OioDatagramChannel, OioServerSocketChannel, OioSocketChannel
```
public interface Channel
extends io.netty.util.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 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.

Nested Class Summary

Nested Classes
Modifier and Type Interface and Description

static interface Channel.Unsafe
Unsafe operations that should never be called from user-code.

Nested Classes
Modifier and Type	Interface and 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 and Description
`default io.netty.buffer.ByteBufAllocator`	`alloc()` Return the assigned `ByteBufAllocator` which will be used to allocate `ByteBuf`s.
`default ChannelFuture`	`bind(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.
`default ChannelFuture`	`bind(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.
`default long`	`bytesBeforeUnwritable()` Get how many bytes can be written until `isWritable()` returns `false`.
`default long`	`bytesBeforeWritable()` Get how many bytes must be drained from underlying buffers until `isWritable()` returns `true`.
`default ChannelFuture`	`close()` Request to close the `Channel` and notify the `ChannelFuture` once the operation completes, either because the operation was successful or because of an error.
`default ChannelFuture`	`close(ChannelPromise promise)` Request to close the `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.
`default ChannelFuture`	`connect(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.
`default ChannelFuture`	`connect(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.
`default ChannelFuture`	`connect(SocketAddress remoteAddress, 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.
`default ChannelFuture`	`connect(SocketAddress remoteAddress, 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.
`default ChannelFuture`	`deregister()` Request to deregister from the previous assigned `EventExecutor` and notify the `ChannelFuture` 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 assigned `EventExecutor` and notify the `ChannelFuture` 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 the `ChannelFuture` 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 the `ChannelFuture` once the operation completes, either because the operation was successful or because of an error.
`EventLoop`	`eventLoop()` Return the `EventLoop` this `Channel` was registered to.
`default Channel`	`flush()` Request to flush all pending messages via this ChannelOutboundInvoker.
`default <T> T`	`getOption(ChannelOption<T> option)` Return the value of the given `ChannelOption`
`ChannelId`	`id()` Returns the globally unique identifier of this `Channel`.
`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()` Returns `true` if the `Channel` is registered with an `EventLoop`.
`default boolean`	`isWritable()` Returns `true` if and only if the I/O thread will perform the requested write operation immediately.
`SocketAddress`	`localAddress()` Returns the local address where this channel is bound to.
`ChannelMetadata`	`metadata()` Return the `ChannelMetadata` of the `Channel` which describe the nature of the `Channel`.
`default ChannelFuture`	`newFailedFuture(Throwable cause)` Create a new `ChannelFuture` which is marked as failed already.
`default ChannelProgressivePromise`	`newProgressivePromise()` Return an new `ChannelProgressivePromise`
`default ChannelPromise`	`newPromise()` Return a new `ChannelPromise`.
`default 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`.
`default 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.
`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(Object msg)` Request to write a message via this `ChannelHandlerContext` through the `ChannelPipeline`.
`default ChannelFuture`	`write(Object msg, ChannelPromise promise)` Request to write a message via this `ChannelHandlerContext` through the `ChannelPipeline`.
`default ChannelFuture`	`writeAndFlush(Object msg)` Shortcut for call `ChannelOutboundInvoker.write(Object)` and `ChannelOutboundInvoker.flush()`.
`default ChannelFuture`	`writeAndFlush(Object msg, ChannelPromise promise)` Shortcut for call `ChannelOutboundInvoker.write(Object, ChannelPromise)` and `ChannelOutboundInvoker.flush()`.

Methods inherited from interface io.netty.util.AttributeMap
attr, hasAttr

Methods inherited from interface java.lang.Comparable
compareTo

- Method Detail
  - 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
```
default 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
```
default 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
```
default 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
```
default io.netty.buffer.ByteBufAllocator alloc()
```
    Return the assigned ByteBufAllocator which will be used to allocate ByteBufs.
  - getOption
```
default <T> T getOption(ChannelOption<T> option)
```
    Return the value of the given ChannelOption
  - 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 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
```
default Channel flush()
```
    Description copied from interface: ChannelOutboundInvoker
    
    Request to flush all pending messages via this ChannelOutboundInvoker.
    
    Specified by:
    
    flush in interface ChannelOutboundInvoker
  - writeAndFlush
```
default ChannelFuture writeAndFlush(Object msg)
```
    Description copied from interface: ChannelOutboundInvoker
    
    Shortcut for call ChannelOutboundInvoker.write(Object) and ChannelOutboundInvoker.flush().
    
    Specified by:
    
    writeAndFlush in interface ChannelOutboundInvoker
  - writeAndFlush
```
default ChannelFuture writeAndFlush(Object msg,
                                    ChannelPromise promise)
```
    Description copied from interface: ChannelOutboundInvoker
    
    Shortcut for call ChannelOutboundInvoker.write(Object, ChannelPromise) and ChannelOutboundInvoker.flush().
    
    Specified by:
    
    writeAndFlush in interface ChannelOutboundInvoker
  - write
```
default ChannelFuture write(Object msg,
                            ChannelPromise promise)
```
    Description copied from interface: ChannelOutboundInvoker
    
    Request to write a message via this ChannelHandlerContext through the ChannelPipeline. This method will not request to actual flush, so be sure to call ChannelOutboundInvoker.flush() once you want to request to flush all pending data to the actual transport.
    
    Specified by:
    
    write in interface ChannelOutboundInvoker
  - write
```
default ChannelFuture write(Object msg)
```
    Description copied from interface: ChannelOutboundInvoker
    
    Request to write a message via this ChannelHandlerContext through the ChannelPipeline. This method will not request to actual flush, so be sure to call ChannelOutboundInvoker.flush() once you want to request to flush all pending data to the actual transport.
    
    Specified by:
    
    write in interface ChannelOutboundInvoker
  - deregister
```
default ChannelFuture deregister(ChannelPromise promise)
```
    Description copied from interface: ChannelOutboundInvoker
    
    Request to deregister 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.
    
    Specified by:
    
    deregister in interface ChannelOutboundInvoker
  - close
```
default ChannelFuture close(ChannelPromise promise)
```
    Description copied from interface: ChannelOutboundInvoker
    
    Request to close the 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.
    
    Specified by:
    
    close in interface ChannelOutboundInvoker
  - disconnect
```
default ChannelFuture disconnect(ChannelPromise promise)
```
    Description copied from interface: ChannelOutboundInvoker
    
    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. 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.
    
    Specified by:
    
    disconnect in interface ChannelOutboundInvoker
  - connect
```
default ChannelFuture connect(SocketAddress remoteAddress,
                              SocketAddress localAddress,
                              ChannelPromise promise)
```
    Description copied from interface: ChannelOutboundInvoker
    
    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. 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.
    
    Specified by:
    
    connect in interface ChannelOutboundInvoker
  - connect
```
default ChannelFuture connect(SocketAddress remoteAddress,
                              ChannelPromise promise)
```
    Description copied from interface: ChannelOutboundInvoker
    
    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. 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.
    
    Specified by:
    
    connect in interface ChannelOutboundInvoker
  - bind
```
default ChannelFuture bind(SocketAddress localAddress,
                           ChannelPromise promise)
```
    Description copied from interface: ChannelOutboundInvoker
    
    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. 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.
    
    Specified by:
    
    bind in interface ChannelOutboundInvoker
  - deregister
```
default ChannelFuture deregister()
```
    Description copied from interface: ChannelOutboundInvoker
    
    Request to deregister 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.
    
    Specified by:
    
    deregister in interface ChannelOutboundInvoker
  - close
```
default ChannelFuture close()
```
    Description copied from interface: ChannelOutboundInvoker
    
    Request to close the 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.
    
    Specified by:
    
    close in interface ChannelOutboundInvoker
  - disconnect
```
default ChannelFuture disconnect()
```
    Description copied from interface: ChannelOutboundInvoker
    
    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.
    This will result in having the ChannelOutboundHandler.disconnect(ChannelHandlerContext, ChannelPromise) method called of the next ChannelOutboundHandler contained in the ChannelPipeline of the Channel.
    
    Specified by:
    
    disconnect in interface ChannelOutboundInvoker
  - connect
```
default ChannelFuture connect(SocketAddress remoteAddress,
                              SocketAddress localAddress)
```
    Description copied from interface: ChannelOutboundInvoker
    
    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.
    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.
    
    Specified by:
    
    connect in interface ChannelOutboundInvoker
  - connect
```
default ChannelFuture connect(SocketAddress remoteAddress)
```
    Description copied from interface: ChannelOutboundInvoker
    
    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.
    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.
    
    Specified by:
    
    connect in interface ChannelOutboundInvoker
  - bind
```
default ChannelFuture bind(SocketAddress localAddress)
```
    Description copied from interface: ChannelOutboundInvoker
    
    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.
    This will result in having the ChannelOutboundHandler.bind(ChannelHandlerContext, SocketAddress, ChannelPromise) method called of the next ChannelOutboundHandler contained in the ChannelPipeline of the Channel.
    
    Specified by:
    
    bind in interface ChannelOutboundInvoker
  - newPromise
```
default ChannelPromise newPromise()
```
    Description copied from interface: ChannelOutboundInvoker
    
    Return a new ChannelPromise.
    
    Specified by:
    
    newPromise in interface ChannelOutboundInvoker
  - newProgressivePromise
```
default ChannelProgressivePromise newProgressivePromise()
```
    Description copied from interface: ChannelOutboundInvoker
    
    Return an new ChannelProgressivePromise
    
    Specified by:
    
    newProgressivePromise in interface ChannelOutboundInvoker
  - newSucceededFuture
```
default ChannelFuture newSucceededFuture()
```
    Description copied from interface: ChannelOutboundInvoker
    
    Create a new 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.
    
    Specified by:
    
    newSucceededFuture in interface ChannelOutboundInvoker
  - newFailedFuture
```
default ChannelFuture newFailedFuture(Throwable cause)
```
    Description copied from interface: ChannelOutboundInvoker
    
    Create a new 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.
    
    Specified by:
    
    newFailedFuture in interface ChannelOutboundInvoker
  - 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 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.
    Be aware this is an expert feature and should be used with care!
    
    Specified by:
    
    voidPromise in interface ChannelOutboundInvoker

Interface Channel

All I/O operations are asynchronous.

Channels are hierarchical

Downcast to access transport-specific operations

Release resources

Nested Class Summary

Method Summary

Methods inherited from interface io.netty.util.AttributeMap

Methods inherited from interface java.lang.Comparable

Method Detail

id

eventLoop

parent

config

isOpen

isRegistered

isActive

metadata

localAddress

remoteAddress

closeFuture

isWritable

bytesBeforeUnwritable

bytesBeforeWritable

unsafe

pipeline

alloc

getOption

setOption

read

flush

writeAndFlush

writeAndFlush

write

write

deregister

close

disconnect

connect

connect

bind

deregister

close

disconnect

connect

connect

bind

newPromise

newProgressivePromise

newSucceededFuture

newFailedFuture

voidPromise