Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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

    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.

Version:
  $Rev: 2244 $, $Date: 2010-04-16 14:07:37 +0900 (Fri, 16 Apr 2010) $
Author:
  The Netty Project, Trustin Lee

Field Summary
`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
`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.
`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.
`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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2008-2010 JBoss, a division of Red Hat, Inc.. All Rights Reserved.