Package com.sas.lsaf.security.membership

## Interface MembershipService

-     public interface MembershipService

  The membership service provides methods to manage and to get information about the members of a context in the repository with membership capability. Membership can be `assigned` or `defined`. Users who are added to membership are considered `assigned` at that context and can be removed at any time. Groups that are defined at the context (meaning they were created at the context) are considered `defined` at that context. Defined members cannot be removed from membership, they must be deleted from the context that implicitly removes them from membership. Groups defined at a context are available for `assigment` at lower subcontexts with the membership capability.
  Since:
    1.2

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `addMember​(java.lang.String contextId, Principal member)` | Adds the principal to the membership list of a membership context.
    `void` | `addMembers​(java.lang.String contextId, java.util.Set<Principal> members)` | Adds the principals to the membership list of a membership context.
    `java.util.Set<Principal>` | `getAssignedMembers​(java.lang.String contextId)` | Retrieves the set of assigned members for the specified context.
    `Membership` | `getMembership​(java.lang.String contextId)` | Retrieves the membership information for the context.
    `Membership` | `getMembershipByPath​(java.lang.String path)` | Retrieves the membership information for the specified repository path.
    `java.util.Set<MembershipDescriptor>` | `getMemberships​(Principal member)` | Gets the set of membership context identifiers in which the principal is a member.
    `java.util.Set<Principal>` | `getPotentialMembers​(java.lang.String contextId, boolean checkParentsIfRequired)` | Retrieves the set of potential members that can be added as members to the context.
    `boolean` | `isMember​(java.lang.String contextId, Principal member, boolean includeImplicit)` | Indicates whether the principal is an explicit member of the membership context.
    `void` | `removeMember​(java.lang.String contextId, Principal member)` | Removes the principal from the membership list of the specified context.
    `void` | `removeMembers​(java.lang.String contextId, java.util.Set<Principal> members)` | Removes the principals from the membership list of the specified context.
    `Membership` | `updateMembership​(Membership membership)` | Updates the assigned members of a context.

- - ### Method Detail

    - #### addMember

          void addMember​(java.lang.String contextId,
                         Principal member)
                  throws MemberExistsException,
                         InvalidMemberException

      Adds the principal to the membership list of a membership context.

      This method requires Read access to the context.

      This method requires the `ScopedPrivileges.PRIVILEGE_MANAGE_MEMBERSHIP` privilege.

      Parameters:
        `contextId` - the membership context.
        `member` - the principal to add to the membership context.
      Throws:
        `MemberExistsException` - thrown when the principal is a member of the context.
        `InvalidMemberException` - thrown when the principal cannot be a member of the specified context.

    - #### addMembers

          void addMembers​(java.lang.String contextId,
                          java.util.Set<Principal> members)
                   throws MemberExistsException,
                          InvalidMemberException

      Adds the principals to the membership list of a membership context.

      This method requires Read access to the context.

      This method requires the `ScopedPrivileges.PRIVILEGE_MANAGE_MEMBERSHIP` privilege.

      Parameters:
        `contextId` - the membership context.
        `members` - the principals to add to the membership context.
      Throws:
        `MemberExistsException` - thrown when some of the principals are members of this context.
        `InvalidMemberException` - thrown when some of the principals cannot be members of the context.

    - #### removeMember

          void removeMember​(java.lang.String contextId,
                            Principal member)
                     throws MemberNotFoundException,
                            InvalidMemberException

      Removes the principal from the membership list of the specified context.

      This method requires Read access to the context.

      This method requires the `ScopedPrivileges.PRIVILEGE_MANAGE_MEMBERSHIP` privilege.

      Parameters:
        `contextId` - the membership context.
        `member` - the principal to remove from the membership context.
      Throws:
        `MemberNotFoundException` - thrown when the principal is not found in the membership list.
        `InvalidMemberException` - thrown when the principal is not removed from the membership, such as a group that is `defined` at the context and is therefore implicitly a member.

    - #### removeMembers

          void removeMembers​(java.lang.String contextId,
                             java.util.Set<Principal> members)
                      throws MemberNotFoundException,
                             InvalidMemberException

      Removes the principals from the membership list of the specified context.

      This method requires Read access to the context.

      This method requires the `ScopedPrivileges.PRIVILEGE_MANAGE_MEMBERSHIP` privilege.

      Parameters:
        `contextId` - The membership context.
        `members` - the principals to remove from the membership context.
      Throws:
        `MemberNotFoundException` - thrown when some of the principals are not found in the membership list.
        `InvalidMemberException` - thrown when some of the principals removed from the membership, such as a group that is `defined` at the context and is therefore implicitly a member.

    - #### isMember

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

      Indicates whether the principal is an explicit member of the membership context.

      If the context or principal is not found, or you do not have access to the context this method returns `False`.

      Parameters:
        `contextId` - the membership context.
        `member` - the principal.
        `includeImplicit` - `True` when the membership check should include implicit memberships through groups, `False`, if this should be an explicit membership only.
      Returns:
        A `boolean` value that indicates whether the principal is a member of the context.

    - #### getMembership

          Membership getMembership​(java.lang.String contextId)

      Retrieves the membership information for the context. This includes members that are defined on the context and members that have been assigned to the context.

      This method requires Read access to the context.

      Parameters:
        `contextId` - the membership context.
      Returns:
        The membership list of the specified context.

    - #### getMembershipByPath

          Membership getMembershipByPath​(java.lang.String path)

      Retrieves the membership information for the specified repository path. If the path is not to a context with the membership capability then the nearest parent context with the capability is found and used. This includes members that are defined on the context as well as members that have been assigned to the context.

      This method requires Read access to the context.

      Parameters:
        `path` - the repository path for which membership. This can be a folder path, file path, context path, or any other repository type in the system.
      Returns:
        The membership list for the path.

    - #### updateMembership

          Membership updateMembership​(Membership membership)
                               throws InvalidMemberException

      Updates the assigned members of a context. Defined members (for example, a group created at this context) cannot be updated using this method. Defined members are always members until they are deleted. Because this relationship is established through existence, passing defined members to this method is not required. If defined members are removed from the set of members when calling this method, they are ignored.
      Parameters:
        `membership` - the membership list to modify.
      Returns:
        The updated membership list.
      Throws:
        `InvalidMemberException` - thrown when the membership list contains principals that are invalid for the context.

    - #### getPotentialMembers

          java.util.Set<Principal> getPotentialMembers​(java.lang.String contextId,
                                                       boolean checkParentsIfRequired)

      Retrieves the set of potential members that can be added as members to the context. Potential members are any members from the parent context that are not currently members of the context. If there are no potential members at the parent and `checkParentsIfRequired` is set to `True`, then this method will continue querying the parents until either potential members are found or the top of the membership hierarchy is reached.

      Read access to the context is required by this method and parents if required.

      Parameters:
        `contextId` - the membership context.
        `checkParentsIfRequired` - if `True`, then the search is recursive.
      Returns:
        The set of all principals that could be included in the membership of the context.

    - #### getAssignedMembers

          java.util.Set<Principal> getAssignedMembers​(java.lang.String contextId)

      Retrieves the set of assigned members for the specified context. Assigned members are members from the parent context that have been assigned to the specified context.

      This method requires Read access to the context.

      Parameters:
        `contextId` - the membership context.
      Returns:
        The set of all principals that are in the membership of the context

    - #### getMemberships

          java.util.Set<MembershipDescriptor> getMemberships​(Principal member)

      Gets the set of membership context identifiers in which the principal is a member.
      Parameters:
        `member` - the principal.
      Returns:
        The set of memberships that contain the principal.