4 Oracle Content Services Group Management

Oracle Content Services Web Services offers the ability to organize users into groups using the GroupManager class. Groups allow user data to be manipulated and passed around all at once, instead of by selecting individual users. This class allows you to create new groups and add or remove users to and from those groups. This chapter illustrates basic group management using the GroupManager class, with an example that performs simple group operations.

Creating a Group

To create a group, you will need a GroupManager (for group operations) and a UserManager (to retrieve user IDs for adding to the group). The process is to generate member lists for the group, create a group definition based on these member lists (and the other group parameters), and then create the group based on the group definition.

There are two classes of users for a group: managers and members. A manager is allowed to perform administrative actions on a group, such as adding and deleting users, and changing the group properties. A member simply belongs to the group and cannot edit the group at all.

This example takes a member list and a manager list as parameters, which are reconstructed as Item arrays and passed to the group definition under the attributes MEMBER_LIST and MANAGER_LIST.

/**
 * Create a group with specified members and managers
 */
public static Item createGroup(String groupName, String groupDesc,
    String[] members, String[] managers) throws RemoteException, FdkException
{
    // get the Manager instances we need
    GroupManager gm = WsConnection.getGroupManager();
    UserManager um = WsConnection.getUserManager();
 
    // get members list length
    int len = (members != null) ? members.length : 0;
 
    // initalize member list
    long mbrList[] = new long[len];
 
    for (int i = 0; i < len; i++)
    {
        // get member
        Item member = um.getUser(members[i], null);
        // get member ID
        mbrList[i] = member.getId();
    }
 
    // get managers list length
    len = (managers != null) ? managers.length : 0;
    // initalize manager list
    long mgrList[] = new long[len];
    for (int i = 0; i < len; i++)
    {
        // get manager
        Item manager = um.getUser(managers[i], null);
        // get manager ID
        mgrList[i] = manager.getId();
    }

For this example, the attributes are two arrays of user IDs, one for the managers you would like to assign to the group (in this example, mgrList), and another for the members (mbrList), as well as the name and description of the group.

// create group definition
    NamedValue[] createGroupDef = 
        WsUtility.newNamedValueArray(new Object[][] { 
            { Attributes.NAME, groupName },
            { Attributes.DESCRIPTION, groupDesc },
            { Attributes.MANAGER_LIST, mgrList },
            { Attributes.MEMBER_LIST, mbrList } });
 
    // group attribute request 
    AttributeRequest[] group_attr = 
    WsUtility.newAttributeRequestArray(new String[] { 
        Attributes.DESCRIPTION,
        Attributes.MEMBER_LIST, Attributes.GROUP_MEMBER_LIST,
        Attributes.MANAGER_LIST });
 
    // create group
    //     -> no AttributeRequest is specified (second argument is null)
    Item gp = gm.createGroup(createGroupDef, group_attr);
 
    // log group info
    WsUtility.log(WsUtility.INDENT, gp);
 
    return gp;
}

Adding and Removing Members

In the previous method, you added both a member and a manager when creating the group. Suppose you want to add more members. The following code demonstrates how to use the GroupManager.addUsers() method to add a member or list of members to an existing group.

/**
 * Adds members to an existing Group.
 * 
 * 
 */
public static Item addMember(Item group, String[] members)
    throws FdkException, RemoteException
{
    // get the Manager instances we need
    GroupManager gm = s_WsCon.getGroupManager();
    UserManager um = s_WsCon.getUserManager();
 
    // get members list length
    int len = (members != null) ? members.length : 0;
    // initalize member list
    long mbrList[] = new long[len];
    for (int i = 0; i < len; i++)
    {
        // get member
        Item member = um.getUser(members[i], null);
        // get member id
        mbrList[i] = member.getId();
    }
 
    // add members definition
    NamedValue[] addMbrDef = WsUtility.newNamedValueArray(new Object[][] { {
        Attributes.MEMBER_LIST, mbrList } });
 
    // group attributes request 
    AttributeRequest[] group_attr = 
        WsUtility.newAttributeRequestArray(new String[] { 
        Attributes.MEMBER_LIST });
    
    // add group member
    Item gp = gm.addUsers(group.getId(), addMbrDef, group_attr);
    
    // log group info
    WsUtility.log(WsUtility.INDENT);
    WsUtility.log("Added members");
    WsUtility.log(WsUtility.INDENT, gp);
 
    return gp;
}

Just as in the previous example, the first step is to generate a members list by fetching each user (as Item objects) using a call to the UserManager. Then, generate an array of NamedValue pairs from the member list, pairing each entry with the Attributes.MEMBER_LIST attribute with each member you want to add. Also, create an AttributeRequest to retrieve the member list (using the MEMBER_LIST attribute). Finally, pass the member list and the attribute request to the addUsers method in the GroupManager.

The process for removing members from a group is similar, as shown below. Note that while we do not need to use an attribute request here, we do so in order to log the attributes of the deleted item.

/**
 * Removes members from an existing Group.
 */
public static Item removeMember(Item group, String[] members)
    throws FdkException, RemoteException
{
    // get the Manager instances we need
    GroupManager gm = s_WsCon.getGroupManager();
    UserManager um = s_WsCon.getUserManager();
 
    // get members list length
    int len = (members != null) ? members.length : 0;
    
    // initalize members list
    long mbrList[] = new long[len];
    for (int i = 0; i < len; i++)
    {
        // get member
        Item member = um.getUser(members[i], null);
      
        // get member id
        mbrList[i] = member.getId();
    }
 
    // remove member definition
    NamedValue[] removeMbrDef = WsUtility.newNamedValueArray(new Object[][] { {
        Attributes.MEMBER_LIST, mbrList } });
 
    // group attributes request 
    AttributeRequest[] group_attr = 
        WsUtility.newAttributeRequestArray(new String[] { 
        Attributes.MEMBER_LIST });
    
    // remove group member
    Item gp =  gm.removeUsers(group.getId(), removeMbrDef, group_attr);
    
    // log group info
    WsUtility.log("Removed members");
    WsUtility.log(WsUtility.INDENT, gp);
    
    return gp;
}

To add and delete managers instead of members, the process is the same. Simply get a manager user, associate it with an Attributes.MANAGER_LIST attribute in a NamedValue pair, and pass it in an array to addUsers().

/**
   * Adds managers to an existing Group.
   */
public static Item addManagers(Item group, String[] managers)
    throws RemoteException, FdkException
{
    // get the Manager instances we need
    GroupManager gm = s_WsCon.getGroupManager();
    UserManager um = s_WsCon.getUserManager();
 
    // get managers list length
    int len = (managers != null) ? managers.length : 0;
    
    // initalize managers list
    long mgrList[] = new long[len];
    for (int i = 0; i < len; i++)
    {
        // get manager
        Item manager = um.getUser(managers[i], null);
      
        // get manager id
        mgrList[i] = manager.getId();
    }
 
    // add manager definition
    NamedValue[] addMgrDef = WsUtility.newNamedValueArray(new Object[][] { {
        Attributes.MANAGER_LIST, mgrList } });
 
    // group attributes request 
    AttributeRequest[] group_attr = 
        WsUtility.newAttributeRequestArray(new String[] { 
        Attributes.MANAGER_LIST });
 
    // add group manager
    Item gp = gm.addUsers(group.getId(), addMgrDef, group_attr);
 
    // log group info
    WsUtility.log("Adds managers");
    WsUtility.log(WsUtility.INDENT, gp);
 
    return gp;
}


/**
 * Removes managers from an existing Group.
 */
public static Item removeManagers(Item group, String[] managers)
    throws FdkException, RemoteException
{
    // get the Manager instances
    GroupManager gm = s_WsCon.getGroupManager();
    UserManager um = s_WsCon.getUserManager();
 
    // Get managers list length
    int len = (managers != null) ? managers.length : 0;
 
    // initalize manager list
    long mgrList[] = new long[len];
 
    for (int i = 0; i < len; i++)
    {
        // get manager
        Item manager = um.getUser(managers[i], null);
      
        // get manager id
        mgrList[i] = manager.getId();
    }
 
    // remove manager definition
    NamedValue[] removeMgrDef = WsUtility.newNamedValueArray(new Object[][] { {
        Attributes.MANAGER_LIST, mgrList } });
 
    // group attributes request 
    AttributeRequest[] group_attr = 
        WsUtility.newAttributeRequestArray(new String[] { 
        Attributes.MANAGER_LIST });
    
    // remove group manager
    Item gp = gm.removeUsers(group.getId(), removeMgrDef, group_attr);
    
    // log group info
    WsUtility.log("Removed managers");
    WsUtility.log(WsUtility.INDENT, gp);

    return gp;
}

Deleting a Group

Deleting a group is as simple as calling a single method, deleteGroup(). Groups must be deleted by group ID.

/**
 * Delete group
 */
public static void deleteGroup(Item group)
    throws FdkException, RemoteException
{
    // get the Manager instance
    GroupManager gm = WsConnection.getGroupManager();
 
    // delete group
    gm.deleteGroup(group.getId());
}

Running the Code

To run the code, connect to a running Oracle Content Services instance, create a group, and start performing group operations. Be sure to log out from the Web Services instance at the end using the WsConnection.logout() method.

private static WsConnection s_WsCon;

public static void main(String[] args)
{
    try
    {
        Properties prop = WsUtility.getProperty(args[0]);
      
        // URL to content services web services servlet
        String serverUrl = "http://" + prop.getProperty("hostname") + ":"
                + prop.getProperty("port") + "/content/ws";
     
        // authenticate to content services
        s_WsCon = WsConnection.login(serverUrl, prop.getProperty("user"), 
                prop.getProperty("password"));
 
        try
        {
            // create group
            Item newGroup = createGroup(
                            "myGroup2",
                            "This is a example group",
                            new String[] { prop.getProperty("member") },
                            new String[] { prop.getProperty("manager"),                                            prop.getProperty("user")}
                            );
 
            // remove member
            newGroup = removeMember(newGroup, new String[] { 
            prop.getProperty("member") });
     
            // add member
            newGroup = addMember(newGroup, new String[] { 
                           prop.getProperty("member") });
        
            // remove manager
            newGroup = removeManagers(newGroup, new String[] { 
                           prop.getProperty("manager") });
 
            // add manager
            newGroup = addManagers(newGroup, new String[] { 
                           prop.getProperty("manager") });
  
            // delete group
            deleteGroup(newGroup);
        }
        finally
        {
            s_WsCon.logout();
        }
    }
    catch (Throwable t)
    {
        t.printStackTrace();
    }
}