/* * Copyright 2009 Red Hat, Inc. * * 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: * * 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; import java.lang.annotation.Documented; import java.lang.annotation.ElementType; import java.lang.annotation.Inherited; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; import org.jboss.netty.bootstrap.Bootstrap; import org.jboss.netty.channel.group.ChannelGroup; /** * Handles or intercepts a {@link ChannelEvent}, and sends a * {@link ChannelEvent} to the next handler in a {@link ChannelPipeline}. * *
* {@link ChannelHandler} itself does not provide any method. To handle a * {@link ChannelEvent} you need to implement its sub-interfaces. There are * two sub-interfaces which handles a received event, one for upstream events * and the other for downstream events: *
* A {@link ChannelHandler} is provided with a {@link ChannelHandlerContext} * object. A {@link ChannelHandler} is supposed to interact with the * {@link ChannelPipeline} it belongs to via a context object. Using the * context object, the {@link ChannelHandler} can pass events upstream or * downstream, modify the pipeline dynamically, or store the information * (attachment) which is specific to the handler. * *
* public class DataServerHandler extends {@link SimpleChannelHandler} { * * private boolean loggedIn; * * {@code @Override} * public void messageReceived({@link ChannelHandlerContext} ctx, {@link MessageEvent} e) { * {@link Channel} ch = e.getChannel(); * Object o = e.getMessage(); * if (o instanceof LoginMessage) { * authenticate((LoginMessage) o); * loggedIn = true; * } else (o instanceof GetDataMessage) { * if (loggedIn) { * ch.write(fetchSecret((GetDataMessage) o)); * } else { * fail(); * } * } * } * ... * } ** Because the handler instance has a state variable which is dedicated to * one connection, you have to create a new handler instance for each new * channel to avoid a race condition where a unauthenticated client can get * the confidential information: *
* // Create a new handler instance per channel. * // See {@link Bootstrap#setPipelineFactory(ChannelPipelineFactory)}. * public class DataServerPipelineFactory implements {@link ChannelPipelineFactory} { * public {@link ChannelPipeline} getPipeline() { * return {@link Channels}.pipeline(new DataServerHandler()); * } * } ** *
* {@code @Sharable} * public class DataServerHandler extends {@link SimpleChannelHandler} { * * {@code @Override} * public void messageReceived({@link ChannelHandlerContext} ctx, {@link MessageEvent} e) { * {@link Channel} ch = e.getChannel(); * Object o = e.getMessage(); * if (o instanceof LoginMessage) { * authenticate((LoginMessage) o); * ctx.setAttachment(true); * } else (o instanceof GetDataMessage) { * if (Boolean.TRUE.equals(ctx.getAttachment())) { * ch.write(fetchSecret((GetDataMessage) o)); * } else { * fail(); * } * } * } * ... * } ** Now that the state of the handler is stored as an attachment, you can add the * same handler instance to different pipelines: *
* public class DataServerPipelineFactory implements {@link ChannelPipelineFactory} { * * private static final DataServerHandler SHARED = new DataServerHandler(); * * public {@link ChannelPipeline} getPipeline() { * return {@link Channels}.pipeline(SHARED); * } * } ** *
* public final class DataServerState { * * public static final {@link ChannelLocal}<Boolean> loggedIn = new {@link ChannelLocal}<Boolean>() { * protected Boolean initialValue(Channel channel) { * return false; * } * } * ... * } * * {@code @Sharable} * public class DataServerHandler extends {@link SimpleChannelHandler} { * * {@code @Override} * public void messageReceived({@link ChannelHandlerContext} ctx, {@link MessageEvent} e) { * Channel ch = e.getChannel(); * Object o = e.getMessage(); * if (o instanceof LoginMessage) { * authenticate((LoginMessage) o); * DataServerState.loggedIn.set(ch, true); * } else (o instanceof GetDataMessage) { * if (DataServerState.loggedIn.get(ch)) { * ctx.getChannel().write(fetchSecret((GetDataMessage) o)); * } else { * fail(); * } * } * } * ... * } * * // Print the remote addresses of the authenticated clients: * {@link ChannelGroup} allClientChannels = ...; * for ({@link Channel} ch: allClientChannels) { * if (DataServerState.loggedIn.get(ch)) { * System.out.println(ch.getRemoteAddress()); * } * } ** *
* In the examples above which used an attachment or a {@link ChannelLocal}, * you might have noticed the {@code @Sharable} annotation. *
* If a {@link ChannelHandler} is annotated with the {@code @Sharable} * annotation, it means you can create an instance of the handler just once and * add it to one or more {@link ChannelPipeline}s multiple times without * a race condition. *
* If this annotation is not specified, you have to create a new handler * instance every time you add it to a pipeline because it has unshared state * such as member variables. *
* This annotation is provided for documentation purpose, just like * the JCIP annotations. * *
* Please refer to the {@link ChannelEvent} and {@link ChannelPipeline} to find * out what a upstream event and a downstream event are, what fundamental * differences they have, and how they flow in a pipeline. * * @author The Netty Project * @author Trustin Lee * * @version $Rev$, $Date$ * * @apiviz.landmark * @apiviz.exclude ^org\.jboss\.netty\.handler\..*$ */ public interface ChannelHandler { /** * Indicates that the same instance of the annotated {@link ChannelHandler} * can be added to one or more {@link ChannelPipeline}s multiple times * without a race condition. *
* If this annotation is not specified, you have to create a new handler * instance every time you add it to a pipeline because it has unshared * state such as member variables. *
* This annotation is provided for documentation purpose, just like * the JCIP annotations. * * @author The Netty Project * @author Trustin Lee * @version $Rev$, $Date$ */ @Inherited @Documented @Target(ElementType.TYPE) @Retention(RetentionPolicy.RUNTIME) public @interface Sharable { // no value } }