def update_role(role_id, delta):
        """
        Updates a role object.

        :param role_id:           The role identifier.
        :type  role_id:           str
        :param delta:             A dict containing update keywords.
        :type  delta:             dict
        :return:                  The updated object
        :rtype:                   dict
        :raise MissingResource:   if the given role does not exist
        :raise PulpDataException: if update keyword  is not supported
        """
        delta.pop('id', None)

        role = Role.get_collection().find_one({'id': role_id})
        if role is None:
            raise MissingResource(role_id)

        for key, value in delta.items():
            # simple changes
            if key in ('display_name', 'description',):
                role[key] = value
                continue

            # unsupported
            raise PulpDataException(_("Update Keyword [%s] is not supported" % key))

        Role.get_collection().save(role, safe=True)

        # Retrieve the user to return the SON object
        updated = Role.get_collection().find_one({'id': role_id})
        return updated

    def add_permissions_to_role(role_id, resource, operations):
        """
        Add permissions to a role.

        :param role_id:         role identifier
        :type  role_id:         str
        :param resource:        resource path to grant permissions to
        :type  resource:        str
        :param operations:      list or tuple
        :type  operations:      list of allowed operations being granted
        :raise MissingResource: if the given role does not exist
        """
        if role_id == SUPER_USER_ROLE:
            raise PulpDataException(_('super-users role cannot be changed'))

        role = Role.get_collection().find_one({'id': role_id})
        if role is None:
            raise MissingResource(role_id)

        current_ops = role['permissions'].setdefault(resource, [])
        for o in operations:
            if o in current_ops:
                continue
            current_ops.append(o)

        users = factory.user_query_manager().find_users_belonging_to_role(role_id)
        for user in users:
            factory.permission_manager().grant(resource, user['login'], operations)

        Role.get_collection().save(role, safe=True)

    def create_role(role_id, display_name=None, description=None):
        """
        Creates a new Pulp role.

        :param role_id:           unique identifier for the role
        :type  role_id:           str
        :param display_name:      user-readable name of the role
        :type  display_name:      str
        :param description:       free form text used to describe the role
        :type  description:       str
        :raise DuplicateResource: if there is already a role with the requested name
        :raise InvalidValue:      if any of the fields are unacceptable

        :return: The created object
        :rtype: dict
        """
        existing_role = Role.get_collection().find_one({'id': role_id})
        if existing_role is not None:
            raise DuplicateResource(role_id)

        if role_id is None or _ROLE_NAME_REGEX.match(role_id) is None:
            raise InvalidValue(['role_id'])

        # Use the ID for the display name if one was not specified
        display_name = display_name or role_id

        # Creation
        create_me = Role(id=role_id, display_name=display_name, description=description)
        Role.get_collection().save(create_me, safe=True)

        # Retrieve the role to return the SON object
        created = Role.get_collection().find_one({'id': role_id})

        return created

 def ensure_super_user_role(self):
     """
     Ensure that the super user role exists.
     """
     role = self.get_role(SUPER_USER_ROLE)
     if role is None:
         role = self.create_role(SUPER_USER_ROLE, 'Super Users',
                                 'Role indicates users with admin privileges')
         role['permissions'] = {'/': [CREATE, READ, UPDATE, DELETE, EXECUTE]}
         Role.get_collection().save(role, safe=True)

 def ensure_super_user_role(self):
     """
     Ensure that the super user role exists.
     """
     role = Role.get_collection().find_one({'id' : self.super_user_role})
     if role is None:
         role = self.create_role(self.super_user_role, 'Super Users', 'Role indicates users with admin privileges')
         pm = factory.permission_manager()
         role['permissions'] = {'/':[pm.CREATE, pm.READ, pm.UPDATE, pm.DELETE, pm.EXECUTE]}
         Role.get_collection().save(role, safe=True)

    def add_user_to_role(role_id, login):
        """
        Add a user to a role. This has the side-effect of granting all the
        permissions granted to the role to the user.

        :param role_id:         role identifier
        :type  role_id:         str
        :param login:           login of user
        :type  login:           str
        :raise MissingResource: if the given role or user does not exist
        """
        role = Role.get_collection().find_one({'id': role_id})
        if role is None:
            raise MissingResource(role_id)

        user = User.get_collection().find_one({'login': login})
        if user is None:
            raise MissingResource(login)

        if role_id in user['roles']:
            return

        user['roles'].append(role_id)
        User.get_collection().save(user, safe=True)

        for resource, operations in role['permissions'].items():
            factory.permission_manager().grant(resource, login, operations)

    def remove_user_from_role(role_id, login):
        """
        Remove a user from a role. This has the side-effect of revoking all the
        permissions granted to the role from the user, unless the permissions are
        also granted by another role.

        :param role_id:         role identifier
        :type  role_id:         str
        :param login:           name of user
        :type  login:           str
        :raise MissingResource: if the given role or user does not exist
        """
        role = Role.get_collection().find_one({'id': role_id})
        if role is None:
            raise MissingResource(role_id)

        user = model.User.objects.get_or_404(login=login)

        if role_id == SUPER_USER_ROLE and user_controller.is_last_super_user(login):
            raise PulpDataException(
                _('%(role)s cannot be empty, and %(login)s is the last member') %
                {'role': SUPER_USER_ROLE, 'login': login})

        if role_id not in user.roles:
            return

        user.roles.remove(role_id)
        user.save()

        for item in role['permissions']:
            other_roles = factory.role_query_manager().get_other_roles(role, user.roles)
            user_ops = _operations_not_granted_by_roles(item['resource'],
                                                        item['permission'],
                                                        other_roles)
            factory.permission_manager().revoke(item['resource'], login, user_ops)

    def add_user_to_role(role_id, login):
        """
        Add a user to a role. This has the side-effect of granting all the
        permissions granted to the role to the user.

        :param role_id:         role identifier
        :type  role_id:         str
        :param login:           login of user
        :type  login:           str
        :raise MissingResource: if the given role does not exist
        :raise InvalidValue: if some params are invalid
        """
        role = Role.get_collection().find_one({'id': role_id})
        if role is None:
            raise MissingResource(role_id)

        user = User.get_collection().find_one({'login': login})
        if user is None:
            raise InvalidValue(['login'])

        if role_id in user['roles']:
            return

        user['roles'].append(role_id)
        User.get_collection().save(user, safe=True)

        for item in role['permissions']:
            factory.permission_manager().grant(item['resource'], login,
                                               item.get('permission', []))

    def remove_permissions_from_role(role_id, resource, operations):
        """
        Remove permissions from a role.

        :param role_id:         role identifier
        :type  role_id:         str
        :param resource:        resource path to revoke permissions from
        :type  resource:        str
        :param operations:      list or tuple
        :type  operations:      list of allowed operations being revoked
        :raise InvalidValue: if some params are invalid
        :raise PulpDataException: if role is a superuser role
        """
        if role_id == SUPER_USER_ROLE:
            raise PulpDataException(_('super-users role cannot be changed'))

        role = Role.get_collection().find_one({'id': role_id})
        if role is None:
            raise InvalidValue(['role_id'])

        resource_permission = {}
        current_ops = []
        for item in role['permissions']:
            if item['resource'] == resource:
                resource_permission = item
                current_ops = resource_permission['permission']

        if not current_ops:
            return
        for o in operations:
            if o not in current_ops:
                continue
            current_ops.remove(o)

        users = factory.user_query_manager().find_users_belonging_to_role(role_id)
        for user in users:
            other_roles = factory.role_query_manager().get_other_roles(role, user['roles'])
            user_ops = _operations_not_granted_by_roles(resource,
                                                        operations,
                                                        other_roles)
            factory.permission_manager().revoke(resource, user['login'], user_ops)

        # in no more allowed operations, remove the resource
        if not current_ops:
            role['permissions'].remove(resource_permission)

        Role.get_collection().save(role, safe=True)

    def find_all(self):
        """
        Returns serialized versions of all role in the database.

        @return: list of serialized roles
        @rtype:  list of dict
        """
        all_roles = list(Role.get_collection().find())
        return all_roles

def _validate_role():
    """
    Validate the Role model
    @rtype: int
    @return: number of errors found during validation
    """
    objectdb = Role.get_collection()
    reference = Role(u'')
    return _validate_model(Role.__name__, objectdb, reference)

    def find_by_id(self, role_id):
        """
        Returns a serialized version of the given role if it exists.
        If a role cannot be found with the given id, None is returned.

        @return: serialized data describing the role
        @rtype:  dict or None
        """
        role = Role.get_collection().find_one({"id": role_id})
        return role

    def add_permissions_to_role(role_id, resource, operations):
        """
        Add permissions to a role.

        :param role_id:         role identifier
        :type  role_id:         str
        :param resource:        resource path to grant permissions to
        :type  resource:        str
        :param operations:      list or tuple
        :type  operations:      list of allowed operations being granted
        :raise InvalidValue: if some params are invalid
        :raise PulpDataException: if role is a superuser role
        """
        if role_id == SUPER_USER_ROLE:
            raise PulpDataException(_('super-users role cannot be changed'))

        role = Role.get_collection().find_one({'id': role_id})
        if role is None:
            raise InvalidValue(['role_id'])
        if not role['permissions']:
            role['permissions'] = []

        resource_permission = {}
        current_ops = []
        for item in role['permissions']:
            if item['resource'] == resource:
                resource_permission = item
                current_ops = resource_permission['permission']

        if not resource_permission:
            resource_permission = dict(resource=resource, permission=current_ops)
            role['permissions'].append(resource_permission)

        for o in operations:
            if o in current_ops:
                continue
            current_ops.append(o)

        users = factory.user_query_manager().find_users_belonging_to_role(role_id)
        for user in users:
            factory.permission_manager().grant(resource, user['login'], operations)

        Role.get_collection().save(role, safe=True)

    def remove_permissions_from_role(self, role_id, resource, operations):
        """
        Remove permissions from a role. 
        
        @type role_id: str
        @param role_id: role identifier
    
        @type resource: str
        @param resource: resource path to revoke permissions from
        
        @type operations: list of allowed operations being revoked
        @param operations: list or tuple
        
        @raise MissingResource: if the given role does not exist
        """
        if role_id == self.super_user_role:
            raise PulpDataException(_('super-users role cannot be changed'))

        role = Role.get_collection().find_one({'id' : role_id})
        if role is None:
            raise MissingResource(role_id)
        
        current_ops = role['permissions'].get(resource, [])
        if not current_ops:
            return
        for o in operations:
            if o not in current_ops:
                continue
            current_ops.remove(o)
            
        users = factory.user_query_manager().find_users_belonging_to_role(role_id)
        for user in users:
            other_roles = factory.role_query_manager().get_other_roles(role, user['roles'])
            user_ops = _operations_not_granted_by_roles(resource,
                                                    operations,
                                                    other_roles)
            factory.permission_manager().revoke(resource, user['login'], user_ops)
        
        # in no more allowed operations, remove the resource
        if not current_ops:
            del role['permissions'][resource]
        
        Role.get_collection().save(role, safe=True)

    def get_role(role):
        """
        Get a Role by id.

        :param role: A role id to search for
        :type  role: str

        :return: a Role object that have the given role id.
        :rtype:  Role or None
        """
        return Role.get_collection().find_one({'id': role})

    def delete_role(role_id):
        """
        Deletes the given role. This has the side-effect of revoking any permissions granted
        to the role from the users in the role, unless those permissions are also granted
        through another role the user is a memeber of.

        :param role_id:         identifies the role being deleted
        :type  role_id:         str
        :raise InvalidValue:    if any of the fields are unacceptable
        :raise MissingResource: if the given role does not exist
        :raise PulpDataException: if role is a superuser role
        """
        # Raise exception if role id is invalid
        if role_id is None or not isinstance(role_id, basestring):
            raise InvalidValue(['role_id'])

        # Check whether role exists
        role = Role.get_collection().find_one({'id': role_id})
        if role is None:
            raise MissingResource(role_id)

        # Make sure role is not a superuser role
        if role_id == SUPER_USER_ROLE:
            raise PulpDataException(_('Role %s cannot be changed') % role_id)

        # Remove respective roles from users
        users = factory.user_query_manager().find_users_belonging_to_role(role_id)

        for item in role['permissions']:
            for user in users:
                other_roles = factory.role_query_manager().get_other_roles(role, user['roles'])
                user_ops = _operations_not_granted_by_roles(item['resource'],
                                                            item['permission'], other_roles)
                factory.permission_manager().revoke(item['resource'], user['login'], user_ops)

        for user in users:
            user['roles'].remove(role_id)
            factory.user_manager().update_user(user['login'], Delta(user, 'roles'))

        Role.get_collection().remove({'id': role_id}, safe=True)

def migrate(*args, **kwargs):
    """
    Move role permissions into the permissions database
    """
    collection = Role.get_collection()
    for role in collection.find({}):
        updated_permissions = []
        if isinstance(role['permissions'], dict):
            for resource, permission in role['permissions'].items():
                resource_permission = dict(resource=resource, permission=permission)
                updated_permissions.append(resource_permission)
            role['permissions'] = updated_permissions
            collection.save(role)

def find_users_belonging_to_role(role_id):
    """
    Get a list of users belonging to the given role

    :param role_id: get members of this role
    :type  role_id: str

    :return: list of users that are members of the given role
    :rtype:  list of pulp.server.db.model.User instances
    """
    role = Role.get_collection().find_one({'id': role_id})
    if role is None:
        raise pulp_exceptions.MissingResource(role_id)
    return [user for user in model.User.objects() if role_id in user.roles]

    def test_delete(self):
        """
        Tests deleting an existing role.
        """

        # Setup
        self.role_manager.create_role('doomed')

        # Test
        status, body = self.delete('/v2/roles/doomed/')

        # Verify
        self.assertEqual(200, status)

        role = Role.get_collection().find_one({'id' : 'doomed'})
        self.assertTrue(role is None)

    def find_users_belonging_to_role(self, role_id):
        """
        Get a list of users belonging to the given role

        @type role_id: str
        @param role_id: id of the role to get members of

        @rtype: list of L{pulp.server.db.model.auth.User} instances
        @return: list of users that are members of the given role
        """
        role = Role.get_collection().find_one({'id': role_id})
        if role is None:
            raise MissingResource(role_id)

        users = []
        for user in self.find_all():
            if role_id in user['roles']:
                users.append(user)
        return users