Package net.dv8tion.jda.api.entities

Interface Role

All Superinterfaces:
Comparable<Role>, Formattable, IMentionable, IPermissionHolder, ISnowflake
public interface Role extends IMentionable, IPermissionHolder, Comparable<Role>
Represents a Guild's Role. Used to control permissions for Members.
See Also:

  • Field Details

    • DEFAULT_COLOR_RAW

      static final int DEFAULT_COLOR_RAW
      Used to keep consistency between color values used in the API
      See Also:

  • Method Details

    • getPosition

      int getPosition()
      The hierarchical position of this Role in the Guild hierarchy. (higher value means higher role).
      The Guild.getPublicRole()'s getPosition() always returns -1.
      Returns:
      The position of this Role as integer.
      Throws:
      IllegalStateException - If this role is not in the guild cache

    • getPositionRaw

      int getPositionRaw()
      The actual position of the Role as stored and given by Discord.
      Role positions are actually based on a pairing of the creation time (as stored in the snowflake id) and the position. If 2 or more roles share the same position then they are sorted based on their creation date.
      The more recent a role was created, the lower it is in the hierarchy. This is handled by getPosition() and it is most likely the method you want. If, for some reason, you want the actual position of the Role then this method will give you that value.
      Returns:
      The true, Discord stored, position of the Role.

    • getName

      @Nonnull String getName()
      The Name of this Role.
      Returns:
      Never-null String containing the name of this Role.

    • isManaged

      boolean isManaged()
      Whether this Role is managed by an integration
      Returns:
      True, if this Role is managed.

    • isHoisted

      boolean isHoisted()
      Whether this Role is hoisted
      Members in a hoisted role are displayed in their own grouping on the user-list
      Returns:
      True, if this Role is hoisted.

    • isMentionable

      boolean isMentionable()
      Whether or not this Role is mentionable
      Returns:
      True, if Role is mentionable.

    • getPermissionsRaw

      long getPermissionsRaw()
      The long representation of the literal permissions that this Role has.
      NOTE: these do not necessarily represent the permissions this role will have in a GuildChannel.
      Returns:
      Never-negative long containing offset permissions of this role.

    • getColor

      @Nullable Color getColor()
      The color this Role is displayed in.
      Returns:
      Color value of Role-color
      See Also:

    • getColorRaw

      int getColorRaw()
      The raw color RGB value used for this role
      Defaults to DEFAULT_COLOR_RAW if this role has no set color
      Returns:
      The raw RGB color value or default

    • isPublicRole

      boolean isPublicRole()
      Whether this role is the @everyone role for its Guild, which is assigned to everyone who joins the Guild.
      Returns:
      True, if and only if this Role is the public role for the Guild provided by getGuild().
      See Also:

    • canInteract

      boolean canInteract(@Nonnull Role role)
      Whether this Role can interact with the specified Role. (move/manage/etc.)
      Parameters:
      role - The not-null role to compare to
      Returns:
      True, if this role can interact with the specified role
      Throws:
      IllegalArgumentException - if the provided Role is null or not from the same Guild

    • getGuild

      @Nonnull Guild getGuild()
      Returns the Guild this Role exists in
      Specified by:
      getGuild in interface IPermissionHolder
      Returns:
      the Guild containing this Role

    • createCopy

      @Nonnull @CheckReturnValue RoleAction createCopy(@Nonnull Guild guild)
      Creates a new Role in the specified Guild with the same settings as the given Role.
      The position of the specified Role does not matter in this case!
      If this Role has an Icon set, only its emoji can be copied over.

      It will be placed at the bottom (just over the Public Role) to avoid permission hierarchy conflicts.
      For this to be successful, the logged in account has to have the MANAGE_ROLES Permission and all Permissions the given Role has.

      Possible ErrorResponses caused by the returned RestAction include the following:

      Parameters:
      guild - The Role that should be copied
      Returns:
      RoleAction
      RoleAction with already copied values from the specified Role
      Throws:
      PermissionException - If the logged in account does not have the Permission.MANAGE_ROLES Permission and every Permission the provided Role has
      IllegalArgumentException - If the specified guild is null

    • createCopy

      @Nonnull @CheckReturnValue default RoleAction createCopy()
      Creates a new Role in this Guild with the same settings as the given Role.
      The position of the specified Role does not matter in this case!
      If this Role has an Icon set, only its emoji can be copied over.

      It will be placed at the bottom (just over the Public Role) to avoid permission hierarchy conflicts.
      For this to be successful, the logged in account has to have the MANAGE_ROLES Permission and all Permissions the given Role has.

      Possible ErrorResponses caused by the returned RestAction include the following:

      Returns:
      RoleAction
      RoleAction with already copied values from the specified Role
      Throws:
      PermissionException - If the logged in account does not have the Permission.MANAGE_ROLES Permission and every Permission the provided Role has

    • getManager

      @Nonnull RoleManager getManager()
      The RoleManager for this Role. In the RoleManager, you can modify all its values.
      You modify multiple fields in one request by chaining setters before calling RestAction.queue().

      This is a lazy idempotent getter. The manager is retained after the first call. This getter is not thread-safe and would require guards by the user.

      Returns:
      The RoleManager of this Role
      Throws:
      InsufficientPermissionException - If the currently logged in account does not have Permission.MANAGE_ROLES
      HierarchyException - If the currently logged in account does not have the required position to modify this role

    • delete

      @Nonnull @CheckReturnValue AuditableRestAction<Void> delete()
      Deletes this Role.

      Possible ErrorResponses include:

      Returns:
      RestAction
      Throws:
      InsufficientPermissionException - If we don't have the permission to MANAGE_ROLES
      HierarchyException - If the role is too high in the role hierarchy to be deleted

    • getJDA

      @Nonnull JDA getJDA()
      Returns the JDA instance of this Role
      Returns:
      the corresponding JDA instance

    • getTags

      @Nonnull Role.RoleTags getTags()
      The tags of this role.
      This is useful to determine the purpose of a managed role.

      This requires CacheFlag.ROLE_TAGS to be enabled. See JDABuilder.enableCache(...).

      Returns:
      Role.RoleTags
      Since:
      4.2.1

    • getIcon

      @Nullable RoleIcon getIcon()
      The Icon of this role or null if no custom image or emoji is set. This icon will be displayed next to the role's name in the members tab and in chat.
      Returns:
      Possibly-null Icon of this role
      Since:
      4.3.1