org.jboss.netty.channel

## Interface Channel

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
`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
`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 `ChannelEvent`s 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