Add `JDA#listenOnce`

[freya022]

Pull Request Etiquette

• [X] I have checked the PRs for upcoming features/bug fixes.
• [X] I have read the contributing guidelines.

Changes

• [X] Internal code
• [X] Library interface (affecting end-user code)
• [ ] Documentation
• [ ] Other: _____

Closes Issue: NaN

Description

Adds an helper method to listen for an event, once.

Example: Listening to a message from a channel and a user, after using a slash command:

final Duration timeout = Duration.ofSeconds(5);
event.reply("Reply in " + TimeFormat.RELATIVE.after(timeout) + " if you can!")
       .setEphemeral(true)
       .queue();

event.getJDA().listenOnce(MessageReceivedEvent.class)
        .filter(messageEvent -> messageEvent.getChannel().getIdLong() == event.getChannel().getIdLong())
        .filter(messageEvent -> messageEvent.getAuthor().getIdLong() == event.getUser().getIdLong())
        .timeout(timeout, () -> {
            event.getHook().editOriginal("Timeout!").queue();
        })
        .submit()
        .onSuccess(messageEvent -> {
            event.getHook().editOriginal("You sent: " + messageEvent.getMessage().getContentRaw()).queue();
        });

[duncte123]

There is an addEventLister method on the shardManager, maybe this helper method could be added to that as well?

[freya022]

There is an addEventLister method on the shardManager, maybe this helper method could be added to that as well?

This would make things more complicated, if someone has a use case where you'd need to listen once for an event across all shards, let me know

[AshlyneS]

Just a quick thought, but I believe these would also be benifical. 💕

<E extends GenericEvent> Task<E> listenOnce(Class<E> type, Predicate<? super E> filter);

<E extends GenericEvent> Task<E> listenOnce(Class<E> type, Predicate<? super E> filter, Duration duration, @Nullable Runnable callback);

Otherwise at least some way to

jda.listenOnce(new SomethingCommonlyImplemented(argA, argB, etc));

[freya022]

Just a quick thought, but I believe these would also be benifical. 💕

<E extends GenericEvent> Task<E> listenOnce(Class<E> type, Predicate<? super E> filter);

<E extends GenericEvent> Task<E> listenOnce(Class<E> type, Predicate<? super E> filter, Duration duration, @Nullable Runnable callback);

Otherwise at least some way to

jda.listenOnce(new SomethingCommonlyImplemented(argA, argB, etc));

After discussing:

• The two first overloads would just be shortcuts, except they bring more confusion on what each parameter is, this will not be added.

• The last overload might be used in interactions which require waiting for user feedback, each class would configure the event, filters and the outcome of each step. This won't be added as JDA remains a low-level enough library, this type of usage can easily be achieved using an utility class such as:

  public abstract class OnceFactory<E extends GenericEvent> {
  private final JDA jda;
  
  public OnceFactory(JDA jda) {
      this.jda = jda;
  }
  
  protected Class<E> getType();
  
  protected void configure(Once.Builder<E> builder);
  
  public Task<E> create() {
      final var builder = jda.listenOnce(getType());
      configure(builder);
  
      return builder.submit();
  }
  }