org.kuali.rice.kim.api.group
Interface GroupService

All Known Implementing Classes:

GroupServiceImpl

public interface GroupService

This service provides operations for checking group membership, querying for group data, creating and updating groups.

A group is a collection of principals. It's membership consists of direct principal assignment and/or nested group membership. All groups are uniquely identified by a namespace code plus a name.

As mentioned previously, groups support nested group membership. A principal or group is considered to be a "member" of a group if it is either directly assigned to the group or indirectly assigned (via a nested group membership). A principal or group is said to be a "direct" member of another group only if it is directly assigned as a member of the group, and not via a nested group assignment.

Author:

Kuali Rice Team (rice.collab@kuali.org)

Method Summary

boolean	addGroupToGroup(String childId, String parentId) Adds the group with the id supplied in childId as a member of the group with the id supplied in parentId.
boolean	addPrincipalToGroup(String principalId, String groupId) Add the principal with the given principalId as a member of the group with the given groupId.
Group	createGroup(Group group) Creates a new group using the given Group.
GroupMember	createGroupMember(GroupMember groupMember) Creates a new group using the given GroupMember.
List<String>	findGroupIds(QueryByCriteria queryByCriteria) Query for groups based on the given search criteria which is a Map of group field names to values.
GroupMemberQueryResults	findGroupMembers(QueryByCriteria queryByCriteria) Query for group members based on the given search criteria which is a Map of group member field names to values.
GroupQueryResults	findGroups(QueryByCriteria queryByCriteria) Query for groups based on the given search criteria which is a Map of group field names to values.
Map<String,String>	getAttributes(String groupId) Get all the attributes of the given group.
List<String>	getDirectGroupIdsByPrincipalId(String principalId) Get all the groups for the given principal.
List<String>	getDirectMemberGroupIds(String groupId) Returns all group ids that are direct members of the given group id.
List<String>	getDirectMemberPrincipalIds(String groupId) Returns all principal ids that are direct members of the given group id.
List<String>	getDirectParentGroupIds(String groupId) Returns all parent groups ids that the given group id is a member of.
Group	getGroup(String id) Lookup a Group based on the passed in id.
Group	getGroupByNamespaceCodeAndName(String namespaceCode, String groupName) Lookup a Group based on the passed in namespace and name.
List<String>	getGroupIdsByPrincipalId(String principalId) Get all the groups for the given principal.
List<String>	getGroupIdsByPrincipalIdAndNamespaceCode(String principalId, String namespaceCode) Get all the groups for the given principal.
List<Group>	getGroups(Collection<String> ids) Gets all groups for the given collection of group ids.
List<Group>	getGroupsByPrincipalId(String principalId) Get all the groups for a given principal.
List<Group>	getGroupsByPrincipalIdAndNamespaceCode(String principalId, String namespaceCode) Get all the groups within a namespace for a given principal.
List<String>	getMemberGroupIds(String groupId) Returns all group ids that are members of the given group id.
List<String>	getMemberPrincipalIds(String groupId) Returns all principal ids that are members of the given group id.
List<GroupMember>	getMembers(List<String> groupIds) Get all GroupMembers all the groups with the given group ids.
List<GroupMember>	getMembersOfGroup(String groupId) Get all GroupMembers all the groups with a given group id.
List<String>	getParentGroupIds(String groupId) Returns all parent groups ids that the given group id is a member of.
boolean	isDirectMemberOfGroup(String principalId, String groupId) Check whether the give principal is a member of the group.
boolean	isGroupMemberOfGroup(String groupMemberId, String groupId) Check whether the group identified by groupMemberId is a member of the group identified by groupId.
boolean	isMemberOfGroup(String principalId, String groupId) Check whether the give principal is a member of the group.
void	removeAllMembers(String groupId) Removes all members from the group with the given groupId.
boolean	removeGroupFromGroup(String childId, String parentId) Removes the group with the id supplied in childId from the group with the id supplied in parentId.
boolean	removePrincipalFromGroup(String principalId, String groupId) Removes the member principal with the given principalId from the group with the given groupId.
Group	updateGroup(Group group) Updates an existing group using the given Group.
Group	updateGroup(String groupId, Group group) Updates a group using the given Group.
GroupMember	updateGroupMember(GroupMember groupMember) Updates an existing group using the given GroupMember.

Method Detail

getGroupsByPrincipalId

@Cacheable(value="http://rice.kuali.org/kim/v2_0/GroupMemberType",
           key="\'principalId=\' + #p0")
List<Group> getGroupsByPrincipalId(String principalId)
                                   throws RiceIllegalArgumentException

Get all the groups for a given principal.

This will include all groups directly assigned as well as those inferred by the fact that they are members of higher level groups.

Parameters:

principalId - The id of the Principal

Returns:

a list of Group objects in which the given Principal is a member of. An empty list is returned if an invalid or non-existant principalId is supplied.

Throws:

RiceIllegalArgumentException - if the principalId is null or blank

getGroupsByPrincipalIdAndNamespaceCode

@Cacheable(value="http://rice.kuali.org/kim/v2_0/GroupMemberType",
           key="\'principalId=\' + #p0 + \'|\' + \'namespaceCode=\' + #p1")
List<Group> getGroupsByPrincipalIdAndNamespaceCode(String principalId,
                                                             String namespaceCode)
                                                   throws RiceIllegalArgumentException

Get all the groups within a namespace for a given principal.

This will include all groups directly assigned as well as those inferred by the fact that they are members of higher level groups, and filtered by Group namespace.

Parameters:

principalId - The id of the Principal

namespaceCode - The namespace code of the desired Groups to return

Returns:

a list of Group objects in which the given Principal is a member of, filtered by Group namespace. An empty list is returned if an invalid or non-existant principalId is supplied.

Throws:

RiceIllegalArgumentException - if the principalId, namespaceCode is null or blank

findGroupIds

List<String> findGroupIds(QueryByCriteria queryByCriteria)
                          throws RiceIllegalArgumentException

Query for groups based on the given search criteria which is a Map of group field names to values.

This method returns it's results as a List of group ids that match the given search criteria.

Parameters:

queryByCriteria - the criteria. Cannot be null.

Returns:

a list of groupId Strings in which the given criteria match Group properties. An empty list is returned if an invalid or non-existent criteria is supplied.

Throws:

RiceIllegalArgumentException - if the queryByCriteria is null

findGroups

GroupQueryResults findGroups(QueryByCriteria queryByCriteria)
                             throws RiceIllegalArgumentException

Query for groups based on the given search criteria which is a Map of group field names to values.

This method returns it's results as a List of Groups that match the given search criteria.

Parameters:

queryByCriteria - the criteria. Cannot be null.

Returns:

a list of Group objects in which the given criteria match Group properties. An empty list is returned if an invalid or non-existent criteria is supplied.

Throws:

RiceIllegalArgumentException - if the queryByCriteria is null

findGroupMembers

GroupMemberQueryResults findGroupMembers(QueryByCriteria queryByCriteria)
                                         throws RiceIllegalArgumentException

Query for group members based on the given search criteria which is a Map of group member field names to values.

This method returns it's results as a List of GroupMemberss that match the given search criteria.

Parameters:

queryByCriteria - the criteria. Cannot be null.

Returns:

a list of GroupMember objects in which the given criteria match Group properties. An empty list is returned if an invalid or non-existent criteria is supplied.

Throws:

RiceIllegalArgumentException - if the queryByCriteria is null

getGroup

@Cacheable(value="http://rice.kuali.org/kim/v2_0/GroupType",
           key="\'id=\' + #p0")
Group getGroup(String id)
               throws RiceIllegalArgumentException

Lookup a Group based on the passed in id.

Parameters:

id - String that matches the desired Groups id

Returns:

a Group with the given id value. A null reference is returned if an invalid or non-existant id is supplied.

Throws:

RiceIllegalArgumentException - if the groupId is null or blank

getGroupByNamespaceCodeAndName

@Cacheable(value="http://rice.kuali.org/kim/v2_0/GroupType",
           key="\'namespaceCode=\' + #p0 + \'|\' + \'groupName=\' + #p1")
Group getGroupByNamespaceCodeAndName(String namespaceCode,
                                               String groupName)
                                     throws RiceIllegalArgumentException

Lookup a Group based on the passed in namespace and name.

Parameters:

namespaceCode - String that matches the desired Group's namespaceCode

groupName - String that matches the desired Group's name

Returns:

a Group with the given namespace and name values. A null reference is returned if an invalid or non-existant id is supplied.

Throws:

RiceIllegalArgumentException - if the namespaceCode, groupName is null or blank

getGroups

@Cacheable(value="http://rice.kuali.org/kim/v2_0/GroupType",
           key="\'ids=\' + T(org.kuali.rice.core.api.cache.CacheKeyUtils).key(#p0)")
List<Group> getGroups(Collection<String> ids)
                      throws RiceIllegalArgumentException

Gets all groups for the given collection of group ids.

The result is a Map containing the group id as the key and the Group as the value.

Parameters:

ids - Collection that matches the desired Groups' id

Returns:

a Map of Groups with the given id values. An empty Map is returned if an invalid or non-existant id is supplied.

Throws:

RiceIllegalArgumentException - if the groupIds null or empty

isMemberOfGroup

@Cacheable(value="http://rice.kuali.org/kim/v2_0/GroupMemberType",
           key="\'{isMemberOfGroup}\' + \'principalId=\' + #p0 + \'|\' + \'groupId=\' + #p1")
boolean isMemberOfGroup(String principalId,
                                  String groupId)
                        throws RiceIllegalArgumentException

Check whether the give principal is a member of the group.

Will return true if the principal is a member of the group or a group assigned to this group.

Parameters:

principalId - Id of the principal

groupId - Id string of group

Returns:

true if principal is a member of the group or a member of a group assigned to the the group.

Throws:

RiceIllegalArgumentException - if the principalId, groupId is null or blank

isDirectMemberOfGroup

@Cacheable(value="http://rice.kuali.org/kim/v2_0/GroupMemberType",
           key="\'{isDirectMemberOfGroup}\' + \'principalId=\' + #p0 + \'|\' + \'groupId=\' + #p1")
boolean isDirectMemberOfGroup(String principalId,
                                        String groupId)
                              throws RiceIllegalArgumentException

Check whether the give principal is a member of the group.

This method does not recurse into contained groups.

Parameters:

principalId - Id of the principal

groupId - Id string of group

Returns:

true if principal is a direct member of the group.

Throws:

RiceIllegalArgumentException - if the principalId, groupId is null or blank

getGroupIdsByPrincipalId

@Cacheable(value="http://rice.kuali.org/kim/v2_0/GroupMemberType",
           key="\'{getGroupIdsByPrincipalId}\' + \'principalId=\' + #p0")
List<String> getGroupIdsByPrincipalId(String principalId)
                                      throws RiceIllegalArgumentException

Get all the groups for the given principal. Recurses into parent groups to provide a comprehensive list.

This returns id for all groups for a given principal id.

Parameters:

principalId - Id of a Principal

Returns:

a list of Group Ids in which the principal is a member of.

Throws:

RiceIllegalArgumentException - if the principalId is null or blank

getGroupIdsByPrincipalIdAndNamespaceCode

@Cacheable(value="http://rice.kuali.org/kim/v2_0/GroupMemberType",
           key="\'{getGroupIdsByPrincipalIdAndNamespaceCode}\' + \'principalId=\' + #p0 + \'|\' + \'namespaceCode=\' + #p1")
List<String> getGroupIdsByPrincipalIdAndNamespaceCode(String principalId,
                                                                String namespaceCode)
                                                      throws RiceIllegalArgumentException

Get all the groups for the given principal. Recurses into parent groups to provide a comprehensive list. This is limited to the passed in Group's namespace.

This returns id for all groups for a given principal id, limited to specific Group namespace.

Parameters:

principalId - Id of a Principal

namespaceCode - Namspace code to limit group results to

Returns:

a list of Group Ids in which the principal is a member of, limited to the passed in namespace.

Throws:

RiceIllegalArgumentException - if the principalId, namespaceCode is null or blank

getDirectGroupIdsByPrincipalId

@Cacheable(value="http://rice.kuali.org/kim/v2_0/GroupMemberType",
           key="\'{getDirectGroupIdsByPrincipalId}\' + \'principalId=\' + #p0")
List<String> getDirectGroupIdsByPrincipalId(String principalId)
                                            throws RiceIllegalArgumentException

Get all the groups for the given principal. Does not recurse into parent groups.

This returns id for all groups for a given principal id.

Parameters:

principalId - Id of a Principal

Returns:

a list of Group Ids in which the principal is directly a member of.

Throws:

RiceIllegalArgumentException - if the principalId is null or blank

isGroupMemberOfGroup

@Cacheable(value="http://rice.kuali.org/kim/v2_0/GroupMemberType",
           key="\'{isGroupMemberOfGroup}\' + \'groupMemberId=\' + #p0 + \'|\' + \'groupId=\' + #p1")
boolean isGroupMemberOfGroup(String groupMemberId,
                                       String groupId)
                             throws RiceIllegalArgumentException

Check whether the group identified by groupMemberId is a member of the group identified by groupId. This will recurse through all groups.

Will return true if the group is a member of the group or a group assigned to this group.

Parameters:

groupMemberId - Id of the principal

groupId - Id string of group

Returns:

true if group is a member of the group or a member of a group assigned to the the group.

Throws:

RiceIllegalArgumentException - if the groupMemberId, groupId is null or blank

getMemberPrincipalIds

@Cacheable(value="http://rice.kuali.org/kim/v2_0/GroupMemberType",
           key="\'{getMemberPrincipalIds}\' + \'groupId=\' + #p0")
List<String> getMemberPrincipalIds(String groupId)
                                   throws RiceIllegalArgumentException

Returns all principal ids that are members of the given group id. Recurses into contained groups for comprehensive list.

Will return a list of all principal ids for members this group.

Parameters:

groupId - Id string of group

Returns:

List of principal ids

Throws:

RiceIllegalArgumentException - if the groupId is null or blank

getDirectMemberPrincipalIds

@Cacheable(value="http://rice.kuali.org/kim/v2_0/GroupMemberType",
           key="\'{getDirectMemberPrincipalIds}\' + \'groupId=\' + #p0")
List<String> getDirectMemberPrincipalIds(String groupId)
                                         throws RiceIllegalArgumentException

Returns all principal ids that are direct members of the given group id.

Will return a list of all principal ids for direct members this group.

Parameters:

groupId - Id string of group

Returns:

List of direct member principal ids.

Throws:

RiceIllegalArgumentException - if the groupId is null or blank

getMemberGroupIds

@Cacheable(value="http://rice.kuali.org/kim/v2_0/GroupMemberType",
           key="\'{getMemberGroupIds}\' + \'groupId=\' + #p0")
List<String> getMemberGroupIds(String groupId)
                               throws RiceIllegalArgumentException

Returns all group ids that are members of the given group id. Recurses into contained groups for a comprehensive list.

Will return a list of all group ids for members this group.

Parameters:

groupId - Id string of group

Returns:

List of group ids

Throws:

RiceIllegalArgumentException - if the groupId is null or blank

getDirectMemberGroupIds

@Cacheable(value="http://rice.kuali.org/kim/v2_0/GroupMemberType",
           key="\'{getDirectMemberGroupIds}\' + \'groupId=\' + #p0")
List<String> getDirectMemberGroupIds(String groupId)
                                     throws RiceIllegalArgumentException

Returns all group ids that are direct members of the given group id.

Will return a list of all group ids for direct members this group.

Parameters:

groupId - Id string of group

Returns:

List of direct member group ids.

Throws:

RiceIllegalArgumentException - if the groupId is null or blank

getParentGroupIds

@Cacheable(value="http://rice.kuali.org/kim/v2_0/GroupMemberType",
           key="\'{getParentGroupIds}\' + \'groupId=\' + #p0")
List<String> getParentGroupIds(String groupId)
                               throws RiceIllegalArgumentException

Returns all parent groups ids that the given group id is a member of. Recurses parent groups for a comprehensive list.

Will return a list of all group ids that the given group id is a member of.

Parameters:

groupId - Id string of group

Returns:

List of parent group ids.

Throws:

RiceIllegalArgumentException - if the groupId is null or blank

getDirectParentGroupIds

@Cacheable(value="http://rice.kuali.org/kim/v2_0/GroupMemberType",
           key="\'{getDirectParentGroupIds}\' + \'groupId=\' + #p0")
List<String> getDirectParentGroupIds(String groupId)
                                     throws RiceIllegalArgumentException

Returns all parent groups ids that the given group id is a member of.

Will return a list of all group ids that the given group id is a member of.

Parameters:

groupId - Id string of group

Returns:

List of parent group ids.

Throws:

RiceIllegalArgumentException - if the groupId is null or blank

getAttributes

@Cacheable(value="http://rice.kuali.org/kim/v2_0/GroupType",
           key="\'{getAttributes}\' + \'groupId=\' + #p0")
Map<String,String> getAttributes(String groupId)
                                 throws RiceIllegalArgumentException

Get all the attributes of the given group.

Throws:

RiceIllegalArgumentException - if the groupId is null or blank

getMembersOfGroup

@Cacheable(value="http://rice.kuali.org/kim/v2_0/GroupMemberType",
           key="\'groupId=\' + #p0")
List<GroupMember> getMembersOfGroup(String groupId)
                                    throws RiceIllegalArgumentException

Get all GroupMembers all the groups with a given group id.

The collection of GroupMembers will contain members for a the group in no defined order.

Parameters:

groupId - Id of group

Returns:

Collection of GroupMembers.

Throws:

RiceIllegalArgumentException - if the groupId is null or blank

getMembers

@Cacheable(value="http://rice.kuali.org/kim/v2_0/GroupMemberType",
           key="\'groupIds=\' + T(org.kuali.rice.core.api.cache.CacheKeyUtils).key(#p0)")
List<GroupMember> getMembers(List<String> groupIds)
                             throws RiceIllegalArgumentException

Get all GroupMembers all the groups with the given group ids.

The collection of GroupMembers will contain members for all the groups in no defined order. The values returned may or may not be grouped by group id.

Parameters:

groupIds - Ids of groups

Returns:

Collection of GroupMembers.

Throws:

RiceIllegalArgumentException - if the groupIds is null or empty

createGroup

@CacheEvict(value={"http://rice.kuali.org/kim/v2_0/GroupType","http://rice.kuali.org/kim/v2_0/GroupMemberType"},
            allEntries=true)
Group createGroup(Group group)
                  throws RiceIllegalArgumentException

Creates a new group using the given Group.

This will attempt to create a new Group

Parameters:

group - The new group to be created

Returns:

a the Group that has been created.

Throws:

RiceIllegalArgumentException - if the group is null

updateGroup

@CacheEvict(value={"http://rice.kuali.org/kim/v2_0/GroupType","http://rice.kuali.org/kim/v2_0/GroupMemberType"},
            allEntries=true)
Group updateGroup(Group group)
                  throws RiceIllegalArgumentException

Updates an existing group using the given Group.

This will attempt to update an existing Group. For this to return without exceptions, the passed in Group must have it's Id set and be a valid group that already exists.

Parameters:

group - The group to be updated

Returns:

a the Group that has been updated.

Throws:

RiceIllegalArgumentException - if the group is null

updateGroup

@CacheEvict(value={"http://rice.kuali.org/kim/v2_0/GroupType","http://rice.kuali.org/kim/v2_0/GroupMemberType"},
            allEntries=true)
Group updateGroup(String groupId,
                             Group group)
                  throws RiceIllegalArgumentException

Updates a group using the given Group.

This will attempt to update an existing group with data from the passed in group. If the passed in groupId and the group.id values are different this method will inactivate the old group and create a new group with the same members with the passed in groups properties.

Parameters:

groupId - Id of the Group to be updated

group - Group object to use for update

Returns:

a the Group that has been updated.

Throws:

RiceIllegalArgumentException - if the group is null or the groupId is null or blank

createGroupMember

@CacheEvict(value="http://rice.kuali.org/kim/v2_0/GroupMemberType",
            allEntries=true)
GroupMember createGroupMember(GroupMember groupMember)
                              throws RiceIllegalArgumentException

Creates a new group using the given GroupMember.

This will attempt to create a new GroupMember

Parameters:

groupMember - The new groupMember to be created

Returns:

a the GroupMember that has been created.

Throws:

RiceIllegalArgumentException - if the group is null

updateGroupMember

@CacheEvict(value="http://rice.kuali.org/kim/v2_0/GroupMemberType",
            allEntries=true)
GroupMember updateGroupMember(GroupMember groupMember)
                              throws RiceIllegalArgumentException

Updates an existing group using the given GroupMember.

This will attempt to update an existing GroupMember. For this to return without exceptions, the passed in GroupMember must have it's Id set and be a valid groupMember that already exists.

Parameters:

groupMember - The groupMember to be updated

Returns:

a the GroupMember that has been updated.

Throws:

RiceIllegalArgumentException - if the groupMember is null

addGroupToGroup

@CacheEvict(value="http://rice.kuali.org/kim/v2_0/GroupMemberType",
            allEntries=true)
boolean addGroupToGroup(String childId,
                                   String parentId)
                        throws RiceIllegalArgumentException

Adds the group with the id supplied in childId as a member of the group with the id supplied in parentId.

Parameters:

childId - Id of the Group to be added to the members of Parent

parentId - Id of the Group object to add the member to

Returns:

true if the member was added successfully.

Throws:

RiceIllegalArgumentException - if the childId, parentId is null or blank

removeGroupFromGroup

@CacheEvict(value="http://rice.kuali.org/kim/v2_0/GroupMemberType",
            allEntries=true)
boolean removeGroupFromGroup(String childId,
                                        String parentId)
                             throws RiceIllegalArgumentException

Removes the group with the id supplied in childId from the group with the id supplied in parentId.

Parameters:

childId - Id of the Group to be removed from the members of Parent

parentId - Id of the Group object to remove the member from

Returns:

true if the member was removed successfully.

Throws:

RiceIllegalArgumentException - if the childId, parentId is null or blank

addPrincipalToGroup

@CacheEvict(value="http://rice.kuali.org/kim/v2_0/GroupMemberType",
            allEntries=true)
boolean addPrincipalToGroup(String principalId,
                                       String groupId)
                            throws RiceIllegalArgumentException

Add the principal with the given principalId as a member of the group with the given groupId.

Parameters:

principalId - Id of the Principal to be added to the members of the Parent Group

groupId - Id of the Group object to add the member to

Returns:

true if the member was added successfully.

Throws:

RiceIllegalArgumentException - if the principalId, groupId is null or blank

removePrincipalFromGroup

@CacheEvict(value="http://rice.kuali.org/kim/v2_0/GroupMemberType",
            allEntries=true)
boolean removePrincipalFromGroup(String principalId,
                                            String groupId)
                                 throws RiceIllegalArgumentException

Removes the member principal with the given principalId from the group with the given groupId.

Parameters:

principalId - Id of the Principal to be removed from the members of the Parent Group

groupId - Id of the Group object to remove the member from

Returns:

true if the member was removed successfully.

Throws:

RiceIllegalArgumentException - if the principalId, groupId is null or blank

removeAllMembers

@CacheEvict(value="http://rice.kuali.org/kim/v2_0/GroupMemberType",
            allEntries=true)
void removeAllMembers(String groupId)
                      throws RiceIllegalArgumentException

Removes all members from the group with the given groupId.

Parameters:

groupId - Id of the Group object to remove the members from

Throws:

RiceIllegalArgumentException - if the groupId is null or blank