Class 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
    • Constructor Detail

    • Method Detail

      • 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
      • 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
      • 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
      • 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
      • 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