feat: better loadItemSync (#134)

main/build.gradle.kts

@@ -29,6 +29,8 @@ dependencies {
     implementation(libs.base64)
     implementation(libs.json)
 
+    implementation(libs.intellij.annotations)
+
     testImplementation(libs.groovy)
     testImplementation(libs.spock.core)
     testImplementation(libs.logback.classic)

main/src/main/java/com/sedmelluq/discord/lavaplayer/player/AudioPlayerManager.java

@@ -3,11 +3,13 @@
 import com.sedmelluq.discord.lavaplayer.source.AudioSourceManager;
 import com.sedmelluq.discord.lavaplayer.tools.io.MessageInput;
 import com.sedmelluq.discord.lavaplayer.tools.io.MessageOutput;
+import com.sedmelluq.discord.lavaplayer.track.AudioItem;
 import com.sedmelluq.discord.lavaplayer.track.AudioReference;
 import com.sedmelluq.discord.lavaplayer.track.AudioTrack;
 import com.sedmelluq.discord.lavaplayer.track.DecodedTrackHolder;
 import org.apache.http.client.config.RequestConfig;
 import org.apache.http.impl.client.HttpClientBuilder;
+import org.jetbrains.annotations.Nullable;
 
 import java.io.IOException;
 import java.util.List;
@@ -112,6 +114,29 @@ default void loadItemSync(final String identifier, final AudioLoadResultHandler
      */
     void loadItemSync(final AudioReference reference, final AudioLoadResultHandler resultHandler);
 
+    /**
+     * Loads a track or playlist with the specified identifier and returns it.
+     *
+     * @param reference The audio reference that holds the identifier that a specific source manager
+     *                  should be able to find the track with.
+     * @return The loaded {@link AudioItem}, or `null` if nothing was found.
+     * @see #loadItemSync(AudioReference)
+     */
+    @Nullable
+    default AudioItem loadItemSync(final String reference) {
+        return loadItemSync(new AudioReference(reference, null));
+    }
+
+    /**
+     * Loads a track or playlist with the specified identifier and returns it.
+     *
+     * @param reference The audio reference that holds the identifier that a specific source manager
+     *                  should be able to find the track with.
+     * @return The loaded {@link AudioItem}, or `null` if nothing was found.
+     */
+    @Nullable
+    AudioItem loadItemSync(final AudioReference reference);
+
     /**
      * Schedules loading a track or playlist with the specified identifier with an ordering key so that items with the
      * same ordering key are handled sequentially in the order of calls to this method.

main/src/main/java/com/sedmelluq/discord/lavaplayer/player/DefaultAudioPlayerManager.java

@@ -13,6 +13,7 @@
 import com.sedmelluq.lava.common.tools.ExecutorTools;
 import org.apache.http.client.config.RequestConfig;
 import org.apache.http.impl.client.HttpClientBuilder;
+import org.jetbrains.annotations.Nullable;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
@@ -148,15 +149,23 @@ public List<AudioSourceManager> getSourceManagers() {
         return Collections.unmodifiableList(sourceManagers);
     }
 
+    @Override
+    public @Nullable AudioItem loadItemSync(AudioReference reference) {
+        AudioItem item = checkSourcesForItem(reference);
+        if (item == null) {
+            log.debug("No matches for track with identifier {}.", reference.identifier);
+        }
+
+        return item;
+    }
+
     @Override
     public void loadItemSync(final AudioReference reference, final AudioLoadResultHandler resultHandler) {
         boolean[] reported = new boolean[1];
 
         try {
-            if (!checkSourcesForItem(reference, resultHandler, reported)) {
-                log.debug("No matches for track with identifier {}.", reference.identifier);
-                resultHandler.noMatches();
-            }
+            AudioItem item = loadItemSync(reference);
+            submitItemToResultHandler(item, resultHandler, reported);
         } catch (Throwable throwable) {
             if (reported[0]) {
                 log.warn("Load result handler for {} threw an exception", reference.identifier, throwable);
@@ -387,40 +396,57 @@ public void setItemLoaderThreadPoolSize(int poolSize) {
         trackInfoExecutorService.setMaximumPoolSize(poolSize);
     }
 
-    private boolean checkSourcesForItem(AudioReference reference, AudioLoadResultHandler resultHandler, boolean[] reported) {
+    private void submitItemToResultHandler(AudioItem item, AudioLoadResultHandler handler, boolean[] reported) {
+        if (item == null) {
+            reported[0] = true;
+            handler.noMatches();
+        } else if (item instanceof AudioTrack) {
+            reported[0] = true;
+            handler.trackLoaded((AudioTrack) item);
+        } else if (item instanceof AudioPlaylist) {
+            reported[0] = true;
+            handler.playlistLoaded((AudioPlaylist) item);
+        } else {
+            log.warn("Cannot submit unknown item to result handler: {}", item);
+        }
+    }
+
+    /**
+     * Attempts to load the provided {@link AudioReference} using the sources registered with this {@link AudioPlayerManager}.
+     * Unlike {@link #checkSourcesForItemOnce} this method attempts to follow any returned redirects.
+     */
+    @Nullable
+    private AudioItem checkSourcesForItem(AudioReference reference) {
         AudioReference currentReference = reference;
 
         for (int redirects = 0; redirects < MAXIMUM_LOAD_REDIRECTS && currentReference.identifier != null; redirects++) {
-            AudioItem item = checkSourcesForItemOnce(currentReference, resultHandler, reported);
-            if (item == null) {
-                return false;
-            } else if (!(item instanceof AudioReference)) {
-                return true;
+            AudioItem item = checkSourcesForItemOnce(currentReference);
+            if (item instanceof AudioReference) {
+                currentReference = (AudioReference) item;
+                continue;
             }
-            currentReference = (AudioReference) item;
+
+            return item;
         }
 
-        return false;
+        return null;
     }
 
-    private AudioItem checkSourcesForItemOnce(AudioReference reference, AudioLoadResultHandler resultHandler, boolean[] reported) {
+    @Nullable
+    private AudioItem checkSourcesForItemOnce(AudioReference reference) {
         for (AudioSourceManager sourceManager : sourceManagers) {
             if (reference.containerDescriptor != null && !(sourceManager instanceof ProbingAudioSourceManager)) {
                 continue;
             }
 
             AudioItem item = sourceManager.loadItem(this, reference);
-
             if (item != null) {
                 if (item instanceof AudioTrack) {
                     log.debug("Loaded a track with identifier {} using {}.", reference.identifier, sourceManager.getClass().getSimpleName());
-                    reported[0] = true;
-                    resultHandler.trackLoaded((AudioTrack) item);
                 } else if (item instanceof AudioPlaylist) {
                     log.debug("Loaded a playlist with identifier {} using {}.", reference.identifier, sourceManager.getClass().getSimpleName());
-                    reported[0] = true;
-                    resultHandler.playlistLoaded((AudioPlaylist) item);
                 }
+
                 return item;
             }
         }

settings.gradle.kts

@@ -36,6 +36,7 @@ fun VersionCatalogBuilder.plugins() {
 fun VersionCatalogBuilder.common() {
     library("slf4j", "org.slf4j", "slf4j-api").version("2.0.7")
     library("commons-io", "commons-io", "commons-io").version("2.13.0")
+    library("intellij-annotations", "org.jetbrains", "annotations").version("24.0.0")
 
     version("jackson", "2.15.2")
     library("jackson-core", "com.fasterxml.jackson.core", "jackson-core").versionRef("jackson")