org.jboss.netty.channel
Annotation Type ChannelPipelineCoverage

@Inherited
@Documented
@Target(value=TYPE)
@Retention(value=RUNTIME)
public @interface ChannelPipelineCoverage

Specifies if the same instance of the annotated ChannelHandler type can be added to more than one ChannelPipeline.

All handler types are expected to specify this annotation. Otherwise you will be warned in runtime. Only two values are allowed for this annotation: "all" and "one".

Please note that this annotation does not prevent a handler annotated with the value "one" from being added to more than one pipeline. This annotation is used for documentation purpose only.

ChannelPipelineCoverage("all")

"all" means you can add the same instance of the annotated handler type to more than one ChannelPipeline. It means the member variables of the handler instance is shared among multiple channels and it is designed to be OK to do so (or there's nothing to share.) The following code shows an example of a handler type annotated with "all" value:

 public class StatelessHandler extends SimpleChannelHandler {

     // No state properties - you are safe to add the same instance to
     //                       multiple pipelines.

     public void messageReceived(ChannelHandlerContext ctx, MessageEvent e) {
         // Prepend a length field to the message.
         ChannelBuffer body = (ChannelBuffer) e.getMessage();
         ChannelBuffer header = ChannelBuffers.buffer(4);
         header.writeInt(body.readableBytes());

         // Create a message prepended with the header and send a new event.
         ChannelBuffer message = ChannelBuffers.wrappedBuffer(header, body);
         Channels.fireMessageReceived(ctx, message, e.getRemoteAddress());
     }
     ...
 }
 

ChannelPipelineCoverage("one")

"one" means you must create a new instance of the annotated handler type for each new channel. It means the member variables of the handler instance can not be shared at all, and violating this contract will lead the handler to a race condition. The following code shows an example of a handler type annotated with "one" value:

 public class StatefulHandler extends SimpleChannelHandler {

     // Stateful property - adding the same instance to multiple pipelines
     //                     can lead to a race condition.
     private int messageId;

     public void messageReceived(ChannelHandlerContext ctx, MessageEvent e) {
         // Prepend a message ID and length field to the message.
         ChannelBuffer body = (ChannelBuffer) e.getMessage();
         ChannelBuffer header = ChannelBuffers.buffer(8);
         header.writeInt(messageId);
         header.writeInt(body.readableBytes());

         // Update the stateful property.
         messageId ++;

         // Create a message prepended with the header and send a new event.
         ChannelBuffer message = ChannelBuffers.wrappedBuffer(header, body);
         Channels.fireMessageReceived(ctx, message, e.getRemoteAddress());
     }
     ...
 }
 

Version:

$Rev: 472 $, $Date: 2008-11-14 16:45:53 +0900 (Fri, 14 Nov 2008) $

Author:

The Netty Project (netty-dev@lists.jboss.org), Trustin Lee (tlee@redhat.com)

Required Element Summary

String

value The value of this annotation

Element Detail

value

public abstract String value

The value of this annotation