org.jboss.netty.channel

## Interface ChannelEvent

- All Known Subinterfaces:
    ChannelStateEvent, ChildChannelStateEvent, ExceptionEvent, IdleStateEvent, MessageEvent, WriteCompletionEvent
  All Known Implementing Classes:
    DefaultChildChannelStateEvent, DefaultExceptionEvent, DefaultIdleStateEvent, DefaultWriteCompletionEvent, DownstreamChannelStateEvent, DownstreamMessageEvent, UpstreamChannelStateEvent, UpstreamMessageEvent

      public interface ChannelEvent

  An I/O event or I/O request associated with a `Channel`.

  A `ChannelEvent` is handled by a series of `ChannelHandler`s in a `ChannelPipeline`.

  ### Upstream events and downstream events, and their interpretation

  Every event is either an upstream event or a downstream event. If an event flows forward from the first handler to the last handler in a `ChannelPipeline`, we call it an upstream event and say "an event goes upstream." If an event flows backward from the last handler to the first handler in a `ChannelPipeline`, we call it a downstream event and say "an event goes downstream." (Please refer to the diagram in `ChannelPipeline` for more explanation.)

  When your server receives a message from a client, the event associated with the received message is an upstream event. When your server sends a message or reply to the client, the event associated with the write request is a downstream event. The same rule applies for the client side. If your client sent a request to the server, it means your client triggered a downstream event. If your client received a response from the server, it means your client will be notified with an upstream event. Upstream events are often the result of inbound operations such as `InputStream.read(byte[])`, and downstream events are the request for outbound operations such as `OutputStream.write(byte[])`, `Socket.connect(SocketAddress)`, and `Socket.close()`.

  #### Upstream events

  Event name | Event type and condition | Meaning
  --- | --- | ---
  `"messageReceived"` | `MessageEvent` | a message object (e.g. `ChannelBuffer`) was received from a remote peer
  `"exceptionCaught"` | `ExceptionEvent` | an exception was raised by an I/O thread or a `ChannelHandler`
  `"channelOpen"` | `ChannelStateEvent` (state = `OPEN`, value = `true`) | a `Channel` is open, but not bound nor connected | Be aware that this event is fired from within the Boss-Thread so you should not execute any heavy operation in there as it will block the dispatching to other workers!
  `"channelClosed"` | `ChannelStateEvent` (state = `OPEN`, value = `false`) | a `Channel` was closed and all its related resources were released
  `"channelBound"` | `ChannelStateEvent` (state = `BOUND`, value = `SocketAddress`) | a `Channel` is open and bound to a local address, but not connected. | Be aware that this event is fired from within the Boss-Thread so you should not execute any heavy operation in there as it will block the dispatching to other workers!
  `"channelUnbound"` | `ChannelStateEvent` (state = `BOUND`, value = `null`) | a `Channel` was unbound from the current local address
  `"channelConnected"` | `ChannelStateEvent` (state = `CONNECTED`, value = `SocketAddress`) | a `Channel` is open, bound to a local address, and connected to a remote address | Be aware that this event is fired from within the Boss-Thread so you should not execute any heavy operation in there as it will block the dispatching to other workers!
  `"writeComplete"` | `WriteCompletionEvent` | something has been written to a remote peer
  `"channelDisconnected"` | `ChannelStateEvent` (state = `CONNECTED`, value = `null`) | a `Channel` was disconnected from its remote peer
  `"channelInterestChanged"` | `ChannelStateEvent` (state = `INTEREST_OPS`, no value) | a `Channel`'s `interestOps` was changed

  These two additional event types are used only for a parent channel which can have a child channel (e.g. `ServerSocketChannel`).

  Event name | Event type and condition | Meaning
  --- | --- | ---
  `"childChannelOpen"` | `ChildChannelStateEvent` (`childChannel.isOpen() = true`) | a child `Channel` was open (e.g. a server channel accepted a connection.)
  `"childChannelClosed"` | `ChildChannelStateEvent` (`childChannel.isOpen() = false`) | a child `Channel` was closed (e.g. the accepted connection was closed.)

  #### Downstream events

  Event name | Event type and condition | Meaning
  --- | --- | ---
  `"write"` | `MessageEvent` | Send a message to the `Channel`.
  `"bind"` | `ChannelStateEvent` (state = `BOUND`, value = `SocketAddress`) | Bind the `Channel` to the specified local address.
  `"unbind"` | `ChannelStateEvent` (state = `BOUND`, value = `null`) | Unbind the `Channel` from the current local address.
  `"connect"` | `ChannelStateEvent` (state = `CONNECTED`, value = `SocketAddress`) | Connect the `Channel` to the specified remote address.
  `"disconnect"` | `ChannelStateEvent` (state = `CONNECTED`, value = `null`) | Disconnect the `Channel` from the current remote address.
  `"close"` | `ChannelStateEvent` (state = `OPEN`, value = `false`) | Close the `Channel`.

  Other event types and conditions which were not addressed here will be ignored and discarded. Please note that there's no `"open"` in the table. It is because a `Channel` is always open when it is created by a `ChannelFactory`.

  ### Additional resources worth reading

  Please refer to the `ChannelHandler` and `ChannelPipeline` documentation to find out how an event flows in a pipeline and how to handle the event in your application.

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `Channel` | `getChannel()` Returns the `Channel` which is associated with this event.
    `ChannelFuture` | `getFuture()` Returns the `ChannelFuture` which is associated with this event.

- - ### Method Detail

    - #### getChannel

          Channel getChannel()

      Returns the `Channel` which is associated with this event.

    - #### getFuture

          ChannelFuture getFuture()

      Returns the `ChannelFuture` which is associated with this event. If this event is an upstream event, this method will always return a `SucceededChannelFuture` because the event has occurred already. If this event is a downstream event (i.e. I/O request), the returned future will be notified when the I/O request succeeds or fails.

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