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

      @Deprecated(since="12.0.3", forRemoval=true) default String getDisplayDescription()
      Deprecated, for removal: This API element is subject to removal in a future version.
      use getDescription()
      Gets the description of the role
      Returns:
      description
      Throws:
      PersistencyException - if persistency access fails
      API:
      This public API is available in Java.

    • getDescription

      String getDescription()
      Gets the description of the role
      Returns:
      description
      Since:
      12.0.3
      API:
      This public API is available in Java.
      Security:
      SESSION OWNS RoleReadDisplayDescription PERMISSION OR OWNS RoleReadDisplayDescription@SYSTEM PERMISSION

    • setDescription

      void setDescription(String description)
      Sets the description of the role
      Parameters:
      description - description
      Since:
      12.0.3
      API:
      This public API is available in Java.
      Security:
      SESSION OWNS RoleSetDisplayDescription PERMISSION OR OWNS RoleSetDisplayDescription@SYSTEM PERMISSION

    • setDisplayDescriptionTemplate

      @Deprecated(since="12.0.3", forRemoval=true) default void setDisplayDescriptionTemplate(String displayDescriptionTemplate)
      Deprecated, for removal: This API element is subject to removal in a future version.
      use setDescription(String)
      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 Java.

    • getDisplayDescriptionTemplate

      @Deprecated(since="12.0.3", forRemoval=true) default String getDisplayDescriptionTemplate()
      Deprecated, for removal: This API element is subject to removal in a future version.
      use getDescription()
      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 Java.

    • getParent

      IRole getParent()
      Returns the parent role
      Returns:
      parent role
      Throws:
      PersistencyException - if persistency access fails
      API:
      This public API is available in Java.
      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 Java.
      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 Java.
      Security:
      SESSION OWNS RoleTreeNavigation PERMISSION OR OWNS RoleTreeNavigation@SYSTEM PERMISSION

    • setExternalSecurityName

      @Deprecated(since="9.1") default void setExternalSecurityName(String externalName)
      Deprecated.
      use setExternalName(String) instead
      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
      API:
      This public API is available in Java.

    • 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 Java.
      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 Java.

    • 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 Java.
      Security:
      SESSION OWNS RoleReadExternalSecurityName PERMISSION OR OWNS RoleReadExternalSecurityName@SYSTEM PERMISSION

    • getAllUsers

      @Deprecated(since="9.1") default 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 Java.

    • users

      IRoleUsers users()
      Gets users that own this role
      Returns:
      users
      Since:
      8.0.3
      API:
      This public API is available in Java.

    • 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 Java.
      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 Java.

    • 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 Java.
      Security:
      SESSION OWNS RoleReadDisplayName PERMISSION OR OWNS RoleReadDisplayName@SYSTEM PERMISSION

    • getDisplayNameTemplate

      @Deprecated(since="12.0.3", forRemoval=true) default String getDisplayNameTemplate()
      Deprecated, for removal: This API element is subject to removal in a future version.
      use getDisplayName()
      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 Java.

    • setDisplayNameTemplate

      @Deprecated(since="12.0.3", forRemoval=true) default void setDisplayNameTemplate(String displayNameTemplate)
      Deprecated, for removal: This API element is subject to removal in a future version.
      use setDisplayName(String)
      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 Java.

    • setDisplayName

      void setDisplayName(String displayName)
      Sets the display name template of this role
      Parameters:
      displayName - the display name template
      Throws:
      PersistencyException - if persistency access fails
      Since:
      12.0.3
      API:
      This public API is available in Java.
      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 Java.
      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 Java.
      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 Java.
      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 Java.
      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 Java.

    • 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 Java.

    • 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 Java.

    • 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 Java.

    • 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 Java.

    • 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 Java.