From 55078d87bd7cc7f560c99f04f6e08dce977a0087 Mon Sep 17 00:00:00 2001
From: Trustin Lee <trustin@gmail.com>
Date: Tue, 29 Dec 2009 03:07:20 +0000
Subject: [PATCH] Documentation

---
 .../netty/channel/ChannelHandlerContext.java  | 25 +++++++++++++++++++
 .../channel/LifeCycleAwareChannelHandler.java |  6 ++---
 2 files changed, 28 insertions(+), 3 deletions(-)

diff --git a/src/main/java/org/jboss/netty/channel/ChannelHandlerContext.java b/src/main/java/org/jboss/netty/channel/ChannelHandlerContext.java
index 8772bfcef1..4cc556b8be 100644
--- a/src/main/java/org/jboss/netty/channel/ChannelHandlerContext.java
+++ b/src/main/java/org/jboss/netty/channel/ChannelHandlerContext.java
@@ -77,6 +77,31 @@ import java.util.concurrent.ConcurrentMap;
  * p2.addLast("f4", fh);
  * </pre>
  *
+ * <h3>Retrieving for later use</h3>
+ *
+ * You can keep the {@link ChannelHandlerContext} for later use, such as
+ * triggering an event outside the handler methods, even from a different thread.
+ * <pre>
+ * public class MyHandler extends SimpleChannelHandler
+ *                        implements LifeCycleAwareChannelHandler {
+ *
+ *     private ChannelHandlerContex ctx;
+ *
+ *     public void beforeAdd(ChannelHandlerContext ctx) {
+ *         this.ctx = ctx;
+ *     }
+ *
+ *     public void messageReceived(ChannelHandlerContext ctx, MessageEvent evt) {
+ *         ctx.setAttachment(evt.getMessage());
+ *     }
+ *
+ *     public Object getLastReceivedMessage() {
+ *         return ctx.getAttachment();
+ *     }
+ *     ...
+ * }
+ * </pre>
+ *
  * <h3>Additional resources worth reading</h3>
  * <p>
  * Please refer to the {@link ChannelHandler}, {@link ChannelEvent}, and
diff --git a/src/main/java/org/jboss/netty/channel/LifeCycleAwareChannelHandler.java b/src/main/java/org/jboss/netty/channel/LifeCycleAwareChannelHandler.java
index 508ccd5db3..6dc26da856 100644
--- a/src/main/java/org/jboss/netty/channel/LifeCycleAwareChannelHandler.java
+++ b/src/main/java/org/jboss/netty/channel/LifeCycleAwareChannelHandler.java
@@ -24,9 +24,9 @@ package org.jboss.netty.channel;
  * Calling {@link ChannelHandlerContext#sendUpstream(ChannelEvent)} or
  * {@link ChannelHandlerContext#sendDownstream(ChannelEvent)} in
  * {@link #beforeAdd(ChannelHandlerContext)} or {@link #afterRemove(ChannelHandlerContext)}
- * will lead to an unexpected behavior.  It is because the context object has
- * not been fully added to the pipeline or the context object is not a part of
- * the pipeline anymore respectively.
+ * might lead to an unexpected behavior.  It is because the context object
+ * might not have been fully added to the pipeline or the context object is not
+ * a part of the pipeline anymore respectively.
  *
  * @author The Netty Project (netty-dev@lists.jboss.org)
  * @author Trustin Lee (trustin@gmail.com)