Package net.dv8tion.jda.api.entities

Interface Role

All Superinterfaces:

Comparable<Role>, Formattable, IDetachableEntity, IMentionable, IPermissionHolder, ISnowflake

public interface Role
extends IMentionable, IPermissionHolder, IDetachableEntity, Comparable<Role>

Represents a Guild's Role. Used to control permissions for Members.

See Also:

• Guild.getRoleCache()
• Guild.getRoleById(long)
• Guild.getRolesByName(String, boolean)
• Guild.getRoles()
• JDA.getRoleCache()
• JDA.getRoleById(long)
• JDA.getRolesByName(String, boolean)
• JDA.getRoles()

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static interface	Role.RoleTags	Tags associated with this role.

Field Summary

Fields

Modifier and Type	Field	Description
static final int	DEFAULT_COLOR_RAW	Used to keep consistency between color values used in the API

Method Summary

Modifier and Type	Method	Description
boolean	canInteract(Role role)	Whether this Role can interact with the specified Role.
default RoleAction	createCopy()	Creates a new Role in this Guild with the same settings as the given Role.
RoleAction	createCopy(Guild guild)	Creates a new Role in the specified Guild with the same settings as the given Role.
AuditableRestAction<Void>	delete()	Deletes this Role.
Color	getColor()	The color this Role is displayed in.
int	getColorRaw()	The raw color RGB value used for this role Defaults to DEFAULT_COLOR_RAW if this role has no set color
Guild	getGuild()	Returns the Guild this Role exists in
RoleIcon	getIcon()	The Icon of this role or null if no custom image or emoji is set.
JDA	getJDA()	Returns the JDA instance of this Role
RoleManager	getManager()	The RoleManager for this Role.
String	getName()	The Name of this Role.
long	getPermissionsRaw()	The long representation of the literal permissions that this Role has.
int	getPosition()	The hierarchical position of this Role in the Guild hierarchy.
int	getPositionRaw()	The actual position of the Role as stored and given by Discord.
Role.RoleTags	getTags()	The tags of this role.
boolean	isHoisted()	Whether this Role is hoisted Members in a hoisted role are displayed in their own grouping on the user-list
boolean	isManaged()	Whether this Role is managed by an integration
boolean	isMentionable()	Whether or not this Role is mentionable
boolean	isPublicRole()	Whether this role is the @everyone role for its Guild, which is assigned to everyone who joins the Guild.

Methods inherited from interface java.lang.Comparable

compareTo

Methods inherited from interface net.dv8tion.jda.api.entities.detached.IDetachableEntity

isDetached

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 Details

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 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

DetachedEntityException - If this role is detached, use getPermissionsRaw() instead

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()

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:

• 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:

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:

• MISSING_PERMISSIONS
  The role could not be created due to a permission discrepancy
• MAX_ROLES_PER_GUILD
  There are too many roles in this Guild

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

DetachedEntityException - If the guild the role should be copied to is detached

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:

• MISSING_PERMISSIONS
  The role could not be created due to a permission discrepancy
• MAX_ROLES_PER_GUILD
  There are too many roles in this Guild

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

DetachedEntityException - If this entity is detached

getManager

@Nonnull
@CheckReturnValue
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().

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

DetachedEntityException - If this entity is detached

delete

@Nonnull
@CheckReturnValue
AuditableRestAction<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 lost Permission.MANAGE_ROLES in the channel.
• MISSING_ACCESS
  If we were removed from the Guild

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

DetachedEntityException - If this entity is detached

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