Interface MessageAction
-
- All Superinterfaces:
Appendable
,RestAction<Message>
public interface MessageAction extends RestAction<Message>, 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
- See Also:
Message.editMessage(Message)
,Message.editMessage(CharSequence)
,Message.editMessage(MessageEmbed)
,Message.editMessageFormat(String, Object...)
,MessageChannel.sendMessage(Message)
,MessageChannel.sendMessage(CharSequence)
,MessageChannel.sendMessage(MessageEmbed)
,MessageChannel.sendMessageFormat(String, Object...)
,MessageChannel.sendFile(File, AttachmentOption...)
,MessageChannel.sendFile(File, String, AttachmentOption...)
,MessageChannel.sendFile(InputStream, String, AttachmentOption...)
,MessageChannel.sendFile(byte[], String, AttachmentOption...)
-
-
Method Summary
All Methods Instance Methods Abstract Methods Default Methods Modifier and Type Method Description default MessageAction
addFile(byte[] data, String name, AttachmentOption... options)
Adds the provided byte[] as file data.MessageAction
addFile(File file, String name, AttachmentOption... options)
Adds the providedFile
as file data.default MessageAction
addFile(File file, AttachmentOption... options)
Adds the providedFile
as file data.MessageAction
addFile(InputStream data, String name, AttachmentOption... options)
Adds the providedInputStream
as file data.MessageAction
append(char c)
default MessageAction
append(CharSequence csq)
MessageAction
append(CharSequence csq, int start, int end)
default MessageAction
appendFormat(String format, 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()
Clears all previously added files
And closesFileInputStreams
generated byaddFile(File, String, net.dv8tion.jda.api.utils.AttachmentOption...)
.MessageAction
clearFiles(BiConsumer<String,InputStream> finalizer)
Clears all previously added filesMessageAction
clearFiles(Consumer<InputStream> finalizer)
Clears all previously added files
TheclearFiles(BiConsumer)
version provides the resource name for more selective operations.MessageAction
content(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.MessageChannel
getChannel()
The targetMessageChannel
for this messageboolean
isEdit()
Whether this MessageAction will be used to update an existing message.boolean
isEmpty()
Whether this MessageAction has no values set.MessageAction
nonce(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
setCheck(BooleanSupplier checks)
Sets the last-second checks before finally executing the http request in the queue.MessageAction
tts(boolean isTTS)
Enable/Disable Text-To-Speech for the resulting message.-
Methods inherited from interface net.dv8tion.jda.api.requests.RestAction
complete, complete, completeAfter, getJDA, queue, queue, queue, queueAfter, queueAfter, queueAfter, queueAfter, queueAfter, queueAfter, submit, submit, submitAfter, submitAfter
-
-
-
-
Method Detail
-
setCheck
@Nonnull MessageAction setCheck(@Nullable 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 tofalse
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 interfaceRestAction<Message>
- Parameters:
checks
- The checks to run before executing the request, ornull
to run no checks- Returns:
- The current RestAction for chaining convenience
-
getChannel
@Nonnull MessageChannel getChannel()
The targetMessageChannel
for this message- Returns:
- The target channel
-
isEmpty
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
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 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:
IllegalArgumentException
- If the message contains anMessageEmbed
that exceeds the sendable character limit, seeMessageEmbed.isSendable(AccountType)
-
tts
@Nonnull @CheckReturnValue 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
@Nonnull @CheckReturnValue 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
@Nonnull @CheckReturnValue MessageAction nonce(@Nullable 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
@Nonnull @CheckReturnValue MessageAction content(@Nullable 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:
IllegalArgumentException
- If the provided content exceeds the 2000 character limit
-
embed
@Nonnull @CheckReturnValue MessageAction embed(@Nullable 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:
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
@Nonnull @CheckReturnValue default MessageAction append(@Nonnull CharSequence csq)
- Specified by:
append
in interfaceAppendable
- Returns:
- Updated MessageAction for chaining convenience
- Throws:
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 CharSequence csq, int start, int end)
- Specified by:
append
in interfaceAppendable
- Returns:
- Updated MessageAction for chaining convenience
- Throws:
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 interfaceAppendable
- Returns:
- Updated MessageAction for chaining convenience
- Throws:
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 String format, 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:
IllegalArgumentException
- If the appended formatting is too big and will cause the content to exceed the 2000 character limitIllegalFormatException
- 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 InputStream data, @Nonnull String name, @Nonnull AttachmentOption... options)
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()
options
- Possible options to apply to this attachment, such as marking it as spoiler image- Returns:
- Updated MessageAction for chaining convenience
- Throws:
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()
)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
@Nonnull @CheckReturnValue default MessageAction addFile(@Nonnull byte[] data, @Nonnull 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 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()
options
- Possible options to apply to this attachment, such as marking it as spoiler image- Returns:
- Updated MessageAction for chaining convenience
- Throws:
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()
)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
@Nonnull @CheckReturnValue default MessageAction addFile(@Nonnull File file, @Nonnull AttachmentOption... options)
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 dataoptions
- Possible options to apply to this attachment, such as marking it as spoiler image- Returns:
- Updated MessageAction for chaining convenience
- Throws:
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()
)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
@Nonnull @CheckReturnValue MessageAction addFile(@Nonnull File file, @Nonnull String name, @Nonnull AttachmentOption... options)
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()
options
- Possible options to apply to this attachment, such as marking it as spoiler image- Returns:
- Updated MessageAction for chaining convenience
- Throws:
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()
)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
@Nonnull @CheckReturnValue MessageAction clearFiles()
Clears all previously added files
And closesFileInputStreams
generated byaddFile(File, String, net.dv8tion.jda.api.utils.AttachmentOption...)
.
To close all stream (including ones given byaddFile(InputStream, String, net.dv8tion.jda.api.utils.AttachmentOption...)
) useclearFiles(Consumer)
.- Returns:
- Updated MessageAction for chaining convenience
- See Also:
clearFiles(BiConsumer)
-
clearFiles
@Nonnull @CheckReturnValue MessageAction clearFiles(@Nonnull BiConsumer<String,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
@Nonnull @CheckReturnValue MessageAction clearFiles(@Nonnull Consumer<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
@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
-
-