Package net.dv8tion.jda.api.requests.restaction

Interface MessageAction

    • Method Detail

      • setDefaultMentions

        static void setDefaultMentions​(@Nullable
                               java.util.Collection<Message.MentionType> allowedMentions)
        Sets the MentionTypes that should be parsed by default. This just sets the default for all MessageActions and can be overridden on a per-action basis using AllowedMentions.allowedMentions(Collection).
        If a message is sent with an empty Set of MentionTypes, then it will not ping any User, Role or @everyone/@here, while still showing up as mention tag.

        If null is provided to this method, then all Types will be pingable (unless whitelisting via one of the mention* methods is used).

        Example

        
 // Disable EVERYONE and HERE mentions by default (to avoid mass ping)
 EnumSet<Message.MentionType> deny = EnumSet.of(Message.MentionType.EVERYONE, Message.MentionType.HERE);
 MessageAction.setDefaultMentions(EnumSet.complementOf(deny));
        Parameters:
        allowedMentions - MentionTypes that are allowed to being parsed and pinged. null to disable and allow all mentions.

      • setDefaultMentionRepliedUser

        static void setDefaultMentionRepliedUser​(boolean mention)
        Sets the default value for mentionRepliedUser(boolean)

        Default: true

        Parameters:
        mention - True, if replies should mention by default

      • isDefaultMentionRepliedUser

        static boolean isDefaultMentionRepliedUser()
        Returns the default mention behavior for replies.
        If this is true then all replies will mention the author of the target message by default. You can specify this individually with mentionRepliedUser(boolean) for each message.

        Default: true

        Returns:
        True, if replies mention by default

      • setDefaultFailOnInvalidReply

        static void setDefaultFailOnInvalidReply​(boolean fail)
        Sets the default value for failOnInvalidReply(boolean)

        Default: false

        Parameters:
        fail - True, to throw a exception if the referenced message does not exist

      • isDefaultFailOnInvalidReply

        static boolean isDefaultFailOnInvalidReply()
        Returns the default behavior for replies when the referenced message does not exist.
        If this is true then all replies will throw an exception if the referenced message does not exist. You can specify this individually with failOnInvalidReply(boolean) for each message.

        Default: false

        Returns:
        True, to throw a exception if the referenced message does not exist

      • setCheck

        @Nonnull
MessageAction setCheck​(@Nullable
                       java.util.function.BooleanSupplier checks)
        Description copied from interface: RestAction
        Sets the last-second checks before finally executing the http request in the queue.
        If the provided supplier evaluates to false or throws an exception this will not be finished. When an exception is thrown from the supplier it will be provided to the failure callback.
        Specified by:
        setCheck in interface RestAction<Message>
        Parameters:
        checks - The checks to run before executing the request, or null to run no checks
        Returns:
        The current RestAction for chaining convenience
        See Also:
        RestAction.getCheck(), RestAction.addCheck(BooleanSupplier)

      • timeout

        @Nonnull
MessageAction timeout​(long timeout,
                      @Nonnull
                      java.util.concurrent.TimeUnit unit)
        Description copied from interface: RestAction
        Timeout for this RestAction instance.
        If the request doesn't get executed within the timeout it will fail.

        When a RestAction times out, it will fail with a TimeoutException. This is the same as deadline(System.currentTimeMillis() + unit.toMillis(timeout)).

        Example

        
 action.timeout(10, TimeUnit.SECONDS) // 10 seconds from now
       .queueAfter(20, SECONDS); // request will not be executed within deadline and timeout immediately after 20 seconds
        Specified by:
        timeout in interface RestAction<Message>
        Parameters:
        timeout - The timeout to use
        unit - Unit for the timeout value
        Returns:
        The same RestAction instance with the applied timeout
        See Also:
        RestAction.setDefaultTimeout(long, TimeUnit)

      • deadline

        @Nonnull
MessageAction deadline​(long timestamp)
        Description copied from interface: RestAction
        Similar to RestAction.timeout(long, TimeUnit) but schedules a deadline at which the request has to be completed.
        If the deadline is reached, the request will fail with a TimeoutException.

        This does not mean that the request will immediately timeout when the deadline is reached. JDA will check the deadline right before executing the request or within intervals in a worker thread. This only means the request will timeout if the deadline has passed.

        Example

        
 action.deadline(System.currentTimeMillis() + 10000) // 10 seconds from now
       .queueAfter(20, SECONDS); // request will not be executed within deadline and timeout immediately after 20 seconds
        Specified by:
        deadline in interface RestAction<Message>
        Parameters:
        timestamp - Millisecond timestamp at which the request will timeout
        Returns:
        The same RestAction with the applied deadline
        See Also:
        RestAction.timeout(long, TimeUnit), RestAction.setDefaultTimeout(long, TimeUnit)

      • isEmpty

        boolean isEmpty()
        Whether this MessageAction has no values set.
        Trying to execute with isEmpty() == true will result in an IllegalStateException!

        This does not check for files!

        Returns:
        True, if no settings have been applied

      • isEdit

        boolean isEdit()
        Whether this MessageAction will be used to update an existing message.
        Returns:
        True, if this MessageAction targets an existing message

      • apply

        @Nonnull
@CheckReturnValue
MessageAction apply​(@Nullable
                    Message message)
        Applies the sendable information of the provided Message to this MessageAction settings.
        This will override all existing settings if new settings are available.

        This does not copy files!

        Parameters:
        message - The nullable Message to apply settings from
        Returns:
        Updated MessageAction for chaining convenience
        Throws:
        java.lang.IllegalArgumentException - If the message contains a MessageEmbed that exceeds the sendable character limit, see MessageEmbed.isSendable()

      • referenceById

        @Nonnull
@CheckReturnValue
MessageAction referenceById​(long messageId)
        Make the message a reply to the referenced message.
        You can only reply to messages from the same channel!
        This will mention the author of the target message. You can disable this through mentionRepliedUser(boolean).
        By default there won't be any error thrown if the referenced message does not exist. This behavior can be changed with failOnInvalidReply(boolean).

        This requires Permission.MESSAGE_HISTORY in the channel! You cannot reply to system messages such as CHANNEL_PINNED_ADD and similar.

        Parameters:
        messageId - The target message
        Returns:
        Updated MessageAction for chaining convenience
        Throws:
        java.lang.IllegalArgumentException - If the provided ID is null or not a valid snowflake
        java.lang.UnsupportedOperationException - If the provided message is from a MessageBuilder
        Since:
        4.2.1

      • referenceById

        @Nonnull
@CheckReturnValue
default MessageAction referenceById​(@Nonnull
                                    java.lang.String messageId)
        Make the message a reply to the referenced message.
        You can only reply to messages from the same channel!
        This will mention the author of the target message. You can disable this through mentionRepliedUser(boolean).
        By default there won't be any error thrown if the referenced message does not exist. This behavior can be changed with failOnInvalidReply(boolean).

        This requires Permission.MESSAGE_HISTORY in the channel! You cannot reply to system messages such as CHANNEL_PINNED_ADD and similar.

        Parameters:
        messageId - The target message
        Returns:
        Updated MessageAction for chaining convenience
        Throws:
        java.lang.IllegalArgumentException - If the provided ID is null or not a valid snowflake
        java.lang.UnsupportedOperationException - If the provided message is from a MessageBuilder
        Since:
        4.2.1

      • reference

        @Nonnull
@CheckReturnValue
default MessageAction reference​(@Nonnull
                                Message message)
        Make the message a reply to the referenced message.
        You can only reply to messages from the same channel!
        This will mention the author of the target message. You can disable this through mentionRepliedUser(boolean).
        By default there won't be any error thrown if the referenced message does not exist. This behavior can be changed with failOnInvalidReply(boolean).

        This requires Permission.MESSAGE_HISTORY in the channel! You cannot reply to system messages such as CHANNEL_PINNED_ADD and similar.

        Parameters:
        message - The target message
        Returns:
        Updated MessageAction for chaining convenience
        Throws:
        java.lang.IllegalArgumentException - If the provided message is null
        java.lang.UnsupportedOperationException - If the provided message is from a MessageBuilder
        Since:
        4.2.1

      • failOnInvalidReply

        @Nonnull
@CheckReturnValue
MessageAction failOnInvalidReply​(boolean fail)
        Whether to throw a exception if the referenced message does not exist, when replying to a message.
        This only matters in combination with reference(Message) and referenceById(long)!

        This is false by default but can be configured using setDefaultFailOnInvalidReply(boolean)!

        Parameters:
        fail - True, to throw a exception if the referenced message does not exist
        Returns:
        Updated MessageAction for chaining convenience
        Since:
        4.2.1

      • tts

        @Nonnull
@CheckReturnValue
MessageAction tts​(boolean isTTS)
        Enable/Disable Text-To-Speech for the resulting message.
        This is only relevant to MessageActions that are not isEdit() == true!
        Parameters:
        isTTS - True, if this should cause a Text-To-Speech effect when sent to the channel
        Returns:
        Updated MessageAction for chaining convenience

      • reset

        @Nonnull
@CheckReturnValue
MessageAction reset()
        Resets this MessageAction to empty state
        isEmpty() will result in true after this has been performed!

        Convenience over using content(null).nonce(null).setEmbeds(emptyList()).tts(false).override(false).clearFiles()

        Returns:
        Updated MessageAction for chaining convenience

      • content

        @Nonnull
@CheckReturnValue
MessageAction content​(@Nullable
                      java.lang.String content)
        Overrides existing content with the provided input
        The content of a Message may not exceed 2000!
        Parameters:
        content - Sets the specified content and overrides previous content or null to reset content
        Returns:
        Updated MessageAction for chaining convenience
        Throws:
        java.lang.IllegalArgumentException - If the provided content exceeds the 2000 character limit

      • setEmbeds

        @Nonnull
@CheckReturnValue
MessageAction setEmbeds​(@Nonnull
                        java.util.Collection<? extends MessageEmbed> embeds)
        Sets up to 10 MessageEmbeds that should be used for this Message. Refer to EmbedBuilder for more information.
        Parameters:
        embeds - The MessageEmbeds that should be attached to this message, Collections.emptyList() to use no embed.
        Returns:
        Updated MessageAction for chaining convenience
        Throws:
        java.lang.IllegalArgumentException - If any of the provided MessageEmbeds is not sendable according to MessageEmbed.isSendable()! If the provided MessageEmbed is an unknown implementation this operation will fail as we are unable to deserialize it.

      • setEmbeds

        @Nonnull
@CheckReturnValue
default MessageAction setEmbeds​(@Nonnull
                                MessageEmbed... embeds)
        Sets up to 10 MessageEmbeds that should be used for this Message. Refer to EmbedBuilder for more information.
        Parameters:
        embeds - The MessageEmbeds that should be attached to this message, Collections.emptyList() to use no embed.
        Returns:
        Updated MessageAction for chaining convenience
        Throws:
        java.lang.IllegalArgumentException - If any of the provided MessageEmbeds is not sendable according to MessageEmbed.isSendable()! If the provided MessageEmbed is an unknown implementation this operation will fail as we are unable to deserialize it.

      • append

        @Nonnull
@CheckReturnValue
default MessageAction append​(@Nonnull
                             java.lang.CharSequence csq)
        Specified by:
        append in interface java.lang.Appendable
        Returns:
        Updated MessageAction for chaining convenience
        Throws:
        java.lang.IllegalArgumentException - If the appended CharSequence is too big and will cause the content to exceed the 2000 character limit

      • append

        @Nonnull
@CheckReturnValue
MessageAction append​(@Nullable
                     java.lang.CharSequence csq,
                     int start,
                     int end)
        Specified by:
        append in interface java.lang.Appendable
        Returns:
        Updated MessageAction for chaining convenience
        Throws:
        java.lang.IllegalArgumentException - If the appended CharSequence is too big and will cause the content to exceed the 2000 character limit

      • append

        @Nonnull
@CheckReturnValue
MessageAction append​(char c)
        Specified by:
        append in interface java.lang.Appendable
        Returns:
        Updated MessageAction for chaining convenience
        Throws:
        java.lang.IllegalArgumentException - If the appended CharSequence is too big and will cause the content to exceed the 2000 character limit

      • appendFormat

        @Nonnull
@CheckReturnValue
default MessageAction appendFormat​(@Nonnull
                                   java.lang.String format,
                                   java.lang.Object... args)
        Applies the result of String.format(String, Object...) as content.

        For more information of formatting review the Formatter documentation!

        Parameters:
        format - The format String
        args - The arguments that should be used for conversion
        Returns:
        Updated MessageAction for chaining convenience
        Throws:
        java.lang.IllegalArgumentException - If the appended formatting is too big and will cause the content to exceed the 2000 character limit
        java.util.IllegalFormatException - If a format string contains an illegal syntax, a format specifier that is incompatible with the given arguments, insufficient arguments given the format string, or other illegal conditions. For specification of all possible formatting errors, see the Details section of the formatter class specification.

      • addFile

        @Nonnull
@CheckReturnValue
MessageAction addFile​(@Nonnull
                      java.io.InputStream data,
                      @Nonnull
                      java.lang.String name,
                      @Nonnull
                      AttachmentOption... options)
        Adds the provided InputStream as file data.
        The stream will be closed upon execution!

        To reset all files use clearFiles()

        Parameters:
        data - The InputStream that will be interpreted as file data
        name - The file name that should be used to interpret the type of the given data using the file-name extension. This name is similar to what will be visible through Message.Attachment.getFileName()
        options - Possible options to apply to this attachment, such as marking it as spoiler image
        Returns:
        Updated MessageAction for chaining convenience
        Throws:
        java.lang.IllegalStateException - If the file limit of 10 has been reached prior to calling this method
        java.lang.IllegalArgumentException - If the provided data is null or the provided name is blank or null
        InsufficientPermissionException - If this is targeting a TextChannel and the currently logged in account does not have Permission.MESSAGE_ATTACH_FILES

      • addFile

        @Nonnull
@CheckReturnValue
default MessageAction addFile​(@Nonnull
                              byte[] data,
                              @Nonnull
                              java.lang.String name,
                              @Nonnull
                              AttachmentOption... options)
        Adds the provided byte[] as file data.

        To reset all files use clearFiles()

        Parameters:
        data - The byte[] that will be interpreted as file data
        name - The file name that should be used to interpret the type of the given data using the file-name extension. This name is similar to what will be visible through Message.Attachment.getFileName()
        options - Possible options to apply to this attachment, such as marking it as spoiler image
        Returns:
        Updated MessageAction for chaining convenience
        Throws:
        java.lang.IllegalStateException - If the file limit of 10 has been reached prior to calling this method
        java.lang.IllegalArgumentException - If the provided data is null or the provided name is blank or null or if the provided data exceeds the maximum file size of the currently logged in account
        InsufficientPermissionException - If this is targeting a TextChannel and the currently logged in account does not have Permission.MESSAGE_ATTACH_FILES
        See Also:
        SelfUser.getAllowedFileSize()

      • addFile

        @Nonnull
@CheckReturnValue
default MessageAction addFile​(@Nonnull
                              java.io.File file,
                              @Nonnull
                              AttachmentOption... options)
        Adds the provided File as file data.
        Shortcut for addFile(file, file.getName()) with the same side-effects.
        Parameters:
        file - The File that will be interpreted as file data
        options - Possible options to apply to this attachment, such as marking it as spoiler image
        Returns:
        Updated MessageAction for chaining convenience
        Throws:
        java.lang.IllegalStateException - If the file limit of 10 has been reached prior to calling this method
        java.lang.IllegalArgumentException - If the provided file is null or if the provided File is bigger than the maximum file size of the currently logged in account
        InsufficientPermissionException - If this is targeting a TextChannel and the currently logged in account does not have Permission.MESSAGE_ATTACH_FILES
        See Also:
        SelfUser.getAllowedFileSize()

      • addFile

        @Nonnull
@CheckReturnValue
MessageAction addFile​(@Nonnull
                      java.io.File file,
                      @Nonnull
                      java.lang.String name,
                      @Nonnull
                      AttachmentOption... options)
        Adds the provided File as file data.

        To reset all files use clearFiles()
        This method opens a FileInputStream which will be closed by executing this action or using clearFiles()!

        Parameters:
        file - The File that will be interpreted as file data
        name - The file name that should be used to interpret the type of the given data using the file-name extension. This name is similar to what will be visible through Message.Attachment.getFileName()
        options - Possible options to apply to this attachment, such as marking it as spoiler image
        Returns:
        Updated MessageAction for chaining convenience
        Throws:
        java.lang.IllegalStateException - If the file limit of 10 has been reached prior to calling this method
        java.lang.IllegalArgumentException - If the provided file is null or the provided name is blank or null or if the provided file is bigger than the maximum file size of the currently logged in account, or if the provided file does not exist/ is not readable
        InsufficientPermissionException - If this is targeting a TextChannel and the currently logged in account does not have Permission.MESSAGE_ATTACH_FILES
        See Also:
        SelfUser.getAllowedFileSize()

      • clearFiles

        @Nonnull
@CheckReturnValue
MessageAction clearFiles​(@Nonnull
                         java.util.function.BiConsumer<java.lang.String,​java.io.InputStream> finalizer)
        Clears all previously added files
        Parameters:
        finalizer - BiConsumer useful to close remaining resources, the consumer will receive the name as a string parameter and the resource as InputStream.
        Returns:
        Updated MessageAction for chaining convenience
        See Also:
        Closeable

      • clearFiles

        @Nonnull
@CheckReturnValue
MessageAction clearFiles​(@Nonnull
                         java.util.function.Consumer<java.io.InputStream> finalizer)
        Clears all previously added files
        The clearFiles(BiConsumer) version provides the resource name for more selective operations.
        Parameters:
        finalizer - Consumer useful to close remaining resources, the consumer will receive only the resource in the form of an InputStream
        Returns:
        Updated MessageAction for chaining convenience
        See Also:
        Closeable

      • retainFilesById

        @Nonnull
@CheckReturnValue
MessageAction retainFilesById​(@Nonnull
                              java.util.Collection<java.lang.String> ids)
        Removes all attachments that are currently attached to the existing message except for the ones provided.
        For example retainFilesById(Arrays.asList("123")) would remove all attachments except for the one with the id 123.

        To remove all attachments from the message you can pass an empty list.

        Parameters:
        ids - The ids for the attachments which should be retained on the message
        Returns:
        Updated MessageAction for chaining convenience
        Throws:
        java.lang.IllegalArgumentException - If any of the ids is null or not a valid snowflake

      • retainFilesById

        @Nonnull
@CheckReturnValue
default MessageAction retainFilesById​(@Nonnull
                                      java.lang.String... ids)
        Removes all attachments that are currently attached to the existing message except for the ones provided.
        For example retainFilesById(Arrays.asList("123")) would remove all attachments except for the one with the id 123.

        To remove all attachments from the message you can pass an empty list.

        Parameters:
        ids - The ids for the attachments which should be retained on the message
        Returns:
        Updated MessageAction for chaining convenience
        Throws:
        java.lang.IllegalArgumentException - If any of the ids is null or not a valid snowflake

      • retainFilesById

        @Nonnull
@CheckReturnValue
default MessageAction retainFilesById​(long... ids)
        Removes all attachments that are currently attached to the existing message except for the ones provided.
        For example retainFilesById(Arrays.asList("123")) would remove all attachments except for the one with the id 123.

        To remove all attachments from the message you can pass an empty list.

        Parameters:
        ids - The ids for the attachments which should be retained on the message
        Returns:
        Updated MessageAction for chaining convenience
        Throws:
        java.lang.IllegalArgumentException - If any of the ids is null or not a valid snowflake

      • retainFiles

        @Nonnull
@CheckReturnValue
default MessageAction retainFiles​(@Nonnull
                                  java.util.Collection<? extends Message.Attachment> attachments)
        Removes all attachments that are currently attached to the existing message except for the ones provided.
        For example retainFiles(message.getAttachments().subList(1, message.getAttachments().size())) would only remove the first attachment from the message.

        To remove all attachments from the message you can pass an empty list.

        Parameters:
        attachments - The attachments which should be retained on the message
        Returns:
        Updated MessageAction for chaining convenience
        Throws:
        java.lang.IllegalArgumentException - If any of the ids is null or not a valid snowflake

      • setActionRows

        @Nonnull
@CheckReturnValue
default MessageAction setActionRows​(@Nonnull
                                    java.util.Collection<? extends ActionRow> rows)
        Set the action rows for the message.
        Parameters:
        rows - The new action rows
        Returns:
        Updated MessageAction for chaining convenience
        Throws:
        java.lang.IllegalArgumentException - If null is provided or more than 5 actions rows are provided

      • setActionRows

        @Nonnull
@CheckReturnValue
MessageAction setActionRows​(@Nonnull
                            ActionRow... rows)
        Set the action rows for the message.
        Parameters:
        rows - The new action rows
        Returns:
        Updated MessageAction for chaining convenience
        Throws:
        java.lang.IllegalArgumentException - If null is provided or more than 5 actions rows are provided

      • setActionRow

        @Nonnull
@CheckReturnValue
default MessageAction setActionRow​(@Nonnull
                                   java.util.Collection<? extends Component> components)
        Create one row of up to 5 interactive message components.
        This is identical to setActionRows(ActionRow.of(components))
        Parameters:
        components - The components for this action row
        Returns:
        Updated MessageAction for chaining convenience
        Throws:
        java.lang.IllegalArgumentException - If anything is null, empty, or an invalid number of components are provided
        See Also:
        ActionRow.of(Collection)

      • setActionRow

        @Nonnull
@CheckReturnValue
default MessageAction setActionRow​(@Nonnull
                                   Component... components)
        Create one row of up to 5 interactive message components.
        This is identical to setActionRows(ActionRow.of(components))
        Parameters:
        components - The components for this action row
        Returns:
        Updated MessageAction for chaining convenience
        Throws:
        java.lang.IllegalArgumentException - If anything is null, empty, or an invalid number of components are provided
        See Also:
        ActionRow.of(Component...)

      • override

        @Nonnull
@CheckReturnValue
MessageAction override​(boolean bool)
        Whether all fields should be considered when editing a message
        Parameters:
        bool - True, to override all fields even if they are not set
        Returns:
        Updated MessageAction for chaining convenience