Package org.jboss.netty.channel
Interface ChannelHandlerContext
-
public interface ChannelHandlerContext
Enables aChannelHandler
to interact with itsChannelPipeline
and other handlers. A handler can send aChannelEvent
upstream or downstream, modify theChannelPipeline
it belongs to dynamically.Sending an event
You can send or forward aChannelEvent
to the closest handler in the sameChannelPipeline
by callingsendUpstream(ChannelEvent)
orsendDownstream(ChannelEvent)
. Please refer toChannelPipeline
to understand how an event flows.Modifying a pipeline
You can get theChannelPipeline
your handler belongs to by callinggetPipeline()
. A non-trivial application could insert, remove, or replace handlers in the pipeline dynamically in runtime.Retrieving for later use
You can keep theChannelHandlerContext
for later use, such as triggering an event outside the handler methods, even from a different thread.public class MyHandler extends
SimpleChannelHandler
implementsLifeCycleAwareChannelHandler
{ privateChannelHandlerContext
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)
andgetAttachment()
allow you to store and access stateful information that is related with a handler and its context. Please refer toChannelHandler
to learn various recommended ways to manage stateful information.A handler can have more than one context
Please note that aChannelHandler
instance can be added to more than oneChannelPipeline
. It means a singleChannelHandler
instance can have more than oneChannelHandlerContext
and therefore the single instance can be invoked with differentChannelHandlerContext
s if it is added to one or moreChannelPipeline
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
, andChannelPipeline
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
All Methods Instance Methods Abstract Methods Modifier and Type Method Description boolean
canHandleDownstream()
boolean
canHandleUpstream()
Object
getAttachment()
Retrieves an object which isattached
to this context.Channel
getChannel()
Returns theChannel
that theChannelPipeline
belongs to.ChannelHandler
getHandler()
Returns theChannelHandler
that this context object is serving.String
getName()
Returns the name of theChannelHandler
in theChannelPipeline
.ChannelPipeline
getPipeline()
Returns theChannelPipeline
that theChannelHandler
belongs to.void
sendDownstream(ChannelEvent e)
Sends the specifiedChannelEvent
to theChannelDownstreamHandler
which is placed in the closest downstream from the handler associated with this context.void
sendUpstream(ChannelEvent e)
Sends the specifiedChannelEvent
to theChannelUpstreamHandler
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 theChannelHandler
which is associated with this context.
-
-
-
Method Detail
-
getChannel
Channel getChannel()
Returns theChannel
that theChannelPipeline
belongs to. This method is a shortcut to getPipeline().getChannel().
-
getPipeline
ChannelPipeline getPipeline()
Returns theChannelPipeline
that theChannelHandler
belongs to.
-
getName
String getName()
Returns the name of theChannelHandler
in theChannelPipeline
.
-
getHandler
ChannelHandler getHandler()
Returns theChannelHandler
that this context object is serving.
-
canHandleUpstream
boolean canHandleUpstream()
-
canHandleDownstream
boolean canHandleDownstream()
-
sendUpstream
void sendUpstream(ChannelEvent e)
Sends the specifiedChannelEvent
to theChannelUpstreamHandler
which is placed in the closest upstream from the handler associated with this context. It is recommended to use the shortcut methods inChannels
rather than calling this method directly.
-
sendDownstream
void sendDownstream(ChannelEvent e)
Sends the specifiedChannelEvent
to theChannelDownstreamHandler
which is placed in the closest downstream from the handler associated with this context. It is recommended to use the shortcut methods inChannels
rather than calling this method directly.
-
getAttachment
Object getAttachment()
Retrieves an object which isattached
to this context.- Returns:
null
if no object was attached ornull
was attached
-
setAttachment
void setAttachment(Object attachment)
Attaches an object to this context to store a stateful information specific to theChannelHandler
which is associated with this context.
-
-