/* * 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 io.netty.channel; import io.netty.util.AttributeMap; import java.net.SocketAddress; /** * 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. * *
* public class MyHandler extends {@link SimpleChannelHandler} * implements {@link LifeCycleAwareChannelHandler} { * * private {@link ChannelHandlerContext} ctx; * * public void beforeAdd({@link ChannelHandlerContext} ctx) { * this.ctx = ctx; * } * * public void login(String username, password) { * {@link Channels}.write( * this.ctx, * {@link Channels}.succeededFuture(this.ctx.getChannel()), * new LoginMessage(username, password)); * } * ... * } ** *
* 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 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); ** *
* 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 io.netty.channel.ChannelHandler */ public interface ChannelHandlerContext extends AttributeMap { String name(); Channel channel(); ChannelHandler handler(); NextHandler next(); // XXX: What happens if inbound queue is bounded (limited capacity) and it's full? // 1) EventLoop removes OP_READ // 2) Once the first inbound buffer is drained to some level, EventLoop adds OP_READ again. // * To achieve this, EventLoop has to specify a wrapped Queue when calling inboundBufferUpdated. interface NextHandler { // For readers void channelRegistered(); void channelUnregistered(); void channelActive(); void channelInactive(); void exceptionCaught(Throwable cause); void userEventTriggered(Object event); ChannelBufferHolder