Package net.dv8tion.jda.api.utils.messages

Class MessageEditBuilder

java.lang.Object

net.dv8tion.jda.api.utils.messages.AbstractMessageBuilder<MessageEditData,MessageEditBuilder>

net.dv8tion.jda.api.utils.messages.MessageEditBuilder

All Implemented Interfaces:

MessageData, MessageEditRequest<MessageEditBuilder>, MessageRequest<MessageEditBuilder>

public class MessageEditBuilder
extends AbstractMessageBuilder<MessageEditData,MessageEditBuilder>
implements MessageEditRequest<MessageEditBuilder>

Builder specialized for building a MessageEditData.

These are used to edit messages and allow configuration that either replaces the message or only updates specific fields.

See Also:

• MessageCreateBuilder

Constructor Summary

Constructors

Constructor	Description
MessageEditBuilder()

Method Summary

Modifier and Type	Method	Description
MessageEditBuilder	applyData(MessageEditData data)	Applies the provided MessageEditData to this request.
MessageEditData	build()	Builds a validated instance of this builder's state, which can then be used for requests.
MessageEditBuilder	clear()	Clears this builder's state, resetting it to the initial state identical to creating a new instance.
MessageEditBuilder	closeFiles()	Closes and removes all FileUploads added to this builder.
static MessageEditBuilder	from(MessageEditData data)	Factory method to start a builder from an existing instance of MessageEditData.
static MessageEditBuilder	fromCreateData(MessageCreateData data)	Factory method to start a builder from an existing instance of MessageCreateData.
static MessageEditBuilder	fromMessage(Message message)	Factory method to start a builder from an existing instance of Message.
List<? extends AttachedFile>	getAttachments()	The configured message attachments as AttachedFile, this is the opposite of MessageRequest.setFiles(Collection) and only returns what was set using that setter.
boolean	isEmpty()	Whether this builder is considered empty, this checks for all required fields of the request type.
boolean	isReplace()	Whether this request will replace the message and remove everything that is not currently set.
boolean	isValid()	Whether this builder has a valid state to build.
MessageEditBuilder	mention(Collection<? extends IMentionable> mentions)	Used to provide a whitelist for Users, Members and Roles that should be pinged, even when they would not be pinged otherwise according to the Set of allowed mention types.
MessageEditBuilder	mentionRepliedUser(boolean mention)	Whether to mention the user, when replying to a message.
MessageEditBuilder	mentionRoles(Collection<String> roleIds)	Used to provide a whitelist of Roles that should be pinged, even when they would not be pinged otherwise according to the Set of allowed mention types.
MessageEditBuilder	mentionUsers(Collection<String> userIds)	Used to provide a whitelist of Users that should be pinged, even when they would not be pinged otherwise according to the Set of allowed mention types.
MessageEditBuilder	setAllowedMentions(Collection<Message.MentionType> allowedMentions)	Sets the MentionTypes that should be parsed.
MessageEditBuilder	setAttachments(Collection<? extends AttachedFile> attachments)	The AttachedFiles that should be attached to the message.
MessageEditBuilder	setComponents(Collection<? extends MessageTopLevelComponent> components)	The MessageTopLevelComponents that should be attached to the message.
MessageEditBuilder	setContent(String content)	The message content, which shows above embeds and attachments.
MessageEditBuilder	setEmbeds(Collection<? extends MessageEmbed> embeds)	The MessageEmbeds that should be attached to the message.
MessageEditBuilder	setReplace(boolean isReplace)	Whether to replace the existing message completely.
MessageEditBuilder	setSuppressEmbeds(boolean suppress)	Set whether embeds should be suppressed on this message.
MessageEditBuilder	useComponentsV2(boolean use)	Sets whether this message is allowed to use V2 components, this is disabled by default.

Methods inherited from class net.dv8tion.jda.api.utils.messages.AbstractMessageBuilder

getAllowedMentions, getComponents, getContent, getEmbeds, getMentionedRoles, getMentionedUsers, getMessageFlagsRaw, isMentionRepliedUser, isSuppressEmbeds, isUsingComponentsV2

Methods inherited from class java.lang.Object

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

Methods inherited from interface net.dv8tion.jda.api.utils.messages.MessageData

getAllowedMentions, getComponents, getComponentTree, getContent, getEmbeds, getMentionedRoles, getMentionedUsers, isMentionRepliedUser, isSuppressEmbeds, isUsingComponentsV2

Methods inherited from interface net.dv8tion.jda.api.utils.messages.MessageEditRequest

applyCreateData, applyMessage, setAttachments, setFiles

Methods inherited from interface net.dv8tion.jda.api.utils.messages.MessageRequest

mention, mentionRoles, mentionRoles, mentionUsers, mentionUsers, setComponents, setComponents, setEmbeds, setFiles, useComponentsV2

Constructor Details

MessageEditBuilder

public MessageEditBuilder()

Method Details

from

@Nonnull
public static MessageEditBuilder from(@Nonnull
 MessageEditData data)

Factory method to start a builder from an existing instance of MessageEditData.
Equivalent to new MessageEditBuilder().applyData(data).

Parameters:

data - The message edit data to apply

Returns:

A new MessageEditBuilder instance with the applied data

Throws:

IllegalArgumentException - If null is provided

See Also:

• applyData(MessageEditData)

fromCreateData

@Nonnull
public static MessageEditBuilder fromCreateData(@Nonnull
 MessageCreateData data)

Factory method to start a builder from an existing instance of MessageCreateData.
Equivalent to new MessageEditBuilder().applyCreateData(data).

This will set the request to be replacing.

Parameters:

data - The message create data to apply

Returns:

A new MessageEditBuilder instance with the applied data

Throws:

IllegalArgumentException - If null is provided

See Also:

• MessageEditRequest.applyCreateData(MessageCreateData)

fromMessage

@Nonnull
public static MessageEditBuilder fromMessage(@Nonnull
 Message message)

Factory method to start a builder from an existing instance of Message.
Equivalent to new MessageEditBuilder().applyMessage(data).

This will set the request to be replacing.

Parameters:

message - The message to apply

Returns:

A new MessageEditBuilder instance with the applied data

Throws:

IllegalArgumentException - If null is provided or the message is a system message

See Also:

• MessageRequest.applyMessage(Message)

mentionRepliedUser

@Nonnull
public MessageEditBuilder mentionRepliedUser(boolean mention)

Description copied from interface: MessageRequest

Whether to mention the user, when replying to a message.
This only matters in combination with MessageCreateAction.setMessageReference(...)!

This is true by default but can be configured using MessageRequest.setDefaultMentionRepliedUser(boolean)!

Specified by:

mentionRepliedUser in interface MessageRequest<MessageEditBuilder>

Overrides:

mentionRepliedUser in class AbstractMessageBuilder<MessageEditData,MessageEditBuilder>

Parameters:

mention - True, to mention the author in the referenced message

Returns:

The same instance for chaining

setAllowedMentions

@Nonnull
public MessageEditBuilder setAllowedMentions(@Nullable
 Collection<Message.MentionType> allowedMentions)

Description copied from interface: MessageRequest

Sets the MentionTypes that should be parsed.
If a message is sent with an empty Set of MentionTypes, then it will not ping any User, Role or @everyone/@here, while still showing up as mention tag.

If null is provided to this method, then all Types will be mentionable (unless whitelisting via one of the mention* methods is used).

Note: A default for this can be set using AllowedMentions.setDefaultMentions(Collection).

Specified by:

setAllowedMentions in interface MessageRequest<MessageEditBuilder>

Overrides:

setAllowedMentions in class AbstractMessageBuilder<MessageEditData,MessageEditBuilder>

Parameters:

allowedMentions - MentionTypes that are allowed to being parsed and mentioned. All other mention types will not be mentioned by this message. You can pass null or EnumSet.allOf(MentionType.class) to allow all mentions.

Returns:

The same instance for chaining

mention

@Nonnull
public MessageEditBuilder mention(@Nonnull
 Collection<? extends IMentionable> mentions)

Description copied from interface: MessageRequest

Used to provide a whitelist for Users, Members and Roles that should be pinged, even when they would not be pinged otherwise according to the Set of allowed mention types.
On other types of IMentionable, this does nothing.

Note: When a User/Member is whitelisted this way, then parsing of User mentions is automatically disabled (same applies to Roles).
Also note that whitelisting users or roles implicitly disables parsing of other mentions, if not otherwise set via MessageRequest.setDefaultMentions(Collection) or MessageRequest.setAllowedMentions(Collection).

Specified by:

mention in interface MessageRequest<MessageEditBuilder>

Overrides:

mention in class AbstractMessageBuilder<MessageEditData,MessageEditBuilder>

Parameters:

mentions - Users, Members and Roles that should be explicitly whitelisted to be pingable.

Returns:

The same instance for chaining

See Also:

• MessageRequest.setAllowedMentions(Collection)
• MessageRequest.setDefaultMentions(Collection)

mentionUsers

@Nonnull
public MessageEditBuilder mentionUsers(@Nonnull
 Collection<String> userIds)

Description copied from interface: MessageRequest

Used to provide a whitelist of Users that should be pinged, even when they would not be pinged otherwise according to the Set of allowed mention types.

Note: When a User is whitelisted this way, then parsing of User mentions is automatically disabled.
Also note that whitelisting users or roles implicitly disables parsing of other mentions, if not otherwise set via MessageRequest.setDefaultMentions(Collection) or MessageRequest.setAllowedMentions(Collection).

Specified by:

mentionUsers in interface MessageRequest<MessageEditBuilder>

Overrides:

mentionUsers in class AbstractMessageBuilder<MessageEditData,MessageEditBuilder>

Parameters:

userIds - Ids of Users that should be explicitly whitelisted to be pingable.

Returns:

The same instance for chaining

See Also:

• MessageRequest.setAllowedMentions(Collection)
• MessageRequest.setDefaultMentions(Collection)

mentionRoles

@Nonnull
public MessageEditBuilder mentionRoles(@Nonnull
 Collection<String> roleIds)

Description copied from interface: MessageRequest

Used to provide a whitelist of Roles that should be pinged, even when they would not be pinged otherwise according to the Set of allowed mention types.

Note: When a Role is whitelisted this way, then parsing of Role mentions is automatically disabled.
Also note that whitelisting users or roles implicitly disables parsing of other mentions, if not otherwise set via MessageRequest.setDefaultMentions(Collection) or MessageRequest.setAllowedMentions(Collection).

Specified by:

mentionRoles in interface MessageRequest<MessageEditBuilder>

Overrides:

mentionRoles in class AbstractMessageBuilder<MessageEditData,MessageEditBuilder>

Parameters:

roleIds - Ids of Roles that should be explicitly whitelisted to be pingable.

Returns:

The same instance for chaining

See Also:

• MessageRequest.setAllowedMentions(Collection)
• MessageRequest.setDefaultMentions(Collection)

setAttachments

@Nonnull
public MessageEditBuilder setAttachments(@Nullable
 Collection<? extends AttachedFile> attachments)

Description copied from interface: MessageEditRequest

The AttachedFiles that should be attached to the message.
This will replace all the existing attachments on the message, you can use Collections.emptyList() or null to clear all attachments.

Resource Handling Note: Once the request is handed off to the requester, for example when you call RestAction.queue(), the requester will automatically clean up all opened files by itself. You are only responsible to close them yourself if it is never handed off properly. For instance, if an exception occurs after using FileUpload.fromData(File), before calling RestAction.queue(). You can safely use a try-with-resources to handle this, since FileUpload.close() becomes ineffective once the request is handed off.

Example

 // Here "message" is an instance of the Message interface

 // Creates a list of the currently attached files of the message, important to get the generic parameter of the list right
 List<AttachedFile> attachments = new ArrayList<>(message.getAttachments());

 // The name here will be "cat.png" to discord, what the file is called on your computer is irrelevant and only used to read the data of the image.
 FileUpload file = FileUpload.fromData(new File("mycat-final-copy.png"), "cat.png"); // Opens the file called "cat.png" and provides the data used for sending

 // Adds another file to upload in addition the current attachments of the message
 attachments.add(file);

 message.editMessage("New content")
        .setAttachments(attachments)
        .queue();
 

Specified by:

setAttachments in interface MessageEditRequest<MessageEditBuilder>

Parameters:

attachments - The AttachedFiles to attach to the message, null or an empty list will set the attachments to an empty list and remove them from the message

Returns:

The same instance for chaining

See Also:

• Collections.emptyList()
• AttachedFile.fromAttachment(String)
• AttachedFile.fromData(InputStream, String)

getAttachments

@Nonnull
public List<? extends AttachedFile> getAttachments()

Description copied from interface: MessageData

The configured message attachments as AttachedFile, this is the opposite of MessageRequest.setFiles(Collection) and only returns what was set using that setter.

For message edit requests, this will not be the current file attachments of the message.

Specified by:

getAttachments in interface MessageData

Returns:

The currently configured attachments, or an empty list if none were set yet

See Also:

• MessageRequest.setFiles(Collection)

setReplace

@Nonnull
public MessageEditBuilder setReplace(boolean isReplace)

Description copied from interface: MessageEditRequest

Whether to replace the existing message completely.

By default, edit requests will only update the message fields which were explicitly set. Changing this to true, will instead replace everything and remove all unset fields.

Example Default
A request such as this will only edit the content of the message, and leave any existing embeds or attachments intact.

 message.editMessage("hello").queue();
 

Example Replace
A request such as this will replace the entire message, and remove any existing embeds, attachments, components, etc.

 message.editMessage("hello").setReplace(true).queue();
 

Specified by:

setReplace in interface MessageEditRequest<MessageEditBuilder>

Parameters:

isReplace - True, if only things explicitly set on this request should be present after the message is edited.

Returns:

The same message edit request builder

isReplace

public boolean isReplace()

Description copied from interface: MessageEditRequest

Whether this request will replace the message and remove everything that is not currently set.

If this is false, the request will only edit the message fields which were explicitly set.

Specified by:

isReplace in interface MessageEditRequest<MessageEditBuilder>

Returns:

True, if this is a replacing request

See Also:

• MessageEditRequest.setReplace(boolean)

setContent

@Nonnull
public MessageEditBuilder setContent(@Nullable
 String content)

Description copied from interface: MessageRequest

The message content, which shows above embeds and attachments.

Specified by:

setContent in interface MessageRequest<MessageEditBuilder>

Overrides:

setContent in class AbstractMessageBuilder<MessageEditData,MessageEditBuilder>

Parameters:

content - The content (up to 2000 characters)

Returns:

The same instance for chaining

setEmbeds

@Nonnull
public MessageEditBuilder setEmbeds(@Nonnull
 Collection<? extends MessageEmbed> embeds)

Description copied from interface: MessageRequest

The MessageEmbeds that should be attached to the message.
You can use Collections.emptyList() to remove all embeds from the message.

This requires Permission.MESSAGE_EMBED_LINKS in the channel.

Specified by:

setEmbeds in interface MessageRequest<MessageEditBuilder>

Overrides:

setEmbeds in class AbstractMessageBuilder<MessageEditData,MessageEditBuilder>

Parameters:

embeds - The embeds to attach to the message (up to 10)

Returns:

The same instance for chaining

See Also:

• Collections.emptyList()

setComponents

@Nonnull
public MessageEditBuilder setComponents(@Nonnull
 Collection<? extends MessageTopLevelComponent> components)

Description copied from interface: MessageRequest

The MessageTopLevelComponents that should be attached to the message.
You can use Collections.emptyList() to remove all components from the message.

Example: Set action rows

 final List<MessageTopLevelComponent> list = new ArrayList<>();
 list.add(ActionRow.of(selectMenu); // first row
 list.add(ActionRow.of(button1, button2)); // second row (shows below the first)

 channel.sendMessage("Content here")
   .setComponents(list)
   .queue();
 

Example: Remove action rows

 channel.sendMessage("Content here")
    .setComponents(Collections.emptyList())
    .queue();
 

Specified by:

setComponents in interface MessageRequest<MessageEditBuilder>

Overrides:

setComponents in class AbstractMessageBuilder<MessageEditData,MessageEditBuilder>

Parameters:

components - The MessageTopLevelComponents to set, can be empty to remove components, can contain up to 5 V1 components. There are no limits for V2 components outside the total tree size (40).

Returns:

The same instance for chaining

useComponentsV2

@Nonnull
public MessageEditBuilder useComponentsV2(boolean use)

Description copied from interface: MessageRequest

Sets whether this message is allowed to use V2 components, this is disabled by default.

Using V2 components removes the top-level component limit, and allows more components in total (40).
They also allow you to use a larger choice of components, such as any component extending MessageTopLevelComponent, as long as they are compatible.
The character limit for the messages also gets changed to 4000.

This, however, comes with a few drawbacks:

• You cannot send content, embeds, polls or stickers
• It does not support voice messages
• It does not support previewing files
• URLs don't create embeds
• You cannot switch this message back to not using Components V2 (you can however upgrade a message to V2)

A default value can be set in MessageRequest.setDefaultUseComponentsV2(boolean).

Specified by:

useComponentsV2 in interface MessageRequest<MessageEditBuilder>

Overrides:

useComponentsV2 in class AbstractMessageBuilder<MessageEditData,MessageEditBuilder>

Parameters:

use - true to enable V2 components, false to disabled them.

Returns:

The same instance for chaining

See Also:

• MessageTopLevelComponent
• MessageRequest.setDefaultUseComponentsV2(boolean)

setSuppressEmbeds

@Nonnull
public MessageEditBuilder setSuppressEmbeds(boolean suppress)

Description copied from interface: MessageRequest

Set whether embeds should be suppressed on this message.
This also includes rich embeds added via MessageRequest.setEmbeds(MessageEmbed...).

Default: false

Specified by:

setSuppressEmbeds in interface MessageRequest<MessageEditBuilder>

Overrides:

setSuppressEmbeds in class AbstractMessageBuilder<MessageEditData,MessageEditBuilder>

Parameters:

suppress - True, if all embeds should be suppressed

Returns:

The same instance for chaining

applyData

@Nonnull
public MessageEditBuilder applyData(@Nonnull
 MessageEditData data)

Description copied from interface: MessageEditRequest

Applies the provided MessageEditData to this request.

Note that this method will only call the setters which were also configured when building the message edit data instance, unless it was set to replace.

Specified by:

applyData in interface MessageEditRequest<MessageEditBuilder>

Parameters:

data - The message edit data to apply

Returns:

The same instance for chaining

isEmpty

public boolean isEmpty()

Description copied from class: AbstractMessageBuilder

Whether this builder is considered empty, this checks for all required fields of the request type.
On a create request, this checks for content, embeds, components, and files.
An edit request is only considered empty if no setters were called. And never empty, if the builder is a replace request.

Specified by:

isEmpty in class AbstractMessageBuilder<MessageEditData,MessageEditBuilder>

Returns:

True, if the builder state is empty

isValid

public boolean isValid()

Description copied from class: AbstractMessageBuilder

Whether this builder has a valid state to build.
If this is false, then AbstractMessageBuilder.build() throws an IllegalStateException. You can check the exception docs on AbstractMessageBuilder.build() for specifics.

Specified by:

isValid in class AbstractMessageBuilder<MessageEditData,MessageEditBuilder>

Returns:

True, if the builder is in a valid state

build

@Nonnull
public MessageEditData build()

Description copied from class: AbstractMessageBuilder

Builds a validated instance of this builder's state, which can then be used for requests.

Specified by:

build in class AbstractMessageBuilder<MessageEditData,MessageEditBuilder>

Returns:

The validated data instance

clear

@Nonnull
public MessageEditBuilder clear()

Description copied from class: AbstractMessageBuilder

Clears this builder's state, resetting it to the initial state identical to creating a new instance.

WARNING: This will remove all the files added to the builder, but will not close them. You can use AbstractMessageBuilder.closeFiles() before calling clear() to close the files explicitly.

Overrides:

clear in class AbstractMessageBuilder<MessageEditData,MessageEditBuilder>

Returns:

The same builder instance for chaining

closeFiles

@Nonnull
public MessageEditBuilder closeFiles()

Description copied from class: AbstractMessageBuilder

Closes and removes all FileUploads added to this builder.

This will keep any AttachmentUpdates added to this builder, as those do not require closing. You can use MessageEditRequest.setAttachments(AttachedFile...) to remove them as well.

Specified by:

closeFiles in class AbstractMessageBuilder<MessageEditData,MessageEditBuilder>

Returns:

The same builder instance for chaining