Add Revapi and fix non-public classes exposed in public API (#11817)

Motivation:
Some of our public APIs expose non-public (private or package-private) members through various means.
This makes the API surface inconsistent, and can lead to compatibility pitfalls.

Modification:
Fix all instances where non-public API is exposed through the public API, by making the non-public API piece public.
The newly-public APIs are also marked with the UnstableApi annotation.

A revapi configuration has been added to the parent pom.xml file, which automatically checks for instances of such API exposures.
Revapi also checks backwards for backwards incompatible changes, like japicmp does.
In time, we might phase out japicmp and rely only on revapi, since revapi seems to perform a super-set of the checks that japicmp does.

Finally, neither revapi nor japicmp are able to ignore API elements annotated with UnstableApi, because the annotation has source retention, and these tools work on the byte code level.
Changing the retention policy would be a backwards incompatible change, so we can only do that in Netty 5.
A TODO note has been added to remind us of this.

Result:
We are no longer exposing non-public API elements through our public API, and automated checks have been put in place that will fail the build if new exposures are introduced.

codec-http/src/main/java/io/netty/handler/codec/spdy/SpdyHeaderBlockDecoder.java

@@ -18,7 +18,13 @@
 import io.netty.buffer.ByteBuf;
 import io.netty.buffer.ByteBufAllocator;
 
-abstract class SpdyHeaderBlockDecoder {
+/**
+ * Super-class for SPDY header-block decoders.
+ *
+ * @see SpdyHeaderBlockRawDecoder
+ * @see SpdyHeaderBlockZlibDecoder
+ */
+public abstract class SpdyHeaderBlockDecoder {
 
     static SpdyHeaderBlockDecoder newInstance(SpdyVersion spdyVersion, int maxHeaderSize) {
         return new SpdyHeaderBlockZlibDecoder(spdyVersion, maxHeaderSize);

codec-http/src/main/java/io/netty/handler/codec/spdy/SpdyHeaderBlockEncoder.java

@@ -19,7 +19,14 @@
 import io.netty.buffer.ByteBufAllocator;
 import io.netty.util.internal.PlatformDependent;
 
-abstract class SpdyHeaderBlockEncoder {
+/**
+ * Super-class for SPDY header-block encoders.
+ *
+ * @see SpdyHeaderBlockZlibEncoder
+ * @see SpdyHeaderBlockJZlibEncoder
+ * @see SpdyHeaderBlockRawEncoder
+ */
+public abstract class SpdyHeaderBlockEncoder {
 
     static SpdyHeaderBlockEncoder newInstance(
             SpdyVersion version, int compressionLevel, int windowBits, int memLevel) {

codec-http2/src/main/java/io/netty/handler/codec/http2/Http2FrameStreamEvent.java

@@ -23,7 +23,8 @@ public final class Http2FrameStreamEvent {
     private final Http2FrameStream stream;
     private final Type type;
 
-    enum Type {
+    @UnstableApi
+    public enum Type {
         State,
         Writability
     }

codec-socks/src/main/java/io/netty/handler/codec/socks/SocksAuthRequestDecoder.java

@@ -19,6 +19,7 @@
 import io.netty.channel.ChannelHandlerContext;
 import io.netty.handler.codec.ReplayingDecoder;
 import io.netty.handler.codec.socks.SocksAuthRequestDecoder.State;
+import io.netty.util.internal.UnstableApi;
 
 import java.util.List;
 
@@ -62,7 +63,8 @@ protected void decode(ChannelHandlerContext ctx, ByteBuf byteBuf, List<Object> o
         ctx.pipeline().remove(this);
     }
 
-    enum State {
+    @UnstableApi
+    public enum State {
         CHECK_PROTOCOL_VERSION,
         READ_USERNAME,
         READ_PASSWORD

codec-socks/src/main/java/io/netty/handler/codec/socks/SocksAuthResponseDecoder.java

@@ -19,6 +19,7 @@
 import io.netty.channel.ChannelHandlerContext;
 import io.netty.handler.codec.ReplayingDecoder;
 import io.netty.handler.codec.socks.SocksAuthResponseDecoder.State;
+import io.netty.util.internal.UnstableApi;
 
 import java.util.List;
 
@@ -55,7 +56,8 @@ protected void decode(ChannelHandlerContext channelHandlerContext, ByteBuf byteB
         channelHandlerContext.pipeline().remove(this);
     }
 
-    enum State {
+    @UnstableApi
+    public enum State {
         CHECK_PROTOCOL_VERSION,
         READ_AUTH_RESPONSE
     }

codec-socks/src/main/java/io/netty/handler/codec/socks/SocksCmdRequestDecoder.java

@@ -20,6 +20,7 @@
 import io.netty.handler.codec.ReplayingDecoder;
 import io.netty.handler.codec.socks.SocksCmdRequestDecoder.State;
 import io.netty.util.NetUtil;
+import io.netty.util.internal.UnstableApi;
 
 import java.util.List;
 
@@ -92,7 +93,8 @@ protected void decode(ChannelHandlerContext ctx, ByteBuf byteBuf, List<Object> o
         ctx.pipeline().remove(this);
     }
 
-    enum State {
+    @UnstableApi
+    public enum State {
         CHECK_PROTOCOL_VERSION,
         READ_CMD_HEADER,
         READ_CMD_ADDRESS

codec-socks/src/main/java/io/netty/handler/codec/socks/SocksCmdResponseDecoder.java

@@ -20,6 +20,7 @@
 import io.netty.handler.codec.ReplayingDecoder;
 import io.netty.handler.codec.socks.SocksCmdResponseDecoder.State;
 import io.netty.util.NetUtil;
+import io.netty.util.internal.UnstableApi;
 
 import java.util.List;
 
@@ -92,7 +93,8 @@ protected void decode(ChannelHandlerContext ctx, ByteBuf byteBuf, List<Object> o
         ctx.pipeline().remove(this);
     }
 
-    enum State {
+    @UnstableApi
+    public enum State {
         CHECK_PROTOCOL_VERSION,
         READ_CMD_HEADER,
         READ_CMD_ADDRESS

codec-socks/src/main/java/io/netty/handler/codec/socks/SocksInitRequestDecoder.java

@@ -19,6 +19,7 @@
 import io.netty.channel.ChannelHandlerContext;
 import io.netty.handler.codec.ReplayingDecoder;
 import io.netty.handler.codec.socks.SocksInitRequestDecoder.State;
+import io.netty.util.internal.UnstableApi;
 
 import java.util.ArrayList;
 import java.util.Collections;
@@ -65,7 +66,8 @@ protected void decode(ChannelHandlerContext ctx, ByteBuf byteBuf, List<Object> o
         ctx.pipeline().remove(this);
     }
 
-    enum State {
+    @UnstableApi
+    public enum State {
         CHECK_PROTOCOL_VERSION,
         READ_AUTH_SCHEMES
     }

codec-socks/src/main/java/io/netty/handler/codec/socks/SocksInitResponseDecoder.java

@@ -19,6 +19,7 @@
 import io.netty.channel.ChannelHandlerContext;
 import io.netty.handler.codec.ReplayingDecoder;
 import io.netty.handler.codec.socks.SocksInitResponseDecoder.State;
+import io.netty.util.internal.UnstableApi;
 
 import java.util.List;
 
@@ -54,7 +55,8 @@ protected void decode(ChannelHandlerContext ctx, ByteBuf byteBuf, List<Object> o
         ctx.pipeline().remove(this);
     }
 
-    enum State {
+    @UnstableApi
+    public enum State {
         CHECK_PROTOCOL_VERSION,
         READ_PREFERRED_AUTH_TYPE
     }

codec-socks/src/main/java/io/netty/handler/codec/socksx/v4/Socks4ClientDecoder.java

@@ -22,6 +22,7 @@
 import io.netty.handler.codec.ReplayingDecoder;
 import io.netty.handler.codec.socksx.v4.Socks4ClientDecoder.State;
 import io.netty.util.NetUtil;
+import io.netty.util.internal.UnstableApi;
 
 import java.util.List;
 
@@ -33,7 +34,8 @@
  */
 public class Socks4ClientDecoder extends ReplayingDecoder<State> {
 
-    enum State {
+    @UnstableApi
+    public enum State {
         START,
         SUCCESS,
         FAILURE

codec-socks/src/main/java/io/netty/handler/codec/socksx/v4/Socks4ServerDecoder.java

@@ -24,6 +24,7 @@
 import io.netty.handler.codec.socksx.v4.Socks4ServerDecoder.State;
 import io.netty.util.CharsetUtil;
 import io.netty.util.NetUtil;
+import io.netty.util.internal.UnstableApi;
 
 import java.util.List;
 
@@ -37,7 +38,8 @@ public class Socks4ServerDecoder extends ReplayingDecoder<State> {
 
     private static final int MAX_FIELD_LENGTH = 255;
 
-    enum State {
+    @UnstableApi
+    public enum State {
         START,
         READ_USERID,
         READ_DOMAIN,

codec-socks/src/main/java/io/netty/handler/codec/socksx/v5/Socks5CommandRequestDecoder.java

@@ -24,6 +24,7 @@
 import io.netty.handler.codec.socksx.SocksVersion;
 import io.netty.handler.codec.socksx.v5.Socks5CommandRequestDecoder.State;
 import io.netty.util.internal.ObjectUtil;
+import io.netty.util.internal.UnstableApi;
 
 import java.util.List;
 
@@ -35,7 +36,8 @@
  */
 public class Socks5CommandRequestDecoder extends ReplayingDecoder<State> {
 
-    enum State {
+    @UnstableApi
+    public enum State {
         INIT,
         SUCCESS,
         FAILURE

codec-socks/src/main/java/io/netty/handler/codec/socksx/v5/Socks5CommandResponseDecoder.java

@@ -24,6 +24,7 @@
 import io.netty.handler.codec.socksx.SocksVersion;
 import io.netty.handler.codec.socksx.v5.Socks5CommandResponseDecoder.State;
 import io.netty.util.internal.ObjectUtil;
+import io.netty.util.internal.UnstableApi;
 
 import java.util.List;
 
@@ -35,7 +36,8 @@
  */
 public class Socks5CommandResponseDecoder extends ReplayingDecoder<State> {
 
-    enum State {
+    @UnstableApi
+    public enum State {
         INIT,
         SUCCESS,
         FAILURE

codec-socks/src/main/java/io/netty/handler/codec/socksx/v5/Socks5InitialRequestDecoder.java

@@ -23,6 +23,7 @@
 import io.netty.handler.codec.ReplayingDecoder;
 import io.netty.handler.codec.socksx.SocksVersion;
 import io.netty.handler.codec.socksx.v5.Socks5InitialRequestDecoder.State;
+import io.netty.util.internal.UnstableApi;
 
 import java.util.List;
 
@@ -34,7 +35,8 @@
  */
 public class Socks5InitialRequestDecoder extends ReplayingDecoder<State> {
 
-    enum State {
+    @UnstableApi
+    public enum State {
         INIT,
         SUCCESS,
         FAILURE

codec-socks/src/main/java/io/netty/handler/codec/socksx/v5/Socks5InitialResponseDecoder.java

@@ -23,6 +23,7 @@
 import io.netty.handler.codec.ReplayingDecoder;
 import io.netty.handler.codec.socksx.SocksVersion;
 import io.netty.handler.codec.socksx.v5.Socks5InitialResponseDecoder.State;
+import io.netty.util.internal.UnstableApi;
 
 import java.util.List;
 
@@ -34,7 +35,8 @@
  */
 public class Socks5InitialResponseDecoder extends ReplayingDecoder<State> {
 
-    enum State {
+    @UnstableApi
+    public enum State {
         INIT,
         SUCCESS,
         FAILURE

codec-socks/src/main/java/io/netty/handler/codec/socksx/v5/Socks5PasswordAuthRequestDecoder.java

@@ -23,6 +23,7 @@
 import io.netty.handler.codec.ReplayingDecoder;
 import io.netty.handler.codec.socksx.v5.Socks5PasswordAuthRequestDecoder.State;
 import io.netty.util.CharsetUtil;
+import io.netty.util.internal.UnstableApi;
 
 import java.util.List;
 
@@ -34,7 +35,8 @@
  */
 public class Socks5PasswordAuthRequestDecoder extends ReplayingDecoder<State> {
 
-    enum State {
+    @UnstableApi
+    public enum State {
         INIT,
         SUCCESS,
         FAILURE

codec-socks/src/main/java/io/netty/handler/codec/socksx/v5/Socks5PasswordAuthResponseDecoder.java

@@ -22,6 +22,7 @@
 import io.netty.handler.codec.DecoderResult;
 import io.netty.handler.codec.ReplayingDecoder;
 import io.netty.handler.codec.socksx.v5.Socks5PasswordAuthResponseDecoder.State;
+import io.netty.util.internal.UnstableApi;
 
 import java.util.List;
 
@@ -33,7 +34,8 @@
  */
 public class Socks5PasswordAuthResponseDecoder extends ReplayingDecoder<State> {
 
-    enum State {
+    @UnstableApi
+    public enum State {
         INIT,
         SUCCESS,
         FAILURE

codec-stomp/src/main/java/io/netty/handler/codec/stomp/StompSubframeDecoder.java

@@ -26,6 +26,7 @@
 import io.netty.util.ByteProcessor;
 import io.netty.util.internal.AppendableCharSequence;
 import io.netty.util.internal.StringUtil;
+import io.netty.util.internal.UnstableApi;
 
 import java.util.List;
 
@@ -55,7 +56,8 @@ public class StompSubframeDecoder extends ReplayingDecoder<State> {
     private static final int DEFAULT_CHUNK_SIZE = 8132;
     private static final int DEFAULT_MAX_LINE_LENGTH = 1024;
 
-    enum State {
+    @UnstableApi
+    public enum State {
         SKIP_CONTROL_CHARACTERS,
         READ_HEADERS,
         READ_CONTENT,

common/src/main/java/io/netty/util/internal/UnstableApi.java

@@ -33,7 +33,7 @@
  *         broken in a non-major release!</li>
  * </ol>
  */
-@Retention(RetentionPolicy.SOURCE)
+@Retention(RetentionPolicy.SOURCE) // TODO Retention policy needs to be CLASS in Netty 5.
 @Target({
         ElementType.ANNOTATION_TYPE,
         ElementType.CONSTRUCTOR,

microbench/src/main/java/io/netty/handler/codec/http2/HpackHeader.java

@@ -32,6 +32,7 @@
 package io.netty.handler.codec.http2;
 
 import io.netty.util.AsciiString;
+import io.netty.util.internal.UnstableApi;
 
 import java.util.ArrayList;
 import java.util.List;
@@ -40,7 +41,8 @@
 /**
  * Helper class representing a single header entry. Used by the benchmarks.
  */
-final class HpackHeader {
+@UnstableApi
+public final class HpackHeader {
     private static final String ALPHABET =
             "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-_";