Package dev.polv.taleapi.event

Class Event<T>

java.lang.Object
dev.polv.taleapi.event.Event<T>
Type Parameters:
T - the callback functional interface type
public final class Event<T> extends Object
A type-safe event holder that manages listener registration and invocation.

Each event type should have its own static Event<T> instance. Listeners are functional interfaces that get combined into a single invoker.

Example Usage


 // Define an event callback interface
 @FunctionalInterface
 public interface MyCallback {
   EventResult onSomething(String data);

   Event<MyCallback> EVENT = Event.create(callbacks -> data -> {
     for (var callback : callbacks) {
       EventResult result = callback.onSomething(data);
       if (result.shouldStop())
         return result;
     }
     return EventResult.PASS;
   });
 }

 // Register a listener
 MyCallback.EVENT.register(data -> {
   System.out.println("Received: " + data);
   return EventResult.PASS;
 });

 // Fire the event
 EventResult result = MyCallback.EVENT.invoker().onSomething("hello");

  • Method Details

    • create

      public static <T> Event<T> create(Function<List<T>,T> invokerFactory, T emptyInvoker)
      Creates a new Event with priority support.
      Type Parameters:
      T - the callback type
      Parameters:
      invokerFactory - function that combines a list of listeners into a single invoker
      emptyInvoker - the invoker to return when no listeners are registered
      Returns:
      a new Event instance

    • invokeAsync

      public static <T> CompletableFuture<EventResult> invokeAsync(Iterator<T> iterator, Function<T,CompletableFuture<EventResult>> invoker)
      Helper to chain async callback processing in priority order.

      This processes callbacks sequentially, awaiting async results before proceeding to the next callback. Stops early if any callback returns a result where EventResult.shouldStop() is true.

      Example Usage: 

      
 Event<PlayerJoinCallback> EVENT = Event.create(
     callbacks -> player -> Event.invokeAsync(
         callbacks.iterator(),
         callback -> callback.onPlayerJoin(player)),
     player -> EventResult.pass());
      Type Parameters:
      T - the callback type
      Parameters:
      iterator - iterator over the callbacks to invoke
      invoker - function that invokes a callback and returns a future result
      Returns:
      a CompletableFuture that completes with the final EventResult

    • register

      public void register(T listener)
      Registers a listener with EventPriority.NORMAL priority.
      Parameters:
      listener - the listener to register
      Throws:
      NullPointerException - if listener is null

    • register

      public void register(EventPriority priority, T listener)
      Registers a listener with the specified priority.
      Parameters:
      priority - the execution priority
      listener - the listener to register
      Throws:
      NullPointerException - if priority or listener is null

    • unregister

      public boolean unregister(T listener)
      Unregisters a listener from all priority levels.
      Parameters:
      listener - the listener to remove
      Returns:
      true if the listener was found and removed

    • invoker

      public T invoker()
      Returns the combined invoker for all registered listeners.

      The invoker executes listeners in priority order (HIGHEST to LOWEST).

      Returns:
      the invoker that will call all registered listeners

    • invokeAsync

      public <R> CompletableFuture<R> invokeAsync(Executor executor, Function<T,R> action)
      Fires the event asynchronously using the provided executor.

      This is a convenience method for async event handling. The returned CompletableFuture completes with the invoker result.

      Type Parameters:
      R - the return type of the event callback
      Parameters:
      executor - the executor to run the event on
      action - a function that calls the invoker and returns its result
      Returns:
      a CompletableFuture that completes with the event result

    • listenerCount

      public int listenerCount()
      Returns:
      the number of registered listeners across all priorities

    • getListeners

      public List<T> getListeners()
      Returns a snapshot of all registered listeners in priority order (HIGHEST to LOWEST).

      This is useful for async event implementations that need direct access to callbacks.

      Returns:
      an unmodifiable list of listeners

    • clearListeners

      public void clearListeners()
      Removes all registered listeners.