com.jivesoftware.community
Interface PermissionsManager

All Superinterfaces:

JiveManager

public interface PermissionsManager
extends JiveManager

Manages permissions for users and groups on a particular resource.

This class is only intended for administrative purposes, and should not be used by skin authors to check the permissions for individual users. For example, to check if a particular user is authorized to post messages in a community, the proper code snippet is as follows:

 Community community = communityManager.getCommunity(123);
 boolean canPost = community.isAuthorized(Permissions.CREATE_MESSAGE);
 

When adding or removing permissions using this class a permissionType of PermissionType.ADDITIVE or PermissionType.NEGATIVE is required to indicate whether the permission should be 'additive' or 'negative'. Additive permissions indicate that if the permission has been already set in a parent object, it will be inherited by the object and all child objects. Negative permissions on the other hand can be thought of as 'blocking' a permission from being inherited by the object and all child objects.

Two modes for group permission checking are provided:

• Normal mode (default): when checking to see if a user has access to an object, the list of groups they belong to is enumerated using the GroupManager.getUserGroups(User) method. Then, a test is performed to see if any of those groups has permissions on the object. This mode works well when it is easy to find the groups that a user belong to, but hard to find the list of users in a group. Typically, this mode works better when the groups classes are being mapped to external roles.
• Alternate mode: when checking to see if a user has access to an object, the list of groups that have permissions for the object is enumerated. Then, a check is performed to see if the user belongs to each group, using the Group.isMember(User) method. This mode works well when it is easy to find the list of users in a group, but hard to find the list of groups a user belongs to.

To enable the alternate mode set the Jive property PermissionsManager.useAltGroupMode to true by adding the following to the jive configuration:

<PermissionsManager><useAltGroupMode>true</useAltGroupMode></PermissionsManager>

Method Summary

void	addAnonymousUserPermission(PermissionType permissionType, long permission) Add a permission of the specified PermissionType for anonymous users.
void	addGroupPermission(Group group, PermissionType permissionType, long permission) Grants a group a particular permission.
void	addRegisteredUserPermission(PermissionType permissionType, long permission) Add a permission of the specified PermissionType for registered users.
void	addUserPermission(User user, PermissionType permissionType, long permission) Add a permission of the specified PermissionType for the specified user.
boolean	anonymousUserHasPermission(PermissionType permissionType, long permission) Returns true if the anonymous users have a particular permission.
Permissions	getFinalGroupPerms(int objectType, long objectID, long groupID, PermissionType permissionType) Returns the Permissions object that corresponds to the permissions that a group has for a particular object.
Permissions	getFinalUserPerms(int objectType, long objectID, long userID, PermissionType permissionType) Returns the Permissions object that corresponds to the combined permissions that a user has for a particular object: Anonymous and "registered users" permissions.
java.lang.Iterable<Group>	groupsWithPermission(PermissionType permissionType, long permission) Returns an Iterator of groups with a particular permission.
int	groupsWithPermissionCount(PermissionType permissionType, long permission) Returns a count of the groups that have a particular permission.
boolean	registeredUserHasPermission(PermissionType permissionType, long permission) Returns true if registered users have a particular permission.
void	removeAllGroupPermissions(PermissionType permissionType) Revokes all group permissions.
void	removeAllPermissions(int objectType, long objectID)
void	removeAllUserPermissions(PermissionType permissionType) Removes all user permissions.
void	removeAnonymousUserPermission(PermissionType permissionType, long permission) Removes a permission of the specified PermissionType for anonymous users.
void	removeGroupPermission(Group group, PermissionType permissionType, long permission) Removes a permission of the specified PermissionType for a group.
void	removeRegisteredUserPermission(PermissionType permissionType, long permission) Removes a permission of the specified PermissionType for registered users.
void	removeUserPermission(User user, PermissionType permissionType, long permission) Removes a permission of the specified PermissionType for the specified user.
java.util.Iterator<java.lang.Long>	usersWithPermission(PermissionType permissionType, long permission) Returns all the userID's of users with a particular permission.
int	usersWithPermissionCount(PermissionType permissionType, long permission) Returns a count of the users that have a particular permission.

Methods inherited from interface com.jivesoftware.community.JiveManager

destroy, initialize

Method Detail

addUserPermission

void addUserPermission(User user,
                       PermissionType permissionType,
                       long permission)
                       throws UnauthorizedException

Add a permission of the specified PermissionType for the specified user. Only community or system administrators can assign permissions to a community, and only system admins can assign system level and community administration permissions. If this permissions context is at the system level, only system admins can call this method.

Parameters:

user - the User to add a permission to.

permissionType - the type of permission to add.

permission - the permission to add.

Throws:

UnauthorizedException - if does not have proper admin permissions.

addAnonymousUserPermission

void addAnonymousUserPermission(PermissionType permissionType,
                                long permission)
                                throws UnauthorizedException

Add a permission of the specified PermissionType for anonymous users. Any registered user automatically inherits any anonymous user permissions. Only community or system administrators can assign permissions to a community, and only system admins can assign community administration permissions. If this permissions context is at the system level, only system admins can call this method.

Parameters:

permissionType - the type of permission to add.

permission - the permission to add.

Throws:

UnauthorizedException - if does not have proper admin permissions.

addRegisteredUserPermission

void addRegisteredUserPermission(PermissionType permissionType,
                                 long permission)
                                 throws UnauthorizedException

Add a permission of the specified PermissionType for registered users. "Registered Users" does not refer to the static current list of users. Instead, it dynamically matches to any member of the user database. Only community or system administrators can assign permissions to a community, and only system admins can assign community administration permissions. If this permissions context is at the system level, only system admins can call this method.

Parameters:

permissionType - the type of permission to add.

permission - the permission to add.

Throws:

UnauthorizedException - if does not have proper admin permissions.

removeUserPermission

void removeUserPermission(User user,
                          PermissionType permissionType,
                          long permission)
                          throws UnauthorizedException

Removes a permission of the specified PermissionType for the specified user. Only community or system administrators can assign permissions to a community, and only system admins can assign community administration permissions. If this permissions context is at the system level, only system admins can call this method.

Parameters:

user - the User to remove a permission from.

permissionType - the type of permission to remove.

permission - the permission to remove

Throws:

UnauthorizedException - if does not have proper admin permissions.

removeAnonymousUserPermission

void removeAnonymousUserPermission(PermissionType permissionType,
                                   long permission)
                                   throws UnauthorizedException

Removes a permission of the specified PermissionType for anonymous users. Only community or system administrators can assign permissions to a community, and only system admins can assign community administration permissions. If this permissions context is at the system level, only system admins can call this method.

Parameters:

permissionType - the type of permission to remove.

permission - the permission to remove

Throws:

UnauthorizedException - if does not have proper admin permissions.

removeRegisteredUserPermission

void removeRegisteredUserPermission(PermissionType permissionType,
                                    long permission)
                                    throws UnauthorizedException

Removes a permission of the specified PermissionType for registered users. "Registered Users" does not refer to the static current list of users. Instead, it dynamically matches to any member of the user database. Only community or system administrators can assign permissions to a community, and only system admins can assign community administration permissions. If this permissions context is at the system level, only system admins can call this method.

Parameters:

permissionType - the type of permission to remove.

permission - the permission to remove

Throws:

UnauthorizedException - if does not have proper admin permissions.

removeAllUserPermissions

void removeAllUserPermissions(PermissionType permissionType)
                              throws UnauthorizedException

Removes all user permissions. Only system administrators can call this method.

Parameters:

permissionType - the type of permissions to remove.

Throws:

UnauthorizedException - if not a system admin.

anonymousUserHasPermission

boolean anonymousUserHasPermission(PermissionType permissionType,
                                   long permission)

Returns true if the anonymous users have a particular permission.

Parameters:

permissionType - the type of permission to check.

permission - the permission to check.

Returns:

true if anonymous users have the specified permission.

registeredUserHasPermission

boolean registeredUserHasPermission(PermissionType permissionType,
                                    long permission)

Returns true if registered users have a particular permission. "Registered Users" does not refer to the static current list of users. Instead, it dynamically matches to any member of the user database.

Parameters:

permissionType - the type of permission to check.

permission - the permission to check.

Returns:

true if all registered users have the specified permission.

usersWithPermission

java.util.Iterator<java.lang.Long> usersWithPermission(PermissionType permissionType,
                                                       long permission)

Returns all the userID's of users with a particular permission. This list does not include the special "anonymous users" and "registered users" permission types. This method is not the normal method for determining if a user has a certain permission on an object in the system; instead it is only useful for permission management. For example, to check if a user has read access on a community, simply call community.isAuthorized(Permissions.READ_ENTRY), where community is the community you want to check perms on.

Parameters:

permissionType - the type of permission to check.

permission - the permission to check.

Returns:

an Iterator of all the users with the specified permission.

usersWithPermissionCount

int usersWithPermissionCount(PermissionType permissionType,
                             long permission)

Returns a count of the users that have a particular permission. This list does not include the special "anonymous users" and "registered users" permission types.

Parameters:

permissionType - the type of permission to check.

permission - the permission to check.

Returns:

a count of the users that have a particular permission.

addGroupPermission

void addGroupPermission(Group group,
                        PermissionType permissionType,
                        long permission)
                        throws UnauthorizedException

Grants a group a particular permission. Only community or system administrators can assign permissions to a community, and only system admins can assign community administration permissions. If this permissions context is at the system level, only system admins can call this method.

Parameters:

group - the group to grant a permission to.

permissionType - the type of permission to add.

permission - the permission to grant the group.

Throws:

UnauthorizedException - if does not have proper admin permissions.

removeGroupPermission

void removeGroupPermission(Group group,
                           PermissionType permissionType,
                           long permission)
                           throws UnauthorizedException

Removes a permission of the specified PermissionType for a group. Only community or system administrators can assign permissions to a community, and only system admins can assign community administration permissions. If this permissions context is at the system level, only system admins can call this method.

Parameters:

group - the group to remove the permission from.

permissionType - the type of permission to remove.

permission - the permission to remove.

Throws:

UnauthorizedException - if does not have proper admin permissions.

removeAllGroupPermissions

void removeAllGroupPermissions(PermissionType permissionType)
                               throws UnauthorizedException

Revokes all group permissions. Only system admins can call this method.

Parameters:

permissionType - the type of permissions to remove.

Throws:

UnauthorizedException - if not a system admin.

groupsWithPermission

java.lang.Iterable<Group> groupsWithPermission(PermissionType permissionType,
                                               long permission)

Returns an Iterator of groups with a particular permission.

Parameters:

permissionType - the type of permission to check.

permission - the permission to check.

Returns:

an Iterator of all the groups with the specified permission.

groupsWithPermissionCount

int groupsWithPermissionCount(PermissionType permissionType,
                              long permission)

Returns a count of the groups that have a particular permission.

Parameters:

permissionType - the type of permission to check.

permission - the permission to check.

Returns:

a count of the groups that have a particular permission.

getFinalUserPerms

Permissions getFinalUserPerms(int objectType,
                              long objectID,
                              long userID,
                              PermissionType permissionType)

Returns the Permissions object that corresponds to the combined permissions that a user has for a particular object:

• Anonymous and "registered users" permissions.
• Permissions for groups that the user belongs to.
• Specific permissions granted to the user.

Parameters:

objectType - the object type to get the permissions on

objectID - the objectID to get the permissions on

userID - the userID to get the permissions for

permissionType - the type of permissions to retrieve

Returns:

the Permissions object that corresponds to the combined permissions that a user has for a particular object

removeAllPermissions

void removeAllPermissions(int objectType,
                          long objectID)

getFinalGroupPerms

Permissions getFinalGroupPerms(int objectType,
                               long objectID,
                               long groupID,
                               PermissionType permissionType)

Returns the Permissions object that corresponds to the permissions that a group has for a particular object.

Parameters:

objectType - the object type to get the permissions on

objectID - the objectID to get the permissions on

groupID - the group to get the permissions for

permissionType - the type of permissions to retrieve

Returns:

the Permissions object that corresponds to the permissions that a group has for a particular object