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 Detail

      • 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:
        EventContextKeys

      • 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:
        EventContextKeys

      • 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:
        EventContextKeys

      • 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:
        EventContextKeys

      • 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:
        EventContextKeys

      • 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:
        EventContextKeys