Package net.dv8tion.jda.api

Class MessageBuilder

java.lang.Object

net.dv8tion.jda.api.MessageBuilder

All Implemented Interfaces:

Appendable

public class MessageBuilder
extends Object
implements Appendable

Builder system used to build Messages.
Internally the builder uses a StringBuilder to take advantage of the efficiencies offered by the StringBuilder, and the methods provided by this class are a combination of those offered by the StringBuilder and String.format(String, Object...).

Since:

1.0

Author:

Michael Ritter, Aljoscha Grebe

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	MessageBuilder.Formatting	Holds the available formatting used in append(java.lang.CharSequence, net.dv8tion.jda.api.MessageBuilder.Formatting...)
static interface	MessageBuilder.SplitPolicy	Interface to allow custom implementation of Splitting rules for MessageBuilder.buildAll(SplitPolicy...).

Constructor Summary

Constructors

Constructor	Description
MessageBuilder()
MessageBuilder(CharSequence content)
MessageBuilder(EmbedBuilder builder)
MessageBuilder(Message message)
MessageBuilder(MessageEmbed embed)
MessageBuilder(MessageBuilder builder)

Method Summary

Modifier and Type	Method	Description
MessageBuilder	allowMentions(Message.MentionType... types)	Adds the provided MentionTypes to the whitelist.
MessageBuilder	append(char c)
MessageBuilder	append(CharSequence text)
MessageBuilder	append(CharSequence text, int start, int end)
MessageBuilder	append(CharSequence text, MessageBuilder.Formatting... format)	Appends a String using the specified chat Formatting(s).
MessageBuilder	append(Object object)	Appends the string representation of an object to the Message.
MessageBuilder	append(IMentionable mention)	Appends a mention to the Message.
MessageBuilder	appendCodeBlock(CharSequence text, CharSequence language)	Appends a code-block to the Message.
MessageBuilder	appendCodeLine(CharSequence text)	Appends a code-line to the Message.
MessageBuilder	appendFormat(String format, Object... args)	This method is an extended form of String.format(String, Object...).
Message	build()	Creates a Message object from this MessageBuilder
Queue<Message>	buildAll(MessageBuilder.SplitPolicy... policy)	Creates a Queue of Message objects from this MessageBuilder.
MessageBuilder	clear()	Clears the current builder.
MessageBuilder	clearMentionedRoles()	Removes the whitelist of mentioned roles.
MessageBuilder	clearMentionedUsers()	Removes the whitelist of mentioned users.
MessageBuilder	clearMentions()	Combination of clearMentionedRoles() and clearMentionedUsers().
MessageBuilder	denyMentions(Message.MentionType... types)	Removes the provided MentionTypes from the whitelist.
StringBuilder	getStringBuilder()	Returns the underlying StringBuilder.
int	indexOf(CharSequence target, int fromIndex, int endIndex)	Returns the index within this string of the first occurrence of the specified substring between the specified indices.
boolean	isEmpty()	Checks if the message contains any contend.
int	lastIndexOf(CharSequence target, int fromIndex, int endIndex)	Returns the index within this string of the last occurrence of the specified substring between the specified indices.
int	length()	Returns the current length of the content that will be built into a Message when build() is called.
MessageBuilder	mention(Collection<? extends IMentionable> mentions)	Adds the provided IMentionable instance to the whitelist of mentions.
MessageBuilder	mention(IMentionable... mentions)	Adds the provided IMentionable instance to the whitelist of mentions.
MessageBuilder	mentionRoles(long... roles)	Adds the provided Roles to the whitelist of mentions.
MessageBuilder	mentionRoles(String... roles)	Adds the provided Roles to the whitelist of mentions.
MessageBuilder	mentionUsers(long... users)	Adds the provided Users to the whitelist of mentions.
MessageBuilder	mentionUsers(String... users)	Adds the provided Users to the whitelist of mentions.
MessageBuilder	replace(String target, String replacement)	Replaces each substring that matches the target string with the specified replacement string.
MessageBuilder	replaceFirst(String target, String replacement)	Replaces the first substring that matches the target string with the specified replacement string.
MessageBuilder	replaceLast(String target, String replacement)	Replaces the last substring that matches the target string with the specified replacement string.
MessageBuilder	setActionRows(Collection<? extends ActionRow> rows)	Set the action rows for the message.
MessageBuilder	setActionRows(ActionRow... rows)	Set the action rows for the message.
MessageBuilder	setAllowedMentions(Collection<Message.MentionType> mentionTypes)	Sets which MentionTypes should be parsed from the input.
MessageBuilder	setContent(String content)	Sets the content of the resulting Message This will replace already added content.
MessageBuilder	setEmbeds(Collection<? extends MessageEmbed> embeds)	Adds up to 10 MessageEmbeds to the Message.
MessageBuilder	setEmbeds(MessageEmbed... embeds)	Adds up to 10 MessageEmbeds to the Message.
MessageBuilder	setNonce(String nonce)	Sets the nonce of the built message(s).
MessageBuilder	setTTS(boolean tts)	Makes the created Message a TTS message.

Methods inherited from class java.lang.Object

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

Constructor Detail

MessageBuilder

public MessageBuilder()

MessageBuilder

public MessageBuilder(@Nullable
                      CharSequence content)

MessageBuilder

public MessageBuilder(@Nullable
                      Message message)

MessageBuilder

public MessageBuilder(@Nullable
                      MessageBuilder builder)

MessageBuilder

public MessageBuilder(@Nullable
                      EmbedBuilder builder)

MessageBuilder

public MessageBuilder(@Nullable
                      MessageEmbed embed)

Method Detail

setTTS

@Nonnull
public MessageBuilder setTTS(boolean tts)

Makes the created Message a TTS message.
TTS stands for Text-To-Speech. When a TTS method is received by the Discord client, it is vocalized so long as the user has not disabled TTS.

Parameters:

tts - whether the created Message should be a tts message

Returns:

The MessageBuilder instance. Useful for chaining.

setEmbeds

@Nonnull
public MessageBuilder setEmbeds(@Nonnull
                                MessageEmbed... embeds)

Adds up to 10 MessageEmbeds to the Message. Embeds can be built using the EmbedBuilder and offer specialized formatting.

Parameters:

embeds - the embeds to add, or empty array to remove

Returns:

The MessageBuilder instance. Useful for chaining.

Throws:

IllegalArgumentException - If any of the provided MessageEmbeds is null or not sendable according to MessageEmbed.isSendable()! The sum of all MessageEmbed.getLength() must not be greater than MessageEmbed.EMBED_MAX_LENGTH_BOT!

setEmbeds

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

Adds up to 10 MessageEmbeds to the Message. Embeds can be built using the EmbedBuilder and offer specialized formatting.

Parameters:

embeds - the embeds to add, or empty list to remove

Returns:

The MessageBuilder instance. Useful for chaining.

Throws:

IllegalArgumentException - If any of the provided MessageEmbeds is null or not sendable according to MessageEmbed.isSendable()! The sum of all MessageEmbed.getLength() must not be greater than MessageEmbed.EMBED_MAX_LENGTH_BOT!

setActionRows

@Nonnull
public MessageBuilder setActionRows(@Nullable
                                    Collection<? extends ActionRow> rows)

Set the action rows for the message.

Parameters:

rows - The new action rows, or null to reset the components

Returns:

The MessageBuilder instance. Useful for chaining.

Throws:

IllegalArgumentException - If null is provided in the collection or more than 5 actions rows are provided

setActionRows

@Nonnull
public MessageBuilder setActionRows(@Nullable
                                    ActionRow... rows)

Set the action rows for the message.

Parameters:

rows - The new action rows, or null to reset the components

Returns:

The MessageBuilder instance. Useful for chaining.

Throws:

IllegalArgumentException - If null is provided in the array or more than 5 actions rows are provided

setNonce

@Nonnull
public MessageBuilder setNonce(@Nullable
                               String nonce)

Sets the nonce of the built message(s). It is recommended to have only 100% unique strings to validate messages via this nonce.
The nonce will be available from the resulting message via Message.getNonce() in message received by events and RestAction responses.
When null is provided no nonce will be used.

Parameters:

nonce - Validation nonce string

Returns:

The MessageBuilder instance. Useful for chaining.

See Also:

Message.getNonce(), Cryptographic Nonce - Wikipedia

setContent

@Nonnull
public MessageBuilder setContent(@Nullable
                                 String content)

Sets the content of the resulting Message
This will replace already added content.

Parameters:

content - The content to use, or null to reset the content

Returns:

The MessageBuilder instance. Useful for chaining.

See Also:

Message.getContentRaw()

append

@Nonnull
public MessageBuilder append(@Nullable
                             CharSequence text)

Specified by:

append in interface Appendable

append

@Nonnull
public MessageBuilder append(@Nullable
                             CharSequence text,
                             int start,
                             int end)

Specified by:

append in interface Appendable

append

@Nonnull
public MessageBuilder append(char c)

Specified by:

append in interface Appendable

append

@Nonnull
public MessageBuilder append(@Nullable
                             Object object)

Appends the string representation of an object to the Message.
This is the same as append(String.valueOf(object))

Parameters:

object - the object to append

Returns:

The MessageBuilder instance. Useful for chaining.

append

@Nonnull
public MessageBuilder append(@Nonnull
                             IMentionable mention)

Appends a mention to the Message.
Typical usage would be providing an IMentionable like User or TextChannel.

This will not add a rule to mention a User or Role. You have to use mention(IMentionable...) in addition to this method.

Parameters:

mention - the mention to append

Returns:

The MessageBuilder instance. Useful for chaining.

Throws:

IllegalArgumentException - If provided with null

append

@Nonnull
public MessageBuilder append(@Nullable
                             CharSequence text,
                             @Nonnull
                             MessageBuilder.Formatting... format)

Appends a String using the specified chat Formatting(s).

Parameters:

text - the text to append.

format - the format(s) to apply to the text.

Returns:

The MessageBuilder instance. Useful for chaining.

appendFormat

@Nonnull
public MessageBuilder appendFormat(@Nonnull
                                   String format,
                                   @Nonnull
                                   Object... args)

This method is an extended form of String.format(String, Object...). It allows for all of the token replacement functionality that String.format(String, Object...) supports.
A lot of JDA entities implement Formattable and will provide specific format outputs for their specific type.

• IMentionable
  These will output their getAsMention by default, some implementations have alternatives such as User and TextChannel.
• MessageChannel
  All message channels format to "#" + getName() by default, TextChannel has special handling and uses the getAsMention output by default and the MessageChannel output as alternative (# flag).
• Message
  Messages by default output their getContentDisplay() value and as alternative use the getContentRaw() value

Example:
If you placed the following code in an method handling a MessageReceivedEvent

 User user = event.getAuthor();
 MessageBuilder builder = new MessageBuilder();
 builder.appendFormat("%#s is really cool!", user);
 builder.build();
 

It would build a message that mentions the author and says that he is really cool!. If the user's name was "Minn" and his discriminator "6688", it would say:

  "Minn#6688 is really cool!"

Note that this uses the # flag to utilize the alternative format for User.
By default it would fallback to IMentionable.getAsMention()

Parameters:

format - a format string.

args - an array objects that will be used to replace the tokens, they must be provided in the order that the tokens appear in the provided format string.

Returns:

The MessageBuilder instance. Useful for chaining.

Throws:

IllegalArgumentException - If the provided format string is null or empty

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.

appendCodeLine

@Nonnull
public MessageBuilder appendCodeLine(@Nullable
                                     CharSequence text)

Appends a code-line to the Message. Code Lines are similar to code-blocks, however they are displayed in-line and do not support language specific highlighting.

Parameters:

text - the code to append

Returns:

The MessageBuilder instance. Useful for chaining.

appendCodeBlock

@Nonnull
public MessageBuilder appendCodeBlock(@Nullable
                                      CharSequence text,
                                      @Nullable
                                      CharSequence language)

Appends a code-block to the Message.
Discord uses Highlight.js for its language highlighting support. You can find out what specific languages are supported here.

Parameters:

text - the code to append

language - the language of the code. If unknown use an empty string

Returns:

The MessageBuilder instance. Useful for chaining.

length

public int length()

Returns the current length of the content that will be built into a Message when build() is called.
If this value is 0 (and there is no embed) or greater than 2000 when build() is called, an exception will be raised as you cannot send an empty message to Discord and Discord has a hard limit of 2000 characters per message.

Hint: You can use build(int, int) or buildAll(SplitPolicy...) as possible ways to deal with the 2000 character cap.

Returns:

the current length of the content that will be built into a Message.

isEmpty

public boolean isEmpty()

Checks if the message contains any contend. This includes text as well as embeds.

Returns:

whether the message contains content

replace

@Nonnull
public MessageBuilder replace(@Nonnull
                              String target,
                              @Nonnull
                              String replacement)

Replaces each substring that matches the target string with the specified replacement string. The replacement proceeds from the beginning of the string to the end, for example, replacing "aa" with "b" in the message "aaa" will result in "ba" rather than "ab".

Parameters:

target - the sequence of char values to be replaced

replacement - the replacement sequence of char values

Returns:

The MessageBuilder instance. Useful for chaining.

replaceFirst

@Nonnull
public MessageBuilder replaceFirst(@Nonnull
                                   String target,
                                   @Nonnull
                                   String replacement)

Replaces the first substring that matches the target string with the specified replacement string.

Parameters:

target - the sequence of char values to be replaced

replacement - the replacement sequence of char values

Returns:

The MessageBuilder instance. Useful for chaining.

replaceLast

@Nonnull
public MessageBuilder replaceLast(@Nonnull
                                  String target,
                                  @Nonnull
                                  String replacement)

Replaces the last substring that matches the target string with the specified replacement string.

Parameters:

target - the sequence of char values to be replaced

replacement - the replacement sequence of char values

Returns:

The MessageBuilder instance. Useful for chaining.

clearMentionedUsers

@Nonnull
public MessageBuilder clearMentionedUsers()

Removes the whitelist of mentioned users.
If setAllowedMentions(Collection) does not contain MentionType.USER then no user will be mentioned.

Returns:

The MessageBuilder instance. Useful for chaining.

clearMentionedRoles

@Nonnull
public MessageBuilder clearMentionedRoles()

Removes the whitelist of mentioned roles.
If setAllowedMentions(Collection) does not contain MentionType.ROLE then no role will be mentioned.

Returns:

The MessageBuilder instance. Useful for chaining.

clearMentions

@Nonnull
public MessageBuilder clearMentions()

Combination of clearMentionedRoles() and clearMentionedUsers().

This will not affect setAllowedMentions(Collection). You can reset those to default by using setAllowedMentions(null).

Returns:

The MessageBuilder instance. Useful for chaining.

setAllowedMentions

@Nonnull
public MessageBuilder setAllowedMentions(@Nullable
                                         Collection<Message.MentionType> mentionTypes)

Sets which MentionTypes should be parsed from the input. This will use MessageAction.getDefaultMentions() by default, or if null is provided.

Parameters:

mentionTypes - Collection of allowed mention types, or null to use MessageAction.getDefaultMentions().

Returns:

The MessageBuilder instance. Useful for chaining.

allowMentions

@Nonnull
public MessageBuilder allowMentions(@Nonnull
                                    Message.MentionType... types)

Adds the provided MentionTypes to the whitelist.

Parameters:

types - The mention types to allow

Returns:

The MessageBuilder instance. Useful for chaining.

Throws:

IllegalArgumentException - If null is provided

denyMentions

@Nonnull
public MessageBuilder denyMentions(@Nonnull
                                   Message.MentionType... types)

Removes the provided MentionTypes from the whitelist.

Parameters:

types - The mention types to deny

Returns:

The MessageBuilder instance. Useful for chaining.

Throws:

IllegalArgumentException - If null is provided

mention

@Nonnull
public MessageBuilder mention(@Nonnull
                              IMentionable... mentions)

Adds the provided IMentionable instance to the whitelist of mentions.
This will only affect instances of User, Member, and Role.
The content will not be affected by this. To append a mention use append(IMentionable).

See AllowedMentions.mention(IMentionable...) for more details.

Parameters:

mentions - Whitelist of mentions to apply

Returns:

The MessageBuilder instance. Useful for chaining.

Throws:

IllegalArgumentException - If null is provided

See Also:

clearMentions(), AllowedMentions.mention(IMentionable...)

mention

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

Adds the provided IMentionable instance to the whitelist of mentions.
This will only affect instances of User, Member, and Role.
The content will not be affected by this. To append a mention use append(IMentionable).

See AllowedMentions.mention(IMentionable...) for more details.

Parameters:

mentions - Whitelist of mentions to apply

Returns:

The MessageBuilder instance. Useful for chaining.

Throws:

IllegalArgumentException - If null is provided

See Also:

clearMentions(), AllowedMentions.mention(IMentionable...)

mentionUsers

@Nonnull
public MessageBuilder mentionUsers(@Nonnull
                                   String... users)

Adds the provided Users to the whitelist of mentions.
The provided list must only contain IDs of users.
The content will not be affected by this. To append a mention use append("<@").append(id).append(">").

See AllowedMentions.mentionUsers(String...) for more details.

Parameters:

users - Whitelist of user IDs to apply

Returns:

The MessageBuilder instance. Useful for chaining.

Throws:

IllegalArgumentException - If null is provided

See Also:

clearMentionedUsers(), AllowedMentions.mentionUsers(String...)

mentionRoles

@Nonnull
public MessageBuilder mentionRoles(@Nonnull
                                   String... roles)

Adds the provided Roles to the whitelist of mentions.
The provided list must only contain IDs of roles.
The content will not be affected by this. To append a mention use append("<@&").append(id).append(">").

See AllowedMentions.mentionRoles(String...) for more details.

Parameters:

roles - Whitelist of role IDs to apply

Returns:

The MessageBuilder instance. Useful for chaining.

Throws:

IllegalArgumentException - If null is provided

See Also:

clearMentionedRoles(), AllowedMentions.mentionRoles(String...)

mentionUsers

@Nonnull
public MessageBuilder mentionUsers(@Nonnull
                                   long... users)

Adds the provided Users to the whitelist of mentions.
The provided list must only contain IDs of users.
The content will not be affected by this. To append a mention use append("<@").append(id).append(">").

See AllowedMentions.mentionUsers(long...) for more details.

Parameters:

users - Whitelist of user IDs to apply

Returns:

The MessageBuilder instance. Useful for chaining.

Throws:

IllegalArgumentException - If null is provided

See Also:

clearMentionedUsers(), AllowedMentions.mentionUsers(long...)

mentionRoles

@Nonnull
public MessageBuilder mentionRoles(@Nonnull
                                   long... roles)

Adds the provided Roles to the whitelist of mentions.
The provided list must only contain IDs of roles.
The content will not be affected by this. To append a mention use append("<@&").append(id).append(">").

See AllowedMentions.mentionRoles(long...) for more details.

Parameters:

roles - Whitelist of role IDs to apply

Returns:

The MessageBuilder instance. Useful for chaining.

Throws:

IllegalArgumentException - If null is provided

See Also:

clearMentionedRoles(), AllowedMentions.mentionRoles(long...)

getStringBuilder

@Nonnull
public StringBuilder getStringBuilder()

Returns the underlying StringBuilder.

Returns:

The StringBuilder used by this MessageBuilder

clear

@Nonnull
public MessageBuilder clear()

Clears the current builder. Useful for mass message creation.

This will not clear the allowed mentions.

Returns:

The MessageBuilder instance. Useful for chaining.

indexOf

public int indexOf(@Nonnull
                   CharSequence target,
                   int fromIndex,
                   int endIndex)

Returns the index within this string of the first occurrence of the specified substring between the specified indices.

If no such value of target exists, then -1 is returned.

Parameters:

target - the substring to search for.

fromIndex - the index from which to start the search.

endIndex - the index at which to end the search.

Returns:

the index of the first occurrence of the specified substring between the specified indices or -1 if there is no such occurrence.

Throws:

IndexOutOfBoundsException -

• If the fromIndex is outside of the range of 0 to length()
• If the endIndex is outside of the range of 0 to length()
• If the fromIndex is greater than endIndex

lastIndexOf

public int lastIndexOf(@Nonnull
                       CharSequence target,
                       int fromIndex,
                       int endIndex)

Returns the index within this string of the last occurrence of the specified substring between the specified indices. If no such value of target exists, then -1 is returned.

Parameters:

target - the substring to search for.

fromIndex - the index from which to start the search.

endIndex - the index at which to end the search.

Returns:

the index of the last occurrence of the specified substring between the specified indices or -1 if there is no such occurrence.

Throws:

IndexOutOfBoundsException -

• If the fromIndex is outside of the range of 0 to length()
• If the endIndex is outside of the range of 0 to length()
• If the fromIndex is greater than endIndex

build

@Nonnull
public Message build()

Creates a Message object from this MessageBuilder

Hint: You can use build(int, int) or buildAll(SplitPolicy...) as possible ways to deal with the 2000 character cap.

Returns:

the created Message

Throws:

IllegalStateException -

• If you attempt to build() an empty Message (length() is 0 and no MessageEmbed was provided to setEmbeds(MessageEmbed...)
• If you attempt to build() a Message with more than 2000 characters of content.

buildAll

@Nonnull
public Queue<Message> buildAll(@Nullable
                               MessageBuilder.SplitPolicy... policy)

Creates a Queue of Message objects from this MessageBuilder.

This method splits the content if it exceeds 2000 chars. The splitting behaviour can be customized using SplitPolicies. The method will try the policies in the order they are passed to it.
If no SplitPolicy is provided each message will be split after exactly 2000 chars.

This is not Markdown safe. An easy workaround is to include Zero Width Spaces as predetermined breaking points to the message and only split on them.

Parameters:

policy - The MessageBuilder.SplitPolicy defining how to split the text in the MessageBuilder into different, individual messages.

Returns:

the created Messages