CommandController and Method/Annotation based Command delegation

So as we all know, a LONG time ago Bukkit swapped it's old Event handling system for a more flexible one, based off of runtime registration of methods through the use of the @EventHandler annotation. Personally, I loved this system. It was more flexible, nicer to write, and didn't require you to create a whole new class if you only wanted to listen for a single event. You could even write a one-class plugin if you liked.

However, what I still don't like and have never liked is Bukkit's way of handling commands. I dislike having to register commands and ALL of their attributes in the plugin YAML file. I find it unwieldy, and I've seen a lot of new programmers confused by it. Furthermore, I don't like the onCommand system. I'm not sure why, but I just don't. Perhaps its because I can't minimize individual commands in Eclipse unless I write entirely new classes to handle every single command.

So what I've done is written a small class that you can chuck into any plugin to circumvent this. When the plugin enables, call the registerCommands method with the plugin and object to register for (EXACTLY the way that you call the registerEvents method for events), and that's all. Beyond that, all you'll need to do is make sure that you've set up the handler class properly, but again, it is extremely similar to the way that event listeners are set up.

Here's the actual class:

Code:java

package com.amoebaman.kitmaster.utilities;
 
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.reflect.Method;
import java.util.HashMap;
 
import org.bukkit.ChatColor;
import org.bukkit.command.Command;
import org.bukkit.command.CommandExecutor;
import org.bukkit.command.CommandSender;
import org.bukkit.command.ConsoleCommandSender;
import org.bukkit.entity.Player;
import org.bukkit.plugin.java.JavaPlugin;
 
import com.google.common.collect.Lists;
 
public class CommandController implements CommandExecutor{
 
    private final static HashMap<Command, Object> handlers = new HashMap<Command, Object>();
    private final static HashMap<Command, Method> methods = new HashMap<Command, Method>();
    private final static HashMap<String, SubCommand> subCommands = new HashMap<String, SubCommand>();
    private final static HashMap<String, Object> subHandlers = new HashMap<String, Object>();
    private final static HashMap<String, Method> subMethods = new HashMap<String, Method>();
 
    /**
     * Registers all command handlers and subcommand handlers in a class, matching them with their corresponding commands and subcommands registered to the specified plugin.
     * @param plugin The plugin whose commands will be considered for registration
     * @param handler An instance of the class whose methods will be considered for registration
     */
    public static void registerCommands(JavaPlugin plugin, Object handler){
 
        for(Method method : handler.getClass().getMethods()){
            Class<?>[] params = method.getParameterTypes();
            if(params.length == 2 && CommandSender.class.isAssignableFrom(params[0]) && String[].class.equals(params[1])){
 
                if(isCommandHandler(method)){
                    CommandHandler annotation = method.getAnnotation(CommandHandler.class);
                    if(plugin.getCommand(annotation.name()) != null){
                        plugin.getCommand(annotation.name()).setExecutor(new CommandController());
                        if(!(annotation.aliases().equals(new String[]{""})))
                            plugin.getCommand(annotation.name()).setAliases(Lists.newArrayList(annotation.aliases()));
                        if(!annotation.description().equals(""))
                            plugin.getCommand(annotation.name()).setDescription(annotation.description());
                        if(!annotation.usage().equals(""))
                            plugin.getCommand(annotation.name()).setUsage(annotation.usage());
                        if(!annotation.permission().equals(""))
                            plugin.getCommand(annotation.name()).setPermission(annotation.permission());
                        if(!annotation.permissionMessage().equals(""))
                            plugin.getCommand(annotation.name()).setPermissionMessage(ChatColor.RED + annotation.permissionMessage());
                        handlers.put(plugin.getCommand(annotation.name()), handler);
                        methods.put(plugin.getCommand(annotation.name()), method);
                    }
                }
 
                if(isSubCommandHandler(method)){
                    SubCommandHandler annotation = method.getAnnotation(SubCommandHandler.class);
                    if(plugin.getCommand(annotation.parent()) != null){
                        plugin.getCommand(annotation.parent()).setExecutor(new CommandController());
                        SubCommand subCommand = new SubCommand(plugin.getCommand(annotation.parent()), annotation.name());
                        subCommand.permission = annotation.permission();
                        subCommand.permissionMessage = annotation.permissionMessage();
                        subCommands.put(subCommand.toString(), subCommand);
                        subHandlers.put(subCommand.toString(), handler);
                        subMethods.put(subCommand.toString(), method);
                    }
                }
            }
        }
    }
 
    /**
     * @author AmoebaMan
     * An annotation interface that may be attached to a method to designate it as a command handler.
     * When registering a handler with this class, only methods marked with this annotation will be considered for command registration.
     */
    @Retention(RetentionPolicy.RUNTIME)
    public static @interface CommandHandler {
        String name();
        String[] aliases() default { "" };
        String description() default "";
        String usage() default "";
        String permission() default "";
        String permissionMessage() default "You do not have permission to use that command";
    }
 
    /**
     * Tests if a method is a command handler
     */
    private static boolean isCommandHandler(Method method){
        return method.getAnnotation(CommandHandler.class) != null;
    }
 
    /**
     * @author AmoebaMan
     * An annotation interface that may be attached to a method to designate it as a subcommand handler.
     * When registering a handler with this class, only methods marked with this annotation will be considered for subcommand registration.
     */
    @Retention(RetentionPolicy.RUNTIME)
    public static @interface SubCommandHandler {
        String parent();
        String name();
        String permission() default "";
        String permissionMessage() default "You do not have permission to use that command";
    }
 
    /**
     * Tests if a method is a subcommand handler
     */
    private static boolean isSubCommandHandler(Method method){
        return method.getAnnotation(SubCommandHandler.class) != null;
    }
 
    /**
     * A class for representing subcommands
     */
    private static class SubCommand{
        public final Command superCommand;
        public final String subCommand;
        public String permission;
        public String permissionMessage;
        public SubCommand(Command superCommand, String subCommand){
            this.superCommand = superCommand;
            this.subCommand = subCommand.toLowerCase();
        }
        public boolean equals(Object x){ return toString().equals(x.toString()); }
        public String toString(){ return (superCommand.getName() + " " + subCommand).trim(); }
    }
 
    /**
     * This is the method that "officially" processes commands, but in reality it will always delegate responsibility to the handlers and methods assigned to the command or subcommand
     * Beyond checking permissions, checking player/console sending, and invoking handlers and methods, this method does not actually act on the commands
     */
    public boolean onCommand(CommandSender sender, Command command, String label, String[] args){
        /*
         * If a subcommand may be present...
         */
        if(args.length > 0){
            /*
             * Get the subcommand given and the handler and method attached to it
             */
            SubCommand subCommand = new SubCommand(command, args[0]);
            subCommand = subCommands.get(subCommand.toString());
            /*
             * If and only if the subcommand actually exists...
             */
            if(subCommand != null){
                Object subHandler = subHandlers.get(subCommand.toString());
                Method subMethod = subMethods.get(subCommand.toString());
                /*
                 * If and only if both handler and method exist...
                 */
                if(subHandler != null && subMethod != null){
                    /*
                     * Reorder the arguments so we don't resend the subcommand
                     */
                    String[] subArgs = new String[args.length - 1];
                    for(int i = 1; i < args.length; i++)
                        subArgs[i - 1] = args[i];
                    /*
                     * If the method requires a player and the subcommand wasn't sent by one, don't continue
                     */
                    if(subMethod.getParameterTypes()[0].equals(Player.class) && !(sender instanceof Player)){
                        sender.sendMessage(ChatColor.RED + "This command requires a player sender");
                        return true;
                    }
                    /*
                     * If the method requires a console and the subcommand wasn't sent by one, don't continue
                     */
                    if(subMethod.getParameterTypes()[0].equals(ConsoleCommandSender.class) && !(sender instanceof ConsoleCommandSender)){
                        sender.sendMessage(ChatColor.RED + "This command requires a console sender");
                        return true;
                    }
                    /*
                     * If a permission is attached to this subcommand and the sender doens't have it, don't continue
                     */
                    if(!subCommand.permission.isEmpty() && !sender.hasPermission(subCommand.permission)){
                        sender.sendMessage(ChatColor.RED + subCommand.permissionMessage);
                        return true;
                    }
                    /*
                     * Try to process the command
                     */
                    try{ subMethod.invoke(subHandler, sender, args); }
                    catch(Exception e){
                        sender.sendMessage(ChatColor.RED + "An error occurred while trying to process the command");
                        e.printStackTrace(); 
                    }
                    return true;
                }
            }
        }
        /*
         * If a subcommand was successfully executed, the command will not reach this point
         * Get the handler and method attached to this command
         */
        Object handler = handlers.get(command);
        Method method = methods.get(command);
        /*
         * If and only if both handler and method exist...
         */
        if(handler != null && method != null){
            /*
             * If the method requires a player and the command wasn't sent by one, don't continue
             */
            if(method.getParameterTypes()[0].equals(Player.class) && !(sender instanceof Player)){
                sender.sendMessage(ChatColor.RED + "This command requires a player sender");
                return true;
            }
            /*
             * If the method requires a console and the command wasn't sent by one, don't continue
             */
            if(method.getParameterTypes()[0].equals(ConsoleCommandSender.class) && !(sender instanceof ConsoleCommandSender)){
                sender.sendMessage(ChatColor.RED + "This command requires a console sender");
                return true;
            }
            /*
             * Try to process the command
             */
            try{ method.invoke(handler, sender, args); }
            catch(Exception e){
                sender.sendMessage(ChatColor.RED + "An error occurred while trying to process the command");
                e.printStackTrace(); 
            }
        }
        /*
         * Otherwise we have to fake not recognising the command
         */
        else
            sender.sendMessage("Unknown command. Type \"help\" for help.");
 
        return true;
    }
 
}[I][/I][/i]

Here's the basic usage of this class:

1. Create a class (any class, no extension or implementation requirements) to serve as your command handler.
2. Write methods to handle commands. Just as well EventHandlers, the names do not matter. The parameters, however do. The first parameter must be some subclass of CommandSender (typically either CommandSender or Player, but you can also specify ConsoleCommandSender), and the second parameter must be a String[] (String array).
3. Add the @CommandHandler annotation. You must include the name of the command in this. Optionally, you can add all the additional fields that can be defined in the plugin YAML. Aliases however will NOT work, as the method for setting them in Bukkit is broken (and will not be fixed).
4. Register the handler with its plugin using the command. Example is below.

Here's a sample handler class and method to handle a command:

Code:java

public class CommandClass{

Code:java

 
[I] @CommandHandler( name = "setspawn" )[/I]
[I] public void setSpawnCommand(Player player, String[] args){[/I]
[I] //code to set the spawn location[/I]
[I] }[/I]
[I]}[/I]

And here's the code to register that handler class and method to its command:

Code:java

CommandController.registerCommands(plugin, new CommandClass());

Here are a few features that this system includes, built in:

1. Quick and easy discrimination about what can send which commands. If the first parameter of the method is a more specific subclass of CommandSender, only that type of sender will be allowed to execute the command, and any others will be given a notification when they try.
2. Fewer arguments to deal with. Command handler is much neater and more compact.
3. Never use the onCommand method again!
4. If you use Eclipse you can now minimize individual commands, because they're each assigned their own method.

In addition to all the wonderfulness, the CommandController can also register and handle sub-commands! These are included thoughtfully for those plugins who prefer to prefix all their functional commands with an alias of the plugin name (think plugins like AutoMessage with /automessage ... or WorldGuard with /region ...). They are registered and handled exactly the same way as normal commands, but in the annotation you'll have to include the parent function as well. Here's an example for you:

Code:java

public class SubCommandClass{

Code:java

 
[I] @SubCommandHandler(parent = "region", name = "define")[/I]
[I] public void regionDefineCommand(Player player, String[] args){[/I]
[I] //code to define a region[/I]
[I] }[/I]
[I] @SubCommandHandler(parent = "region", name = "info")[/I]
[I] public void regionInfoCommand(Player player, String[] args){[/I]
[I] //code to get info about a region[/I]
[I] }[/I]
[I]}[/I]

Things to remember about using subcommands:

1. The argument that is actually used to define the subcommand will be automatically removed from the argument list being sent in the String[]. The argument list will only include all the arguments AFTER the subcommand.
2. Subcommands will always override their parent commands. If a subcommand exists for a given command, and is called, the parent command will never be called, even if an error occurs.

That's all for now folks, I hope this helps, and I hope I don't get bashed too much for overriding traditional Bukkit functionality!



By the way, all of this is tested and works.

I'm not sure why everything went all italic and junk, but oh well...

EDIT by Moderator: merged posts, please use the edit button instead of double posting.

 

Think u meant to put this in resources.

 

Moved to the appropriate section.

 

Here's a link to the Bukkit Dev paste:

CommandController class

 

Oh boy, i just love this

 

AmoebaMan

This has made things so much easier

I see that your CommandController class can handle permission nodes. How do I use this feature? And is usable with Vault?

 

Junrall

Yes vault is compatible with it, I use it and it works wonders!


AmoebaMan

Before anything, thank you so much for making this, it is very helpful in a multitude ways.

My question: How do I save to the config?
I've been using the same way I always have but it doesn't seem to be working? I've tried different things over the span of 2 days, and I've kind of rage quit. Here is what I have so far:

In my subCommand:

Code:

this.addPlayerBounty(args[2], args[1]);

In my main class:

Code:

private HashMap<String, String> playerBounty;
 
public void addPlayerBounty(final String newBounty, final String newPrice){
        this.playerBounty.put(newBounty, newPrice);
        //this.getConfig().set("bounties."+newBounty, newPrice);
        this.getConfig().set("bounties.djoutbased", "10");
        this.saveConfig();
    }

Not sure what I'm doing wrong, as I've used it in other plugins without these problems. I've tried
doing

Code:

this.plugin.addBounty(args[1], args[2]);

but then it have to add a bunch of stuff and eventually change

Code:

CommandController.registerCommands(this, new Bounty());

a bit which just leads to mayhem. I did try it, but still it didn't work.

This may not be a problem with your code, but I was just asking for general advice overall, thanks ^.^

 

unrealdesign

Very cool!

Could you please show how vault is used with this?

Thanks!

 

Junrall

It's used like anything else, you just have to implement it like you were using onCommand(). This should help you out: https://github.com/MilkBowl/Vault

 

unrealdesign

I'm comfortable with the use of vault

I was just curious about the references to permissions within CommandController. It looks like you can assign permission nodes through CommandController. If this is the case, how would pass permission nodes to it? Maybe like this:?

Code:

public class SubCommandClass{
    @SubCommandHandler(parent = "region", name = "define", permission = "region.define")
    public void regionDefineCommand(Player player, String[] args){
        //code to define a region
    }
    @SubCommandHandler(parent = "region", name = "info", permission = "region.info")
    public void regionInfoCommand(Player player, String[] args){
        //code to get info about a region
    }
}

 

Not sure to be honest, you'd have to reference his code, or ask him when he responds. Also I fixed my own problem >.>

 

unrealdesign
It appears that we both came here for answers and ended up solving our own problems. Lol
My examples above are the correct way to have CommandController check permissions for a command.

Here is what you can pass to it:
parent = "region" The main command
name = "define" The sub command.
aliases = "rdefine, rd, regdef" Alternate aliases for the command. You have to separate the aliases with commas
description = "Sets a cubed region." Description of the command
usage = "/region define - Defines a cuboid."Show how to use the command
permission = "region.define" The permission node to check for this command
permissionMessage = "You do not have permission for this command." The message to display if the person does not have permission to use the command.

 

Junrall

Well thanks for all that! Now I won't have to go through the code myself ^.^ You the best!

/internethug

 

I am having some difficulties trying this out unfortunately. Seperate "public class TestCommand" with the method:

Code:

@CommandHandler(name = "test", description = "testing testing testing ", permission = "lf.test", permissionMessage = "Sorry, you lack the sufficient permissions to execute this.", usage = "Wrong syntax; try: /test")
public void test(CommandSender cs, String[] args) {
  Messaging messaging = new Messaging(this.plugin);
  messaging.send(cs, ChatColor.GREEN + "executing!");
  messaging.logInfo(ChatColor.GREEN + "executing!");
}

I've assumed I am to register it inside the main onEnable()... like so:

Code:

CommandController.registerCommands(this, new TestCommand());

Any insight would be greatly appreciated.

 

Have you added the command to plugin.yml?

Code:

commands:
   test:
      description: Testing command.

 

Hah! My bad, just went from reflection so I recently haven't been using that, good catch!

 

Yeah, plugin.yml is still required at the most basic level. I could probably hack into Bukkit's registration system and force it in if I wanted to, but it'd be messy, and I'd rather not risk breaking Bukkit entirely.

 

Hehe, I just have a need for dynamically named commands, so reflection is what I'm going with

 

This appears to be exactly what I was looking for. Thanks so much.

 

This is indeed what i have been looking for, since I'm too lazy to actually code the interface myself. Though I have not personally gone through the process of making one like this, I cannot tell what is wrong, as I seem to be getting an error.

CommandController Line 43-50,
[ The method description() is undefined for CommandController.CommandHandler ]

CommandController Line 81-84,
[ This method requires a body instead of a semi-colon ]

Not sure what it means. I've seen how annotations work, but don't get whats going wrong.

A little help?