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 defaultRestAction
that allows setting message information before sending!This is available as return type of all sendMessage/sendFile methods in
MessageChannel
or by usingMessageBuilder.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 totrue
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
All Methods Instance Methods Concrete Methods 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 providedFile
as file data.MessageAction
addFile(java.io.File file, java.lang.String name)
Adds the providedFile
as file data.MessageAction
addFile(java.io.InputStream data, java.lang.String name)
Adds the providedInputStream
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 ofString.format(String, Object...)
as content.MessageAction
apply(Message message)
Applies the sendable information of the providedMessage
to this MessageAction settings.MessageAction
clearFiles()
MessageAction
clearFiles(java.util.function.BiConsumer<java.lang.String,java.io.InputStream> finalizer)
Clears all previously added filesMessageAction
clearFiles(java.util.function.Consumer<java.io.InputStream> finalizer)
Clears all previously added files
TheclearFiles(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 theMessageEmbed
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 MessageMessageAction
override(boolean bool)
Whether all fields should be considered when editing a messageMessageAction
reset()
Resets this MessageAction to empty stateisEmpty()
will result intrue
after this has been performed!MessageAction
tts(boolean isTTS)
Enable/Disable Text-To-Speech for the resulting message.-
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 withisEmpty() == true
will result in anIllegalStateException
!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 providedMessage
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 anMessageEmbed
that exceeds the sendable character limit, seeMessageEmbed.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 notisEdit() == 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 stateisEmpty()
will result intrue
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 MessageFor more information see
MessageBuilder.setNonce(String)
andMessage.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 ornull
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 theMessageEmbed
that should be used for this Message. Refer toEmbedBuilder
for more information.- Parameters:
embed
- TheMessageEmbed
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 toMessageEmbed.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 interfacejava.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 interfacejava.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 interfacejava.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 ofString.format(String, Object...)
as content.For more information of formatting review the
Formatter
documentation!- Parameters:
format
- The format Stringargs
- 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 limitjava.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 providedInputStream
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 dataname
- 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 throughMessage.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 (seeisEdit()
)java.lang.IllegalArgumentException
- If the provided data isnull
or the provided name is blank ornull
InsufficientPermissionException
- If this is targeting a TextChannel and the currently logged in account does not havePermission.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 dataname
- 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 throughMessage.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 (seeisEdit()
)java.lang.IllegalArgumentException
- If the provided data isnull
or the provided name is blank ornull
or if the provided data exceeds the maximum file size of the currently logged in accountInsufficientPermissionException
- If this is targeting a TextChannel and the currently logged in account does not havePermission.MESSAGE_ATTACH_FILES
- See Also:
SelfUser.getAllowedFileSize()
-
addFile
@CheckReturnValue public MessageAction addFile(java.io.File file)
Adds the providedFile
as file data.
Shortcut foraddFile(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 (seeisEdit()
)java.lang.IllegalArgumentException
- If the provided file isnull
or if the provided File is bigger than the maximum file size of the currently logged in accountInsufficientPermissionException
- If this is targeting a TextChannel and the currently logged in account does not havePermission.MESSAGE_ATTACH_FILES
- See Also:
SelfUser.getAllowedFileSize()
-
addFile
@CheckReturnValue public MessageAction addFile(java.io.File file, java.lang.String name)
Adds the providedFile
as file data.To reset all files use
clearFiles()
This method opens aFileInputStream
which will be closed by executing this action or usingclearFiles()
!- Parameters:
file
- The File that will be interpreted as file dataname
- 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 throughMessage.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 (seeisEdit()
)java.lang.IllegalArgumentException
- If the provided file isnull
or the provided name is blank ornull
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 readableInsufficientPermissionException
- If this is targeting a TextChannel and the currently logged in account does not havePermission.MESSAGE_ATTACH_FILES
- See Also:
SelfUser.getAllowedFileSize()
-
clearFiles
@CheckReturnValue public MessageAction clearFiles()
Clears all previously added files
And closesFileInputStreams
generated byaddFile(File, String)
.
To close all stream (including ones given byaddFile(InputStream, String)
) useclearFiles(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 asInputStream
.- 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
TheclearFiles(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 anInputStream
- 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
-
-