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 import java.util.concurrent.Executor;
19
20 import org.jboss.netty.handler.execution.ExecutionHandler;
21
22
23 /**
24 * Handles or intercepts an upstream {@link ChannelEvent}, and sends a
25 * {@link ChannelEvent} to the next handler in a {@link ChannelPipeline}.
26 * <p>
27 * The most common use case of this interface is to intercept an I/O event
28 * generated by I/O workers to transform the received messages or execute
29 * the relevant business logic.
30 *
31 * <h3>{@link SimpleChannelUpstreamHandler}</h3>
32 * <p>
33 * In most cases, you will get to use a {@link SimpleChannelUpstreamHandler} to
34 * implement an upstream handler because it provides an individual handler
35 * method for each event type. You might want to implement this interface
36 * directly though if you want to handle various types of events in more
37 * generic way.
38 *
39 * <h3>Firing an event to the next handler</h3>
40 * <p>
41 * You can forward the received event upstream or downstream. In most cases,
42 * {@link ChannelUpstreamHandler} will send the event upstream (i.e. inbound)
43 * although it is legal to send the event downstream (i.e. outbound):
44 *
45 * <pre>
46 * // Sending the event upstream (inbound)
47 * void handleUpstream({@link ChannelHandlerContext} ctx, {@link ChannelEvent} e) throws Exception {
48 * ...
49 * ctx.sendUpstream(e);
50 * ...
51 * }
52 *
53 * // Sending the event downstream (outbound)
54 * void handleDownstream({@link ChannelHandlerContext} ctx, {@link ChannelEvent} e) throws Exception {
55 * ...
56 * ctx.sendDownstream(new {@link DownstreamMessageEvent}(...));
57 * ...
58 * }
59 * </pre>
60 *
61 * <h4>Using the helper class to send an event</h4>
62 * <p>
63 * You will also find various helper methods in {@link Channels} to be useful
64 * to generate and send an artificial or manipulated event.
65 *
66 * <h3>State management</h3>
67 *
68 * Please refer to {@link ChannelHandler}.
69 *
70 * <h3>Thread safety</h3>
71 * <p>
72 * {@link #handleUpstream(ChannelHandlerContext, ChannelEvent) handleUpstream}
73 * will be invoked sequentially by the same thread (i.e. an I/O thread) and
74 * therefore a handler does not need to worry about being invoked with a new
75 * upstream event before the previous upstream event is finished.
76 * <p>
77 * This does not necessarily mean that there's a dedicated thread per
78 * {@link Channel}; the I/O thread of some transport can serve more than one
79 * {@link Channel} (e.g. NIO transport), while the I/O thread of other
80 * transports can serve only one (e.g. OIO transport).
81 * <p>
82 * However, if you add an {@link ExecutionHandler} to a {@link ChannelPipeline},
83 * this behavior changes depending on what {@link Executor} was employed to
84 * dispatch the events. Please refer to {@link ExecutionHandler} for more
85 * information.
86 *
87 * @apiviz.exclude ^org\.jboss\.netty\.handler\..*$
88 */
89 public interface ChannelUpstreamHandler extends ChannelHandler {
90
91 /**
92 * Handles the specified upstream event.
93 *
94 * @param ctx the context object for this handler
95 * @param e the upstream event to process or intercept
96 */
97 void handleUpstream(ChannelHandlerContext ctx, ChannelEvent e) throws Exception;
98 }