Class EmbedBuilder


  • public class EmbedBuilder
    extends java.lang.Object
    Builder system used to build MessageEmbeds.
    A visual breakdown of an Embed and how it relates to this class is available at https://imgur.com/a/yOb5n.
    Since:
    3.0
    Author:
    John A. Grosh
    • Field Detail

      • ZERO_WIDTH_SPACE

        public static final java.lang.String ZERO_WIDTH_SPACE
        See Also:
        Constant Field Values
      • URL_PATTERN

        public static final java.util.regex.Pattern URL_PATTERN
    • Constructor Detail

      • EmbedBuilder

        public EmbedBuilder()
        Creates an EmbedBuilder to be used to creates an embed to send.
        Every part of an embed can be removed or cleared by providing null to the setter method.
      • EmbedBuilder

        public EmbedBuilder​(EmbedBuilder builder)
      • EmbedBuilder

        public EmbedBuilder​(MessageEmbed embed)
        Creates an EmbedBuilder using fields in an existing embed.
        Parameters:
        embed - the existing embed
    • Method Detail

      • build

        public MessageEmbed build()
        Returns a MessageEmbed that has been checked as being valid for sending.
        Returns:
        the built, sendable MessageEmbed
        Throws:
        java.lang.IllegalStateException - If the embed is empty. Can be checked with isEmpty().
      • clear

        public EmbedBuilder clear()
        Resets this builder to default state.
        All parts will be either empty or null after this method has returned.
        Returns:
        The current EmbedBuilder with default values
      • isEmpty

        public boolean isEmpty()
        Checks if the given embed is empty. Empty embeds will throw an exception if built
        Returns:
        true if the embed is empty and cannot be built
      • length

        public int length()
        The overall length of the current EmbedBuilder in displayed characters.
        Represents the MessageEmbed.getLength() value.
        Returns:
        length of the current builder state
      • isValidLength

        public boolean isValidLength​(AccountType type)
        Checks whether the constructed MessageEmbed is within the limits for the specified AccountType
        Parameters:
        type - The AccountType to validate
        Returns:
        True, if the length is less or equal to the specific limit
        Throws:
        java.lang.IllegalArgumentException - If provided with null
      • setTitle

        public EmbedBuilder setTitle​(java.lang.String title)
        Sets the Title of the embed.
        Overload for setTitle(String, String) without URL parameter.

        Example

        Parameters:
        title - the title of the embed
        Returns:
        the builder after the title has been set
        Throws:
        java.lang.IllegalArgumentException -
      • setTitle

        public EmbedBuilder setTitle​(java.lang.String title,
                                     java.lang.String url)
        Sets the Title of the embed.
        You can provide null as url if no url should be used.

        Example

        Parameters:
        title - the title of the embed
        url - Makes the title into a hyperlink pointed at this url.
        Returns:
        the builder after the title has been set
        Throws:
        java.lang.IllegalArgumentException -
      • getDescriptionBuilder

        public java.lang.StringBuilder getDescriptionBuilder()
        The StringBuilder used to build the description for the embed.
        Note: To reset the description use setDescription(null)
        Returns:
        StringBuilder with current description context
      • setDescription

        public final EmbedBuilder setDescription​(java.lang.CharSequence description)
        Sets the Description of the embed. This is where the main chunk of text for an embed is typically placed.

        Example

        Parameters:
        description - the description of the embed, null to reset
        Returns:
        the builder after the description has been set
        Throws:
        java.lang.IllegalArgumentException - If the length of description is greater than MessageEmbed.TEXT_MAX_LENGTH
      • appendDescription

        public EmbedBuilder appendDescription​(java.lang.CharSequence description)
        Appends to the description of the embed. This is where the main chunk of text for an embed is typically placed.

        Example

        Parameters:
        description - the string to append to the description of the embed
        Returns:
        the builder after the description has been set
        Throws:
        java.lang.IllegalArgumentException -
      • setTimestamp

        public EmbedBuilder setTimestamp​(java.time.temporal.TemporalAccessor temporal)
        Sets the Timestamp of the embed.

        Example

        Hint: You can get the current time using Instant.now() or convert time from a millisecond representation by using Instant.ofEpochMilli(long);

        Parameters:
        temporal - the temporal accessor of the timestamp
        Returns:
        the builder after the timestamp has been set
      • setColor

        public EmbedBuilder setColor​(java.awt.Color color)
        Sets the Color of the embed. Example
        Parameters:
        color - The Color of the embed or null to use no color
        Returns:
        the builder after the color has been set
        See Also:
        setColor(int)
      • setThumbnail

        public EmbedBuilder setThumbnail​(java.lang.String url)
        Sets the Thumbnail of the embed.

        Example

        Uploading images with Embeds
        When uploading an image (using MessageChannel.sendFile(...)) you can reference said image using the specified filename as URI attachment://filename.ext.

        Example

        
         MessageChannel channel; // = reference of a MessageChannel
         MessageBuilder message = new MessageBuilder();
         EmbedBuilder embed = new EmbedBuilder();
         InputStream file = new URL("https://http.cat/500").openStream();
         embed.setThumbnail("attachment://cat.png") // we specify this in sendFile as "cat.png"
              .setDescription("This is a cute cat :3");
         message.setEmbed(embed.build());
         channel.sendFile(file, "cat.png", message.build()).queue();
         
        Parameters:
        url - the url of the thumbnail of the embed
        Returns:
        the builder after the thumbnail has been set
        Throws:
        java.lang.IllegalArgumentException -
      • setImage

        public EmbedBuilder setImage​(java.lang.String url)
        Sets the Image of the embed.

        Example

        Uploading images with Embeds
        When uploading an image (using MessageChannel.sendFile(...)) you can reference said image using the specified filename as URI attachment://filename.ext.

        Example

        
         MessageChannel channel; // = reference of a MessageChannel
         MessageBuilder message = new MessageBuilder();
         EmbedBuilder embed = new EmbedBuilder();
         InputStream file = new URL("https://http.cat/500").openStream();
         embed.setImage("attachment://cat.png") // we specify this in sendFile as "cat.png"
              .setDescription("This is a cute cat :3");
         message.setEmbed(embed.build());
         channel.sendFile(file, "cat.png", message.build()).queue();
         
        Parameters:
        url - the url of the image of the embed
        Returns:
        the builder after the image has been set
        Throws:
        java.lang.IllegalArgumentException -
        See Also:
        MessageChannel.sendFile(...)
      • setAuthor

        public EmbedBuilder setAuthor​(java.lang.String name)
        Sets the Author of the embed. The author appears in the top left of the embed and can have a small image beside it along with the author's name being made clickable by way of providing a url. This convenience method just sets the name.

        Example

        Parameters:
        name - the name of the author of the embed. If this is not set, the author will not appear in the embed
        Returns:
        the builder after the author has been set
      • setAuthor

        public EmbedBuilder setAuthor​(java.lang.String name,
                                      java.lang.String url)
        Sets the Author of the embed. The author appears in the top left of the embed and can have a small image beside it along with the author's name being made clickable by way of providing a url. This convenience method just sets the name and the url.

        Example

        Parameters:
        name - the name of the author of the embed. If this is not set, the author will not appear in the embed
        url - the url of the author of the embed
        Returns:
        the builder after the author has been set
        Throws:
        java.lang.IllegalArgumentException -
      • setAuthor

        public EmbedBuilder setAuthor​(java.lang.String name,
                                      java.lang.String url,
                                      java.lang.String iconUrl)
        Sets the Author of the embed. The author appears in the top left of the embed and can have a small image beside it along with the author's name being made clickable by way of providing a url.

        Example

        Uploading images with Embeds
        When uploading an image (using MessageChannel.sendFile(...)) you can reference said image using the specified filename as URI attachment://filename.ext.

        Example

        
         MessageChannel channel; // = reference of a MessageChannel
         MessageBuilder message = new MessageBuilder();
         EmbedBuilder embed = new EmbedBuilder();
         InputStream file = new URL("https://http.cat/500").openStream();
         embed.setAuthor("Minn", null, "attachment://cat.png") // we specify this in sendFile as "cat.png"
              .setDescription("This is a cute cat :3");
         message.setEmbed(embed.build());
         channel.sendFile(file, "cat.png", message.build()).queue();
         
        Parameters:
        name - the name of the author of the embed. If this is not set, the author will not appear in the embed
        url - the url of the author of the embed
        iconUrl - the url of the icon for the author
        Returns:
        the builder after the author has been set
        Throws:
        java.lang.IllegalArgumentException -
        • If the length of url is longer than MessageEmbed.URL_MAX_LENGTH.
        • If the provided url is not a properly formatted http or https url.
        • If the length of iconUrl is longer than MessageEmbed.URL_MAX_LENGTH.
        • If the provided iconUrl is not a properly formatted http or https url.
      • setFooter

        public EmbedBuilder setFooter​(java.lang.String text,
                                      java.lang.String iconUrl)
        Sets the Footer of the embed.

        Example

        Uploading images with Embeds
        When uploading an image (using MessageChannel.sendFile(...)) you can reference said image using the specified filename as URI attachment://filename.ext.

        Example

        
         MessageChannel channel; // = reference of a MessageChannel
         MessageBuilder message = new MessageBuilder();
         EmbedBuilder embed = new EmbedBuilder();
         InputStream file = new URL("https://http.cat/500").openStream();
         embed.setFooter("Cool footer!", "attachment://cat.png") // we specify this in sendFile as "cat.png"
              .setDescription("This is a cute cat :3");
         message.setEmbed(embed.build());
         channel.sendFile(file, "cat.png", message.build()).queue();
         
        Parameters:
        text - the text of the footer of the embed. If this is not set, the footer will not appear in the embed.
        iconUrl - the url of the icon for the footer
        Returns:
        the builder after the footer has been set
        Throws:
        java.lang.IllegalArgumentException -
      • addField

        public EmbedBuilder addField​(java.lang.String name,
                                     java.lang.String value,
                                     boolean inline)
        Adds a Field to the embed.

        Note: If a blank string is provided to either name or value, the blank string is replaced with ZERO_WIDTH_SPACE.

        Example of Inline

        Example if Non-inline

        Parameters:
        name - the name of the Field, displayed in bold above the value.
        value - the contents of the field.
        inline - whether or not this field should display inline.
        Returns:
        the builder after the field has been added
        Throws:
        java.lang.IllegalArgumentException -
      • addBlankField

        public EmbedBuilder addBlankField​(boolean inline)
        Adds a blank (empty) Field to the embed.

        Example of Inline

        Example of Non-inline

        Parameters:
        inline - whether or not this field should display inline
        Returns:
        the builder after the field has been added
      • clearFields

        public EmbedBuilder clearFields()
        Clears all fields from the embed, such as those created with the EmbedBuilder(MessageEmbed) constructor or via the addField methods.
        Returns:
        the builder after the field has been added
      • getFields

        public java.util.List<MessageEmbed.Field> getFields()
        Modifiable list of MessageEmbed Fields that the builder will use for build().
        You can add/remove Fields and restructure this List and it will then be applied in the built MessageEmbed. These fields will be available again through MessageEmbed.getFields().
        Returns:
        Mutable List of Fields