com.plumtree.server
Interface IPTUserGroup

All Superinterfaces:
IPTLocalizable, IPTObject, IPTServerContext, IPTStorable, IPTUnknown

public interface IPTUserGroup
extends IPTObject

IPTUserGroup is the interface representing a portal UserGroup object. UseGroups can contain both users and groups. User memberships are either static or dynamic. The former are manipulated directly via the IPTUserGroup API. The later are based on rules, e.g. 'Country' contains 'USA', and are assessed by the Dynamic Membership Agent. The rule is specified using an IPTFilter and the IPTUserGroup API.

Version:
2.0
Author:
Arvind Seshan

Method Summary
 void AddChildGroups(int iGroupID)
          Adds the indicated group to this group
 void AddChildGroups(int[] iaGroupIDs)
          Adds the indicated groups to this group
 void AddUsers(int iUserIDs)
          Adds the indicated user to this group as a static member.
 void AddUsers(int[] iaUserIDs)
          Adds the indicated users to this group as static members.
 java.lang.String GetAuthenticationGroup()
          Used when synchronizing with external usergroup repositories (e.g.
 int GetAuthenticationSourceID()
          Retrieves the authentication source ID for this group.
 IPTFilter GetDynamicMembershipRule()
          Returns the IPTFilter describing this group's dynamic membership rule.
 java.lang.String GetMappingAuthName()
          Retrieves the Mapping Auth Name for the group.
 java.lang.String GetUniqueAuthName()
          Returns the unique name for this group in the authentication source from which the group was synced (e.g., the unique name for the group in LDAP).
 void GrantActivityRights(java.lang.Object[] oaActivityIDs)
          Grant the indicated activity rights to members of this group
 IPTQueryResult PreviewDynamicMembershipRule(IPTFilter pRules)
          Returns an IPTQueryResult that shows what users match the given IPTFilter.
 IPTQueryResult QueryActivityRights(int nPropIDMask, int nSkipRows, int nMaxRows)
          Returns a QueryResult containing the activity rights granted to members of this group.
 IPTQueryResult QueryAllActivityRights()
          Similar to QueryActivityRights, but returns a QueryResult containing all properties for all activity rights granted to members of this group.
 IPTQueryResult QueryAllInheritedActivityRights()
          Similar to QueryInheritedActivityRights, but returns a QueryResult containing all properties for all activity rights granted to members of this group, including those that were obtained through groups that this group is a member of.
 IPTQueryResult QueryDirectChildGroups()
          Returns an IPTQueryResult describing all groups in this group (excluding the groups that are in subgroups- this function returns ONLY the groups that are direct members of this group.) Returned properties include PT_PROPID_OBJECTID, PT_PROPID_NAME, PT_PROPID_ISLOCALIZED, PT_PROPID_USERGROUP_UNIQUENAME.
 int QueryDirectChildGroupsCount()
          Returns the number of groups that are direct members of this group.
 IPTQueryResult QueryDirectParentGroups()
          Returns a QueryResult describing the groups that directly contain this group.
 IPTQueryResult QueryFlattenedParentGroups()
          Returns a QueryResult describing the groups that directly or indirectly contain this group.
 IPTQueryResult QueryInheritedActivityRights(int nPropIDMask, int nSkipRows, int nMaxRows)
          Returns a QueryResult containing the activity rights granted to members of this group, including those that were obtained through groups that this group is a member of.
 IPTQueryResult QueryUsers()
          Returns an IPTQueryResult describing all static users in this group.
 IPTQueryResult QueryUsers(boolean bIncludeDynamicMembers, boolean bIncludeStaticMembers)
          Returns the direct user members of this group.
 IPTQueryResult QueryUsers(boolean bIncludeDynamicMembers, boolean bIncludeStaticMembers, int nMaxRows, int nRowsToSkip)
          Returns a portion of the direct user members of this group, indicated by nMaxRows and nRowsToSkip.
 int QueryUsersCount()
          Returns the number of users that are direct static members of this group.
 int QueryUsersCount(boolean bIncludeDynamicMembers, boolean bIncludeStaticMembers)
          Returns the number of users that are direct members of this group.
 void RemoveAllUsers()
          Removes all users from this group that have static memberships.
 void RemoveChildGroups(int iGroupID)
          Removes the indicated group from this group
 void RemoveChildGroups(int[] iaGroupIDs)
          Removes the indicated groups from this group
 void RemoveUsers(int iUserID)
          Removes the indicated user from this group as a static member.
 void RemoveUsers(int[] iaUserIDs)
          Removes the indicated users from this group as static members.
 void RevokeActivityRights(java.lang.Object[] oaActivityIDs)
          Revoke the indicated activity rights from members of this group
 void SetAuthenticationGroup(java.lang.String Value)
          Used when synchronizing with external usergroup repositories (e.g.
 void SetAuthenticationSourceID(int iAuthSourceID)
          Sets the authentication source ID for this group.
 void SetDynamicMembershipRule(IPTFilter pRules)
          Sets the dynamic membership rule to be used for this group.
 void SetMappingAuthName(java.lang.String strValue)
          Sets the Mapping Auth Name for the group.
 void SetUniqueAuthName(java.lang.String strValue)
          Sets the unique name on the IPTUserGroup object.
 void UpdateDynamicMembers()
          Reconciles the dynamic members of this group with those that match the current dynamic membership rule.
 
Methods inherited from interface com.plumtree.server.IPTObject
GetAdminFolderID, GetClassID, GetCreated, GetImageUUID, GetLastModified, GetObjectProperties, SetAdminFolderID, SetImageUUID, SetLastModified
 
Methods inherited from interface com.plumtree.server.IPTLocalizable
GetDescription, GetIsLocalized, GetLocalizedDescription, GetLocalizedDescriptions, GetLocalizedName, GetLocalizedNames, GetName, GetPrimaryLang, GetSupportsLocalization, SetDescription, SetIsLocalized, SetLocalizedDescriptions, SetLocalizedNames, SetName, SetPrimaryLang
 
Methods inherited from interface com.plumtree.server.IPTUnknown
GetInterfaces
 
Methods inherited from interface com.plumtree.server.IPTServerContext
GetAccessLevel, GetACL, GetLastModifiedBy, GetLockState, GetObjectID, GetOwnerID, GetServerContextSettings, GetSession, GetSettings, LockObject, SetLastModifiedBy, SetObjectID, SetOwnerID, SetServerContextSettings, SetSettings, UnlockObject
 
Methods inherited from interface com.plumtree.server.IPTStorable
Store
 

Method Detail

GetAuthenticationSourceID

int GetAuthenticationSourceID()
Retrieves the authentication source ID for this group.

Returns:
The authentication source ID.

SetAuthenticationSourceID

void SetAuthenticationSourceID(int iAuthSourceID)
Sets the authentication source ID for this group. Cannot modify built-in groups.

Parameters:
iAuthSourceID - - The authentication source ID.

GetAuthenticationGroup

java.lang.String GetAuthenticationGroup()
Used when synchronizing with external usergroup repositories (e.g. LDAP.) Each external repository is associated with a unique group name, so that users and groups from different repositories don't have naming conflicts.

Returns:
the authentication group associated with this object

SetAuthenticationGroup

void SetAuthenticationGroup(java.lang.String Value)
Used when synchronizing with external usergroup repositories (e.g. LDAP.) Each external repository is associated with a unique group name, so that users and groups from different repositories don't have naming conflicts.

Parameters:
Value - the authentication group which should be associated with this object

AddUsers

void AddUsers(int[] iaUserIDs)
Adds the indicated users to this group as static members.

Parameters:
iaUserIDs - a 1D array of ints containing User IDs

AddUsers

void AddUsers(int iUserIDs)
Adds the indicated user to this group as a static member.

Parameters:
iUserID - the ID of the User to be added

RemoveUsers

void RemoveUsers(int[] iaUserIDs)
Removes the indicated users from this group as static members.

Parameters:
iaUserIDs - a 1D array of ints containing User IDs

RemoveUsers

void RemoveUsers(int iUserID)
Removes the indicated user from this group as a static member.

Parameters:
iUserID - the ID of the User to be removed

RemoveAllUsers

void RemoveAllUsers()
Removes all users from this group that have static memberships.


QueryUsers

IPTQueryResult QueryUsers()
Returns an IPTQueryResult describing all static users in this group. Returned properties include PT_PROPID_OBJECTID, PT_PROPID_NAME, PT_PROPID_DESCRIPTION, PT_PROPID_ISLOCALIZED, PT_PROPID_USER_UNIQUENAME, PT_PROPID_USER_LOGINNAME. NOTE: this function only returns users that are static members. Use the QueryUsers(boolean, boolean) override to get dynamic memberships as well.

Returns:
the user information, in an IPTQueryResult
See Also:
IPTQueryResult, PT_PROPIDS

GetMappingAuthName

java.lang.String GetMappingAuthName()
Retrieves the Mapping Auth Name for the group. The Mapping Auth Name is used with groups that are synchronized from an external authentication source, and is specific to the Authentication Source Provider. It maps the group name used in ACL sync agents.

Returns:
The mapping auth name.

SetMappingAuthName

void SetMappingAuthName(java.lang.String strValue)
Sets the Mapping Auth Name for the group. The Mapping Auth Name is used with groups that are synchronized from an external authentication source, and is specific to the Authentication Source Provider. It maps the group name used in ACL sync agents.


GetUniqueAuthName

java.lang.String GetUniqueAuthName()
Returns the unique name for this group in the authentication source from which the group was synced (e.g., the unique name for the group in LDAP).

Returns:
The unique name in the authentication source.

SetUniqueAuthName

void SetUniqueAuthName(java.lang.String strValue)
Sets the unique name on the IPTUserGroup object. Used during authentication source synchronization.

Parameters:
strValue - - The unique name in the authentication source.

AddChildGroups

void AddChildGroups(int[] iaGroupIDs)
Adds the indicated groups to this group

Parameters:
iaGroupIDs - a 1D array of ints containing Group IDs

AddChildGroups

void AddChildGroups(int iGroupID)
Adds the indicated group to this group

Parameters:
iGroupID - the ID of the group to be added

RemoveChildGroups

void RemoveChildGroups(int[] iaGroupIDs)
Removes the indicated groups from this group

Parameters:
iaGroupIDs - a 1D array of ints containing Group IDs

RemoveChildGroups

void RemoveChildGroups(int iGroupID)
Removes the indicated group from this group

Parameters:
iGroupID - the ID of the Group to be removed

QueryDirectChildGroups

IPTQueryResult QueryDirectChildGroups()
Returns an IPTQueryResult describing all groups in this group (excluding the groups that are in subgroups- this function returns ONLY the groups that are direct members of this group.) Returned properties include PT_PROPID_OBJECTID, PT_PROPID_NAME, PT_PROPID_ISLOCALIZED, PT_PROPID_USERGROUP_UNIQUENAME.

Returns:
the group information, in an IPTQueryResult
See Also:
IPTQueryResult, PT_PROPIDS

GrantActivityRights

void GrantActivityRights(java.lang.Object[] oaActivityIDs)
Grant the indicated activity rights to members of this group

Parameters:
iaActivityIDs - a 1D array of Objects containing the IDs of the Activity rights to be granted to group members

RevokeActivityRights

void RevokeActivityRights(java.lang.Object[] oaActivityIDs)
Revoke the indicated activity rights from members of this group

Parameters:
iaActivityIDs - a 1D array of Integers containing the IDs of the Activity rights to be revoked from group members

QueryActivityRights

IPTQueryResult QueryActivityRights(int nPropIDMask,
                                   int nSkipRows,
                                   int nMaxRows)
Returns a QueryResult containing the activity rights granted to members of this group. This does NOT include any activity rights inherited from groups to which this group belongs.

Parameters:
nPropIDMask - a bitmask of the properties to be included in the QueryResult, from PT_PROPIDS
nSkipRows - number of rows to skip at the beginning, or 0 for none
nMaxRows - maximum number of rows to return, or -1 for all
Returns:
the QueryResult describing the granted activity rights
See Also:
IPTQueryResult, PT_PROPIDS

QueryAllActivityRights

IPTQueryResult QueryAllActivityRights()
Similar to QueryActivityRights, but returns a QueryResult containing all properties for all activity rights granted to members of this group. This does NOT include any activity rights inherited from groups to which this group belongs.

Returns:
the QueryResult describing the granted activity rights
See Also:
IPTQueryResult

QueryInheritedActivityRights

IPTQueryResult QueryInheritedActivityRights(int nPropIDMask,
                                            int nSkipRows,
                                            int nMaxRows)
Returns a QueryResult containing the activity rights granted to members of this group, including those that were obtained through groups that this group is a member of. This includes ALL activity rights granted to users, whether they are through THIS group, through PARENT groups, through parents of parents, etc.

Parameters:
nPropIDMask - a bitmask of the properties to be included in the QueryResult, from PT_PROPIDS
nSkipRows - number of rows to skip at the beginning, or 0 for none
nMaxRows - maximum number of rows to return, or -1 for all
Returns:
the QueryResult describing the granted activity rights
See Also:
IPTQueryResult, PT_PROPIDS

QueryAllInheritedActivityRights

IPTQueryResult QueryAllInheritedActivityRights()
Similar to QueryInheritedActivityRights, but returns a QueryResult containing all properties for all activity rights granted to members of this group, including those that were obtained through groups that this group is a member of. This includes ALL activity rights granted to users, whether they are through THIS group, through PARENT groups, through parents of parents, etc.

Returns:
the QueryResult describing the granted activity rights
See Also:
IPTQueryResult

QueryDirectChildGroupsCount

int QueryDirectChildGroupsCount()
Returns the number of groups that are direct members of this group. Does not include groups that are members of groups that are in turn members of this group, etc.

Returns:
the number of child groups

QueryUsersCount

int QueryUsersCount()
Returns the number of users that are direct static members of this group. Does not include users that are members of groups that are in turn members of this group, etc.

This function only returns users that are static members. Use the QueryUsersCount(boolean, boolean) override to get dynamic memberships as well.

Returns:
the number of users

QueryUsersCount

int QueryUsersCount(boolean bIncludeDynamicMembers,
                    boolean bIncludeStaticMembers)
Returns the number of users that are direct members of this group. Does not include users that are members of groups that are in turn members of this group, etc.

NOTE: providing a value of true for both bIncludeDynamicMembers and bIncludeStaticMembers will return all memberships for this group.

Parameters:
bIncludeDynamicMembers - - true to include dynamic memberships, false to exclude them
bIncludeStaticMembers - - true to include static memberships, false to exclude them
Returns:
the number of users

QueryDirectParentGroups

IPTQueryResult QueryDirectParentGroups()
Returns a QueryResult describing the groups that directly contain this group. Does NOT include groups that contain this group indirectly, through a third group. Returned properties include PT_PROPID_OBJECTID, PT_PROPID_NAME, PT_PROPID_ISLOCALIZED.

Returns:
the QueryResult describing the groups

QueryFlattenedParentGroups

IPTQueryResult QueryFlattenedParentGroups()
Returns a QueryResult describing the groups that directly or indirectly contain this group. DOES include groups that contain this group indirectly, through a third group. Returned properties include PT_PROPID_OBJECTID, PT_PROPID_NAME, PT_PROPID_ISLOCALIZED.

Returns:
the QueryResult describing the groups

SetDynamicMembershipRule

void SetDynamicMembershipRule(IPTFilter pRules)
Sets the dynamic membership rule to be used for this group. Once set, the dynamic memberships rule will be assessed by the Dynamic Membership Update Agent periodically. To force an update of this group's dynamic memeberships, see UpdateDynamicMembers().

To clear all dynamic memberships for this group, set the rule to null and store the group. Finally, call UpdateDynamicMembers() to clear the dynamic memberships.
NOTE: If this is a remote group, a PTException of type PT_RESULTCODES.PT_E_USERGROUP_IS_REMOTE will be thrown.

Parameters:
pRules - a valid IPTFilter that describes the dynamic membership criteria to evaluate. Pass null to clear the rule.

GetDynamicMembershipRule

IPTFilter GetDynamicMembershipRule()
Returns the IPTFilter describing this group's dynamic membership rule. If no rule is set, or this is a remote group, null will be returned. When manipulating a dynamic membership rule, it is best practice to get the rule, manipulate it, and then set it using SetDynamicMembershipRule(IPTFilter). Finally the object should be stored and unlocked.

Returns:
the IPTFilter decribing the dynamic membership rule, null

QueryUsers

IPTQueryResult QueryUsers(boolean bIncludeDynamicMembers,
                          boolean bIncludeStaticMembers)
Returns the direct user members of this group. Allows one to distinguish between dynamic and static memberships, or return both.

Returned properties include PT_PROPID_OBJECTID, PT_PROPID_NAME, PT_PROPID_DESCRIPTION, PT_PROPID_ISLOCALIZED, PT_PROPID_USER_UNIQUENAME, PT_PROPID_USER_LOGINNAME.
NOTE: providing a value of true for both bIncludeDynamicMembers and bIncludeStaticMembers will return all memberships for this group.

Parameters:
bIncludeDynamicMembers - - true to include dynamic memberships, false to exclude them
bIncludeStaticMembers - - true to include static memberships, false to exclude them
Returns:
the user information, in an IPTQueryResult
See Also:
IPTQueryResult, PT_PROPIDS

QueryUsers

IPTQueryResult QueryUsers(boolean bIncludeDynamicMembers,
                          boolean bIncludeStaticMembers,
                          int nMaxRows,
                          int nRowsToSkip)
Returns a portion of the direct user members of this group, indicated by nMaxRows and nRowsToSkip. Allows one to distinguish between dynamic and static memberships, or return both.

Returned properties include PT_PROPID_OBJECTID, PT_PROPID_NAME, PT_PROPID_DESCRIPTION, PT_PROPID_ISLOCALIZED, PT_PROPID_USER_UNIQUENAME, PT_PROPID_USER_LOGINNAME.
NOTE: providing a value of true for both bIncludeDynamicMembers and bIncludeStaticMembers will return all memberships for this group.

Parameters:
bIncludeDynamicMembers - - true to include dynamic memberships, false to exclude them
bIncludeStaticMembers - - true to include static memberships, false to exclude them
nMaxRows - - maximum number of users returned by the query
nRowsToSkip - - number of users at the start of the result set to skip
Returns:
the user information, in an IPTQueryResult
See Also:
IPTQueryResult, PT_PROPIDS

PreviewDynamicMembershipRule

IPTQueryResult PreviewDynamicMembershipRule(IPTFilter pRules)
Returns an IPTQueryResult that shows what users match the given IPTFilter. This function does not update the dynamic members of this group. Because the search for matching users is done in real-time, this function may take some time to return related users.

NOTE: If this is a remote group, a PTException of type PT_RESULTCODES.PT_E_USERGROUP_IS_REMOTE will be thrown.

Returned properties include PT_PROPID_OBJECTID, PT_PROPID_NAME, PT_PROPID_DESCRIPTION, PT_PROPID_ISLOCALIZED, PT_PROPID_USER_UNIQUENAME, PT_PROPID_USER_LOGINNAME.

Parameters:
pRules - - a valid IPTFilter
Returns:
the user information, in an IPTQueryResult
See Also:
IPTQueryResult, PT_PROPIDS

UpdateDynamicMembers

void UpdateDynamicMembers()
Reconciles the dynamic members of this group with those that match the current dynamic membership rule. If users no longer match this rule, they will be removed as dynamic members. If they are also listed as static members, this membership will be maintained. New users that match the rule will become dynamic members. All changes are persisted to the database in real-time, no store is necessary after calling this function.

NOTE: A PTObjectLock should not be held against this object when calling this function. If a lock is a held, an Exception will be thrown.

NOTE: If this is a remote group, a PTException of type PT_RESULTCODES.PT_E_USERGROUP_IS_REMOTE will be thrown.



Copyright 2008 Plumtree Software Inc. All Rights Reserved.