2008-08-08 02:37:18 +02:00
|
|
|
/*
|
2009-08-28 09:15:49 +02:00
|
|
|
* Copyright 2009 Red Hat, Inc.
|
2008-08-08 02:37:18 +02:00
|
|
|
*
|
2009-08-28 09:15:49 +02:00
|
|
|
* Red Hat 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:
|
2008-08-08 02:37:18 +02:00
|
|
|
*
|
2009-08-28 09:15:49 +02:00
|
|
|
* http://www.apache.org/licenses/LICENSE-2.0
|
2008-08-08 03:27:24 +02:00
|
|
|
*
|
2009-08-28 09:15:49 +02:00
|
|
|
* 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.
|
2008-08-08 02:37:18 +02:00
|
|
|
*/
|
2008-08-08 03:40:10 +02:00
|
|
|
package org.jboss.netty.channel;
|
2008-08-08 02:37:18 +02:00
|
|
|
|
2009-09-10 06:25:05 +02:00
|
|
|
|
2008-08-08 02:37:18 +02:00
|
|
|
/**
|
2009-06-17 11:13:10 +02:00
|
|
|
* Provides the properties and operations which are specific to a
|
2008-09-24 12:08:30 +02:00
|
|
|
* {@link ChannelHandler} and the {@link ChannelPipeline} it belongs to.
|
2008-09-24 12:37:19 +02:00
|
|
|
* Via a {@link ChannelHandlerContext}, a {@link ChannelHandler} can send
|
2009-09-03 06:33:15 +02:00
|
|
|
* a {@link ChannelEvent} upstream or downstream, modify the behavior of the
|
|
|
|
* pipeline, or store the information (attachment) which is specific to the
|
|
|
|
* handler.
|
2008-09-24 12:37:19 +02:00
|
|
|
* <pre>
|
2009-06-17 11:13:10 +02:00
|
|
|
* <b>n</b> = the number of the handler entries in a pipeline
|
|
|
|
*
|
2009-04-28 15:35:55 +02:00
|
|
|
* +---------+ 1 .. 1 +----------+ 1 n +---------+ n m +---------+
|
|
|
|
* | Channel |--------| Pipeline |--------| Context |--------| Handler |
|
2009-06-17 11:13:10 +02:00
|
|
|
* +---------+ +----------+ +----+----+ +----+----+
|
|
|
|
* | 1..1 |
|
|
|
|
* +-----+------+ |
|
|
|
|
* | Attachment |<----------+
|
|
|
|
* +------------+ stores
|
2009-04-28 15:35:55 +02:00
|
|
|
* </pre>
|
|
|
|
* 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
|
2009-06-17 11:13:10 +02:00
|
|
|
* 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:
|
2009-04-28 15:35:55 +02:00
|
|
|
* <pre>
|
2010-02-02 03:00:04 +01:00
|
|
|
* public class FactorialHandler extends {@link SimpleChannelHandler} {
|
2009-04-28 16:35:23 +02:00
|
|
|
*
|
|
|
|
* // This handler will receive a sequence of increasing integers starting
|
|
|
|
* // from 1.
|
2010-02-02 03:00:04 +01:00
|
|
|
* {@code @Override}
|
|
|
|
* public void messageReceived({@link ChannelHandlerContext} ctx, {@link MessageEvent} evt) {
|
2009-04-28 15:35:55 +02:00
|
|
|
* Integer a = (Integer) ctx.getAttachment();
|
|
|
|
* Integer b = (Integer) evt.getMessage();
|
|
|
|
*
|
|
|
|
* if (a == null) {
|
2009-04-28 16:35:23 +02:00
|
|
|
* a = 1;
|
2009-04-28 15:35:55 +02:00
|
|
|
* }
|
|
|
|
*
|
2009-04-28 16:35:23 +02:00
|
|
|
* ctx.setAttachment(Integer.valueOf(a * b));
|
2009-04-28 15:35:55 +02:00
|
|
|
* }
|
|
|
|
* }
|
2009-04-28 16:35:23 +02:00
|
|
|
*
|
|
|
|
* // Different context objects are given to "f1", "f2", "f3", and "f4" even if
|
2009-04-28 16:41:48 +02:00
|
|
|
* // they refer to the same handler instance. Because the FactorialHandler
|
2009-04-28 16:35:23 +02:00
|
|
|
* // stores its state in a context object (as an attachment), the factorial is
|
2009-04-28 16:43:20 +02:00
|
|
|
* // calculated correctly 4 times once the two pipelines (p1 and p2) are active.
|
2009-04-28 16:35:23 +02:00
|
|
|
* FactorialHandler fh = new FactorialHandler();
|
|
|
|
*
|
2010-02-02 03:00:04 +01:00
|
|
|
* {@link ChannelPipeline} p1 = {@link Channels}.pipeline();
|
2009-04-28 16:35:23 +02:00
|
|
|
* p1.addLast("f1", fh);
|
|
|
|
* p1.addLast("f2", fh);
|
|
|
|
*
|
2010-02-02 03:00:04 +01:00
|
|
|
* {@link ChannelPipeline} p2 = {@link Channels}.pipeline();
|
2009-04-28 16:35:23 +02:00
|
|
|
* p2.addLast("f3", fh);
|
|
|
|
* p2.addLast("f4", fh);
|
2008-09-24 12:37:19 +02:00
|
|
|
* </pre>
|
2008-08-08 02:37:18 +02:00
|
|
|
*
|
2009-12-29 04:07:20 +01:00
|
|
|
* <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>
|
2010-02-02 03:00:04 +01:00
|
|
|
* public class MyHandler extends {@link SimpleChannelHandler}
|
|
|
|
* implements {@link LifeCycleAwareChannelHandler} {
|
2009-12-29 04:07:20 +01:00
|
|
|
*
|
2010-02-02 03:00:04 +01:00
|
|
|
* private {@link ChannelHandlerContext} ctx;
|
2009-12-29 04:07:20 +01:00
|
|
|
*
|
2010-02-02 03:00:04 +01:00
|
|
|
* public void beforeAdd({@link ChannelHandlerContext} ctx) {
|
2009-12-29 04:07:20 +01:00
|
|
|
* this.ctx = ctx;
|
|
|
|
* }
|
|
|
|
*
|
2010-02-02 03:00:04 +01:00
|
|
|
* {@code @Override}
|
|
|
|
* public void messageReceived({@link ChannelHandlerContext} ctx, {@link MessageEvent} evt) {
|
2009-12-29 04:07:20 +01:00
|
|
|
* ctx.setAttachment(evt.getMessage());
|
|
|
|
* }
|
|
|
|
*
|
|
|
|
* public Object getLastReceivedMessage() {
|
|
|
|
* return ctx.getAttachment();
|
|
|
|
* }
|
|
|
|
* ...
|
|
|
|
* }
|
|
|
|
* </pre>
|
|
|
|
*
|
2009-06-17 11:13:10 +02:00
|
|
|
* <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
|
2009-10-30 08:51:33 +01:00
|
|
|
* event are, what fundamental differences they have, how they flow in a
|
|
|
|
* pipeline, and how to handle the event in your application.
|
2009-06-17 11:13:10 +02:00
|
|
|
*
|
2010-01-26 10:04:19 +01:00
|
|
|
* @author <a href="http://www.jboss.org/netty/">The Netty Project</a>
|
|
|
|
* @author <a href="http://gleamynode.net/">Trustin Lee</a>
|
2008-08-08 02:37:18 +02:00
|
|
|
*
|
|
|
|
* @version $Rev$, $Date$
|
|
|
|
*
|
2008-08-08 03:40:10 +02:00
|
|
|
* @apiviz.owns org.jboss.netty.channel.ChannelHandler
|
2008-08-08 02:37:18 +02:00
|
|
|
*/
|
|
|
|
public interface ChannelHandlerContext {
|
2008-09-02 12:39:57 +02:00
|
|
|
|
2008-12-03 09:31:17 +01:00
|
|
|
/**
|
|
|
|
* Returns the {@link Channel} that the {@link ChannelPipeline} belongs to.
|
|
|
|
* This method is a shortcut to <tt>getPipeline().getChannel()</tt>.
|
|
|
|
*/
|
|
|
|
Channel getChannel();
|
|
|
|
|
2008-09-02 12:39:57 +02:00
|
|
|
/**
|
|
|
|
* Returns the {@link ChannelPipeline} that the {@link ChannelHandler}
|
|
|
|
* belongs to.
|
|
|
|
*/
|
2008-08-08 02:37:18 +02:00
|
|
|
ChannelPipeline getPipeline();
|
|
|
|
|
2008-09-02 12:39:57 +02:00
|
|
|
/**
|
|
|
|
* Returns the name of the {@link ChannelHandler} in the
|
|
|
|
* {@link ChannelPipeline}.
|
|
|
|
*/
|
2008-08-08 02:37:18 +02:00
|
|
|
String getName();
|
2008-09-02 12:39:57 +02:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Returns the {@link ChannelHandler} that this context object is
|
|
|
|
* serving.
|
|
|
|
*/
|
2008-08-08 02:37:18 +02:00
|
|
|
ChannelHandler getHandler();
|
2008-09-02 12:39:57 +02:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Returns {@code true} if and only if the {@link ChannelHandler} is an
|
|
|
|
* instance of {@link ChannelUpstreamHandler}.
|
|
|
|
*/
|
2008-08-08 02:37:18 +02:00
|
|
|
boolean canHandleUpstream();
|
2008-09-02 12:39:57 +02:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Returns {@code true} if and only if the {@link ChannelHandler} is an
|
|
|
|
* instance of {@link ChannelDownstreamHandler}.
|
|
|
|
*/
|
2008-08-08 02:37:18 +02:00
|
|
|
boolean canHandleDownstream();
|
|
|
|
|
2008-09-02 12:39:57 +02:00
|
|
|
/**
|
2009-09-03 06:33:15 +02:00
|
|
|
* 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.
|
2008-09-02 12:39:57 +02:00
|
|
|
*/
|
2008-08-08 02:37:18 +02:00
|
|
|
void sendUpstream(ChannelEvent e);
|
2008-09-02 12:39:57 +02:00
|
|
|
|
|
|
|
/**
|
2009-09-03 06:33:15 +02:00
|
|
|
* 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.
|
2008-09-02 12:39:57 +02:00
|
|
|
*/
|
2008-08-08 02:37:18 +02:00
|
|
|
void sendDownstream(ChannelEvent e);
|
2009-03-11 11:53:52 +01:00
|
|
|
|
2009-06-17 11:13:10 +02:00
|
|
|
/**
|
|
|
|
* 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
|
|
|
|
*/
|
2009-03-11 11:53:52 +01:00
|
|
|
Object getAttachment();
|
2009-06-17 11:13:10 +02:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Attaches an object to this context to store a stateful information
|
|
|
|
* specific to the {@link ChannelHandler} which is associated with this
|
|
|
|
* context.
|
|
|
|
*/
|
2009-03-11 11:53:52 +01:00
|
|
|
void setAttachment(Object attachment);
|
2009-08-28 09:15:49 +02:00
|
|
|
}
|