Package io.artificial.enchantments.internal

Class EffectDispatchSpine

java.lang.Object

io.artificial.enchantments.internal.EffectDispatchSpine

public final class EffectDispatchSpine
extends Object

Central dispatch spine for all enchantment effects.

This class is the single unified coordinator that powers both:

• Typed callbacks - direct invocation of EnchantmentEffectHandler methods
• Event bus - dispatch of EnchantEffectEvent subclasses to registered listeners

Both paths flow through this spine to ensure:

• Single point of validation and calculation
• No duplicate effect execution
• Consistent cancellation propagation
• Thread-safe dispatch via FoliaScheduler

Processing order:

1. Calculate scaled value using enchantment's LevelScaling
2. Create appropriate EffectContext via ContextFactory
3. Fire typed callback path (if handler exists)
4. Check cancellation - stop if cancelled
5. Fire event bus path (if listeners registered)
6. Check cancellation after bus

See Also:

• TypedCallbackDispatcher
• EventBusDispatcher
• ContextFactory

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static enum	EffectDispatchSpine.DispatchEventType	Enumeration of all dispatchable event types.

Constructor Summary

Constructors

Constructor	Description
EffectDispatchSpine(@NotNull FoliaScheduler scheduler, @NotNull EnchantmentEventBus eventBus)	Creates a new EffectDispatchSpine with the given components.
EffectDispatchSpine(@NotNull FoliaScheduler scheduler, @NotNull EnchantmentEventBus eventBus, EffectExecutionContext.ExecutionMode executionMode)	Creates a new EffectDispatchSpine with the given components and execution mode.

Method Summary

Modifier and Type	Method	Description
boolean	dispatch(@NotNull EnchantmentDefinition enchantment, int level, @NotNull org.bukkit.event.Event bukkitEvent, @Nullable org.bukkit.inventory.EquipmentSlot slot, @NotNull EffectDispatchSpine.DispatchEventType eventType)	Dispatches an enchantment effect through both callback and event bus paths.
@NotNull ContextFactory	getContextFactory()	Returns the ContextFactory for creating effect contexts.
EffectExecutionContext.ExecutionMode	getExecutionMode()	Gets the current execution mode.
@NotNull FoliaScheduler	getScheduler()	Returns the FoliaScheduler for scheduling tasks.
boolean	isShutdown()	Check if the spine has been shut down.
void	setExecutionMode(EffectExecutionContext.ExecutionMode mode)	Sets the execution mode for effect handler failures.
void	shutdown()	Shuts down the dispatch spine, preventing further dispatches.

Methods inherited from class java.lang.Object

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

Constructor Details

EffectDispatchSpine

public EffectDispatchSpine(@NotNull
 @NotNull FoliaScheduler scheduler,
 @NotNull
 @NotNull EnchantmentEventBus eventBus)

Creates a new EffectDispatchSpine with the given components.

Defaults to LENIENT execution mode where exceptions in effect handlers are logged but do not prevent other handlers from executing.

Parameters:

scheduler - the folia scheduler for thread-safe dispatch

eventBus - the event bus for dispatching events to listeners

EffectDispatchSpine

public EffectDispatchSpine(@NotNull
 @NotNull FoliaScheduler scheduler,
 @NotNull
 @NotNull EnchantmentEventBus eventBus,
 @NotNull
 EffectExecutionContext.ExecutionMode executionMode)

Creates a new EffectDispatchSpine with the given components and execution mode.

Parameters:

scheduler - the folia scheduler for thread-safe dispatch

eventBus - the event bus for dispatching events to listeners

executionMode - the execution mode (LENIENT or STRICT)

Method Details

dispatch

public boolean dispatch(@NotNull
 @NotNull EnchantmentDefinition enchantment,
 int level,
 @NotNull
 @NotNull org.bukkit.event.Event bukkitEvent,
 @Nullable
 @Nullable org.bukkit.inventory.EquipmentSlot slot,
 @NotNull
 @NotNull EffectDispatchSpine.DispatchEventType eventType)

Dispatches an enchantment effect through both callback and event bus paths.

This is the main entry point for effect dispatch. It coordinates:

• Value calculation via LevelScaling
• Context creation
• Typed callback invocation
• Event bus dispatch
• Cancellation handling

Parameters:

enchantment - the enchantment definition

level - the enchantment level

bukkitEvent - the underlying Bukkit event

slot - the equipment slot where the enchantment is applied (may be null for non-equipment events)

eventType - the type of event being dispatched

Returns:

true if the effect was dispatched successfully, false if cancelled or error occurred

getScheduler

@NotNull
public @NotNull FoliaScheduler getScheduler()

Returns the FoliaScheduler for scheduling tasks.

Returns:

the scheduler

getContextFactory

@NotNull
public @NotNull ContextFactory getContextFactory()

Returns the ContextFactory for creating effect contexts.

Returns:

the context factory

shutdown

public void shutdown()

Shuts down the dispatch spine, preventing further dispatches.

isShutdown

public boolean isShutdown()

Check if the spine has been shut down.

Returns:

true if shutdown

getExecutionMode

@NotNull
public EffectExecutionContext.ExecutionMode getExecutionMode()

Gets the current execution mode.

Returns:

the current execution mode (LENIENT or STRICT)

setExecutionMode

public void setExecutionMode(@NotNull
 EffectExecutionContext.ExecutionMode mode)

Sets the execution mode for effect handler failures.

In LENIENT mode (default), exceptions from effect handlers are logged but do not prevent other handlers from executing.

In STRICT mode, exceptions from effect handlers are logged and propagated to stop all further execution. This is useful for debugging.

Parameters:

mode - the execution mode to set