/*
* Copyright 2011 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 org.jboss.netty.channel;
/**
* Enables a {@link ChannelHandler} to interact with its {@link ChannelPipeline}
* and other handlers. A handler can send a {@link ChannelEvent} upstream or
* downstream, modify the {@link ChannelPipeline} it belongs to dynamically.
*
* <h3>Sending an event</h3>
*
* You can send or forward a {@link ChannelEvent} to the closest handler in the
* same {@link ChannelPipeline} by calling {@link #sendUpstream(ChannelEvent)}
* or {@link #sendDownstream(ChannelEvent)}. 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 #getPipeline()}. A non-trivial application could insert, remove, or
* replace handlers in the pipeline dynamically in 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 SimpleChannelHandler}
* implements {@link LifeCycleAwareChannelHandler} {
*
* <b>private {@link ChannelHandlerContext} ctx;</b>
*
* public void beforeAdd({@link ChannelHandlerContext} ctx) {
* <b>this.ctx = ctx;</b>
* }
*
* public void login(String username, password) {
* {@link Channels}.write(
* <b>this.ctx</b>,
* {@link Channels}.succeededFuture(<b>this.ctx.getChannel()</b>),
* new LoginMessage(username, password));
* }
* ...
* }
* </pre>
*
* <h3>Storing stateful information</h3>
*
* {@link #setAttachment(Object)} and {@link #getAttachment()} 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 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:
* <pre>
* public class FactorialHandler extends {@link SimpleChannelHandler} {
*
* // This handler will receive a sequence of increasing integers starting
* // from 1.
* {@code @Override}
* public void messageReceived({@link ChannelHandlerContext} ctx, {@link MessageEvent} evt) {
* Integer a = (Integer) ctx.getAttachment();
* Integer b = (Integer) evt.getMessage();
*
* if (a == null) {
* a = 1;
* }
*
* ctx.setAttachment(Integer.valueOf(a * b));
* }
* }
*
* // 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);
* </pre>
*
* <h3>Additional resources worth reading</h3>
* <p>
* Please refer to the {@link ChannelHandler}, {@link ChannelEvent}, and
* {@link ChannelPipeline} to find out what a upstream event and a downstream
* event are, what fundamental differences they have, how they flow in a
* pipeline, and how to handle the event in your application.
*
* @apiviz.owns org.jboss.netty.channel.ChannelHandler
*/
public interface ChannelHandlerContext {
/**
* Returns the {@link Channel} that the {@link ChannelPipeline} belongs to.
* This method is a shortcut to <tt>getPipeline().getChannel()</tt>.
*/
Channel getChannel();
/**
* Returns the {@link ChannelPipeline} that the {@link ChannelHandler}
* belongs to.
*/
ChannelPipeline getPipeline();
/**
* Returns the name of the {@link ChannelHandler} in the
* {@link ChannelPipeline}.
*/
String getName();
/**
* Returns the {@link ChannelHandler} that this context object is
* serving.
*/
ChannelHandler getHandler();
/**
* Returns {@code true} if and only if the {@link ChannelHandler} is an
* instance of {@link ChannelUpstreamHandler}.
*/
boolean canHandleUpstream();
/**
* Returns {@code true} if and only if the {@link ChannelHandler} is an
* instance of {@link ChannelDownstreamHandler}.
*/
boolean canHandleDownstream();
/**
* Sends the specified {@link ChannelEvent} to the
* {@link ChannelUpstreamHandler} which is placed in the closest upstream
* from the handler associated with this context. It is recommended to use
* the shortcut methods in {@link Channels} rather than calling this method
* directly.
*/
void sendUpstream(ChannelEvent e);
/**
* Sends the specified {@link ChannelEvent} to the
* {@link ChannelDownstreamHandler} which is placed in the closest
* downstream from the handler associated with this context. It is
* recommended to use the shortcut methods in {@link Channels} rather than
* calling this method directly.
*/
void sendDownstream(ChannelEvent e);
/**
* Retrieves an object which is {@link #setAttachment(Object) attached} to
* this context.
*
* @return {@code null} if no object was attached or
* {@code null} was attached
*/
Object getAttachment();
/**
* Attaches an object to this context to store a stateful information
* specific to the {@link ChannelHandler} which is associated with this
* context.
*/
void setAttachment(Object attachment);
}