org.jboss.netty.channel

## Interface ChannelHandlerContext

-     public interface ChannelHandlerContext

  Enables a `ChannelHandler` to interact with its `ChannelPipeline` and other handlers. A handler can send a `ChannelEvent` upstream or downstream, modify the `ChannelPipeline` it belongs to dynamically.

  ### Sending an event

  You can send or forward a `ChannelEvent` to the closest handler in the same `ChannelPipeline` by calling `sendUpstream(ChannelEvent)` or `sendDownstream(ChannelEvent)`. Please refer to `ChannelPipeline` to understand how an event flows.

  ### Modifying a pipeline

  You can get the `ChannelPipeline` your handler belongs to by calling `getPipeline()`. A non-trivial application could insert, remove, or replace handlers in the pipeline dynamically in runtime.

  ### Retrieving for later use

  You can keep the `ChannelHandlerContext` for later use, such as triggering an event outside the handler methods, even from a different thread.

       public class MyHandler extends SimpleChannelHandler
                              implements LifeCycleAwareChannelHandler {

           private ChannelHandlerContext ctx;

           public void beforeAdd(ChannelHandlerContext ctx) {
               this.ctx = ctx;
           }

           public void login(String username, password) {
               Channels.write(
                       this.ctx,
                       Channels.succeededFuture(this.ctx.getChannel()),
                       new LoginMessage(username, password));
           }
           ...
       }

  ### Storing stateful information

  `setAttachment(Object)` and `getAttachment()` allow you to store and access stateful information that is related with a handler and its context. Please refer to `ChannelHandler` to learn various recommended ways to manage stateful information.

  ### A handler can have more than one context

  Please note that a `ChannelHandler` instance can be added to more than one `ChannelPipeline`. It means a single `ChannelHandler` instance can have more than one `ChannelHandlerContext` and therefore the single instance can be invoked with different `ChannelHandlerContext`s if it is added to one or more `ChannelPipeline`s more than once.

  For example, the following handler will have as many independent attachments as how many times it is added to pipelines, regardless if it is added to the same pipeline multiple times or added to different pipelines multiple times:

       public class FactorialHandler extends SimpleChannelHandler {

         // This handler will receive a sequence of increasing integers starting
         // from 1.
         @Override
         public void messageReceived(ChannelHandlerContext ctx, MessageEvent evt) {
           Integer a = (Integer) ctx.getAttachment();
           Integer b = (Integer) evt.getMessage();

           if (a == null) {
             a = 1;
           }

           ctx.setAttachment(Integer.valueOf(a * b));
         }
       }

       // Different context objects are given to "f1", "f2", "f3", and "f4" even if
       // they refer to the same handler instance.  Because the FactorialHandler
       // stores its state in a context object (as an attachment), the factorial is
       // calculated correctly 4 times once the two pipelines (p1 and p2) are active.
       FactorialHandler fh = new FactorialHandler();

       ChannelPipeline p1 = Channels.pipeline();
       p1.addLast("f1", fh);
       p1.addLast("f2", fh);

       ChannelPipeline p2 = Channels.pipeline();
       p2.addLast("f3", fh);
       p2.addLast("f4", fh);

  ### Additional resources worth reading

  Please refer to the `ChannelHandler`, `ChannelEvent`, and `ChannelPipeline` to find out what a upstream event and a downstream event are, what fundamental differences they have, how they flow in a pipeline, and how to handle the event in your application.

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `canHandleDownstream()` Returns `true` if and only if the `ChannelHandler` is an instance of `ChannelDownstreamHandler`.
    `boolean` | `canHandleUpstream()` Returns `true` if and only if the `ChannelHandler` is an instance of `ChannelUpstreamHandler`.
    `Object` | `getAttachment()` Retrieves an object which is `attached` to this context.
    `Channel` | `getChannel()` Returns the `Channel` that the `ChannelPipeline` belongs to.
    `ChannelHandler` | `getHandler()` Returns the `ChannelHandler` that this context object is serving.
    `String` | `getName()` Returns the name of the `ChannelHandler` in the `ChannelPipeline`.
    `ChannelPipeline` | `getPipeline()` Returns the `ChannelPipeline` that the `ChannelHandler` belongs to.
    `void` | `sendDownstream(ChannelEvent e)` Sends the specified `ChannelEvent` to the `ChannelDownstreamHandler` which is placed in the closest downstream from the handler associated with this context.
    `void` | `sendUpstream(ChannelEvent e)` Sends the specified `ChannelEvent` to the `ChannelUpstreamHandler` which is placed in the closest upstream from the handler associated with this context.
    `void` | `setAttachment(Object attachment)` Attaches an object to this context to store a stateful information specific to the `ChannelHandler` which is associated with this context.

- - ### Method Detail

    - #### getChannel

          Channel getChannel()

      Returns the `Channel` that the `ChannelPipeline` belongs to. This method is a shortcut to `getPipeline().getChannel()`.

    - #### getPipeline

          ChannelPipeline getPipeline()

      Returns the `ChannelPipeline` that the `ChannelHandler` belongs to.

    - #### getName

          String getName()

      Returns the name of the `ChannelHandler` in the `ChannelPipeline`.

    - #### getHandler

          ChannelHandler getHandler()

      Returns the `ChannelHandler` that this context object is serving.

    - #### canHandleUpstream

          boolean canHandleUpstream()

      Returns `true` if and only if the `ChannelHandler` is an instance of `ChannelUpstreamHandler`.

    - #### canHandleDownstream

          boolean canHandleDownstream()

      Returns `true` if and only if the `ChannelHandler` is an instance of `ChannelDownstreamHandler`.

    - #### sendUpstream

          void sendUpstream(ChannelEvent e)

      Sends the specified `ChannelEvent` to the `ChannelUpstreamHandler` which is placed in the closest upstream from the handler associated with this context. It is recommended to use the shortcut methods in `Channels` rather than calling this method directly.

    - #### sendDownstream

          void sendDownstream(ChannelEvent e)

      Sends the specified `ChannelEvent` to the `ChannelDownstreamHandler` which is placed in the closest downstream from the handler associated with this context. It is recommended to use the shortcut methods in `Channels` rather than calling this method directly.

    - #### getAttachment

          Object getAttachment()

      Retrieves an object which is `attached` to this context.
      Returns:
        `null` if no object was attached or `null` was attached

    - #### setAttachment

          void setAttachment(Object attachment)

      Attaches an object to this context to store a stateful information specific to the `ChannelHandler` which is associated with this context.

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