package com.github.bjoernpetersen.jmusicbot.provider;

import com.github.bjoernpetersen.jmusicbot.IdPlugin;
import com.github.bjoernpetersen.jmusicbot.InitStateWriter;
import com.github.bjoernpetersen.jmusicbot.InitializationException;
import com.github.bjoernpetersen.jmusicbot.Song;
import java.util.Collections;
import java.util.List;
import java.util.Set;
import javax.annotation.Nonnull;

public interface Suggester extends IdPlugin {

  /**
   * <p>Suggest the next song to play.</p>
   *
   * <p>When a song has been returned by this method, it can be assumed it's going to be played.
   * This means it should be removed from the 'next suggestions' list.</p>
   *
   * @return a song to play
   */
  @Nonnull
  Song suggestNext();

  /**
   * <p>Gets a list of next suggestions which will be returned by calling {@link
   * #suggestNext()}.</p>
   *
   * <p>The returned list will contain at least one element.</p>
   *
   * @param maxLength the maximum length of the returned list
   * @return a list of next suggestions
   */
  @Nonnull
  List<Song> getNextSuggestions(int maxLength);

  /**
   * <p>Notifies this Suggester that the specified song has been played.</p>
   *
   * <p>It is recommended that the song will be removed from the next suggestions when this method
   * is called.</p>
   *
   * <p>It is guaranteed that the song comes from a provider this suggester depends on.</p>
   *
   * @param song a Song
   */
  default void notifyPlayed(@Nonnull Song song) {
  }

  /**
   * <p>Removes the specified song from the suggestions.</p>
   *
   * The default implementation does nothing.
   *
   * @param song a song
   */
  default void removeSuggestion(@Nonnull Song song) {
  }

  /**
   * <p>Indicates a user disliking the specified song.</p>
   *
   * The default implementation calls {@link #removeSuggestion(Song)}.
   *
   * @param song a song
   */
  default void dislike(@Nonnull Song song) {
    removeSuggestion(song);
  }

  /**
   * <p>Signals to the provider that it can start doing work.</p>
   *
   * <p>The Suggester should remain operational until {@link #close()} is called.</p>
   *
   * <p>The dependency Map is guaranteed to contain all dependencies requested by {@link
   * #getDependencies()}. It will also contain all satisfiable dependencies that were requested by
   * {@link #getOptionalDependencies()}.</p>
   *
   * @param dependencies the Provider instances requested by {@link #getDependencies()} and {@link
   * #getOptionalDependencies()}
   * @param initStateWriter a writer for initialization state messages
   * @throws InitializationException If any errors occur (for example due to invalid log-in
   * credentials)
   * @throws InterruptedException if the thread is interrupted while initializing
   */
  void initialize(@Nonnull InitStateWriter initStateWriter,
      @Nonnull DependencyMap<Provider> dependencies)
      throws InitializationException, InterruptedException;

  /**
   * <p>Gets a set of providers this Suggester depends on.</p>
   *
   * The default implementation returns an empty set.
   *
   * @return a set of provider base classes
   */
  default Set<Class<? extends Provider>> getDependencies() {
    return Collections.emptySet();
  }

  /**
   * <p>Gets a set of providers this Suggester may use, but doesn't need.</p>
   *
   * The default implementation returns an empty set.
   *
   * @return a set of provider base classes
   */
  default Set<Class<? extends Provider>> getOptionalDependencies() {
    return Collections.emptySet();
  }
}

@@ -1390,32 +1390,115 @@
 ds on.%3C/p%3E%0A   *%0A
+   * %3Cp%3EThe default implementation calls %7B@link #removeSuggestion(Song)%7D.%3C/p%3E%0A   *%0A
    * @param song
@@ -1620,75 +1620,57 @@
 the 
-suggestions.%3C/p%3E%0A   *%0A   * The default implementation does nothing.
+%7B@link #getNextSuggestions(int) suggestions%7D.%3C/p%3E
 %0A   
@@ -1699,32 +1699,24 @@
 ong%0A   */%0A  
-default 
 void removeS
@@ -1736,38 +1736,33 @@
 nnull Song song)
- %7B%0A  %7D
+;
 %0A%0A  /**%0A   * %3Cp%3E

Make Suggester.removeSuggestion(Song) mandatory