1 /*
2 * Copyright 2012 The Netty Project
3 *
4 * The Netty Project licenses this file to you under the Apache License,
5 * version 2.0 (the "License"); you may not use this file except in compliance
6 * with the 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.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 * @apiviz.owns org.jboss.netty.channel.ChannelHandler
121 */
122 public interface ChannelHandlerContext {
123
124 /**
125 * Returns the {@link Channel} that the {@link ChannelPipeline} belongs to.
126 * This method is a shortcut to <tt>getPipeline().getChannel()</tt>.
127 */
128 Channel getChannel();
129
130 /**
131 * Returns the {@link ChannelPipeline} that the {@link ChannelHandler}
132 * belongs to.
133 */
134 ChannelPipeline getPipeline();
135
136 /**
137 * Returns the name of the {@link ChannelHandler} in the
138 * {@link ChannelPipeline}.
139 */
140 String getName();
141
142 /**
143 * Returns the {@link ChannelHandler} that this context object is
144 * serving.
145 */
146 ChannelHandler getHandler();
147
148 /**
149 * Returns {@code true} if and only if the {@link ChannelHandler} is an
150 * instance of {@link ChannelUpstreamHandler}.
151 */
152 boolean canHandleUpstream();
153
154 /**
155 * Returns {@code true} if and only if the {@link ChannelHandler} is an
156 * instance of {@link ChannelDownstreamHandler}.
157 */
158 boolean canHandleDownstream();
159
160 /**
161 * Sends the specified {@link ChannelEvent} to the
162 * {@link ChannelUpstreamHandler} which is placed in the closest upstream
163 * from the handler associated with this context. It is recommended to use
164 * the shortcut methods in {@link Channels} rather than calling this method
165 * directly.
166 */
167 void sendUpstream(ChannelEvent e);
168
169 /**
170 * Sends the specified {@link ChannelEvent} to the
171 * {@link ChannelDownstreamHandler} which is placed in the closest
172 * downstream from the handler associated with this context. It is
173 * recommended to use the shortcut methods in {@link Channels} rather than
174 * calling this method directly.
175 */
176 void sendDownstream(ChannelEvent e);
177
178 /**
179 * Retrieves an object which is {@link #setAttachment(Object) attached} to
180 * this context.
181 *
182 * @return {@code null} if no object was attached or
183 * {@code null} was attached
184 */
185 Object getAttachment();
186
187 /**
188 * Attaches an object to this context to store a stateful information
189 * specific to the {@link ChannelHandler} which is associated with this
190 * context.
191 */
192 void setAttachment(Object attachment);
193 }