Package com.sas.lsaf.security.group

## Interface GroupService

-     public interface GroupService

  The service that provides methods to manage the lifecycle of a group within the SAS Life Science Analytics Framework.

  A group is a collection of principals (users or other groups) and is uniquely identified by name and context. A group is associated with and scoped to a context in which it is defined. Group contexts are repository contexts that have the membership capability.

  Since:
    1.2

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `Group` | `createGroup​(java.lang.String contextId, java.lang.String name, java.lang.String description, java.util.Set<Principal> members)` | Creates the group.
    `void` | `deleteGroup​(java.lang.String groupId)` | Deletes the group.
    `java.util.Set<GroupDescriptor>` | `getAllGroupsByMember​(Principal member)` | Gets all of the group descriptors that have the specified principal as a member.
    `java.util.Set<GroupDescriptor>` | `getAllReachableGroupsByMember​(Principal member)` | Gets the set of all of the reachable groups.
    `Group` | `getGroupById​(java.lang.String groupId)` | Gets the full representation of the group by its identifier.
    `Group` | `getGroupByName​(java.lang.String contextId, java.lang.String name)` | Gets the full representation of the group by its name and context.
    `GroupDescriptor` | `getGroupDescriptorById​(java.lang.String groupId)` | Gets the lightweight representation of the group by its identifier.
    `GroupDescriptor` | `getGroupDescriptorByName​(java.lang.String contextId, java.lang.String name)` | Gets the lightweight representation of a group by its name and context.
    `java.util.Set<GroupDescriptor>` | `getGroupDescriptors​(java.lang.String contextId)` | Gets the lightweight representation of all of the groups that are defined at the context.
    `java.util.Set<GroupDescriptor>` | `getGroupDescriptorsByIds​(java.util.Set<java.lang.String> groupIds)` | Gets the lightweight representations of a set of groups by their specified identifiers.
    `java.util.Set<Group>` | `getGroups​(java.lang.String contextId)` | Gets all of the groups defined at the context.
    `java.util.Set<Group>` | `getGroupsByIds​(java.util.Set<java.lang.String> groupIds)` | Gets all of the groups by a list of identifiers.
    `java.util.Set<GroupDescriptor>` | `getGroupsByMember​(java.lang.String contextId, Principal member)` | Gets all of the groups in a context that have the principal as a member.
    `java.util.Set<GroupDescriptor>` | `getReachableGroupsByMember​(java.lang.String contextId, Principal member)` | Gets the set of all of the reachable groups at the context.
    `boolean` | `groupExists​(java.lang.String contextId, java.lang.String name)` | Indicates whether a group with the name exists at the context.
    `boolean` | `isMember​(java.lang.String groupId, Principal member, boolean includeImplicit)` | Indicates whether the principal is a member of the group, using the group identifier.
    `void` | `removeFromAllGroups​(Principal member)` | Removes the member from all groups.
    `void` | `removeFromGroups​(java.lang.String contextId, java.util.Set<Principal> members)` | Removes the members from all groups in a specific context.
    `Group` | `updateGroup​(Group group)` | Updates the definition of the group.

- - ### Method Detail

    - #### createGroup

          Group createGroup​(java.lang.String contextId,
                            java.lang.String name,
                            java.lang.String description,
                            java.util.Set<Principal> members)
                     throws GroupExistsException,
                            InvalidGroupMemberException

      Creates the group.

      This method requires read access to the context.

      The method requires the `ScopedPrivileges.PRIVILEGE_MANAGE_MEMBERSHIP` privilege.

      Parameters:
        `contextId` - the context in which the group will be created.
        `name` - the name of the group.
        `description` - the description of the group.
        `members` - the members of the group.
      Returns:
        The created group.
      Throws:
        `GroupExistsException` - thrown when a group by the name exists at the specified context.
        `InvalidGroupMemberException` - thrown when any of the members violate any membership contracts.

    - #### updateGroup

          Group updateGroup​(Group group)
                     throws GroupNotFoundException,
                            GroupExistsException,
                            InvalidGroupMemberException

      Updates the definition of the group.

      This method requires read access to the context.

      This method requires the `ScopedPrivileges.PRIVILEGE_MANAGE_MEMBERSHIP` privilege.

      Parameters:
        `group` - the group.
      Returns:
        The updated group.
      Throws:
        `GroupNotFoundException` - thrown when the group is not be found on the server.
        `GroupExistsException` - thrown when the updated group's new name exists at the specified context.
        `InvalidGroupMemberException` - thrown when a group is updated with new members that violate any membership contracts.

    - #### deleteGroup

          void deleteGroup​(java.lang.String groupId)
                    throws GroupNotFoundException

      Deletes the group.

      This method requires Read access to the context.

      This method requires the `ScopedPrivileges.PRIVILEGE_MANAGE_MEMBERSHIP` privilege.

      Parameters:
        `groupId` - the group identifier.
      Throws:
        `GroupNotFoundException` - thrown when the group to delete is not be found.

    - #### removeFromAllGroups

          void removeFromAllGroups​(Principal member)

      Removes the member from all groups.

      This method requires Read access to the contexts.

      This method requires the `ScopedPrivileges.PRIVILEGE_MANAGE_MEMBERSHIP` privilege.

      Parameters:
        `member` - the member.

    - #### removeFromGroups

          void removeFromGroups​(java.lang.String contextId,
                                java.util.Set<Principal> members)

      Removes the members from all groups in a specific context.

      Read access to the context is required by this method.

      The `ScopedPrivileges.PRIVILEGE_MANAGE_MEMBERSHIP` privilege is also required by this method.

      Parameters:
        `contextId` - the context of the groups to modify.
        `members` - the members.

    - #### groupExists

          boolean groupExists​(java.lang.String contextId,
                              java.lang.String name)

      Indicates whether a group with the name exists at the context.
      Parameters:
        `contextId` - the context identifier of the group.
        `name` - the name of the group.
      Returns:
        `True`, when a group exists with the name at the specified context.

    - #### isMember

          boolean isMember​(java.lang.String groupId,
                           Principal member,
                           boolean includeImplicit)

      Indicates whether the principal is a member of the group, using the group identifier.

      If `False` is specified for `includeImplicit`, this method returns `True` then the principal is an explicit member or `False` when the principal is not a member, the group does not exist, or the principal does not exist. If True is specified for includeImplicit, this method checks for explicit membership and any sub groups for membership.

      Parameters:
        `groupId` - the identifier of the group.
        `member` - the principal.
        `includeImplicit` - `True`, when membership checking should include implicit memberships through nested groups, `False` when this should be an explicit membership only.
      Returns:
        A Boolean value that indicate that the principal is a member of the group.

    - #### getGroupById

          Group getGroupById​(java.lang.String groupId)
                      throws GroupNotFoundException

      Gets the full representation of the group by its identifier.

      This method requires Read access to the context.

      Parameters:
        `groupId` - the identifier of the group.
      Returns:
        The group with the identifier.
      Throws:
        `GroupNotFoundException` - thrown when the specified group is not be found.

    - #### getGroupByName

          Group getGroupByName​(java.lang.String contextId,
                               java.lang.String name)
                        throws GroupNotFoundException

      Gets the full representation of the group by its name and context.

      This method requires Read access to the context.

      Parameters:
        `contextId` - the context of the group.
        `name` - the name of the group.
      Returns:
        The group with the given name and context.
      Throws:
        `GroupNotFoundException` - thrown when the specified group is not be found.

    - #### getGroupDescriptorById

          GroupDescriptor getGroupDescriptorById​(java.lang.String groupId)
                                          throws GroupNotFoundException

      Gets the lightweight representation of the group by its identifier.

      This method requires Read access to the context.

      Parameters:
        `groupId` - the identifier of the group.
      Returns:
        The group descriptor with the identifier.
      Throws:
        `GroupNotFoundException` - thrown when the specified group is not be found.

    - #### getGroupDescriptorByName

          GroupDescriptor getGroupDescriptorByName​(java.lang.String contextId,
                                                   java.lang.String name)
                                            throws GroupNotFoundException

      Gets the lightweight representation of a group by its name and context.

      This method requires Read access to the context..

      Parameters:
        `contextId` - the context of the group.
        `name` - the name of the group.
      Returns:
        The group descriptor with the specified name and context.
      Throws:
        `GroupNotFoundException` - thrown when the specified group is not be found.

    - #### getGroupDescriptorsByIds

          java.util.Set<GroupDescriptor> getGroupDescriptorsByIds​(java.util.Set<java.lang.String> groupIds)

      Gets the lightweight representations of a set of groups by their specified identifiers. The groups that are returned are the groups that are found to which the user has access.
      Parameters:
        `groupIds` - the identifiers of the groups.
      Returns:
        The groups that are found.

    - #### getGroupsByIds

          java.util.Set<Group> getGroupsByIds​(java.util.Set<java.lang.String> groupIds)

      Gets all of the groups by a list of identifiers. The groups that are returned are the groups that are found to which the user has access.
      Parameters:
        `groupIds` - the identifiers of the groups.
      Returns:
        The group descriptors found.

    - #### getGroups

          java.util.Set<Group> getGroups​(java.lang.String contextId)

      Gets all of the groups defined at the context.

      This method requires Read access to the context.

      Parameters:
        `contextId` - the context of the groups.
      Returns:
        The set of all of the groups that are defined at the context.

    - #### getGroupDescriptors

          java.util.Set<GroupDescriptor> getGroupDescriptors​(java.lang.String contextId)

      Gets the lightweight representation of all of the groups that are defined at the context.

      This method requires Read access to the context.

      Parameters:
        `contextId` - the context of the groups.
      Returns:
        The lightweight representation of all of the groups that are defined at the context.

    - #### getAllGroupsByMember

          java.util.Set<GroupDescriptor> getAllGroupsByMember​(Principal member)

      Gets all of the group descriptors that have the specified principal as a member. The groups that are returned are the groups that are found to which the user has access.
      Parameters:
        `member` - the principal.
      Returns:
        The set of all of the groups that have the principal as a member.

    - #### getGroupsByMember

          java.util.Set<GroupDescriptor> getGroupsByMember​(java.lang.String contextId,
                                                           Principal member)

      Gets all of the groups in a context that have the principal as a member.

      This method requires Read access to the context.

      Parameters:
        `contextId` - the context.
        `member` - the principal.
      Returns:
        The set of all of the groups in the context that have the principal as a member.

    - #### getAllReachableGroupsByMember

          java.util.Set<GroupDescriptor> getAllReachableGroupsByMember​(Principal member)

      Gets the set of all of the reachable groups.

      Reachable groups are the groups that are directly groups and all groups that are (transitively) reachable from them in the group hierarchy.

      Example:
      Group hierarchy: GROUP_A > GROUP_B and GROUP_B > GROUP_C.

      Directly assigned authority: GROUP_A.
      Reachable authorities: GROUP_A, GROUP_B, GROUP_C.

      Parameters:
        `member` - the principal.
      Returns:
        The set of all of the reachable groups of which the principal is a member.

    - #### getReachableGroupsByMember

          java.util.Set<GroupDescriptor> getReachableGroupsByMember​(java.lang.String contextId,
                                                                    Principal member)

      Gets the set of all of the reachable groups at the context.

      Reachable groups are the groups that are directly assigned and all groups that are (transitively) reachable from them in the group hierarchy.

      This method requires Read access to the context.

      Parameters:
        `contextId` - the context.
        `member` - the principal.
      Returns:
        The set of reachable groups in the context to which the principal is a member.