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();
    }

This example features an attribute request, which is a request from a manager for a set of specific attributes about a particular Item. The attribute request is performed by creating an AttributeRequest array, and populating it with a list of attributes. Using attribute requests, you can fetch additional attributes about the Item by passing (possibly nested) arrays of attribute requests. This allows for retrieval of entire trees of related objects and their attributes in one call. When the call containing the attribute request is made (in this case the createGroup call), it returns the requested attributes into an Item (in this case gp). The attributes in the item can then be retrieved using the Item method getRequestedAttributes() (not shown below).

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;
}

In the last line before returning, the returned attributes from the AttributeRequest are passed to a log method of the WsUtility class, which writes a log of the action that took place. Inside the log method, the attributes are retrieved using the getRequestedAttributes method, which returns an array of NamedValue pairs (each containing an Attribute and a value).

public static void log(String indent, Item item)
{
    ...
 
    NamedValue[] attributes = item.getRequestedAttributes();
    int len = (attributes == null) ? 0 : attributes.length;
 
    if (len > 0)
    {
        log(indent, "Requested Attributes");
    }
    for (int i = 0; i < len; i++)
    {
        log(indent + INDENT, attributes[i]);
    }
}

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.

/**
 * Add members in the existing group
 */
public static Item addMember(Item group, String[] members)
    throws FdkException, RemoteException
{
    // 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();
    }
 
    // add members definition
    NamedValue[] addMbrDef = WsUtility.newNamedValueArray(new Object[][] { {
        Attributes.MEMBER_LIST, mbrList } });
 
    // group attribute member request 
    AttributeRequest[] group_attr_mbr = 
        WsUtility.newAttributeRequestArray(new String[] { 
        Attributes.MEMBER_LIST });
    // add group member
    //     -> no AttributeRequest is specified (third argument is null)
    Item gp = gm.addUsers(group.getId(), addMbrDef, group_attr_mbr);
 
    // log group info
    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 the attribute request is not included for this example, since we are deleting an item and thus do not need to retrieve its properties.

/**
 * Remove members from the existing group
 */
public static Item removeMember(Item group, String[] members)
    throws FdkException, RemoteException
{
    // 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 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 } });
 
    // remove group member
    // -> no AttributeRequest is specified (third argument is null)
    return gm.removeUsers(group.getId(), removeMbrDef, null);
}

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().

/**
 * Add managers in the existing group
 */
public static Item addManagers(Item group, String[] managers)
    throws RemoteException, FdkException
{
    // get the Manager instances we need
    GroupManager gm = WsConnection.getGroupManager();
    UserManager um = WsConnection.getUserManager();
 
    // get managers list length
    int len = (managers != null) ? managers.length : 0;
    // initialize 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 attribute manager request 
    AttributeRequest[] group_attr_mgr = 
    WsUtility.newAttributeRequestArray(new String[] { 
        Attributes.MANAGER_LIST });
 
    // add group manager
    // -> no AttributeRequest is specified (third argument is null)
    Item gp = gm.addUsers(group.getId(), addMgrDef, group_attr_mgr);
 
    // log group info
    WsUtility.log(WsUtility.INDENT, gp);

    return gp;
}



/**
 * Remove managers from the existing group
 */
public static Item removeManagers(Item group, String[] managers)
    throws FdkException, RemoteException
{
    // get the Manager instances we need
    GroupManager gm = WsConnection.getGroupManager();
    UserManager um = WsConnection.getUserManager();
 
    // Get managers list length
    int len = (managers != null) ? managers.length : 0;
 
    // initialize 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 manmager definition
    NamedValue[] removeMgrDef = WsUtility.newNamedValueArray(new Object[][] { {
        Attributes.MANAGER_LIST, mgrList } });
 
    // remove group manager
    //     -> no AttributeRequest is specified (third argument is null)
    return gm.removeUsers(group.getId(), removeMgrDef, null);
}

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 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
    {
        try
        {
            // URL to content services web services servlet
            String serverUrl = "http://yourserver.com:7777/content/ws";
 
            // authenticate to content services
            s_WsCon = s_WsCon.login(serverUrl, "tim", "welcome1");
 
            // create group
            Item newGroup = createGroup("myGroup", "This is a example group",
                new String[] { "ellie" }, new String[] { "jon" });
 
            // add member
            newGroup = addMember(newGroup, new String[] { "ray" });
 
            // add manager
            newGroup = addManagers(newGroup, new String[] { "tanya" });
 
            // remove member
            newGroup = removeMember(newGroup, new String[] { "ray" });
 
            // remove manager
            newGroup = removeManagers(newGroup, new String[] { "tanya" });
 
            // delete group
            deleteGroup(newGroup);
        }
        finally
        {
            s_WsCon.logout();
        }
    }
    catch (Throwable t)
    {
        t.printStackTrace();
    }
}