* Added examples for timeout handlers

* Fixed a problem where the handler methods in IdleStateAwareChannel*Handler was not declared with 'throws Exeception' unlike other handlers.

src/main/java/org/jboss/netty/handler/timeout/IdleStateAwareChannelHandler.java

@@ -52,7 +52,7 @@ public class IdleStateAwareChannelHandler extends SimpleChannelHandler {
     /**
      * Invoked when a {@link Channel} has been idle for a while.
      */
-    public void channelIdle(ChannelHandlerContext ctx, IdleStateEvent e) {
+    public void channelIdle(ChannelHandlerContext ctx, IdleStateEvent e) throws Exception {
         ctx.sendUpstream(e);
     }
 }

src/main/java/org/jboss/netty/handler/timeout/IdleStateAwareChannelUpstreamHandler.java

@@ -52,7 +52,7 @@ public class IdleStateAwareChannelUpstreamHandler extends SimpleChannelUpstreamH
     /**
      * Invoked when a {@link Channel} has been idle for a while.
      */
-    public void channelIdle(ChannelHandlerContext ctx, IdleStateEvent e) {
+    public void channelIdle(ChannelHandlerContext ctx, IdleStateEvent e) throws Exception {
         ctx.sendUpstream(e);
     }
 }

src/main/java/org/jboss/netty/handler/timeout/IdleStateHandler.java

@@ -62,6 +62,24 @@ import org.jboss.netty.util.TimerTask;
  * </tr>
  * </table>
  *
+ * <pre>
+ * // An example that sends a ping message when there is no traffic
+ * // (either inbound or outbound) for 30 seconds.
+ * ChannelPipeline p = ...;
+ * Timer timer = new HashedWheelTimer();
+ * p.addLast("timeout", new IdleStateHandler(timer, 30, 30, 0));
+ * p.addLast("handler", new MyHandler());
+ *
+ * // Handler should handle the IdleStateEvent triggered by IdleStateHandler.
+ * public class MyHandler extends IdleStateAwareChannelHandler {
+ *     public void channelIdle(ChannelHandlerContext ctx, IdleStateEvent e) {
+ *         ctx.getChannel().write(new PingMessage());
+ *     }
+ * }
+ *
+ * // To shut down, call {@link #releaseExternalResources()} or {@link Timer#stop()}.
+ * </pre>
+ *
  * @author The Netty Project (netty-dev@lists.jboss.org)
  * @author Trustin Lee (tlee@redhat.com)
  * @version $Rev$, $Date$

src/main/java/org/jboss/netty/handler/timeout/ReadTimeoutHandler.java

@@ -36,6 +36,16 @@ import org.jboss.netty.util.TimerTask;
  * Raises a {@link ReadTimeoutException} when no data was read within a certain
  * period of time.
  *
+ * <pre>
+ * // An example configuration that implements 30-second read timeout:
+ * ChannelPipeline p = ...;
+ * Timer timer = new HashedWheelTimer();
+ * p.addLast("timeout", new ReadTimeoutHandler(timer, 30));
+ * p.addLast("handler", new MyHandler());
+ *
+ * // To shut down, call {@link #releaseExternalResources()} or {@link Timer#stop()}.
+ * </pre>
+ *
  * @author The Netty Project (netty-dev@lists.jboss.org)
  * @author Trustin Lee (tlee@redhat.com)
  * @version $Rev$, $Date$

src/main/java/org/jboss/netty/handler/timeout/WriteTimeoutHandler.java

@@ -36,6 +36,16 @@ import org.jboss.netty.util.TimerTask;
  * Raises a {@link WriteTimeoutException} when no data was written within a
  * certain period of time.
  *
+ * <pre>
+ * // An example configuration that implements 30-second write timeout:
+ * ChannelPipeline p = ...;
+ * Timer timer = new HashedWheelTimer();
+ * p.addLast("timeout", new WriteTimeoutHandler(timer, 30));
+ * p.addLast("handler", new MyHandler());
+ *
+ * // To shut down, call {@link #releaseExternalResources()} or {@link Timer#stop()}.
+ * </pre>
+ *
  * @author The Netty Project (netty-dev@lists.jboss.org)
  * @author Trustin Lee (tlee@redhat.com)
  * @version $Rev$, $Date$