Oracle® Content Services Application Developer's Guide 10g Release 1 (10.1.1) Part Number B14494-01 |
|
|
View PDF |
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.
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]); } }
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 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()); }
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(); } }