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 Details

    • MAX_POSITIVE_NUMBER

      public static final double MAX_POSITIVE_NUMBER
      The highest positive amount Discord allows the NUMBER type to be.
      See Also:

    • MIN_NEGATIVE_NUMBER

      public static final double MIN_NEGATIVE_NUMBER
      The largest negative amount Discord allows the NUMBER type to be.
      See Also:

    • MAX_NAME_LENGTH

      public static final int MAX_NAME_LENGTH
      The maximum length the name of an option can be.
      See Also:

    • 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:

    • MAX_DESCRIPTION_LENGTH

      public static final int MAX_DESCRIPTION_LENGTH
      The maximum length the description of an option can be.
      See Also:

    • 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:

    • MAX_CHOICES

      public static final int MAX_CHOICES
      The total amount of choices you can set.
      See Also:

    • MAX_STRING_OPTION_LENGTH

      public static final int MAX_STRING_OPTION_LENGTH
      The maximum length for a String option.
      See Also:

  • 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 -

  • 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 @Unmodifiable 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:

    • 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 -

    • 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 -

    • 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 -

    • 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 -

    • 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 -

    • 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 -

    • 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 -

    • 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 -

    • 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 -

    • 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 -

    • 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 -

    • 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 -

    • 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 -

    • 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 -

    • 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 -

    • 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 -

    • 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 -

    • 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 -

    • 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 -

    • 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