nl.gx.webmanager.services.usermanager
Interface GroupManager

public interface GroupManager

This type contains CRUD methods on the Group instances, and provides methods to link and unlink Users to Groups, and to query the set of Users in a given Group.

Note that the methods of a GroupManager instance that require a Group parameter are allowed to assume that such a instance has been obtained through the methods of the same GroupManager instance. If this is not the case, then an implementation may throw an unchecked exception to indicate a programming error. The same holds for the parameters of the User type: implementations may assume that these have been created by the UserManager that has been obtained by the Realm through which this GroupManager has been obtained.

Method Summary

void	addTo(User user, Group group) Adds the given user to the given group.
Group	create(java.lang.String name) Creates a new group with the given name.
GroupSearchFilter	createFilter(java.lang.String name) Creates a group filter for the given name pattern.
SortOptions<GroupSortBy>	createSortOptions(boolean isAscending, GroupSortBy sortBy) Creates a sort options instance.
void	delete(Group group) Deletes the given group.
SearchResult<Group>	find(GroupSearchFilter groupSearchFilter, SortOptions<GroupSortBy> sortOptions) Queries the groups according to the given search filter.
Group	get(java.lang.String idString) Gets a group instance from the given identifier string.
java.util.List<User>	getUsers(Group group) Retrieves all users in a given group.
void	removeFrom(User user, Group group) Removes the given user from the given group.
void	update(Group group) Updates the given group in the persistent storage.

Method Detail

create

Group create(java.lang.String name)
             throws UserManagementException

Creates a new group with the given name.

Parameters:

name - the name of the new group

Returns:

the new Group

Throws:

UserManagementException - if no group could be created for another reason

createFilter

GroupSearchFilter createFilter(java.lang.String name)

Creates a group filter for the given name pattern. If the name pattern is null then the filter will return all groups. This method is useful for creating a filter that can be given to the find(GroupSearchFilter, SortOptions) method.

Parameters:

name - a string which must be a substring of the group name, which may be null

Returns:

a filter for the given name; see GroupSearchFilter

createSortOptions

SortOptions<GroupSortBy> createSortOptions(boolean isAscending,
                                           GroupSortBy sortBy)

Creates a sort options instance. This method is useful for creating a sort options instance that can be given to the find(GroupSearchFilter, SortOptions) method.

Parameters:

isAscending - the isAscending value for the sort options (only relevant if sortBy is not null

sortBy - the data by which must be sorted (may be null)

Returns:

a sort options instance

find

SearchResult<Group> find(GroupSearchFilter groupSearchFilter,
                         SortOptions<GroupSortBy> sortOptions)
                         throws UserManagementException

Queries the groups according to the given search filter.

Parameters:

groupSearchFilter - the search filter, may be null in which case all groups are returned

sortOptions - the sort options for the result set, may be null in which case the order is unspecified

Returns:

a SearchResult for the filter sorted according to the given sort options

Throws:

UserManagementException - on error

update

void update(Group group)
            throws UserManagementException

Updates the given group in the persistent storage.

Parameters:

group - the Group to update

Throws:

UserManagementException - on error

delete

void delete(Group group)
            throws UserManagementException

Deletes the given group.

Parameters:

group - the Group to delete

Throws:

UserManagementException - on error

addTo

void addTo(User user,
           Group group)
           throws UserManagementException

Adds the given user to the given group.

Parameters:

user - the User to add

group - the Group to add the User to

Throws:

UserManagementException - on error

removeFrom

void removeFrom(User user,
                Group group)
                throws UserManagementException

Removes the given user from the given group. This method has no effect if the user is no part of the group.

Parameters:

user - the User to remove

group - the Group to remove the User from

Throws:

UserManagementException - on error

getUsers

java.util.List<User> getUsers(Group group)
                              throws UserManagementException

Retrieves all users in a given group.

Parameters:

group - the Group to get the users for

Returns:

a list of User instances in the given group

Throws:

UserManagementException - on error

get

Group get(java.lang.String idString)
          throws UserManagementException

Gets a group instance from the given identifier string. This string is to be obtained by calling Group#getId()#toString() on a Group instance which has been created by a GroupManager instance. This implementation checks that the group still exists in the persistence store.

Parameters:

idString - the id string to use to create a Group instance

Returns:

a Group instance which can be used with the methods of this manager

Throws:

UserManagementException - on error (e.g., the group has been deleted or belongs to another realm)