Creating Directory Entries (Java Enterprise in a Nutshell)

6.11. Creating Directory Entries

So far, we have been accessing directory entries that are already present in the directory. Now it's time to learn how to create directory entries of our own, using the createSubcontext() method of DirContext. As we discussed earlier, when you create a subcontext of a Context object, the service provider controls the type of object that is created. With a DirContext, this is not the case; you actually have complete control over the type of object you create with createSubcontext() (within the constraints of the directory schema, of course).

As I noted earlier, the object class definition determines the type of a directory entry, and the entry stores its object class as an attribute. So, in order to create a directory entry, we must pass the object class attribute and some other attributes into the parent entry's createSubcontext() method.

Most directories require that you specify attributes for at least the object class definition (e.g., "objectclass=") and key attribute (e.g., common name, "cn=") of a directory entry. Often directories require that you specify more attributes than just these. The minimum set of attributes necessary for creating a directory entry are called the mandatory attributes. They are mandatory because if you do not specify them, createSubcontext() throws an InvalidAttributesException. Other attributes that are not required, but that add more useful data to the entry, are called extended attributes.

Say we have a reference to a DirContext called orgUnit (where this directory entry lives in an LDAP v3 directory), and we want to create a user entry that is a child of orgUnit to represent the network user Billy Roberts. Here's how we can create a user entry for Billy:[3]

[3] Note that I didn't implement a "create directory entry" command for NamingShell because most public-access LDAP servers don't allow you to create new entries.

DirContext orgUnit = ... ;     // Created somewhere else in the program

BasicAttributes mandatory = new BasicAttributes("cn", "Billy");
BasicAttribute objectclass = new BasicAttribute("objectclass", "user");
BasicAttribute surname = new BasicAttribute("surname", "Roberts");
mandatory.put(objectclass);
mandatory.put(surname);

orgUnit.createSubcontext("cn=Billy", mandatory);

Note that the createSubcontext() method of DirContext resembles the createSubcontext() method of Context; the only difference is the addition of an Attributes parameter. In this example, we create a BasicAttributes object and put three attributes in it. While all the attribute values here are String objects (because that's what an LDAP directory requires), the JNDI API allows you to specify any kind of object as an attribute value.

In this example, orgUnit represents an organizational unit, under which Billy Roberts' newly created user entry resides. In an LDAP directory, an organizational unit is an object class definition that represents a division of a company, and a user is an object class definition that represents a person who uses network resources. It is natural that a division of a company can contain a person, but it doesn't necessarily work in the opposite direction; it doesn't make sense that a user can contain an organizational unit. The LDAP schema dictates these rules and also specifies the values we can use for the "objectclass" attribute (which is where "user" came from in the example code).

When you are creating your own directory entries, be sure to consult the schema for the directory you are using. If you attempt to create a type of entry that cannot reside under a particular DirContext, or you specify an incorrect value for the "objectclass" attribute, createSubcontext() throws an exception.