Package net.dv8tion.jda.core.requests.restaction

Class MessageAction

java.lang.Object

net.dv8tion.jda.core.requests.RestAction<Message>

net.dv8tion.jda.core.requests.restaction.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

Nested Class Summary

Nested classes/interfaces inherited from class net.dv8tion.jda.core.requests.RestAction

RestAction.EmptyRestAction<T>

Field Summary

Fields inherited from class net.dv8tion.jda.core.requests.RestAction

DEFAULT_FAILURE, DEFAULT_SUCCESS, LOG

Constructor Summary

Constructors

Constructor	Description
MessageAction(JDA api, net.dv8tion.jda.core.requests.Route.CompiledRoute route, MessageChannel channel)
MessageAction(JDA api, net.dv8tion.jda.core.requests.Route.CompiledRoute route, MessageChannel channel, java.lang.StringBuilder contentBuilder)

Method Summary

Modifier and Type	Method	Description
MessageAction	addFile(byte[] data, java.lang.String name)	Adds the provided byte[] as file data.
MessageAction	addFile(java.io.File file)	Adds the provided File as file data.
MessageAction	addFile(java.io.File file, java.lang.String name)	Adds the provided File as file data.
MessageAction	addFile(java.io.InputStream data, java.lang.String name)	Adds the provided InputStream as file data.
MessageAction	append(char c)
MessageAction	append(java.lang.CharSequence csq)
MessageAction	append(java.lang.CharSequence csq, int start, int end)
MessageAction	appendFormat(java.lang.String format, java.lang.Object... args)	Applies the result of String.format(String, Object...) as content.
MessageAction	apply(Message message)	Applies the sendable information of the provided Message to this MessageAction settings.
MessageAction	clearFiles()	Clears all previously added files And closes FileInputStreams generated by addFile(File, String).
MessageAction	clearFiles(java.util.function.BiConsumer<java.lang.String,java.io.InputStream> finalizer)	Clears all previously added files
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.
MessageAction	content(java.lang.String content)	Overrides existing content with the provided input The content of a Message may not exceed 2000!
MessageAction	embed(MessageEmbed embed)	Sets the MessageEmbed that should be used for this Message.
boolean	isEdit()	Whether this MessageAction will be used to update an existing message.
boolean	isEmpty()	Whether this MessageAction has no values set.
MessageAction	nonce(java.lang.String nonce)	Sets the validation nonce for the outgoing Message
MessageAction	override(boolean bool)	Whether all fields should be considered when editing a message
MessageAction	reset()	Resets this MessageAction to empty state isEmpty() will result in true after this has been performed!
MessageAction	tts(boolean isTTS)	Enable/Disable Text-To-Speech for the resulting message.

Methods inherited from class java.lang.Object

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

Methods inherited from class net.dv8tion.jda.core.requests.RestAction

complete, complete, completeAfter, getJDA, isPassContext, queue, queue, queue, queueAfter, queueAfter, queueAfter, queueAfter, queueAfter, queueAfter, setCheck, setPassContext, submit, submit, submitAfter, submitAfter

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

nonce

@CheckReturnValue
public MessageAction nonce(java.lang.String nonce)

Sets the validation nonce for the outgoing Message

For more information see MessageBuilder.setNonce(String) and Message.getNonce()

Parameters:

nonce - The nonce that shall be used

Returns:

Updated MessageAction for chaining convenience

See Also:

Message.getNonce(), MessageBuilder.setNonce(String), Cryptographic Nonce - Wikipedia

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()

Clears all previously added files
And closes FileInputStreams generated by addFile(File, String).
To close all stream (including ones given by addFile(InputStream, String)) use clearFiles(Consumer).

Returns:

Updated MessageAction for chaining convenience

See Also:

clearFiles(Consumer), clearFiles(BiConsumer)

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