Package net.dv8tion.jda.api.interactions.commands.build

Class OptionData

java.lang.Object

net.dv8tion.jda.api.interactions.commands.build.OptionData

All Implemented Interfaces:

SerializableData

public class OptionData
extends Object
implements SerializableData

Builder for a Slash-Command option.

Field Summary

Fields

Modifier and Type	Field	Description
static final int	MAX_CHOICE_NAME_LENGTH	The maximum length of the name of Command Option Choice names
static final int	MAX_CHOICE_VALUE_LENGTH	The maximum length a String value for a choice can be.
static final int	MAX_CHOICES	The total amount of choices you can set.
static final int	MAX_DESCRIPTION_LENGTH	The maximum length the description of an option can be.
static final int	MAX_NAME_LENGTH	The maximum length the name of an option can be.
static final double	MAX_POSITIVE_NUMBER	The highest positive amount Discord allows the NUMBER type to be.
static final int	MAX_STRING_OPTION_LENGTH	The maximum length for a String option.
static final double	MIN_NEGATIVE_NUMBER	The largest negative amount Discord allows the NUMBER type to be.

Constructor Summary

Constructors

Constructor	Description
OptionData(OptionType type, String name, String description)	Create an option builder.
OptionData(OptionType type, String name, String description, boolean isRequired)	Create an option builder.
OptionData(OptionType type, String name, String description, boolean isRequired, boolean isAutoComplete)	Create an option builder.

Method Summary

Modifier and Type	Method	Description
OptionData	addChoice(String name, double value)	Add a predefined choice for this option.
OptionData	addChoice(String name, long value)	Add a predefined choice for this option.
OptionData	addChoice(String name, String value)	Add a predefined choice for this option.
OptionData	addChoices(Collection<? extends Command.Choice> choices)	Adds up to 25 predefined choices for this option.
OptionData	addChoices(Command.Choice... choices)	Adds up to 25 predefined choices for this option.
static OptionData	fromData(DataObject json)	Parses the provided serialization back into an OptionData instance.
static OptionData	fromOption(Command.Option option)	Converts the provided Command.Option into a OptionData instance.
EnumSet<ChannelType>	getChannelTypes()	The ChannelTypes this option is restricted to.
List<Command.Choice>	getChoices()	The choices for this option.
String	getDescription()	The description for this option
LocalizationMap	getDescriptionLocalizations()	The localizations of this option's description for various languages.
Integer	getMaxLength()	The maximum length for strings which can be provided for this option.
Number	getMaxValue()	The maximum value which can be provided for this option.
Integer	getMinLength()	The minimum length for strings which can be provided for this option.
Number	getMinValue()	The minimum value which can be provided for this option.
String	getName()	The name for this option
LocalizationMap	getNameLocalizations()	The localizations of this option's name for various languages.
OptionType	getType()	The OptionType for this option
boolean	isAutoComplete()	Whether this option supports auto-complete interactions via CommandAutoCompleteInteractionEvent.
boolean	isRequired()	Whether this option is required.
OptionData	setAutoComplete(boolean autoComplete)	Configure whether this option should support auto-complete interactions via CommandAutoCompleteInteractionEvent.
OptionData	setChannelTypes(Collection<ChannelType> channelTypes)	Configure the ChannelTypes to restrict this option to.
OptionData	setChannelTypes(ChannelType... channelTypes)	Configure the ChannelTypes to restrict this option to.
OptionData	setDescription(String description)	Configure the description
OptionData	setDescriptionLocalization(DiscordLocale locale, String description)	Sets a language-specific localization of this option's description.
OptionData	setDescriptionLocalizations(Map<DiscordLocale,String> map)	Sets multiple language-specific localizations of this option's description.
OptionData	setMaxLength(int maxLength)	Configure the maximum length for strings which can be provided for this option.
OptionData	setMaxValue(double value)	Configure the maximal value which can be provided for this option.
OptionData	setMaxValue(long value)	Configure the maximal value which can be provided for this option.
OptionData	setMinLength(int minLength)	Configure the minimum length for strings which can be provided for this option.
OptionData	setMinValue(double value)	Configure the minimal value which can be provided for this option.
OptionData	setMinValue(long value)	Configure the minimal value which can be provided for this option.
OptionData	setName(String name)	Configure the name
OptionData	setNameLocalization(DiscordLocale locale, String name)	Sets a language-specific localization of this option's name.
OptionData	setNameLocalizations(Map<DiscordLocale,String> map)	Sets multiple language-specific localizations of this option's name.
OptionData	setRequired(boolean required)	Configure whether the user must set this option.
OptionData	setRequiredLength(int minLength, int maxLength)	Configure the minimum and maximum length for strings which can be provided for this option.
OptionData	setRequiredRange(double minValue, double maxValue)	Configure the minimal and maximal value which can be provided for this option.
OptionData	setRequiredRange(long minValue, long maxValue)	Configure the minimal and maximal value which can be provided for this option.
DataObject	toData()	Serialized DataObject for this object.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

MAX_POSITIVE_NUMBER

public static final double MAX_POSITIVE_NUMBER

The highest positive amount Discord allows the NUMBER type to be.

See Also:

• Constant Field Values

MIN_NEGATIVE_NUMBER

public static final double MIN_NEGATIVE_NUMBER

The largest negative amount Discord allows the NUMBER type to be.

See Also:

• Constant Field Values

MAX_NAME_LENGTH

public static final int MAX_NAME_LENGTH

The maximum length the name of an option can be.

See Also:

• Constant Field Values

MAX_CHOICE_NAME_LENGTH

public static final int MAX_CHOICE_NAME_LENGTH

The maximum length of the name of Command Option Choice names

See Also:

• Constant Field Values

MAX_DESCRIPTION_LENGTH

public static final int MAX_DESCRIPTION_LENGTH

The maximum length the description of an option can be.

See Also:

• Constant Field Values

MAX_CHOICE_VALUE_LENGTH

public static final int MAX_CHOICE_VALUE_LENGTH

The maximum length a String value for a choice can be.

See Also:

• Constant Field Values

MAX_CHOICES

public static final int MAX_CHOICES

The total amount of choices you can set.

See Also:

• Constant Field Values

MAX_STRING_OPTION_LENGTH

public static final int MAX_STRING_OPTION_LENGTH

The maximum length for a String option.

See Also:

• Constant Field Values

Constructor Details

OptionData

public OptionData(@Nonnull
 OptionType type,
 @Nonnull
 String name,
 @Nonnull
 String description)

Create an option builder.
This option is not required by default.

Parameters:

type - The OptionType

name - The option name, up to 32 alphanumeric (with dash) lowercase characters, as defined by MAX_NAME_LENGTH

description - The option description, up to 100 characters, as defined by MAX_DESCRIPTION_LENGTH

Throws:

IllegalArgumentException -

• If type is null
• If type is UNKNOWN
• If name is not alphanumeric (with dash), lowercase and between 1 and 32 characters long
• If description is not between 1 and 100 characters long

OptionData

public OptionData(@Nonnull
 OptionType type,
 @Nonnull
 String name,
 @Nonnull
 String description,
 boolean isRequired)

Create an option builder.

Parameters:

type - The OptionType

name - The option name, up to 32 alphanumeric (with dash) lowercase characters, as defined by MAX_NAME_LENGTH

description - The option description, up to 100 characters, as defined by MAX_DESCRIPTION_LENGTH

isRequired - True, if this option is required

Throws:

IllegalArgumentException -

• If type is null
• If type is UNKNOWN
• If name is not alphanumeric (with dash), lowercase and between 1 and 32 characters long
• If description is not between 1 and 100 characters long

OptionData

public OptionData(@Nonnull
 OptionType type,
 @Nonnull
 String name,
 @Nonnull
 String description,
 boolean isRequired,
 boolean isAutoComplete)

Create an option builder.

Parameters:

type - The OptionType

name - The option name, up to 32 alphanumeric (with dash) lowercase characters, as defined by MAX_NAME_LENGTH

description - The option description, up to 100 characters, as defined by MAX_DESCRIPTION_LENGTH

isRequired - True, if this option is required

isAutoComplete - True, if auto-complete should be supported (requires OptionType.canSupportChoices())

Throws:

IllegalArgumentException -

• If type is null
• If type is UNKNOWN, SUB_COMMAND, or SUB_COMMAND_GROUP
• If name is not alphanumeric (with dash), lowercase and between 1 and 32 characters long
• If description is not between 1 and 100 characters long
• If OptionType.canSupportChoices() is false and isAutoComplete is true

Method Details

getType

@Nonnull
public OptionType getType()

The OptionType for this option

Returns:

The OptionType

getName

@Nonnull
public String getName()

The name for this option

Returns:

The name

getNameLocalizations

@Nonnull
public LocalizationMap getNameLocalizations()

The localizations of this option's name for various languages.

Returns:

The LocalizationMap containing the mapping from DiscordLocale to the localized name

getDescription

@Nonnull
public String getDescription()

The description for this option

Returns:

The description

getDescriptionLocalizations

@Nonnull
public LocalizationMap getDescriptionLocalizations()

The localizations of this option's description for various languages.

Returns:

The LocalizationMap containing the mapping from DiscordLocale to the localized description

isRequired

public boolean isRequired()

Whether this option is required.
This can be configured with setRequired(boolean).

Required options must always be set by the command invocation.

Returns:

True, if this option is required

isAutoComplete

public boolean isAutoComplete()

Whether this option supports auto-complete interactions via CommandAutoCompleteInteractionEvent.

Returns:

True, if this option supports auto-complete

getChannelTypes

@Nonnull
public EnumSet<ChannelType> getChannelTypes()

The ChannelTypes this option is restricted to.
This is empty if the option is not of type CHANNEL or not restricted to specific types.

Returns:

EnumSet of ChannelType

getMinValue

@Nullable
public Number getMinValue()

The minimum value which can be provided for this option.
This returns null if the value is not set or if the option is not of type INTEGER or NUMBER.

Returns:

The minimum value for this option

getMaxValue

@Nullable
public Number getMaxValue()

The maximum value which can be provided for this option.
This returns null if the value is not set or if the option is not of type INTEGER or NUMBER.

Returns:

The maximum value for this option

getMinLength

@Nullable
public Integer getMinLength()

The minimum length for strings which can be provided for this option.
This returns null if the value is not set or if the option is not of type STRING.

Returns:

The minimum length for strings for this option or null

getMaxLength

@Nullable
public Integer getMaxLength()

The maximum length for strings which can be provided for this option.
This returns null if the value is not set or if the option is not of type STRING.

Returns:

The maximum length for strings for this option or null

getChoices

@Nonnull
public List<Command.Choice> getChoices()

The choices for this option.
This is empty by default and can only be configured for specific option types.

Returns:

Immutable list of Choices

See Also:

• addChoice(String, long)
• addChoice(String, String)

setName

@Nonnull
public OptionData setName(@Nonnull
 String name)

Configure the name

Parameters:

name - The lowercase alphanumeric (with dash) name, 1-32 characters long

Returns:

The OptionData instance, for chaining

Throws:

IllegalArgumentException - If the name is null, empty, not alphanumeric, or not between 1-32 characters long, as defined by MAX_NAME_LENGTH

setNameLocalization

@Nonnull
public OptionData setNameLocalization(@Nonnull
 DiscordLocale locale,
 @Nonnull
 String name)

Sets a language-specific localization of this option's name.

Parameters:

locale - The locale to associate the translated name with

name - The translated name to put

Returns:

This builder instance, for chaining

Throws:

IllegalArgumentException -

• If the locale is null
• If the name is null
• If the locale is DiscordLocale.UNKNOWN
• If the name does not pass the corresponding name check

setNameLocalizations

@Nonnull
public OptionData setNameLocalizations(@Nonnull
 Map<DiscordLocale,String> map)

Sets multiple language-specific localizations of this option's name.

Parameters:

map - The map from which to transfer the translated names

Returns:

This builder instance, for chaining

Throws:

IllegalArgumentException -

• If the map is null
• If the map contains an DiscordLocale.UNKNOWN key
• If the map contains a name which does not pass the corresponding name check

setDescription

@Nonnull
public OptionData setDescription(@Nonnull
 String description)

Configure the description

Parameters:

description - The description, 1-100 characters, as defined by MAX_DESCRIPTION_LENGTH

Returns:

The OptionData instance, for chaining

Throws:

IllegalArgumentException - If the name is null, empty, or longer than 100, as defined by MAX_DESCRIPTION_LENGTH

setDescriptionLocalization

@Nonnull
public OptionData setDescriptionLocalization(@Nonnull
 DiscordLocale locale,
 @Nonnull
 String description)

Sets a language-specific localization of this option's description.

Parameters:

locale - The locale to associate the translated description with

description - The translated description to put

Returns:

This builder instance, for chaining

Throws:

IllegalArgumentException -

• If the locale is null
• If the description is null
• If the locale is DiscordLocale.UNKNOWN
• If the description does not pass the corresponding description check

setDescriptionLocalizations

@Nonnull
public OptionData setDescriptionLocalizations(@Nonnull
 Map<DiscordLocale,String> map)

Sets multiple language-specific localizations of this option's description.

Parameters:

map - The map from which to transfer the translated descriptions

Returns:

This builder instance, for chaining

Throws:

IllegalArgumentException -

• If the map is null
• If the map contains an DiscordLocale.UNKNOWN key
• If the map contains a description which does not pass the corresponding description check

setRequired

@Nonnull
public OptionData setRequired(boolean required)

Configure whether the user must set this option.
Required options must always be filled out when using the command.

Parameters:

required - True, if this option is required

Returns:

The OptionData instance, for chaining

setAutoComplete

@Nonnull
public OptionData setAutoComplete(boolean autoComplete)

Configure whether this option should support auto-complete interactions via CommandAutoCompleteInteractionEvent.

This is only supported for options which support choices. See OptionType.canSupportChoices().

Parameters:

autoComplete - True, if auto-complete should be supported

Returns:

The OptionData instance, for chaining

Throws:

IllegalStateException - If this option is already configured to use choices or the option type does not support auto-complete

setChannelTypes

@Nonnull
public OptionData setChannelTypes(@Nonnull
 ChannelType... channelTypes)

Configure the ChannelTypes to restrict this option to. This only applies to options of type CHANNEL.

Parameters:

channelTypes - The ChannelTypes to restrict this option to or empty array to accept all ChannelTypes

Returns:

The OptionData instance, for chaining

Throws:

IllegalArgumentException -

• If type of this option is not CHANNEL
• If channelTypes contain null
• If channelTypes contains non-guild channels

setChannelTypes

@Nonnull
public OptionData setChannelTypes(@Nonnull
 Collection<ChannelType> channelTypes)

Configure the ChannelTypes to restrict this option to. This only applies to options of type CHANNEL.

Parameters:

channelTypes - The ChannelTypes to restrict this option to or empty collection to accept all ChannelTypes

Returns:

The OptionData instance, for chaining

Throws:

IllegalArgumentException -

• If type of this option is not CHANNEL
• If channelTypes is null
• If channelTypes contain null
• If channelTypes contains non-guild channels

setMinValue

@Nonnull
public OptionData setMinValue(long value)

Configure the minimal value which can be provided for this option.

Parameters:

value - The minimal value which can be provided for this option.

Returns:

The OptionData instance, for chaining

Throws:

IllegalArgumentException -

• If type of this option is not INTEGER or NUMBER
• If value is less than MIN_NEGATIVE_NUMBER

setMinValue

@Nonnull
public OptionData setMinValue(double value)

Configure the minimal value which can be provided for this option.

Parameters:

value - The minimal value which can be provided for this option.

Returns:

The OptionData instance, for chaining

Throws:

IllegalArgumentException -

• If type of this option is not NUMBER
• If value is less than MIN_NEGATIVE_NUMBER

setMaxValue

@Nonnull
public OptionData setMaxValue(long value)

Configure the maximal value which can be provided for this option.

Parameters:

value - The maximal value which can be provided for this option.

Returns:

The OptionData instance, for chaining

Throws:

IllegalArgumentException -

• If type of this option is not INTEGER or NUMBER
• If value is greater than MAX_POSITIVE_NUMBER

setMaxValue

@Nonnull
public OptionData setMaxValue(double value)

Configure the maximal value which can be provided for this option.

Parameters:

value - The maximal value which can be provided for this option.

Returns:

The OptionData instance, for chaining

Throws:

IllegalArgumentException -

• If type of this option is not NUMBER
• If value is greater than MAX_POSITIVE_NUMBER

setRequiredRange

@Nonnull
public OptionData setRequiredRange(long minValue,
 long maxValue)

Configure the minimal and maximal value which can be provided for this option.

Parameters:

minValue - The minimal value which can be provided for this option.

maxValue - The maximal value which can be provided for this option.

Returns:

The OptionData instance, for chaining

Throws:

IllegalArgumentException -

• If type of this option is not INTEGER or NUMBER
• If minValue is less than or not equal to MIN_NEGATIVE_NUMBER
• If maxValue is greater than MAX_POSITIVE_NUMBER

setRequiredRange

@Nonnull
public OptionData setRequiredRange(double minValue,
 double maxValue)

Configure the minimal and maximal value which can be provided for this option.

Parameters:

minValue - The minimal value which can be provided for this option.

maxValue - The maximal value which can be provided for this option.

Returns:

The OptionData instance, for chaining

Throws:

IllegalArgumentException -

• If type of this option is not NUMBER
• If minValue is less than or not equal to MIN_NEGATIVE_NUMBER
• If maxValue is greater than MAX_POSITIVE_NUMBER

setMinLength

@Nonnull
public OptionData setMinLength(int minLength)

Configure the minimum length for strings which can be provided for this option.

Parameters:

minLength - The minimum length for strings which can be provided for this option.

Returns:

The OptionData instance, for chaining

Throws:

IllegalArgumentException -

• If type of this option is not STRING
• If minLength is not positive

setMaxLength

@Nonnull
public OptionData setMaxLength(int maxLength)

Configure the maximum length for strings which can be provided for this option.

Parameters:

maxLength - The maximum length for strings which can be provided for this option.

Returns:

The OptionData instance, for chaining

Throws:

IllegalArgumentException -

• If type of this option is not STRING
• If maxLength is not positive or greater than 6000

setRequiredLength

@Nonnull
public OptionData setRequiredLength(int minLength,
 int maxLength)

Configure the minimum and maximum length for strings which can be provided for this option.

Parameters:

minLength - The minimum length for strings which can be provided for this option.

maxLength - The maximum length for strings which can be provided for this option.

Returns:

The OptionData instance, for chaining

Throws:

IllegalArgumentException -

• If type of this option is not STRING
• If minLength is greater than maxLength

addChoice

@Nonnull
public OptionData addChoice(@Nonnull
 String name,
 double value)

Add a predefined choice for this option.
The user can only provide one of the choices and cannot specify any other value.

Parameters:

name - The name used in the client, up to 100 characters long, as defined by MAX_CHOICE_NAME_LENGTH

value - The value received in OptionMapping

Returns:

The OptionData instance, for chaining

Throws:

IllegalArgumentException -

• If name is null, empty, or greater than 100 characters long
• If value is less than MIN_NEGATIVE_NUMBER or greater than MAX_POSITIVE_NUMBER
• If adding this choice would exceed 25 choices, as defined by MAX_CHOICES
• If the OptionType is not OptionType.NUMBER
• If the option is auto-complete enabled

addChoice

@Nonnull
public OptionData addChoice(@Nonnull
 String name,
 long value)

Add a predefined choice for this option.
The user can only provide one of the choices and cannot specify any other value.

Parameters:

name - The name used in the client

value - The value received in OptionMapping

Returns:

The OptionData instance, for chaining

Throws:

IllegalArgumentException -

• If name is null, empty, or greater than 100 characters long
• If value is less than MIN_NEGATIVE_NUMBER or greater than MAX_POSITIVE_NUMBER
• If adding this choice would exceed 25 choices, as defined by MAX_CHOICES
• If the OptionType is not OptionType.INTEGER
• If the option is auto-complete enabled

addChoice

@Nonnull
public OptionData addChoice(@Nonnull
 String name,
 @Nonnull
 String value)

Add a predefined choice for this option.
The user can only provide one of the choices and cannot specify any other value.

Parameters:

name - The name used in the client

value - The value received in OptionMapping

Returns:

The OptionData instance, for chaining

Throws:

IllegalArgumentException -

• If name is null, empty, or greater than 100 characters long
• If value is less than MIN_NEGATIVE_NUMBER or greater than MAX_POSITIVE_NUMBER
• If adding this choice would exceed 25 choices, as defined by MAX_CHOICES
• If the OptionType is not OptionType.STRING
• If the option is auto-complete enabled

addChoices

@Nonnull
public OptionData addChoices(@Nonnull
 Command.Choice... choices)

Adds up to 25 predefined choices for this option.
The user can only provide one of the choices and cannot specify any other value.

Parameters:

choices - The choices to add

Returns:

The OptionData instance, for chaining

Throws:

IllegalArgumentException -

• If the OptionType does not support choices
• If the provided choices are null
• If the amount of choices provided, when combined with the already set choices, would be greater than 25, as defined by MAX_CHOICES
• If the OptionType of the choices is not either OptionType.INTEGER, OptionType.STRING or OptionType.NUMBER
• If the option is auto-complete enabled

addChoices

@Nonnull
public OptionData addChoices(@Nonnull
 Collection<? extends Command.Choice> choices)

Adds up to 25 predefined choices for this option.
The user can only provide one of the choices and cannot specify any other value.

Parameters:

choices - The choices to add

Returns:

The OptionData instance, for chaining

Throws:

IllegalArgumentException -

• If the OptionType does not support choices
• If the provided choices collection is null
• If the provided choices are null
• If the amount of choices provided, when combined with the already set choices, would be greater than 25, as defined by MAX_CHOICES
• If the OptionType of the choices is not either OptionType.INTEGER, OptionType.STRING or OptionType.NUMBER
• If the option is auto-complete enabled

toData

@Nonnull
public DataObject toData()

Description copied from interface: SerializableData

Serialized DataObject for this object.

Specified by:

toData in interface SerializableData

Returns:

DataObject

fromData

@Nonnull
public static OptionData fromData(@Nonnull
 DataObject json)

Parses the provided serialization back into an OptionData instance.
This is the reverse function for toData().

Parameters:

json - The serialized DataObject representing the option

Returns:

The parsed OptionData instance, which can be further configured through setters

Throws:

ParsingException - If the serialized object is missing required fields

IllegalArgumentException - If any of the values are failing the respective checks such as length

fromOption

@Nonnull
public static OptionData fromOption(@Nonnull
 Command.Option option)

Converts the provided Command.Option into a OptionData instance.

Parameters:

option - The option to convert

Returns:

An instance of OptionData

Throws:

IllegalArgumentException - If null is provided or the option has illegal configuration