2008-08-08 02:37:18 +02:00
|
|
|
/*
|
2008-08-08 03:27:24 +02:00
|
|
|
* JBoss, Home of Professional Open Source
|
2008-08-08 02:37:18 +02:00
|
|
|
*
|
2008-08-08 03:27:24 +02:00
|
|
|
* Copyright 2008, Red Hat Middleware LLC, and individual contributors
|
|
|
|
* by the @author tags. See the COPYRIGHT.txt in the distribution for a
|
|
|
|
* full listing of individual contributors.
|
2008-08-08 02:37:18 +02:00
|
|
|
*
|
2008-08-08 03:27:24 +02:00
|
|
|
* This is free software; you can redistribute it and/or modify it
|
|
|
|
* under the terms of the GNU Lesser General Public License as
|
|
|
|
* published by the Free Software Foundation; either version 2.1 of
|
|
|
|
* the License, or (at your option) any later version.
|
|
|
|
*
|
|
|
|
* This software is distributed in the hope that it will be useful,
|
2008-08-08 02:37:18 +02:00
|
|
|
* but WITHOUT ANY WARRANTY; without even the implied warranty of
|
2008-08-08 03:27:24 +02:00
|
|
|
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
2008-08-08 02:37:18 +02:00
|
|
|
* Lesser General Public License for more details.
|
|
|
|
*
|
|
|
|
* You should have received a copy of the GNU Lesser General Public
|
2008-08-08 03:27:24 +02:00
|
|
|
* License along with this software; if not, write to the Free
|
|
|
|
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
|
|
|
|
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
|
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
|
|
|
|
|
|
|
/**
|
2008-09-24 12:08:30 +02:00
|
|
|
* Provides the properties and operations which are specific to the
|
|
|
|
* {@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
|
2008-11-14 09:02:42 +01:00
|
|
|
* an upstream or downstream {@link ChannelEvent} to the next or previous
|
2009-04-28 15:35:55 +02:00
|
|
|
* {@link ChannelHandler} in a {@link ChannelPipeline}.
|
2008-09-24 12:37:19 +02:00
|
|
|
*
|
|
|
|
* <pre>
|
2009-04-28 15:35:55 +02:00
|
|
|
* +---------+ 1 .. 1 +----------+ 1 n +---------+ n m +---------+
|
|
|
|
* | Channel |--------| Pipeline |--------| Context |--------| Handler |
|
|
|
|
* +---------+ +----------+ +---------+ +---------+
|
2009-04-28 15:39:06 +02:00
|
|
|
* n = the number of the handler entries in a pipeline
|
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
|
|
|
|
* 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:
|
|
|
|
* <pre>
|
2009-04-28 16:35:23 +02:00
|
|
|
* public class FactorialHandler extends SimpleUpstreamChannelHandler {
|
|
|
|
*
|
|
|
|
* // This handler will receive a sequence of increasing integers starting
|
|
|
|
* // from 1.
|
2009-04-28 15:35:55 +02:00
|
|
|
* public void messageReceived(ChannelHandlerContext ctx, MessageEvent evt) {
|
|
|
|
* 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
|
|
|
|
* // calculated correctly 4 times.
|
|
|
|
* FactorialHandler fh = new FactorialHandler();
|
|
|
|
*
|
|
|
|
* ChannelPipeline p1 = Channels.pipeline();
|
|
|
|
* p1.addLast("f1", fh);
|
|
|
|
* p1.addLast("f2", fh);
|
|
|
|
*
|
|
|
|
* ChannelPipeline p2 = Channels.pipeline();
|
|
|
|
* 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
|
|
|
*
|
2008-08-08 03:27:24 +02:00
|
|
|
* @author The Netty Project (netty-dev@lists.jboss.org)
|
|
|
|
* @author Trustin Lee (tlee@redhat.com)
|
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
|
|
|
/**
|
2008-09-03 05:04:51 +02:00
|
|
|
* Sends the specified {@link ChannelEvent} to the next
|
|
|
|
* {@link ChannelUpstreamHandler} in the {@link ChannelPipeline}. It is
|
|
|
|
* recommended to use the event generation 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
|
|
|
|
|
|
|
/**
|
2008-09-03 05:04:51 +02:00
|
|
|
* Sends the specified {@link ChannelEvent} to the previous
|
|
|
|
* {@link ChannelDownstreamHandler} in the {@link ChannelPipeline}. It is
|
|
|
|
* recommended to use the event generation 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
|
|
|
|
|
|
|
Object getAttachment();
|
|
|
|
void setAttachment(Object attachment);
|
2008-08-08 02:37:18 +02:00
|
|
|
}
|