Replace the CommandSource with a CommandCause

* Split out notion of a console to the Game object, which is a MessageReceiver & Subject named SystemSubject
* Make sure JDs are consistent with causes, remove anything to do with CommandSources
* Renamed Nameable -> Nameable.Translatable.
* Most objects now inherit Subject, MessageReceiver and Nameable.
* Introduce the notion of the CommandCause, which is effectively a wrapper class that provides simple methods to get common entities from the cause. It is also a superinterface of CommandContext.
* Add ExecuteCommandEvent.
* Update for the use of factories to remove any unchecked warnings.
* Update for CheckerFramework.

Author: dualspiral

src/main/java/org/spongepowered/api/Game.java

@@ -86,6 +86,14 @@ public interface Game {
      */
     Server getServer();
 
+    /**
+     * Gets the {@link SystemSubject}. Depending on the implementation, this
+     * may also represent the game console.
+     *
+     * @return The {@link SystemSubject}
+     */
+    SystemSubject getSystemSubject();
+
     /**
      * Returns if the {@link Client} is available for use. The result of this method is entirely
      * dependent on the implementation.

src/main/java/org/spongepowered/api/Server.java

@@ -24,13 +24,13 @@
  */
 package org.spongepowered.api;
 
-import org.spongepowered.api.command.source.CommandSource;
 import org.spongepowered.api.entity.living.player.Player;
 import org.spongepowered.api.profile.GameProfileManager;
 import org.spongepowered.api.resourcepack.ResourcePack;
 import org.spongepowered.api.scoreboard.Scoreboard;
 import org.spongepowered.api.text.Text;
 import org.spongepowered.api.text.channel.MessageChannel;
+import org.spongepowered.api.text.channel.MessageReceiver;
 import org.spongepowered.api.world.WorldManager;
 import org.spongepowered.api.world.chunk.ChunkTicketManager;
 import org.spongepowered.api.world.storage.ChunkLayout;
@@ -43,7 +43,7 @@
 /**
  * Represents a typical Minecraft Server.
  */
-public interface Server extends Engine, CommandSource {
+public interface Server extends Engine, MessageReceiver {
 
     /**
      * Gets the {@link WorldManager}.

src/main/java/org/spongepowered/api/Sponge.java

@@ -217,6 +217,16 @@ public static Server getServer() {
         return getGame().getServer();
     }
 
+    /**
+     * Gets the {@link SystemSubject} instance from the {@link Game} instance.
+     *
+     * @see Game#getSystemSubject() ()
+     * @return The system subject
+     */
+    public static SystemSubject getSystemSubject() {
+        return getGame().getSystemSubject();
+    }
+
     /**
      * Gets the {@link CauseStackManager} instance from the
      * {@link Game} instance.

…ed/api/command/source/CommandSource.java …org/spongepowered/api/SystemSubject.javasrc/main/java/org/spongepowered/api/command/source/CommandSource.java renamed to src/main/java/org/spongepowered/api/SystemSubject.java src/main/java/org/spongepowered/api/command/source/CommandSource.java renamed to src/main/java/org/spongepowered/api/SystemSubject.java

@@ -22,32 +22,22 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  * THE SOFTWARE.
  */
-package org.spongepowered.api.command.source;
+package org.spongepowered.api;
 
 import org.spongepowered.api.service.permission.Subject;
 import org.spongepowered.api.text.channel.MessageReceiver;
-import org.spongepowered.api.text.translation.locale.Locales;
-
-import java.util.Locale;
 
 /**
- * Something that traditionally executes commands, can receive messages and
- * can have permissions associated with them.
+ * Represents the "super user" of the game.
  *
- * <p>Examples of potential implementations include players, the server console,
- * Rcon clients, web-based clients, command blocks, and so on.</p>
+ * <p>The {@link SystemSubject} is intended to be the {@link Subject} that
+ * represents server actions. This subject may represent an interaction
+ * through a console.</p>
  *
- * <p>Note that while this source is provided, it is done so as a courtesy to
- * provide an indication as to what will both receive messages and act as a
- * permission {@link Subject}.</p>
+ * <p>This object is also a {@link MessageReceiver}. Any message sent here
+ * should be directed to a system visible location, such as a log or a
+ * console.</p>
  */
-public interface CommandSource extends MessageReceiver, Subject {
-
-    /**
-     * Gets the name identifying this command source.
-     *
-     * @return The name of this command source
-     */
-    String getName();
+public interface SystemSubject extends Subject, MessageReceiver {
 
 }

src/main/java/org/spongepowered/api/block/entity/CommandBlock.java

@@ -24,18 +24,20 @@
  */
 package org.spongepowered.api.block.entity;
 
-import org.spongepowered.api.command.source.CommandSource;
 import org.spongepowered.api.data.Keys;
 import org.spongepowered.api.data.value.OptionalValue;
 import org.spongepowered.api.data.value.Value;
+import org.spongepowered.api.service.permission.Subject;
 import org.spongepowered.api.text.Text;
+import org.spongepowered.api.text.channel.MessageReceiver;
+import org.spongepowered.api.util.Nameable;
 
 import java.util.Optional;
 
 /**
  * Represents a Command Block.
  */
-public interface CommandBlock extends BlockEntity, CommandSource {
+public interface CommandBlock extends BlockEntity, Subject, MessageReceiver, Nameable {
 
     /**
      * Executes the currently stored command.

src/main/java/org/spongepowered/api/block/entity/Sign.java

@@ -24,15 +24,16 @@
  */
 package org.spongepowered.api.block.entity;
 
-import org.spongepowered.api.command.source.CommandSource;
 import org.spongepowered.api.data.Keys;
 import org.spongepowered.api.data.value.ListValue;
+import org.spongepowered.api.service.permission.Subject;
 import org.spongepowered.api.text.Text;
+import org.spongepowered.api.util.Nameable;
 
 /**
  * Represents a sign.
  */
-public interface Sign extends BlockEntity, CommandSource {
+public interface Sign extends BlockEntity, Subject, Nameable {
 
     /**
      * Gets the {@link org.spongepowered.api.data.value.ListValue.Mutable} of {@link Text} for the {@link Sign}

src/main/java/org/spongepowered/api/command/Command.java

@@ -29,11 +29,11 @@
 import org.spongepowered.api.command.exception.CommandException;
 import org.spongepowered.api.command.parameter.CommandContext;
 import org.spongepowered.api.command.parameter.Parameter;
-import org.spongepowered.api.command.source.CommandSource;
 import org.spongepowered.api.event.cause.Cause;
 import org.spongepowered.api.event.cause.EventContext;
 import org.spongepowered.api.event.cause.EventContextKeys;
 import org.spongepowered.api.plugin.PluginContainer;
+import org.spongepowered.api.service.permission.Subject;
 import org.spongepowered.api.text.Text;
 import org.spongepowered.api.util.ResettableBuilder;
 import org.spongepowered.api.world.Location;
@@ -63,10 +63,10 @@
  * as required. This <em>may</em> enable the use of client side command
  * completions, if the implementation is equipped to do so.</p>
  *
- * <p>Commands in Sponge are provided with a {@link Cause}, which explains
- * who <strong>directly</strong> invoked the command. In line with causes used
- * in events, you may assume that the {@link Cause#root()} is the
- * <strong>intended</strong> direct invoker.</p>
+ * <p>Commands in Sponge are provided with a {@link CommandCause}, which
+ * provides a {@link Cause} explains who <strong>directly</strong> invoked the
+ * command. In line with causes used in events, you may assume that the
+ * {@link Cause#root()} is the <strong>intended</strong> direct invoker.</p>
  *
  * <p>It is <em>very</em> important to note that no object in the {@link Cause}
  * is guaranteed to be a traditional "command source" - a plugin may invoke a
@@ -86,12 +86,16 @@
  * be handled, in addition to using the provided cause stack:</p>
  *
  * <ul>
- *     <li>{@link EventContextKeys#MESSAGE_CHANNEL}, which indicates the
+ *     <li>{@link EventContextKeys#MESSAGE_TARGET}, 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);
- *     and,</li>
+ *     </li>
  *     <li>{@link EventContextKeys#SUBJECT}, which indicates the subject that
- *     should be subjected to any permission checks.</li>
+ *     should be subjected to any permission checks;</li>
+ *     <li>{@link EventContextKeys#LOCATION}, which indicates the location that
+ *     the command should be assumed to be executed around; and,</li>
+ *     <li>{@link EventContextKeys#BLOCK_TARGET}, which indicates the block that
+ *     the command should take into account when executing.</li>
  * </ul>
  */
 public interface Command {
@@ -111,31 +115,31 @@ static Builder builder() {
      * <p>The implementing class must perform the necessary permission
      * checks.</p>
      *
-     * @param cause The {@link Cause} of the invocation of command
+     * @param cause The {@link CommandCause} of the invocation of command
      * @param arguments The raw arguments for this command
      * @return The result of a command being processed
      * @throws CommandException Thrown on a command error
      */
-    CommandResult process(Cause cause, String arguments) throws CommandException;
+    CommandResult process(CommandCause cause, String arguments) throws CommandException;
 
     /**
      * Gets a list of suggestions based on input.
      *
      * <p>If a suggestion is chosen by the user, it will replace the last
      * word.</p>
      *
-     * @param cause The {@link Cause} of the command
+     * @param cause The {@link CommandCause} of the command
      * @param arguments The arguments entered up to this point
      * @param targetPosition The position the source is looking at when
      *     performing tab completion
      * @return A list of suggestions
      * @throws CommandException Thrown if there was a parsing error
      */
-    List<String> getSuggestions(Cause cause, String arguments, @Nullable Location targetPosition) throws CommandException;
+    List<String> getSuggestions(CommandCause cause, String arguments, @Nullable Location targetPosition) throws CommandException;
 
     /**
      * Test whether this command can probably be executed given this
-     * {@link Cause} and {@link CommandSource}.
+     * {@link Cause}.
      *
      * <p>If implementations are unsure if the command can be executed by
      * the source, {@code true} should be returned. Return values of this method
@@ -145,7 +149,7 @@ static Builder builder() {
      * @param cause The {@link Cause} to check
      * @return Whether this command will execute
      */
-    boolean canExecute(Cause cause);
+    boolean canExecute(CommandCause cause);
 
     /**
      * Gets a short one-line description of this command.
@@ -155,7 +159,7 @@ static Builder builder() {
      * @param cause The {@link Cause} of the help request
      * @return A description
      */
-    Optional<Text> getShortDescription(Cause cause);
+    Optional<Text> getShortDescription(CommandCause cause);
 
     /**
      * Gets a longer formatted help message about this command.
@@ -172,7 +176,7 @@ static Builder builder() {
      * @param cause The {@link Cause} of the help request
      * @return A help text
      */
-    Optional<Text> getHelp(Cause cause);
+    Optional<Text> getHelp(CommandCause cause);
 
     /**
      * Gets the usage string of this command.
@@ -185,7 +189,7 @@ static Builder builder() {
      * @param cause The {@link Cause} of the help request
      * @return A usage string
      */
-    Text getUsage(Cause cause);
+    Text getUsage(CommandCause cause);
 
     /**
      * A {@link Command} that has distinct steps for parsing arguments and
@@ -208,13 +212,13 @@ interface Parameterized extends Command, CommandExecutor {
          * @param arguments The argument {@link String}
          * @return The {@link CommandContext}
          */
-        CommandContext parseArguments(Cause cause, String arguments);
+        CommandContext parseArguments(CommandCause cause, String arguments);
 
         /**
          * Processes the command by parsing the arguments, then
          * executing command based on these arguments.
          *
-         * <p>By default, this will call {@link #parseArguments(Cause, String)}
+         * <p>By default, this will call {@link #parseArguments(CommandCause, String)}
          * and pass the resulting {@link CommandContext} to
          * {@link #execute(CommandContext)}.</p>
          *
@@ -223,7 +227,7 @@ interface Parameterized extends Command, CommandExecutor {
          * @return The result of a command being processed
          * @throws CommandException Thrown on a command error
          */
-        default CommandResult process(Cause cause, String arguments) throws CommandException {
+        default CommandResult process(CommandCause cause, String arguments) throws CommandException {
             return execute(parseArguments(cause, arguments));
         }
 
@@ -362,7 +366,7 @@ default Builder parameters(Iterable<Parameter> parameters) {
          *      relevant description based on the supplied {@link Cause}
          * @return This builder, for chaining
          */
-        Builder setExtendedDescription(Function<Cause, Optional<Text>> extendedDescriptionFunction);
+        Builder setExtendedDescription(Function<CommandCause, Optional<Text>> extendedDescriptionFunction);
 
         /**
          * Provides the description for this command.
@@ -382,18 +386,17 @@ default Builder setExtendedDescription(@Nullable Text extendedDescription) {
 
         /**
          * Provides a simple description for this command, typically no more
-         * than one line, which is dependent on the {@link Cause} and the
-         * responsible {@link CommandSource} that requests it.
+         * than one line, which is dependent on the {@link Cause} that requests
+         * it.
          *
          * <p>Fuller descriptions should be provided through
          * {@link #setExtendedDescription(Function)}</p>
          *
          * @param descriptionFunction A function that provides a relevant
-         *      description based on the supplied {@link Cause} and
-         *      {@link CommandSource}
+         *      description based on the supplied {@link Cause}
          * @return This builder, for chaining
          */
-        Builder setShortDescription(Function<Cause, Optional<Text>> descriptionFunction);
+        Builder setShortDescription(Function<CommandCause, Optional<Text>> descriptionFunction);
 
         /**
          * Provides a simple description for this command, typically no more
@@ -413,8 +416,9 @@ default Builder setShortDescription(@Nullable Text description) {
         }
 
         /**
-         * The permission that a {@link CommandSource} requires to run this
-         * command, or {@code null} if no permission is required.
+         * The permission that the responsible {@link Subject} in the given
+         * {@link Cause} requires to run this command, or {@code null} if no
+         * permission is required.
          *
          * <p>For more control over whether a command can be executed, use
          * {@link #setExecutionRequirements(Predicate)}. However, note that
@@ -423,7 +427,7 @@ default Builder setShortDescription(@Nullable Text description) {
          * during execution.</p>
          *
          * <p>Any permission checks set here will be performed during the
-         * {@link Command#canExecute(Cause)}.</p>
+         * {@link Command#canExecute(CommandCause)}.</p>
          *
          * <p>Calling this repeatedly will not add additional permission
          * checks, instead replacing the permission check. If multiple
@@ -438,21 +442,21 @@ default Builder setShortDescription(@Nullable Text description) {
 
         /**
          * Sets a function that determines what is required of the provided
-         * {@link Cause} and {@link CommandSource} before this command executes.
+         * {@link Cause} before this command executes.
          *
          * <p>Any requirements here are in addition to the permission check
          * from {@link #setPermission(String)}</p>
          *
          * <p>Any requirements set here will be performed during the
-         * {@link Command#canExecute(Cause)}.</p>
+         * {@link Command#canExecute(CommandCause)}.</p>
          *
          * <p>Calling this repeatedly will not add additional checks, instead
          * replacing the previous requirements.</p>
          *
          * @param executionRequirements A function that sets the
          * @return This builder, for chaining
          */
-        Builder setExecutionRequirements(@Nullable Predicate<Cause> executionRequirements);
+        Builder setExecutionRequirements(@Nullable Predicate<CommandCause> executionRequirements);
 
         /**
          * Builds this command, creating a {@link Command.Parameterized}