netty Asynchronous Task-ChannelFuture: http://donald-draper.iteye.com/blog/2388297
netty Pipeline Definition-ChannelPipeline: http://donald-draper.iteye.com/blog/2388453
netty default Channel pipeline initialization: http://donald-draper.iteye.com/blog/2388613
netty default Channel pipeline - adding channel handlers: http: //donald-draper.iteye.com/blog/2388726
netty default Channel pipeline - channel handler removal and replacement: http://donald-draper.iteye.com/blog/2388793
netty default Channel pipeline - Inbound and Outbound event handling: http://donald-draper.iteye.com/blog/2389148
Introduction:
In the previous articles, we looked at the default implementation of the Channel pipeline, each channel has a Channel pipeline, the pipeline is used to manage the channel processor, the pipeline manages the channel processor in context mode, and each channel context has a predecessor and a successor Context, it can be said that the channel context is a doubly linked list in the pipeline, the head of the context linked list is HeadContext, and the tail is TailContext. The pipeline mainly judges the context type by the inbound and oubound flags of the context. The pipeline processes inbound events from the head context to the tail context, and finally discards it directly by default. The pipeline processes outbound related events, from the tail context to the head context, and when it reaches the head, it is processed by the Unsafe of the Channel associated with the context pipeline.
Today we look at the definition of the channel processor context interface:
package io.netty.channel;
import io.netty.buffer.ByteBuf;
import io.netty.buffer.ByteBufAllocator;
import io.netty.util.Attribute;
import io.netty.util.AttributeKey;
import io.netty.util.AttributeMap;
import io.netty.util.concurrent.EventExecutor;
import java.nio.channels.Channels;
/**
* 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.
* The channel handler context ChannelHandlerContext enables the channel handler to interact with the pipeline and other handlers in the pipeline.
When an IO event occurs, the processing can forward the event to the next channel processor of the pipeline to which it belongs, and can dynamically modify the pipeline to which the processor belongs.
* <h3>Notify</h3>
*notify
* You can notify the closest handler in the same {@link ChannelPipeline} by calling one of the various methods
* provided here.
*You can use the provided method to notify adjacent channel handlers of event triggering.
* Please refer to {@link ChannelPipeline} to understand how an event flows.
*Also can refer to the pipeline to understand the event flow
* <h3>Modifying a pipeline</h3>
* Modify the pipeline
* 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.
* You can use the #pipeline method of the channel processor context to get the pipeline to which the processor belongs. References in the runtime environment
, it is possible to insert and remove processors in the replacement pipeline
* <h3>Retrieving for later use</h3>
*Used to obtain relevant information
* You can keep the {@link ChannelHandlerContext} for later use, such as
* triggering an event outside the handler methods, even from a different thread.
You can save the channel handler context for use in event triggering outside of the channel handler method, or even in a different thread.
* <pre>
Below is an example that saves context information
* 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>
*Stores information, but is currently abandoned
* {@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.
The *#attr(AttributeKey) method allows you to store information associated with the channel handler and context. Refer to Channel Processor to learn more about management
Handler and context attribute methods.
* <h3>A handler can have more than one context</h3>
* A process can have multiple associated contexts
* 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.
It is important to note that channel processor instances can be added to multiple pipelines. means that a channel handler can have multiple contexts,
If the channel handler is added to more than one pipeline, then the instance can be called by multiple contexts.
* <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:
For example, the following processor can have many independent properties because it is added to the channel multiple times, no matter if a channel is added multiple times,
Still different pipes multiple times.
* <pre>
* public class FactorialHandler extends {@link ChannelInboundHandlerAdapter} {
*
* private final {@link AttributeKey}<{@link Integer}> 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();
*
The corresponding contexts "f1", "f2", "f3", and "f4" are not the same, even though they refer to the same processor instance.
Since the handler stores a context property, once the pipeline is activated, it will be called 4 times.
* {@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>Additional resources worth reading
* 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.
Please refer to Channel Processors and Pipelines for more information on inbound and outbound operations, as well as the basic differences between the two operations, how to transmit and
How actions are handled in the app.
*/
public interface ChannelHandlerContext extends AttributeMap, ChannelInboundInvoker, ChannelOutboundInvoker {
/**
* Return the {@link Channel} which is bound to the {@link ChannelHandlerContext}.
Get the channel handler context associated channel
*/
Channel channel();
/**
* Returns the {@link EventExecutor} which is used to execute an arbitrary task.
Get the context event executor for executing the task
*/
EventExecutor executor();
/**
* The unique name of the {@link ChannelHandlerContext}.The name was used when then {@link ChannelHandler}
* was added to the {@link ChannelPipeline}. This name can also be used to access the registered
* {@link ChannelHandler} from the {@link ChannelPipeline}.
The name of the channel context, which is the name of the channel handler when it was added to the pipeline. This name can get the corresponding channel handler from the pipe
*/
String name();
/**
* The {@link ChannelHandler} that is bound this {@link ChannelHandlerContext}.
Get the context associated channel handler
*/
ChannelHandler handler();
/**
* Return {@code true} if the {@link ChannelHandler} which belongs to this context was removed
* from the {@link ChannelPipeline}. Note that this method is only meant to be called from with in the
* {@link EventLoop}.
Determines whether the context associated with the current channel handler is removed from the pipeline. This method is called in the event loop
*/
boolean isRemoved();
//Trigger Inbound event method
@Override
ChannelHandlerContext fireChannelRegistered();
@Override
ChannelHandlerContext fireChannelUnregistered();
@Override
ChannelHandlerContext fireChannelActive();
@Override
ChannelHandlerContext fireChannelInactive();
@Override
ChannelHandlerContext fireExceptionCaught(Throwable cause);
@Override
ChannelHandlerContext fireUserEventTriggered(Object evt);
@Override
ChannelHandlerContext fireChannelRead(Object msg);
@Override
ChannelHandlerContext fireChannelReadComplete();
@Override
ChannelHandlerContext fireChannelWritabilityChanged();
@Override
ChannelHandlerContext read();
@Override
ChannelHandlerContext flush();
/**
* Return the assigned {@link ChannelPipeline}
Get the owning pipeline
*/
ChannelPipeline pipeline();
/**
* Return the assigned {@link ByteBufAllocator} which will be used to allocate {@link ByteBuf}s.
Get the byte buf allocator of the channel context for allocating buf
*/
ByteBufAllocator alloc();
/**
* @deprecated Use {@link Channel#attr(AttributeKey)}
Get the attribute value of the specified key, discarded
*/
@Deprecated
@Override
<T> Attribute<T> attr(AttributeKey<T> key);
/**
* @deprecated Use {@link Channel#hasAttr(AttributeKey)}
Determine if there is an attribute value
*/
@Deprecated
@Override
<T> boolean hasAttr(AttributeKey<T> key);
}
Summary:
The channel handler context ChannelHandlerContext enables the channel handler to interact with the pipeline and other processors in the pipeline. When an IO event occurs, the processing can forward the event to the next channel processor of the pipeline to which it belongs, and can dynamically modify the pipeline to which the processor belongs. Through the context, you can obtain information such as associated channels, processors, event executors, context names, and belonging pipes. At the same time, you can store context attributes through AttributeKey, and use the alloc method to obtain the byte buf allocator of the channel context for allocating buf.
Attached:
//AttributeMap
package io.netty.util;
/**
* Holds {@link Attribute}s which can be accessed via {@link AttributeKey}.
*
* Implementations must be Thread-safe.
*/
public interface AttributeMap {
/**
* Get the {@link Attribute} for the given {@link AttributeKey}. This method will never return null, but may return
* an {@link Attribute} which does not have a value set yet.
*/
<T> Attribute<T> attr(AttributeKey<T> key);
/**
* Returns {@code} true if and only if the given {@link Attribute} exists in this {@link AttributeMap}.
*/
<T> boolean hasAttr(AttributeKey<T> key);
}
//AttributeKey
/**
* Key which can be used to access {@link Attribute} out of the {@link AttributeMap}. Be aware that it is not be
* possible to have multiple keys with the same name.
*
* @param <T> the type of the {@link Attribute} which can be accessed via this {@link AttributeKey}.
*/
@SuppressWarnings("UnusedDeclaration") // 'T' is used only at compile time
public final class AttributeKey<T> extends AbstractConstant<AttributeKey<T>> {
private static final ConstantPool<AttributeKey<Object>> pool = new ConstantPool<AttributeKey<Object>>() {
//ConstantPool
/**
* A pool of {@link Constant}s.
*
* @param <T> the type of the constant
*/
public abstract class ConstantPool<T extends Constant<T>> {
private final ConcurrentMap<String, T> constants = PlatformDependent.newConcurrentHashMap();
private final AtomicInteger nextId = new AtomicInteger(1);
//ByteBufAllocator
/**
* Implementations are responsible to allocate buffers. Implementations of this interface are expected to be
* thread-safe.
*/
public interface ByteBufAllocator {
ByteBufAllocator DEFAULT = ByteBufUtil.DEFAULT_ALLOCATOR;
/**
* Allocate a {@link ByteBuf}. If it is a direct or heap buffer
* depends on the actual implementation.
*/
ByteBuf buffer();
/**
* Allocate a {@link ByteBuf} with the given initial capacity.
* If it is a direct or heap buffer depends on the actual implementation.
*/
ByteBuf buffer(int initialCapacity);
/**
* Allocate a {@link ByteBuf} with the given initial capacity and the given
* maximal capacity. If it is a direct or heap buffer depends on the actual
* implementation.
*/
ByteBuf buffer(int initialCapacity, int maxCapacity);
/**
* Allocate a {@link ByteBuf}, preferably a direct buffer which is suitable for I/O.
*/
ByteBuf ioBuffer();
/**
* Allocate a {@link ByteBuf}, preferably a direct buffer which is suitable for I/O.
*/
ByteBuf ioBuffer(int initialCapacity);
/**
* Allocate a {@link ByteBuf}, preferably a direct buffer which is suitable for I/O.
*/
ByteBuf ioBuffer(int initialCapacity, int maxCapacity);
/**
* Allocate a heap {@link ByteBuf}.
*/
ByteBuf heapBuffer();
/**
* Allocate a heap {@link ByteBuf} with the given initial capacity.
*/
ByteBuf heapBuffer(int initialCapacity);
/**
* Allocate a heap {@link ByteBuf} with the given initial capacity and the given
* maximal capacity.
*/
ByteBuf heapBuffer(int initialCapacity, int maxCapacity);
/**
* Allocate a direct {@link ByteBuf}.
*/
ByteBuf directBuffer();
/**
* Allocate a direct {@link ByteBuf} with the given initial capacity.
*/
ByteBuf directBuffer(int initialCapacity);
/**
* Allocate a direct {@link ByteBuf} with the given initial capacity and the given
* maximal capacity.
*/
ByteBuf directBuffer(int initialCapacity, int maxCapacity);
/**
* Allocate a {@link CompositeByteBuf}.
* If it is a direct or heap buffer depends on the actual implementation.
*/
CompositeByteBuf compositeBuffer();
/**
* Allocate a {@link CompositeByteBuf} with the given maximum number of components that can be stored in it.
* If it is a direct or heap buffer depends on the actual implementation.
*/
CompositeByteBuf compositeBuffer(int maxNumComponents);
/**
* Allocate a heap {@link CompositeByteBuf}.
*/
CompositeByteBuf compositeHeapBuffer();
/**
* Allocate a heap {@link CompositeByteBuf} with the given maximum number of components that can be stored in it.
*/
CompositeByteBuf compositeHeapBuffer(int maxNumComponents);
/**
* Allocate a direct {@link CompositeByteBuf}.
*/
CompositeByteBuf compositeDirectBuffer();
/**
* Allocate a direct {@link CompositeByteBuf} with the given maximum number of components that can be stored in it.
*/
CompositeByteBuf compositeDirectBuffer(int maxNumComponents);
/**
* Returns {@code true} if direct {@link ByteBuf}'s are pooled
*/
boolean isDirectBufferPooled();
/**
* Calculate the new capacity of a {@link ByteBuf} that is used when a {@link ByteBuf} needs to expand by the
* {@code minNewCapacity} with {@code maxCapacity} as upper-bound.
*/
int calculateNewCapacity(int minNewCapacity, int maxCapacity);
}