Show TOC

Using User Management Engine APILocate this document in the navigation structure

Use

The user management engine (UME) provides a comprehensive API for managing users, roles, groups, and the associated access control lists (ACLs).

When using UME API, consider the following performance related topics:

  • Checking for the existence of UME entities

  • Assigning multiple users to a group or to a role

Checking for the Existence of UME Entities

The UME API that enables you to search for a UME entity such as a user, a role, or a group, may impact performance because it returns multiple attributes related to the entity. For example, the getUser method, returns the IUser object with multiple attributes:

IUser getUser(String uniqueID, AttributeList populateAttributes) throws UMException

To improve performance, use the populateAttributes parameter to minimize the number of attributes to return, as shown in the following example:

               String uniqueID = ...;

AttributeList attrList = new AttributeList();
attrList.addAttribute(IPrincipal.DEFAULT_NAMESPACE, IPrincipal.UNIQUE_NAME, AttributeList.TYPE_STRING);

UMFactory.getUserFactory().getUser(uniqueID, attrList);

If you just need to know whether an entity exists, you can use the search API, instead of the UME API, to search for the entity.

The following example shows how to use the search API to receive a boolean result regarding the existence of a user:

               boolean existsUserByUniqueName(final String uname) throws UMException {
   final IUserFactory userFactory = UMFactory.getUserFactory();
   final IUserSearchFilter filter = userFactory.getUserSearchFilter();
   filter.setUniqueName(uname, ISearchAttribute.EQUALS_OPERATOR, false);
   return userFactory.searchUsers(filter).hasNext();
  }
Note

To check for the existence of a group or a role, replace the searchUsers() method with searchGroup() or searchRole() respectively.

Assigning Multiple Users to a Group or to a Role

UME API provides methods to assign multiple users to a group or to a role.

Note that the following UME methods have been deprecated for performance reasons: addUserToRole(), addUserToGroup(), removeUserFromRole() , removeUserFromGroup().

When upgrading from a prior version, in which the deprecated methods were used to assign multiple users to a group or to a role, you can improve consistency and performance by using the methods shown in the following example:

                  IRole role = null;
   role = UMFactory.getRoleFactory().getMutableRole(<roleid1>);
   role.addUserMember(<userid1>);
   role.addUserMember(<userid2>);
   role.addUserMember(<userid3>);
   role.save();
   role.commit();
Note

The method addMember() has the same functionality as the method addUserMember() when passed a user ID. However, only the addMember() method accepts a group ID as well. Thus, using the addUserMember() method ensures that only users are added to a role.

For more information about UME API, see Adding User Management Functions to Applications .