Channel (The Netty Project API Reference (3.7.1.Final))

All Superinterfaces:

Comparable<Channel>

All Known Subinterfaces:

DatagramChannel, LocalChannel, LocalServerChannel, ServerChannel, ServerSocketChannel, SocketChannel

All Known Implementing Classes:

AbstractChannel, AbstractServerChannel, NioDatagramChannel, NioSocketChannel
```
public interface Channel
extends 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 getParent().
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.
InterestOps

A Channel has a property called interestOps which is similar to that of NIO SelectionKey. It is represented as a bit field which is composed of the two flags.
- OP_READ - If set, a message sent by a remote peer will be read immediately. If unset, the message from the remote peer will not be read until the OP_READ flag is set again (i.e. read suspension).
- OP_WRITE - If set, a write request will not be sent to a remote peer until the OP_WRITE flag is cleared and the write request will be pending in a queue. If unset, the write request will be flushed out as soon as possible from the queue.
- OP_READ_WRITE - This is a combination of OP_READ and OP_WRITE, which means only write requests are suspended.
- OP_NONE - This is a combination of (NOT OP_READ) and (NOT OP_WRITE), which means only read operation is suspended.
You can set or clear the OP_READ flag to suspend and resume read operation via setReadable(boolean).
Please note that you cannot suspend or resume write operation just like you can set or clear OP_READ. The OP_WRITE flag is read only and provided simply as a mean to tell you if the size of pending write requests exceeded a certain threshold or not so that you don't issue too many pending writes that lead to an OutOfMemoryError. For example, the NIO socket transport uses the writeBufferLowWaterMark and writeBufferHighWaterMark properties in NioSocketChannelConfig to determine when to set or clear the OP_WRITE flag.

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`OP_NONE` The `interestOps` value which tells that only read operation has been suspended.
`static int`	`OP_READ` The `interestOps` value which tells that neither read nor write operation has been suspended.
`static int`	`OP_READ_WRITE` The `interestOps` value which tells that only write operation has been suspended.
`static int`	`OP_WRITE` The `interestOps` value which tells that both read and write operation has been suspended.

Method Summary

Methods
Modifier and Type	Method and Description
`ChannelFuture`	`bind(SocketAddress localAddress)` Binds this channel to the specified local address asynchronously.
`ChannelFuture`	`close()` Closes this channel asynchronously.
`ChannelFuture`	`connect(SocketAddress remoteAddress)` Connects this channel to the specified remote address asynchronously.
`ChannelFuture`	`disconnect()` Disconnects this channel from the current remote address asynchronously.
`Object`	`getAttachment()` Retrieves an object which is `attached` to this `Channel`.
`ChannelFuture`	`getCloseFuture()` Returns the `ChannelFuture` which will be notified when this channel is closed.
`ChannelConfig`	`getConfig()` Returns the configuration of this channel.
`ChannelFactory`	`getFactory()` Returns the `ChannelFactory` which created this channel.
`Integer`	`getId()` Returns the unique integer ID of this channel.
`int`	`getInterestOps()` Returns the current `interestOps` of this channel.
`SocketAddress`	`getLocalAddress()` Returns the local address where this channel is bound to.
`Channel`	`getParent()` Returns the parent of this channel.
`ChannelPipeline`	`getPipeline()` Returns the `ChannelPipeline` which handles `ChannelEvent`s associated with this channel.
`SocketAddress`	`getRemoteAddress()` Returns the remote address where this channel is connected to.
`boolean`	`isBound()` Returns `true` if and only if this channel is bound to a local address.
`boolean`	`isConnected()` Returns `true` if and only if this channel is connected to a remote address.
`boolean`	`isOpen()` Returns `true` if and only if this channel is open.
`boolean`	`isReadable()` Returns `true` if and only if the I/O thread will read a message from this channel.
`boolean`	`isWritable()` Returns `true` if and only if the I/O thread will perform the requested write operation immediately.
`void`	`setAttachment(Object attachment)` Attaches an object to this `Channel` to store a stateful information
`ChannelFuture`	`setInterestOps(int interestOps)` Changes the `interestOps` of this channel asynchronously.
`ChannelFuture`	`setReadable(boolean readable)` Suspends or resumes the read operation of the I/O thread asynchronously.
`ChannelFuture`	`unbind()` Unbinds this channel from the current local address asynchronously.
`ChannelFuture`	`write(Object message)` Sends a message to this channel asynchronously.
`ChannelFuture`	`write(Object message, SocketAddress remoteAddress)` Sends a message to this channel asynchronously.

Methods inherited from interface java.lang.Comparable
compareTo

- Field Detail
  - OP_NONE
```
static final int OP_NONE
```
    The interestOps value which tells that only read operation has been suspended.
    
    See Also:
    Constant Field Values
  - OP_READ
```
static final int OP_READ
```
    The interestOps value which tells that neither read nor write operation has been suspended.
    
    See Also:
    Constant Field Values
  - OP_WRITE
```
static final int OP_WRITE
```
    The interestOps value which tells that both read and write operation has been suspended.
    
    See Also:
    Constant Field Values
  - OP_READ_WRITE
```
static final int OP_READ_WRITE
```
    The interestOps value which tells that only write operation has been suspended.
    
    See Also:
    Constant Field Values
- Method Detail
  - getId
```
Integer getId()
```
    Returns the unique integer ID of this channel.
  - getFactory
```
ChannelFactory getFactory()
```
    Returns the ChannelFactory which created this channel.
  - getParent
```
Channel getParent()
```
    Returns the parent of this channel.
    
    Returns:
    the parent channel. null if this channel does not have a parent channel.
  - getConfig
```
ChannelConfig getConfig()
```
    Returns the configuration of this channel.
  - getPipeline
```
ChannelPipeline getPipeline()
```
    Returns the ChannelPipeline which handles ChannelEvents associated with this channel.
  - isOpen
```
boolean isOpen()
```
    Returns true if and only if this channel is open.
  - isBound
```
boolean isBound()
```
    Returns true if and only if this channel is bound to a local address.
  - isConnected
```
boolean isConnected()
```
    Returns true if and only if this channel is connected to a remote address.
  - getLocalAddress
```
SocketAddress getLocalAddress()
```
    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.
  - getRemoteAddress
```
SocketAddress getRemoteAddress()
```
    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 MessageEvent.getRemoteAddress() to determine the origination of the received message as this method will return null.
  - write
```
ChannelFuture write(Object message)
```
    Sends a message to this channel asynchronously. If this channel was created by a connectionless transport (e.g. DatagramChannel) and is not connected yet, you have to call write(Object, SocketAddress) instead. Otherwise, the write request will fail with NotYetConnectedException and an 'exceptionCaught' event will be triggered.
    
    Parameters:
    message - the message to write
    
    Returns:
    the ChannelFuture which will be notified when the write request succeeds or fails
    
    Throws:
    
    NullPointerException - if the specified message is null
  - write
```
ChannelFuture write(Object message,
                  SocketAddress remoteAddress)
```
    Sends a message to this channel asynchronously. It has an additional parameter that allows a user to specify where to send the specified message instead of this channel's current remote address. If this channel was created by a connectionless transport (e.g. DatagramChannel) and is not connected yet, you must specify non-null address. Otherwise, the write request will fail with NotYetConnectedException and an 'exceptionCaught' event will be triggered.
    
    Parameters:
    message - the message to write
    remoteAddress - where to send the specified message. This method is identical to write(Object) if null is specified here.
    
    Returns:
    the ChannelFuture which will be notified when the write request succeeds or fails
    
    Throws:
    
    NullPointerException - if the specified message is null
  - bind
```
ChannelFuture bind(SocketAddress localAddress)
```
    Binds this channel to the specified local address asynchronously.
    
    Parameters:
    localAddress - where to bind
    
    Returns:
    the ChannelFuture which will be notified when the bind request succeeds or fails
    
    Throws:
    
    NullPointerException - if the specified address is null
  - connect
```
ChannelFuture connect(SocketAddress remoteAddress)
```
    Connects this channel to the specified remote address asynchronously.
    
    Parameters:
    remoteAddress - where to connect
    
    Returns:
    the ChannelFuture which will be notified when the connection request succeeds or fails
    
    Throws:
    
    NullPointerException - if the specified address is null
  - disconnect
```
ChannelFuture disconnect()
```
    Disconnects this channel from the current remote address asynchronously.
    
    Returns:
    the ChannelFuture which will be notified when the disconnection request succeeds or fails
  - unbind
```
ChannelFuture unbind()
```
    Unbinds this channel from the current local address asynchronously.
    
    Returns:
    the ChannelFuture which will be notified when the unbind request succeeds or fails
  - close
```
ChannelFuture close()
```
    Closes this channel asynchronously. If this channel is bound or connected, it will be disconnected and unbound first. Once a channel is closed, it can not be open again. Calling this method on a closed channel has no effect. Please note that this method always returns the same future instance.
    
    Returns:
    the ChannelFuture which will be notified when the close request succeeds or fails
  - getCloseFuture
```
ChannelFuture getCloseFuture()
```
    Returns the ChannelFuture which will be notified when this channel is closed. This method always returns the same future instance.
  - getInterestOps
```
int getInterestOps()
```
    Returns the current interestOps of this channel.
    
    Returns:
    OP_NONE, OP_READ, OP_WRITE, or OP_READ_WRITE
  - isReadable
```
boolean isReadable()
```
    Returns true if and only if the I/O thread will read a message from this channel. This method is a shortcut to the following code:
```
 return (getInterestOps() & OP_READ) != 0;
 
```
  - 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. This method is a shortcut to the following code:
```
 return (getInterestOps() & OP_WRITE) == 0;
 
```
  - setInterestOps
```
ChannelFuture setInterestOps(int interestOps)
```
    Changes the interestOps of this channel asynchronously.
    
    Parameters:
    interestOps - the new interestOps
    
    Returns:
    the ChannelFuture which will be notified when the interestOps change request succeeds or fails
  - setReadable
```
ChannelFuture setReadable(boolean readable)
```
    Suspends or resumes the read operation of the I/O thread asynchronously. This method is a shortcut to the following code:
```
 int interestOps = getInterestOps();
 if (readable) {
     setInterestOps(interestOps | OP_READ);
 } else {
     setInterestOps(interestOps & ~OP_READ);
 }
 
```
    Parameters:
    readable - true to resume the read operation and false to suspend the read operation
    
    Returns:
    the ChannelFuture which will be notified when the interestOps change request succeeds or fails
  - getAttachment
```
Object getAttachment()
```
    Retrieves an object which is attached to this Channel.
    
    Returns:
    null if no object was attached or null was attached
  - setAttachment
```
void setAttachment(Object attachment)
```
    Attaches an object to this Channel to store a stateful information

Interface Channel

All I/O operations are asynchronous.

Channels are hierarchical

Downcast to access transport-specific operations

InterestOps

Field Summary

Method Summary

Methods inherited from interface java.lang.Comparable

Field Detail

OP_NONE

OP_READ

OP_WRITE

OP_READ_WRITE

Method Detail

getId

getFactory

getParent

getConfig

getPipeline

isOpen

isBound

isConnected

getLocalAddress

getRemoteAddress

write

write

bind

connect

disconnect

unbind

close

getCloseFuture

getInterestOps

isReadable

isWritable

setInterestOps

setReadable

getAttachment

setAttachment