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.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 * @author <a href="http://www.jboss.org/netty/">The Netty Project</a> 88 * @author <a href="http://gleamynode.net/">Trustin Lee</a> 89 * 90 * @version $Rev: 2122 $, $Date: 2010-02-02 11:00:04 +0900 (Tue, 02 Feb 2010) $ 91 * 92 * @apiviz.exclude ^org\.jboss\.netty\.handler\..*$ 93 */ 94 public interface ChannelUpstreamHandler extends ChannelHandler { 95 96 /** 97 * Handles the specified upstream event. 98 * 99 * @param ctx the context object for this handler 100 * @param e the upstream event to process or intercept 101 */ 102 void handleUpstream(ChannelHandlerContext ctx, ChannelEvent e) throws Exception; 103 }