com.tivoli.pd.jadmin
Class PDGroup

java.lang.Object
  com.tivoli.pd.jutil.PDEnvironmentObject
      com.tivoli.pd.jadmin.PDGroup

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable

public class PDGroup
extends com.tivoli.pd.jutil.PDEnvironmentObject
implements java.lang.Cloneable

This class represents a group in the Policy Directory Management Server. It may also represent a group that is defined only in the registry, but not within the the Policy Directory Management Server.

See Also:

Serialized Form

Field Summary

static java.lang.String	PDGROUP_ALLPATTERN Constant used to match all names when listing groups.
static int	PDGROUP_MAXRETURN Constant used to return the maximum number possible when listing groups.

Constructor Summary

PDGroup(PDContext context, java.lang.Object name, PDMessages messages)
Creates a PDGroup object with the specified input name.

Method Summary

void	addMembers(PDContext context, java.util.ArrayList members, PDMessages messages) Adds the specified user to this group.
static void	addMembers(PDContext context, java.lang.String name, java.util.ArrayList members, PDMessages messages) Adds the specified user to the specified group.
java.lang.Object	clone() Returns a copy of this object.
static void	createGroup(PDContext context, java.lang.String pdName, PDRgyGroupName rgyName, java.lang.String description, java.lang.String container, PDMessages messages) Creates a group in the Policy Director Management Server.
static void	deleteGroup(PDContext context, java.lang.String name, boolean deleteFromRgy, PDMessages messages) Deletes a group from the Policy Director Management Server and optionally deletes it from the group registry.
boolean	equals(java.lang.Object obj) Determines whether this PDGroup is equivalent to the input object.
java.lang.String	getDescription() Returns the group description from this object.
java.lang.String	getId() Returns the name for this group as defined by Policy Director.
java.util.ArrayList	getMembers() Returns a list of users from this object that are members of this group.
java.lang.String	getRgyName() Returns the name for this group as defined in the group registry.
int	hashCode()
static void	importGroup(PDContext context, java.lang.String pdName, PDRgyGroupName rgyName, java.lang.String container, PDMessages messages) Creates a group in the Policy Director Management Server by importing it from the group directory.
boolean	isPDGroup() Returns a setting from this object indicating whether or not this group is defined to the Policy Director Management Server.
static java.util.ArrayList	listGroups(PDContext context, java.lang.String pattern, long maxReturn, boolean listByRgyName, PDMessages messages) Lists groups whose names match the input pattern.
void	removeMembers(PDContext context, java.util.ArrayList members, PDMessages messages) Removes the specified user from this group.
static void	removeMembers(PDContext context, java.lang.String name, java.util.ArrayList members, PDMessages messages) Removes the specified user from the specified group.
void	setDescription(PDContext context, java.lang.String newDesc, PDMessages messages) Modifies this Policy Director group's description.
static void	setDescription(PDContext context, java.lang.String name, java.lang.String newDesc, PDMessages messages) Modifies the description for the specified Policy Director group.
java.lang.String	toString() Returns a String representation of this object.

Methods inherited from class com.tivoli.pd.jutil.PDEnvironmentObject

getContext, setContext

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Field Detail

PDGROUP_ALLPATTERN

public static final java.lang.String PDGROUP_ALLPATTERN

Constant used to match all names when listing groups.

See Also:

Constant Field Values

PDGROUP_MAXRETURN

public static final int PDGROUP_MAXRETURN

Constant used to return the maximum number possible when listing groups.

See Also:

Constant Field Values

Constructor Detail

PDGroup

public PDGroup(PDContext context,
               java.lang.Object name,
               PDMessages messages)
        throws PDException

Creates a PDGroup object with the specified input name. If the input name is a Policy Director group name, the group must be defined in Policy Director Management Server. If the input name is a registry group name, the group must be defined in the registry, but need not be defined to Policy Director.

This constructor corresponds to the ivadmin_group_get() and ivadmin_group_getbydn() C APIs.

Parameters:

context - the context for communicating with the Policy Director Management Server.

name - the name of the group to instantiate. If this is a Policy Director group, input the Policy Director name (a String). If this is a registry-only group, input the registry name (a PDRgyGroupName object).

messages - in/out parameter; empty PDMessages on input; may contain zero or more informational or warning messages on output.

Throws:

PDException - if an error occurs. This exception may contain error and message codes defined in the product Error Message Reference document.

Method Detail

getId

public java.lang.String getId()
                       throws PDException

Returns the name for this group as defined by Policy Director. Null is returned if the group is defined only in the registry, but not in the Policy Director Management Server.

This method corresponds to the ivadmin_group_getid() C API.

Throws:

PDException

getRgyName

public java.lang.String getRgyName()
                            throws PDException

Returns the name for this group as defined in the group registry.

This method corresponds to the ivadmin_group_getdn() C API.

Throws:

PDException

getDescription

public java.lang.String getDescription()
                                throws PDException

Returns the group description from this object. The return value will never be null, but it may be an empty String if the description has not been set.

This method corresponds to the ivadmin_group_getdescription() C API.

Throws:

PDException

getMembers

public java.util.ArrayList getMembers()
                               throws PDException

Returns a list of users from this object that are members of this group.

This method corresponds to the ivadmin_group_getmembers() C API.

For efficiency consideration, current implementation lazy loads the membership list on first call to this method. Developers should expect a longer response time (especially for a group with larger membership) on first call as it fetches the group's membership details from the registry. The membership list is then cached in this instance. Subsequent calls on this method will not fetch the group membership from registry but return the membership list from the cache. The membership cache is updated whenever the group membership changes are performed by calling this instance's addMembers or removeMembers methods.

Application developer should be aware of the above behaviour. The cached membership in this instance may become stale if the group membership is being altered via another instance of PDGroup object or external application such as pdadmin.

Returns:

An ArrayList of String representing the names of users which belong to this group. The list may be empty if no users belong to the group. The return value is null if the group is not defined in the Management Server.

Throws:

PDException

isPDGroup

public boolean isPDGroup()
                  throws PDException

Returns a setting from this object indicating whether or not this group is defined to the Policy Director Management Server.

Returns:

true, if the group is defined to Policy Director; false, if the group is defined only in the group registry.

Throws:

PDException

addMembers

public void addMembers(PDContext context,
                       java.util.ArrayList members,
                       PDMessages messages)
                throws PDException

Adds the specified user to this group. This change affects both the current object and the group in the Policy Director Management Server.

This method corresponds to the ivadmin_group_addmember() C API.

Parameters:

context - the context for communicating with the Policy Director Management Server.

members - a list of member names (Strings) to add to the group. This argument may not be null and must contain at least one user name.

messages - in/out parameter; empty PDMessages on input; may contain zero or more informational or warning messages on output.

Throws:

PDException - if an error occurs. This exception may contain error and message codes defined in the product Error Message Reference document.

removeMembers

public void removeMembers(PDContext context,
                          java.util.ArrayList members,
                          PDMessages messages)
                   throws PDException

Removes the specified user from this group. This change affects both the current object and the group in the Policy Director Management Server.

This method corresponds to the ivadmin_group_removemember() C API.

Parameters:

context - the context for communicating with the Policy Director Management Server.

members - a list of member names (Strings) to remove from the group. This argument may not be null and must contain at least one user name.

messages - in/out parameter; empty PDMessages on input; may contain zero or more informational or warning messages on output.

Throws:

PDException - if an error occurs. This exception may contain error and message codes defined in the product Error Message Reference document.

setDescription

public void setDescription(PDContext context,
                           java.lang.String newDesc,
                           PDMessages messages)
                    throws PDException

Modifies this Policy Director group's description. This change affects both the current object and the group in the Policy Director Management Server.

This method corresponds to the ivadmin_group_setdescription() C API.

Parameters:

context - the context for communicating with the Policy Director Management Server.

newDesc - the new description. This argument may not be null but may be zero length to clear an existing description.

messages - in/out parameter; empty PDMessages on input; may contain zero or more informational or warning messages on output.

Throws:

PDException - if an error occurs. This exception may contain error and message codes defined in the product Error Message Reference document.

toString

public java.lang.String toString()

Returns a String representation of this object.

Overrides:

toString in class java.lang.Object

clone

public java.lang.Object clone()

Returns a copy of this object.

Overrides:

clone in class java.lang.Object

equals

public boolean equals(java.lang.Object obj)

Determines whether this PDGroup is equivalent to the input object.

Overrides:

equals in class java.lang.Object

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

createGroup

public static void createGroup(PDContext context,
                               java.lang.String pdName,
                               PDRgyGroupName rgyName,
                               java.lang.String description,
                               java.lang.String container,
                               PDMessages messages)
                        throws PDException

Creates a group in the Policy Director Management Server.

This constructor corresponds to the ivadmin_group_create2() C API.

Parameters:

context - the context for communicating with the Policy Director Management Server.

pdName - the Policy Director group name. This value may not be null and must have a nonzero length.

rgyName - the registry group name. The registry name in this object must be nonnull and have a nonzero length.

description - this argument is currently ignored; the description must be set explicitly using the setDescription method.

container - the container object within the management object space. This value can be null or zero-length to indicate the group is at the root level.

messages - in/out parameter; empty PDMessages on input; may contain zero or more informational or warning messages on output.

Throws:

PDException - if an error occurs. This exception may contain error and message codes defined in the product Error Message Reference document.

importGroup

public static void importGroup(PDContext context,
                               java.lang.String pdName,
                               PDRgyGroupName rgyName,
                               java.lang.String container,
                               PDMessages messages)
                        throws PDException

Creates a group in the Policy Director Management Server by importing it from the group directory.

This constructor corresponds to the ivadmin_group_import() C API.

Parameters:

context - the context for communicating with the Policy Director Management Server.

pdName - the Policy Director group name.

rgyName - an object specifying the registry group name. This value may not be null or specify a null or zero-length name.

container - the container object within the management object space. This value can be null or zero-length to indicate the group is at the root level.

messages - in/out parameter; empty PDMessages on input; may contain zero or more informational or warning messages on output.

Throws:

PDException - if an error occurs. This exception may contain error and message codes defined in the product Error Message Reference document.

deleteGroup

public static void deleteGroup(PDContext context,
                               java.lang.String name,
                               boolean deleteFromRgy,
                               PDMessages messages)
                        throws PDException

Deletes a group from the Policy Director Management Server and optionally deletes it from the group registry.

This method corresponds to the ivadmin_group_delete() C API.

Parameters:

context - the context for communicating with the Policy Director Management Server.

name - the Policy Director group name. Cannot be null.

deleteFromRgy - true, if the group should be deleted from the group registry in addition to the Policy Director Management Server; false, otherwise.

messages - in/out parameter; empty PDMessages on input; may contain zero or more informational or warning messages on output.

Throws:

PDException - if an error occurs. This exception may contain error and message codes defined in the product Error Message Reference document.

listGroups

public static java.util.ArrayList listGroups(PDContext context,
                                             java.lang.String pattern,
                                             long maxReturn,
                                             boolean listByRgyName,
                                             PDMessages messages)
                                      throws PDException

Lists groups whose names match the input pattern. The returned list may be empty but it will never be null.

If listByRgyName is false, list the Policy Director groups that match the specified pattern. If listByRgyName is true, list the registry groups whose names match the specified pattern.

This method corresponds to the ivadmin_group_list() and ivadmin_group_listbydn() C APIs.

Parameters:

context - the context for communicating with the Policy Director Management Server.

pattern - the pattern for group names to match. For LDAP registries, this pattern is interpreted as a literal string, with the exception of the asterisk ('*') character, which is interpreted as a metacharacter that matches zero or more characters. Asterisks can be located at the beginning, in the middle or at the end of the pattern, and the pattern can contain multiple asterisks. PDGROUP_ALLPATTERN matches all names. Non-LDAP registries that are supported in the future may not follow these pattern rules.

maxReturn - the maximum number of group names to return. This argument must be greater than or equal to 0. The value of 0 or PDGROUP_MAXRETURN means return all groups. This number can also be limited by the registry server so the maximum number returned is really the minimum of the server configuration and this value.

listByRgyName - true, if the groups should be matched by their registry names; false, if the users should be matched by their Policy Director names.

messages - in/out parameter; empty PDMessages on input; may contain zero or more informational or warning messages on output.

Returns:

an ArrayList of strings that represent the names of groups. The returned list will never be null.

Throws:

PDException - if an error occurs. This exception may contain error and message codes defined in the product Error Message Reference document.

setDescription

public static void setDescription(PDContext context,
                                  java.lang.String name,
                                  java.lang.String newDesc,
                                  PDMessages messages)
                           throws PDException

Modifies the description for the specified Policy Director group. This change affects only group data in the Policy Director Management Server.

This method corresponds to the ivadmin_group_setdescription() C API.

Parameters:

context - the context for communicating with the Policy Director Management Server.

name - the Policy Director group name.

newDesc - the new description. This argument may not be null but may be zero length to clear an existing description.

messages - in/out parameter; empty PDMessages on input; may contain zero or more informational or warning messages on output.

Throws:

PDException - if an error occurs. This exception may contain error and message codes defined in the product Error Message Reference document.

addMembers

public static void addMembers(PDContext context,
                              java.lang.String name,
                              java.util.ArrayList members,
                              PDMessages messages)
                       throws PDException

Adds the specified user to the specified group. This change affects only group data in the Policy Director Management Server.

This method corresponds to the ivadmin_group_addmember() C API.

Parameters:

context - the context for communicating with the Policy Director Management Server.

name - the Policy Director group name.

members - a list of member names (Strings) to add to the group. This argument may not be null and must contain at least one user name.

messages - in/out parameter; empty PDMessages on input; may contain zero or more informational or warning messages on output.

Throws:

PDException - if an error occurs. This exception may contain error and message codes defined in the product Error Message Reference document.

removeMembers

public static void removeMembers(PDContext context,
                                 java.lang.String name,
                                 java.util.ArrayList members,
                                 PDMessages messages)
                          throws PDException

Removes the specified user from the specified group. This change affects only group data in the Policy Director Management Server.

This method corresponds to the ivadmin_group_removemember() C API.

Parameters:

context - the context for communicating with the Policy Director Management Server.

name - the Policy Director group name.

members - a list of member names (Strings) to remove from the group. This argument may not be null and must contain at least one user name.

messages - in/out parameter; empty PDMessages on input; may contain zero or more informational or warning messages on output.

Throws:

PDException - if an error occurs. This exception may contain error and message codes defined in the product Error Message Reference document.