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:

• Commands 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 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 Emote#getAsMention() (IE: <:EmoteName:EmoteID>).

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

Method Summary

Modifier and Type	Method and Description
void	addAnnotatedModule(java.lang.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.
void	addAnnotatedModule(java.lang.Object module, java.util.function.Function<Command,java.lang.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.
void	addCommand(Command command) Adds a single Command to this CommandClient's registered Commands.
void	addCommand(Command command, int index) Adds a single Command to this CommandClient's registered Commands at the specified index.
void	applyCooldown(java.lang.String name, int seconds) Applies the specified cooldown with the provided name.
void	cleanCooldowns() Cleans up expired cooldowns to reduce memory.
java.lang.String	getAltPrefix() Gets the Client's alternate prefix.
java.util.List<Command>	getCommands() Returns the list of registered Commands during this session.
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.
int	getCommandUses(java.lang.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.
java.time.OffsetDateTime	getCooldown(java.lang.String name) Gets the OffsetDateTime that the specified cooldown expires.
java.lang.String[]	getCoOwnerIds() Gets the ID(s) of any CoOwners of this bot as a String Array.
long[]	getCoOwnerIdsLong() Gets the ID(s) of any CoOwners of this bot as a long Array.
java.lang.String	getError() Gets the error emoji.
java.lang.String	getHelpWord() Gets the word used to invoke a help DM.
CommandListener	getListener() Returns the current CommandListener.
java.lang.String	getOwnerId() Gets the ID of the owner of this bot as a String.
long	getOwnerIdLong() Gets the ID of the owner of this bot as a long.
java.lang.String	getPrefix() Gets the Client's prefix.
int	getRemainingCooldown(java.lang.String name) Gets the remaining number of seconds on the specified cooldown.
java.util.concurrent.ScheduledExecutorService	getScheduleExecutor() Gets the ScheduledExecutorService held by this client.
java.lang.String	getServerInvite() Gets the invite to the bot's support server.
<S> S	getSettingsFor(net.dv8tion.jda.core.entities.Guild guild) Returns an Object of the type parameter that should contain settings relating to the specified Guild.
<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.
java.time.OffsetDateTime	getStartTime() Gets the time this CommandClient implementation was created.
java.lang.String	getSuccess() Gets the success emoji.
java.lang.String	getTextualPrefix() Returns the visual representation of the bot's prefix.
int	getTotalGuilds() Gets an a recently updated count of all the Guilds the bot is connected to on all shards.
java.lang.String	getWarning() Gets the warning emoji.
void	removeCommand(java.lang.String name) Removes a single Command from this CommandClient's registered Commands at the index linked to the provided name/alias.
void	setListener(CommandListener listener) Sets the CommandListener to catch command-related events thrown by this CommandClient.
boolean	usesLinkedDeletion() Gets whether this CommandClient uses linked deletion.

Method Detail

getPrefix

java.lang.String getPrefix()

Gets the Client's prefix.

Returns:

A possibly-null prefix

getAltPrefix

java.lang.String getAltPrefix()

Gets the Client's alternate prefix.

Returns:

A possibly-null alternate prefix

getTextualPrefix

java.lang.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:

java.lang.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:

java.lang.ArrayIndexOutOfBoundsException - If index < 0 or index > size()

java.lang.IllegalArgumentException - If the Command provided has a name or alias that has already been registered to an index

removeCommand

void removeCommand(java.lang.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:

java.lang.IllegalArgumentException - If the name provided was not registered to an index

addAnnotatedModule

void addAnnotatedModule(java.lang.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:

java.lang.IllegalArgumentException - If the Command provided has a name or alias that has already been registered

addAnnotatedModule

void addAnnotatedModule(java.lang.Object module,
                        java.util.function.Function<Command,java.lang.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:

java.lang.ArrayIndexOutOfBoundsException - If index < 0 or index > size()

java.lang.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

java.util.List<Command> getCommands()

Returns the list of registered Commands during this session.

Returns:

A never-null List of Commands registered during this session

getStartTime

java.time.OffsetDateTime getStartTime()

Gets the time this CommandClient implementation was created.

Returns:

The start time of this CommandClient implementation

getCooldown

java.time.OffsetDateTime getCooldown(java.lang.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(java.lang.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(java.lang.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(java.lang.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

java.lang.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

java.lang.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

java.lang.String getSuccess()

Gets the success emoji.

Returns:

The success emoji

getWarning

java.lang.String getWarning()

Gets the warning emoji.

Returns:

The warning emoji

getError

java.lang.String getError()

Gets the error emoji.

Returns:

The error emoji

getScheduleExecutor

java.util.concurrent.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

java.lang.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

java.lang.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:

CommandClientBuilder#setLinkedCacheSize(int)

getSettingsFor

<S> S getSettingsFor(net.dv8tion.jda.core.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.