netty 学习- channel代码相关注释

2019独角兽企业重金招聘Python工程师标准>>>

    channelhandler 

1. /**
   * Handles an I/O event or intercepts an I/O operation, and forwards it to its next handler in
    * its {@link ChannelPipeline}.
    *
    * <h3>Sub-types</h3>
    * <p>
    * {@link ChannelHandler} itself does not provide many methods, but you usually have to implement one of its subtypes:
    * <ul>
    * <li>{@link ChannelInboundHandler} to handle inbound I/O events, and</li>
    * <li>{@link ChannelOutboundHandler} to handle outbound I/O operations.</li>
    * </ul>
    * </p>
    * <p>
    * Alternatively, the following adapter classes are provided for your convenience:
    * <ul>
    * <li>{@link ChannelInboundHandlerAdapter} to handle inbound I/O events,</li>
    * <li>{@link ChannelOutboundHandlerAdapter} to handle outbound I/O operations, and</li>
    * <li>{@link ChannelDuplexHandler} to handle both inbound and outbound events</li>
    * </ul>
    * </p>
    * <p>
    * For more information, please refer to the documentation of each subtype.
    * </p>
    *
    * <h3>The context object</h3>
    * <p>
    * A {@link ChannelHandler} is provided with a {@link ChannelHandlerContext}
    * object.  A {@link ChannelHandler} is supposed to interact with the
    * {@link ChannelPipeline} it belongs to via a context object.  Using the
    * context object, the {@link ChannelHandler} can pass events upstream or
    * downstream, modify the pipeline dynamically, or store the information
    * (using {@link AttributeKey}s) which is specific to the handler.
    *
    * <h3>State management</h3>
    *
    * A {@link ChannelHandler} often needs to store some stateful information.
    * The simplest and recommended approach is to use member variables:
    * <pre>
    * public interface Message {
    *     // your methods here
    * }
    *
    * public class DataServerHandler extends {@link SimpleChannelInboundHandler}&lt;Message&gt; {
    *
    *     <b>private boolean loggedIn;</b>
    *
    *     {@code @Override}
    *     public void channelRead0({@link ChannelHandlerContext} ctx, Message message) {
    *         {@link Channel} ch = e.getChannel();
    *         if (message instanceof LoginMessage) {
    *             authenticate((LoginMessage) message);
    *             <b>loggedIn = true;</b>
    *         } else (message instanceof GetDataMessage) {
    *             if (<b>loggedIn</b>) {
    *                 ch.write(fetchSecret((GetDataMessage) message));
    *             } else {
    *                 fail();
    *             }
    *         }
    *     }
    *     ...
    * }
    * </pre>
    * Because the handler instance has a state variable which is dedicated to
    * one connection, you have to create a new handler instance for each new
    * channel to avoid a race condition where a unauthenticated client can get
    * the confidential information:
    * <pre>
    * // Create a new handler instance per channel.
    * // See {@link ChannelInitializer#initChannel(Channel)}.
    * public class DataServerInitializer extends {@link ChannelInitializer}&lt;{@link Channel}&gt; {
    *     {@code @Override}
    *     public void initChannel({@link Channel} channel) {
    *         channel.pipeline().addLast("handler", <b>new DataServerHandler()</b>);
    *     }
    * }
    *
    * </pre>
    *
    * <h4>Using {@link AttributeKey}s</h4>
    *
    * Although it's recommended to use member variables to store the state of a
    * handler, for some reason you might not want to create many handler instances.
    * In such a case, you can use {@link AttributeKey}s which is provided by
    * {@link ChannelHandlerContext}:
    * <pre>
    * public interface Message {
    *     // your methods here
    * }
    *
    * {@code @Sharable}
    * public class DataServerHandler extends {@link SimpleChannelInboundHandler}&lt;Message&gt; {
    *     private final {@link AttributeKey}&lt;{@link Boolean}&gt; auth =
    *           {@link AttributeKey#valueOf(String) AttributeKey.valueOf("auth")};
    *
    *     {@code @Override}
    *     public void channelRead({@link ChannelHandlerContext} ctx, Message message) {
    *         {@link Attribute}&lt;{@link Boolean}&gt; attr = ctx.attr(auth);
    *         {@link Channel} ch = ctx.channel();
    *         if (message instanceof LoginMessage) {
    *             authenticate((LoginMessage) o);
    *             <b>attr.set(true)</b>;
    *         } else (message instanceof GetDataMessage) {
    *             if (<b>Boolean.TRUE.equals(attr.get())</b>) {
    *                 ch.write(fetchSecret((GetDataMessage) o));
    *             } else {
    *                 fail();
    *             }
    *         }
    *     }
    *     ...
    * }
    * </pre>
    * Now that the state of the handler is attached to the {@link ChannelHandlerContext}, you can add the
    * same handler instance to different pipelines:
    * <pre>
    * public class DataServerInitializer extends {@link ChannelInitializer}&lt;{@link Channel}&gt; {
    *
    *     private static final DataServerHandler <b>SHARED</b> = new DataServerHandler();
    *
    *     {@code @Override}
    *     public void initChannel({@link Channel} channel) {
    *         channel.pipeline().addLast("handler", <b>SHARED</b>);
    *     }
    * }
    * </pre>
    *
    *
    * <h4>The {@code @Sharable} annotation</h4>
    * <p>
    * In the example above which used an {@link AttributeKey},
    * you might have noticed the {@code @Sharable} annotation.
    * <p>
    * If a {@link ChannelHandler} is annotated with the {@code @Sharable}
    * annotation, it means you can create an instance of the handler just once and
    * add it to one or more {@link ChannelPipeline}s multiple times without
    * a race condition.
    * <p>
    * If this annotation is not specified, you have to create a new handler
    * instance every time you add it to a pipeline because it has unshared state
    * such as member variables.
    * <p>
    * This annotation is provided for documentation purpose, just like
    * <a href="http://www.javaconcurrencyinpractice.com/annotations/doc/">the JCIP annotations</a>.
    *
    * <h3>Additional resources worth reading</h3>
    * <p>
    * Please refer to the {@link ChannelHandler}, and
    * {@link ChannelPipeline} to find out more about inbound and outbound operations,
    * what fundamental differences they have, how they flow in a  pipeline,  and how to handle
    * the operation in your application.
    */

上述描述可以看到：

1. @Sharable//注解@Sharable可以让它在channels间共享

2.  * <li>{@link ChannelInboundHandlerAdapter} to handle inbound I/O events,</li>

3.  * <li>{@link ChannelOutboundHandlerAdapter} to handle outbound I/O operations, and</li>

4.  * <li>{@link ChannelDuplexHandler} to handle both inbound and outbound events</li>

ChannelHandlerContext

/**
 * Enables a {@link ChannelHandler} to interact with its {@link ChannelPipeline}
 * and other handlers. Among other things a handler can notify the next {@link ChannelHandler} in the
 * {@link ChannelPipeline} as well as modify the {@link ChannelPipeline} it belongs to dynamically.
 *
 * <h3>Notify</h3>
 *
 * You can notify the closest handler in the same {@link ChannelPipeline} by calling one of the various methods
 * provided here.
 *
 * Please refer to {@link ChannelPipeline} to understand how an event flows.
 *
 * <h3>Modifying a pipeline</h3>
 *
 * You can get the {@link ChannelPipeline} your handler belongs to by calling
 * {@link #pipeline()}.  A non-trivial application could insert, remove, or
 * replace handlers in the pipeline dynamically at runtime.
 *
 * <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 {@link ChannelDuplexHandler} {
 *
 *     <b>private {@link ChannelHandlerContext} ctx;</b>
 *
 *     public void beforeAdd({@link ChannelHandlerContext} ctx) {
 *         <b>this.ctx = ctx;</b>
 *     }
 *
 *     public void login(String username, password) {
 *         ctx.write(new LoginMessage(username, password));
 *     }
 *     ...
 * }
 * </pre>
 *
 * <h3>Storing stateful information</h3>
 *
 * {@link #attr(AttributeKey)} allow you to
 * store and access stateful information that is related with a handler and its
 * context.  Please refer to {@link ChannelHandler} to learn various recommended
 * ways to manage stateful information.
 *
 * <h3>A handler can have more than one context</h3>
 *
 * Please note that a {@link ChannelHandler} instance can be added to more than
 * one {@link ChannelPipeline}.  It means a single {@link ChannelHandler}
 * instance can have more than one {@link ChannelHandlerContext} and therefore
 * the single instance can be invoked with different
 * {@link ChannelHandlerContext}s if it is added to one or more
 * {@link ChannelPipeline}s more than once.
 * <p>
 * For example, the following handler will have as many independent {@link AttributeKey}s
 * as how many times it is added to pipelines, regardless if it is added to the
 * same pipeline multiple times or added to different pipelines multiple times:
 * <pre>
 * public class FactorialHandler extends {@link ChannelInboundHandlerAdapter} {
 *
 *   private final {@link AttributeKey}&lt;{@link Integer}&gt; counter = {@link AttributeKey}.valueOf("counter");
 *
 *   // This handler will receive a sequence of increasing integers starting
 *   // from 1.
 *   {@code @Override}
 *   public void channelRead({@link ChannelHandlerContext} ctx, Object msg) {
 *     Integer a = ctx.attr(counter).get();
 *
 *     if (a == null) {
 *       a = 1;
 *     }
 *
 *     attr.set(a * (Integer) msg);
 *   }
 * }
 *
 * // Different context objects are given to "f1", "f2", "f3", and "f4" even if
 * // they refer to the same handler instance.  Because the FactorialHandler
 * // stores its state in a context object (using an {@link AttributeKey}), the factorial is
 * // calculated correctly 4 times once the two pipelines (p1 and p2) are active.
 * FactorialHandler fh = new FactorialHandler();
 *
 * {@link ChannelPipeline} p1 = {@link Channels}.pipeline();
 * p1.addLast("f1", fh);
 * p1.addLast("f2", fh);
 *
 * {@link ChannelPipeline} p2 = {@link Channels}.pipeline();
 * p2.addLast("f3", fh);
 * p2.addLast("f4", fh);
 * </pre>
 *
 * <h3>Additional resources worth reading</h3>
 * <p>
 * Please refer to the {@link ChannelHandler}, and
 * {@link ChannelPipeline} to find out more about inbound and outbound operations,
 * what fundamental differences they have, how they flow in a  pipeline,  and how to handle
 * the operation in your application.
 */

ChannelInitializer

/**
 * A special {@link ChannelInboundHandler} which offers an easy way to initialize a {@link Channel} once it was
 * registered to its {@link EventLoop}.
 *
 * Implementations are most often used in the context of {@link Bootstrap#handler(ChannelHandler)} ,
 * {@link ServerBootstrap#handler(ChannelHandler)} and {@link ServerBootstrap#childHandler(ChannelHandler)} to
 * setup the {@link ChannelPipeline} of a {@link Channel}.
 *
 * <pre>
 *
 * public class MyChannelInitializer extends {@link ChannelInitializer} {
 *     public void initChannel({@link Channel} channel) {
 *         channel.pipeline().addLast("myHandler", new MyHandler());
 *     }
 * }
 *
 * {@link ServerBootstrap} bootstrap = ...;
 * ...
 * bootstrap.childHandler(new MyChannelInitializer());
 * ...
 * </pre>
 * Be aware that this class is marked as {@link Sharable} and so the implementation must be safe to be re-used.
 *
 * @param <C>   A sub-type of {@link Channel}
 */

ChannelHandler.Sharable

Indicates that the same instance of the annotated ChannelHandler can be added to one or more ChannelPipelines multiple times without a race condition.

ChannelHandler.Skip

Indicates that the annotated event handler method in ChannelHandler will not be invoked by ChannelPipeline.

转载于:https://my.oschina.net/u/131940/blog/631608