io.netty.channel.ChannelHandlerContext Maven / Gradle / Ivy
/*
* Copyright 2012 The Netty Project
*
* The Netty Project licenses this file to you under the Apache License,
* version 2.0 (the "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at:
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
* License for the specific language governing permissions and limitations
* under the License.
*/
package io.netty.channel;
import io.netty.buffer.BufType;
import io.netty.buffer.ByteBuf;
import io.netty.buffer.MessageBuf;
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. A handler can notify the next {@link ChannelHandler} in the {@link ChannelPipeline},
* modify the {@link ChannelPipeline} it belongs to dynamically.
*
* Notify
*
* You can notify the closest handler in the
* same {@link ChannelPipeline} by calling one of the various methods which are listed in {@link ChannelInboundInvoker}
* and {@link ChannelOutboundInvoker}. Please refer to {@link ChannelPipeline} to understand how an event flows.
*
* Modifying a 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 in runtime.
*
* Retrieving for later use
*
* You can keep the {@link ChannelHandlerContext} for later use, such as
* triggering an event outside the handler methods, even from a different thread.
*
* public class MyHandler extends {@link ChannelDuplexHandler} {
*
* private {@link ChannelHandlerContext} ctx;
*
* public void beforeAdd({@link ChannelHandlerContext} ctx) {
* this.ctx = ctx;
* }
*
* public void login(String username, password) {
* ctx.write(new LoginMessage(username, password));
* }
* ...
* }
*
*
* Storing stateful information
*
* {@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.
*
* A handler can have more than one context
*
* 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.
*
* For example, the following handler will have as many independent attachments
* 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:
*
* public class FactorialHandler extends {@link ChannelInboundMessageHandlerAdapter}<{@link Integer}> {
*
* private final {@link AttributeKey}<{@link Integer}> counter =
* new {@link AttributeKey}<{@link Integer}>("counter");
*
* // 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}<{@link Integer}> attr = ctx.getAttr(counter);
* Integer a = ctx.getAttr(counter).get();
*
* if (a == null) {
* a = 1;
* }
*
* attr.set(a * integer));
* }
* }
*
* // 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 (as an attachment), 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);
*
*
* 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.
*/
public interface ChannelHandlerContext
extends AttributeMap, ChannelPropertyAccess,
ChannelInboundInvoker, ChannelOutboundInvoker {
/**
* Return the {@link Channel} which is bound to the {@link ChannelHandlerContext}.
*/
Channel channel();
/**
* The {@link EventExecutor} that is used to dispatch the events. This can also be used to directly
* submit tasks that get executed in the event loop. For more informations please refer to the
* {@link EventExecutor} javadocs.
*/
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}.
*/
String name();
/**
* The {@link ChannelHandler} that is bound this {@link ChannelHandlerContext}.
*/
ChannelHandler handler();
/**
* Return {@code true} if the {@link ChannelHandlerContext} has an {@link ByteBuf} bound for inbound
* which can be used.
*/
boolean hasInboundByteBuffer();
/**
* Return {@code true} if the {@link ChannelHandlerContext} has a {@link MessageBuf} bound for inbound
* which can be used.
*/
boolean hasInboundMessageBuffer();
/**
* Return the bound {@link ByteBuf} for inbound data if {@link #hasInboundByteBuffer()} returned
* {@code true}. If {@link #hasInboundByteBuffer()} returned {@code false} it will throw a
* {@link UnsupportedOperationException}.
*
* This method can only be called from within the event-loop, otherwise it will throw an
* {@link IllegalStateException}.
*/
ByteBuf inboundByteBuffer();
/**
* Return the bound {@link MessageBuf} for inbound data if {@link #hasInboundMessageBuffer()} returned
* {@code true}. If {@link #hasInboundMessageBuffer()} returned {@code false} it will throw a
* {@link UnsupportedOperationException}.
*
* This method can only be called from within the event-loop, otherwise it will throw an
* {@link IllegalStateException}.
*/
MessageBuf inboundMessageBuffer();
/**
* Return {@code true} if the {@link ChannelHandlerContext} has an {@link ByteBuf} bound for outbound
* data which can be used.
*
*/
boolean hasOutboundByteBuffer();
/**
* Return {@code true} if the {@link ChannelHandlerContext} has a {@link MessageBuf} bound for outbound
* which can be used.
*/
boolean hasOutboundMessageBuffer();
/**
* Return the bound {@link ByteBuf} for outbound data if {@link #hasOutboundByteBuffer()} returned
* {@code true}. If {@link #hasOutboundByteBuffer()} returned {@code false} it will throw
* a {@link UnsupportedOperationException}.
*
* This method can only be called from within the event-loop, otherwise it will throw an
* {@link IllegalStateException}.
*/
ByteBuf outboundByteBuffer();
/**
* Return the bound {@link MessageBuf} for outbound data if {@link #hasOutboundMessageBuffer()} returned
* {@code true}. If {@link #hasOutboundMessageBuffer()} returned {@code false} it will throw a
* {@link UnsupportedOperationException}.
*
* This method can only be called from within the event-loop, otherwise it will throw an
* {@link IllegalStateException}.
*/
MessageBuf outboundMessageBuffer();
/**
* Return the {@link ByteBuf} of the next {@link ChannelInboundByteHandler} in the pipeline.
*/
ByteBuf nextInboundByteBuffer();
/**
* Return the {@link MessageBuf} of the next {@link ChannelInboundMessageHandler} in the pipeline.
*/
MessageBuf