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

Copyright © 2008-2012 The Netty Project. All Rights Reserved.