Package net.sf.basedb.core

Class ItemKey

java.lang.Object

net.sf.basedb.core.BasicItem

net.sf.basedb.core.Key

net.sf.basedb.core.ItemKey

All Implemented Interfaces:

AccessControlled, Identifiable

public class ItemKey
extends Key

This class is used to get information about which users and groups a Shareable item has been shared to.

An item key is immutable and the user/group/permission combinations cannot be changed once the key has been created. This allows the core to resuse item keys for all items with the same combination of user/group/permission values without fear that someone else may change the permissions.

To create a new item key use the UserPermissions and/or GroupPermissions objects and pass the information to the getNewOrExisting(DbControl, UserPermissions, GroupPermissions) method.

Another option is to use the MultiPermissions object which allows you to modifiy the sharing information of a whole bunch of shareable items in one go. The MultiPermissions class takes care of all the cumbersome work of creating new keys and assigning those to the items for you.

Version:

2.0

Author:

Nicklas

See Also:

• Shareable

Field Summary

Fields

Modifier and Type	Field	Description
static final Item	TYPE	The type of item represented by this class.

Constructor Summary

Constructors

Constructor	Description
ItemKey(ItemKeyData itemKeyData)

Method Summary

Modifier and Type	Method	Description
static int	deleteUnusedItemKeys()	Delete all keys that are currently not used by any item.
static ItemKey	getById(DbControl dc, int id)	Get an ItemKey item when you know the ID.
(package private) ItemKeyData	getData()	Get the BasicData object that holds all data for this item.
Set<Integer>	getGroupIds(Permission permission)	Get the ID:s of all groups that have the specified permission in this item key.
static ItemKey	getNewOrExisting(DbControl dc, UserPermissions userPermissions, GroupPermissions groupPermissions)	Create a new or load an existing ItemKey when you have a combination of user/group/permission values.
(package private) static int	getNewOrExistingKey(Session session, Map<UserData,Integer> userPermissions, Map<GroupData,Integer> groupPermissions)	Find the ID of an existing key with exactly the same user/group/permission combination.
Set<Permission>	getPermissions(Group group)	Get the permissions for a group.
Set<Permission>	getPermissions(User user)	Get the permissions for a user.
(package private) PluginPermission	getPluginPermissions()
static ItemKey	getShareToEveryOneKey(DbControl dc, Permission permission)	Get a key that can be used to share items to the EVERYONE group with the given permissions.
Item	getType()	Get the type of item represented by the object.
Set<Integer>	getUserIds(Permission permission)	Get the ID:s of all users that have the specified permission in this item key.
Set<ItemProxy>	getUsingItems()	Get all: Shareable items shared to this key
(package private) void	initPermissions(int granted, int denied)	WRITE permission is always denied.
boolean	isUsed()	Checks if: A Shareable item is using this key.

Methods inherited from class net.sf.basedb.core.BasicItem

addAnnotatableParents, addUsingItems, addUsingItems, breakCircularReferences, checkBatchAnnotatableUsage, checkPermission, equals, getBasicData, getDbControl, getId, getPermissions, getSessionControl, getVersion, hashCode, hasPermission, isDetached, isInDatabase, onAfterCommit, onAfterInsert, onBeforeCommit, onRollback, setDbControl, setProjectDefaults, toString, validate

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Details

TYPE

public static final Item TYPE

The type of item represented by this class.

See Also:

• Item.ITEMKEY
• getType()

Constructor Details

ItemKey

ItemKey(ItemKeyData itemKeyData)

Method Details

getNewOrExisting

public static ItemKey getNewOrExisting(DbControl dc,
 UserPermissions userPermissions,
 GroupPermissions groupPermissions)
                                throws PermissionDeniedException,
InvalidDataException,
BaseException

Create a new or load an existing ItemKey when you have a combination of user/group/permission values. If the database contains an item key with the same combination that key is loaded and returned, otherwise a new item key is created. If no existing key is found, the new key will immediately be saved and committed to the database using a different transaction. This ensures that no two keys contains identical permissions.

Parameters:

dc - The DbControl which will be used for permission checking and database access

userPermissions - A UserPermissions object holding the permissions for users

groupPermissions - A GroupPermissions object holding the permissions for groups

Returns:

The ItemKey item

Throws:

PermissionDeniedException - If the logged in user tried to share to the Group.EVERYONE group without having Permission.SHARE_TO_EVERYONE permission

InvalidDataException - If not sharing to any user or group

BaseException - If there is an error

getShareToEveryOneKey

public static ItemKey getShareToEveryOneKey(DbControl dc,
 Permission permission)

Get a key that can be used to share items to the EVERYONE group with the given permissions.

Parameters:

dc - An open DbControl

permission - The permissions

Returns:

An ItemKey object

Since:

3.0

getById

public static ItemKey getById(DbControl dc,
 int id)
                       throws ItemNotFoundException,
PermissionDeniedException,
BaseException

Get an ItemKey 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 ItemKey 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

deleteUnusedItemKeys

public static int deleteUnusedItemKeys()
                                throws BaseException

Delete all keys that are currently not used by any item. This method is intended to be executed at regular intervals by a cleanup application.

Returns:

The number of deleted item keys

Throws:

BaseException - If a unused key could not be deleted.

Since:

2.13

getData

ItemKeyData getData()

Description copied from class: BasicItem

Get the BasicData object that holds all data for this item.

Specified by:

getData in class BasicItem

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.

Returns:

A value indicating the type of item

isUsed

public boolean isUsed()
               throws BaseException

Checks if:

• A Shareable item is using this key.

Overrides:

isUsed in class BasicItem

Returns:

TRUE if this item is used, FALSE otherwise

Throws:

BaseException - If not able to tell if item is used or not.

See Also:

• BasicItem.getUsingItems()

getUsingItems

public Set<ItemProxy> getUsingItems()

Get all:

• Shareable items shared to this key

Overrides:

getUsingItems in class BasicItem

Returns:

A set containing proxies for the items, or an empty set if no items are using this item

Since:

2.2

See Also:

• BasicItem.addUsingItems(Set, Item, org.hibernate.query.Query)

initPermissions

void initPermissions(int granted,
 int denied)
              throws BaseException

WRITE permission is always denied. USE and CREATE permission is always granted.

Overrides:

initPermissions in class BasicItem

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

getPluginPermissions

PluginPermission getPluginPermissions()

Overrides:

getPluginPermissions in class BasicItem

getPermissions

public Set<Permission> getPermissions(User user)
                               throws InvalidDataException

Get the permissions for a user.

Parameters:

user - The User for which we want to get the permission

Returns:

A Set containing the granted permissions, or an empty set if no permissions have been granted

Throws:

InvalidDataException - If the user is null

See Also:

• Permission

getPermissions

public Set<Permission> getPermissions(Group group)
                               throws InvalidDataException

Get the permissions for a group.

Parameters:

group - The Group for which we want to get the permission

Returns:

A Set containing the granted permissions, or an empty set if no permissions have been granted

Throws:

InvalidDataException - If the user is null

See Also:

• Permission

getUserIds

public Set<Integer> getUserIds(Permission permission)

Get the ID:s of all users that have the specified permission in this item key.

Parameters:

permission - The permission the users must have

Returns:

A set with the ID:s of all matching users, or an empty set if there are no matches

getGroupIds

public Set<Integer> getGroupIds(Permission permission)

Get the ID:s of all groups that have the specified permission in this item key.

Parameters:

permission - The permission the groups must have

Returns:

A set with the ID:s of all matching groups, or an empty set if there are no matches

getNewOrExistingKey

static int getNewOrExistingKey(Session session,
 Map<UserData,Integer> userPermissions,
 Map<GroupData,Integer> groupPermissions)
                        throws BaseException

Find the ID of an existing key with exactly the same user/group/permission combination. If no existing key is found a new one is created.

Parameters:

session - The Hibernate session to use, or null if a new session should be created

userPermissions - A Map holding the user/permission combinations

groupPermissions - A Map holding the group/permission combinations

Returns:

The ID of the new or existing key

Throws:

BaseException