Miscellaneous

Attributes

Because most of the operations on the LDAP directory center around attributes, you need to understand how to use those attributes through the JNDI.

An LDAP entry's attributes are represented by the Attributes interface, whereas individual attributes are represented by the Attribute interface. To create attributes for use in your program, you should use the BasicAttributes and BasicAttribute classes.

Here is an example that creates two attributes, "oc" and "photo", and puts them into an Attributes object.

// Create a multivalued attribute that has four String values
BasicAttribute oc = new BasicAttribute("objectClass", "top");
oc.add("person");
oc.add("organizationalPerson");
oc.add("inetOrgPerson");

// Create an attribute by using a byte array
BasicAttribute photo = new BasicAttribute("jpegPhoto", buf);

// Create the attribute set
BasicAttributes attrs = new BasicAttributes(true);
attrs.put(oc);
attrs.put(photo);

Attribute Names

You identify an attribute through the use of its attribute name, which is sometimes called the attribute identifier or attribute type name. The Directory Operations lesson discusses attribute names, specifically, it covers attribute subclassing, attribute name synonyms, and the syntax for specifying language preferences. These features might not be supported by all LDAP server implementations.

LDAP attribute names are case-insensitive. Thus two attribute names, such as "objectclass" and "objectClass", both would be interpreted to refer to the same attribute. If you are using the BasicAttributes class to represent LDAP attributes, then you should pass true for the ignoreCase parameter to its constructors. Here are some examples.

Attributes attrs1 = new BasicAttributes(true);
Attributes attrs2 = new BasicAttributes("objectClass", "top", true); 

Options

The LDAP v3 allows options to be appended to an attribute name. Each option is preceded by a semicolon character (";"). Options are like attribute subclassing. That is, an attribute named without the option is treated as the superclass of an attribute named with an option. The only option defined by the protocol is binary ( indicated by using the string ";binary"), which means that the attribute's value should be transmitted in binary format (regardless of its actual syntax). This option is reserved for transmitting ASN.1 encoded data (such as certificates: "caCertificate;binary"). Servers that support attribute subclassing may support identification of the attribute without its binary option, but it is best always to include the binary option in the attribute name.

Operational Attributes

The LDAP v3 supports the notion of operational attributes, which are attributes associated with a directory object for administrative purposes. The access control list for an object, for example, is an operational attribute. In DirContext.getAttributes() and DirContext.search(), you can supply null as the list of attributes to return and therefore can specify that all attributes associated with the requested objects be returned. The attributes returned, however, do not include operational attributes. To retrieve operational attributes, you must name them explicitly.

Attribute Values

An LDAP attribute can have a single value or multiple, unordered values. Whether an attribute is allowed to have more than one value is dictated by the attribute's definition in the directory's schema. Both single and multivalued attributes are represented in the JNDI as an Attribute. In the previous example, a multivalued attribute and a single-valued attribute are created.

The JNDI is very flexible in how attribute values can be represented because such values are declared as java.lang.Object. When you use the JNDI to access or update attributes stored in a particular directory, the types of the attribute values depend on the directory and to some extent, on the corresponding service provider. For the LDAP directory, Sun's LDAP provider represents attribute values as either java.lang.String or byte[]. byte arrays are used to represent attribute values with nonstring attribute syntaxes. Strings are used to represent the values of all other syntaxes.

For an arbitrary attribute, no programmatic way is available to determine whether its syntax is nonstring. Manual ways are available, of course, and involve looking up the attribute and its syntax in documents such as RFC 2256. The LDAP service provider has a built-in list of attribute names that it knows contain nonstring values and allows clients to add to that list. The following table gives that built-in list.

Attribute Name	Attribute OID
All attribute names containing the ";binary" option.
photo	0.9.2342.19200300.100.1.7
personalSignature	0.9.2342.19200300.100.1.53
audio	0.9.2342.19200300.100.1.55
jpegPhoto	0.9.2342.19200300.100.1.60
javaSerializedData	1.3.6.1.4.1.42.2.27.4.1.8
thumbnailPhoto	1.3.6.1.4.1.1466.101.120.35
thumbnailLogo	1.3.6.1.4.1.1466.101.120.36
userPassword	2.5.4.35
userCertificate	2.5.4.36
cACertificate	2.5.4.37
authorityRevocationList	2.5.4.38
certificateRevocationList	2.5.4.39
crossCertificatePair	2.5.4.40
x500UniqueIdentifier	2.5.4.45

When you read one of these attributes from the LDAP directory, its value will be of type byte[].

Specifying Additional Nonstring Attributes

If your program uses an attribute whose value should be returned as a byte array but the attribute's name is not on this list, then you need to add the name to the list of nonstring attributes. You do this by using the "java.naming.ldap.attributes.binary" environment property. Its value is a string of space-separated attribute names.

For example, the following environment property setting informs the LDAP provider that the values of the attributes named "mpegVideo" and "mySpecialKey" are to be returned as byte arrays:

env.put("java.naming.ldap.attributes.binary", "mpegVideo mySpecialKey");

Suppressing the Return of Attribute Values

The LDAP v3 allows you to specify that only attribute type names (and not attribute values) be returned. To do this by using the JNDI, you set the "java.naming.ldap.typesOnly" environment property. This property affects DirContext.getAttributes() and DirContext.search(). When you specify that objects are to be returned (by passing true to SearchControls.setReturningObjFlag()) and then you invoke search(), this property is ignored because attribute values are required to generate the object.

Here's an example that gets a list of an entry's attribute names.

// Indicate that you want only the type names
env.put("java.naming.ldap.typesOnly", "true");

// Create initial context
DirContext ctx = new InitialDirContext(env);

// Get the attributes
Attributes attrs = ctx.getAttributes("cn=Ted Geisel, ou=People");

This example produces the following output.

{sn=sn: No values, 
 objectclass=objectclass: No values, 
 jpegphoto=jpegphoto: No values, 
 mail=mail: No values, 
 facsimiletelephonenumber=facsimiletelephonenumber: No values, 
 telephonenumber=telephonenumber: No values, cn=cn: No values}

Miscellaneous