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

Class AbstractMessageBuilder<T,R extends AbstractMessageBuilder<T,R>>

java.lang.Object

net.dv8tion.jda.api.utils.messages.AbstractMessageBuilder<T,R>

Type Parameters:

T - The result type used for build()

R - The return type used for method chaining

All Implemented Interfaces:

MessageData, MessageRequest<R>

Direct Known Subclasses:

MessageCreateBuilder, MessageEditBuilder

public abstract class AbstractMessageBuilder<T,R extends AbstractMessageBuilder<T,R>>
extends Object
implements MessageRequest<R>

Abstract builder implementation of MessageRequest.

This builder cannot be instantiated directly. You should use MessageCreateBuilder or MessageEditBuilder instead.

See Also:

• MessageCreateBuilder
• MessageEditBuilder

Method Summary

Modifier and Type	Method	Description
abstract T	build()	Builds a validated instance of this builder's state, which can then be used for requests.
R	clear()	Clears this builder's state, resetting it to the initial state identical to creating a new instance.
abstract R	closeFiles()	Closes and removes all FileUploads added to this builder.
EnumSet<Message.MentionType>	getAllowedMentions()	The mention types which are whitelisted.
List<MessageTopLevelComponentUnion>	getComponents()	The configured message components, this is the opposite of MessageRequest.setComponents(Collection) and only returns what was set using that setter.
String	getContent()	The configured message content, this is the opposite for MessageRequest.setContent(String) and only returns what was set using that setter.
List<MessageEmbed>	getEmbeds()	The configured message embeds, this is the opposite of MessageRequest.setEmbeds(Collection) and only returns what was set using that setter.
Set<String>	getMentionedRoles()	The IDs for roles which are allowed to be mentioned, or an empty list.
Set<String>	getMentionedUsers()	The IDs for users which are allowed to be mentioned, or an empty list.
long	getMessageFlagsRaw()	The flags set on this message.
abstract boolean	isEmpty()	Whether this builder is considered empty, this checks for all required fields of the request type.
boolean	isMentionRepliedUser()	Whether this message would mention a user, if it is sent as a reply.
boolean	isSuppressEmbeds()	Whether embeds will be suppressed on this message.
boolean	isUsingComponentsV2()	Whether this message is using components V2.
abstract boolean	isValid()	Whether this builder has a valid state to build.
R	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.
R	mentionRepliedUser(boolean mention)	Whether to mention the user, when replying to a message.
R	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.
R	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.
R	setAllowedMentions(Collection<Message.MentionType> allowedMentions)	Sets the MentionTypes that should be parsed.
R	setComponents(Collection<? extends MessageTopLevelComponent> components)	The MessageTopLevelComponents that should be attached to the message.
R	setContent(String content)	The message content, which shows above embeds and attachments.
R	setEmbeds(Collection<? extends MessageEmbed> embeds)	The MessageEmbeds that should be attached to the message.
R	setSuppressEmbeds(boolean suppress)	Set whether embeds should be suppressed on this message.
R	useComponentsV2(boolean use)	Sets whether this message is allowed to use V2 components, this is disabled by default.

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

getAttachments, getComponentTree

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

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

Method Details

setContent

@Nonnull
public R setContent(@Nullable
 String content)

Description copied from interface: MessageRequest

The message content, which shows above embeds and attachments.

Specified by:

setContent in interface MessageRequest<T>

Parameters:

content - The content (up to 2000 characters)

Returns:

The same instance for chaining

getContent

@Nonnull
public String getContent()

Description copied from interface: MessageData

The configured message content, this is the opposite for MessageRequest.setContent(String) and only returns what was set using that setter.

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

Specified by:

getContent in interface MessageData

Returns:

The currently configured content, or an empty string if none was set yet

See Also:

• MessageRequest.setContent(String)

mentionRepliedUser

@Nonnull
public R 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<T>

Parameters:

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

Returns:

The same instance for chaining

setAllowedMentions

@Nonnull
public R 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<T>

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 R 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<T>

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 R 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<T>

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 R 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<T>

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)

getMentionedUsers

@Nonnull
public Set<String> getMentionedUsers()

Description copied from interface: MessageData

The IDs for users which are allowed to be mentioned, or an empty list.

Specified by:

getMentionedUsers in interface MessageData

Returns:

The user IDs which are mention whitelisted

getMentionedRoles

@Nonnull
public Set<String> getMentionedRoles()

Description copied from interface: MessageData

The IDs for roles which are allowed to be mentioned, or an empty list.

Specified by:

getMentionedRoles in interface MessageData

Returns:

The role IDs which are mention whitelisted

getAllowedMentions

@Nonnull
public EnumSet<Message.MentionType> getAllowedMentions()

Description copied from interface: MessageData

The mention types which are whitelisted.

Specified by:

getAllowedMentions in interface MessageData

Returns:

The mention types which can be mentioned by this message

isMentionRepliedUser

public boolean isMentionRepliedUser()

Description copied from interface: MessageData

Whether this message would mention a user, if it is sent as a reply.

Specified by:

isMentionRepliedUser in interface MessageData

Returns:

True, if this would mention with the reply

setEmbeds

@Nonnull
public R 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<T>

Parameters:

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

Returns:

The same instance for chaining

See Also:

• Collections.emptyList()

getEmbeds

@Nonnull
public List<MessageEmbed> getEmbeds()

Description copied from interface: MessageData

The configured message embeds, this is the opposite of MessageRequest.setEmbeds(Collection) and only returns what was set using that setter.

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

Specified by:

getEmbeds in interface MessageData

Returns:

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

See Also:

• MessageRequest.setEmbeds(Collection)

setComponents

@Nonnull
public R 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<T>

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 R 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<T>

Parameters:

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

Returns:

The same instance for chaining

See Also:

• MessageTopLevelComponent
• MessageRequest.setDefaultUseComponentsV2(boolean)

getComponents

@Nonnull
public List<MessageTopLevelComponentUnion> getComponents()

Description copied from interface: MessageData

The configured message components, this is the opposite of MessageRequest.setComponents(Collection) and only returns what was set using that setter.

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

Specified by:

getComponents in interface MessageData

Returns:

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

See Also:

• MessageRequest.setEmbeds(Collection)

isUsingComponentsV2

public boolean isUsingComponentsV2()

Description copied from interface: MessageData

Whether this message is using components V2.

Specified by:

isUsingComponentsV2 in interface MessageData

Returns:

true if this is using components V2

See Also:

• MessageRequest.useComponentsV2()
• MessageRequest.useComponentsV2(boolean)

setSuppressEmbeds

@Nonnull
public R 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<T>

Parameters:

suppress - True, if all embeds should be suppressed

Returns:

The same instance for chaining

isSuppressEmbeds

public boolean isSuppressEmbeds()

Description copied from interface: MessageData

Whether embeds will be suppressed on this message.

Specified by:

isSuppressEmbeds in interface MessageData

Returns:

True, if embeds are suppressed

getMessageFlagsRaw

public long getMessageFlagsRaw()

The flags set on this message.

Returns:

The currently set message flags

isEmpty

public abstract boolean isEmpty()

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.

Returns:

True, if the builder state is empty

isValid

public abstract boolean isValid()

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

Returns:

True, if the builder is in a valid state

build

@Nonnull
public abstract T build()

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

Returns:

The validated data instance

Throws:

IllegalStateException - For MessageCreateBuilder

• If the builder is empty
• If the content set is longer than 2000
• If more than 10 embeds are set
• When using components V1, if more than 5 top-level components are set
• When using components V2, if more than 40 total components are set

For MessageEditBuilder

• If the content set is longer than 2000
• If more than 10 embeds are set
• When using components V1, if more than 5 top-level components are set
• When using components V2, if more than 40 total components are set

clear

@Nonnull
public R clear()

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 closeFiles() before calling clear() to close the files explicitly.

Returns:

The same builder instance for chaining

closeFiles

@Nonnull
public abstract R closeFiles()

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.

Returns:

The same builder instance for chaining