PUMA User and group management

Portal User Management Architecture (PUMA) provides interfaces for accessing the profile of a portal user or group. The getObjectID() method from the com.ibm.portal.Identifiable interface returns the ObjectID of a user or group in the portal user registry.

PumaProfile	Read-only access to user and group attributes and identifiers. Used to get the User object for the current user.
PumaLocator	Obtain a list of group objects for all of the groups in which the current user is a member. Paging is supported, where the result set is split up into subsets (pages) and an iterator is used to access the pages.
PumaController	Create and delete Users and Groups Modify profiles and membership
PumaEnvironment	Retrieve virtual principals, access general properties for user management, and bypass access control for the user and group management layer.

Before the portlet can use these provider objects, it must first retrieve the appropriate home interface, depending on the type of application.

Standard portlet	com.ibm.portal.um.portletservice.PumaHome
IBM portlet	com.ibm.portal.um.portletservice.legacy.PumaHome
Portal application (for example, theme or skin)	com.ibm.portal.um.PumaHome

Examples of how these interfaces are retrieved are provided in the accompanying Javadoc documentation. The following example shows how a standard portlet would obtain the identifier of a User as a String.

PortletServiceHome psh;
try{
   javax.naming.Context ctx = new javax.naming.InitialContext();
   psh = (PortletServiceHome) 
         ctx.lookup("portletservice/com.ibm.portal.um.portletservice.PumaHome");
   if (psh != null){
      PumaHome service = (PumaHome) psh.getPortletService(PumaHome.class);
      PumaProfile pp = service.getProfile(request);
      User user = pp.getCurrentUser();
      String user_objid = pp.getIdentifier(user);
   }
}
catch (PumaException pe){
   // ... error handling ...
} catch(javax.naming.NameNotFoundException ex) {
   // ... error handling ...
} catch(javax.naming.NamingException ex) {
   // ... error handling ...
}

Note: Because PumaProfile, PumaLocator and PumaController store the current user, we must not store these objects in a session or anywhere else. But we can retrieve them from PumaHome each time we use them. PumaHome, however, can be stored. The following sample shows how a standard portlet would do a standard search for reading and writing attributes:

List<User> usersStartingWithA = pumaLocator.findUsersByAttribute("uid", "a*");

// if no value for ibm-primaryEmail attribute is set, then set it
List<String> requestedAttributes = new ArrayList<String>(2);
requestedAttributes.add("uid");
requestedAttributes.add("primaryEmail");
for(User user: usersStartingWithA) 
{
    Map<String, Object> attributes = pumaProfile.getAttributes(user, requestedAttributes);
    if (attributes.get("primaryEmail")==null
    || "".equals(attributes.get("ibm-primaryEmail")))
    {
        pumaController.setAttributes(user, Collections.singletonMap("ibm-primaryEmail", attributes.get("uid")+"@ibm.com"));
    }
}

The following sample shows how to do a paged search:

// Create a properties map that requests 10 results per Page
Map<String, Object> pageProperties = new HashMap<String, Object>(2);
pageProperties.put(PumaLocator.RESULTS_PER_PAGE, 10);

PagingIterator<User> pageIter = pumaLocator.findUsersByAttribute("uid", "a*", pageProperties);

List<User> buffer = new ArrayList<User>(10);
do 
{
pageIter.getNextPage(buffer); //=> always has a first page
if (pageIter.getCurrentPageNumber()==0)
{
    System.out.println("Total results: "+pageIter.getNumberOfTotalResults());
    System.out.println("Total pages: "+pageIter.getNumberOfPages());
}
for (User aUser: buffer)
{ 
    display(aUser); 
}
} while (pageIter.hasNextPage());

// Jump to page 5
// => Will throw NoSuchPageException if NumberOfPages < 6
List<User> result = pageIter.getPage(null, 5);