Interface CommandClient
- All Known Implementing Classes:
CommandClientImpl
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 Command
s.
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:
Command
s may be added or removed.- The
CommandListener
may be set.
- 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 anIllegalArgumentException
).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 inEmoji.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 Summary
Modifier and TypeMethodDescriptionvoid
addAnnotatedModule
(Object module) Compiles the providedObject
annotated withJDACommand.Module
into aList
ofCommand
s and adds them to this CommandClient in the order they are listed.void
addAnnotatedModule
(Object module, Function<Command, Integer> mapFunction) Compiles the providedObject
annotated withJDACommand.Module
into aList
ofCommand
s and adds them to this CommandClient via theFunction
provided.void
addCommand
(Command command) Adds a singleCommand
to this CommandClient's registered Commands.void
addCommand
(Command command, int index) Adds a singleCommand
to this CommandClient's registered Commands at the specified index.void
addContextMenu
(ContextMenu menu) Adds a singleContextMenu
to this CommandClient's registered Context Menus.void
addContextMenu
(ContextMenu menu, int index) Adds a singleContextMenu
to this CommandClient's registered Context Menus.void
addSlashCommand
(SlashCommand command) Adds a singleSlashCommand
to this CommandClient's registered SlashCommand.void
addSlashCommand
(SlashCommand command, int index) Adds a singleSlashCommand
to this CommandClient's registered Commands at the specified index.void
applyCooldown
(String name, int seconds) Applies the specified cooldown with the provided name.void
Cleans up expired cooldowns to reduce memory.Returns the forced Guild ID for automatic slash command upsertsGets the Client's alternate prefix.Returns the list of registeredCommand
s during this session.int
getCommandUses
(Command command) Gets the number of uses for the provideCommand
during this session, or0
if the command is not registered to this CommandClient.int
getCommandUses
(String name) Gets the number of uses for aCommand
during this session matching the provided String name, or0
if there is no Command with the name.Returns the list of registeredContextMenu
s during this session.getCooldown
(String name) Gets theOffsetDateTime
that the specified cooldown expires.String[]
Gets the ID(s) of any CoOwners of this bot as a String Array.long[]
Gets the ID(s) of any CoOwners of this bot as along
Array.getError()
Gets the error emoji.Gets the word used to invoke a help DM.Returns the currentCommandListener
.Gets the ID of the owner of this bot as a String.long
Gets the ID of the owner of this bot as along
.Gets the Client's prefix.String[]
Gets the array of prefixesGets the prefix BiConsumerint
getRemainingCooldown
(String name) Gets the remaining number of seconds on the specified cooldown.Gets theScheduledExecutorService
held by this client.Gets the invite to the bot's support server.<S> S
getSettingsFor
(net.dv8tion.jda.api.entities.Guild guild) Returns an Object of the type parameter that should contain settings relating to the specifiedGuild
.<M extends GuildSettingsManager>
MReturns the type ofGuildSettingsManager
, the same type of one provided when building this CommandClient, ornull
if one was not provided there.Returns the list of registeredSlashCommand
s during this session.Gets the time thisCommandClient
implementation was created.Gets the success emoji.Returns the visual representation of the bot's prefix.int
Gets an a recently updated count of all theGuild
s the bot is connected to on all shards.Gets the warning emoji.boolean
Returns whether manual upsertion is enabledvoid
removeCommand
(String name) Removes a singleCommand
from this CommandClient's registered Commands at the index linked to the provided name/alias.void
setListener
(CommandListener listener) Sets theCommandListener
to catch command-related events thrown by thisCommandClient
.void
shutdown()
Shuts down internals of the Command Client, such as the threadpool and guild settings managervoid
upsertInteractions
(net.dv8tion.jda.api.JDA jda) Upserts all interactions to the providedforced server
.void
upsertInteractions
(net.dv8tion.jda.api.JDA jda, String serverId) Upserts all interactions to the provided server.boolean
Gets whether this CommandClient uses linked deletion.
-
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
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
Adds a singleCommand
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 aHashMap
which links theirname
and theiraliases
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
Adds a singleCommand
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 aHashMap
which links theirname
and theiraliases
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 addindex
- The index to add the Command at (must follow the specifications0<=index<=size()
)- Throws:
ArrayIndexOutOfBoundsException
- Ifindex < 0
orindex > size()
IllegalArgumentException
- If the Command provided has a name or alias that has already been registered to an index
-
addSlashCommand
Adds a singleSlashCommand
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 aHashMap
which links theirname
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
Adds a singleSlashCommand
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 aHashMap
which links theirname
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 addindex
- The index to add the Command at (must follow the specifications0<=index<=size()
)- Throws:
ArrayIndexOutOfBoundsException
- Ifindex < 0
orindex > size()
IllegalArgumentException
- If the Command provided has a name or alias that has already been registered to an index
-
addContextMenu
Adds a singleContextMenu
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
Adds a singleContextMenu
to this CommandClient's registered Context Menus.- Parameters:
menu
- The menu to addindex
- The index to add the Context Menu at (must follow the specifications0<=index<=size()
)- Throws:
IllegalArgumentException
- If the Context Menu provided has a name that has already been registered
-
removeCommand
Removes a singleCommand
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 aHashMap
which links theirname
and theiraliases
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
Compiles the providedObject
annotated withJDACommand.Module
into aList
ofCommand
s 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
Compiles the providedObject
annotated withJDACommand.Module
into aList
ofCommand
s and adds them to this CommandClient via theFunction
provided.This is done through the
AnnotatedModuleCompiler
provided when building this CommandClient.The Function will
apply
eachCommand
in the compiled list and request anint
in return.
Using thisint
, the command provided will be applied to the CommandClient viaCommandClient#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
- Ifindex < 0
orindex > size()
IllegalArgumentException
- If the Command provided has a name or alias that has already been registered to an index
-
setListener
Sets theCommandListener
to catch command-related events thrown by thisCommandClient
.- Parameters:
listener
- The CommandListener
-
getListener
CommandListener getListener()Returns the currentCommandListener
.- Returns:
- A possibly-null CommandListener
-
getCommands
Returns the list of registeredCommand
s during this session.- Returns:
- A never-null List of Commands registered during this session
-
getSlashCommands
List<SlashCommand> getSlashCommands()Returns the list of registeredSlashCommand
s during this session.- Returns:
- A never-null List of Slash Commands registered during this session
-
getContextMenus
List<ContextMenu> getContextMenus()Returns the list of registeredContextMenu
s 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 thisCommandClient
implementation was created.- Returns:
- The start time of this CommandClient implementation
-
getCooldown
Gets theOffsetDateTime
that the specified cooldown expires.- Parameters:
name
- The cooldown name- Returns:
- The expiration time, or null if the cooldown does not exist
-
getRemainingCooldown
Gets the remaining number of seconds on the specified cooldown.- Parameters:
name
- The cooldown name- Returns:
- The number of seconds remaining
-
applyCooldown
Applies the specified cooldown with the provided name.- Parameters:
name
- The cooldown nameseconds
- The time to make the cooldown last
-
cleanCooldowns
void cleanCooldowns()Cleans up expired cooldowns to reduce memory. -
getCommandUses
Gets the number of uses for the provideCommand
during this session, or0
if the command is not registered to this CommandClient.- Parameters:
command
- The Command- Returns:
- The number of uses for the Command
-
getCommandUses
Gets the number of uses for aCommand
during this session matching the provided String name, or0
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 thatchild commands
ARE NOT tracked and providing names or effective names of child commands will return0
.- 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 along
.- 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 along
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 theScheduledExecutorService
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 theGuild
s 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
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
Message
s.
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 specifiedGuild
.The returning object for this is specified via provision of a
GuildSettingsManager
toCommandClientBuilder#setGuildSettingsManager(GuildSettingsManager)
, more specificallyGuildSettingsManager#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 benull
if the implementation allows it.
-
getSettingsManager
Returns the type ofGuildSettingsManager
, the same type of one provided when building this CommandClient, ornull
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 providedforced server
.
This runs after theReadyEvent
has been fired ifisManualUpsert()
isfalse
.
IfforcedGuildId()
isnull
, commands will upsert globally. This may take up to an hour.- Parameters:
jda
- The JDA instance to use
-
upsertInteractions
Upserts all interactions to the provided server.
This runs after theReadyEvent
has been fired ifisManualUpsert()
isfalse
.
Ifnull
is passed for the server, commands will upsert globally. This may take up to an hour.- Parameters:
jda
- The JDA instance to useserverId
- The server to upsert interactions for
-