Package org.spongepowered.api.event

Interface CauseStackManager

public interface CauseStackManager
Provides an interface into the system managing the cause and contextual information for events being thrown. This allows plugins to attach more contextual information to events which may be triggered from their api interactions.

For example a plugin may wish to push a player into the cause stack before spawning an entity to expose to any plugin listening for SpawnEntityEvents that the player is the reason that the entity was spawned.

This system will automatically handle associating a plugin with actions performed inside of event listeners, command executors, and scheduled tasks.

  • Method Details

    • currentCause

      Cause currentCause()
      Gets the current Cause object from the current cause stack.
      Returns:
      A cause of the current stack.

    • currentContext

      EventContext currentContext()
      Gets an EventContext object on the current contextual information.
      Returns:
      The current event context

    • pushCause

      CauseStackManager pushCause(Object obj)
      Pushes an object to the current cause stack which will associate it with all events through from api actions until it is popped off again.
      Parameters:
      obj - The object to push to the stack
      Returns:
      The cause stack manager, for chaining

    • popCause

      Object popCause()
      Pops the most recently pushed cause object off of the stack and returns it.
      Returns:
      The last pushed object

    • popCauses

      void popCauses(int n)
      Pops the most recently n pushed cause objects off of the stack.
      Parameters:
      n - The number of causes to pop

    • peekCause

      Object peekCause()
      Retrieves but does not remove the most recently pushed cause object.
      Returns:
      The last pushed object

    • pushCauseFrame

      CauseStackManager.StackFrame pushCauseFrame()
      Pushes a frame of the current cause stack and context state.
      Returns:
      A handle for the frame which must be passed back to pop the frame from the stack

    • popCauseFrame

      void popCauseFrame(CauseStackManager.StackFrame handle)
      Replaces the current cause stack and context with the cause frame at the top of the frame stack.

      The frame handle is required to ensure that frames are popped of in order and are not left in the stack. If an attempt is made to pop a frame which is not the head of the frame stack then an error will be thrown as this indicates that a frame was not popped properly.

      Parameters:
      handle - The frame handle to pop

    • addContext

      <T> CauseStackManager addContext(EventContextKey<T> key, T value)
      Adds the given object to the current context under the given key.
      Type Parameters:
      T - The type of the value stored with the event context key
      Parameters:
      key - The context key
      value - The object
      Returns:
      The cause stack manager, for chaining
      See Also:

    • addContext

      default <T> CauseStackManager addContext(EventContextKey<T> key, Supplier<? extends T> value)
      Adds the given object to the current context under the given key.
      Type Parameters:
      T - The type of the value stored with the event context key
      Parameters:
      key - The context key
      value - The object
      Returns:
      The cause stack manager, for chaining
      See Also:

    • addContext

      default <T> CauseStackManager addContext(Supplier<EventContextKey<T>> key, T value)
      Adds the given object to the current context under the given key.
      Type Parameters:
      T - The type of the value stored with the event context key
      Parameters:
      key - The context key
      value - The object
      Returns:
      The cause stack manager, for chaining
      See Also:

    • addContext

      default <T> CauseStackManager addContext(Supplier<EventContextKey<T>> key, Supplier<? extends T> value)
      Adds the given object to the current context under the given key.
      Type Parameters:
      T - The type of the value stored with the event context key
      Parameters:
      key - The context key
      value - The object
      Returns:
      The cause stack manager, for chaining
      See Also:

    • context

      <T> Optional<T> context(EventContextKey<T> key)
      Gets the context value with the given key.
      Type Parameters:
      T - The type of the value stored with the event context key
      Parameters:
      key - The context key
      Returns:
      The context object, if present

    • context

      default <T> Optional<T> context(Supplier<EventContextKey<T>> key)
      Gets the context value with the given key.
      Type Parameters:
      T - The type of the value stored with the event context key
      Parameters:
      key - The context key
      Returns:
      The context object, if present

    • requireContext

      default <T> T requireContext(EventContextKey<T> key)
      Gets the context value with the given key.

      If the key is not available, NoSuchElementException will be thrown.

      Type Parameters:
      T - The type of the value stored with the event context key
      Parameters:
      key - The context key
      Returns:
      The context object, if present

    • requireContext

      default <T> T requireContext(Supplier<EventContextKey<T>> key)
      Gets the context value with the given key.

      If the key is not available, NoSuchElementException will be thrown.

      Type Parameters:
      T - The type of the value stored with the event context key
      Parameters:
      key - The context key
      Returns:
      The context object, if present

    • removeContext

      <T> Optional<T> removeContext(EventContextKey<T> key)
      Removes the given context key from the current context.
      Type Parameters:
      T - The type of the value stored with the event context key
      Parameters:
      key - The key to clear
      Returns:
      The existing context value, if it was present
      See Also:

    • removeContext

      default <T> Optional<T> removeContext(Supplier<EventContextKey<T>> key)
      Removes the given context key from the current context.
      Type Parameters:
      T - The type of the value stored with the event context key
      Parameters:
      key - The key to clear
      Returns:
      The existing context value, if it was present
      See Also: