org.jboss.netty.channel
Interface ChannelDownstreamHandler

All Superinterfaces:
ChannelHandler
All Known Implementing Classes:
Base64Encoder, ChunkedWriteHandler, CompatibleObjectEncoder, ExecutionHandler, HttpMessageEncoder, HttpRequestEncoder, HttpResponseEncoder, IdleStateAwareChannelHandler, LengthFieldPrepender, LoggingHandler, ObjectEncoder, OneToOneEncoder, ProtobufEncoder, SimpleChannelDownstreamHandler, SimpleChannelHandler, SslHandler, StringEncoder, WriteTimeoutHandler

public interface ChannelDownstreamHandler
extends ChannelHandler

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

Downstream events

A downstream event is an event which is supposed to be processed by a series of downstream handlers in the ChannelPipeline. It is often an I/O request made by a user application.

The most common use case of this interface is to intercept an I/O request such as Channel.write(Object) and Channel.close(). The received ChannelEvent object is interpreted as described in the following table:

Event nameEvent type and conditionMeaning
"write" MessageEventSend a message to the Channel.
"bind" ChannelStateEvent
(state = BOUND, value = SocketAddress)
Bind the Channel to the specified local address.
"unbind" ChannelStateEvent
(state = BOUND, value = null)
Unbind the Channel from the current local address.
"connect" ChannelStateEvent
(state = CONNECTED, value = SocketAddress)
Connect the Channel to the specified remote address.
"disconnect" ChannelStateEvent
(state = CONNECTED, value = null)
Disconnect the Channel from the current remote address.
"close" ChannelStateEvent
(state = OPEN, value = false)
Close the Channel.

Other event types and conditions which were not addressed here will be ignored and discarded. Please note that there's no "open" in the table. It is because a Channel is always open when it is created by a ChannelFactory.

Additional resources worth reading

You might want to refer to ChannelUpstreamHandler to see how a ChannelEvent is interpreted when going upstream. 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.

Firing an event to the next handler

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

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

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

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

handleDownstream may be invoked by more than one thread simultaneously. If the handler accesses a shared resource or stores stateful information, you might need proper synchronization in the handler implementation.

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 handleDownstream(ChannelHandlerContext ctx, ChannelEvent e)
          Handles the specified downstream event.
 

Method Detail

handleDownstream

void handleDownstream(ChannelHandlerContext ctx,
                      ChannelEvent e)
                      throws Exception
Handles the specified downstream event.

Parameters:
ctx - the context object for this handler
e - the downstream event to process or intercept
Throws:
Exception


Copyright © 2008-2009 JBoss, by Red Hat. All Rights Reserved.