Package studio.mevera.imperat.events

Interface EventSubscription<T extends Event>

Type Parameters:
T - the exact type of Event this subscription handles
All Superinterfaces:
Prioritizable
public interface EventSubscription<T extends Event> extends Prioritizable
Represents a single subscription to a specific event type on an EventBus.

An EventSubscription is created every time a handler is registered via EventBus.register(java.lang.Class<T>, studio.mevera.imperat.events.EventListenerConsumer<T>) and encapsulates all the metadata associated with that registration: its unique identifier, the handler itself, the priority at which it executes, and whether it runs synchronously or asynchronously.

The subscription's identity is solely determined by its UUID. Two subscriptions with the same ID are considered equal regardless of their other fields.

Subscription Lifecycle

  1. Handler is registered via EventBus.register(Class, EventListenerConsumer)
  2. EventBus creates an EventSubscription with a unique ID
  3. Subscription is stored and returned to the caller
  4. Handler is invoked whenever matching events are posted
  5. Subscription can be unregistered via EventBus.unregister(UUID)

Example: Storing and Managing Subscriptions


 // Store subscription for later unregistration
 EventSubscription<PlayerJoinEvent> subscription =
     eventBus.register(PlayerJoinEvent.class, event -> {
         logger.info("Player joined: {}", event.getPlayer().getName());
     });

 // Later, unregister using the subscription ID
 eventBus.unregister(subscription.id());

Example: Inspecting Subscription Metadata


 EventSubscription<?> subscription = eventBus.register(
     CommandPostRegistrationEvent.class,
     event -> handleCommandRegistration(event),
     Priority.HIGH,
     ExecutionStrategy.ASYNC
 );

 logger.info("Registered handler with ID: {}", subscription.id());
 logger.info("Priority: {}", subscription.priority());
 logger.info("Strategy: {}", subscription.strategy());

Example: Dynamic Handler Management


 // Track subscriptions for cleanup
 Map<String, EventSubscription<?>> activeSubscriptions = new HashMap<>();

 public void enableFeature(String featureName) {
     EventSubscription<?> subscription = eventBus.register(
         FeatureEvent.class,
         event -> handleFeature(event)
     );
     activeSubscriptions.put(featureName, subscription);
 }

 public void disableFeature(String featureName) {
     EventSubscription<?> subscription = activeSubscriptions.remove(featureName);
     if (subscription != null) {
         eventBus.unregister(subscription.id());
     }
 }
Since:
1.0
See Also:

  • Method Details

    • id

      UUID id()
      Returns the unique identifier of this subscription.

      This ID is automatically generated when the subscription is created and is used to unregister the subscription via EventBus.unregister(UUID).

      Returns:
      the unique identifier, never null

    • handler

      EventListenerConsumer<T> handler()
      Returns the handler consumer that processes events for this subscription.
      Returns:
      the event handler, never null

    • strategy

      ExecutionStrategy strategy()
      Returns the execution strategy for this subscription, determining whether the handler runs in the posting thread (ExecutionStrategy.SYNC) or in a background thread (ExecutionStrategy.ASYNC).
      Returns:
      the execution strategy, never null
      See Also: