* An upstream event is an event which is supposed to be processed from the * first handler to the last handler in the {@link ChannelPipeline}. * For example, all events initiated by an I/O thread are upstream events, and * they have the following meaning: *
*
| Event name | Event type and condition | Meaning | *
|---|---|---|
| {@code "messageReceived"} | *{@link MessageEvent} | *a message object (e.g. {@link ChannelBuffer}) was received from a remote peer | *
| {@code "exceptionCaught"} | *{@link ExceptionEvent} | *an exception was raised by an I/O thread or a {@link ChannelHandler} | *
| {@code "channelOpen"} | *{@link ChannelStateEvent} (state = {@link ChannelState#OPEN OPEN}, value = {@code true}) |
* a {@link Channel} is open, but not bound nor connected | *
| {@code "channelClosed"} | *{@link ChannelStateEvent} (state = {@link ChannelState#OPEN OPEN}, value = {@code false}) |
* a {@link Channel} was closed and all its related resources were released | *
| {@code "channelBound"} | *{@link ChannelStateEvent} (state = {@link ChannelState#BOUND BOUND}, value = {@link SocketAddress}) |
* a {@link Channel} is open and bound to a local address, but not connected | *
| {@code "channelUnbound"} | *{@link ChannelStateEvent} (state = {@link ChannelState#BOUND BOUND}, value = {@code null}) |
* a {@link Channel} was unbound from the current local address | *
| {@code "channelConnected"} | *{@link ChannelStateEvent} (state = {@link ChannelState#CONNECTED CONNECTED}, value = {@link SocketAddress}) |
* a {@link Channel} is open, bound to a local address, and connected to a remote address | *
| {@code "writeComplete"} | *{@link WriteCompletionEvent} | *something has been written to a remote peer | *
| {@code "channelDisconnected"} | *{@link ChannelStateEvent} (state = {@link ChannelState#CONNECTED CONNECTED}, value = {@code null}) |
* a {@link Channel} was disconnected from its remote peer | *
| {@code "channelInterestChanged"} | *{@link ChannelStateEvent} (state = {@link ChannelState#INTEREST_OPS INTEREST_OPS}, no value) |
* a {@link Channel}'s {@link Channel#getInterestOps() interestOps} was changed | *
* These two additional event types are used only for a parent channel which * can have a child channel (e.g. {@link ServerSocketChannel}). *
*
| Event name | Event type and condition | Meaning | *
|---|---|---|
| {@code "childChannelOpen"} | *{@link ChildChannelStateEvent} ({@code childChannel.isOpen() = true}) |
* a child {@link Channel} was open (e.g. a server channel accepted a connection.) | *
| {@code "childChannelClosed"} | *{@link ChildChannelStateEvent} ({@code childChannel.isOpen() = false}) |
* a child {@link Channel} was closed (e.g. the accepted connection was closed.) | *
* You might want to refer to {@link ChannelDownstreamHandler} to see how a * {@link ChannelEvent} is interpreted when going downstream. Also, please * refer to the {@link ChannelEvent} documentation to find out what an upstream * event and a downstream event are and what fundamental differences they have, * if you didn't read yet. * *
* In most cases, you will get to use a {@link SimpleChannelHandler} to * implement an upstream handler because it provides an individual handler * method for each event type. You might want to implement this interface * directly though if you want to handle various types of events in more * generic way. * *
* You can forward the received event upstream or downstream. In most cases, * {@link ChannelUpstreamHandler} will sent the event to the next handler * (upstream) although it is absolutely normal to sent the event to the * previous handler (downstream): * *
* // Sending the event forward (upstream)
* void handleUpstream({@link ChannelHandlerContext} ctx, {@link ChannelEvent} e) throws Exception {
* ...
* ctx.sendUpstream(e);
* ...
* }
*
* // Sending the event backward (downstream)
* void handleDownstream({@link ChannelHandlerContext} ctx, {@link ChannelEvent} e) throws Exception {
* ...
* ctx.sendDownstream(new MessageEvent(...));
* ...
* }
*
*
* * You will also find various helper methods in {@link Channels} to be useful * to generate and send an artificial or manipulated event. * *
* If there's no {@link ExecutionHandler} in the {@link ChannelPipeline}, * {@link #handleUpstream(ChannelHandlerContext, ChannelEvent) handleUpstream} * will be invoked sequentially by the same thread (i.e. an I/O thread). * Please note that this does not necessarily mean that there's a dedicated * thread per {@link Channel}; the I/O thread of some transport can serve more * than one {@link Channel} (e.g. NIO transport), while the I/O thread of * other transports can serve only one (e.g. OIO transport). *
* If an {@link ExecutionHandler} is added in the {@link ChannelPipeline}, * {@link #handleUpstream(ChannelHandlerContext, ChannelEvent) handleUpstream} * may be invoked by different threads at the same time, depending on what * {@link Executor} implementation is used with the {@link ExecutionHandler}. *
* {@link OrderedMemoryAwareThreadPoolExecutor} is provided to guarantee the * order of {@link ChannelEvent}s. It does not guarantee that the invocation * will be made by the same thread for the same channel, but it does guarantee * that the invocation will be made sequentially for the events of the same * channel. For example, the events can be processed as depicted below: * *
* -----------------------------------> Timeline -----------------------------------> * * Thread X: --- Channel A (Event 1) --. .-- Channel B (Event 2) --- Channel B (Event 3) ---> * \ / * X * / \ * Thread Y: --- Channel B (Event 1) --' '-- Channel A (Event 2) --- Channel A (Event 3) ---> **
* Also, please refer to the {@link ChannelPipelineCoverage} annotation to * understand the relationship between a handler and its stateful properties. * * @author The Netty Project (netty-dev@lists.jboss.org) * @author Trustin Lee (tlee@redhat.com) * * @version $Rev$, $Date$ */ public interface ChannelUpstreamHandler extends ChannelHandler { /** * Handles the specified upstream event. * * @param ctx the context object for this handler * @param e the upstream event to process or intercept */ void handleUpstream(ChannelHandlerContext ctx, ChannelEvent e) throws Exception; }