Package com.jagrosh.jdautilities.command

Class Command

java.lang.Object
com.jagrosh.jdautilities.command.Command
Direct Known Subclasses:
AboutCommand, GuildlistCommand, PingCommand, RoleinfoCommand, ServerinfoCommand, ShutdownCommand, SlashCommand
public abstract class Command extends Object
Commands In JDA-Utilities

The internal inheritance for Commands used in JDA-Utilities is that of the Command object.

Classes created inheriting this class gain the unique traits of commands operated using the Commands Extension.
Using several fields, a command can define properties that make it unique and complex while maintaining a low level of development.
All Commands extending this class can define any number of these fields in a object constructor and then create the command action/response in the abstract #execute(CommandEvent) body: 

 public class ExampleCmd extends Command {
      
      public ExampleCmd() {
          this.name = "example";
          this.aliases = new String[]{"test","demo"};
          this.help = "gives an example of commands do";
      }
      
      @Override
      protected void execute(CommandEvent) {
          event.reply("Hey look! This would be the bot's reply if this was a command!");
      }
      
 }
Execution is with the provision of a MessageReceivedEvent-CommandClient wrapper called a CommandEvent and is performed in two steps:
  • run - The command runs through a series of conditionals, automatically terminating the command instance if one is not met, and possibly providing an error response.
  • execute - The command, now being cleared to run, executes and performs whatever lies in the abstract body method.
Author:
John Grosh (jagrosh)

  • Field Details

    • name

      protected String name
      The name of the command, allows the command to be called the formats:
      Normal Command: [prefix]<command name>.
      Slash Command: /<command name>

    • help

      protected String help
      A small help String that summarizes the function of the command, used in the default help builder, and shown in the client for Slash Commands.

    • category

      protected Command.Category category
      The Category of the command.
      This can perform any other checks not completed by the default conditional fields.

    • arguments

      protected String arguments
      An arguments format String for the command, used in the default help builder. Not supported for SlashCommands.
      See Also:

    • guildOnly

      protected boolean guildOnly
      true if the command may only be used in a Guild, false if it may be used in both a Guild and a DM.
      Default true.

    • nsfwOnly

      protected boolean nsfwOnly
      true if the command may only be used in an NSFW TextChannel or DMs. false if it may be used anywhere
      Default: false

    • requiredRole

      protected String requiredRole
      A String name of a role required to use this command.

    • ownerCommand

      protected boolean ownerCommand
      true if the command may only be used by a User with an ID matching the Owners or any of the CoOwners.
      If enabled for a Slash Command, only owners (owner + up to 9 co-owners) will be added to the SlashCommand. All other permissions will be ignored.
      Default false.

    • cooldown

      protected int cooldown
      An int number of seconds users must wait before using this command again.

    • userPermissions

      protected net.dv8tion.jda.api.Permission[] userPermissions
      Any Permissions a Member must have to use this command.
      These are only checked in a Guild environment.

    • botPermissions

      protected net.dv8tion.jda.api.Permission[] botPermissions
      Any Permissions the bot must have to use a command.
      These are only checked in a Guild environment.

    • aliases

      protected String[] aliases
      The aliases of the command, when calling a command these function identically to calling the Command.name. This options only works for normal commands, not slash commands.

    • children

      protected Command[] children
      The child commands of the command. These are used in the format [prefix]<parent name> <child name>.

    • helpBiConsumer

      protected BiConsumer<CommandEvent,Command> helpBiConsumer
      The BiConsumer for creating a help response to the format [prefix]<command name> help.

    • usesTopicTags

      protected boolean usesTopicTags
      true if this command checks a channel topic for topic-tags.
      This means that putting {-commandname}, {-command category}, {-all} in a channel topic will cause this command to terminate.
      Default true.

    • hidden

      protected boolean hidden
      true if this command should be hidden from the help.
      Default false
      This has no effect for SlashCommands.

    • cooldownScope

      protected Command.CooldownScope cooldownScope
      The CooldownScope of the command. This defines how far of a scope cooldowns have.
      Default CooldownScope.USER.

    • botMissingPermMessage

      protected String botMissingPermMessage
      The permission message used when the bot does not have the requires permission. Requires 3 "%s", first is user mention, second is the permission needed, third is type, e.g. Guild.

    • userMissingPermMessage

      protected String userMissingPermMessage
      The permission message used when the user does not have the requires permission. Requires 3 "%s", first is user mention, second is the permission needed, third is type, e.g. Guild.

  • Constructor Details

    • Command

      public Command()

  • Method Details

    • execute

      protected abstract void execute(CommandEvent event)
      The main body method of a Command.
      This is the "response" for a successful #run(CommandEvent).
      Parameters:
      event - The CommandEvent that triggered this Command

    • run

      public final void run(CommandEvent event)
      Runs checks for the Command with the given CommandEvent that called it.
      Will terminate, and possibly respond with a failure message, if any checks fail.
      Parameters:
      event - The CommandEvent that triggered this Command

    • isCommandFor

      public boolean isCommandFor(String input)
      Checks if the given input represents this Command
      Parameters:
      input - The input to check
      Returns:
      true if the input is the name or an alias of the Command

    • isAllowed

      public boolean isAllowed(net.dv8tion.jda.api.entities.TextChannel channel)
      Checks whether a command is allowed in a TextChannel by searching the channel topic for topic tags relating to the command.

      {-name}, {-category name}, or {-all} are valid examples of ways that this method would return false if placed in a channel topic.

      NOTE:Topic tags are case sensitive and proper usage must be in lower case!
      Also note that setting usesTopicTags to false will cause this method to always return true, as the feature would not be applicable in the first place.

      Parameters:
      channel - The TextChannel to test.
      Returns:
      true if the channel topic doesn't specify any topic-tags that would cause this command to be cancelled, or if usesTopicTags has been set to false.

    • getName

      public String getName()
      Gets the Command.name for the Command.
      Returns:
      The name for the Command

    • getHelp

      public String getHelp()
      Gets the Command.help for the Command.
      Returns:
      The help for the Command

    • getCategory

      public Command.Category getCategory()
      Gets the Command.category for the Command.
      Returns:
      The category for the Command

    • getArguments

      public String getArguments()
      Gets the Command.arguments for the Command.
      Returns:
      The arguments for the Command

    • isGuildOnly

      public boolean isGuildOnly()
      Checks if this Command can only be used in a Guild.
      Returns:
      true if this Command can only be used in a Guild, else false if it can be used outside of one

    • getRequiredRole

      public String getRequiredRole()
      Gets the Command.requiredRole for the Command.
      Returns:
      The requiredRole for the Command

    • getCooldown

      public int getCooldown()
      Gets the Command.cooldown for the Command.
      Returns:
      The cooldown for the Command

    • getUserPermissions

      public net.dv8tion.jda.api.Permission[] getUserPermissions()
      Gets the Command.userPermissions for the Command.
      Returns:
      The userPermissions for the Command

    • getBotPermissions

      public net.dv8tion.jda.api.Permission[] getBotPermissions()
      Gets the Command.botPermissions for the Command.
      Returns:
      The botPermissions for the Command

    • getAliases

      public String[] getAliases()
      Gets the Command.aliases for the Command.
      Returns:
      The aliases for the Command

    • getChildren

      public Command[] getChildren()
      Gets the Command.children for the Command.
      Returns:
      The children for the Command

    • isOwnerCommand

      public boolean isOwnerCommand()
      Checks whether or not this command is an owner only Command.
      Returns:
      true if the command is an owner command, otherwise false if it is not

    • isHidden

      public boolean isHidden()
      Checks whether or not this command should be hidden from the help.
      Returns:
      true if the command should be hidden, otherwise false

    • getCooldownKey

      public String getCooldownKey(CommandEvent event)
      Gets the proper cooldown key for this Command under the provided CommandEvent.
      Parameters:
      event - The CommandEvent to generate the cooldown for.
      Returns:
      A String key to use when applying a cooldown.

    • getCooldownError

      public String getCooldownError(CommandEvent event, int remaining)
      Gets an error message for this Command under the provided CommanEvent.
      Parameters:
      event - The CommandEvent to generate the error message for.
      remaining - The remaining number of seconds a command is on cooldown for.
      Returns:
      A String error message for this command if remaining > 0, else null.