Package ch.ivyteam.ivy.security

Interface IRole

All Superinterfaces:
ISecurityMember
public interface IRole extends ISecurityMember
A security Role. The roles are organized hierarchically.
The only top level role 'Everybody' is provided by the system (see ivy.security.roles().topLevel()).
If a user owns directly or indirectly a member role it owns also this role. (See getRoleMembers(), addRoleMember(IRole), removeRoleMember(IRole)). 
 Example:

 -Everybody (top level Role)
    -Role1   (RoleMembers: [RoleA, Role2]) owned by User1
      -RoleA (RoleMembers: [])             owned by UserA
    -Role2   (RoleMembers: [])             owned by User2

 getUsers():
 Role1.getUsers() = [User1]
 Role2.getUsers() = [User2]
 RoleA.getUsers() = [UserA]

 getAllUsers():
 Role1.getAllUsers() = [User1, User2, UserA]
 Role2.getAllUsers() = [User2]
 RoleA.getAllUsers() = [UserA]

 IUser.getRoles():
 User1.getRoles() = [Role1]
 User2.getRoles() = [Role2]
 UserA.getRoles() = [RoleA]

 IUser.getAllRoles():
 User1.getAllRoles() = [Role1]
 User2.getAllRoles() = [Role2, Role1]
 UserA.getAllRoles() = [RoleA, Role1]
Since:
17.05.2006
See Also:
API:
This is a public API.

  • Method Details

    • getDisplayDescription

      String getDisplayDescription()
      Gets the description of the role
      Returns:
      description
      Throws:
      PersistencyException - if persistency access fails
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.
      Security:
      SESSION OWNS RoleReadDisplayDescription PERMISSION OR OWNS RoleReadDisplayDescription@SYSTEM PERMISSION

    • setDisplayDescriptionTemplate

      void setDisplayDescriptionTemplate(String displayDescriptionTemplate)
      Set the description of the role
      Parameters:
      displayDescriptionTemplate - Description of the role
      Throws:
      PersistencyException - if persistency access fails
      API:
      This public API is available in IvyScript and Java. It has the visibility EXPERT.
      Security:
      SESSION OWNS RoleSetDisplayDescription PERMISSION OR OWNS RoleSetDisplayDescription@SYSTEM PERMISSION

    • getDisplayDescriptionTemplate

      String getDisplayDescriptionTemplate()
      Get the display description template of the role
      Returns:
      display description template
      Throws:
      PersistencyException - if persistency access fails
      API:
      This public API is available in IvyScript and Java. It has the visibility EXPERT.
      Security:
      SESSION OWNS RoleReadDisplayDescriptionTemplate PERMISSION OR OWNS RoleReadDisplayDescriptionTemplate@SYSTEM PERMISSION

    • getParent

      IRole getParent()
      Returns the parent role
      Returns:
      parent role
      Throws:
      PersistencyException - if persistency access fails
      API:
      This public API is available in IvyScript and Java. It has the visibility ADVANCED.
      Security:
      SESSION OWNS RoleTreeNavigation PERMISSION OR OWNS RoleTreeNavigation@SYSTEM PERMISSION

    • getChildRoles

      List<IRole> getChildRoles()
      Returns the child roles
      Returns:
      child roles
      Throws:
      PersistencyException - if persistency access fails
      API:
      This public API is available in IvyScript and Java. It has the visibility ADVANCED.
      Security:
      SESSION OWNS RoleTreeNavigation PERMISSION OR OWNS RoleTreeNavigation@SYSTEM PERMISSION

    • findChildRole

      IRole findChildRole(String roleName)
      Finds the child role with it's name
      Parameters:
      roleName - Name of the child role
      Returns:
      role or null if no child role with that name exists.
      Throws:
      PersistencyException - if persistency access fails
      API:
      This public API is available in IvyScript and Java. It has the visibility ADVANCED.
      Security:
      SESSION OWNS RoleTreeNavigation PERMISSION OR OWNS RoleTreeNavigation@SYSTEM PERMISSION

    • setExternalName

      void setExternalName(String externalName)
      Sets the full qualified external name of the this role. This external name is used to lookup the role in the external security system.
      Parameters:
      externalName - The external name of the role
      Throws:
      PersistencyException - if persistency access fails
      Since:
      9.1
      API:
      This public API is available in IvyScript and Java. It has the visibility EXPERT.
      Security:
      SESSION OWNS RoleSetExternalSecurityName PERMISSION OR OWNS RoleSetExternalSecurityName@SYSTEM PERMISSION

    • getExternalSecurityName

      @Deprecated(since="9.1") default String getExternalSecurityName()
      Deprecated.
      use getExternalName() instead
      Gets the full qualified name of the role in the external security system
      Returns:
      external name
      Throws:
      PersistencyException - if persistency access fails
      API:
      This public API is available in IvyScript and Java. It has the visibility EXPERT.

    • getExternalName

      String getExternalName()
      Gets the full qualified name of the role in the external security system
      Returns:
      external name
      Throws:
      PersistencyException - if persistency access fails
      Since:
      9.1
      API:
      This public API is available in IvyScript and Java. It has the visibility EXPERT.
      Security:
      SESSION OWNS RoleReadExternalSecurityName PERMISSION OR OWNS RoleReadExternalSecurityName@SYSTEM PERMISSION

    • getAllUsers

      @Deprecated(since="9.1") List<IUser> getAllUsers()
      Deprecated.
      use users().allPaged()

      WARNING: This methods loads the resulting users into memory.
      This can cause out of memory exceptions and bad performance depending on the number of users in your application.

      Returns:
      list with the users
      Throws:
      PersistencyException - if persistency access fails
      See Also:
      API:
      This public API is available in IvyScript and Java. It has the visibility EXPERT.
      Security:
      SESSION OWNS RoleReadUsers PERMISSION OR OWNS RoleReadUsers@SYSTEM PERMISSION

    • users

      IRoleUsers users()
      Gets users that own this role
      Returns:
      users
      Since:
      8.0.3
      API:
      This public API is available in IvyScript and Java. It has the visibility EXPERT.

    • getUsers

      @Deprecated(since="9.1") List<IUser> getUsers()
      Deprecated.
      use users().assignedPaged()
      Migration Example: ivy.session().getSecurityContext().findRole("ivy").getUsers() ==> ivy.security.roles().find("ivy").users().assignedPaged().page(1)

      WARNING: This methods loads the resulting users into memory.
      This can cause out of memory exceptions and bad performance depending on the number of users in your application.

      Returns:
      list with the users
      Throws:
      PersistencyException - if persistency access fails
      See Also:
      API:
      This public API is available in IvyScript and Java. It has the visibility EXPERT.
      Security:
      SESSION OWNS RoleReadUsers PERMISSION OR OWNS RoleReadUsers@SYSTEM PERMISSION

    • isRole

      boolean isRole(IRole role)
      Checks whether this or any parent role is equal with the role given
      Parameters:
      role - The role to check
      Returns:
      true If the role is equal to this or to any parent role, else false
      Throws:
      PersistencyException - if persistency access fails
      API:
      This public API is available in IvyScript and Java. It has the visibility ADVANCED.

    • getDisplayName

      String getDisplayName()
      Gets the display name of this role
      Specified by:
      getDisplayName in interface ISecurityMember
      Returns:
      the display name
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.
      Security:
      SESSION OWNS RoleReadDisplayName PERMISSION OR OWNS RoleReadDisplayName@SYSTEM PERMISSION

    • getDisplayNameTemplate

      String getDisplayNameTemplate()
      Gets the display name template of this role
      Returns:
      the display name template
      Throws:
      PersistencyException - if persistency access fails
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.
      Security:
      SESSION OWNS RoleReadDisplayNameTemplate PERMISSION OR OWNS RoleReadDisplayNameTemplate@SYSTEM PERMISSION

    • setDisplayNameTemplate

      void setDisplayNameTemplate(String displayNameTemplate)
      Sets the display name template of this role
      Parameters:
      displayNameTemplate - the display name template
      Throws:
      PersistencyException - if persistency access fails
      API:
      This public API is available in IvyScript and Java. It has the visibility EXPERT.
      Security:
      SESSION OWNS RoleSetDisplayName PERMISSION OR OWNS RoleSetDisplayName@SYSTEM PERMISSION

    • setProperty

      void setProperty(String name, String value)
      Sets a property to the role
      Parameters:
      name - Name of the property to set (maximum 255 characters)
      value - Value of the property to set
      Throws:
      IllegalArgumentException - If the property name has more than 255 characters
      PersistencyException - if persistency access fails
      API:
      This public API is available in IvyScript and Java. It has the visibility ADVANCED.
      Security:
      SESSION OWNS RolePropertyWrite PERMISSION OR OWNS RolePropertyWrite@SYSTEM PERMISSION

    • getProperty

      String getProperty(String name)
      Gets a property of the role
      Parameters:
      name - Name of the property
      Returns:
      property value or null if no such property exists
      Throws:
      PersistencyException - if persistency access fails
      API:
      This public API is available in IvyScript and Java. It has the visibility ADVANCED.
      Security:
      SESSION OWNS RolePropertyRead PERMISSION OR OWNS RolePropertyRead@SYSTEM PERMISSION

    • removeProperty

      String removeProperty(String name)
      Removes a property from the role
      Parameters:
      name - Name of the property to remove
      Returns:
      property value or null if no such property exists
      Throws:
      PersistencyException - if persistency access fails
      API:
      This public API is available in IvyScript and Java. It has the visibility ADVANCED.
      Security:
      SESSION OWNS RolePropertyWrite PERMISSION OR OWNS RolePropertyWrite@SYSTEM PERMISSION

    • getAllPropertyNames

      List<String> getAllPropertyNames()
      Gets all property names of the role
      Returns:
      Enumeration with the property names
      Throws:
      PersistencyException - if persistency access fails
      API:
      This public API is available in IvyScript and Java. It has the visibility ADVANCED.
      Security:
      SESSION OWNS RolePropertyRead PERMISSION OR OWNS RolePropertyRead@SYSTEM PERMISSION

    • addRoleMember

      void addRoleMember(IRole role)
      Adds the given role as role member of this role.
      If a user owns directly or indirectly a member role it owns also this role.
      Parameters:
      role - member to add
      Throws:
      PersistencyException - if persistency access fails
      IllegalArgumentException - if the member is the role iself
      API:
      This public API is available in IvyScript and Java. It has the visibility EXPERT.

    • getRoleMembers

      List<IRole> getRoleMembers()
      Gets all direct role members of this role.
      If a user owns directly or indirectly a member role it owns also this role.
      Returns:
      all direct role members of this role
      Throws:
      PersistencyException
      API:
      This public API is available in IvyScript and Java. It has the visibility EXPERT.

    • removeRoleMember

      void removeRoleMember(IRole role)
      Removes the given member role from this role.
      If a user owns directly or indirectly a member role it owns also this role.
      Parameters:
      role - to remove
      Throws:
      PersistencyException - if persistency access fails
      API:
      This public API is available in IvyScript and Java. It has the visibility EXPERT.

    • getRoles

      List<IRole> getRoles()
      Gets the directly owned roles. The parent role and all roles where this role is a direct role member.
      This list never contains this role itself.
      Returns:
      list of the parent and all roles this role is a direct member
      Throws:
      PersistencyException - if persistency access fails
      See Also:
      • getAllRoles()
      API:
      This public API is available in IvyScript and Java. It has the visibility EXPERT.

    • isDynamic

      boolean isDynamic()
      Returns if this role is dynamic or not.
      Roles created during deployment are never dynamic.
      Returns:
      if this role is dynamic
      API:
      This public API is available in IvyScript and Java. It has the visibility EXPERT.

    • setName

      void setName(String name)
      Sets the name of the role.

      Attention: This is a critical and dangerous operation, at least for non-dynamic roles. This role may be referenced in processes with its old name. All references in all processes in all deployed projects (PMVs) must first be manually adjusted to the new name. Otherwise, the processes will fail in the future.

      Parameters:
      name - role name
      API:
      This public API is available in IvyScript and Java. It has the visibility EXPERT.