Package org.spongepowered.api.event

Class Cause

java.lang.Object
org.spongepowered.api.event.Cause
All Implemented Interfaces:
Iterable<Object>
@DoNotStore public final class Cause extends Object implements Iterable<Object>
A cause represents the reason or initiator of an event.

For example, if a block of sand is placed where it drops, the block of sand would create a falling sand entity, which then would place another block of sand. The block place event for the final block of sand would have the cause chain of the block of sand -> falling sand entity.

It is not possible to accurately describe the chain of causes in all scenarios so a best effort approach is generally acceptable. For example, a player might press a lever, activating a complex Redstone circuit, which would then launch TNT and cause the destruction of some blocks, but tracing this event would be too complicated and thus may not be attempted.

  • Method Details

    • builder

      public static Cause.Builder builder()
      Creates a new Cause.Builder to make a new Cause.
      Returns:
      The new builder

    • of

      public static Cause of(EventContext ctx, Object cause)
      Constructs a new cause with the specified event context and cause.
      Parameters:
      ctx - The event context
      cause - The direct object cause
      Returns:
      The constructed cause

    • of

      public static Cause of(EventContext ctx, Object cause, Object... causes)
      Constructs a new cause with the specified event context and causes.
      Parameters:
      ctx - The event context
      cause - The direct object cause
      causes - Other associated causes
      Returns:
      The built cause

    • of

      public static Cause of(EventContext ctx, Iterable<Object> iterable)
      Constructs a new cause with the specified event context and causes.
      Parameters:
      ctx - The event context
      iterable - The associated causes
      Returns:
      The built cause

    • context

      public EventContext context()
      Gets the event context relating to this cause.
      Returns:
      The event context

    • root

      public Object root()
      Gets the root Object of this cause.
      Returns:
      The root object cause for this cause

    • first

      public <T> Optional<T> first(Class<T> target)
      Gets the first T object of this Cause, if available.
      Type Parameters:
      T - The type of object being queried for
      Parameters:
      target - The class of the target type
      Returns:
      The first element of the type, if available

    • last

      public <T> Optional<T> last(Class<T> target)
      Gets the last object instance of the Class of type T.
      Type Parameters:
      T - The type of object being queried for
      Parameters:
      target - The class of the target type
      Returns:
      The last element of the type, if available

    • before

      public Optional<?> before(Class<?> clazz)
      Gets the object immediately before the object that is an instance of the Class passed in.
      Parameters:
      clazz - The class of the object
      Returns:
      The object

    • after

      public Optional<?> after(Class<?> clazz)
      Gets the object immediately after the object that is an instance of the Class passed in.
      Parameters:
      clazz - The class to type check
      Returns:
      The object after, if available

    • containsType

      public boolean containsType(Class<?> target)
      Returns whether the target class matches any object of this Cause.
      Parameters:
      target - The class of the target type
      Returns:
      True if found, false otherwise

    • contains

      public boolean contains(Object object)
      Checks if this cause contains of any of the provided Object. This is the equivalent to checking based on equals(Object) for each object in this cause.
      Parameters:
      object - The object to check if it is contained
      Returns:
      True if the object is contained within this cause

    • allOf

      public <T> List<T> allOf(Class<T> target)
      Gets an ImmutableList of all objects that are instances of the given Class type T.
      Type Parameters:
      T - The type of objects to query for
      Parameters:
      target - The class of the target type
      Returns:
      An immutable list of the objects queried

    • noneOf

      public List<Object> noneOf(Class<?> ignoredClass)
      Gets an immutable List with all object causes that are not instances of the provided Class.
      Parameters:
      ignoredClass - The class of object types to ignore
      Returns:
      The list of objects not an instance of the provided class

    • all

      public List<Object> all()
      Gets an List of all causes within this Cause.
      Returns:
      An immutable list of all the causes

    • with

      public Cause with(Object additional)
      Creates a new Cause where the objects are added at the end of the cause array of objects.
      Parameters:
      additional - The additional object to add
      Returns:
      The new cause

    • with

      public Cause with(Object additional, Object... additionals)
      Creates a new Cause where the objects are added at the end of the cause array of objects.
      Parameters:
      additional - The additional object to add
      additionals - The remaining objects to add
      Returns:
      The new cause

    • with

      public Cause with(Iterable<Object> iterable)
      Creates a new Cause where the objects are added at the end of the cause array of objects.
      Parameters:
      iterable - The additional objects
      Returns:
      The new cause

    • with

      public Cause with(Cause cause)
      Merges this cause with the other cause.
      Parameters:
      cause - The cause to merge with this
      Returns:
      The new merged cause

    • iterator

      public Iterator<Object> iterator()
      Specified by:
      iterator in interface Iterable<Object>

    • equals

      public boolean equals(@Nullable Object object)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object