1 /*
2 * Copyright 2018 The Netty Project
3 *
4 * The Netty Project licenses this file to you under the Apache License,
5 * version 2.0 (the "License"); you may not use this file except in compliance
6 * with the License. You may obtain a copy of the License at:
7 *
8 * https://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
12 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13 * License for the specific language governing permissions and limitations
14 * under the License.
15 */
16 package io.netty.channel;
17
18 import io.netty.util.ReferenceCountUtil;
19 import io.netty.util.internal.TypeParameterMatcher;
20
21 /**
22 * {@link ChannelInboundHandlerAdapter} which allows to conveniently only handle a specific type of user events.
23 *
24 * For example, here is an implementation which only handle {@link String} user events.
25 *
26 * <pre>
27 * public class StringEventHandler extends
28 * {@link SimpleUserEventChannelHandler}<{@link String}> {
29 *
30 * {@code @Override}
31 * protected void eventReceived({@link ChannelHandlerContext} ctx, {@link String} evt)
32 * throws {@link Exception} {
33 * System.out.println(evt);
34 * }
35 * }
36 * </pre>
37 *
38 * Be aware that depending of the constructor parameters it will release all handled events by passing them to
39 * {@link ReferenceCountUtil#release(Object)}. In this case you may need to use
40 * {@link ReferenceCountUtil#retain(Object)} if you pass the object to the next handler in the {@link ChannelPipeline}.
41 */
42 public abstract class SimpleUserEventChannelHandler<I> extends ChannelInboundHandlerAdapter {
43
44 private final TypeParameterMatcher matcher;
45 private final boolean autoRelease;
46
47 /**
48 * see {@link #SimpleUserEventChannelHandler(boolean)} with {@code true} as boolean parameter.
49 */
50 protected SimpleUserEventChannelHandler() {
51 this(true);
52 }
53
54 /**
55 * Create a new instance which will try to detect the types to match out of the type parameter of the class.
56 *
57 * @param autoRelease {@code true} if handled events should be released automatically by passing them to
58 * {@link ReferenceCountUtil#release(Object)}.
59 */
60 protected SimpleUserEventChannelHandler(boolean autoRelease) {
61 matcher = TypeParameterMatcher.find(this, SimpleUserEventChannelHandler.class, "I");
62 this.autoRelease = autoRelease;
63 }
64
65 /**
66 * see {@link #SimpleUserEventChannelHandler(Class, boolean)} with {@code true} as boolean value.
67 */
68 protected SimpleUserEventChannelHandler(Class<? extends I> eventType) {
69 this(eventType, true);
70 }
71
72 /**
73 * Create a new instance
74 *
75 * @param eventType The type of events to match
76 * @param autoRelease {@code true} if handled events should be released automatically by passing them to
77 * {@link ReferenceCountUtil#release(Object)}.
78 */
79 protected SimpleUserEventChannelHandler(Class<? extends I> eventType, boolean autoRelease) {
80 matcher = TypeParameterMatcher.get(eventType);
81 this.autoRelease = autoRelease;
82 }
83
84 /**
85 * Returns {@code true} if the given user event should be handled. If {@code false} it will be passed to the next
86 * {@link ChannelInboundHandler} in the {@link ChannelPipeline}.
87 */
88 protected boolean acceptEvent(Object evt) throws Exception {
89 return matcher.match(evt);
90 }
91
92 @Override
93 public final void userEventTriggered(ChannelHandlerContext ctx, Object evt) throws Exception {
94 boolean release = true;
95 try {
96 if (acceptEvent(evt)) {
97 @SuppressWarnings("unchecked")
98 I ievt = (I) evt;
99 eventReceived(ctx, ievt);
100 } else {
101 release = false;
102 ctx.fireUserEventTriggered(evt);
103 }
104 } finally {
105 if (autoRelease && release) {
106 ReferenceCountUtil.release(evt);
107 }
108 }
109 }
110
111 /**
112 * Is called for each user event triggered of type {@link I}.
113 *
114 * @param ctx the {@link ChannelHandlerContext} which this {@link SimpleUserEventChannelHandler} belongs to
115 * @param evt the user event to handle
116 *
117 * @throws Exception is thrown if an error occurred
118 */
119 protected abstract void eventReceived(ChannelHandlerContext ctx, I evt) throws Exception;
120 }