Package org.jboss.netty.channel
Interface ChannelHandlerContext
- All Known Implementing Classes:
DefaultChannelPipeline.DefaultChannelHandlerContext
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 aChannelEvent
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 theChannelPipeline
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 theChannelHandlerContext
for later use, such as
triggering an event outside the handler methods, even from a different thread.
public class MyHandler extendsSimpleChannelHandler
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)
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 aChannelHandler
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 extendsSimpleChannelHandler
{ // 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
Modifier and TypeMethodDescriptionboolean
boolean
Retrieves an object which isattached
to this context.Returns theChannel
that theChannelPipeline
belongs to.Returns theChannelHandler
that this context object is serving.getName()
Returns the name of theChannelHandler
in theChannelPipeline
.Returns theChannelPipeline
that theChannelHandler
belongs to.void
Sends the specifiedChannelEvent
to theChannelDownstreamHandler
which is placed in the closest downstream from the handler associated with this context.void
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 Details
-
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
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
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
Attaches an object to this context to store a stateful information specific to theChannelHandler
which is associated with this context.
-