User Guide for 3.1 updated - please comment!

[Trustin Lee]

Hi Yanky,

On Thu, Apr 16, 2009 at 3:52 PM, yanky young <yanky.young at gmail.com> wrote:
> Hi, trustin:
>
> The updated user guide is pretty clear. Just one thing I am a bit confused.
> It is about upstream and downstream concept. I have read ChannelPipeline
> document. I can generally understand what's upstream and downstream about,
> but not very clear.
>
> the diagram is good for understanding, but I think it is about how the two
> kinds of events flow in the pipeline and in which order they are processed
> by handlers. The problem is why? why would the upstream event be processed
> from the first handler to the last handler? and why would the downstream
> event be processed in a reverse order? The essence is, when receiving
> protocol message, we usually decode raw bytes into frames, and then decode
> frames into string or other protocol object, and then process protocol
> object(application level); and when sending protocol message, we firstly
> build new protocol object(application level), and then encode into string or
> whatever protocol format, and finally encode into raw bytes. So, I wonder if
> the upstream and downstream naming will be clear here. How about
> ChannelInboundHandler/ChannelOutboundHandler? Just my thoughts. It would be
> better to make netty API more clear or more intuitive.

The term upstream and downstream stem from ACE framework:
http://www.cs.wustl.edu/~schmidt/PDF/SUG-94.pdf (See figure 11)

However, I like the word 'inbound' and 'outbound' - why didn't I
choose them over 'upstream' and 'downstream'?  It's too late to
renaming the whole classes and methods.  So.. the documentation needs
to clarify their meaning even more.

> Another question is, why FrameDecoder extends SimpleChannelHandler?
> SimpleChannelHandler process both downstream and upstream events, but
> FrameEncoder seems just process upstream events, right?

Yes, it is.  I've just updated all handler implementations extend
SimpleChannelUpstreamHandler wherever possible.

Thanks a bunch for the valuable feed back!

— Trustin Lee, http://gleamynode.net/