Apply Nullable/NotNullByDefault annotations (java-native-access#673)

Motivation:
`Nullable`/`NotNullByDefault` annotations give an idea of what to expect
from the API. Plus, they provide a better IDE integration. This PR is
based on the work done in netty/netty#12878

Modification:
`Nullable`/`NotNullByDefault` annotations are applied where necessary.

Result:
The change extends the API with nullability expectations. Plus, it
provides a better IDE integration.

codec-classes-quic/pom.xml

@@ -85,5 +85,13 @@
       <!-- Let's mark as optional as it is not strictly needed -->
       <optional>true</optional>
     </dependency>
+    <dependency>
+      <groupId>org.jetbrains</groupId>
+      <artifactId>annotations</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>com.google.code.findbugs</groupId>
+      <artifactId>jsr305</artifactId>
+    </dependency>
   </dependencies>
 </project>

codec-classes-quic/src/main/java/io/netty/incubator/codec/quic/BoringSSL.java

@@ -16,6 +16,7 @@
 package io.netty.incubator.codec.quic;
 
 import io.netty.handler.ssl.util.LazyX509Certificate;
+import org.jetbrains.annotations.Nullable;
 
 import java.io.ByteArrayOutputStream;
 import java.io.IOException;
@@ -41,10 +42,10 @@ static long SSLContext_new(boolean server, String[] applicationProtocols,
                                BoringSSLHandshakeCompleteCallback handshakeCompleteCallback,
                                BoringSSLCertificateCallback certificateCallback,
                                BoringSSLCertificateVerifyCallback verifyCallback,
-                               BoringSSLTlsextServernameCallback servernameCallback,
-                               BoringSSLKeylogCallback keylogCallback,
-                               BoringSSLSessionCallback sessionCallback,
-                               BoringSSLPrivateKeyMethod privateKeyMethod,
+                               @Nullable BoringSSLTlsextServernameCallback servernameCallback,
+                               @Nullable BoringSSLKeylogCallback keylogCallback,
+                               @Nullable BoringSSLSessionCallback sessionCallback,
+                               @Nullable BoringSSLPrivateKeyMethod privateKeyMethod,
                                BoringSSLSessionTicketCallback sessionTicketCallback,
                                int verifyMode,
                                byte[][] subjectNames) {
@@ -72,9 +73,9 @@ private static byte[] toWireFormat(String[] applicationProtocols) {
     private static native long SSLContext_new0(boolean server,
                                                byte[] applicationProtocols, Object handshakeCompleteCallback,
                                                Object certificateCallback, Object verifyCallback,
-                                               Object servernameCallback, Object keylogCallback,
-                                               Object sessionCallback,
-                                               Object privateKeyMethod,
+                                               @Nullable Object servernameCallback, @Nullable Object keylogCallback,
+                                               @Nullable Object sessionCallback,
+                                               @Nullable Object privateKeyMethod,
                                                Object sessionTicketCallback,
                                                int verifyDepth, byte[][] subjectNames);
     static native void SSLContext_set_early_data_enabled(long context, boolean enabled);
@@ -87,7 +88,7 @@ private static native long SSLContext_new0(boolean server,
     static long SSL_new(long context, boolean server, String hostname) {
         return SSL_new0(context, server, tlsExtHostName(hostname));
     }
-    static native long SSL_new0(long context, boolean server, String hostname);
+    static native long SSL_new0(long context, boolean server, @Nullable String hostname);
     static native void SSL_free(long ssl);
 
     static native Runnable SSL_getTask(long ssl);
@@ -100,9 +101,11 @@ static long SSL_new(long context, boolean server, String hostname) {
     static native long CRYPTO_BUFFER_stack_new(long ssl, byte[][] bytes);
     static native void CRYPTO_BUFFER_stack_free(long chain);
 
+    @Nullable
     static native String ERR_last_error();
 
-    private static String tlsExtHostName(String hostname) {
+    @Nullable
+    private static String tlsExtHostName(@Nullable String hostname) {
         if (hostname != null && hostname.endsWith(".")) {
             // Strip trailing dot if included.
             // See https://github.com/netty/netty-tcnative/issues/400

codec-classes-quic/src/main/java/io/netty/incubator/codec/quic/BoringSSLCertificateCallback.java

@@ -17,6 +17,7 @@
 
 
 import io.netty.util.CharsetUtil;
+import org.jetbrains.annotations.Nullable;
 
 import javax.net.ssl.SSLException;
 import javax.net.ssl.SSLHandshakeException;
@@ -90,7 +91,7 @@ final class BoringSSLCertificateCallback {
     private final X509ExtendedKeyManager keyManager;
     private final String password;
 
-    BoringSSLCertificateCallback(QuicheQuicSslEngineMap engineMap, X509ExtendedKeyManager keyManager, String password) {
+    BoringSSLCertificateCallback(QuicheQuicSslEngineMap engineMap, @Nullable X509ExtendedKeyManager keyManager, String password) {
         this.engineMap = engineMap;
         this.keyManager = keyManager;
         this.password = password;
@@ -222,11 +223,14 @@ private static byte[] toPemEncoded(PrivateKey key) {
             return null;
         }
     }
+
+    @Nullable
     private String chooseClientAlias(QuicheQuicSslEngine engine,
                                      String[] keyTypes, X500Principal[] issuer) {
         return keyManager.chooseEngineClientAlias(keyTypes, issuer, engine);
     }
 
+    @Nullable
     private String chooseServerAlias(QuicheQuicSslEngine engine, String type) {
         return keyManager.chooseEngineServerAlias(type, null, engine);
     }
@@ -256,6 +260,7 @@ private static Set<String> supportedClientKeyTypes(byte[] clientCertificateTypes
         return result;
     }
 
+    @Nullable
     private static String clientKeyType(byte clientCertificateType) {
         // See also https://www.ietf.org/assignments/tls-parameters/tls-parameters.xml
         switch (clientCertificateType) {

codec-classes-quic/src/main/java/io/netty/incubator/codec/quic/BoringSSLKeylessManagerFactory.java

@@ -15,6 +15,8 @@
  */
 package io.netty.incubator.codec.quic;
 
+import org.jetbrains.annotations.Nullable;
+
 import javax.net.ssl.KeyManager;
 import javax.net.ssl.KeyManagerFactory;
 import javax.net.ssl.KeyManagerFactorySpi;
@@ -148,6 +150,7 @@ private KeylessKeyStore(final X509Certificate[] certificateChain) {
                 private final Date creationDate = new Date();
 
                 @Override
+                @Nullable
                 public Key engineGetKey(String alias, char[] password) {
                     if (engineContainsAlias(alias)) {
                         return BoringSSLKeylessPrivateKey.INSTANCE;
@@ -161,11 +164,13 @@ public Certificate[] engineGetCertificateChain(String alias) {
                 }
 
                 @Override
+                @Nullable
                 public Certificate engineGetCertificate(String alias) {
                     return engineContainsAlias(alias)? certificateChain[0] : null;
                 }
 
                 @Override
+                @Nullable
                 public Date engineGetCreationDate(String alias) {
                     return engineContainsAlias(alias)? creationDate : null;
                 }
@@ -217,6 +222,7 @@ public boolean engineIsCertificateEntry(String alias) {
                 }
 
                 @Override
+                @Nullable
                 public String engineGetCertificateAlias(Certificate cert) {
                     if (cert instanceof X509Certificate) {
                         for (X509Certificate x509Certificate : certificateChain) {
@@ -234,7 +240,7 @@ public void engineStore(OutputStream stream, char[] password) {
                 }
 
                 @Override
-                public void engineLoad(InputStream stream, char[] password) {
+                public void engineLoad(@Nullable InputStream stream, char[] password) {
                     if (stream != null && password != null) {
                         throw new UnsupportedOperationException();
                     }

codec-classes-quic/src/main/java/io/netty/incubator/codec/quic/BoringSSLSessionCallback.java

@@ -18,6 +18,7 @@
 import io.netty.util.internal.EmptyArrays;
 import io.netty.util.internal.logging.InternalLogger;
 import io.netty.util.internal.logging.InternalLoggerFactory;
+import org.jetbrains.annotations.Nullable;
 
 import java.io.ByteArrayOutputStream;
 import java.io.DataOutputStream;
@@ -30,7 +31,7 @@ final class BoringSSLSessionCallback {
     private final QuicClientSessionCache sessionCache;
     private final QuicheQuicSslEngineMap engineMap;
 
-    BoringSSLSessionCallback(QuicheQuicSslEngineMap engineMap, QuicClientSessionCache sessionCache) {
+    BoringSSLSessionCallback(QuicheQuicSslEngineMap engineMap, @Nullable QuicClientSessionCache sessionCache) {
         this.engineMap = engineMap;
         this.sessionCache = sessionCache;
     }

codec-classes-quic/src/main/java/io/netty/incubator/codec/quic/Quic.java

@@ -21,6 +21,7 @@
 import io.netty.util.AttributeKey;
 import io.netty.util.internal.ObjectUtil;
 import io.netty.util.internal.logging.InternalLogger;
+import org.jetbrains.annotations.Nullable;
 
 import java.util.HashMap;
 import java.util.LinkedHashMap;
@@ -87,6 +88,7 @@ public static void ensureAvailability() {
      *
      * @return the cause if unavailable. {@code null} if available.
      */
+    @Nullable
     public static Throwable unavailabilityCause() {
         return UNAVAILABILITY_CAUSE;
     }
@@ -131,7 +133,7 @@ private static void setChannelOption(
      * Allow to specify a {@link ChannelOption} which is used for the {@link QuicStreamChannel} instances once they got
      * created. Use a value of {@code null} to remove a previous set {@link ChannelOption}.
      */
-    static <T> void updateOptions(Map<ChannelOption<?>, Object> options, ChannelOption<T> option, T value) {
+    static <T> void updateOptions(Map<ChannelOption<?>, Object> options, ChannelOption<T> option, @Nullable T value) {
         ObjectUtil.checkNotNull(option, "option");
         if (value == null) {
             options.remove(option);
@@ -144,7 +146,7 @@ static <T> void updateOptions(Map<ChannelOption<?>, Object> options, ChannelOpti
      * Allow to specify an initial attribute of the newly created {@link QuicStreamChannel}. If the {@code value} is
      * {@code null}, the attribute of the specified {@code key} is removed.
      */
-    static <T> void updateAttributes(Map<AttributeKey<?>, Object> attributes, AttributeKey<T> key, T value) {
+    static <T> void updateAttributes(Map<AttributeKey<?>, Object> attributes, AttributeKey<T> key, @Nullable T value) {
         ObjectUtil.checkNotNull(key, "key");
         if (value == null) {
             attributes.remove(key);
@@ -154,7 +156,7 @@ static <T> void updateAttributes(Map<AttributeKey<?>, Object> attributes, Attrib
     }
 
     static void setupChannel(Channel ch, Map.Entry<ChannelOption<?>, Object>[] options,
-                             Map.Entry<AttributeKey<?>, Object>[] attrs, ChannelHandler handler,
+                             Map.Entry<AttributeKey<?>, Object>[] attrs, @Nullable ChannelHandler handler,
                              InternalLogger logger) {
         Quic.setChannelOptions(ch, options, logger);
         Quic.setAttributes(ch, attrs);

codec-classes-quic/src/main/java/io/netty/incubator/codec/quic/QuicChannel.java

@@ -23,6 +23,7 @@
 import io.netty.channel.ChannelPromise;
 import io.netty.util.concurrent.Future;
 import io.netty.util.concurrent.Promise;
+import org.jetbrains.annotations.Nullable;
 
 import javax.net.ssl.SSLEngine;
 import java.net.SocketAddress;
@@ -154,6 +155,7 @@ default ChannelPromise voidPromise() {
      *
      * @return the engine.
      */
+    @Nullable
     SSLEngine sslEngine();
 
     /**
@@ -177,6 +179,7 @@ default ChannelPromise voidPromise() {
      *
      * @return peerTransportParams.
      */
+    @Nullable
     QuicTransportParameters peerTransportParameters();
 
     /**
@@ -189,7 +192,7 @@ default ChannelPromise voidPromise() {
      *                  {@link io.netty.channel.ChannelPipeline} during the stream creation.
      * @return          the {@link Future} that will be notified once the operation completes.
      */
-    default Future<QuicStreamChannel> createStream(QuicStreamType type, ChannelHandler handler) {
+    default Future<QuicStreamChannel> createStream(QuicStreamType type, @Nullable ChannelHandler handler) {
         return createStream(type, handler, eventLoop().newPromise());
     }
 
@@ -204,7 +207,7 @@ default Future<QuicStreamChannel> createStream(QuicStreamType type, ChannelHandl
      * @param promise   the {@link ChannelPromise} that will be notified once the operation completes.
      * @return          the {@link Future} that will be notified once the operation completes.
      */
-    Future<QuicStreamChannel> createStream(QuicStreamType type, ChannelHandler handler,
+    Future<QuicStreamChannel> createStream(QuicStreamType type, @Nullable ChannelHandler handler,
                                            Promise<QuicStreamChannel> promise);
 
     /**

codec-classes-quic/src/main/java/io/netty/incubator/codec/quic/QuicChannelBootstrap.java

@@ -26,6 +26,7 @@
 import io.netty.util.internal.ObjectUtil;
 import io.netty.util.internal.logging.InternalLogger;
 import io.netty.util.internal.logging.InternalLoggerFactory;
+import org.jetbrains.annotations.Nullable;
 
 import java.net.InetSocketAddress;
 import java.net.SocketAddress;
@@ -74,7 +75,7 @@ public final class QuicChannelBootstrap {
      * @param <T>       the type of the value.
      * @return          this instance.
      */
-    public <T> QuicChannelBootstrap option(ChannelOption<T> option, T value) {
+    public <T> QuicChannelBootstrap option(ChannelOption<T> option, @Nullable T value) {
         Quic.updateOptions(options, option, value);
         return this;
     }
@@ -88,7 +89,7 @@ public <T> QuicChannelBootstrap option(ChannelOption<T> option, T value) {
      * @param <T>       the type of the value.
      * @return          this instance.
      */
-    public <T> QuicChannelBootstrap attr(AttributeKey<T> key, T value) {
+    public <T> QuicChannelBootstrap attr(AttributeKey<T> key, @Nullable T value) {
         Quic.updateAttributes(attrs, key, value);
         return this;
     }
@@ -115,7 +116,7 @@ public QuicChannelBootstrap handler(ChannelHandler handler) {
      * @param <T>       the type of the value.
      * @return          this instance.
      */
-    public <T> QuicChannelBootstrap streamOption(ChannelOption<T> option, T value) {
+    public <T> QuicChannelBootstrap streamOption(ChannelOption<T> option, @Nullable T value) {
         Quic.updateOptions(streamOptions, option, value);
         return this;
     }
@@ -129,7 +130,7 @@ public <T> QuicChannelBootstrap streamOption(ChannelOption<T> option, T value) {
      * @param <T>       the type of the value.
      * @return          this instance.
      */
-    public <T> QuicChannelBootstrap streamAttr(AttributeKey<T> key, T value) {
+    public <T> QuicChannelBootstrap streamAttr(AttributeKey<T> key, @Nullable T value) {
         Quic.updateAttributes(streamAttrs, key, value);
         return this;
     }

codec-classes-quic/src/main/java/io/netty/incubator/codec/quic/QuicClientSessionCache.java

@@ -17,6 +17,7 @@
 
 import io.netty.util.AsciiString;
 import io.netty.util.internal.SystemPropertyUtil;
+import org.jetbrains.annotations.Nullable;
 
 import java.util.Iterator;
 import java.util.LinkedHashMap;
@@ -55,7 +56,7 @@ protected boolean removeEldestEntry(Map.Entry<HostPort, SessionHolder> eldest) {
                 }
             };
 
-    void saveSession(String host, int port, long creationTime, long timeout, byte[] session, boolean isSingleUse) {
+    void saveSession(@Nullable String host, int port, long creationTime, long timeout, byte[] session, boolean isSingleUse) {
         HostPort hostPort = keyFor(host, port);
         if (hostPort != null) {
             synchronized (sessions) {
@@ -72,7 +73,7 @@ void saveSession(String host, int port, long creationTime, long timeout, byte[]
     }
 
     // Only used for testing.
-    boolean hasSession(String host, int port) {
+    boolean hasSession(@Nullable String host, int port) {
         HostPort hostPort = keyFor(host, port);
         if (hostPort != null) {
             synchronized (sessions) {
@@ -82,7 +83,7 @@ boolean hasSession(String host, int port) {
         return false;
     }
 
-    byte[] getSession(String host, int port) {
+    byte[] getSession(@Nullable String host, int port) {
         HostPort hostPort = keyFor(host, port);
         if (hostPort != null) {
             SessionHolder sessionHolder;
@@ -103,7 +104,7 @@ byte[] getSession(String host, int port) {
         return null;
     }
 
-    void removeSession(String host, int port) {
+    void removeSession(@Nullable String host, int port) {
         HostPort hostPort = keyFor(host, port);
         if (hostPort != null) {
             synchronized (sessions) {
@@ -167,7 +168,8 @@ private void expungeInvalidSessions() {
         }
     }
 
-    private static HostPort keyFor(String host, int port) {
+    @Nullable
+    private static HostPort keyFor(@Nullable String host, int port) {
         if (host == null && port < 1) {
             return null;
         }

codec-classes-quic/src/main/java/io/netty/incubator/codec/quic/QuicClosedChannelException.java

@@ -15,6 +15,8 @@
  */
 package io.netty.incubator.codec.quic;
 
+import org.jetbrains.annotations.Nullable;
+
 import java.nio.channels.ClosedChannelException;
 
 /**
@@ -25,7 +27,7 @@ public final class QuicClosedChannelException extends ClosedChannelException {
 
     private final QuicConnectionCloseEvent event;
 
-    QuicClosedChannelException(QuicConnectionCloseEvent event) {
+    QuicClosedChannelException(@Nullable QuicConnectionCloseEvent event) {
         this.event = event;
     }
 
@@ -34,6 +36,7 @@ public final class QuicClosedChannelException extends ClosedChannelException {
      *
      * @return the event.
      */
+    @Nullable
     public QuicConnectionCloseEvent event() {
         return event;
     }