Package com.github.johnnyjayjay.discord.commandapi

Class CommandSettings

java.lang.Object

com.github.johnnyjayjay.discord.commandapi.CommandSettings

public class CommandSettings
extends Object

To use this framework, create a new object of this class and add your command classes by using add(...)

When you want your commands to become active, use activate()

Since:

1.1

Version:

3.2

Author:

Johnny_JayJay

Field Summary

Fields

Modifier and Type	Field	Description
protected static org.slf4j.Logger	LOGGER	The logger of this framework.
static String	VALID_LABEL	A regex that only matches valid labels.
static String	VALID_PREFIX	A regex that only matches valid prefixes.

Constructor Summary

Constructors

Constructor	Description
CommandSettings(String defaultPrefix, net.dv8tion.jda.bot.sharding.ShardManager shardManager, boolean labelIgnoreCase)	This is the optional constructor in case you are sharding your bot.
CommandSettings(String defaultPrefix, net.dv8tion.jda.core.JDA jda, boolean labelIgnoreCase)	This is the constructor.

Method Summary

Modifier and Type	Method	Description
void	activate()	Sets the prefix and the command HashMap for the rest of the API.
CommandSettings	addChannelsToBlacklist(long... channelIds)	Adds multiple channels to the blacklist.
CommandSettings	addChannelsToBlacklist(Collection<Long> channelIds)	Adds multiple channels to the blacklist.
CommandSettings	addChannelToBlacklist(long channelId)	Adds a given channel to the blacklist (meaning commands can not be executed in there).
CommandSettings	addHelpLabel(String label)	Deprecated. This method is deprecated and thus not supported anymore.
CommandSettings	addHelpLabels(String... labels)	Deprecated. This method is deprecated and thus not supported anymore.
CommandSettings	addHelpLabels(Collection<String> labels)	Deprecated. This method is deprecated and thus not supported anymore.
boolean	botsMayExecute()	Returns whether bot execution is enabled.
CommandSettings	clear()	Resets this whole instance by clearing the commands and setting everything to how it was at the beginning.
CommandSettings	clearBlacklist()	Clears the blacklist so that no channel is blacklisted anymore.
CommandSettings	clearCommands()	Clears all commands.
CommandSettings	clearCustomPrefixes()	Removes all entries from the prefix map, resetting every custom prefix.
CommandSettings	clearHelpLabels()	Deprecated. This method is deprecated and thus not supported anymore.
void	deactivate()	Deactivates the current CommandSettings by removing the command listener from jda.
Set<Long>	getBlacklistedChannels()	Use this to get the blacklisted channels.
protected Map<String,ICommand>	getCommands()
long	getCooldown()	Returns the currently set cooldown for this instance.
Color	getHelpColor()	Returns the help color for DefaultHelpCommand.
Set<String>	getHelpLabelSet()	Deprecated. This method is deprecated and not supported in this version anymore.
Set<String>	getLabels(ICommand command)	Returns every registered label for an ICommand instance in an immutable Set.
Set<String>	getLabelSet()	Returns every registered label in a Set.
String	getPrefix()	Use this method to get the default prefix.
String	getPrefix(long guildId)	Use this method to get the prefix for a specific guild.
protected net.dv8tion.jda.core.entities.Message	getUnknownCommandMessage()
boolean	isActivated()	Returns whether this instance is activated or not.
boolean	isBlacklisted(long channelId)	Returns whether the given channel id is blacklisted.
boolean	isLabelIgnoreCase()	Returns whether command labels are case insensitive on this instance of CommandSettings.
boolean	isResetCooldown()	Returns whether the cooldown will be reset for each execution attempt.
CommandSettings	put(ICommand executor, String label)	Use this method to add commands from your project.
CommandSettings	put(ICommand executor, String... labels)	Use this method to add commands with aliases.
CommandSettings	put(ICommand executor, Collection<String> labels)	Use this method to add commands with aliases from a Set.
boolean	remove(String label)	Use this method to remove existing commands.
boolean	remove(String... labels)	Use this method to remove more than one command at a time.
boolean	remove(Collection<String> labels)	Removes every label that is in the given Collection.
boolean	removeChannelFromBlacklist(long channelId)	Removes one channel from the blacklist.
boolean	removeChannelsFromBlacklist(long... channelIds)	Removes one or more channels from the blacklist.
boolean	removeChannelsFromBlackList(Collection<Long> channelIds)	Removes a given Collection of channel ids from the blacklist.
boolean	removeHelpLabel(String label)	Deprecated. This method is deprecated and thus not supported anymore.
boolean	removeHelpLabels(String... labels)	Deprecated. This method is deprecated and thus not supported anymore.
boolean	removeHelpLabels(Collection<String> labels)	Deprecated. This method is deprecated and thus not supported anymore.
CommandSettings	setBotExecution(boolean botExecution)	Setter for the field botExecution.
CommandSettings	setCooldown(long msCooldown)	Sets the cooldown for this instance of settings.
CommandSettings	setCustomPrefix(long guildId, String prefix)	Use this method to add a custom command prefix to a guild.
CommandSettings	setCustomPrefixes(Map<Long,String> guildIdPrefixMap)	You may use this method as another way to add custom prefixes.
CommandSettings	setDefaultPrefix(String prefix)	Use this method to set the default prefix.
CommandSettings	setHelpCommandColor(Color color)	Sets the color the help message embed will have if you use DefaultHelpCommand.
CommandSettings	setResetCooldown(boolean resetCooldown)	Sets the parameter resetCooldown.
CommandSettings	setUnknownCommandMessage(net.dv8tion.jda.core.entities.Message message)	Sets a Message that will be sent in the event of a Member using the prefix without executing any valid command.
String	toString()	Transforms this instance to a String, showing the current set options.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

VALID_PREFIX

public static final String VALID_PREFIX

A regex that only matches valid prefixes. Can be used to check user input.

See Also:

Constant Field Values

VALID_LABEL

public static final String VALID_LABEL

A regex that only matches valid labels. Can be used to check user input.

See Also:

Constant Field Values

LOGGER

protected static final org.slf4j.Logger LOGGER

The logger of this framework. This is protected.

Constructor Detail

CommandSettings

public CommandSettings(@Nonnull
                       String defaultPrefix,
                       @Nonnull
                       net.dv8tion.jda.bot.sharding.ShardManager shardManager,
                       boolean labelIgnoreCase)

This is the optional constructor in case you are sharding your bot. The parameters are validated automatically. In case of any problems (if the prefix is empty), this will throw a CommandSetException.

Parameters:

shardManager - Put your active ShardManager here. This is important for the activation of the CommandListener.

defaultPrefix - The String you will have to put before every command in order to get your command execution registered. This can later be changed.

labelIgnoreCase - Set this to true, if you want deactivate case sensitivity for the recognition of labels. E.g.: there will be no difference between the labels "foo", "FOO", "FoO" and so on.

CommandSettings

public CommandSettings(@Nonnull
                       String defaultPrefix,
                       @Nonnull
                       net.dv8tion.jda.core.JDA jda,
                       boolean labelIgnoreCase)

This is the constructor. The parameters are validated automatically. In case of any problems (if the prefix is empty), this will throw a CommandSetException.

Parameters:

jda - Put your active JDA here. This is important for the activation of the CommandListener.

defaultPrefix - The String you will have to put before every command in order to get your command execution registered. This can later be changed.

labelIgnoreCase - Set this to true, if you want deactivate case sensitivity for the recognition of labels. E.g.: there will be no difference between the labels "foo", "FOO", "FoO" and so on.

Method Detail

addHelpLabel

@Deprecated
public CommandSettings addHelpLabel(String label)

Deprecated.

This method is deprecated and thus not supported anymore. Help Commands are now registered like any other command, i.e. using CommandSettings#put. To use the default implementation of the help command, register an instance of DefaultHelpCommand.

Method to add one help label.

Parameters:

label - The label to add.

Returns:

The current object. This is to use fluent interface.

Throws:

CommandSetException - if the given label is invalid (contains spaces)

See Also:

DefaultHelpCommand

addHelpLabels

@Deprecated
public CommandSettings addHelpLabels(@Nonnull
                                     String... labels)

Deprecated.

This method is deprecated and thus not supported anymore. Help Commands are now registered like any other command, i.e. using CommandSettings#put. To use the default implementation of the help command, register an instance of DefaultHelpCommand.

Use this method to add help labels. This will only work if you instantiated this class with the parameter useHelpCommand as true.

Parameters:

labels - One or more labels which may later be called by members to list all commands or to show info about one specific command.

Returns:

The current object. This is to use fluent interface.

See Also:

DefaultHelpCommand

addHelpLabels

@Deprecated
public CommandSettings addHelpLabels(@Nonnull
                                     Collection<String> labels)

Deprecated.

This method is deprecated and thus not supported anymore. Help Commands are now registered like any other command, i.e. using CommandSettings#put. To use the default implementation of the help command, register an instance of DefaultHelpCommand.

Adds multiple labels from a String Set.

Parameters:

labels - A Set which contains the labels you want to add.

Returns:

The current object. This is to use fluent interface.

Throws:

CommandSetException - if one of the labels is not a valid label.

See Also:

DefaultHelpCommand

removeHelpLabel

@Deprecated
public boolean removeHelpLabel(String label)

Deprecated.

This method is deprecated and thus not supported anymore. Help commands are now removed like any other command, using CommandSettings#remove.

This method removes one specific help label from the help label Set.

Parameters:

label - The label to remove.

Returns:

true, if the label was successfully removed. False, if not.

removeHelpLabels

@Deprecated
public boolean removeHelpLabels(@Nonnull
                                String... labels)

Deprecated.

This method is deprecated and thus not supported anymore. Help commands are now removed like any other command, using CommandSettings#remove.

This can be used to remove some help labels, but not all of them.

Parameters:

labels - The help labels to remove.

Returns:

true, if every label was successfully removed. false, if one of the given labels does not exist and thus was not removed.

removeHelpLabels

@Deprecated
public boolean removeHelpLabels(@Nonnull
                                Collection<String> labels)

Deprecated.

This method is deprecated and thus not supported anymore. Help commands are now removed like any other command, using CommandSettings#remove.

Removes all labels from a Set.

Parameters:

labels - The Set of labels that are to be removed.

Returns:

true, if every label was successfully removed. false, if one of the given labels does not exist and thus was not removed.

clearHelpLabels

@Deprecated
public CommandSettings clearHelpLabels()

Deprecated.

This method is deprecated and thus not supported anymore. Help commands are now removed like any other command, using CommandSettings#remove.

This can be used to deactivate the help labels. Removes every help label.

Returns:

The current object. This is to use fluent interface.

addChannelToBlacklist

public CommandSettings addChannelToBlacklist(long channelId)

Adds a given channel to the blacklist (meaning commands can not be executed in there).

Parameters:

channelId - the id of the channel to be blacklisted.

Returns:

The current object. This is to use fluent interface.

addChannelsToBlacklist

public CommandSettings addChannelsToBlacklist(long... channelIds)

Adds multiple channels to the blacklist.

Parameters:

channelIds - multiple ids or an array of ids to be added.

Returns:

The current object. This is to use fluent interface.

addChannelsToBlacklist

public CommandSettings addChannelsToBlacklist(Collection<Long> channelIds)

Adds multiple channels to the blacklist.

Parameters:

channelIds - A Collection of channel ids to be added.

Returns:

The current object. This is to use fluent interface.

removeChannelFromBlacklist

public boolean removeChannelFromBlacklist(long channelId)

Removes one channel from the blacklist.

Parameters:

channelId - the id of the channel to remove.

Returns:

true, if this was successful, false, if not.

removeChannelsFromBlacklist

public boolean removeChannelsFromBlacklist(long... channelIds)

Removes one or more channels from the blacklist.

Parameters:

channelIds - The ids of the channels to remove.

Returns:

true, if this was successful, false, if not.

removeChannelsFromBlackList

public boolean removeChannelsFromBlackList(Collection<Long> channelIds)

Removes a given Collection of channel ids from the blacklist.

Parameters:

channelIds - the Collection to remove.

Returns:

true, if this was successful, false, if not.

clearBlacklist

public CommandSettings clearBlacklist()

Clears the blacklist so that no channel is blacklisted anymore.

Returns:

The current object. This is to use fluent interface.

put

public CommandSettings put(@Nonnull
                           ICommand executor,
                           String label)

Use this method to add commands from your project. Every command which is supposed to be active should be added by this.

The two parameters will be put in a HashMap which is used by the API to notice commands.

Parameters:

label - The label which describes your command, i.e. the string after the prefix [prefix][label].

executor - An instance of your command class which implements ICommand.

Returns:

The current object. This is to use fluent interface.

Throws:

CommandSetException - If the label is empty or consists of multiple words.

put

public CommandSettings put(@Nonnull
                           ICommand executor,
                           @Nonnull
                           String... labels)

Use this method to add commands with aliases.

Works like put(ICommand, String) but adds multiple labels to the same command.

Parameters:

executor - An instance of your command class which implements ICommand.

labels - One or more labels. This will throw a CommandSetException, if the label is empty or contains spaces.

Returns:

The current object. This is to use fluent interface.

Throws:

CommandSetException - If one label is empty or consists of multiple words

put

public CommandSettings put(@Nonnull
                           ICommand executor,
                           @Nonnull
                           Collection<String> labels)

Use this method to add commands with aliases from a Set. This is not much different from the put-method with Varargs.

Parameters:

executor - An instance of your command class which implements ICommand.

labels - One or more labels. This will throw a CommandSetException, if the label is empty or contains spaces.

Returns:

The current object. This is to use fluent interface.

Throws:

CommandSetException - if one label is empty or contains spaces.

remove

public boolean remove(String label)

Use this method to remove existing commands.

Parameters:

label - The label of the command to remove.

Returns:

true, if the label was successfully removed. false, if the given label doesn't exist.

remove

public boolean remove(@Nonnull
                      String... labels)

Use this method to remove more than one command at a time.

Parameters:

labels - One or more labels to remove

Returns:

true, if every label was successfully removed. false, if one of the given labels does not exist and thus was not removed.

remove

public boolean remove(@Nonnull
                      Collection<String> labels)

Removes every label that is in the given Collection.

Parameters:

labels - The labels to remove.

Returns:

true, if every label was successfully removed. False, if not (e.g. the label didn't exist)

clearCommands

public CommandSettings clearCommands()

Clears all commands.

Returns:

The current object. This is to use fluent interface.

clear

public CommandSettings clear()

Resets this whole instance by clearing the commands and setting everything to how it was at the beginning. This instance will also be deactivated if it is not already.
Values that were assigned in the constructor will keep their current value.

Returns:

The current object. This is to use fluent interface.

setDefaultPrefix

public CommandSettings setDefaultPrefix(@Nonnull
                                        String prefix)

Use this method to set the default prefix.

Parameters:

prefix - The prefix to set. In case the given String is empty, this will throw a CommandSetException.

Returns:

The current object. This is to use fluent interface.

Throws:

CommandSetException - if a non-null prefix does not match the requirements for a valid prefix.

setUnknownCommandMessage

public CommandSettings setUnknownCommandMessage(@Nullable
                                                net.dv8tion.jda.core.entities.Message message)

Sets a Message that will be sent in the event of a Member using the prefix without executing any valid command. By default, it is null. If it is null, no Message will be sent.

Parameters:

message - Nullable Message object that will be wrapped in a new MessageBuilder to prevent the usage of already sent Messages. If this is null, the message is deactivated.

Returns:

The current object. This is to use fluent interface.

See Also:

MessageBuilder

setCustomPrefix

public CommandSettings setCustomPrefix(long guildId,
                                       @Nullable
                                       String prefix)

Use this method to add a custom command prefix to a guild. This will only work if you instantiated this class with useCustomPrefixes set to true. You can remove the custom prefix from a guild by setting its prefix to null.

Parameters:

guildId - The guild id as a long.

prefix - The nullable prefix to be set.

Returns:

The current object. This is to use fluent interface.

Throws:

CommandSetException - if a non-null prefix does not match the requirements for a valid prefix.

setCustomPrefixes

public CommandSettings setCustomPrefixes(@Nonnull
                                         Map<Long,String> guildIdPrefixMap)

You may use this method as another way to add custom prefixes. This might be useful if you have many guilds to set prefixes for, because this bulk adds the Map parameter.

Parameters:

guildIdPrefixMap - A Map which contains the prefix for each guild to add. Key: guild ID (Long), Value: prefix (String)

Returns:

The current object. This is to use fluent interface.

Throws:

CommandSetException - if one of the prefixes is not valid.

clearCustomPrefixes

public CommandSettings clearCustomPrefixes()

Removes all entries from the prefix map, resetting every custom prefix.

Returns:

The current object. This is to use fluent interface.

setCooldown

public CommandSettings setCooldown(long msCooldown)

Sets the cooldown for this instance of settings. If someone executes a command before the cooldown has expired, it won't be called.

Parameters:

msCooldown - the cooldown in milliseconds.

Returns:

The current object. This is to use fluent interface.

setResetCooldown

public CommandSettings setResetCooldown(boolean resetCooldown)

Sets the parameter resetCooldown. Should be used in combination with the cooldown function of this API. By default, this is false.

Parameters:

resetCooldown - True: The command cooldown is reset on each attempt to execute a command. E.g.: A User executes an command and gets a 10 second cooldown. If he tries to execute another command within these 10 seconds, the command isn't executed and the cooldown is at 10 seconds again.

False: Once the cooldown is activated, it will not be reset by further attempts to execute commands.

Returns:

The current object. This is to use fluent interface.

setBotExecution

public CommandSettings setBotExecution(boolean botExecution)

Setter for the field botExecution. Decides whether bots may execute commands. By default, this is NOT the case.

Parameters:

botExecution - true, if you want to allow bots to execute commands. false, if not.

Returns:

The current object. This is to use fluent interface.

setHelpCommandColor

public CommandSettings setHelpCommandColor(@Nullable
                                           Color color)

Sets the color the help message embed will have if you use DefaultHelpCommand. By default, it will always be the color of the self member.

Parameters:

color - The color to set. To set this to self member color, set it to null.

Returns:

The current object. This is to use fluent interface.

See Also:

DefaultHelpCommand

activate

public void activate()

Sets the prefix and the command HashMap for the rest of the API. This is the last method to call when having finished setting up your commands.

Note that activating multiple CommandSettings may cause problems. You can do this to use multiple prefixes, but it is not recommended.

This method is important to call because otherwise no command will be registered by the internal command listener.

Throws:

CommandSetException - if you already activated this instance.

deactivate

public void deactivate()

Deactivates the current CommandSettings by removing the command listener from jda. The CommandSettings can be activated again by using activate().

Throws:

CommandSetException - if you either did not activate this instance or already deactivated it.

getPrefix

public String getPrefix(long guildId)

Use this method to get the prefix for a specific guild.

Parameters:

guildId - The id of the guild to check.

Returns:

the default prefix, if there is no custom prefix set for the given guild id. Otherwise, it returns the custom prefix.

getPrefix

public String getPrefix()

Use this method to get the default prefix.

Returns:

default prefix set in the constructor or the method setDefaultPrefix(String).

getBlacklistedChannels

public Set<Long> getBlacklistedChannels()

Use this to get the blacklisted channels.

Returns:

an unmodifiable Set with all blacklisted channels.

isBlacklisted

public boolean isBlacklisted(long channelId)

Returns whether the given channel id is blacklisted.

Parameters:

channelId - The id of the channel to check for.

Returns:

true, if the blacklist Set contains this id. False, if not.

getLabelSet

public Set<String> getLabelSet()

Returns every registered label in a Set. Note that in case you activated isLabelIgnoreCase, every label in there will be in lower case. Adding or removing something will not have any effect. This can primarily be used to iterate over the labels.

Returns:

an unmodifiable Set of labels.

getLabels

public Set<String> getLabels(ICommand command)

Returns every registered label for an ICommand instance in an immutable Set. Note that in case you activated isLabelIgnoreCase, every label in there will be in lower case. Adding or removing something will not have any effect. This can primarily be used to get a command's aliases.

Parameters:

command - The ICommand instance to get the labels from

Returns:

an unmodifiable Set of labels.

getHelpLabelSet

@Deprecated
public Set<String> getHelpLabelSet()

Deprecated.

This method is deprecated and not supported in this version anymore. It will be removed in a future release. Help labels can now be retrieved with CommandSettings#getLabels(ICommand).

Returns all of the registered help labels.

Returns:

an unmodifiable Set of Strings that are registered as help labels.

isActivated

public boolean isActivated()

Returns whether this instance is activated or not.

Returns:

true, if it is, false, if not.

getHelpColor

public Color getHelpColor()

Returns the help color for DefaultHelpCommand.

Returns:

possibly-null java.awt.Color.

getCooldown

public long getCooldown()

Returns the currently set cooldown for this instance.

Returns:

The cooldown in milliseconds.

isLabelIgnoreCase

public boolean isLabelIgnoreCase()

Returns whether command labels are case insensitive on this instance of CommandSettings.

Returns:

true, if ignore case for labels is activated. False, if not.

isResetCooldown

public boolean isResetCooldown()

Returns whether the cooldown will be reset for each execution attempt. See the setter of this for more.

Returns:

True, if the cooldown is reset each time. False, if not.

botsMayExecute

public boolean botsMayExecute()

Returns whether bot execution is enabled.

Returns:

True, if bots may execute commands. False, if not.

toString

public String toString()

Transforms this instance to a String, showing the current set options.

Overrides:

toString in class Object

Returns:

This instance as a String.

getUnknownCommandMessage

protected net.dv8tion.jda.core.entities.Message getUnknownCommandMessage()

getCommands

protected Map<String,ICommand> getCommands()