Package org.spongepowered.api.command

Interface CommandCause

All Superinterfaces:

Contextual, Subject, SubjectProxy

@DoNotStore
public interface CommandCause
extends SubjectProxy

The CommandCause represents the Cause of a command, and also contains utility methods to obtain key information about said cause.

In line with causes used in events, you may assume that the Cause.root() (from cause()) is the direct invoker of the command, though it should also be noted that the invoker and intended target of a command may be different, which will be indicated by entries in the Cause.context()

It is very important to note that no object in the Cause is guaranteed to be a traditional "command source" - a plugin may invoke a command without pushing anything to the cause stack and thus the PluginContainer of the plugin in question will be the root of the cause.

In the case of a command being executed as a "proxy", such as a command block executing a command by virtue of an entity stepping on a pressure plate, the direct cause will be the command block. However, the player in question will also be present in the cause stack, allowing command providers to obtain richer information about the invocation of their command. This is inline with how Causes work in Sponge and its events, for more information about how Causes work, see the Cause and CauseStackManager javadocs and associated documentation.

The EventContext that is attached to Cause.context() may offer other indications as to how the command should be handled, in addition to using the provided cause stack:

• EventContextKeys.AUDIENCE, which indicates the where messages that should be sent back to the invoker should be sent to (typically messages indicating the status of the command execution);
• EventContextKeys.SUBJECT, which indicates the subject that should be subjected to any permission checks;
• EventContextKeys.LOCATION, which indicates the location that the command should be assumed to be executed around;
• EventContextKeys.ROTATION, which indicates the rotation that the command should assume the target has; and
• EventContextKeys.BLOCK_TARGET, which indicates the block that the command should take into account when executing.

This object acts as a Subject, and simply redirects all calls inherited by this interface to the subject returned by subject().

There are utility methods on this interface that provide hints as to what the implementation will select for different tasks, for example, the implementation will use the result of subject() for permission checks. Third party command consumers are under no obligation to use these utility methods as all methods obtain their information from the Cause.

No method on this interface, apart from cause(), should be taken a guarantee of what may be present, however, they indicate what typically would be of interest to command API consumers.

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static interface	CommandCause.Factory	Creates instances of the CommandCause.

Method Summary

Modifier and Type	Method	Description
default Optional<?>	after(Class<?> clazz)
default List<Object>	all()
default <T> List<T>	allOf(Class<T> target)
Audience	audience()	Gets the Audience that should be the target for any messages sent by the command (by default).
default Optional<?>	before(Class<?> clazz)
Cause	cause()	Gets the Cause of the command invocation.
default boolean	contains(Object object)
default boolean	containsType(Class<?> target)
default EventContext	context()
default Cause	contextCause()	Get the cause describing the current state of this subject.
static CommandCause	create()	Creates a CommandCause from the current Cause.
default <T> Optional<T>	first(Class<T> target)
default <T> Optional<T>	last(Class<T> target)
Optional<ServerLocation>	location()	Gets the ServerLocation that this command is associated with.
default List<Object>	noneOf(Class<?> ignoredClass)
default Object	root()
Optional<Vector3d>	rotation()	Gets the Vector3d rotation that this command is associated with.
void	sendMessage(Identified source, Component message)	Sends a message to the Audience as given by audience().
void	sendMessage(Identity source, Component message)	Sends a message to the Audience as given by audience().
void	sendMessage(Component message)	Sends a system message to the Audience as given by audience().
Subject	subject()	Get the Subject that will be selected for permission checks during command execution (by default).
Optional<BlockSnapshot>	targetBlock()	Returns the target block ServerLocation, if applicable.

Methods inherited from interface org.spongepowered.api.service.permission.SubjectProxy

associatedObject, asSubjectReference, containingCollection, friendlyIdentifier, hasPermission, hasPermission, hasPermission, identifier, isChildOf, isChildOf, isChildOf, isSubjectDataPersisted, option, option, option, parents, parents, parents, permissionValue, permissionValue, permissionValue, subjectData, transientSubjectData

Method Details

create

static CommandCause create()

Creates a CommandCause from the current Cause.

Returns:

The CommandCause

cause

Cause cause()

Gets the Cause of the command invocation.

Returns:

The cause of the invocation.

contextCause

default Cause contextCause()

Description copied from interface: Contextual

Get the cause describing the current state of this subject.

This is often not based on current game state, but rather the last known state of this subject. If a subject refers to a game object that is not active in the world, the cause may be a global cause.

Specified by:

contextCause in interface Contextual

Specified by:

contextCause in interface Subject

Specified by:

contextCause in interface SubjectProxy

Returns:

the active cause

context

default EventContext context()

Returns:

The event context

See Also:

• Cause.context()

root

default Object root()

Returns:

The root object cause for this cause

See Also:

• Cause.root()

first

default <T> Optional<T> first(Class<T> target)

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

See Also:

• Cause.first(Class)

last

default <T> Optional<T> last(Class<T> target)

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

See Also:

• Cause.last(Class)

before

default Optional<?> before(Class<?> clazz)

Parameters:

clazz - The class of the object

Returns:

The object

See Also:

• Cause.before(Class)

after

default Optional<?> after(Class<?> clazz)

Parameters:

clazz - The class to type check

Returns:

The object after, if available

See Also:

• Cause.after(Class)

containsType

default boolean containsType(Class<?> target)

Parameters:

target - The object to check if it is contained

Returns:

True if the object is contained within this cause

See Also:

• Cause.contains(Object)

contains

default boolean contains(Object object)

Parameters:

object - The object to check if it is contained

Returns:

True if the object is contained within this cause

See Also:

• Cause.contains(Object)

allOf

default <T> List<T> allOf(Class<T> target)

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

See Also:

• Cause.allOf(Class)

noneOf

default List<Object> noneOf(Class<?> ignoredClass)

Parameters:

ignoredClass - The class of object types to ignore

Returns:

The list of objects not an instance of the provided class

See Also:

• Cause.noneOf(Class)

all

default List<Object> all()

Returns:

An immutable list of all the causes

See Also:

• Cause.all()

subject

Subject subject()

Get the Subject that will be selected for permission checks during command execution (by default).

The Subject will be selected in the following way from the Cause in cause():

• The EventContextKeys.SUBJECT, if any
• The first Subject in the Cause
• The SystemSubject if no subject exists within the cause

This subject may present a different view of default context than calls to Subject methods directly on this cause.

Note: while it might be tempting to use this as the invoker of the command, the Cause.root() and this might be different. Command executors should generally use the root of the Cause as the target of their command.

Specified by:

subject in interface SubjectProxy

Returns:

The Subject responsible, if any.

audience

Audience audience()

Gets the Audience that should be the target for any messages sent by the command (by default).

The Audience will be selected in the following way from the Cause in cause():

• The EventContextKeys.AUDIENCE, if any
• An audience containing the first Audience in the Cause
• The SystemSubject Audience

Note that this returns a Audience and it may not what may be thought of as a traditional entity executing the command. For the object that invoked the command, check the Cause.root() of the cause().

Returns:

The Audience to send any messages to.

location

Optional<ServerLocation> location()

Gets the ServerLocation that this command is associated with.

The following are checked in order:

• The EventContextKeys.LOCATION, if any
• targetBlock()
• the location of the first locatable in the Cause

Returns:

The ServerLocation, if it exists

rotation

Optional<Vector3d> rotation()

Gets the Vector3d rotation that this command is associated with.

The following are checked in order:

• The EventContextKeys.ROTATION, if any
• the rotation of the first Entity in the Cause

Returns:

The Vector3d rotation, if it exists

targetBlock

Optional<BlockSnapshot> targetBlock()

Returns the target block ServerLocation, if applicable.

The following are checked in order:

• The EventContextKeys.BLOCK_TARGET, if any
• The first BlockSnapshot in the Cause

Returns:

The BlockSnapshot if applicable, or an empty optional.

sendMessage

void sendMessage(Component message)

Sends a system message to the Audience as given by audience().

Parameters:

message - The message to send

See Also:

• Audience.sendMessage(Component)

sendMessage

void sendMessage(Identified source,
 Component message)

Sends a message to the Audience as given by audience().

Parameters:

source - The Identified to send a message from.

message - The message to send.

See Also:

• Audience.sendMessage(Identified, Component)

sendMessage

void sendMessage(Identity source,
 Component message)

Sends a message to the Audience as given by audience().

Parameters:

source - The Identity to send a message from.

message - The message to send.

See Also:

• Audience.sendMessage(Identity, Component)