1 /*
2 * Copyright 2009 Red Hat, Inc.
3 *
4 * Red Hat licenses this file to you under the Apache License, version 2.0
5 * (the "License"); you may not use this file except in compliance with the
6 * License. You may obtain a copy of the License at:
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
12 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13 * License for the specific language governing permissions and limitations
14 * under the License.
15 */
16 package org.jboss.netty.channel;
17
18 import java.lang.annotation.Documented;
19 import java.lang.annotation.ElementType;
20 import java.lang.annotation.Inherited;
21 import java.lang.annotation.Retention;
22 import java.lang.annotation.RetentionPolicy;
23 import java.lang.annotation.Target;
24
25 import org.jboss.netty.bootstrap.Bootstrap;
26 import org.jboss.netty.channel.group.ChannelGroup;
27
28 /**
29 * Handles or intercepts a {@link ChannelEvent}, and sends a
30 * {@link ChannelEvent} to the next handler in a {@link ChannelPipeline}.
31 *
32 * <h3>Sub-types</h3>
33 * <p>
34 * {@link ChannelHandler} itself does not provide any method. To handle a
35 * {@link ChannelEvent} you need to implement its sub-interfaces. There are
36 * two sub-interfaces which handles a received event, one for upstream events
37 * and the other for downstream events:
38 * <ul>
39 * <li>{@link ChannelUpstreamHandler} handles and intercepts an upstream {@link ChannelEvent}.</li>
40 * <li>{@link ChannelDownstreamHandler} handles and intercepts a downstream {@link ChannelEvent}.</li>
41 * </ul>
42 *
43 * You will also find more detailed explanation from the documentation of
44 * each sub-interface on how an event is interpreted when it goes upstream and
45 * downstream respectively.
46 *
47 * <h3>The context object</h3>
48 * <p>
49 * A {@link ChannelHandler} is provided with a {@link ChannelHandlerContext}
50 * object. A {@link ChannelHandler} is supposed to interact with the
51 * {@link ChannelPipeline} it belongs to via a context object. Using the
52 * context object, the {@link ChannelHandler} can pass events upstream or
53 * downstream, modify the pipeline dynamically, or store the information
54 * (attachment) which is specific to the handler.
55 *
56 * <h3>State management</h3>
57 *
58 * A {@link ChannelHandler} often needs to store some stateful information.
59 * The simplest and recommended approach is to use member variables:
60 * <pre>
61 * public class DataServerHandler extends {@link SimpleChannelHandler} {
62 *
63 * <b>private boolean loggedIn;</b>
64 *
65 * {@code @Override}
66 * public void messageReceived({@link ChannelHandlerContext} ctx, {@link MessageEvent} e) {
67 * {@link Channel} ch = e.getChannel();
68 * Object o = e.getMessage();
69 * if (o instanceof LoginMessage) {
70 * authenticate((LoginMessage) o);
71 * <b>loggedIn = true;</b>
72 * } else (o instanceof GetDataMessage) {
73 * if (<b>loggedIn</b>) {
74 * ch.write(fetchSecret((GetDataMessage) o));
75 * } else {
76 * fail();
77 * }
78 * }
79 * }
80 * ...
81 * }
82 * </pre>
83 * Because the handler instance has a state variable which is dedicated to
84 * one connection, you have to create a new handler instance for each new
85 * channel to avoid a race condition where a unauthenticated client can get
86 * the confidential information:
87 * <pre>
88 * // Create a new handler instance per channel.
89 * // See {@link Bootstrap#setPipelineFactory(ChannelPipelineFactory)}.
90 * public class DataServerPipelineFactory implements {@link ChannelPipelineFactory} {
91 * public {@link ChannelPipeline} getPipeline() {
92 * return {@link Channels}.pipeline(<b>new DataServerHandler()</b>);
93 * }
94 * }
95 * </pre>
96 *
97 * <h4>Using an attachment</h4>
98 *
99 * Although it's recommended to use member variables to store the state of a
100 * handler, for some reason you might not want to create many handler instances.
101 * In such a case, you can use an <em>attachment</em> which is provided by
102 * {@link ChannelHandlerContext}:
103 * <pre>
104 * {@code @Sharable}
105 * public class DataServerHandler extends {@link SimpleChannelHandler} {
106 *
107 * {@code @Override}
108 * public void messageReceived({@link ChannelHandlerContext} ctx, {@link MessageEvent} e) {
109 * {@link Channel} ch = e.getChannel();
110 * Object o = e.getMessage();
111 * if (o instanceof LoginMessage) {
112 * authenticate((LoginMessage) o);
113 * <b>ctx.setAttachment(true)</b>;
114 * } else (o instanceof GetDataMessage) {
115 * if (<b>Boolean.TRUE.equals(ctx.getAttachment())</b>) {
116 * ch.write(fetchSecret((GetDataMessage) o));
117 * } else {
118 * fail();
119 * }
120 * }
121 * }
122 * ...
123 * }
124 * </pre>
125 * Now that the state of the handler is stored as an attachment, you can add the
126 * same handler instance to different pipelines:
127 * <pre>
128 * public class DataServerPipelineFactory implements {@link ChannelPipelineFactory} {
129 *
130 * private static final DataServerHandler <b>SHARED</b> = new DataServerHandler();
131 *
132 * public {@link ChannelPipeline} getPipeline() {
133 * return {@link Channels}.pipeline(<b>SHARED</b>);
134 * }
135 * }
136 * </pre>
137 *
138 * <h4>Using a {@link ChannelLocal}</h4>
139 *
140 * If you have a state variable which needs to be accessed either from other
141 * handlers or outside handlers, you can use {@link ChannelLocal}:
142 * <pre>
143 * public final class DataServerState {
144 *
145 * <b>public static final {@link ChannelLocal}<Boolean> loggedIn = new {@link ChannelLocal}<Boolean>() {
146 * protected Boolean initialValue(Channel channel) {
147 * return false;
148 * }
149 * }</b>
150 * ...
151 * }
152 *
153 * {@code @Sharable}
154 * public class DataServerHandler extends {@link SimpleChannelHandler} {
155 *
156 * {@code @Override}
157 * public void messageReceived({@link ChannelHandlerContext} ctx, {@link MessageEvent} e) {
158 * Channel ch = e.getChannel();
159 * Object o = e.getMessage();
160 * if (o instanceof LoginMessage) {
161 * authenticate((LoginMessage) o);
162 * <b>DataServerState.loggedIn.set(ch, true);</b>
163 * } else (o instanceof GetDataMessage) {
164 * if (<b>DataServerState.loggedIn.get(ch)</b>) {
165 * ctx.getChannel().write(fetchSecret((GetDataMessage) o));
166 * } else {
167 * fail();
168 * }
169 * }
170 * }
171 * ...
172 * }
173 *
174 * // Print the remote addresses of the authenticated clients:
175 * {@link ChannelGroup} allClientChannels = ...;
176 * for ({@link Channel} ch: allClientChannels) {
177 * if (<b>DataServerState.loggedIn.get(ch)</b>) {
178 * System.out.println(ch.getRemoteAddress());
179 * }
180 * }
181 * </pre>
182 *
183 * <h4>The {@code @Sharable} annotation</h4>
184 * <p>
185 * In the examples above which used an attachment or a {@link ChannelLocal},
186 * you might have noticed the {@code @Sharable} annotation.
187 * <p>
188 * If a {@link ChannelHandler} is annotated with the {@code @Sharable}
189 * annotation, it means you can create an instance of the handler just once and
190 * add it to one or more {@link ChannelPipeline}s multiple times without
191 * a race condition.
192 * <p>
193 * If this annotation is not specified, you have to create a new handler
194 * instance every time you add it to a pipeline because it has unshared state
195 * such as member variables.
196 * <p>
197 * This annotation is provided for documentation purpose, just like
198 * <a href="http://www.javaconcurrencyinpractice.com/annotations/doc/">the JCIP annotations</a>.
199 *
200 * <h3>Additional resources worth reading</h3>
201 * <p>
202 * Please refer to the {@link ChannelEvent} and {@link ChannelPipeline} to find
203 * out what a upstream event and a downstream event are, what fundamental
204 * differences they have, and how they flow in a pipeline.
205 *
206 * @author <a href="http://www.jboss.org/netty/">The Netty Project</a>
207 * @author <a href="http://gleamynode.net/">Trustin Lee</a>
208 *
209 * @version $Rev: 2152 $, $Date: 2010-02-17 17:22:45 +0900 (Wed, 17 Feb 2010) $
210 *
211 * @apiviz.landmark
212 * @apiviz.exclude ^org\.jboss\.netty\.handler\..*$
213 */
214 public interface ChannelHandler {
215
216 /**
217 * Indicates that the same instance of the annotated {@link ChannelHandler}
218 * can be added to one or more {@link ChannelPipeline}s multiple times
219 * without a race condition.
220 * <p>
221 * If this annotation is not specified, you have to create a new handler
222 * instance every time you add it to a pipeline because it has unshared
223 * state such as member variables.
224 * <p>
225 * This annotation is provided for documentation purpose, just like
226 * <a href="http://www.javaconcurrencyinpractice.com/annotations/doc/">the JCIP annotations</a>.
227 *
228 * @author <a href="http://www.jboss.org/netty/">The Netty Project</a>
229 * @author <a href="http://gleamynode.net/">Trustin Lee</a>
230 * @version $Rev: 2152 $, $Date: 2010-02-17 17:22:45 +0900 (Wed, 17 Feb 2010) $
231 */
232 @Inherited
233 @Documented
234 @Target(ElementType.TYPE)
235 @Retention(RetentionPolicy.RUNTIME)
236 public @interface Sharable {
237 // no value
238 }
239 }