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
19 /**
20 * Enables a {@link ChannelHandler} to interact with its {@link ChannelPipeline}
21 * and other handlers. A handler can send a {@link ChannelEvent} upstream or
22 * downstream, modify the {@link ChannelPipeline} it belongs to dynamically.
23 *
24 * <h3>Sending an event</h3>
25 *
26 * You can send or forward a {@link ChannelEvent} to the closest handler in the
27 * same {@link ChannelPipeline} by calling {@link #sendUpstream(ChannelEvent)}
28 * or {@link #sendDownstream(ChannelEvent)}. Please refer to
29 * {@link ChannelPipeline} to understand how an event flows.
30 *
31 * <h3>Modifying a pipeline</h3>
32 *
33 * You can get the {@link ChannelPipeline} your handler belongs to by calling
34 * {@link #getPipeline()}. A non-trivial application could insert, remove, or
35 * replace handlers in the pipeline dynamically in runtime.
36 *
37 * <h3>Retrieving for later use</h3>
38 *
39 * You can keep the {@link ChannelHandlerContext} for later use, such as
40 * triggering an event outside the handler methods, even from a different thread.
41 * <pre>
42 * public class MyHandler extends {@link SimpleChannelHandler}
43 * implements {@link LifeCycleAwareChannelHandler} {
44 *
45 * <b>private {@link ChannelHandlerContext} ctx;</b>
46 *
47 * public void beforeAdd({@link ChannelHandlerContext} ctx) {
48 * <b>this.ctx = ctx;</b>
49 * }
50 *
51 * public void login(String username, password) {
52 * {@link Channels}.write(
53 * <b>this.ctx</b>,
54 * {@link Channels}.succeededFuture(<b>this.ctx</t>.getChannel()</b>),
55 * new LoginMessage(username, password));
56 * }
57 * ...
58 * }
59 * </pre>
60 *
61 * <h3>Storing stateful information</h3>
62 *
63 * {@link #setAttachment(Object)} and {@link #getAttachment()} allow you to
64 * store and access stateful information that is related with a handler and its
65 * context. Please refer to {@link ChannelHandler} to learn various recommended
66 * ways to manage stateful information.
67 *
68 * <h3>A handler can have more than one context</h3>
69 *
70 * Please note that a {@link ChannelHandler} instance can be added to more than
71 * one {@link ChannelPipeline}. It means a single {@link ChannelHandler}
72 * instance can have more than one {@link ChannelHandlerContext} and therefore
73 * the single instance can be invoked with different
74 * {@link ChannelHandlerContext}s if it is added to one or more
75 * {@link ChannelPipeline}s more than once.
76 * <p>
77 * For example, the following handler will have as many independent attachments
78 * as how many times it is added to pipelines, regardless if it is added to the
79 * same pipeline multiple times or added to different pipelines multiple times:
80 * <pre>
81 * public class FactorialHandler extends {@link SimpleChannelHandler} {
82 *
83 * // This handler will receive a sequence of increasing integers starting
84 * // from 1.
85 * {@code @Override}
86 * public void messageReceived({@link ChannelHandlerContext} ctx, {@link MessageEvent} evt) {
87 * Integer a = (Integer) ctx.getAttachment();
88 * Integer b = (Integer) evt.getMessage();
89 *
90 * if (a == null) {
91 * a = 1;
92 * }
93 *
94 * ctx.setAttachment(Integer.valueOf(a * b));
95 * }
96 * }
97 *
98 * // Different context objects are given to "f1", "f2", "f3", and "f4" even if
99 * // they refer to the same handler instance. Because the FactorialHandler
100 * // stores its state in a context object (as an attachment), the factorial is
101 * // calculated correctly 4 times once the two pipelines (p1 and p2) are active.
102 * FactorialHandler fh = new FactorialHandler();
103 *
104 * {@link ChannelPipeline} p1 = {@link Channels}.pipeline();
105 * p1.addLast("f1", fh);
106 * p1.addLast("f2", fh);
107 *
108 * {@link ChannelPipeline} p2 = {@link Channels}.pipeline();
109 * p2.addLast("f3", fh);
110 * p2.addLast("f4", fh);
111 * </pre>
112 *
113 * <h3>Additional resources worth reading</h3>
114 * <p>
115 * Please refer to the {@link ChannelHandler}, {@link ChannelEvent}, and
116 * {@link ChannelPipeline} to find out what a upstream event and a downstream
117 * event are, what fundamental differences they have, how they flow in a
118 * pipeline, and how to handle the event in your application.
119 *
120 * @author <a href="http://www.jboss.org/netty/">The Netty Project</a>
121 * @author <a href="http://gleamynode.net/">Trustin Lee</a>
122 *
123 * @version $Rev: 2157 $, $Date: 2010-02-17 17:37:38 +0900 (Wed, 17 Feb 2010) $
124 *
125 * @apiviz.owns org.jboss.netty.channel.ChannelHandler
126 */
127 public interface ChannelHandlerContext {
128
129 /**
130 * Returns the {@link Channel} that the {@link ChannelPipeline} belongs to.
131 * This method is a shortcut to <tt>getPipeline().getChannel()</tt>.
132 */
133 Channel getChannel();
134
135 /**
136 * Returns the {@link ChannelPipeline} that the {@link ChannelHandler}
137 * belongs to.
138 */
139 ChannelPipeline getPipeline();
140
141 /**
142 * Returns the name of the {@link ChannelHandler} in the
143 * {@link ChannelPipeline}.
144 */
145 String getName();
146
147 /**
148 * Returns the {@link ChannelHandler} that this context object is
149 * serving.
150 */
151 ChannelHandler getHandler();
152
153 /**
154 * Returns {@code true} if and only if the {@link ChannelHandler} is an
155 * instance of {@link ChannelUpstreamHandler}.
156 */
157 boolean canHandleUpstream();
158
159 /**
160 * Returns {@code true} if and only if the {@link ChannelHandler} is an
161 * instance of {@link ChannelDownstreamHandler}.
162 */
163 boolean canHandleDownstream();
164
165 /**
166 * Sends the specified {@link ChannelEvent} to the
167 * {@link ChannelUpstreamHandler} which is placed in the closest upstream
168 * from the handler associated with this context. It is recommended to use
169 * the shortcut methods in {@link Channels} rather than calling this method
170 * directly.
171 */
172 void sendUpstream(ChannelEvent e);
173
174 /**
175 * Sends the specified {@link ChannelEvent} to the
176 * {@link ChannelDownstreamHandler} which is placed in the closest
177 * downstream from the handler associated with this context. It is
178 * recommended to use the shortcut methods in {@link Channels} rather than
179 * calling this method directly.
180 */
181 void sendDownstream(ChannelEvent e);
182
183 /**
184 * Retrieves an object which is {@link #setAttachment(Object) attached} to
185 * this context.
186 *
187 * @return {@code null} if no object was attached or
188 * {@code null} was attached
189 */
190 Object getAttachment();
191
192 /**
193 * Attaches an object to this context to store a stateful information
194 * specific to the {@link ChannelHandler} which is associated with this
195 * context.
196 */
197 void setAttachment(Object attachment);
198 }