Package studio.mevera.imperat.events

Interface CancellableEvent

All Superinterfaces:

Event

All Known Implementing Classes:

CommandPostProcessEvent, CommandPreProcessEvent, CommandPreRegistrationEvent

public interface CancellableEvent
extends Event

An extension of Event that supports cancellation.

Events implementing this interface can be cancelled by handlers, preventing subsequent actions or operations from occurring. This is particularly useful for pre-processing events where validation or authorization checks may need to prevent the main action.

Important: The event bus does NOT automatically skip handlers for cancelled events. It is the responsibility of each handler to check isCancelled() if they should respect cancellation. This design provides maximum flexibility, allowing some handlers to process even cancelled events (e.g., for logging purposes).

Cancellation Semantics

• Cancellation is cooperative - handlers must explicitly check the flag
• Higher priority handlers can cancel events before lower priority handlers run
• Cancelled events still propagate through all registered handlers
• Events can be un-cancelled by calling setCancelled(false)

Example Implementation

 public class PlayerChatEvent implements CancellableEvent {
     private final Player player;
     private String message;
     private boolean cancelled;
     
     public PlayerChatEvent(Player player, String message) {
         this.player = player;
         this.message = message;
         this.cancelled = false;
     }
     
     @Override
     public boolean isCancelled() {
         return cancelled;
     }
     
     @Override
     public void setCancelled(boolean cancelled) {
         this.cancelled = cancelled;
     }
     
     public Player getPlayer() {
         return player;
     }

     public String getMessage() {
         return message;
     }

     public void setMessage(String message) {
         this.message = message;
     }
 }
 

Example: Respecting Cancellation

 // Handler that respects cancellation
 eventBus.register(PlayerChatEvent.class, event -> {
     if (event.isCancelled()) {
         return; // Skip processing if already cancelled
     }
     broadcastMessage(event.getPlayer(), event.getMessage());
 }, Priority.NORMAL);
 

Example: Validation Handler

 // High priority handler that validates and may cancel
 eventBus.register(PlayerChatEvent.class, event -> {
     String message = event.getMessage();

     // Check for profanity
     if (containsProfanity(message)) {
         event.setCancelled(true);
         event.getPlayer().sendMessage("Please avoid profanity!");
         return;
     }

     // Check for spam
     if (isSpam(event.getPlayer(), message)) {
         event.setCancelled(true);
         event.getPlayer().sendMessage("Please don't spam!");
     }
 }, Priority.HIGH);
 

Example: Logging Cancelled Events

 // Logger that runs even for cancelled events
 eventBus.register(PlayerChatEvent.class, event -> {
     if (event.isCancelled()) {
         logger.info("Cancelled chat from {}: {}",
                     event.getPlayer().getName(),
                     event.getMessage());
     } else {
         logger.info("Chat from {}: {}",
                     event.getPlayer().getName(),
                     event.getMessage());
     }
 }, Priority.LOWEST); // Run last to log final state
 

Example: Un-cancelling Events

 // Admin override handler that can un-cancel events
 eventBus.register(PlayerChatEvent.class, event -> {
     Player player = event.getPlayer();

     // Admins can bypass cancellation
     if (event.isCancelled() && player.hasPermission("chat.bypass")) {
         event.setCancelled(false);
         logger.info("Admin {} bypassed chat cancellation", player.getName());
     }
 }, Priority.LOW); // Run after validation handlers
 

Since:

1.0

See Also:

• Event
• EventBus

Method Summary

Modifier and Type	Method	Description
boolean	isCancelled()	Checks if this event has been cancelled.
void	setCancelled(boolean cancelled)	Sets the cancellation state of this event.

Method Details

isCancelled

boolean isCancelled()

Checks if this event has been cancelled.

Returns:

true if the event is cancelled, false otherwise

setCancelled

void setCancelled(boolean cancelled)

Sets the cancellation state of this event.

Setting this to true typically indicates that the main action associated with this event should not proceed. However, handlers must explicitly check isCancelled() and decide how to respond.

Parameters:

cancelled - true to cancel the event, false to un-cancel it