org.jboss.netty.channel
Interface ChannelHandlerContext

public interface ChannelHandlerContext

Provides the properties and operations which are specific to a ChannelHandler and the ChannelPipeline it belongs to. Via a ChannelHandlerContext, a ChannelHandler can send a ChannelEvent upstream or downstream, modify the behavior of the pipeline, or store the information (attachment) which is specific to the handler.

         n = the number of the handler entries in a pipeline

 +---------+ 1 .. 1 +----------+ 1    n +---------+ n    m +---------+
 | Channel |--------| Pipeline |--------| Context |--------| Handler |
 +---------+        +----------+        +----+----+        +----+----+
                                             | 1..1             |
                                       +-----+------+           |
                                       | Attachment |<----------+
                                       +------------+    stores
 

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 ChannelHandlerContexts if it is added to one or more ChannelPipelines 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 SimpleUpstreamChannelHandler {

   // This handler will receive a sequence of increasing integers starting
   // from 1.
   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, and how they flow in a pipeline.

Version:

$Rev: 1726 $, $Date: 2009-09-10 13:25:05 +0900 (목, 10 9 2009) $

Author:

The Netty Project (netty-dev@lists.jboss.org), Trustin Lee (tlee@redhat.com)

Method Summary

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.

As an alternative, you might want to use a ChannelLocal variable or a ConcurrentMap whose key is ChannelHandlerContext. Please refer to ChannelPipelineCoverage for the detailed examples.

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.

As an alternative, you might want to use a ChannelLocal variable or a ConcurrentMap whose key is ChannelHandlerContext. Please refer to ChannelPipelineCoverage for the detailed examples.