Modifying Directory Entries (Java Enterprise in a Nutshell)

6.10. Modifying Directory Entries

Modifying the attribute values of a directory entry involves using the modifyAttributes() method of DirContext. One variant of this method takes the name of a directory entry, a modification type, and an Attributes object that contains modified Attribute objects, while another variant takes a name and an array of javax.naming.directory.ModificationItem objects. A ModificationItem encapsulates a modified Attribute object and a modification type.

The only part of this operation that warrants much explanation is the creation of modified Attribute objects. The javax.naming.directory.BasicAttributes and javax.naming.directory.BasicAttribute classes implement the Attributes and Attribute interfaces, respectively. These are the classes you'll typically use to create modified attribute values.

For example, let's say we want to remove the phone number "303 444 6633" from a user entry's "telephonenumber" attribute and replace it with the new number "520 765 4321." In the following code, we create two BasicAttributes objects, newNumber and oldNumber, and use them in calls to modifyAttributes():

DirContext user ... ;     // Created somewhere else in the program

BasicAttribute newAttr = new BasicAttribute();
newAttr.add("telephonenumber", "520 765 4321");
BasicAttributes newNumber = new BasicAttributes();
newNumber.put(newAttr);

BasicAttributes oldNumber = 
  new BasicAttributes("telephonenumber", "303 444 6633");

user.modifyAttributes("", DirContext.REMOVE_ATTRIBUTE, oldNumber);
user.modifyAttributes("", DirContext.ADD_ATTRIBUTE, newNumber);

In this code, we use two different techniques to create BasicAttributes objects. For newNumber, we first create a new BasicAttribute and add a "telephonenumber" attribute to it. Then we create a new BasicAttributes object and put the BasicAttribute in it. With oldNumber, we use the convenience constructor of BasicAttributes to accomplish the same task in one line of code.

Now we use the two BasicAttributes objects in two calls to modifyAttributes(), one to remove the old number and one to add the new. DirContext defines three constants we can use to specify the type of modification we are doing: ADD_ATTRIBUTES, REMOVE_ATTRIBUTES, andREPLACE_ATTRIBUTES. With any of these types, modifyAttributes() uses the ID of each Attribute object to determine which attribute to modify by adding, removing, or replacing attribute values. The net result of our two calls is that the old number is replaced with the new number. Of course, we could have done this with one call to modifyAttributes() if we had used the REPLACE_ATTRIBUTES modification type.

The following code shows how to make the same change using the variant of modifyAttributes() that takes an array of ModificationItem objects:

ModificationItem[] mods = new ModificationItem[2];
mods[0] = new ModificationItem(DirContext.REMOVE_ATTRIBUTE,
  new BasicAttribute("telephonenumber", "303 444 6633"));
mods[1] = new ModificationItem(DirContext.ADD_ATTRIBUTE,
  new BasicAttribute("telephonenumber", "520 765 4321"));
user.modifyAttributes("", mods);

Again, this change could also have been done with a single ModificationItem, using REPLACE_ATTRIBUTES.

Note that the examples here do not reflect any particular directory. In order to change a "telephonenumber" attribute value for a particular directory, you need to consult the schema of that directory for the appropriate attribute type and syntax definitions.

Note also that we have only discussed modifying existing attribute values, not adding new attributes altogether. The reason is that adding new attribute IDs requires modifying the schema, or type system, of a directory. JNDI supports schema access and modification, but the details on how to do so are beyond the scope of this chapter.