com.sun.jndi.ldap.obj
Class GroupOfNames

java.lang.Object
  extended by com.sun.jndi.ldap.obj.GroupOfNames
All Implemented Interfaces:
java.security.acl.Group, java.security.Principal
Direct Known Subclasses:
GroupOfUniqueNames

public class GroupOfNames
extends java.lang.Object
implements java.security.acl.Group

A representation of the LDAP groupOfNames object class. This is a static group: its members are listed in the group's member LDAP attribute.

Note that when a GroupOfNames object is created by the application program then most of its methods throw IllegalStateException until the program binds the object in the directory. However, when a GroupOfNames object is returned to the application program then the object is already bound in the directory and its methods function normally.

A GroupOfNames instance is not synchronized against concurrent multithreaded access. Multiple threads trying to access and modify a GroupOfNames should lock the object.

In order to bind a GroupOfNames object in the directory, the following LDAP object class definition (RFC 2256) must be supported in the directory schema:

     ( 2.5.6.9 NAME 'groupOfNames'
        SUP top
        STRUCTURAL
        MUST ( member $
               cn )
        MAY ( businessCategory $
              seeAlso $
              owner $
              ou $
              o $
              description ) )
 
See DirContext.bind for details on binding an object in the directory.

The following code sample shows how the class may be used:


     // set the java.naming.factory.object property
     env.put(Context.OBJECT_FACTORIES,
         "com.sun.jndi.ldap.obj.LdapGroupFactory");

     // set the java.naming.factory.state property
     env.put(Context.STATE_FACTORIES,
         "com.sun.jndi.ldap.obj.LdapGroupFactory");

     // create an initial context using the supplied environment properties
     DirContext ctx = new InitialDirContext(env);

     // create a set of members
     Set members = new HashSet();
     members.add("cn=bill,ou=people");
     members.add("cn=ben,ou=people");
     members.add("cn=sysadmins,ou=groups");
     Group administrators = new GroupOfNames(members);

     // bind the group in the directory
     ctx.bind("cn=administrators,ou=groups", administrators);

     // list all of the group's members
     listMembers(administrators);
     ...


     // list the members of a group (subgroups are expanded, by default)
     void listMembers(Group group) {
         for (Enumeration members = group.members();
                 members.hasMoreElements(); ) {
             Object object = members.nextElement();
             if (object instanceof Group) {
                 System.out.println("+" + ((Group) object).getName());
             } else if (object instanceof Principal) {
                 System.out.println(" " + ((Principal) object).getName());
             }
          }
      }
 
 

Author:
Vincent Ryan

Nested Class Summary
(package private)  class GroupOfNames.Members
          The members of a static group.
 
Field Summary
private  javax.naming.directory.Attributes attributes
           
private static javax.naming.directory.SearchControls BASE_SEARCH_NO_ATTRS
           
private  javax.naming.directory.DirContext bindCtx
           
private  java.lang.String bindDN
           
private  javax.naming.Name bindName
           
private  javax.naming.directory.DirContext ctx
           
private static boolean debug
           
private  java.util.Hashtable env
           
private static java.lang.String EXPAND_GROUP
           
private  boolean expandGroup
           
private  java.lang.Object[] filterArgs
           
private  java.lang.String groupDN
           
private static java.lang.String MEMBER_ATTR_ID
           
private static java.lang.String MEMBER_FILTER_EXPR
           
private  javax.naming.directory.Attribute memberAttr
           
private  java.lang.String memberAttrId
           
private  java.lang.String memberFilterExpr
           
private  javax.naming.directory.ModificationItem[] modification
           
private  javax.naming.Name name
           
private static java.lang.String OBJECT_CLASS
           
private static javax.naming.directory.Attribute OBJECT_CLASS_ATTR
           
private  boolean objectIsBound
           
private  javax.naming.directory.DirContext rootCtx
           
 
Constructor Summary
GroupOfNames()
          Create an empty group object.
GroupOfNames(javax.naming.directory.Attribute objectClass, java.lang.String memberAttrId, java.lang.String memberFilterExpr, java.util.Set members)
          Create a group object.
GroupOfNames(javax.naming.directory.Attribute objectClass, java.lang.String memberAttrId, java.lang.String memberFilterExpr, java.util.Set members, java.lang.String groupDN, javax.naming.directory.DirContext ctx, javax.naming.Name name, java.util.Hashtable env, javax.naming.directory.Attributes attributes)
          Create a group object from its entry in the directory.
GroupOfNames(java.util.Set members)
          Create a group object with an initial set of members.
 
Method Summary
 boolean addMember(java.security.Principal member)
          Adds a member to the group.
 boolean addMember(java.lang.String dn)
          Adds a member to the group.
 void close()
          Releases the naming context created by this group.
(package private) static java.util.Hashtable generateRootContextProperties(java.util.Hashtable env)
           
(package private)  javax.naming.directory.Attributes getAttributes()
          Retrieves the group's attributes.
 java.lang.String getName()
          Retrieves the distinguished name of the group.
(package private) static java.lang.Object getObjectInstance(java.lang.String groupDN, javax.naming.directory.DirContext ctx, javax.naming.Name name, java.util.Hashtable env, javax.naming.directory.Attributes attributes)
          Create a group object from its entry in the directory.
private  void initializeBoundState(java.lang.String groupDN, javax.naming.directory.DirContext ctx, javax.naming.Name name, java.util.Hashtable env, javax.naming.directory.Attributes attributes)
           
private  void initializeState(javax.naming.directory.Attribute objectClass, java.lang.String memberAttrId, java.lang.String memberFilterExpr, java.util.Set members)
           
private  boolean isBound()
           
 boolean isMember(java.security.Principal member)
          Checks if the supplied name is a member of the group.
 boolean isMember(java.lang.String dn)
          Checks if the supplied name is a member of the group.
private  boolean isSubgroupMember(java.lang.String dn)
           
(package private) static boolean matches(javax.naming.directory.Attribute objectClass)
          Determines whether the supplied LDAP objectClass attribute matches that of the group.
 java.util.Enumeration members()
          Returns the members of the group.
private  boolean modifyMember(java.lang.String member, int mod_op)
           
 boolean removeMember(java.security.Principal member)
          Removes a member from the group.
 boolean removeMember(java.lang.String dn)
          Removes a member from the group.
(package private)  void setName(java.lang.String groupDN, javax.naming.directory.DirContext ctx, javax.naming.Name name)
          Sets the distinguished name of the group.
 java.lang.String toString()
          Creates a string representation of the group.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface java.security.Principal
equals, hashCode
 

Field Detail

debug

private static final boolean debug
See Also:
Constant Field Values

OBJECT_CLASS

private static final java.lang.String OBJECT_CLASS
See Also:
Constant Field Values

MEMBER_ATTR_ID

private static final java.lang.String MEMBER_ATTR_ID
See Also:
Constant Field Values

MEMBER_FILTER_EXPR

private static final java.lang.String MEMBER_FILTER_EXPR
See Also:
Constant Field Values

EXPAND_GROUP

private static final java.lang.String EXPAND_GROUP
See Also:
Constant Field Values

OBJECT_CLASS_ATTR

private static final javax.naming.directory.Attribute OBJECT_CLASS_ATTR

BASE_SEARCH_NO_ATTRS

private static final javax.naming.directory.SearchControls BASE_SEARCH_NO_ATTRS

objectIsBound

private boolean objectIsBound

expandGroup

private boolean expandGroup

attributes

private javax.naming.directory.Attributes attributes

memberAttr

private javax.naming.directory.Attribute memberAttr

memberAttrId

private java.lang.String memberAttrId

memberFilterExpr

private java.lang.String memberFilterExpr

filterArgs

private java.lang.Object[] filterArgs

modification

private javax.naming.directory.ModificationItem[] modification

groupDN

private java.lang.String groupDN

bindDN

private java.lang.String bindDN

rootCtx

private javax.naming.directory.DirContext rootCtx

ctx

private javax.naming.directory.DirContext ctx

bindCtx

private javax.naming.directory.DirContext bindCtx

name

private javax.naming.Name name

bindName

private javax.naming.Name bindName

env

private java.util.Hashtable env
Constructor Detail

GroupOfNames

public GroupOfNames()
Create an empty group object.

Note that the newly constructed object does not represent a group in the directory until it is bound by using DirContext.bind.


GroupOfNames

public GroupOfNames(java.util.Set members)
Create a group object with an initial set of members.

Note that the newly constructed object does not represent a group in the directory until it is bound by using DirContext.bind.

Parameters:
members - The set of initial members. It may be null. Each element is of class String or Principal.

GroupOfNames

GroupOfNames(javax.naming.directory.Attribute objectClass,
             java.lang.String memberAttrId,
             java.lang.String memberFilterExpr,
             java.util.Set members)
Create a group object. This method is called by GroupOfUniqueNames.

Parameters:
objectClass - The LDAP objectClass attribute.
memberAttrId - The LDAP attribute ID which identifies the members.
memberfilterExpr - The filter expression used to find a member.
members - The set of initial members. It may be null.

GroupOfNames

GroupOfNames(javax.naming.directory.Attribute objectClass,
             java.lang.String memberAttrId,
             java.lang.String memberFilterExpr,
             java.util.Set members,
             java.lang.String groupDN,
             javax.naming.directory.DirContext ctx,
             javax.naming.Name name,
             java.util.Hashtable env,
             javax.naming.directory.Attributes attributes)
Create a group object from its entry in the directory. This method is called by GroupOfUniqueNames.

Parameters:
objectClass - The LDAP objectClass attribute.
memberAttrId - The LDAP attribute ID which identifies the members.
memberfilterExpr - The filter expression used to find a member.
members - The set of initial members. It may be null.
groupDN - The group's distinguished name.
name - The group's LDAP distinguished name.
ctx - An LDAP context.
name - The group's name relative to the context.
env - The context's environment properties.
attributes - The group's LDAP attributes.
Method Detail

getObjectInstance

static java.lang.Object getObjectInstance(java.lang.String groupDN,
                                          javax.naming.directory.DirContext ctx,
                                          javax.naming.Name name,
                                          java.util.Hashtable env,
                                          javax.naming.directory.Attributes attributes)
Create a group object from its entry in the directory. This method is called by LdapGroupFactory.

Parameters:
groupDN - The group's distinguished name.
ctx - An LDAP context.
name - The group's name relative to the context.
env - The context's environment properties.
attributes - The group's LDAP attributes.
Returns:
Object The new object instance.

addMember

public boolean addMember(java.security.Principal member)
Adds a member to the group. Performs an LDAP modify to add the member.

Specified by:
addMember in interface java.security.acl.Group
Parameters:
member - The name of the member to be added.
Returns:
boolean true if the addition was successful; false otherwise.
Throws:
java.lang.IllegalStateException - The exception is thrown if the group does not represent a group in the directory.

addMember

public boolean addMember(java.lang.String dn)
                  throws javax.naming.NamingException
Adds a member to the group. Performs an LDAP modify to add the member.

Parameters:
dn - The distinguished name (RFC 2253) of the member to be added.
Returns:
boolean true if the addition was successful; false otherwise.
Throws:
javax.naming.NamingException - The exception is thrown if an error occurs while performing LDAP modify.
java.lang.IllegalStateException - The exception is thrown if the group does not represent a group in the directory.

isMember

public boolean isMember(java.security.Principal member)
Checks if the supplied name is a member of the group. Performs LDAP searches to determine membership.

By default, subgroups are also checked. As subgroup expansion is potentially an expensive activity the feature may be disabled by setting the environment property "com.sun.jndi.ldap.obj.expandGroup" to the string value "false".

Specified by:
isMember in interface java.security.acl.Group
Parameters:
member - The name of the member to be checked.
Returns:
boolean true if membership is confirmed; false otherwise.
Throws:
java.lang.IllegalStateException - The exception is thrown if the group does not represent a group in the directory.

isMember

public boolean isMember(java.lang.String dn)
                 throws javax.naming.NamingException
Checks if the supplied name is a member of the group. Performs LDAP searches to determine membership.

By default, subgroups are also checked. As subgroup expansion is potentially an expensive activity the feature may be disabled by setting the environment property "com.sun.jndi.ldap.obj.expandGroup" to the string value "false".

Parameters:
dn - The distinguished name (RFC 2253) of the member to be checked.
Returns:
boolean true if membership is confirmed; false otherwise.
Throws:
javax.naming.NamingException - The exception is thrown if an error occurs while performing LDAP search.
java.lang.IllegalStateException - The exception is thrown if the group does not represent a group in the directory.

members

public java.util.Enumeration members()
Returns the members of the group. Performs LDAP searches to retrieve the members.

By default, subgroups and their members are also included. As subgroup expansion is potentially an expensive activity the feature may be disabled by setting the environment property "com.sun.jndi.ldap.obj.expandGroup" to the string value "false". When the feature is disabled only the group's direct members are returned.

Specified by:
members in interface java.security.acl.Group
Returns:
Enumeration The list of members of the group. When only the LdapGroupFactory object factory is active then each element in the enumeration is of class Group or Principal. However, when additional object factories are active then the enumeration may contain elements of a different class.
Throws:
java.lang.IllegalStateException - The exception is thrown if the group does not represent a group in the directory.

removeMember

public boolean removeMember(java.security.Principal member)
Removes a member from the group. Performs an LDAP modify to remove the member.

Specified by:
removeMember in interface java.security.acl.Group
Parameters:
member - The name of the member to be removed.
Returns:
boolean true if the removal was successful; false otherwise.
Throws:
java.lang.IllegalStateException - The exception is thrown if the group does not represent a group in the directory.

removeMember

public boolean removeMember(java.lang.String dn)
                     throws javax.naming.NamingException
Removes a member from the group. Performs an LDAP modify to remove the member.

Parameters:
dn - The distinguished name (RFC 2253) of the member to be removed.
Returns:
boolean true if the removal was successful; false otherwise.
Throws:
javax.naming.NamingException - The exception is thrown if an error occurs while performing LDAP modify.
java.lang.IllegalStateException - The exception is thrown if the group does not represent a group in the directory.

getName

public java.lang.String getName()
Retrieves the distinguished name of the group.

Specified by:
getName in interface java.security.Principal
Returns:
String The distinguished name of the group.
Throws:
java.lang.IllegalStateException - The exception is thrown if the group does not represent a group in the directory.

setName

void setName(java.lang.String groupDN,
             javax.naming.directory.DirContext ctx,
             javax.naming.Name name)
Sets the distinguished name of the group. This method is called by LdapGroupFactory.

Parameters:
groupDN - The group's distinguished name.
ctx - An LDAP context.
name - The group's name relative to the context.

toString

public java.lang.String toString()
Creates a string representation of the group.

Specified by:
toString in interface java.security.Principal
Overrides:
toString in class java.lang.Object
Returns:
String A string listing the distinguished name of the group and the contents of the group's attribute set. See BasicAttributes.toString() for details. The name is omitted if the group is not bound in the directory and null is returned if no attributes are available.

getAttributes

javax.naming.directory.Attributes getAttributes()
Retrieves the group's attributes. This method is called by LdapGroupFactory.

Returns:
Attribute The group's attributes.

matches

static boolean matches(javax.naming.directory.Attribute objectClass)
Determines whether the supplied LDAP objectClass attribute matches that of the group. A match occurs if the argument contains the value "GroupOfNames".

Parameters:
objectClass - The non-null objectClass attribute to check against.
Returns:
true if the objectClass attributes match; false otherwise.

isBound

private boolean isBound()

close

public void close()
           throws javax.naming.NamingException
Releases the naming context created by this group. Closes the root naming context if one had been created.

Throws:
javax.naming.NamingException - The exception is thrown if a problem is encountered while closing the naming context.

initializeState

private void initializeState(javax.naming.directory.Attribute objectClass,
                             java.lang.String memberAttrId,
                             java.lang.String memberFilterExpr,
                             java.util.Set members)

initializeBoundState

private void initializeBoundState(java.lang.String groupDN,
                                  javax.naming.directory.DirContext ctx,
                                  javax.naming.Name name,
                                  java.util.Hashtable env,
                                  javax.naming.directory.Attributes attributes)

modifyMember

private boolean modifyMember(java.lang.String member,
                             int mod_op)
                      throws javax.naming.NamingException
Throws:
javax.naming.NamingException

isSubgroupMember

private boolean isSubgroupMember(java.lang.String dn)
                          throws javax.naming.NamingException
Throws:
javax.naming.NamingException

generateRootContextProperties

static java.util.Hashtable generateRootContextProperties(java.util.Hashtable env)