Interface Role
- All Superinterfaces:
Comparable<Role>,Formattable,IMentionable,IPermissionHolder,ISnowflake
Guild's Role. Used to control permissions for Members.-
Nested Class Summary
Nested ClassesModifier and TypeInterfaceDescriptionstatic interfaceTags associated with this role. -
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final intUsed to keep consistency between color values used in the API -
Method Summary
Modifier and TypeMethodDescriptionbooleancanInteract(Role role) Whether this Role can interact with the specified Role.default RoleActioncreateCopy(Guild guild) delete()Deletes this Role.getColor()The color thisRoleis displayed in.intThe raw color RGB value used for this role
Defaults toDEFAULT_COLOR_RAWif this role has no set colorgetGuild()Returns theGuildthis Role exists ingetIcon()TheIconof this role ornullif no custom image or emoji is set.getJDA()Returns theJDAinstance of this RoleTheRoleManagerfor this Role.getName()The Name of thisRole.longThelongrepresentation of the literal permissions that thisRolehas.intintThe actual position of theRoleas stored and given by Discord.getTags()The tags of this role.booleanWhether thisRoleis hoisted
Members in a hoisted role are displayed in their own grouping on the user-listbooleanWhether thisRoleis managed by an integrationbooleanWhether or not this Role is mentionablebooleanMethods inherited from interface java.lang.Comparable
compareToMethods inherited from interface net.dv8tion.jda.api.entities.IMentionable
formatTo, getAsMentionMethods inherited from interface net.dv8tion.jda.api.entities.IPermissionHolder
canSync, canSync, getPermissions, getPermissions, getPermissionsExplicit, getPermissionsExplicit, hasAccess, hasPermission, hasPermission, hasPermission, hasPermissionMethods inherited from interface net.dv8tion.jda.api.entities.ISnowflake
getId, getIdLong, getTimeCreated
-
Field Details
-
DEFAULT_COLOR_RAW
static final int DEFAULT_COLOR_RAWUsed to keep consistency between color values used in the API- See Also:
-
-
Method Details
-
getPosition
int getPosition()The hierarchical position of thisRolein theGuildhierarchy. (higher value means higher role).
TheGuild.getPublicRole()'s getPosition() always returns -1.- Returns:
- The position of this
Roleas integer. - Throws:
IllegalStateException- If this role is not in the guild cache
-
getPositionRaw
int getPositionRaw()The actual position of theRoleas 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 bygetPosition()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
The Name of thisRole.- Returns:
- Never-null String containing the name of this
Role.
-
isManaged
boolean isManaged()Whether thisRoleis managed by an integration- Returns:
- True, if this
Roleis managed.
-
isHoisted
boolean isHoisted()Whether thisRoleis hoisted
Members in a hoisted role are displayed in their own grouping on the user-list- Returns:
- True, if this
Roleis hoisted.
-
isMentionable
boolean isMentionable()Whether or not this Role is mentionable- Returns:
- True, if Role is mentionable.
-
getPermissionsRaw
long getPermissionsRaw()Thelongrepresentation of the literal permissions that thisRolehas.
NOTE: these do not necessarily represent the permissions this role will have in aGuildChannel.- Returns:
- Never-negative long containing offset permissions of this role.
-
getColor
The color thisRoleis displayed in.- Returns:
- Color value of Role-color
- See Also:
-
getColorRaw
int getColorRaw()The raw color RGB value used for this role
Defaults toDEFAULT_COLOR_RAWif 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 itsGuild, which is assigned to everyone who joins theGuild.- Returns:
- True, if and only if this
Roleis the public role for theGuildprovided bygetGuild(). - See Also:
-
canInteract
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 sameGuild
-
getGuild
Returns theGuildthis Role exists in- Specified by:
getGuildin interfaceIPermissionHolder- Returns:
- the Guild containing this Role
-
createCopy
Creates a newRolein the specifiedGuildwith the same settings as the givenRole.
The position of the specified Role does not matter in this case!
If thisRolehas anIconset, 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 theMANAGE_ROLESPermission and allPermissionsthe givenRolehas.Possible
ErrorResponsescaused by the returnedRestActioninclude the following:MISSING_PERMISSIONS
The role could not be created due to a permission discrepancyMAX_ROLES_PER_GUILD
There are too many roles in this Guild
- Parameters:
guild- TheRolethat should be copied- Returns:
RoleAction
RoleAction with already copied values from the specifiedRole- Throws:
PermissionException- If the logged in account does not have thePermission.MANAGE_ROLESPermission and every Permission the provided Role hasIllegalArgumentException- If the specified guild isnull
-
createCopy
Creates a newRolein thisGuildwith the same settings as the givenRole.
The position of the specified Role does not matter in this case!
If thisRolehas anIconset, 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 theMANAGE_ROLESPermission and allPermissionsthe givenRolehas.Possible
ErrorResponsescaused by the returnedRestActioninclude the following:MISSING_PERMISSIONS
The role could not be created due to a permission discrepancyMAX_ROLES_PER_GUILD
There are too many roles in this Guild
- Returns:
RoleAction
RoleAction with already copied values from the specifiedRole- Throws:
PermissionException- If the logged in account does not have thePermission.MANAGE_ROLESPermission and every Permission the provided Role has
-
getManager
TheRoleManagerfor this Role. In the RoleManager, you can modify all its values.
You modify multiple fields in one request by chaining setters before callingRestAction.queue().- Returns:
- The RoleManager of this Role
- Throws:
InsufficientPermissionException- If the currently logged in account does not havePermission.MANAGE_ROLESHierarchyException- If the currently logged in account does not have the required position to modify this role
-
delete
Deletes this Role.Possible ErrorResponses include:
ErrorResponse.UNKNOWN_ROLE
If the the role was already deleted.MISSING_PERMISSIONS
The send request was attempted after the account lostPermission.MANAGE_ROLESin the channel.MISSING_ACCESS
If we were removed from the Guild
- Returns:
RestAction- Throws:
InsufficientPermissionException- If we don't have the permission toMANAGE_ROLESHierarchyException- If the role is too high in the role hierarchy to be deleted
-
getJDA
Returns theJDAinstance of this Role- Returns:
- the corresponding JDA instance
-
getTags
The tags of this role.
This is useful to determine the purpose of a managed role.This requires
CacheFlag.ROLE_TAGSto be enabled. SeeJDABuilder.enableCache(...).- Returns:
Role.RoleTags- Since:
- 4.2.1
-
getIcon
TheIconof this role ornullif 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
Iconof this role - Since:
- 4.3.1
-