Package com.mewna.catnip.entity.message

Class MessageOptions

java.lang.Object
com.mewna.catnip.entity.message.MessageOptions
public class MessageOptions extends Object
Options used for creating a new message.
Since:
10/10/2018
Author:
SamOphis

  • Constructor Details

    • MessageOptions

      public MessageOptions(@Nonnull MessageOptions options)

    • MessageOptions

      public MessageOptions(@Nonnull Message message)

    • MessageOptions

      public MessageOptions()

  • Method Details

    • addFile

      @CheckReturnValue @Nonnull public MessageOptions addFile(@Nonnull File file)
      Adds a file, used when sending messages. Files are NOT added to constructed Message instances.

      The name of the file/attachment is taken from File.getName().

      Parameters:
      file - A non-null, existing, readable File instance.
      Returns:
      Itself.
      See Also:

    • addFile

      @CheckReturnValue @Nonnull public MessageOptions addFile(@Nonnull String name, @Nonnull File file)
      Adds a file, used when sending messages. Files are NOT added to constructed Message instances.

      This allows you to specify a custom name for the file, unlike addFile(File).

      Parameters:
      name - A not-null name for the file.
      file - A not-null, existing, readable File instance.
      Returns:
      Itself.
      See Also:

    • addFile

      @CheckReturnValue @Nonnull public MessageOptions addFile(@Nonnull String name, @Nonnull InputStream stream)
      Adds an input stream/file, used when sending messages. Files are NOT added to constructed Message instances.

      This allows you to specify a custom name for the input stream data, unlike addFile(File).

      Parameters:
      name - A not-null name for the file.
      stream - A not-null, readable InputStream.
      Returns:
      Itself.
      See Also:

    • referenceMessage

      @Nonnull @CheckReturnValue public MessageOptions referenceMessage(@Nullable MessageReference reference)
      Sets the reference on this message. Reference may be null. Used for things like inline replies. [
      Parameters:
      reference - The nullable reference to set
      Returns:
      Itself.

    • withFlags

      public MessageOptions withFlags(@Nonnull Set<MessageFlag> flags)
      Set flags on this message. Flags are used for things like embed suppression.
      Parameters:
      flags - The flags to set, or an empty set for none.
      Returns:
      Itself.

    • addFile

      @CheckReturnValue @Nonnull public MessageOptions addFile(@Nonnull String name, @Nonnull byte[] data)
      Adds raw data/a file, used when sending messages. Files are NOT added to constructed Message instances.

      This allows you to specify a custom name for the raw data, unlike addFile(File).

      Parameters:
      name - A not-null name for the file.
      data - A not-null byte array containing the raw data for the file.
      Returns:
      Itself.
      See Also:

    • hasFiles

      @CheckReturnValue public boolean hasFiles()
      Checks to see whether or not this MessageOptions instance has any files attached.

      This should be used over !files().isEmpty() because it doesn't construct a new list for each read.

      Returns:
      True or false.

    • files

      @CheckReturnValue @Nonnull public List<org.apache.commons.lang3.tuple.ImmutablePair<String,byte[]>> files()
      Constructs a new immutable list containing all of the raw file data. Each immutable pair contains the name and the data buffer.

      This method is expensive! It constructs a new list each time and should be used sparingly.

      Returns:
      A copy of the raw file list.

    • parseNoMentions

      @CheckReturnValue @Nonnull public MessageOptions parseNoMentions()
      Clears parse flags or sets it to an empty set to mark as mention none. This may be overwritten by user and role mention whitelists.
      Returns:
      Itself.

    • parseAllMentions

      @CheckReturnValue @Nonnull public MessageOptions parseAllMentions()
      Nullifies the parse flags set to mark as mention all. This may be overwritten by user and role mention whitelists.
      Returns:
      Itself.

    • parseMentionsByName

      @CheckReturnValue @Nonnull public MessageOptions parseMentionsByName(Collection<String> flags)
      Add a restriction on who gets mentioned by this message. This does NOT get added to constructed Message instances.
      Parameters:
      flags - A collection of mentions to allow parsing for.
      Returns:
      Itself.

    • parseMentionsByName

      @CheckReturnValue @Nonnull public MessageOptions parseMentionsByName(String... flags)
      Add a restriction on who gets mentioned by this message. This does NOT get added to constructed Message instances.
      Parameters:
      flags - An array of mentions to allow parsing for.
      Returns:
      Itself.

    • parseMentions

      @CheckReturnValue @Nonnull public MessageOptions parseMentions(Collection<MentionParseFlag> flags)
      Add a restriction on who gets mentioned by this message. This does NOT get added to constructed Message instances.
      Parameters:
      flags - A collection of mentions to allow parsing for.
      Returns:
      Itself.

    • parseMentions

      @CheckReturnValue @Nonnull public MessageOptions parseMentions(MentionParseFlag... flags)
      Add a restriction on who gets mentioned by this message. This does NOT get added to constructed Message instances.
      Parameters:
      flags - An array of mentions to allow parsing for.
      Returns:
      Itself.

    • parseMentionByName

      @CheckReturnValue @Nonnull public MessageOptions parseMentionByName(String flag)
      Add a restriction on who gets mentioned by this message. This does NOT get added to constructed Message instances.
      Parameters:
      flag - A mention to allow parsing for.
      Returns:
      Itself.

    • parseMention

      @CheckReturnValue @Nonnull public MessageOptions parseMention(MentionParseFlag flag)
      Add a restriction on who gets mentioned by this message. This does NOT get added to constructed Message instances.
      Parameters:
      flag - A mention to allow parsing for.
      Returns:
      Itself.

    • mentionNoUsers

      @CheckReturnValue @Nonnull public MessageOptions mentionNoUsers()
      Clears users or sets it to an empty set to mark as mention none. This has no effect if users is present in the parse flags set.
      Returns:
      Itself.

    • mentionAllUsers

      @CheckReturnValue @Nonnull public MessageOptions mentionAllUsers()
      Nullifies the users set to mark as mention all. This has no effect if users is present in the parse flags set.
      Returns:
      Itself.

    • mentionMembers

      @CheckReturnValue @Nonnull public MessageOptions mentionMembers(Collection<Member> users)
      Adds users to the mention whitelist. Mentions are NOT added to constructed Message instances. This list has no effect if users is present in the parse flags set.
      Parameters:
      users - A collection of members to add.
      Returns:
      Itself.

    • mentionMembers

      @CheckReturnValue @Nonnull public MessageOptions mentionMembers(Member... users)
      Adds users to the mention whitelist. Mentions are NOT added to constructed Message instances. This list has no effect if users is present in the parse flags set.
      Parameters:
      users - An array of members to add.
      Returns:
      Itself.

    • mentionUsers

      @CheckReturnValue @Nonnull public MessageOptions mentionUsers(Collection<User> users)
      Adds users to the mention whitelist. Mentions are NOT added to constructed Message instances. This list has no effect if users is present in the parse flags set.
      Parameters:
      users - A collection of users to add.
      Returns:
      Itself.

    • mentionUsers

      @CheckReturnValue @Nonnull public MessageOptions mentionUsers(User... users)
      Adds users to the mention whitelist. Mentions are NOT added to constructed Message instances. This list has no effect if users is present in the parse flags set.
      Parameters:
      users - An array of users to add.
      Returns:
      Itself.

    • mentionUsersById

      @CheckReturnValue @Nonnull public MessageOptions mentionUsersById(Collection<String> users)
      Adds users to the mention whitelist. Mentions are NOT added to constructed Message instances. This list has no effect if users is present in the parse flags set. There is NO validation of if any of these strings are a proper snowflake.
      Parameters:
      users - A collection of user IDs to add.
      Returns:
      Itself.

    • mentionUsersById

      @CheckReturnValue @Nonnull public MessageOptions mentionUsersById(String... users)
      Adds users to the mention whitelist. Mentions are NOT added to constructed Message instances. This list has no effect if users is present in the parse flags set. There is NO validation of if any of these strings are a proper snowflake.
      Parameters:
      users - An array of user IDs to add.
      Returns:
      Itself.

    • mentionUsersById

      @CheckReturnValue @Nonnull public MessageOptions mentionUsersById(long... users)
      Adds users to the mention whitelist. Mentions are NOT added to constructed Message instances. This list has no effect if users is present in the parse flags set.
      Parameters:
      users - An array of user IDs to add.
      Returns:
      Itself.

    • mentionMember

      @CheckReturnValue @Nonnull public MessageOptions mentionMember(Member member)
      Adds a user to the mention whitelist. Mentions are NOT added to constructed Message instances. This list has no effect if users is present in the parse flags set.
      Parameters:
      member - A member to add.
      Returns:
      Itself.

    • mentionUser

      @CheckReturnValue @Nonnull public MessageOptions mentionUser(User user)
      Adds a user to the mention whitelist. Mentions are NOT added to constructed Message instances. This list has no effect if users is present in the parse flags set.
      Parameters:
      user - A user to add.
      Returns:
      Itself.

    • mentionUserById

      @CheckReturnValue @Nonnull public MessageOptions mentionUserById(String id)
      Adds a user to the mention whitelist. Mentions are NOT added to constructed Message instances. This list has no effect if users is present in the parse flags set. There is NO validation of if the string is a proper snowflake.
      Parameters:
      id - A user ID to add.
      Returns:
      Itself.

    • mentionUserById

      @CheckReturnValue @Nonnull public MessageOptions mentionUserById(long id)
      Adds a user to the mention whitelist. Mentions are NOT added to constructed Message instances. This list has no effect if users is present in the parse flags set.
      Parameters:
      id - A user ID to add.
      Returns:
      Itself.

    • mentionedUsers

      @CheckReturnValue @Nullable public Set<String> mentionedUsers()
      A whitelist of mentioned users. Mentions returned from here are NOT added to constructed Message instances. This list has no effect if users is present in the parse flags set. There is NO validation of if any of the strings are a proper snowflake.
      Returns:
      Mutable whitelist of user IDs, or null for all.

    • mentionNoRoles

      @CheckReturnValue @Nonnull public MessageOptions mentionNoRoles()
      Clears roles or sets it to an empty set to mark as mention none. This has no effect if roles is present in the parse flags set.
      Returns:
      Itself.

    • mentionAllRoles

      @CheckReturnValue @Nonnull public MessageOptions mentionAllRoles()
      Nullifies the roles set to mark as mention all. This has no effect if roles is present in the parse flags set.
      Returns:
      Itself.

    • mentionRoles

      @CheckReturnValue @Nonnull public MessageOptions mentionRoles(Collection<Role> roles)
      Adds roles to the mention whitelist. Mentions are NOT added to constructed Message instances. This list has no effect if roles is present in the parse flags set.
      Parameters:
      roles - A collection of roles to add.
      Returns:
      Itself.

    • mentionRoles

      @CheckReturnValue @Nonnull public MessageOptions mentionRoles(Role... roles)
      Adds roles to the mention whitelist. Mentions are NOT added to constructed Message instances. This list has no effect if roles is present in the parse flags set.
      Parameters:
      roles - An array of roles to add.
      Returns:
      Itself.

    • mentionRolesById

      @CheckReturnValue @Nonnull public MessageOptions mentionRolesById(Collection<String> roles)
      Adds roles to the mention whitelist. Mentions are NOT added to constructed Message instances. This list has no effect if roles is present in the parse flags set. There is NO validation of if any of the strings are a proper snowflake.
      Parameters:
      roles - A collection of role IDs to add.
      Returns:
      Itself.

    • mentionRolesById

      @CheckReturnValue @Nonnull public MessageOptions mentionRolesById(String... roles)
      Adds roles to the mention whitelist. Mentions are NOT added to constructed Message instances. This list has no effect if roles is present in the parse flags set. There is NO validation of if any of the strings are a proper snowflake.
      Parameters:
      roles - An array of role IDs to add.
      Returns:
      Itself.

    • mentionRolesById

      @CheckReturnValue @Nonnull public MessageOptions mentionRolesById(long... roles)
      Adds roles to the mention whitelist. Mentions are NOT added to constructed Message instances. This list has no effect if roles is present in the parse flags set.
      Parameters:
      roles - An array of role IDs to add.
      Returns:
      Itself.

    • mentionRole

      @CheckReturnValue @Nonnull public MessageOptions mentionRole(Role role)
      Adds a role to the mention whitelist. Mentions are NOT added to constructed Message instances. This list has no effect if roles is present in the parse flags set.
      Parameters:
      role - A role to add.
      Returns:
      Itself.

    • mentionRoleById

      @CheckReturnValue @Nonnull public MessageOptions mentionRoleById(String id)
      Adds a role to the mention whitelist. Mentions are NOT added to constructed Message instances. This list has no effect if roles is present in the parse flags set. There is NO validation of if the string is a proper snowflake.
      Parameters:
      id - An ID for a role to add.
      Returns:
      Itself.

    • mentionRoleById

      @CheckReturnValue @Nonnull public MessageOptions mentionRoleById(long id)
      Adds a role to the mention whitelist. Mentions are NOT added to constructed Message instances. This list has no effect if roles is present in the parse flags set.
      Parameters:
      id - A role ID to add.
      Returns:
      Itself.

    • mentionedRoles

      @CheckReturnValue @Nullable public Set<String> mentionedRoles()
      A whitelist of mentioned roles. Mentions returned from here are NOT added to constructed Message instances. This list has no effect if roles is present in the parse flags set. There is NO validation of if any of the strings are a proper snowflake.
      Returns:
      Mutable whitelist of roles IDs, or null for all.

    • clear

      @CheckReturnValue @Nonnull public MessageOptions clear()
      Resets this MessageOptions class back to its initial state where there is no content, no embeds or no files.
      Returns:
      Itself (but with a clean state).

    • addEmbed

      @Nonnull @CheckReturnValue public MessageOptions addEmbed(@Nonnull Embed embed)

    • addComponent

      @Nonnull @CheckReturnValue public MessageOptions addComponent(@Nonnull ActionRow component)
      Adds the specified row to the message. Currently, only ActionRows can be top-level components.
      Parameters:
      component - The component to add.
      Returns:
      Itself.

    • buildMessage

      @CheckReturnValue @Nonnull public Message buildMessage()
      Constructs a new Message from the content and Embed this MessageOptions class stores.

      Creating messages this way does NOT include the added files, only the content and the embed. Try to pass the actual options class instead of a Message when sending messages, as otherwise you'll be performing unnecessary operations.

      Returns:
      A new Message instance with the content and Embed set in this class.

    • content

      @CheckReturnValue @Nullable public String content()

    • embeds

      @CheckReturnValue @Nullable public List<Embed> embeds()

    • parseFlags

      @CheckReturnValue @Nullable public EnumSet<MentionParseFlag> parseFlags()
      Restricts who get mentioned by this message. This does NOT get added to constructed message instances. Set to an empty enum set or clear to disable all parsing of mentions except for whitelisted user and role mentions. Set to null to allow all mentions. This may be overwritten by user and role mention whitelists.
      See Also:

    • flags

      @CheckReturnValue @Nullable public Set<MessageFlag> flags()
      A set of flags that can be set on this message. Flags are used for a number of things, including, but not limited to:
      1. Indicating if a message is crossposted
      2. Indicating if a message is urgent
      3. Suppressing embeds on a message

    • reference

      @CheckReturnValue @Nullable public MessageReference reference()
      A reference to the message to reply to. Setting this will make the message be created as an inline reply.

    • pingReply

      @CheckReturnValue @Nullable public boolean pingReply()
      Whether or not the message should ping the person it is replying to. This is useless if reference is not set.

    • override

      @CheckReturnValue @Nullable public boolean override()
      Whether or not to forcibly set fields even if they aren't set (read: are null).

    • components

      @CheckReturnValue @Nullable public List<MessageComponent> components()

    • content

      @Nonnull public MessageOptions content(@Nullable String content)
      Returns:
      this.

    • pingReply

      @Nonnull public MessageOptions pingReply(@Nullable boolean pingReply)
      Whether or not the message should ping the person it is replying to. This is useless if reference is not set.
      Returns:
      this.

    • override

      @Nonnull public MessageOptions override(@Nullable boolean override)
      Whether or not to forcibly set fields even if they aren't set (read: are null).
      Returns:
      this.

    • components

      @Nonnull public MessageOptions components(@Nullable List<MessageComponent> components)
      Returns:
      this.