Interface MessageAction
-
- All Superinterfaces:
Appendable,RestAction<Message>
public interface MessageAction extends RestAction<Message>, Appendable
Extension of a defaultRestActionthat allows setting message information before sending!This is available as return type of all sendMessage/sendFile methods in
MessageChannelor 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 totruewill 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 MessageActionaddFile(byte[] data, String name, AttachmentOption... options)Adds the provided byte[] as file data.MessageActionaddFile(File file, String name, AttachmentOption... options)Adds the providedFileas file data.default MessageActionaddFile(File file, AttachmentOption... options)Adds the providedFileas file data.MessageActionaddFile(InputStream data, String name, AttachmentOption... options)Adds the providedInputStreamas file data.MessageActionappend(char c)default MessageActionappend(CharSequence csq)MessageActionappend(CharSequence csq, int start, int end)default MessageActionappendFormat(String format, Object... args)Applies the result ofString.format(String, Object...)as content.MessageActionapply(Message message)Applies the sendable information of the providedMessageto this MessageAction settings.MessageActionclearFiles()Clears all previously added files
And closesFileInputStreamsgenerated byaddFile(File, String, net.dv8tion.jda.api.utils.AttachmentOption...).MessageActionclearFiles(BiConsumer<String,InputStream> finalizer)Clears all previously added filesMessageActionclearFiles(Consumer<InputStream> finalizer)Clears all previously added files
TheclearFiles(BiConsumer)version provides the resource name for more selective operations.MessageActioncontent(String content)Overrides existing content with the provided input
The content of a Message may not exceed 2000!MessageActionembed(MessageEmbed embed)Sets theMessageEmbedthat should be used for this Message.MessageChannelgetChannel()The targetMessageChannelfor this messagebooleanisEdit()Whether this MessageAction will be used to update an existing message.booleanisEmpty()Whether this MessageAction has no values set.MessageActionnonce(String nonce)Sets the validation nonce for the outgoing MessageMessageActionoverride(boolean bool)Whether all fields should be considered when editing a messageMessageActionreset()Resets this MessageAction to empty stateisEmpty()will result intrueafter this has been performed!MessageActionsetCheck(BooleanSupplier checks)Sets the last-second checks before finally executing the http request in the queue.MessageActiontts(boolean isTTS)Enable/Disable Text-To-Speech for the resulting message.-
Methods inherited from interface net.dv8tion.jda.api.requests.RestAction
complete, complete, completeAfter, delay, delay, delay, delay, flatMap, flatMap, getJDA, map, 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:RestActionSets the last-second checks before finally executing the http request in the queue.
If the provided supplier evaluates tofalseor 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:
setCheckin interfaceRestAction<Message>- Parameters:
checks- The checks to run before executing the request, ornullto run no checks- Returns:
- The current RestAction for chaining convenience
-
getChannel
@Nonnull MessageChannel getChannel()
The targetMessageChannelfor this message- Returns:
- The target channel
-
isEmpty
boolean isEmpty()
Whether this MessageAction has no values set.
Trying to execute withisEmpty() == truewill 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 providedMessageto 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 anMessageEmbedthat 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 intrueafter 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 ornullto 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 theMessageEmbedthat should be used for this Message. Refer toEmbedBuilderfor more information.- Parameters:
embed- TheMessageEmbedthat should be attached to this message,nullto 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:
appendin 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:
appendin 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:
appendin 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
Formatterdocumentation!- 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 providedInputStreamas 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 isnullor the provided name is blank ornullInsufficientPermissionException- 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 isnullor the provided name is blank ornullor 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 providedFileas 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 isnullor 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 providedFileas file data.To reset all files use
clearFiles()
This method opens aFileInputStreamwhich 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 isnullor the provided name is blank ornullor 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 closesFileInputStreamsgenerated 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
-
-