Package com.jagrosh.jdautilities.command

Interface CommandClient

All Known Implementing Classes:
CommandClientImpl
public interface CommandClient
A Bot Client interface implemented on objects used to hold bot data.

This is implemented in CommandClientImpl alongside implementation of EventListener to create a compounded "Client Listener" which catches specific kinds of events thrown by JDA and processes them automatically to handle and execute Commands.

Implementations also serve as a useful platforms, carrying reference info such as the bot's Owner ID, prefix, and a support server invite.

For the CommandClientImpl, once initialized, only the following can be modified:

Author:
John Grosh (jagrosh)
Implementation Note:
While typically safe, there are a few ways to misuse the standard implementation of this interface: the CommandClientImpl.
Because of this the following should ALWAYS be followed to avoid such errors:

1) Do not build and add more than one CommandClient to an instance JDA, EVER.

2) Always create and add the CommandClientImpl to JDA BEFORE you build it, or there is a chance some minor errors will occur, especially if JDA has already fired a ReadyEvent.

3) Do not provide anything other than a String representing a long (and furthermore a User ID) as an Owner ID or a CoOwner ID. This will generate errors, but not stop the creation of the CommandClientImpl which will cause several errors to occur very quickly after startup (except if you provide null for the Owner ID, that'll just flat out throw an IllegalArgumentException).

4) Do not provide strings when using CommandClientBuilder#setEmojis(String, String, String) that are not unicode emojis or that do not match the custom emote format specified in Emoji.getFormatted() () Emote#getAsMention()} (IE: <:EmoteName:EmoteID>).

5) Avoid using CommandClientImpl.linkIds(long, net.dv8tion.jda.api.entities.Message). This will create errors and has no real purpose outside of it's current usage.

  • Method Details

    • getPrefix

      String getPrefix()
      Gets the Client's prefix.
      Returns:
      A possibly-null prefix

    • getAltPrefix

      String getAltPrefix()
      Gets the Client's alternate prefix.
      Returns:
      A possibly-null alternate prefix

    • getPrefixes

      String[] getPrefixes()
      Gets the array of prefixes
      Returns:
      A possibly-null list of prefixes

    • getPrefixFunction

      Function<net.dv8tion.jda.api.events.message.MessageReceivedEvent,String> getPrefixFunction()
      Gets the prefix BiConsumer
      Returns:
      A possibly-null prefix BiConsumer

    • getTextualPrefix

      String getTextualPrefix()
      Returns the visual representation of the bot's prefix.

      This is the same as getPrefix() unless the prefix is the default, in which case it appears as @Botname.

      Returns:
      A never-null prefix

    • addCommand

      void addCommand(Command command)
      Adds a single Command to this CommandClient's registered Commands.

      For CommandClient's containing 20 commands or less, command calls by users will have the bot iterate through the entire ArrayList to find the command called. As expected, this can get fairly hefty if a bot has a lot of Commands registered to it.

      To prevent delay a CommandClient that has more that 20 Commands registered to it will begin to use indexed calls.
      Indexed calls use a HashMap which links their name and their aliases to the index that which they are located at in the ArrayList they are stored.

      This means that all insertion and removal of Commands must reorganize the index maintained by the HashMap.
      For this particular insertion, the Command provided is inserted at the end of the index, meaning it will become the "rightmost" Command in the ArrayList.

      Parameters:
      command - The Command to add
      Throws:
      IllegalArgumentException - If the Command provided has a name or alias that has already been registered

    • addCommand

      void addCommand(Command command, int index)
      Adds a single Command to this CommandClient's registered Commands at the specified index.

      For CommandClient's containing 20 commands or less, command calls by users will have the bot iterate through the entire ArrayList to find the command called. As expected, this can get fairly hefty if a bot has a lot of Commands registered to it.

      To prevent delay a CommandClient that has more that 20 Commands registered to it will begin to use indexed calls.
      Indexed calls use a HashMap which links their name and their aliases to the index that which they are located at in the ArrayList they are stored.

      This means that all insertion and removal of Commands must reorganize the index maintained by the HashMap.
      For this particular insertion, the Command provided is inserted at the index specified, meaning it will become the Command located at that index in the ArrayList. This will shift the Command previously located at that index as well as any located at greater indices, right one index (size()+1).

      Parameters:
      command - The Command to add
      index - The index to add the Command at (must follow the specifications 0<=index<=size())
      Throws:
      ArrayIndexOutOfBoundsException - If index < 0 or index > size()
      IllegalArgumentException - If the Command provided has a name or alias that has already been registered to an index

    • addSlashCommand

      void addSlashCommand(SlashCommand command)
      Adds a single SlashCommand to this CommandClient's registered SlashCommand.

      For CommandClient's containing 20 commands or less, command calls by users will have the bot iterate through the entire ArrayList to find the command called. As expected, this can get fairly hefty if a bot has a lot of Commands registered to it.

      To prevent delay a CommandClient that has more that 20 Commands registered to it will begin to use indexed calls.
      Indexed calls use a HashMap which links their name to the index that which they are located at in the ArrayList they are stored.

      This means that all insertion and removal of SlashCommands must reorganize the index maintained by the HashMap.
      For this particular insertion, the SlashCommand provided is inserted at the end of the index, meaning it will become the "rightmost" Command in the ArrayList.

      Parameters:
      command - The Command to add
      Throws:
      IllegalArgumentException - If the SlashCommand provided has a name or alias that has already been registered

    • addSlashCommand

      void addSlashCommand(SlashCommand command, int index)
      Adds a single SlashCommand to this CommandClient's registered Commands at the specified index.

      For CommandClient's containing 20 commands or less, command calls by users will have the bot iterate through the entire ArrayList to find the command called. As expected, this can get fairly hefty if a bot has a lot of Commands registered to it.

      To prevent delay a CommandClient that has more that 20 Commands registered to it will begin to use indexed calls.
      Indexed calls use a HashMap which links their name to the index that which they are located at in the ArrayList they are stored.

      This means that all insertion and removal of Commands must reorganize the index maintained by the HashMap.
      For this particular insertion, the Command provided is inserted at the index specified, meaning it will become the Command located at that index in the ArrayList. This will shift the Command previously located at that index as well as any located at greater indices, right one index (size()+1).

      Parameters:
      command - The Command to add
      index - The index to add the Command at (must follow the specifications 0<=index<=size())
      Throws:
      ArrayIndexOutOfBoundsException - If index < 0 or index > size()
      IllegalArgumentException - If the Command provided has a name or alias that has already been registered to an index

    • addContextMenu

      void addContextMenu(ContextMenu menu)
      Adds a single ContextMenu to this CommandClient's registered Context Menus.
      Parameters:
      menu - The menu to add
      Throws:
      IllegalArgumentException - If the Context Menu provided has a name that has already been registered

    • addContextMenu

      void addContextMenu(ContextMenu menu, int index)
      Adds a single ContextMenu to this CommandClient's registered Context Menus.
      Parameters:
      menu - The menu to add
      index - The index to add the Context Menu at (must follow the specifications 0<=index<=size())
      Throws:
      IllegalArgumentException - If the Context Menu provided has a name that has already been registered

    • removeCommand

      void removeCommand(String name)
      Removes a single Command from this CommandClient's registered Commands at the index linked to the provided name/alias.

      For CommandClient's containing 20 commands or less, command calls by users will have the bot iterate through the entire ArrayList to find the command called. As expected, this can get fairly hefty if a bot has a lot of Commands registered to it.

      To prevent delay a CommandClient that has more that 20 Commands registered to it will begin to use indexed calls.
      Indexed calls use a HashMap which links their name and their aliases to the index that which they are located at in the ArrayList they are stored.

      This means that all insertion and removal of Commands must reorganize the index maintained by the HashMap.
      For this particular removal, the Command removed is that of the corresponding index retrieved by the name provided. This will shift any Commands located at greater indices, left one index (size()-1).

      Parameters:
      name - The name or an alias of the Command to remove
      Throws:
      IllegalArgumentException - If the name provided was not registered to an index

    • addAnnotatedModule

      void addAnnotatedModule(Object module)
      Compiles the provided Object annotated with JDACommand.Module into a List of Commands and adds them to this CommandClient in the order they are listed.

      This is done through the AnnotatedModuleCompiler provided when building this CommandClient.

      Parameters:
      module - An object annotated with JDACommand.Module to compile into commands to be added.
      Throws:
      IllegalArgumentException - If the Command provided has a name or alias that has already been registered

    • addAnnotatedModule

      void addAnnotatedModule(Object module, Function<Command,Integer> mapFunction)
      Compiles the provided Object annotated with JDACommand.Module into a List of Commands and adds them to this CommandClient via the Function provided.

      This is done through the AnnotatedModuleCompiler provided when building this CommandClient.

      The Function will apply each Command in the compiled list and request an int in return.
      Using this int, the command provided will be applied to the CommandClient via CommandClient#addCommand(Command, int).

      Parameters:
      module - An object annotated with JDACommand.Module to compile into commands to be added.
      mapFunction - The Function to get indexes for each compiled Command with when adding them to the CommandClient.
      Throws:
      ArrayIndexOutOfBoundsException - If index < 0 or index > size()
      IllegalArgumentException - If the Command provided has a name or alias that has already been registered to an index

    • setListener

      void setListener(CommandListener listener)
      Sets the CommandListener to catch command-related events thrown by this CommandClient.
      Parameters:
      listener - The CommandListener

    • getListener

      CommandListener getListener()
      Returns the current CommandListener.
      Returns:
      A possibly-null CommandListener

    • getCommands

      List<Command> getCommands()
      Returns the list of registered Commands during this session.
      Returns:
      A never-null List of Commands registered during this session

    • getSlashCommands

      List<SlashCommand> getSlashCommands()
      Returns the list of registered SlashCommands during this session.
      Returns:
      A never-null List of Slash Commands registered during this session

    • getContextMenus

      List<ContextMenu> getContextMenus()
      Returns the list of registered ContextMenus during this session.
      Returns:
      A never-null List of Context Menus registered during this session

    • isManualUpsert

      boolean isManualUpsert()
      Returns whether manual upsertion is enabled
      Returns:
      The manual upsertion status

    • forcedGuildId

      String forcedGuildId()
      Returns the forced Guild ID for automatic slash command upserts
      Returns:
      A possibly-null forcedGuildId set in the builder

    • getStartTime

      OffsetDateTime getStartTime()
      Gets the time this CommandClient implementation was created.
      Returns:
      The start time of this CommandClient implementation

    • getCooldown

      OffsetDateTime getCooldown(String name)
      Gets the OffsetDateTime that the specified cooldown expires.
      Parameters:
      name - The cooldown name
      Returns:
      The expiration time, or null if the cooldown does not exist

    • getRemainingCooldown

      int getRemainingCooldown(String name)
      Gets the remaining number of seconds on the specified cooldown.
      Parameters:
      name - The cooldown name
      Returns:
      The number of seconds remaining

    • applyCooldown

      void applyCooldown(String name, int seconds)
      Applies the specified cooldown with the provided name.
      Parameters:
      name - The cooldown name
      seconds - The time to make the cooldown last

    • cleanCooldowns

      void cleanCooldowns()
      Cleans up expired cooldowns to reduce memory.

    • getCommandUses

      int getCommandUses(Command command)
      Gets the number of uses for the provide Command during this session, or 0 if the command is not registered to this CommandClient.
      Parameters:
      command - The Command
      Returns:
      The number of uses for the Command

    • getCommandUses

      int getCommandUses(String name)
      Gets the number of uses for a Command during this session matching the provided String name, or 0 if there is no Command with the name.

      NOTE: this method WILL NOT get uses for a command if an alias is provided! Also note that child commands ARE NOT tracked and providing names or effective names of child commands will return 0.

      Parameters:
      name - The name of the Command
      Returns:
      The number of uses for the Command, or 0 if the name does not match with a Command

    • getOwnerId

      String getOwnerId()
      Gets the ID of the owner of this bot as a String.
      Returns:
      The String ID of the owner of the bot

    • getOwnerIdLong

      long getOwnerIdLong()
      Gets the ID of the owner of this bot as a long.
      Returns:
      The long ID of the owner of the bot

    • getCoOwnerIds

      String[] getCoOwnerIds()
      Gets the ID(s) of any CoOwners of this bot as a String Array.
      Returns:
      The String ID(s) of any CoOwners of this bot

    • getCoOwnerIdsLong

      long[] getCoOwnerIdsLong()
      Gets the ID(s) of any CoOwners of this bot as a long Array.
      Returns:
      The long ID(s) of any CoOwners of this bot

    • getSuccess

      String getSuccess()
      Gets the success emoji.
      Returns:
      The success emoji

    • getWarning

      String getWarning()
      Gets the warning emoji.
      Returns:
      The warning emoji

    • getError

      String getError()
      Gets the error emoji.
      Returns:
      The error emoji

    • getScheduleExecutor

      ScheduledExecutorService getScheduleExecutor()
      Gets the ScheduledExecutorService held by this client.

      This is used for methods such as CommandEvent#async(Runnable) run code asynchronously.

      Returns:
      The ScheduledExecutorService held by this client.

    • getServerInvite

      String getServerInvite()
      Gets the invite to the bot's support server.
      Returns:
      A possibly-null server invite

    • getTotalGuilds

      int getTotalGuilds()
      Gets an a recently updated count of all the Guilds the bot is connected to on all shards.

      NOTE: This may not always or should not be assumed accurate! Any time a shard joins or leaves a guild it will update the number retrieved by this method but will not update when other shards join or leave guilds. This means that shards will not always retrieve the same value. For instance:

      • 1) Shard A joins 10 Guilds
      • 2) Shard B invokes this method
      • 3) Shard A invokes this method
      The number retrieved by Shard B will be that of the number retrieved by Shard A, minus 10 guilds because Shard B hasn't updated and accounted for those 10 guilds on Shard A.

      This feature requires a Discord Bots API Key to be set!
      To set your Discord Bots API Key, you'll have to retrieve it from the Discord Bots website.

      Returns:
      A recently updated count of all the Guilds the bot is connected to on all shards.

    • getHelpWord

      String getHelpWord()
      Gets the word used to invoke a help DM.
      Returns:
      The help word

    • usesLinkedDeletion

      boolean usesLinkedDeletion()
      Gets whether this CommandClient uses linked deletion.

      Linking calls is the basic principle of pairing bot responses with their calling Messages.
      Using this with a basic function such as deletion, this causes bots to delete their Messages as a response to the calling Message being deleted.

      Returns:
      true if the bot uses linked deletion, false otherwise.
      See Also:

    • getSettingsFor

      <S> S getSettingsFor(net.dv8tion.jda.api.entities.Guild guild)
      Returns an Object of the type parameter that should contain settings relating to the specified Guild.

      The returning object for this is specified via provision of a GuildSettingsManager to CommandClientBuilder#setGuildSettingsManager(GuildSettingsManager), more specifically GuildSettingsManager#getSettings(Guild).

      Type Parameters:
      S - The type of settings the GuildSettingsManager provides
      Parameters:
      guild - The Guild to get Settings for
      Returns:
      The settings object for the Guild, specified in GuildSettingsManager#getSettings(Guild), can be null if the implementation allows it.

    • getSettingsManager

      <M extends GuildSettingsManager> M getSettingsManager()
      Returns the type of GuildSettingsManager, the same type of one provided when building this CommandClient, or null if one was not provided there.

      This is good if you want to use non-abstract methods specific to your implementation.

      Type Parameters:
      M - The type of the GuildSettingsManager
      Returns:
      The GuildSettingsManager, or null if one was not provided when building this CommandClient.

    • shutdown

      void shutdown()
      Shuts down internals of the Command Client, such as the threadpool and guild settings manager

    • upsertInteractions

      void upsertInteractions(net.dv8tion.jda.api.JDA jda)
      Upserts all interactions to the provided forced server.
      This runs after the ReadyEvent has been fired if isManualUpsert() is false.
      If forcedGuildId() is null, commands will upsert globally. This may take up to an hour.
      Parameters:
      jda - The JDA instance to use

    • upsertInteractions

      void upsertInteractions(net.dv8tion.jda.api.JDA jda, String serverId)
      Upserts all interactions to the provided server.
      This runs after the ReadyEvent has been fired if isManualUpsert() is false.
      If null is passed for the server, commands will upsert globally. This may take up to an hour.
      Parameters:
      jda - The JDA instance to use
      serverId - The server to upsert interactions for