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.