org.xmlecho.palomar.security
Interface SecurityService

public interface SecurityService

defines permission checking and setting for a base set of operations on objects.

the model resembles Unix file system permissions of read, write and execute, but those semantics are up to the application to decide

Also, like Unix, the concepts of users, groups, and a "superuser" are used.

Field Summary

static java.lang.String	ADMINISTRATOR
static java.lang.String	PERMISSION_EXECUTE Execute permission
static java.lang.String	PERMISSION_READ Read permission
static java.lang.String	PERMISSION_WRITE Write permission

Method Summary

Group	addGroup(java.lang.String groupName, int callerId) Add a new Group to the database.
User	addUser(java.lang.String userName, java.lang.String password, int callerId) Add a new user to the database.
boolean	addUserToGroup(User user, Group group, int callerId, boolean isPrimary) Add an existing user to a group.
boolean	checkExecute(int userId, PermissionSet mask) check if a user has a "execute" permission.
boolean	checkExecute(User user, PermissionSet mask) check if a user has an "execute" permission.
boolean	checkPermission(int userId, PermissionSet mask, java.lang.String perm) check if a user has a certain permission.
boolean	checkPermission(User user, PermissionSet mask, java.lang.String perm) check if a user has a certain permission.
boolean	checkRead(int userId, PermissionSet mask) check if a user has a "read" permission.
boolean	checkRead(User user, PermissionSet mask) check if a user has a "read" permission.
boolean	checkWrite(int userId, PermissionSet mask) check if a user has a "write" permission.
boolean	checkWrite(User user, PermissionSet mask) check if a user has a "write" permission.
boolean	deleteGroup(Group group, int callerId) Delete a group from the database.
boolean	deleteUser(User user, int callerId) Delete a user's entry from the database.
boolean	deleteUserFromGroup(User user, Group group, int callerId) deleting the relationship between an existing user and a group.
User	getAdminUser()
Group	getGroup(int id)
Group	getGroup(java.lang.String name)
User	getGuestUser()
User	getUser(int id)
User	getUser(java.lang.String name)
boolean	isAdministrativeUser(int userId) Check if a given user is an Administrator
User	login(java.lang.String hash) authenticate using a hash code.
User	login(java.lang.String userName, java.lang.String password) authenticate the username and password.
void	setDefault(PermissionSet mask) set the default granted permission.
void	setGroupExecute(PermissionSet mask, boolean bit) set a Group "Execute" permission
void	setGroupRead(PermissionSet mask, boolean bit) set a Group "Read" permission
void	setGroupWrite(PermissionSet mask, boolean bit) set a Group "Write" permission
void	setOwnerExecute(PermissionSet mask, boolean bit) set a Owner "Execute" permission
void	setOwnerRead(PermissionSet mask, boolean bit) set a Owner "Read" permission
void	setOwnerWrite(PermissionSet mask, boolean bit) set a Owner "Write" permission
boolean	setPrimaryGroup(User user, Group group, int callerId) set the primary group of a user.
void	setWorldExecute(PermissionSet mask, boolean bit) set a World "Execute" permission
void	setWorldRead(PermissionSet mask, boolean bit) set a World "Read" permission
void	setWorldWrite(PermissionSet mask, boolean bit) set a World "Write" permission
boolean	updateGroup(Group group, int callerId) Update a Group's information in the database.
boolean	updateUser(User user, int callerId) Update a user's information.

Field Detail

PERMISSION_READ

public static final java.lang.String PERMISSION_READ

Read permission

See Also:

Constant Field Values

PERMISSION_WRITE

public static final java.lang.String PERMISSION_WRITE

Write permission

See Also:

Constant Field Values

PERMISSION_EXECUTE

public static final java.lang.String PERMISSION_EXECUTE

Execute permission

See Also:

Constant Field Values

ADMINISTRATOR

public static final java.lang.String ADMINISTRATOR

See Also:

Constant Field Values

Method Detail

login

public User login(java.lang.String userName,
                  java.lang.String password)
           throws SecurityServiceException

authenticate the username and password.

Parameters:

userName - username

password - password

Returns:

the User object representing the authenticated user or null if unable to authenticate.

Throws:

SecurityServiceException

login

public User login(java.lang.String hash)
           throws SecurityServiceException

authenticate using a hash code.

Parameters:

hash - the hash code

Returns:

the User object representing the authenticated user or null if unable to authenticate.

Throws:

SecurityServiceException

isAdministrativeUser

public boolean isAdministrativeUser(int userId)

Check if a given user is an Administrator

Parameters:

userId - the ID of the User

Returns:

true if the user is an Administrator, false if the user is not an Administrator

checkPermission

public boolean checkPermission(User user,
                               PermissionSet mask,
                               java.lang.String perm)

check if a user has a certain permission.

Parameters:

user - a User object whose permission needs to be checked.

mask - a PermissionSet object containing all the granted permission information to be checked against.

perm - a String indicating the permission to be checked. The valid value (case insensitive) are "read", "write", "execute".

Returns:

true if the perm is granted to the user, false if the perm is not granted to the user.

checkPermission

public boolean checkPermission(int userId,
                               PermissionSet mask,
                               java.lang.String perm)

check if a user has a certain permission.

Parameters:

userId - the ID of the user whose permission needs to be checked.

mask - a PermissionSet object containing all the granted permission information to be checked against.

perm - a String indicating the permission to be checked. The valid value (case insensitive) are "read", "write", "execute".

Returns:

true if the perm is granted to the userId, false if the perm is not granted to the userId.

checkRead

public boolean checkRead(User user,
                         PermissionSet mask)

check if a user has a "read" permission.

Parameters:

user - the user whose permission needs to be checked.

mask - a PermissionSet object containing all the granted permission information to be checked against.

Returns:

true if the "read" permission is granted to the userId, false if the "read" permission is not granted to the userId.

checkWrite

public boolean checkWrite(User user,
                          PermissionSet mask)

check if a user has a "write" permission.

Parameters:

user - the user whose permission needs to be checked.

mask - a PermissionSet object containing all the granted permission information to be checked against.

Returns:

true if the "write" permission is granted to the userId, false if the "write" permission is not granted to the userId.

checkExecute

public boolean checkExecute(User user,
                            PermissionSet mask)

check if a user has an "execute" permission.

Parameters:

user - the user whose permission needs to be checked.

mask - a PermissionSet object containing all the granted permission information to be checked against.

Returns:

true if the "execute" permission is granted to the userId, false if the read "permission" is not granted to the userId.

checkRead

public boolean checkRead(int userId,
                         PermissionSet mask)

check if a user has a "read" permission.

Parameters:

userId - the id of the User object whose permission needs to be checked.

mask - a PermissionSet object containing all the granted permission information to be checked against.

Returns:

true if the "read" permission is granted to the user, false if the "read" permission is not granted to the user.

checkWrite

public boolean checkWrite(int userId,
                          PermissionSet mask)

check if a user has a "write" permission.

Parameters:

userId - the of the User object whose permission needs to be checked.

mask - a PermissionSet object containing all the granted permission information to be checked against.

Returns:

true if the "write" permission is granted to the user, false if the "write" permission is not granted to the user.

checkExecute

public boolean checkExecute(int userId,
                            PermissionSet mask)

check if a user has a "execute" permission.

Parameters:

userId - the id of the User object whose permission needs to be checked.

mask - a PermissionSet object containing all the granted permission information to be checked against.

Returns:

true if the "execute" permission is granted to the user, false if the "execute" permission is not granted to the user.

setDefault

public void setDefault(PermissionSet mask)

set the default granted permission. The default is Owner "read", "write", "execute"; Group "read" and World "read".

Parameters:

mask - the PermissionSet object to be set to default values.

setOwnerRead

public void setOwnerRead(PermissionSet mask,
                         boolean bit)

set a Owner "Read" permission

Parameters:

mask - the PermissionSet object to be set with Owner "Read" permission

setOwnerWrite

public void setOwnerWrite(PermissionSet mask,
                          boolean bit)

set a Owner "Write" permission

Parameters:

mask - the PermissionSet object to be set with Owner "Write" permission

setOwnerExecute

public void setOwnerExecute(PermissionSet mask,
                            boolean bit)

set a Owner "Execute" permission

Parameters:

mask - the PermissionSet object to be set with Owner "Execute" permission

setGroupRead

public void setGroupRead(PermissionSet mask,
                         boolean bit)

set a Group "Read" permission

Parameters:

mask - the PermissionSet object to be set with Group "Read" permission

setGroupWrite

public void setGroupWrite(PermissionSet mask,
                          boolean bit)

set a Group "Write" permission

Parameters:

mask - the PermissionSet object to be set with Group "Write" permission

setGroupExecute

public void setGroupExecute(PermissionSet mask,
                            boolean bit)

set a Group "Execute" permission

Parameters:

mask - the PermissionSet object to be set with Group "Execute" permission

setWorldRead

public void setWorldRead(PermissionSet mask,
                         boolean bit)

set a World "Read" permission

Parameters:

mask - the PermissionSet object to be set with World "Read" permission

setWorldWrite

public void setWorldWrite(PermissionSet mask,
                          boolean bit)

set a World "Write" permission

Parameters:

mask - the PermissionSet object to be set with World "Write" permission

setWorldExecute

public void setWorldExecute(PermissionSet mask,
                            boolean bit)

set a World "Execute" permission

Parameters:

mask - the PermissionSet object to be set with World "Execute" permission

addUser

public User addUser(java.lang.String userName,
                    java.lang.String password,
                    int callerId)
             throws SecurityServiceException

Add a new user to the database. Only the administrator is allowed to do so.

Parameters:

userName - the new User name to be added to the database.

password - the new password of the user to be added.

callerId - the userId for the user who calls this method.

Returns:

User object if the user is added successfully, null if permission is denied or addition is unsuccessful.

Throws:

SecurityServiceException

updateUser

public boolean updateUser(User user,
                          int callerId)
                   throws SecurityServiceException

Update a user's information. Only the administrator or the very user himself are allowed to do so.

Parameters:

user - the User object containing the new user information to be updated in the database.

callerId - the userId for the user who calls this method.

Returns:

true if the user is updated successfully, false if permission is denied or update is unsuccessful.

Throws:

SecurityServiceException

deleteUser

public boolean deleteUser(User user,
                          int callerId)
                   throws SecurityServiceException

Delete a user's entry from the database. Only the administrator is allowed to do so.

Parameters:

user - the new User object to be deleted from the database.

callerId - the userId for the user who calls this method.

Returns:

true if the user is deleted successfully, false if permission is denied or deletion is unsuccessful.

Throws:

SecurityServiceException

addGroup

public Group addGroup(java.lang.String groupName,
                      int callerId)
               throws SecurityServiceException

Add a new Group to the database. Only the administrator is allowed to do so.

Parameters:

groupName - The new Group name to be added.

callerId - the userId of the user who calls this method.

Returns:

Group object if the group is added successfully, null if permission is denied or addition is unsuccessful.

Throws:

SecurityServiceException

updateGroup

public boolean updateGroup(Group group,
                           int callerId)
                    throws SecurityServiceException

Update a Group's information in the database. Only the administrator is allowed to do so.

Parameters:

group - The Group object containing the updated information.

callerId - the userId of the user who calls this method.

Returns:

true if the group is updated successfully, false if permission is denied or update is unsuccessful.

Throws:

SecurityServiceException

deleteGroup

public boolean deleteGroup(Group group,
                           int callerId)
                    throws SecurityServiceException

Delete a group from the database. Only the administrator is allowed to do so.

Parameters:

group - The Group object to be deleted from the database.

callerId - the userId of the user who calls this method.

Returns:

true if the group is deleted successfully, false if permission is denied or deletion is unsuccessful.

Throws:

SecurityServiceException

addUserToGroup

public boolean addUserToGroup(User user,
                              Group group,
                              int callerId,
                              boolean isPrimary)
                       throws SecurityServiceException

Add an existing user to a group.

Parameters:

user - the User object to be added to a group

group - the group

isPrimary - indicating whether this group is going to be the primary group for this user a user may only have one primary group

Returns:

true if the addition is successful, false if permission is denied, or addition is unsuccessful

Throws:

SecurityServiceException

deleteUserFromGroup

public boolean deleteUserFromGroup(User user,
                                   Group group,
                                   int callerId)
                            throws SecurityServiceException

deleting the relationship between an existing user and a group.

Parameters:

user - the User object to be removed to a group

group - the group

Returns:

true if the deletion is successful, false if permission is denied, or deletion is unsuccessful

Throws:

SecurityServiceException

setPrimaryGroup

public boolean setPrimaryGroup(User user,
                               Group group,
                               int callerId)
                        throws SecurityServiceException

set the primary group of a user. If currently another group is the primary group of the user, that group will be cleared of the primary role, since a user may only have one and only one primary group.

Parameters:

user - The User object for which a primary group is to be set

group - The Group object which will be assigned as the primary group for the user

callerId - the ID of the user who calls this method

Returns:

true if the primary group is set successfully, false if the permission is denied or the group setting is unsuccessful.

Throws:

SecurityServiceException

getUser

public User getUser(int id)
             throws SecurityServiceException

Parameters:

id - the user Id

Returns:

an object implementing the User interface given a user Id, null if does not exist or error occurs.

Throws:

SecurityServiceException

getUser

public User getUser(java.lang.String name)
             throws SecurityServiceException

Parameters:

name - the user name

Returns:

an object implementing the User interface given a user name, null if does not exist or error occurs.

Throws:

SecurityServiceException

getGuestUser

public User getGuestUser()
                  throws SecurityServiceException

Returns:

an object implementing the User interface given a user name, for the "guest" user null if does not exist or error occurs.

Throws:

SecurityServiceException

getAdminUser

public User getAdminUser()
                  throws SecurityServiceException

Returns:

an object implementing the User interface given a user name, for the administration user null if does not exist or error occurs.

Throws:

SecurityServiceException

getGroup

public Group getGroup(int id)
               throws SecurityServiceException

Parameters:

id - the group id

Returns:

an object implementing the Group interface given the group id, null if does not exist or error occurs.

Throws:

SecurityServiceException

getGroup

public Group getGroup(java.lang.String name)
               throws SecurityServiceException

Parameters:

name - the group's name

Returns:

an object implementing the Group interface given the group name, null if does not exist or error occurs.

Throws:

SecurityServiceException