public interface ChannelHandler
ChannelEvent
, and sends a
ChannelEvent
to the next handler in a ChannelPipeline
.
ChannelHandler
itself does not provide any method. To handle a
ChannelEvent
you need to implement its sub-interfaces. There are
two sub-interfaces which handles a received event, one for upstream events
and the other for downstream events:
ChannelUpstreamHandler
handles and intercepts an upstream ChannelEvent
.ChannelDownstreamHandler
handles and intercepts a downstream ChannelEvent
.
A ChannelHandler
is provided with a ChannelHandlerContext
object. A ChannelHandler
is supposed to interact with the
ChannelPipeline
it belongs to via a context object. Using the
context object, the ChannelHandler
can pass events upstream or
downstream, modify the pipeline dynamically, or store the information
(attachment) which is specific to the handler.
ChannelHandler
often needs to store some stateful information.
The simplest and recommended approach is to use member variables:
public class DataServerHandler extendsBecause the handler instance has a state variable which is dedicated to one connection, you have to create a new handler instance for each new channel to avoid a race condition where a unauthenticated client can get the confidential information:SimpleChannelHandler
{ private boolean loggedIn;@Override
public void messageReceived(ChannelHandlerContext
ctx,MessageEvent
e) {Channel
ch = e.getChannel(); Object o = e.getMessage(); if (o instanceof LoginMessage) { authenticate((LoginMessage) o); loggedIn = true; } else (o instanceof GetDataMessage) { if (loggedIn) { ch.write(fetchSecret((GetDataMessage) o)); } else { fail(); } } } ... }
// Create a new handler instance per channel. // SeeBootstrap.setPipelineFactory(ChannelPipelineFactory)
. public class DataServerPipelineFactory implementsChannelPipelineFactory
{ publicChannelPipeline
getPipeline() { returnChannels
.pipeline(new DataServerHandler()); } }
ChannelHandlerContext
:
Now that the state of the handler is stored as an attachment, you can add the same handler instance to different pipelines:@Sharable
public class DataServerHandler extendsSimpleChannelHandler
{@Override
public void messageReceived(ChannelHandlerContext
ctx,MessageEvent
e) {Channel
ch = e.getChannel(); Object o = e.getMessage(); if (o instanceof LoginMessage) { authenticate((LoginMessage) o); ctx.setAttachment(true); } else (o instanceof GetDataMessage) { if (Boolean.TRUE.equals(ctx.getAttachment())) { ch.write(fetchSecret((GetDataMessage) o)); } else { fail(); } } } ... }
public class DataServerPipelineFactory implementsChannelPipelineFactory
{ private static final DataServerHandler SHARED = new DataServerHandler(); publicChannelPipeline
getPipeline() { returnChannels
.pipeline(SHARED); } }
ChannelLocal
ChannelLocal
:
public final class DataServerState { public static finalChannelLocal
<Boolean> loggedIn = newChannelLocal
<>() { protected Boolean initialValue(Channel channel) { return false; } } ... }@Sharable
public class DataServerHandler extendsSimpleChannelHandler
{@Override
public void messageReceived(ChannelHandlerContext
ctx,MessageEvent
e) { Channel ch = e.getChannel(); Object o = e.getMessage(); if (o instanceof LoginMessage) { authenticate((LoginMessage) o); DataServerState.loggedIn.set(ch, true); } else (o instanceof GetDataMessage) { if (DataServerState.loggedIn.get(ch)) { ctx.getChannel().write(fetchSecret((GetDataMessage) o)); } else { fail(); } } } ... } // Print the remote addresses of the authenticated clients:ChannelGroup
allClientChannels = ...; for (Channel
ch: allClientChannels) { if (DataServerState.loggedIn.get(ch)) { System.out.println(ch.getRemoteAddress()); } }
@Sharable
annotation
In the examples above which used an attachment or a ChannelLocal
,
you might have noticed the @Sharable
annotation.
If a ChannelHandler
is annotated with the @Sharable
annotation, it means you can create an instance of the handler just once and
add it to one or more ChannelPipeline
s multiple times without
a race condition.
If this annotation is not specified, you have to create a new handler instance every time you add it to a pipeline because it has unshared state such as member variables.
This annotation is provided for documentation purpose, just like the JCIP annotations.
Please refer to the 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 | Interface and Description |
---|---|
static interface |
ChannelHandler.Sharable
Indicates that the same instance of the annotated
ChannelHandler
can be added to one or more ChannelPipeline s multiple times
without a race condition. |
Copyright © 2008-2014 The Netty Project. All Rights Reserved.