And again javadocs cleanup

handler/src/main/java/io/netty/handler/timeout/IdleStateHandler.java

@@ -65,10 +65,11 @@ import java.util.concurrent.TimeUnit;
  * // for 30 seconds.  The connection is closed when there is no inbound traffic
  * // for 60 seconds.
  *
- * public class MyChannelInitializer extends {@link ChannelInitializer} {
+ * public class MyChannelInitializer extends {@link ChannelInitializer}&lt{@link Channel}&gt {
+ *     {@code @Override}
  *     public void initChannel({@link Channel} channel) {
- *         {@link Channel}.pipeline().addLast("idleStateHandler", new {@link IdleStateHandler}(60, 30, 0);
+ *         channel.pipeline().addLast("idleStateHandler", new {@link IdleStateHandler}(60, 30, 0);
- *         {@link Channel}.pipeline().addLast("myHandler", new MyHandler());
+ *         channel.pipeline().addLast("myHandler", new MyHandler());
  *     }
  * }
  *

handler/src/main/java/io/netty/handler/timeout/ReadTimeoutHandler.java

@@ -33,7 +33,7 @@ import java.util.concurrent.TimeUnit;
  * // The connection is closed when there is no inbound traffic
  * // for 30 seconds.
  *
- * public class MyChannelInitializer extends {@link ChannelInitializer} {
+ * public class MyChannelInitializer extends {@link ChannelInitializer}&lt{@link Channel}&gt {
  *     public void initChannel({@link Channel} channel) {
  *         channel.pipeline().addLast("readTimeoutHandler", new {@link ReadTimeoutHandler}(30);
  *         channel.pipeline().addLast("myHandler", new MyHandler());

handler/src/main/java/io/netty/handler/timeout/WriteTimeoutHandler.java

@@ -36,7 +36,7 @@ import java.util.concurrent.TimeUnit;
  * // The connection is closed when there is no outbound traffic
  * // for 30 seconds.
  *
- * public class MyChannelInitializer extends {@link ChannelInitializer} {
+ * public class MyChannelInitializer extends {@link ChannelInitializer}&lt{@link Channel}&gt {
  *     public void initChannel({@link Channel} channel) {
  *         channel.pipeline().addLast("writeTimeoutHandler", new {@link WriteTimeoutHandler}(30);
  *         channel.pipeline().addLast("myHandler", new MyHandler());

transport/src/main/java/io/netty/channel/ChannelHandler.java

@@ -15,7 +15,10 @@
  */
 package io.netty.channel;
 
-import io.netty.channel.group.ChannelGroup;
+import io.netty.buffer.ByteBuf;
+import io.netty.buffer.MessageBuf;
+import io.netty.util.Attribute;
+import io.netty.util.AttributeKey;
 
 import java.lang.annotation.Documented;
 import java.lang.annotation.ElementType;
@@ -23,21 +26,28 @@ import java.lang.annotation.Inherited;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
-import java.nio.channels.Channels;
 
 /**
- * Handles or intercepts a {@link ChannelEvent}, and sends a
+ * Handles or intercepts a {@link ChannelInboundInvoker} or {@link ChannelOutboundInvoker} operation, and forwards it
- * {@link ChannelEvent} to the next handler in a {@link ChannelPipeline}.
+ * to the next handler in a {@link ChannelPipeline}.
  *
  * <h3>Sub-types</h3>
  * <p>
- * {@link ChannelHandler} itself does not provide any method.  To handle a
+ * {@link ChannelHandler} itself does not provide many methods.  To handle a
- * {@link ChannelEvent} you need to implement its sub-interfaces.  There are
+ * a {@link ChannelInboundInvoker} or {@link ChannelOutboundInvoker} operation
- * two sub-interfaces which handles a received event, one for upstream events
+ * you need to implement its sub-interfaces.  There are many different sub-interfaces
- * and the other for downstream events:
+ * which handles inbound and outbound operations.
+ *
+ * But the most useful for developers may be:
  * <ul>
- * <li>{@link ChannelUpstreamHandler} handles and intercepts an upstream {@link ChannelEvent}.</li>
+ * <li>{@link ChannelInboundByteHandlerAdapter} handles and intercepts inbound operations where the inbound message
- * <li>{@link ChannelDownstreamHandler} handles and intercepts a downstream {@link ChannelEvent}.</li>
+ * type is a {@link ByteBuf}.</li>
+ * <li>{@link ChannelInboundMessageHandlerAdapter} handles and intercepts inbound operations where the inbound message
+ * type is a {@link MessageBuf}.</li>
+ *  * <li>{@link ChannelOutboundByteHandlerAdapter} handles and intercepts outbound operations where the inbound message
+ * type is a {@link ByteBuf}.</li>
+ * <li>{@link ChannelOutboundMessageHandlerAdapter} handles and intercepts outbound operations where the inbound message
+ * type is a {@link MessageBuf}.</li>
  * </ul>
  *
  * You will also find more detailed explanation from the documentation of
@@ -58,20 +68,23 @@ import java.nio.channels.Channels;
  * A {@link ChannelHandler} often needs to store some stateful information.
  * The simplest and recommended approach is to use member variables:
  * <pre>
- * public class DataServerHandler extends {@link SimpleChannelHandler} {
+ * public interface Message {
+ *     // your methods here
+ * }
+ *
+ * public class DataServerHandler extends {@link ChannelInboundMessageHandlerAdapter}&ltMessage&gt {
  *
  *     <b>private boolean loggedIn;</b>
  *
  *     {@code @Override}
- *     public void messageReceived({@link ChannelHandlerContext} ctx, {@link MessageEvent} e) {
+ *     public void messageReceived({@link ChannelHandlerContext} ctx, Message message) {
  *         {@link Channel} ch = e.getChannel();
- *         Object o = e.getMessage();
+ *         if (message instanceof LoginMessage) {
- *         if (o instanceof LoginMessage) {
+ *             authenticate((LoginMessage) message);
- *             authenticate((LoginMessage) o);
  *             <b>loggedIn = true;</b>
- *         } else (o instanceof GetDataMessage) {
+ *         } else (message instanceof GetDataMessage) {
  *             if (<b>loggedIn</b>) {
- *                 ch.write(fetchSecret((GetDataMessage) o));
+ *                 ch.write(fetchSecret((GetDataMessage) message));
  *             } else {
  *                 fail();
  *             }
@@ -86,12 +99,14 @@ import java.nio.channels.Channels;
  * the confidential information:
  * <pre>
  * // Create a new handler instance per channel.
- * // See {@link ClientBootstrap#setPipelineFactory(ChannelPipelineFactory)}.
+ * // See {@link ChannelInitializer#initChannel(Channel)}.
- * public class DataServerPipelineFactory implements {@link ChannelPipelineFactory} {
+ * public class DataServerInitializer extends {@link ChannelInitializer}&lt{@link Channel}&gt {
- *     public {@link ChannelPipeline} getPipeline() {
+ *     {@code @Override}
- *         return {@link Channels}.pipeline(<b>new DataServerHandler()</b>);
+ *     public void initChannel({@link Channel} channel) {
+ *         channel.pipeline().addLast("handler", <b>new DataServerHandler()</b>);
  *     }
  * }
+ *
  * </pre>
  *
  * <h4>Using an attachment</h4>
@@ -101,18 +116,29 @@ import java.nio.channels.Channels;
  * In such a case, you can use an <em>attachment</em> which is provided by
  * {@link ChannelHandlerContext}:
  * <pre>
+ * public interface Message {
+ *     // your methods here
+ * }
+ *
  * {@code @Sharable}
- * public class DataServerHandler extends {@link SimpleChannelHandler} {
+ * public class DataServerHandler extends {@link ChannelInboundMessageHandlerAdapter}&ltMessage&gt {
+ *   private final {@link AttributeKey}&lt{@link Boolean}&gt auth =
+ *           new {@link AttributeKey}&lt{@link Boolean}&gt("auth");
+ *
+ *   // This handler will receive a sequence of increasing integers starting
+ *   // from 1.
+ *   {@code @Override}
+ *   public void messageReceived({@link ChannelHandlerContext} ctx, {@link Integer} integer) {
+ *     {@link Attribute}&lt{@link Boolean}&gt attr = ctx.getAttr(auth);
  *
  *     {@code @Override}
- *     public void messageReceived({@link ChannelHandlerContext} ctx, {@link MessageEvent} e) {
+ *     public void messageReceived({@link ChannelHandlerContext} ctx, Message message) {
- *         {@link Channel} ch = e.getChannel();
+ *         {@link Channel} ch = ctx.channel();
- *         Object o = e.getMessage();
+ *         if (message instanceof LoginMessage) {
- *         if (o instanceof LoginMessage) {
  *             authenticate((LoginMessage) o);
- *             <b>ctx.setAttachment(true)</b>;
+ *             <b>attr.set(true)</b>;
- *         } else (o instanceof GetDataMessage) {
+ *         } else (message instanceof GetDataMessage) {
- *             if (<b>Boolean.TRUE.equals(ctx.getAttachment())</b>) {
+ *             if (<b>Boolean.TRUE.equals(attr.get())</b>) {
  *                 ch.write(fetchSecret((GetDataMessage) o));
  *             } else {
  *                 fail();
@@ -125,64 +151,21 @@ import java.nio.channels.Channels;
  * Now that the state of the handler is stored as an attachment, you can add the
  * same handler instance to different pipelines:
  * <pre>
- * public class DataServerPipelineFactory implements {@link ChannelPipelineFactory} {
+ * public class DataServerInitializer extends {@link ChannelInitializer}&lt{@link Channel}&gt {
  *
  *     private static final DataServerHandler <b>SHARED</b> = new DataServerHandler();
  *
- *     public {@link ChannelPipeline} getPipeline() {
- *         return {@link Channels}.pipeline(<b>SHARED</b>);
- *     }
- * }
- * </pre>
- *
- * <h4>Using a {@link ChannelLocal}</h4>
- *
- * If you have a state variable which needs to be accessed either from other
- * handlers or outside handlers, you can use {@link ChannelLocal}:
- * <pre>
- * public final class DataServerState {
- *
- *     <b>public static final {@link ChannelLocal}&lt;Boolean&gt; loggedIn = new {@link ChannelLocal}&lt;&gt;() {
- *         protected Boolean initialValue(Channel channel) {
- *             return false;
- *         }
- *     }</b>
- *     ...
- * }
- *
- * {@code @Sharable}
- * public class DataServerHandler extends {@link SimpleChannelHandler} {
- *
  *     {@code @Override}
- *     public void messageReceived({@link ChannelHandlerContext} ctx, {@link MessageEvent} e) {
+ *     public void initChannel({@link Channel} channel) {
- *         Channel ch = e.getChannel();
+ *         channel.pipeline().addLast("handler", <b>SHARED</b>);
- *         Object o = e.getMessage();
- *         if (o instanceof LoginMessage) {
- *             authenticate((LoginMessage) o);
- *             <b>DataServerState.loggedIn.set(ch, true);</b>
- *         } else (o instanceof GetDataMessage) {
- *             if (<b>DataServerState.loggedIn.get(ch)</b>) {
- *                 ctx.getChannel().write(fetchSecret((GetDataMessage) o));
- *             } else {
- *                 fail();
- *             }
- *         }
- *     }
- *     ...
- * }
- *
- * // Print the remote addresses of the authenticated clients:
- * {@link ChannelGroup} allClientChannels = ...;
- * for ({@link Channel} ch: allClientChannels) {
- *     if (<b>DataServerState.loggedIn.get(ch)</b>) {
- *         System.out.println(ch.getRemoteAddress());
  *     }
  * }
  * </pre>
  *
+ *
  * <h4>The {@code @Sharable} annotation</h4>
  * <p>
- * In the examples above which used an attachment or a {@link ChannelLocal},
+ * In the examples above which used an attachment,
  * you might have noticed the {@code @Sharable} annotation.
  * <p>
  * If a {@link ChannelHandler} is annotated with the {@code @Sharable}
@@ -199,9 +182,10 @@ import java.nio.channels.Channels;
  *
  * <h3>Additional resources worth reading</h3>
  * <p>
- * Please refer to the {@link ChannelEvent} and {@link ChannelPipeline} to find
+ * Please refer to the {@link ChannelHandler}, and
- * out what a upstream event and a downstream event are, what fundamental
+ * {@link ChannelPipeline} to find out more about inbound and outbound operations,
- * differences they have, and how they flow in a pipeline.
+ * what fundamental differences they have, how they flow in a  pipeline,  and how to handle
+ * the operation in your application.
  * @apiviz.landmark
  * @apiviz.exclude ^io\.netty\.handler\..*$
  */

transport/src/main/java/io/netty/channel/ChannelHandlerContext.java

@@ -91,7 +91,7 @@ import java.util.Set;
  *   // from 1.
  *   {@code @Override}
  *   public void messageReceived({@link ChannelHandlerContext} ctx, {@link Integer} integer) {
- *     {@link Attribute}&lt{@link Integer}&gt} attr = ctx.getAttr(counter);
+ *     {@link Attribute}&lt{@link Integer}&gt attr = ctx.getAttr(counter);
  *     Integer a = ctx.getAttr(counter).get();
  *
  *     if (a == null) {