[JDA-Utilities Guide] How to use EventWaiter's waitForEvent method

[Andre601]

When using JDA-Utilities, people will quite frequently ask questions regarding the EventWaiter and how you use its waitForEvent method.
This little discussion should serve as a small guide to assist in answering common questions about it.

Before we start

It is highly recommended to use JDA-Chewtils instead of JDA-Utilities as it is updated and maintained, and also includes new features such as Support for Slashcommands.

JDA-Chewtils is fully compatible with JDA-Utilities and the setup explained here regarding the EventWaiter is also the same for JDA-Chewtils.

What is the EventWaiter?

The name should say it all. This utility, which is part of the common JDA-Utilities package, allows you to wait for a specific event.
Supported are all classes that extend the abstract Event class from JDA. If you have your own custom events extending this class can you try it out with the EventWaiter. It may require some tinkering tho.

Structure of waitForEvent

The EventWaiter has two specific waitForEvent methods: One with and one without a timeout.

Common parts

Both methods share the first 3 parts:

waitForEvent(
        GenericEvent.class,   // Class<T> (Needs to extend Event)
        event -> true,        // Predicate<T>. "event" will have the Event type you listened for.
        event -> someMethod() // Consumer<T>. "event" will have the Event type you listened for.
)

This method will wait indefinitely for the Predicate<T> to be true, to execute whatever was defined in the Consumer<T>

The second waitForEvent method is different in that it has 3 additional variables to define a time, time unit and timeout action when the defined n time units run out without any true condition.

Full Structure:

waitForEvent(
        GenericEvent.class, 
        event -> true, 
        event -> someMethod(),
        1,                      // The amount of Time units to wait for the event.
        TimeUnit.MINUTES,       // The time units to wait for. This means that with the above, this example would wait 1 minute.
        () -> someOtherMethod() // Part that will be executed when the set time passed without any true conditions.
)

The above example would wait 1 minute before timing out.
Please note that the last part is actually a Runnable and not a Predicate<T> or Consumer<T> like the 2nd and 3rd part are.

Once a waitForEvent method has a true Predicate<T> will it execute whatever was defined in the Consumer<T>.
If it has a timeout defined and the Predicate<T> didn't return true in that time will the Runnable be executed.

In either case will the EventWaiter stop listening for the event you defined, essentially dropping the event listening in that case.

Examples

Here are some examples. They range from very simple to quite difficult/advanced. If you have any other example to show, let me know and I include them.

Prerequisite: Setup EventWaiter

It's recommended to only have a single EventWaiter instance that you use through a Getter (Get method).

In the examples below will we assume the following basic setup. If you have a different setup for your bot can you freely adjust this to your preferences.

public class MyBot
{
    private final EventWaiter eventWaiter = new EventWaiter();

    public static void main(String[] args)
    {
        try
        {
            // args[0] would be our Bot token
            new MyBot().start(args[0]);
        }
        catch (LoginException | InterruptedException ex)
        {
            ex.printStackTrace()
        }
    }

    public void start(String token)
    {
        JDABuilder.createDefault(token)
                .enableIntents(GatewayIntent.GUILD_MEMBERS) // Priviledged intent. Some examples use it.
                .addEventListeners(
                        new MessageExample(this),  // See example 1
                        new ReactionExample(this), // See example 2
                        new ButtonsExample(this),  // See example 3
                        eventWaiter                // Always add the EventWaiter instance as event listener
                )
                .build()
                .awaitReady();
    }
    
    public EventWaiter getEventWaiter()
    {
        return eventWaiter;
    }
}

Example 1: Wait for a response.

The bot waits for a response from the user once they send a specific command.

public class MessageExample extends ListenerAdapter
{ 
    private final MyBot bot;
    
    public MessageExample(MyBotbot)
    {
        this.bot = bot;
    }
    
    @Override
    public void onGuildMessageReceived(GuildMessageReceivedEvent event){
        String msg = event.getMessage().getContentRaw();
        TextChannel tc = event.getChannel();
        User author = event.getAuthor();
        
        if (author.isBot()) // Ignore Bots (Yourself)
        {
            return;
        }
        
        if (!msg.equalsIgnoreCase("!repeat")) // Only react if message equals !repeat
        {
            return;
        }
        
        tc.sendMessage("Hello " + author.getName() + ", what should I say?")
            .queue(message -> bot.getWaiter().waitForEvent( // Setup Wait action once message was send
                GuildMessageReceivedEvent.class,
                e -> {
                    if(!e.getChannel().getId().equals(tc.getId())) // Check that channel is the same
                    {
                        return false;
                    }
                    
                    return e.getAuthor().getIdLong() == author.getIdLong(); // Check for same author
                },
                e -> {
                    String authorMessage = e.getMessage().getContentRaw();
                    tc.sendMessage(authorMessage).queue();
                },
                1, TimeUnit.MINUTES,
                () -> {
                    tc.sendMessage("You didn't respond in time!").queue();
                }
            )
        );
    }
}

Example 2: Make a choose-system (With Reactions)

Let's the user select whether they like apples or not by clicking on the reactions.

public class ReactionExample extends ListenerAdapter
{
    
    private final MyBot bot;
    
    public ReactionExample(MyBot bot)
    {
        this.bot = bot;
    }
    
    @Override
    public void onGuildMessageReceived(GuildMessageReceivedEvent event)
    {
        String msg = event.getMessage().getContentRaw();
        TextChannel tc = event.getChannel();
        User author = event.getAuthor();
        
        if(author.isBot()) // Ignore Bots (Yourself)
        {
            return;
        }
        
        if(!msg.equalsIgnoreCase("!apple")) // Only react if message equals !apple
        {
            return;
        }
        
        tc.sendMessage("Hello " + author.getName() + ", do you like apples?").queue(
            message -> RestAction.allOf( // Allows the combination of multiple RestActions
                message.addReaction("\u2705"), // ✅
                message.addReaction("\u274c")  // ❌
            ).queue(v -> bot.getWaiter().waitForEvent(
                GuildMessageReactionAddEvent.class,
                e -> {
                    if(!e.getMessageId().equals(message.getId())) // Make sure the message is the same
                    {
                        return false;
                    }
                                
                    if(e.getUser().isBot()) // Ignore Bots... again
                    {
                        return false;
                    }
                            
                    MessageReaction.ReactionEmote emote = e.getReactionEmote(); // Get the Emote
                    if(!emote.isEmoji()) // Check if it's actually unicode and not custom
                    {
                        return false;
                    }
                            
                    // Make sure the user reacting is the same.
                    if(e.getUserIdLong() != author.getIdLong())
                    {
                        return false;
                    }
                            
                    // Check that the Reaction is either ✅ or ❌
                    return emote.getName().equals("\u2705") || emote.getName().equals("\u274c");
                },
                e -> {
                    MessageReaction.ReactionEmote emote = e.getReactionEmote();
                                
                    // Since we already checked for ✅ and ❌ before do we now
                    // only need to know which one we have.
                    if(emote.getName().equals("\u2705"))
                    {
                        tc.sendMessage("You like apples!").queue();
                    }
                    else // Not ✅? Then it's ❌
                    {
                        tc.sendMessage("You **don't** like apples!").queue();
                    }
                },
                1, TimeUnit.MINUTES,
                () -> {
                    tc.sendMessage("You didn't respond in time!").queue();
                }
            ))
        );
    }
}

Example 3: Make a choose-system (With Buttons)

Similar to the 2nd example, but with Discord buttons.

public class ButtonsExample extends ListenerAdapter
{
    
    private final MyBot bot;
    
    public ButtonsExample(MyBot bot)
    {
        this.bot = bot;
    }
    
    @Override
    public void onGuildMessageReceived(GuildMessageReceivedEvent event)
    {
        String msg = event.getMessage().getContentRaw();
        TextChannel tc = event.getChannel();
        User author = event.getAuthor();
        
        if(author.isBot()) // Ignore Bots (Yourself)
        {
            return;
        }
        
        if(!msg.equalsIgnoreCase("!pet")) // Only react if message equals !pet
        {
            return;
        }
        
        tc.sendMessage("Hello " + author.getName() + ", which pet do you like the most?")
            .setActionRow( // Add our Buttons (max 5 per ActionRow)
                Button.of(ButtonStyle.PRIMARY, "example-bot:button:pet:cat", "Cat", Emoji.fromUnicode("\uD83D\uDC31")),     // 🐱 
                Button.of(ButtonStyle.PRIMARY, "example-bot:button:pet:dog", "Dog", Emoji.fromUnicode("\uD83D\uDC36")),     // 🐶 
                Button.of(ButtonStyle.PRIMARY, "example-bot:button:pet:bunny", "Bunny", Emoji.fromUnicode("\uD83D\uDC30")), // 🐰 
                Button.of(ButtonStyle.PRIMARY, "example-bot:button:pet:fox", "Fox", Emoji.fromUnicode("\uD83E\uDD8A"))      // 🦊
            ).queue(message -> bot.getWaiter().waitForEvent(
                ButtonClickEvent.class, 
                e -> { 
                    if (e.getMessageIdLong() != message.getIdLong())
                    {
                        return false;
                    }
                    
                    if (e.getUser().getIdLong() != author.getIdLong())
                    {
                        return false;
                    }
                    
                    if (!equalsAny(e.getComponentId()))
                    {
                        return false;
                    }
                    
                    return !e.isAcknowledged();
                },
                e -> {
                    // Split the Button ID on : and get the 4th part of it.
                    String selection = e.getComponentId().split(":")[3];
                    
                    e.getHook().sendMessage("You selected " + selection + "!").queue();
                },
                1, TimeUnit.MINUTES,
                () -> {
                    tc.sendMessage("You didn't respond in time!").queue();
                }
            )
        );
    }
    
    // Convenience method to check the ID and keep the main code more clean
    private boolean equalsAny(String buttonId)
    {
        return buttonId.equals("example-bot:button:pet:cat") ||
               buttonId.equals("example-bot:button:pet:dog") ||
               buttonId.equals("example-bot:button:pet:bunny") ||
               buttonId.equals("example-bot:button:pet:fox");
    }
}

[DV8FromTheWorld]

This guide looks great! 🥇

You may want to link to docs throughout the guide to introduce developers to key aspects of documention.

[DV8FromTheWorld]

You also might want to consider restructuring the 2nd example to introduce the fact that you can define the predicates and handlers as methods on the class and pass them to the event waiter using the Java8 function syntax to help with readability.

Maybe something like this?

.waitForEvent(
  GuildMessageReactionAddEvent.class,
  this.isValidReactionOnMessage(message.getId()), //Should return a built predicate
  this::handleReaction,
  1, TimeUnit.MINUTES,
  this::handleTimeout
);

[Andre601]

These should mainly be easy examples and this would imo only add more complexity to it... I also don't know how the methods would need to look like...

[Andre601]

This guide looks great! 🥇

You may want to link to docs throughout the guide to introduce developers to key aspects of documention.

Yeah sure. Although I think the online JDA-Utilities docs are a bit outdated. At least the last time I checked was that the case for me.

[arynxd]

enableIntents(GatewayIntent.GUILD_MEMBER)

should be
enableIntents(GatewayIntent.GUILD_MEMBERS)

[Andre601]

Updated. Thanks

[Andre601]

Updated the examples with a ButtonClickEvent one... Not 100% if that is really the best example tho.