JavaDoc

src/main/java/org/jboss/netty/channel/ChannelDownstreamHandler.java

@@ -24,6 +24,23 @@ package org.jboss.netty.channel;
 
 
 /**
+ * Handles or intercepts a downstream {@link ChannelEvent}, and fires a
+ * {@link ChannelEvent} to the next handler in a {@link ChannelPipeline}.
+ * <p>
+ * A downstream event is an event which is supposed to be processed from the
+ * last handler to the first handler in the {@link ChannelPipeline}.
+ * For example, all I/O requests made by a user application are downstream
+ * events.
+ * <p>
+ * In most common use case of this interface is to intercept an I/O request
+ * such as {@link Channel#write(Object)} and {@link Channel#close()}.
+ *
+ * <h3>Thread safety</h3>
+ * <p>
+ * {@link #handleDownstream(ChannelHandlerContext, ChannelEvent) 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.
  *
  * @author The Netty Project (netty-dev@lists.jboss.org)
  * @author Trustin Lee (tlee@redhat.com)
@@ -33,5 +50,12 @@ package org.jboss.netty.channel;
  * @apiviz.landmark
  */
 public interface ChannelDownstreamHandler extends ChannelHandler {
+
+    /**
+     * Handles the specified downstream event.
+     *
+     * @param ctx  the context object for this handler
+     * @param e    the downstream event to process or intercept
+     */
     void handleDownstream(ChannelHandlerContext ctx, ChannelEvent e) throws Exception;
 }

src/main/java/org/jboss/netty/channel/ChannelHandler.java

@@ -23,6 +23,19 @@
 package org.jboss.netty.channel;
 
 /**
+ * Handles or intercepts a {@link ChannelEvent}, and fires a new, modified, or
+ * existing {@link ChannelEvent} to the next handler in a {@link ChannelPipeline}.
+ * <p>
+ * This is a tag interface.  There are two sub-interfaces which processes
+ * a received event actually, one for upstream events and the other for
+ * downstream events:
+ * <ul>
+ * <li>{@link ChannelUpstreamHandler} handles and intercepts
+ *     a {@link ChannelEvent} fired by an I/O thread.</li>
+ * <li>{@link ChannelDownstreamHandler} handles and intercepts
+ *     a {@link ChannelEvent} fired by a user via the methods in
+ *     the {@link Channel} interface and the {@link Channels} utility class.</li>
+ * </ul>
  *
  * @author The Netty Project (netty-dev@lists.jboss.org)
  * @author Trustin Lee (tlee@redhat.com)

src/main/java/org/jboss/netty/channel/ChannelUpstreamHandler.java

@@ -22,8 +22,56 @@
  */
 package org.jboss.netty.channel;
 
+import java.util.concurrent.Executor;
+
+import org.jboss.netty.handler.execution.ExecutionHandler;
+import org.jboss.netty.handler.execution.OrderedMemoryAwareThreadPoolExecutor;
+
 
 /**
+ * Handles or intercepts a upstream {@link ChannelEvent}, and fires a
+ * {@link ChannelEvent} to the next handler in a {@link ChannelPipeline}.
+ * <p>
+ * A upstream event is an event which is supposed to be processed from the
+ * first handler to the last handler in the {@link ChannelPipeline}.
+ * For example, all events fired by an I/O thread are upstream events.
+ * <p>
+ * In most cases, you should use a {@link SimpleChannelHandler} to implement
+ * this interface more easily.  You might want to implement this interface
+ * directly though, when you want to handle various types of events in more
+ * generic way.
+ *
+ * <a name="thread_safety"></a>
+ * <h3>Thread safety</h3>
+ * <p>
+ * If there's no {@link ExecutionHandler} in the {@link ChannelPipeline},
+ * {@link #handleUpstream(ChannelHandlerContext, ChannelEvent) handleUpstream}
+ * will be invoked sequentially by the same thread (i.e. an I/O thread).
+ * Please note that this doesn't necessarily mean that there's a dedicated
+ * thread per {@link Channel}; the I/O thread of some transport can serve more
+ * than one {@link Channel} (e.g. NIO transport), while the I/O thread of
+ * others can serve only one (e.g. OIO transport).
+ * <p>
+ * If an {@link ExecutionHandler} is added in the {@link ChannelPipeline},
+ * {@link #handleUpstream(ChannelHandlerContext, ChannelEvent) handleUpstream}
+ * may be invoked by different threads at the same time, depending on what
+ * {@link Executor} implementation is used with the {@link ExecutionHandler}.
+ * <p>
+ * {@link OrderedMemoryAwareThreadPoolExecutor} is provided to guarantee the
+ * order of {@link ChannelEvent}s.  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:
+ *
+ * <pre>
+ *           -----------------------------------&gt; Timeline -----------------------------------&gt;
+ *
+ * Thread X: --- Channel A (Event 1) --.   .-- Channel B (Event 2) --- Channel B (Event 3) ---&gt;
+ *                                      \ /
+ *                                       X
+ *                                      / \
+ * Thread Y: --- Channel B (Event 1) --'   '-- Channel A (Event 2) --- Channel A (Event 3) ---&gt;
+ * </pre>
  *
  * @author The Netty Project (netty-dev@lists.jboss.org)
  * @author Trustin Lee (tlee@redhat.com)
@@ -33,5 +81,12 @@ package org.jboss.netty.channel;
  * @apiviz.landmark
  */
 public interface ChannelUpstreamHandler extends ChannelHandler {
+
+    /**
+     * Handles the specified upstream event.
+     *
+     * @param ctx  the context object for this handler
+     * @param e    the upstream event to process or intercept
+     */
     void handleUpstream(ChannelHandlerContext ctx, ChannelEvent e) throws Exception;
 }

src/main/java/org/jboss/netty/channel/SimpleChannelHandler.java

@@ -22,11 +22,122 @@
  */
 package org.jboss.netty.channel;
 
+import org.jboss.netty.buffer.ChannelBuffer;
+import org.jboss.netty.channel.socket.ServerSocketChannel;
 import org.jboss.netty.logging.InternalLogger;
 import org.jboss.netty.logging.InternalLoggerFactory;
 
 
 /**
+ * Generic {@link ChannelUpstreamHandler} implementation that satisfies most
+ * use cases.  This handler down-casts the received upstream event into more
+ * meaningful sub-type event and calls an appropriate handler method with the
+ * down-casted event.  The following table shows the provided handler methods:
+ *
+ * <table border="1" cellspacing="0" cellpadding="6">
+ * <tr>
+ * <th>Handler method</th><th>Event type</th><th>Invoked when ...</th>
+ * </tr>
+ * <tr>
+ * <td>{@link #messageReceived(ChannelHandlerContext, MessageEvent) messageReceived}</td>
+ * <td>{@link MessageEvent}</td>
+ * <td>a message object (e.g. {@link ChannelBuffer}) was received from a remote peer</td>
+ * </tr>
+ * <tr>
+ * <td>{@link #exceptionCaught(ChannelHandlerContext, ExceptionEvent) exceptionCaught}</td>
+ * <td>{@link ExceptionEvent}</td>
+ * <td>an exception was raised by an I/O thread or a {@link ChannelHandler}</td>
+ * </tr>
+ * <tr>
+ * <td>{@link #channelOpen(ChannelHandlerContext, ChannelStateEvent) channelOpen}</td>
+ * <td>{@link ChannelStateEvent}</td>
+ * <td>a {@link Channel} is open, but not bound nor connected</td>
+ * </tr>
+ * <tr>
+ * <td>{@link #channelOpen(ChannelHandlerContext, ChannelStateEvent) channelOpen}</td>
+ * <td>{@link ChannelStateEvent}</td>
+ * <td>a {@link Channel} is open, but not bound nor connected</td>
+ * </tr>
+ * <tr>
+ * <td>{@link #channelBound(ChannelHandlerContext, ChannelStateEvent) channelBound}</td>
+ * <td>{@link ChannelStateEvent}</td>
+ * <td>a {@link Channel} is open and bound to a local address, but not connected</td>
+ * </tr>
+ * <tr>
+ * <td>{@link #channelConnected(ChannelHandlerContext, ChannelStateEvent) channelConnected}</td>
+ * <td>{@link ChannelStateEvent}</td>
+ * <td>a {@link Channel} is open, bound to a local address, and connected to a remote address</td>
+ * </tr>
+ * <tr>
+ * <td>{@link #channelInterestChanged(ChannelHandlerContext, ChannelStateEvent) channelInterestedChanged}</td>
+ * <td>{@link ChannelStateEvent}</td>
+ * <td>a {@link Channel}'s {@link Channel#getInterestOps() interestOps} was changed</td>
+ * </tr>
+ * <tr>
+ * <td>{@link #channelDisconnected(ChannelHandlerContext, ChannelStateEvent) channelDisconnected}</td>
+ * <td>{@link ChannelStateEvent}</td>
+ * <td>a {@link Channel} was disconnected from its remote peer</td>
+ * </tr>
+ * <tr>
+ * <td>{@link #channelUnbound(ChannelHandlerContext, ChannelStateEvent) channelUnbound}</td>
+ * <td>{@link ChannelStateEvent}</td>
+ * <td>a {@link Channel} was unbound from the current local address</td>
+ * </tr>
+ * <tr>
+ * <td>{@link #channelClosed(ChannelHandlerContext, ChannelStateEvent) channelClosed}</td>
+ * <td>{@link ChannelStateEvent}</td>
+ * <td>a {@link Channel} was closed and all its related resources were released</td>
+ * </tr>
+ * </table>
+ *
+ * <p>
+ * These two handler methods are used only for a parent channel which can have
+ * a child channel (e.g. {@link ServerSocketChannel}).
+ * </p>
+ *
+ * <table border="1" cellspacing="0" cellpadding="6">
+ * <tr>
+ * <th>Handler method</th><th>Event type</th><th>Invoked when ...</th>
+ * </tr>
+ * <tr>
+ * <td>{@link #childChannelOpen(ChannelHandlerContext, ChildChannelStateEvent) childChannelOpen}</td>
+ * <td>{@link ChildChannelStateEvent}</td>
+ * <td>a child {@link Channel} was open (e.g. a server channel accepted a connection.)</td>
+ * </tr>
+ * <tr>
+ * <td>{@link #childChannelClosed(ChannelHandlerContext, ChildChannelStateEvent) childChannelClosed}</td>
+ * <td>{@link ChildChannelStateEvent}</td>
+ * <td>a child {@link Channel} was closed (e.g. the accepted connection was closed.)</td>
+ * </tr>
+ * </table>
+ *
+ * <h3>Overriding {@link #handleUpstream(ChannelHandlerContext, ChannelEvent) handleUpstream} method</h3>
+ * <p>
+ * You can override the {@link #handleUpstream(ChannelHandlerContext, ChannelEvent) handleUpstream}
+ * method just like you can do with other {@link ChannelUpstreamHandler}s.
+ * However, please make sure that you call {@code super.handleUpstream()} so
+ * that other handler methods are invoked properly:
+ * </p>
+ * <pre>public class MyChannelHandler extends SimpleChannelHandler {
+ *
+ *     public void handleUpstream(
+ *             ChannelHandlerContext ctx, ChannelEvent e) throws Exception {
+ *
+ *         // Log all channel state changes.
+ *         if (e instanceof ChannelStateEvent) {
+ *             logger.info("Channel state changed: " + e);
+ *         }
+ *
+ *         <strong>super.handleUpstream(ctx, e);</strong>
+ *     }
+ * }</pre>
+ *
+ * <h3>Thread safety</h3>
+ * <p>
+ * The same rule with {@link ChannelUpstreamHandler} is applied.  Please refer
+ * to the '<a href="ChannelUpstreamHandler.html#thread_safety">thread safety</a>'
+ * section.
+ *
  *
  * @author The Netty Project (netty-dev@lists.jboss.org)
  * @author Trustin Lee (tlee@redhat.com)
@@ -38,6 +149,11 @@ public class SimpleChannelHandler implements ChannelUpstreamHandler {
     private static final InternalLogger logger =
         InternalLoggerFactory.getInstance(SimpleChannelHandler.class.getName());
 
+    /**
+     * {@inheritDoc}  Down-casts the received upstream event into more
+     * meaningful sub-type event and calls an appropriate handler method with
+     * the down-casted event.
+     */
     public void handleUpstream(
             ChannelHandlerContext ctx, ChannelEvent e) throws Exception {
 
@@ -85,46 +201,19 @@ public class SimpleChannelHandler implements ChannelUpstreamHandler {
         }
     }
 
-    public void channelBound(
+    /**
-            ChannelHandlerContext ctx, ChannelStateEvent e) throws Exception {
+     * Invoked when a message object (e.g. {@link ChannelBuffer}) was received
-        ctx.sendUpstream(e);
+     * from a remote peer.
-    }
+     */
-
-    public void channelClosed(
-            ChannelHandlerContext ctx, ChannelStateEvent e) throws Exception {
-        ctx.sendUpstream(e);
-    }
-
-    public void channelConnected(
-            ChannelHandlerContext ctx, ChannelStateEvent e) throws Exception {
-        ctx.sendUpstream(e);
-    }
-
-    public void channelInterestChanged(
-            ChannelHandlerContext ctx, ChannelStateEvent e) throws Exception {
-        ctx.sendUpstream(e);
-    }
-
-    public void channelDisconnected(
-            ChannelHandlerContext ctx, ChannelStateEvent e) throws Exception {
-        ctx.sendUpstream(e);
-    }
-
-    public void channelOpen(
-            ChannelHandlerContext ctx, ChannelStateEvent e) throws Exception {
-        ctx.sendUpstream(e);
-    }
-
-    public void channelUnbound(
-            ChannelHandlerContext ctx, ChannelStateEvent e) throws Exception {
-        ctx.sendUpstream(e);
-    }
-
     public void messageReceived(
             ChannelHandlerContext ctx, MessageEvent e) throws Exception {
         ctx.sendUpstream(e);
     }
 
+    /**
+     * Invoked when an exception was raised by an I/O thread or a
+     * {@link ChannelHandler}.
+     */
     public void exceptionCaught(
             ChannelHandlerContext ctx, ExceptionEvent e) throws Exception {
         if (this == ctx.getPipeline().getLast()) {
@@ -135,13 +224,81 @@ public class SimpleChannelHandler implements ChannelUpstreamHandler {
         ctx.sendUpstream(e);
     }
 
-    public void childChannelClosed(
+    /**
-            ChannelHandlerContext ctx, ChildChannelStateEvent e) throws Exception {
+     * Invoked when a {@link Channel} is open, but not bound nor connected.
+     */
+    public void channelOpen(
+            ChannelHandlerContext ctx, ChannelStateEvent e) throws Exception {
         ctx.sendUpstream(e);
     }
 
+    /**
+     * Invoked when a {@link Channel} is open and bound to a local address,
+     * but not connected.
+     */
+    public void channelBound(
+            ChannelHandlerContext ctx, ChannelStateEvent e) throws Exception {
+        ctx.sendUpstream(e);
+    }
+
+    /**
+     * Invoked when a {@link Channel} is open, bound to a local address, and
+     * connected to a remote address.
+     */
+    public void channelConnected(
+            ChannelHandlerContext ctx, ChannelStateEvent e) throws Exception {
+        ctx.sendUpstream(e);
+    }
+
+    /**
+     * Invoked when a {@link Channel}'s {@link Channel#getInterestOps() interestOps}
+     * was changed.
+     */
+    public void channelInterestChanged(
+            ChannelHandlerContext ctx, ChannelStateEvent e) throws Exception {
+        ctx.sendUpstream(e);
+    }
+
+    /**
+     * Invoked when a {@link Channel} was disconnected from its remote peer.
+     */
+    public void channelDisconnected(
+            ChannelHandlerContext ctx, ChannelStateEvent e) throws Exception {
+        ctx.sendUpstream(e);
+    }
+
+    /**
+     * Invoked when a {@link Channel} was unbound from the current local address.
+     */
+    public void channelUnbound(
+            ChannelHandlerContext ctx, ChannelStateEvent e) throws Exception {
+        ctx.sendUpstream(e);
+    }
+
+    /**
+     * Invoked when a {@link Channel} was closed and all its related resources
+     * were released.
+     */
+    public void channelClosed(
+            ChannelHandlerContext ctx, ChannelStateEvent e) throws Exception {
+        ctx.sendUpstream(e);
+    }
+
+    /**
+     * Invoked when a child {@link Channel} was open.
+     * (e.g. a server channel accepted a connection)
+     */
     public void childChannelOpen(
             ChannelHandlerContext ctx, ChildChannelStateEvent e) throws Exception {
         ctx.sendUpstream(e);
     }
+
+    /**
+     * Invoked when a child {@link Channel} was closed.
+     * (e.g. the accepted connection was closed)
+     */
+    public void childChannelClosed(
+            ChannelHandlerContext ctx, ChildChannelStateEvent e) throws Exception {
+        ctx.sendUpstream(e);
+    }
 }