org.jboss.netty.channel
Interface ChannelUpstreamHandler

All Superinterfaces:

ChannelHandler

All Known Implementing Classes:

Base64Decoder, ChunkedWriteHandler, CompatibleObjectDecoder, DelimiterBasedFrameDecoder, ExecutionHandler, FixedLengthFrameDecoder, FrameDecoder, HttpChunkAggregator, HttpMessageDecoder, HttpRequestDecoder, HttpResponseDecoder, IdleStateAwareChannelHandler, IdleStateAwareChannelUpstreamHandler, IdleStateHandler, LengthFieldBasedFrameDecoder, LoggingHandler, ObjectDecoder, OneToOneDecoder, ProtobufDecoder, ReadTimeoutHandler, ReplayingDecoder, SimpleChannelHandler, SimpleChannelUpstreamHandler, SslHandler, StringDecoder

public interface ChannelUpstreamHandler
extends ChannelHandler

Handles or intercepts an upstream ChannelEvent, and sends a ChannelEvent to the next handler in a ChannelPipeline.

Upstream events

An upstream event is an event which is supposed to be processed by a series of upstream handlers in the the ChannelPipeline. The upstream events are generated by an I/O thread, and they have the following meaning:

Event name	Event type and condition	Meaning
"messageReceived"	MessageEvent	a message object (e.g. ChannelBuffer) was received from a remote peer
"exceptionCaught"	ExceptionEvent	an exception was raised by an I/O thread or a ChannelHandler
"channelOpen"	ChannelStateEvent (state = OPEN, value = true)	a Channel is open, but not bound nor connected
"channelClosed"	ChannelStateEvent (state = OPEN, value = false)	a Channel was closed and all its related resources were released
"channelBound"	ChannelStateEvent (state = BOUND, value = SocketAddress)	a Channel is open and bound to a local address, but not connected
"channelUnbound"	ChannelStateEvent (state = BOUND, value = null)	a Channel was unbound from the current local address
"channelConnected"	ChannelStateEvent (state = CONNECTED, value = SocketAddress)	a Channel is open, bound to a local address, and connected to a remote address
"writeComplete"	WriteCompletionEvent	something has been written to a remote peer
"channelDisconnected"	ChannelStateEvent (state = CONNECTED, value = null)	a Channel was disconnected from its remote peer
"channelInterestChanged"	ChannelStateEvent (state = INTEREST_OPS, no value)	a Channel's interestOps was changed

These two additional event types are used only for a parent channel which can have a child channel (e.g. ServerSocketChannel).

Event name	Event type and condition	Meaning
"childChannelOpen"	ChildChannelStateEvent (childChannel.isOpen() = true)	a child Channel was open (e.g. a server channel accepted a connection.)
"childChannelClosed"	ChildChannelStateEvent (childChannel.isOpen() = false)	a child Channel was closed (e.g. the accepted connection was closed.)

Additional resources worth reading

You might want to refer to ChannelDownstreamHandler to see how a ChannelEvent is interpreted when going downstream. Also, please refer to the ChannelEvent and ChannelPipeline documentation to find out what an upstream event and a downstream event are, what fundamental differences they have, and how they flow in a pipeline.

SimpleChannelHandler

In most cases, you will get to use a 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.

Firing an event to the next handler

You can forward the received event upstream or downstream. In most cases, ChannelUpstreamHandler will send the event upstream (i.e. inbound) although it is legal to send the event downstream (i.e. outbound):

 // Sending the event upstream (inbound)
 void handleUpstream(ChannelHandlerContext ctx, ChannelEvent e) throws Exception {
     ...
     ctx.sendUpstream(e);
     ...
 }

 // Sending the event downstream (outbound)
 void handleDownstream(ChannelHandlerContext ctx, ChannelEvent e) throws Exception {
     ...
     ctx.sendDownstream(new MessageEvent(...));
     ...
 }
 

Using the helper class to send an event

You will also find various helper methods in Channels to be useful to generate and send an artificial or manipulated event.

Thread safety

If there's no ExecutionHandler in the ChannelPipeline, 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 Channel; the I/O thread of some transport can serve more than one Channel (e.g. NIO transport), while the I/O thread of other transports can serve only one (e.g. OIO transport).

If an ExecutionHandler is added in the ChannelPipeline, handleUpstream may be invoked by different threads at the same time, depending on what Executor implementation is used with the ExecutionHandler.

OrderedMemoryAwareThreadPoolExecutor is provided to guarantee the order of ChannelEvents. 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 ChannelPipelineCoverage annotation to understand the relationship between a handler and its stateful properties.

Version:

$Rev: 1706 $, $Date: 2009-09-03 13:33:15 +0900 (목, 03 9 2009) $

Author:

The Netty Project (netty-dev@lists.jboss.org), Trustin Lee (tlee@redhat.com)

Method Summary

void	handleUpstream(ChannelHandlerContext ctx, ChannelEvent e) Handles the specified upstream event.

Method Detail

handleUpstream

void handleUpstream(ChannelHandlerContext ctx,
                    ChannelEvent e)
                    throws Exception

Handles the specified upstream event.

Parameters:

ctx - the context object for this handler

e - the upstream event to process or intercept

Throws:

Exception