Create SimpleUserEventChannelHandler convenience class (netty#7991)

Motivation:

Currently, the vast majority of userEventTriggered() implementations
require the user to supply the boilerplate behavior of performing an
instanceof check, handling if appropriate, and calling
fireUserEventTriggered() otherwise.

We can simplify this very common use case by creating a class that only
matches user events of a given type, similar to the existing
SimpleChannelInboundHandler class.

Modifications:

Create a new SimpleUserEventChannelHandler class
Create accompanying SimpleUserEventChannelHandlerTest class

Result:

Users will be able to handle most events in a less verbose manner.

transport/src/main/java/io/netty/channel/SimpleUserEventChannelHandler.java

@@ -0,0 +1,120 @@
+/*
+ * Copyright 2018 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.ReferenceCountUtil;
+import io.netty.util.internal.TypeParameterMatcher;
+
+/**
+ * {@link ChannelInboundHandlerAdapter} which allows to conveniently only handle a specific type of user events.
+ *
+ * For example, here is an implementation which only handle {@link String} user events.
+ *
+ * <pre>
+ *     public class StringEventHandler extends
+ *             {@link SimpleUserEventChannelHandler}&lt;{@link String}&gt; {
+ *
+ *         {@code @Override}
+ *         protected void eventReceived({@link ChannelHandlerContext} ctx, {@link String} evt)
+ *                 throws {@link Exception} {
+ *             System.out.println(evt);
+ *         }
+ *     }
+ * </pre>
+ *
+ * Be aware that depending of the constructor parameters it will release all handled events by passing them to
+ * {@link ReferenceCountUtil#release(Object)}. In this case you may need to use
+ * {@link ReferenceCountUtil#retain(Object)} if you pass the object to the next handler in the {@link ChannelPipeline}.
+ */
+public abstract class SimpleUserEventChannelHandler<I> extends ChannelInboundHandlerAdapter {
+
+    private final TypeParameterMatcher matcher;
+    private final boolean autoRelease;
+
+    /**
+     * see {@link #SimpleUserEventChannelHandler(boolean)} with {@code true} as boolean parameter.
+     */
+    protected SimpleUserEventChannelHandler() {
+        this(true);
+    }
+
+    /**
+     * Create a new instance which will try to detect the types to match out of the type parameter of the class.
+     *
+     * @param autoRelease   {@code true} if handled events should be released automatically by passing them to
+     *                      {@link ReferenceCountUtil#release(Object)}.
+     */
+    protected SimpleUserEventChannelHandler(boolean autoRelease) {
+        matcher = TypeParameterMatcher.find(this, SimpleUserEventChannelHandler.class, "I");
+        this.autoRelease = autoRelease;
+    }
+
+    /**
+     * see {@link #SimpleUserEventChannelHandler(Class, boolean)} with {@code true} as boolean value.
+     */
+    protected SimpleUserEventChannelHandler(Class<? extends I> eventType) {
+        this(eventType, true);
+    }
+
+    /**
+     * Create a new instance
+     *
+     * @param eventType      The type of events to match
+     * @param autoRelease    {@code true} if handled events should be released automatically by passing them to
+     *                       {@link ReferenceCountUtil#release(Object)}.
+     */
+    protected SimpleUserEventChannelHandler(Class<? extends I> eventType, boolean autoRelease) {
+        matcher = TypeParameterMatcher.get(eventType);
+        this.autoRelease = autoRelease;
+    }
+
+    /**
+     * Returns {@code true} if the given user event should be handled. If {@code false} it will be passed to the next
+     * {@link ChannelInboundHandler} in the {@link ChannelPipeline}.
+     */
+    protected boolean acceptEvent(Object evt) throws Exception {
+        return matcher.match(evt);
+    }
+
+    @Override
+    public final void userEventTriggered(ChannelHandlerContext ctx, Object evt) throws Exception {
+        boolean release = true;
+        try {
+            if (acceptEvent(evt)) {
+                @SuppressWarnings("unchecked")
+                I ievt = (I) evt;
+                eventReceived(ctx, ievt);
+            } else {
+                release = false;
+                ctx.fireUserEventTriggered(evt);
+            }
+        } finally {
+            if (autoRelease && release) {
+                ReferenceCountUtil.release(evt);
+            }
+        }
+    }
+
+    /**
+     * Is called for each user event triggered of type {@link I}.
+     *
+     * @param ctx the {@link ChannelHandlerContext} which this {@link SimpleUserEventChannelHandler} belongs to
+     * @param evt the user event to handle
+     *
+     * @throws Exception is thrown if an error occurred
+     */
+    protected abstract void eventReceived(ChannelHandlerContext ctx, I evt) throws Exception;
+}

transport/src/test/java/io/netty/channel/SimpleUserEventChannelHandlerTest.java

@@ -0,0 +1,101 @@
+/*
+ * Copyright 2018 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.buffer.DefaultByteBufHolder;
+import io.netty.buffer.Unpooled;
+import io.netty.channel.embedded.EmbeddedChannel;
+import org.junit.Before;
+import org.junit.Test;
+
+import java.util.ArrayList;
+import java.util.List;
+
+import static org.junit.Assert.*;
+
+public class SimpleUserEventChannelHandlerTest {
+
+    private FooEventCatcher fooEventCatcher;
+    private AllEventCatcher allEventCatcher;
+    private EmbeddedChannel channel;
+
+    @Before
+    public void setUp() {
+        fooEventCatcher = new FooEventCatcher();
+        allEventCatcher = new AllEventCatcher();
+        channel = new EmbeddedChannel(fooEventCatcher, allEventCatcher);
+    }
+
+    @Test
+    public void testTypeMatch() {
+        FooEvent fooEvent = new FooEvent();
+        channel.pipeline().fireUserEventTriggered(fooEvent);
+        assertEquals(1, fooEventCatcher.caughtEvents.size());
+        assertEquals(0, allEventCatcher.caughtEvents.size());
+        assertEquals(0, fooEvent.refCnt());
+        assertFalse(channel.finish());
+    }
+
+    @Test
+    public void testTypeMismatch() {
+        BarEvent barEvent = new BarEvent();
+        channel.pipeline().fireUserEventTriggered(barEvent);
+        assertEquals(0, fooEventCatcher.caughtEvents.size());
+        assertEquals(1, allEventCatcher.caughtEvents.size());
+        assertTrue(barEvent.release());
+        assertFalse(channel.finish());
+    }
+
+    static final class FooEvent extends DefaultByteBufHolder {
+        FooEvent() {
+            super(Unpooled.buffer());
+        }
+    }
+
+    static final class BarEvent extends DefaultByteBufHolder {
+        BarEvent() {
+            super(Unpooled.buffer());
+        }
+    }
+
+    static final class FooEventCatcher extends SimpleUserEventChannelHandler<FooEvent> {
+
+        public List<FooEvent> caughtEvents;
+
+        FooEventCatcher() {
+            caughtEvents = new ArrayList<FooEvent>();
+        }
+
+        @Override
+        protected void eventReceived(ChannelHandlerContext ctx, FooEvent evt) {
+            caughtEvents.add(evt);
+        }
+    }
+
+    static final class AllEventCatcher extends ChannelInboundHandlerAdapter {
+
+        public List<Object> caughtEvents;
+
+        AllEventCatcher() {
+            caughtEvents = new ArrayList<Object>();
+        }
+
+        @Override
+        public void userEventTriggered(ChannelHandlerContext ctx, Object evt) {
+            caughtEvents.add(evt);
+        }
+    }
+}