e3846c54f6
Motivation: ChannelHandler.exceptionCaught(...) was marked as @deprecated as it should only exist in inbound handlers. Modifications: Remove ChannelHandler.exceptionCaught(...) and adjust code / tests. Result: Fixes https://github.com/netty/netty/issues/8527
237 lines
9.0 KiB
Java
237 lines
9.0 KiB
Java
/*
|
|
* Copyright 2012 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.Attribute;
|
|
import io.netty.util.AttributeKey;
|
|
|
|
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;
|
|
|
|
/**
|
|
* Handles an I/O event or intercepts an I/O operation, and forwards it to its next handler in
|
|
* its {@link ChannelPipeline}.
|
|
*
|
|
* <h3>Sub-types</h3>
|
|
* <p>
|
|
* {@link ChannelHandler} itself does not provide many methods, but you usually have to implement one of its subtypes:
|
|
* <ul>
|
|
* <li>{@link ChannelInboundHandler} to handle inbound I/O events, and</li>
|
|
* <li>{@link ChannelOutboundHandler} to handle outbound I/O operations.</li>
|
|
* </ul>
|
|
* </p>
|
|
* <p>
|
|
* Alternatively, the following adapter classes are provided for your convenience:
|
|
* <ul>
|
|
* <li>{@link ChannelInboundHandlerAdapter} to handle inbound I/O events,</li>
|
|
* <li>{@link ChannelOutboundHandlerAdapter} to handle outbound I/O operations, and</li>
|
|
* <li>{@link ChannelDuplexHandler} to handle both inbound and outbound events</li>
|
|
* </ul>
|
|
* </p>
|
|
* <p>
|
|
* For more information, please refer to the documentation of each subtype.
|
|
* </p>
|
|
*
|
|
* <h3>The context object</h3>
|
|
* <p>
|
|
* 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
|
|
* (using {@link AttributeKey}s) which is specific to the handler.
|
|
*
|
|
* <h3>State management</h3>
|
|
*
|
|
* A {@link ChannelHandler} often needs to store some stateful information.
|
|
* The simplest and recommended approach is to use member variables:
|
|
* <pre>
|
|
* public interface Message {
|
|
* // your methods here
|
|
* }
|
|
*
|
|
* public class DataServerHandler extends {@link SimpleChannelInboundHandler}<Message> {
|
|
*
|
|
* <b>private boolean loggedIn;</b>
|
|
*
|
|
* {@code @Override}
|
|
* public void channelRead0({@link ChannelHandlerContext} ctx, Message message) {
|
|
* if (message instanceof LoginMessage) {
|
|
* authenticate((LoginMessage) message);
|
|
* <b>loggedIn = true;</b>
|
|
* } else (message instanceof GetDataMessage) {
|
|
* if (<b>loggedIn</b>) {
|
|
* ctx.writeAndFlush(fetchSecret((GetDataMessage) message));
|
|
* } else {
|
|
* fail();
|
|
* }
|
|
* }
|
|
* }
|
|
* ...
|
|
* }
|
|
* </pre>
|
|
* 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:
|
|
* <pre>
|
|
* // Create a new handler instance per channel.
|
|
* // See {@link ChannelInitializer#initChannel(Channel)}.
|
|
* public class DataServerInitializer extends {@link ChannelInitializer}<{@link Channel}> {
|
|
* {@code @Override}
|
|
* public void initChannel({@link Channel} channel) {
|
|
* channel.pipeline().addLast("handler", <b>new DataServerHandler()</b>);
|
|
* }
|
|
* }
|
|
*
|
|
* </pre>
|
|
*
|
|
* <h4>Using {@link AttributeKey}s</h4>
|
|
*
|
|
* Although it's recommended to use member variables to store the state of a
|
|
* handler, for some reason you might not want to create many handler instances.
|
|
* In such a case, you can use {@link AttributeKey}s which is provided by
|
|
* {@link ChannelHandlerContext}:
|
|
* <pre>
|
|
* public interface Message {
|
|
* // your methods here
|
|
* }
|
|
*
|
|
* {@code @Sharable}
|
|
* public class DataServerHandler extends {@link SimpleChannelInboundHandler}<Message> {
|
|
* private final {@link AttributeKey}<{@link Boolean}> auth =
|
|
* {@link AttributeKey#valueOf(String) AttributeKey.valueOf("auth")};
|
|
*
|
|
* {@code @Override}
|
|
* public void channelRead({@link ChannelHandlerContext} ctx, Message message) {
|
|
* {@link Attribute}<{@link Boolean}> attr = ctx.attr(auth);
|
|
* if (message instanceof LoginMessage) {
|
|
* authenticate((LoginMessage) o);
|
|
* <b>attr.set(true)</b>;
|
|
* } else (message instanceof GetDataMessage) {
|
|
* if (<b>Boolean.TRUE.equals(attr.get())</b>) {
|
|
* ctx.writeAndFlush(fetchSecret((GetDataMessage) o));
|
|
* } else {
|
|
* fail();
|
|
* }
|
|
* }
|
|
* }
|
|
* ...
|
|
* }
|
|
* </pre>
|
|
* Now that the state of the handler is attached to the {@link ChannelHandlerContext}, you can add the
|
|
* same handler instance to different pipelines:
|
|
* <pre>
|
|
* public class DataServerInitializer extends {@link ChannelInitializer}<{@link Channel}> {
|
|
*
|
|
* private static final DataServerHandler <b>SHARED</b> = new DataServerHandler();
|
|
*
|
|
* {@code @Override}
|
|
* public void initChannel({@link Channel} channel) {
|
|
* channel.pipeline().addLast("handler", <b>SHARED</b>);
|
|
* }
|
|
* }
|
|
* </pre>
|
|
*
|
|
*
|
|
* <h4>The {@code @Sharable} annotation</h4>
|
|
* <p>
|
|
* In the example above which used an {@link AttributeKey},
|
|
* you might have noticed the {@code @Sharable} annotation.
|
|
* <p>
|
|
* 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.
|
|
* <p>
|
|
* 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.
|
|
* <p>
|
|
* This annotation is provided for documentation purpose, just like
|
|
* <a href="http://www.javaconcurrencyinpractice.com/annotations/doc/">the JCIP annotations</a>.
|
|
*
|
|
* <h3>Additional resources worth reading</h3>
|
|
* <p>
|
|
* Please refer to the {@link ChannelHandler}, and
|
|
* {@link ChannelPipeline} to find out more about inbound and outbound operations,
|
|
* what fundamental differences they have, how they flow in a pipeline, and how to handle
|
|
* the operation in your application.
|
|
*/
|
|
public interface ChannelHandler {
|
|
|
|
/**
|
|
* Gets called after the {@link ChannelHandler} was added to the actual context and it's ready to handle events.
|
|
*/
|
|
void handlerAdded(ChannelHandlerContext ctx) throws Exception;
|
|
|
|
/**
|
|
* Gets called after the {@link ChannelHandler} was removed from the actual context and it doesn't handle events
|
|
* anymore.
|
|
*/
|
|
void handlerRemoved(ChannelHandlerContext ctx) throws Exception;
|
|
|
|
/**
|
|
* 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.
|
|
* <p>
|
|
* 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.
|
|
* <p>
|
|
* This annotation is provided for documentation purpose, just like
|
|
* <a href="http://www.javaconcurrencyinpractice.com/annotations/doc/">the JCIP annotations</a>.
|
|
*/
|
|
@Inherited
|
|
@Documented
|
|
@Target({ElementType.TYPE, ElementType.TYPE_USE})
|
|
@Retention(RetentionPolicy.RUNTIME)
|
|
@interface Sharable {
|
|
// no value
|
|
}
|
|
|
|
/**
|
|
* Indicates that the annotated event handler method in {@link ChannelHandler} will not be invoked by
|
|
* {@link ChannelPipeline}. This annotation is only useful when your handler method implementation
|
|
* only passes the event through to the next handler, like the following:
|
|
*
|
|
* <pre>
|
|
* {@code @Skip}
|
|
* {@code @Override}
|
|
* public void channelActive({@link ChannelHandlerContext} ctx) {
|
|
* ctx.fireChannelActive(); // do nothing but passing through to the next handler
|
|
* }
|
|
* </pre>
|
|
*
|
|
* <p>
|
|
* Note that this annotation is not {@linkplain Inherited inherited}. If you override a method annotated with
|
|
* {@link Skip}, it will not be skipped anymore. Similarly, you can override a method not annotated with
|
|
* {@link Skip} and simply pass the event through to the next handler, which reverses the behavior of the
|
|
* supertype.
|
|
* </p>
|
|
*/
|
|
@Target(ElementType.METHOD)
|
|
@Retention(RetentionPolicy.RUNTIME)
|
|
@interface Skip {
|
|
// no value
|
|
}
|
|
}
|