public class MessageBuilder
extends java.lang.Object
implements java.lang.Appendable
Messages
.
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...)
.Modifier and Type | Class and Description |
---|---|
static class |
MessageBuilder.Formatting
Holds the available formatting used in
append(java.lang.CharSequence, net.dv8tion.jda.core.MessageBuilder.Formatting...) |
static class |
MessageBuilder.MentionType
Holds the strippable mention types used in
stripMentions(JDA, MentionType...)
and stripMentions(Guild, MentionType...) |
static interface |
MessageBuilder.SplitPolicy
Interface to allow custom implementation of Splitting rules for
MessageBuilder.buildAll(SplitPolicy...) . |
Constructor and Description |
---|
MessageBuilder() |
Modifier and Type | Method and Description |
---|---|
MessageBuilder |
append(char c) |
MessageBuilder |
append(java.lang.CharSequence text)
Appends a String to the Message.
|
MessageBuilder |
append(java.lang.CharSequence text,
int start,
int end) |
MessageBuilder |
append(java.lang.CharSequence text,
MessageBuilder.Formatting... format)
Appends a String using the specified chat
Formatting(s) . |
MessageBuilder |
append(IMentionable mention)
Appends a mention to the Message.
|
MessageBuilder |
append(java.lang.Object object)
Appends the string representation of an object to the Message.
|
MessageBuilder |
appendCodeBlock(java.lang.CharSequence text,
java.lang.CharSequence language)
Appends a code-block to the Message.
|
MessageBuilder |
appendFormat(java.lang.String format,
java.lang.Object... args)
This method is an extended form of
String.format(String, Object...) . |
Message |
build()
Creates a
Message object from this MessageBuilder |
java.util.Queue<Message> |
buildAll(MessageBuilder.SplitPolicy... policy)
Creates a
Queue of Message objects from this MessageBuilder. |
MessageBuilder |
clear()
Clears the current builder.
|
java.lang.StringBuilder |
getStringBuilder()
Returns the underlying
StringBuilder . |
int |
indexOf(java.lang.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(java.lang.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()
|
MessageBuilder |
replaceAll(java.lang.String target,
java.lang.String replacement)
Replaces each substring that matches the target string with the specified replacement string.
|
MessageBuilder |
replaceFirst(java.lang.String target,
java.lang.String replacement)
Replaces the first substring that matches the target string with the specified replacement string.
|
MessageBuilder |
replaceLast(java.lang.String target,
java.lang.String replacement)
Replaces the last substring that matches the target string with the specified replacement string.
|
MessageBuilder |
setEmbed(MessageEmbed embed)
Adds a
MessageEmbed to the Message. |
MessageBuilder |
setTTS(boolean tts)
Makes the created Message a TTS message.
|
MessageBuilder |
stripMentions(Guild guild)
Removes all mentions and replaces them with the closest looking textual representation.
|
MessageBuilder |
stripMentions(Guild guild,
MessageBuilder.MentionType... types)
Removes all mentions of the specified types and replaces them with the closest looking textual representation.
|
MessageBuilder |
stripMentions(JDA jda)
Removes all mentions and replaces them with the closest looking textual representation.
|
MessageBuilder |
stripMentions(JDA jda,
MessageBuilder.MentionType... types)
Removes all mentions of the specified types and replaces them with the closest looking textual representation.
|
public MessageBuilder setTTS(boolean tts)
tts
- whether the created Message should be a tts messageMessageBuilder
instance. Useful for chaining.public MessageBuilder setEmbed(MessageEmbed embed)
MessageEmbed
to the Message. Embeds can be built using
the EmbedBuilder
and offer specialized formatting.embed
- the embed to add, or null to removeMessageBuilder
instance. Useful for chaining.public MessageBuilder append(java.lang.CharSequence text)
append
in interface java.lang.Appendable
text
- the text to appendMessageBuilder
instance. Useful for chaining.public MessageBuilder append(java.lang.CharSequence text, int start, int end)
append
in interface java.lang.Appendable
public MessageBuilder append(char c)
append
in interface java.lang.Appendable
public MessageBuilder append(java.lang.Object object)
append(String.valueOf(object))
object
- the object to appendMessageBuilder
instance. Useful for chaining.public MessageBuilder append(IMentionable mention)
IMentionable
like
User
or TextChannel
.mention
- the mention to appendMessageBuilder
instance. Useful for chaining.public MessageBuilder append(java.lang.CharSequence text, MessageBuilder.Formatting... format)
Formatting(s)
.text
- the text to append.format
- the format(s) to apply to the text.MessageBuilder
instance. Useful for chaining.public MessageBuilder appendFormat(java.lang.String format, java.lang.Object... args)
String.format(String, Object...)
. It allows for all of
the token replacement functionality that String.format(String, Object...) supports.
Formattable
and will provide
specific format outputs for their specific type.
IMentionable
getAsMention
by default,
some implementations have alternatives such as User
and TextChannel
.MessageChannel
"#" + getName()
by default, TextChannel has special handling
and uses the getAsMention output by default and the MessageChannel output as alternative (#
flag).Message
getContent()
value and
as alternative use the getRawContent()
valueExample:
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!"
#
flag to utilize the alternative format for User
.
IMentionable.getAsMention()
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.MessageBuilder
instance. Useful for chaining.java.lang.IllegalArgumentException
- If the provided format string is null
or emptypublic MessageBuilder appendCodeBlock(java.lang.CharSequence text, java.lang.CharSequence language)
text
- the code to appendlanguage
- the language of the code. If unknown use an empty stringMessageBuilder
instance. Useful for chaining.public int length()
Message
when build()
is called.
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.
public boolean isEmpty()
public Message build()
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.
Message
java.lang.IllegalStateException
- length()
is 0
and no
MessageEmbed
was provided to setEmbed(net.dv8tion.jda.core.entities.MessageEmbed)
)public MessageBuilder replaceAll(java.lang.String target, java.lang.String replacement)
target
- the sequence of char values to be replacedreplacement
- the replacement sequence of char valuesMessageBuilder
instance. Useful for chaining.public MessageBuilder replaceFirst(java.lang.String target, java.lang.String replacement)
target
- the sequence of char values to be replacedreplacement
- the replacement sequence of char valuesMessageBuilder
instance. Useful for chaining.public MessageBuilder replaceLast(java.lang.String target, java.lang.String replacement)
target
- the sequence of char values to be replacedreplacement
- the replacement sequence of char valuesMessageBuilder
instance. Useful for chaining.public MessageBuilder stripMentions(JDA jda)
Use this over stripMentions(Guild)
if User
mentions
should be replaced with their User.getName()
instead of their Nicknames.
jda
- The JDA instance used to resolve the mentions.MessageBuilder
instance. Useful for chaining.public MessageBuilder stripMentions(Guild guild)
Use this over stripMentions(JDA)
if User
mentions should
be replaced with their nicknames in a specific guild based.
Uses Member.getEffectiveName()
guild
- the guild for User
mentionsMessageBuilder
instance. Useful for chaining.public MessageBuilder stripMentions(Guild guild, MessageBuilder.MentionType... types)
Use this over stripMentions(JDA, MentionType...)
if User
mentions should
be replaced with their nicknames in a specific guild based.
Uses Member.getEffectiveName()
guild
- the guild for User
mentionstypes
- the MentionTypes
that should be strippedMessageBuilder
instance. Useful for chaining.public MessageBuilder stripMentions(JDA jda, MessageBuilder.MentionType... types)
Use this over stripMentions(Guild, MentionType...)
if User
mentions should be replaced with their User.getName()
.
jda
- The JDA instance used to resolve the mentions.types
- the MentionTypes
that should be strippedMessageBuilder
instance. Useful for chaining.public java.lang.StringBuilder getStringBuilder()
StringBuilder
.StringBuilder
used by this MessageBuilder
public MessageBuilder clear()
MessageBuilder
instance. Useful for chaining.public int indexOf(java.lang.CharSequence target, int fromIndex, int endIndex)
If no such value of target
exists, then -1
is returned.
target
- the substring to search for.fromIndex
- the index from which to start the search.endIndex
- the index at which to end the search.-1
if there is no such occurrence.java.lang.IndexOutOfBoundsException
- public int lastIndexOf(java.lang.CharSequence target, int fromIndex, int endIndex)
target
exists, then -1
is returned.target
- the substring to search for.fromIndex
- the index from which to start the search.endIndex
- the index at which to end the search.-1
if there is no such occurrence.java.lang.IndexOutOfBoundsException
- public java.util.Queue<Message> buildAll(MessageBuilder.SplitPolicy... policy)
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.
policy
- The MessageBuilder.SplitPolicy
defining how to split the text in the
MessageBuilder into different, individual messages.Messages