2.17.2: 2011-06-17

net.sf.basedb.core
Class Role

java.lang.Object
  extended by net.sf.basedb.core.BasicItem<RoleData>
      extended by net.sf.basedb.core.Role
All Implemented Interfaces:
AccessControlled, Identifiable, Nameable, Registered, Removable, SystemItem

public class Role
extends BasicItem<RoleData>
implements Nameable, Removable, SystemItem, Registered

This class is used to represent roles. A role is used in the permission system to give users access to various parts of BASE. A permission given to a role is global, ie. it applies to all items of a spcific type on the entire server, and not only within a group or project. For example it is possible to give READ access to all SAMPLE:s, no matter if the owner has shared them to other users or not.

BASE comes with a predefined set of roles, for example ADMINISTRATOR and GUEST, which have been configured with what we think is an appropriate combination of privileges. If you wish, you may create more roles. Use roles only for functional grouping of the users, and not for organisational grouping. If you wish to do that you should use a Group or Project instead.

Version:
2.0
Author:
Nicklas
See Also:
Group, Project, Default permissions
Last modified
$Date: 2009-04-06 14:52:39 +0200 (Mon, 06 Apr 2009) $

Nested Class Summary
private static class Role.QueryRuntimeFilterImpl
          A runtime filter implementation that limits a query to only return roles where the logged in user is a member unless the logged in user has generic read permission.
 
Field Summary
static String ADMINISTRATOR
          The id for the Role item representing adminstrators.
static String GUEST
          The id for the Role item representing guests.
static String JOBAGENT
          The id for the Role item representing job agents.
static String POWER_USER
          The id for the Role item representing power users.
private static QueryRuntimeFilter RUNTIME_FILTER
          This filter will limit a query to only return roles where the logged in user is a member unless the logged in user has generic read permission.
static String SUPERVISOR
          The id for the Role item representing supervisors.
static Item TYPE
          The type of item represented by this class.
static String USER
          The id for the Role item representing regular users.
 
Fields inherited from interface net.sf.basedb.core.Nameable
MAX_DESCRIPTION_LENGTH, MAX_NAME_LENGTH
 
Fields inherited from interface net.sf.basedb.core.SystemItem
MAX_SYSTEM_ID_LENGTH
 
Constructor Summary
Role(RoleData roleData)
           
 
Method Summary
 void addUser(User user)
          Assign this Role to a user.
static Role getById(DbControl dc, int id)
          Get a Role item when you know the ID.
 String getDescription()
          Get the description for the item.
 Date getEntryDate()
          Get the date that the item was registered in the database.
 String getName()
          Get the name of the item.
static Role getNew(DbControl dc)
          Create a new Role item.
static ItemQuery<Role> getQuery()
          Get a ItemQuery object configured to retrieve Role items.
 String getSystemId()
          Get the system id for the item.
 Item getType()
          Get the type of item represented by the object.
 ItemQuery<User> getUsers()
          Get a query that returns the users that are members of this role.
(package private)  void initPermissions(int granted, int denied)
          If the logged in user is a member of this role, read permission is granted.
 boolean isDefault()
          If this role should be assigned to new users by default or not.
 boolean isMember(User user)
          Check if the given user is member of this role or not.
 boolean isRemoved()
          Check if the removed flag is set for this item.
 boolean isSystemItem()
          Check if the item is a system item or not.
 void removeUser(User user)
          Revoke this Role from a user.
 void setDefault(boolean isDefault)
          If this role should be assigned to new users by default or not.
 void setDescription(String description)
          Set the description for the item.
 void setName(String name)
          Set the name of the item.
 void setRemoved(boolean removed)
          Set the removed flag for this item.
 
Methods inherited from class net.sf.basedb.core.BasicItem
addUsingItems, addUsingItems, checkPermission, equals, getData, getDbControl, getId, getPermissions, getPluginPermissions, getSessionControl, getUsingItems, getVersion, hashCode, hasPermission, isDetached, isInDatabase, isUsed, onAfterCommit, onAfterInsert, onBeforeCommit, onRollback, setDbControl, setProjectDefaults, toString, toTransferable, validate
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface net.sf.basedb.core.Identifiable
getId, getVersion
 
Methods inherited from interface net.sf.basedb.core.AccessControlled
checkPermission, getPermissions, hasPermission
 

Field Detail

TYPE

public static final Item TYPE
The type of item represented by this class.

See Also:
Item.ROLE, getType()

ADMINISTRATOR

public static final String ADMINISTRATOR
The id for the Role item representing adminstrators. By default administrators have full privileges on the server.

See Also:
Constant Field Values

SUPERVISOR

public static final String SUPERVISOR
The id for the Role item representing supervisors. A supervisor have READ permission to everything in BASE.

See Also:
Constant Field Values

POWER_USER

public static final String POWER_USER
The id for the Role item representing power users. A power user have less permissions than an administrator but may do some things that an ordinary user may not.

See Also:
Constant Field Values

USER

public static final String USER
The id for the Role item representing regular users. This role should be sufficient for most regular users of BASE.

See Also:
Constant Field Values

GUEST

public static final String GUEST
The id for the Role item representing guests. Guests have very limited access to the server.

See Also:
Constant Field Values

JOBAGENT

public static final String JOBAGENT
The id for the Role item representing job agents. The job agents have permission to read jobs and execute them.

See Also:
Constant Field Values

RUNTIME_FILTER

private static final QueryRuntimeFilter RUNTIME_FILTER
This filter will limit a query to only return roles where the logged in user is a member unless the logged in user has generic read permission.

Constructor Detail

Role

Role(RoleData roleData)
Method Detail

getNew

public static Role getNew(DbControl dc)
                   throws BaseException
Create a new Role item.

Parameters:
dc - The DbControl which will be used for permission checking and database access.
Returns:
The new Role item
Throws:
BaseException - If there is an error

getById

public static Role getById(DbControl dc,
                           int id)
                    throws ItemNotFoundException,
                           PermissionDeniedException,
                           BaseException
Get a Role item when you know the ID.

Parameters:
dc - The DbControl which will be used for permission checking and database access.
id - The ID of the item to load
Returns:
The Role item
Throws:
ItemNotFoundException - If an item with the specified ID is not found
PermissionDeniedException - If the logged in user doesn't have Permission.READ permission to the item
BaseException - If there is another error

getQuery

public static ItemQuery<Role> getQuery()
Get a ItemQuery object configured to retrieve Role items. If the logged in user doesn't have generic permission to all roles, only roles where that user is a member are included in the list.

Returns:
A ItemQuery object

getType

public Item getType()
Description copied from interface: Identifiable
Get the type of item represented by the object. The returned value is one of the values defined in the Item enumeration.

Specified by:
getType in interface Identifiable
Returns:
A value indicating the type of item

getName

public String getName()
Description copied from interface: Nameable
Get the name of the item.

Specified by:
getName in interface Nameable
Returns:
A String with the name of the item

setName

public void setName(String name)
             throws PermissionDeniedException,
                    InvalidDataException
Description copied from interface: Nameable
Set the name of the item. The name cannot be null and mustn't be longer than the value specified by the Nameable.MAX_NAME_LENGTH constant.

Specified by:
setName in interface Nameable
Parameters:
name - The new name for the item
Throws:
PermissionDeniedException - If the logged in user doesn't have write permission
InvalidDataException - If the name is null or longer than specified by the Nameable.MAX_NAME_LENGTH constant

getDescription

public String getDescription()
Description copied from interface: Nameable
Get the description for the item.

Specified by:
getDescription in interface Nameable
Returns:
A String with a description of the item

setDescription

public void setDescription(String description)
                    throws PermissionDeniedException,
                           InvalidDataException
Description copied from interface: Nameable
Set the description for the item. The description can be null but mustn't be longer than the value specified by the Nameable.MAX_DESCRIPTION_LENGTH constant.

Specified by:
setDescription in interface Nameable
Parameters:
description - The new description for the item
Throws:
PermissionDeniedException - If the logged in user doesn't have write permission
InvalidDataException - If the description longer than specified by the Nameable.MAX_DESCRIPTION_LENGTH constant

isRemoved

public boolean isRemoved()
Description copied from interface: Removable
Check if the removed flag is set for this item.

Specified by:
isRemoved in interface Removable
Returns:
TRUE if the item is flagged as removed, FALSE otherwise

setRemoved

public void setRemoved(boolean removed)
                throws PermissionDeniedException
Description copied from interface: Removable
Set the removed flag for this item.

Specified by:
setRemoved in interface Removable
Parameters:
removed - TRUE if the item should be flagged as removed, FALSE otherwise
Throws:
PermissionDeniedException - If the logged in user doesn't have Permission.DELETE permission for setting the flag to TRUE or Permission.WRITE permission for setting the flag to FALSE

getSystemId

public String getSystemId()
Description copied from interface: SystemItem
Get the system id for the item.

Specified by:
getSystemId in interface SystemItem
Returns:
The id of the item or null if it is not a system item

isSystemItem

public boolean isSystemItem()
Description copied from interface: SystemItem
Check if the item is a system item or not. A system item have a non-null value for the system id.

Specified by:
isSystemItem in interface SystemItem
Returns:
TRUE if this item is a system item, FALSE otherwise

getEntryDate

public Date getEntryDate()
Description copied from interface: Registered
Get the date that the item was registered in the database.

Specified by:
getEntryDate in interface Registered
Returns:
A date or null if this is not known

initPermissions

void initPermissions(int granted,
                     int denied)
               throws BaseException
If the logged in user is a member of this role, read permission is granted. If this is a system role, delete and create permissions are revoked.

Overrides:
initPermissions in class BasicItem<RoleData>
Parameters:
granted - Permissions that have been granted by the subclass
denied - Permissions that have been denied by the subclass
Throws:
BaseException - If the permissions couldn't be initialised

isDefault

public boolean isDefault()
If this role should be assigned to new users by default or not.

Since:
2.4

setDefault

public void setDefault(boolean isDefault)
If this role should be assigned to new users by default or not. Note! The client must call User.addToDefaultRolesAndGroups().

Parameters:
isDefault - The new setting
Throws:
PermissionDeniedException - If the logged in user doesn't have Permission.WRITE permission for the role
Since:
2.4

addUser

public void addUser(User user)
             throws PermissionDeniedException,
                    InvalidDataException
Assign this Role to a user.

Parameters:
user - The user to be assigned this role
Throws:
PermissionDeniedException - If the logged in user doesn't have Permission.WRITE permission for the role and Permission.USE permission for the user
InvalidDataException - If the user is null

removeUser

public void removeUser(User user)
                throws PermissionDeniedException,
                       InvalidDataException
Revoke this Role from a user.

Parameters:
user - The user that should be removed from this role
Throws:
PermissionDeniedException - If the logged in user doesn't have Permission.WRITE permission for the role and Permission.USE permission for the user
InvalidDataException - If the user is null

isMember

public boolean isMember(User user)
Check if the given user is member of this role or not.

Parameters:
user - The user to check
Returns:
TRUE if the user is member, FALSE otherwise

getUsers

public ItemQuery<User> getUsers()
Get a query that returns the users that are members of this role. This query excludes users that the logged in user doesn't have permission to read.

See Also:
User.getQuery()

2.17.2: 2011-06-17