
public interface ChannelHandlerContext
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);
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.
| Modifier and Type | Method and Description |
|---|---|
boolean |
canHandleDownstream()
|
boolean |
canHandleUpstream()
|
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. |
Channel getChannel()
Channel that the ChannelPipeline belongs to.
This method is a shortcut to getPipeline().getChannel().ChannelPipeline getPipeline()
ChannelPipeline that the ChannelHandler
belongs to.String getName()
ChannelHandler in the
ChannelPipeline.ChannelHandler getHandler()
ChannelHandler that this context object is
serving.boolean canHandleUpstream()
boolean canHandleDownstream()
void sendUpstream(ChannelEvent e)
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.void sendDownstream(ChannelEvent e)
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.Object getAttachment()
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.
null if no object was attached or
null was attachedvoid setAttachment(Object attachment)
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.
Copyright © 2008-2013 JBoss, by Red Hat. All Rights Reserved.