com.jagrosh.jdautilities.commons.waiter

Class EventWaiter

java.lang.Object

com.jagrosh.jdautilities.commons.waiter.EventWaiter

All Implemented Interfaces:

net.dv8tion.jda.core.hooks.EventListener

public class EventWaiter
extends java.lang.Object
implements net.dv8tion.jda.core.hooks.EventListener

The EventWaiter is capable of handling specialized forms of Event that must meet criteria not normally specifiable without implementation of an EventListener.

Creating an EventWaiter requires provision and/or creation of a Executor, and thus a proper shutdown of said executor. The default constructor for an EventWaiter sets up a working, "live", EventWaiter whose shutdown is triggered via JDA firing a ShutdownEvent.
A more "shutdown adaptable" constructor allows the provision of a ScheduledExecutorService and a choice of how exactly shutdown will be handled (see EventWaiter(ScheduledExecutorService, boolean) for more details).

As a final note, if you intend to use the EventWaiter, it is highly recommended you DO NOT create multiple EventWaiters! Doing this will cause unnecessary increases in memory usage.

Author:

John Grosh (jagrosh)

Constructor Summary

Constructors

Constructor and Description
EventWaiter() Constructs an empty EventWaiter.
EventWaiter(java.util.concurrent.ScheduledExecutorService threadpool, boolean shutdownAutomatically) Constructs an EventWaiter using the provided Executor as it's threadpool.

Method Summary

Modifier and Type	Method and Description
boolean	isShutdown() Gets whether the EventWaiter's internal ScheduledExecutorService is shutdown.
void	onEvent(net.dv8tion.jda.core.events.Event event)
void	shutdown() Closes this EventWaiter if it doesn't normally shutdown automatically.
<T extends net.dv8tion.jda.core.events.Event> void	waitForEvent(java.lang.Class<T> classType, java.util.function.Predicate<T> condition, java.util.function.Consumer<T> action) Waits an indefinite amount of time for an Event that returns true when tested with the provided Predicate.
<T extends net.dv8tion.jda.core.events.Event> void	waitForEvent(java.lang.Class<T> classType, java.util.function.Predicate<T> condition, java.util.function.Consumer<T> action, long timeout, java.util.concurrent.TimeUnit unit, java.lang.Runnable timeoutAction) Waits a predetermined amount of time for an Event that returns true when tested with the provided Predicate.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

EventWaiter

public EventWaiter()

Constructs an empty EventWaiter.

EventWaiter

public EventWaiter(java.util.concurrent.ScheduledExecutorService threadpool,
                   boolean shutdownAutomatically)

Constructs an EventWaiter using the provided Executor as it's threadpool.

A developer might choose to use this constructor over the default, for using a alternate form of threadpool, as opposed to a single thread executor.
A developer might also favor this over the default as they use the same waiter for multiple shards, and thus shutdown must be handled externally if a special shutdown sequence is being used.

shutdownAutomatically is required to be manually specified by developers as a way of verifying a contract that the developer will conform to the behavior of the newly generated EventWaiter:

• If true, shutdown is handled when a ShutdownEvent is fired. This means that any external functions of the provided Executor is now impossible and any externally queued tasks are lost if they have yet to be run.
• If false, shutdown is now placed as a responsibility of the developer, and no attempt will be made to shutdown the provided Executor.

It's worth noting that this EventWaiter can serve as a delegate to invoke the threadpool's shutdown via a call to EventWaiter#shutdown(). However, this operation is only supported for EventWaiters that are not supposed to shutdown automatically, otherwise invocation of EventWaiter#shutdown() will result in an UnsupportedOperationException.

Parameters:

threadpool - The ScheduledExecutorService to use for this EventWaiter's threadpool.

shutdownAutomatically - Whether or not the threadpool will shutdown automatically when a ShutdownEvent is fired.

Throws:

java.lang.IllegalArgumentException - If the threadpool provided is null or is shutdown

See Also:

EventWaiter#shutdown()

Method Detail

isShutdown

public boolean isShutdown()

Gets whether the EventWaiter's internal ScheduledExecutorService is shutdown.

Returns:

true if the ScheduledExecutorService is shutdown, false otherwise.

waitForEvent

public <T extends net.dv8tion.jda.core.events.Event> void waitForEvent(java.lang.Class<T> classType,
                                                                       java.util.function.Predicate<T> condition,
                                                                       java.util.function.Consumer<T> action)

Waits an indefinite amount of time for an Event that returns true when tested with the provided Predicate.

When this occurs, the provided Consumer will accept and execute using the same Event.

Type Parameters:

T - The type of Event to wait for.

Parameters:

classType - The Class of the Event to wait for. Never null.

condition - The Predicate to test when Events of the provided type are thrown. Never null.

action - The Consumer to perform an action when the condition Predicate returns true. Never null.

Throws:

java.lang.IllegalArgumentException - One of two reasons:

• 1) Either the classType, condition, or action was null.
• 2) The internal threadpool is shut down, meaning that no more tasks can be submitted.

waitForEvent

public <T extends net.dv8tion.jda.core.events.Event> void waitForEvent(java.lang.Class<T> classType,
                                                                       java.util.function.Predicate<T> condition,
                                                                       java.util.function.Consumer<T> action,
                                                                       long timeout,
                                                                       java.util.concurrent.TimeUnit unit,
                                                                       java.lang.Runnable timeoutAction)

Waits a predetermined amount of time for an Event that returns true when tested with the provided Predicate.

Once started, there are two possible outcomes:

• The correct Event occurs within the time allotted, and the provided Consumer will accept and execute using the same Event.
• The time limit is elapsed and the provided Runnable is executed.

Type Parameters:

T - The type of Event to wait for.

Parameters:

classType - The Class of the Event to wait for. Never null.

condition - The Predicate to test when Events of the provided type are thrown. Never null.

action - The Consumer to perform an action when the condition Predicate returns true. Never null.

timeout - The maximum amount of time to wait for, or -1 if there is no timeout.

unit - The TimeUnit measurement of the timeout, or null if there is no timeout.

timeoutAction - The Runnable to run if the time runs out before a correct Event is thrown, or null if there is no action on timeout.

Throws:

java.lang.IllegalArgumentException - One of two reasons:

• 1) Either the classType, condition, or action was null.
• 2) The internal threadpool is shut down, meaning that no more tasks can be submitted.

onEvent

public final void onEvent(net.dv8tion.jda.core.events.Event event)

Specified by:

onEvent in interface net.dv8tion.jda.core.hooks.EventListener

shutdown

public void shutdown()

Closes this EventWaiter if it doesn't normally shutdown automatically.

IF YOU USED THE DEFAULT CONSTRUCTOR WITH NO ARGUMENTS DO NOT CALL THIS!
Calling this method on an EventWaiter that does shutdown automatically will result in an UnsupportedOperationException being thrown.

Throws:

java.lang.UnsupportedOperationException - The EventWaiter is supposed to close automatically.