Add NotNull/Nullable annotations.

Author: devoxin

.gitignore

@@ -27,3 +27,4 @@ replay_pid*
 .gradle/*
 .idea/*
 .DS_Store
+*/build/*

build.gradle.kts

@@ -28,5 +28,6 @@ allprojects {
         implementation("org.mozilla:rhino-engine:1.7.14")
         implementation("com.grack:nanojson:1.7")
         compileOnly("org.slf4j:slf4j-api:1.7.25")
+        compileOnly("org.jetbrains:annotations:24.1.0")
     }
 }

common/src/main/java/dev/lavalink/youtube/CannotBeLoaded.java

@@ -1,5 +1,7 @@
 package dev.lavalink.youtube;
 
+import org.jetbrains.annotations.NotNull;
+
 public class CannotBeLoaded extends Throwable {
     // This is a 'cheap' exception used to tell the source manager to stop trying
     // to load a track as it's unloadable, e.g. if a video doesn't exist/is private etc...
@@ -9,7 +11,7 @@ public class CannotBeLoaded extends Throwable {
      * in the chain.
      * @param original The original exception that triggered this exception.
      */
-    public CannotBeLoaded(Throwable original) {
+    public CannotBeLoaded(@NotNull Throwable original) {
         super("The URL could not be loaded.", original, false, false);
     }
 }

common/src/main/java/dev/lavalink/youtube/UrlTools.java

@@ -3,6 +3,7 @@
 import com.sedmelluq.discord.lavaplayer.tools.FriendlyException;
 import org.apache.http.NameValuePair;
 import org.apache.http.client.utils.URIBuilder;
+import org.jetbrains.annotations.NotNull;
 
 import java.net.URISyntaxException;
 import java.util.Map;
@@ -11,7 +12,9 @@
 import static com.sedmelluq.discord.lavaplayer.tools.FriendlyException.Severity.COMMON;
 
 public class UrlTools {
-    public static UrlInfo getUrlInfo(String url, boolean retryValidPart) {
+    @NotNull
+    public static UrlInfo getUrlInfo(@NotNull String url,
+                                     boolean retryValidPart) {
         try {
             if (!url.startsWith("http://") && !url.startsWith("https://")) {
                 url = "https://" + url;
@@ -34,7 +37,8 @@ public static class UrlInfo {
         public final String path;
         public final Map<String, String> parameters;
 
-        private UrlInfo(String path, Map<String, String> parameters) {
+        private UrlInfo(@NotNull String path,
+                        @NotNull Map<String, String> parameters) {
             this.path = path;
             this.parameters = parameters;
         }

common/src/main/java/dev/lavalink/youtube/YoutubeAudioSourceManager.java

@@ -24,6 +24,8 @@
 import dev.lavalink.youtube.track.YoutubeAudioTrack;
 import org.apache.http.client.methods.CloseableHttpResponse;
 import org.apache.http.client.methods.HttpGet;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
@@ -39,7 +41,6 @@
 
 @SuppressWarnings("RegExpUnnecessaryNonCapturingGroup")
 public class YoutubeAudioSourceManager implements AudioSourceManager {
-    // TODO: consider adding notnull/nullable annotations
     // TODO: connect timeout = 16000ms, read timeout = 8000ms (as observed from scraped youtube config)
     // TODO: look at possibly scraping jsUrl from WEB config to save a request
     // TODO: search providers use cookieless httpinterfacemanagers. should this do the same?
@@ -58,12 +59,11 @@ public class YoutubeAudioSourceManager implements AudioSourceManager {
     private static final Pattern mainDomainPattern = Pattern.compile("^" + PROTOCOL_REGEX + DOMAIN_REGEX + "/.*");
     private static final Pattern shortHandPattern = Pattern.compile("^" + PROTOCOL_REGEX + "(?:" + DOMAIN_REGEX + "/(?:live|embed|shorts)|" + SHORT_DOMAIN_REGEX + ")/(?<id>.*)");
 
+    protected final HttpInterfaceManager httpInterfaceManager;
+    protected final boolean allowSearch;
+    protected final Client[] clients;
 
-    protected HttpInterfaceManager httpInterfaceManager = HttpClientTools.createDefaultThreadLocalManager();
-    protected boolean allowSearch;
-    protected Client[] clients;
-
-    protected SignatureCipherManager cipherManager;
+    protected final SignatureCipherManager cipherManager;
 
     public YoutubeAudioSourceManager() {
         this(true);
@@ -80,7 +80,7 @@ public YoutubeAudioSourceManager(boolean allowSearch) {
      * @param clients The clients to use for track loading. They will be queried in
      *                the order they are provided.
      */
-    public YoutubeAudioSourceManager(Client... clients) {
+    public YoutubeAudioSourceManager(@NotNull Client... clients) {
         this(true, clients);
     }
 
@@ -92,7 +92,8 @@ public YoutubeAudioSourceManager(Client... clients) {
      * @param clients The clients to use for track loading. They will be queried in
      *                the order they are provided.
      */
-    public YoutubeAudioSourceManager(boolean allowSearch, Client... clients) {
+    public YoutubeAudioSourceManager(boolean allowSearch, @NotNull Client... clients) {
+        this.httpInterfaceManager = HttpClientTools.createDefaultThreadLocalManager();
         this.allowSearch = allowSearch;
         this.clients = clients == null ? new Client[0] : clients;
         this.cipherManager = new SignatureCipherManager();
@@ -115,7 +116,8 @@ public void setPlaylistPageCount(int count) {
     }
 
     @Override
-    public AudioItem loadItem(AudioPlayerManager manager, AudioReference reference) {
+    @Nullable
+    public AudioItem loadItem(@NotNull AudioPlayerManager manager, @NotNull AudioReference reference) {
         try {
             return loadItemOnce(reference);
         } catch (FriendlyException exception) {
@@ -128,11 +130,12 @@ public AudioItem loadItem(AudioPlayerManager manager, AudioReference reference)
         }
     }
 
-    public AudioItem loadItemOnce(AudioReference reference) {
+    @Nullable
+    protected AudioItem loadItemOnce(@NotNull AudioReference reference) {
         Throwable lastException = null;
 
         try (HttpInterface httpInterface = httpInterfaceManager.getInterface()) {
-            Router router = getRouter(reference.identifier, httpInterface);
+            Router router = getRouter(httpInterface, reference.identifier);
 
             if (router == null) {
                 return null;
@@ -173,7 +176,8 @@ public AudioItem loadItemOnce(AudioReference reference) {
         return null;
     }
 
-    protected Router getRouter(String identifier, HttpInterface httpInterface) {
+    @Nullable
+    protected Router getRouter(@NotNull HttpInterface httpInterface, @NotNull String identifier) {
         if (identifier.startsWith(SEARCH_PREFIX)) {
             if (allowSearch) return (client) -> client.loadSearch(this, httpInterface, identifier.substring(SEARCH_PREFIX.length()).trim());
         } else if (identifier.startsWith(MUSIC_SEARCH_PREFIX)) {
@@ -187,7 +191,7 @@ protected Router getRouter(String identifier, HttpInterface httpInterface) {
                 if ("/watch".equals(urlInfo.path)) {
                     String videoId = urlInfo.parameters.get("v");
 
-                    if (videoId != null) return routeFromVideoId(videoId, urlInfo, httpInterface);
+                    if (videoId != null) return routeFromVideoId(httpInterface, videoId, urlInfo);
                 } else if ("/playlist".equals(urlInfo.path)) {
                     String playlistId = urlInfo.parameters.get("list");
 
@@ -201,7 +205,7 @@ protected Router getRouter(String identifier, HttpInterface httpInterface) {
                             List<URI> redirects = httpInterface.getContext().getRedirectLocations();
 
                             if (redirects != null && !redirects.isEmpty()) {
-                                return getRouter(redirects.get(0).toString(), httpInterface);
+                                return getRouter(httpInterface, redirects.get(0).toString());
                             }
 
                             throw new FriendlyException("Unable to process youtube watch_videos link", SUSPICIOUS,
@@ -215,20 +219,23 @@ protected Router getRouter(String identifier, HttpInterface httpInterface) {
                 Matcher shortHandMatcher = shortHandPattern.matcher(identifier);
 
                 if (shortHandMatcher.matches()) {
-                    return routeFromVideoId(shortHandMatcher.group("videoId"), null, httpInterface);
+                    return routeFromVideoId(httpInterface, shortHandMatcher.group("videoId"), null);
                 }
             }
         }
 
         return null;
     }
 
-    protected Router routeFromVideoId(String videoId, UrlInfo urlInfo, HttpInterface httpInterface) {
+    @Nullable
+    protected Router routeFromVideoId(@NotNull HttpInterface httpInterface,
+                                      @NotNull String videoId,
+                                      @Nullable UrlInfo urlInfo) {
         String trimmedId = videoId.length() > 11 ? videoId.substring(0, 11) : videoId;
 
         if (!directVideoIdPattern.matcher(trimmedId).matches()) {
             return Router.none;
-        } else if (urlInfo.parameters.containsKey("list")) {
+        } else if (urlInfo != null && urlInfo.parameters.containsKey("list")) {
             String playlistId = urlInfo.parameters.get("list");
 
             if (playlistId.startsWith("RD")) {
@@ -241,10 +248,12 @@ protected Router routeFromVideoId(String videoId, UrlInfo urlInfo, HttpInterface
         return (client) -> client.loadVideo(this, httpInterface, trimmedId);
     }
 
+    @NotNull
     public YoutubeAudioTrack buildAudioTrack(AudioTrackInfo trackInfo) {
         return new YoutubeAudioTrack(trackInfo, this);
     }
 
+    @NotNull
     public SignatureCipherManager getCipherManager() {
         return cipherManager;
     }
@@ -254,7 +263,8 @@ public SignatureCipherManager getCipherManager() {
      * @param cls The class of the client to return.
      * @return The client instance, or null if it's not registered.
      */
-    public <T extends Client> T getClient(Class<T> cls) {
+    @Nullable
+    public <T extends Client> T getClient(@NotNull Class<T> cls) {
         for (Client client : clients) {
             if (cls.isAssignableFrom(client.getClass())) {
                 return cls.cast(client);
@@ -264,14 +274,17 @@ public <T extends Client> T getClient(Class<T> cls) {
         return null;
     }
 
+    @NotNull
     public Client[] getClients() {
         return clients;
     }
 
+    @NotNull
     public HttpInterfaceManager getHttpInterfaceManager() {
         return httpInterfaceManager;
     }
 
+    @NotNull
     public HttpInterface getInterface() {
         return httpInterfaceManager.getInterface();
     }
@@ -287,7 +300,8 @@ public void encodeTrack(AudioTrack track, DataOutput output) {
     }
 
     @Override
-    public AudioTrack decodeTrack(AudioTrackInfo trackInfo, DataInput input) {
+    @NotNull
+    public AudioTrack decodeTrack(@NotNull AudioTrackInfo trackInfo, @NotNull DataInput input) {
         return new YoutubeAudioTrack(trackInfo, this);
     }
 
@@ -300,6 +314,7 @@ public void shutdown() {
     protected interface Router {
         Router none = (unused) -> AudioReference.NO_TRACK;
 
-        AudioItem route(Client client) throws CannotBeLoaded, IOException;
+        @Nullable
+        AudioItem route(@NotNull Client client) throws CannotBeLoaded, IOException;
     }
 }

common/src/main/java/dev/lavalink/youtube/cipher/CipherOperation.java

@@ -1,5 +1,7 @@
 package dev.lavalink.youtube.cipher;
 
+import org.jetbrains.annotations.NotNull;
+
 /**
  * One cipher operation definition.
  */
@@ -17,7 +19,7 @@ public class CipherOperation {
      * @param type The type of the operation.
      * @param parameter The parameter for the operation.
      */
-    public CipherOperation(CipherOperationType type, int parameter) {
+    public CipherOperation(@NotNull CipherOperationType type, int parameter) {
         this.type = type;
         this.parameter = parameter;
     }

common/src/main/java/dev/lavalink/youtube/cipher/SignatureCipher.java

@@ -1,5 +1,7 @@
 package dev.lavalink.youtube.cipher;
 
+import org.jetbrains.annotations.NotNull;
+
 import javax.script.Invocable;
 import javax.script.ScriptEngine;
 import javax.script.ScriptException;
@@ -15,7 +17,9 @@ public class SignatureCipher {
   public final String scriptTimestamp;
   public final String rawScript;
 
-  public SignatureCipher(String nFunction, String timestamp, String rawScript) {
+  public SignatureCipher(@NotNull String nFunction,
+                         @NotNull String timestamp,
+                         @NotNull String rawScript) {
     this.nFunction = nFunction;
     this.scriptTimestamp = timestamp;
     this.rawScript = rawScript;
@@ -25,7 +29,7 @@ public SignatureCipher(String nFunction, String timestamp, String rawScript) {
    * @param text Text to apply the cipher on
    * @return The result of the cipher on the input text
    */
-  public String apply(String text) {
+  public String apply(@NotNull String text) {
     StringBuilder builder = new StringBuilder(text);
 
     for (CipherOperation operation : operations) {
@@ -56,7 +60,7 @@ public String apply(String text) {
    * @param scriptEngine JavaScript engine to execute function
    * @return The result of the n parameter transformation
    */
-  public String transform(String text, ScriptEngine scriptEngine) throws ScriptException, NoSuchMethodException {
+  public String transform(@NotNull String text, @NotNull ScriptEngine scriptEngine) throws ScriptException, NoSuchMethodException {
     String transformed;
 
     scriptEngine.eval("n=" + nFunction);
@@ -68,7 +72,7 @@ public String transform(String text, ScriptEngine scriptEngine) throws ScriptExc
   /**
    * @param operation The operation to add to this cipher
    */
-  public void addOperation(CipherOperation operation) {
+  public void addOperation(@NotNull CipherOperation operation) {
     operations.add(operation);
   }