View Javadoc

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  }