Interface Role
-
- All Superinterfaces:
java.lang.Comparable<Role>,java.util.Formattable,IMentionable,IPermissionHolder,ISnowflake
public interface Role extends IMentionable, IPermissionHolder, java.lang.Comparable<Role>
Represents aGuild's Role. Used to control permissions for Members.
-
-
Nested Class Summary
Nested Classes Modifier and Type Interface Description static interfaceRole.RoleTagsTags associated with this role.
-
Field Summary
Fields Modifier and Type Field Description static intDEFAULT_COLOR_RAWUsed to keep consistency between color values used in the API
-
Method Summary
All Methods Instance Methods Abstract Methods Default Methods Modifier and Type Method Description booleancanInteract(Role role)Whether this Role can interact with the specified Role.default RoleActioncreateCopy()RoleActioncreateCopy(Guild guild)AuditableRestAction<java.lang.Void>delete()Deletes this Role.java.awt.ColorgetColor()The color thisRoleis displayed in.intgetColorRaw()The raw color RGB value used for this role
Defaults toDEFAULT_COLOR_RAWif this role has no set colorGuildgetGuild()Returns theGuildthis Role exists inRoleIcongetIcon()TheIconof this role ornullif no custom image or emoji is set.JDAgetJDA()Returns theJDAinstance of this RoleRoleManagergetManager()TheRoleManagerfor this Role.java.lang.StringgetName()The Name of thisRole.longgetPermissionsRaw()Thelongrepresentation of the literal permissions that thisRolehas.intgetPosition()intgetPositionRaw()The actual position of theRoleas stored and given by Discord.Role.RoleTagsgetTags()The tags of this role.booleanisHoisted()Whether thisRoleis hoisted
Members in a hoisted role are displayed in their own grouping on the user-listbooleanisManaged()Whether thisRoleis managed by an integrationbooleanisMentionable()Whether or not this Role is mentionablebooleanisPublicRole()-
Methods inherited from interface net.dv8tion.jda.api.entities.IMentionable
formatTo, getAsMention
-
Methods inherited from interface net.dv8tion.jda.api.entities.IPermissionHolder
canSync, canSync, getPermissions, getPermissions, getPermissionsExplicit, getPermissionsExplicit, hasAccess, hasPermission, hasPermission, hasPermission, hasPermission
-
Methods inherited from interface net.dv8tion.jda.api.entities.ISnowflake
getId, getIdLong, getTimeCreated
-
-
-
-
Field Detail
-
DEFAULT_COLOR_RAW
static final int DEFAULT_COLOR_RAW
Used to keep consistency between color values used in the API- See Also:
- Constant Field Values
-
-
Method Detail
-
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:
java.lang.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
@Nonnull java.lang.String 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
@Nullable java.awt.Color getColor()
The color thisRoleis displayed in.- Returns:
- Color value of Role-color
- See Also:
getColorRaw()
-
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:
Guild.getPublicRole()
-
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:
java.lang.IllegalArgumentException- if the provided Role is null or not from the sameGuild
-
getGuild
@Nonnull Guild getGuild()
Returns theGuildthis Role exists in- Specified by:
getGuildin interfaceIPermissionHolder- Returns:
- the Guild containing this Role
-
createCopy
@Nonnull @CheckReturnValue RoleAction createCopy(@Nonnull Guild guild)
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 hasjava.lang.IllegalArgumentException- If the specified guild isnull
-
createCopy
@Nonnull @CheckReturnValue default RoleAction 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
@Nonnull RoleManager 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().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 havePermission.MANAGE_ROLESHierarchyException- If the currently logged in account does not have the required position to modify this role
-
delete
@Nonnull @CheckReturnValue AuditableRestAction<java.lang.Void> 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
@Nonnull JDA getJDA()
Returns theJDAinstance 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_TAGSto be enabled. SeeJDABuilder.enableCache(...).- Returns:
Role.RoleTags- Since:
- 4.2.1
-
-