Class MessageAction

  • All Implemented Interfaces:
    java.lang.Appendable

    public class MessageAction
    extends RestAction<Message>
    implements java.lang.Appendable
    Extension of a default RestAction that allows setting message information before sending!

    This is available as return type of all sendMessage/sendFile methods in MessageChannel or by using MessageBuilder.sendTo(MessageChannel)

    When updating a Message, unset fields will be ignored by default. To override existing fields with no value (remove content) you can use override(true). Setting this to true will cause all fields to be considered and will override the Message entirely causing unset values to be removed from that message.
    This can be used to remove existing embeds from a message:
    message.editMessage("This message had an embed").override(true).queue()

    When this RestAction has been executed all provided files will be closed. If you decide not to execute this action, you should call clearFiles() to free resources.
    Note that the garbage collector also frees opened file streams when it finalizes the stream object.

    Example

    
     @Override
      public void onMessageReceived(MessageReceivedEvent event)
      {
          MessageChannel channel = event.getChannel();
          channel.sendMessage("This has an embed with an image!")
                 .addFile(new File("dog.png"))
                 .embed(new EmbedBuilder()
                     .setImage("attachment://dog.png")
                     .build())
                 .queue(); // this actually sends the information to discord
      }
     
    Since:
    3.4.0
    • Constructor Detail

      • MessageAction

        public MessageAction​(JDA api,
                             net.dv8tion.jda.core.requests.Route.CompiledRoute route,
                             MessageChannel channel)
      • MessageAction

        public MessageAction​(JDA api,
                             net.dv8tion.jda.core.requests.Route.CompiledRoute route,
                             MessageChannel channel,
                             java.lang.StringBuilder contentBuilder)
    • Method Detail

      • isEmpty

        public 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

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

        @CheckReturnValue
        public MessageAction apply​(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 an MessageEmbed that exceeds the sendable character limit, see MessageEmbed.isSendable(AccountType)
      • tts

        @CheckReturnValue
        public 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

        @CheckReturnValue
        public 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).embed(null).tts(false).override(false).clearFiles()

        Returns:
        Updated MessageAction for chaining convenience
      • content

        @CheckReturnValue
        public MessageAction content​(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
      • embed

        @CheckReturnValue
        public MessageAction embed​(MessageEmbed embed)
        Sets the MessageEmbed that should be used for this Message. Refer to EmbedBuilder for more information.
        Parameters:
        embed - The MessageEmbed that should be attached to this message, null to use no embed.
        Returns:
        Updated MessageAction for chaining convenience
        Throws:
        java.lang.IllegalArgumentException - If the provided MessageEmbed is not sendable according to MessageEmbed.isSendable(AccountType)! If the provided MessageEmbed is an unknown implementation this operation will fail as we are unable to deserialize it.
      • append

        @CheckReturnValue
        public MessageAction append​(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

        @CheckReturnValue
        public MessageAction append​(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

        @CheckReturnValue
        public 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

        @CheckReturnValue
        public MessageAction appendFormat​(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

        @CheckReturnValue
        public MessageAction addFile​(java.io.InputStream data,
                                     java.lang.String name)
        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()
        Returns:
        Updated MessageAction for chaining convenience
        Throws:
        java.lang.IllegalStateException - If the file limit of 10 has been reached prior to calling this method, or if this MessageAction will perform an edit operation on an existing Message (see isEdit())
        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

        @CheckReturnValue
        public MessageAction addFile​(byte[] data,
                                     java.lang.String name)
        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()
        Returns:
        Updated MessageAction for chaining convenience
        Throws:
        java.lang.IllegalStateException - If the file limit of 10 has been reached prior to calling this method, or if this MessageAction will perform an edit operation on an existing Message (see isEdit())
        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

        @CheckReturnValue
        public MessageAction addFile​(java.io.File file)
        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
        Returns:
        Updated MessageAction for chaining convenience
        Throws:
        java.lang.IllegalStateException - If the file limit of 10 has been reached prior to calling this method, or if this MessageAction will perform an edit operation on an existing Message (see isEdit())
        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

        @CheckReturnValue
        public MessageAction addFile​(java.io.File file,
                                     java.lang.String name)
        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()
        Returns:
        Updated MessageAction for chaining convenience
        Throws:
        java.lang.IllegalStateException - If the file limit of 10 has been reached prior to calling this method, or if this MessageAction will perform an edit operation on an existing Message (see isEdit())
        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

        @CheckReturnValue
        public MessageAction clearFiles​(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

        @CheckReturnValue
        public MessageAction clearFiles​(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
      • override

        @CheckReturnValue
        public 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