Package com.jagrosh.jdautilities.commons.waiter

Class EventWaiter

java.lang.Object
com.jagrosh.jdautilities.commons.waiter.EventWaiter
All Implemented Interfaces:
net.dv8tion.jda.api.hooks.EventListener
public class EventWaiter extends Object implements net.dv8tion.jda.api.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 Details

    • EventWaiter

      public EventWaiter()
      Constructs an empty EventWaiter.

    • EventWaiter

      public EventWaiter(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:
      IllegalArgumentException - If the threadpool provided is null or is shutdown
      See Also:

  • Method Details

    • 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.api.events.Event> void waitForEvent(Class<T> classType, Predicate<T> condition, 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:
      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.api.events.Event> void waitForEvent(Class<T> classType, Predicate<T> condition, Consumer<T> action, long timeout, TimeUnit unit, 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:
      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.api.events.GenericEvent event)
      Specified by:
      onEvent in interface net.dv8tion.jda.api.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:
      UnsupportedOperationException - The EventWaiter is supposed to close automatically.