Previous | Next | Trail Map | Tips for LDAP Users | Miscellaneous

Attributes

Because most of the operations on the LDAP directory center around attributes, it is important to understand how to use them through the JNDI.

An LDAP entry's attributes are represented by the Attributes(in the API reference documentation) interface, while individual attributes are represented by the Attribute(in the API reference documentation) interface. To create attributes for use in your program, you should use the BasicAttributes(in the API reference documentation) and BasicAttribute(in the API reference documentation) classes. Here is an example that creates two attributes, oc and photo, and puts them into an Attributes object.

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

// Create a binary attribute
BasicAttribute photo = new BasicAttribute("jpegPhoto", buf);

// Create 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 (in the Basics trail) lesson contains a section that discuss 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. For example, the attribute names "objectclass" and "objectClass" both refer to the same attribute. So, if you are using the BasicAttributes(in the API reference documentation) class to represent LDAP attributes, 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

LDAP v3 allows case-insensitive options to be appended to an attribute name. Each option is preceded by a semi-colon 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, which means that the attribute's value should be transmitted in binary format (regardless of its actual syntax). For example, to return the value of the attribute "caCertificate" in binary format, you would use the attribute name "caCertificate;binary". See the discussion below for more discussion on attribute values.

Operational Attributes

The LDAP v3 supports the notion of operational attributes, which are attributes associated with a directory object for administrative purposes. An example of operational attributes is the access control list for an object. In the DirContext.getAttributes()(in the API reference documentation) and DirContext.search()(in the API reference documentation) methods, you can specify that all attributes associated with the requested objects be returned by supplying null as the list of attributes to return. The attributes returned do not include operational attributes. In order 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 specified by the attribute's definition in the directory's schema. Both single and multivalued attributes are represented in the JNDI using the Attribute interface. In the example shown previously, a multivalued attribute and a single valued attribute are created.

The JNDI is very flexible in how attribute values can represented because they are declared as java.lang.Object. When you use the JNDI to access or update attributes stored in a particular directory, the objects that represent attribute values depend on the directory, and to some extent 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 that have "binary" attribute syntaxes. For attributes of all other syntaxes, the values are represented as strings.

For an arbitrary attribute, there is no programmatic way to determine whether its syntax is binary. There are manual ways to do this of course, by looking up the attribute and its syntax in documents such as RFC 2256. Therefore, the LDAP service provider has a built-in list of attribute names that it knows to contain binary values, and allows clients to add to that list. Here is the built-in list:

Attribute Name Attribute OID
All attribute names containing the ";binary" tag.  
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
javaSerializedObject 1.3.6.1.4.1.42.2.27.4.1.2
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 Binary Attributes

If your program uses an attribute whose value should be returned as a byte array but is not on this list, you can do one of two things. If you are requesting the attribute explicitly, for example, by naming it in the attributesToReturn parameter to DirContext.getAttributes()(in the API reference documentation) or SearchControls.setReturningAttributes()(in the API reference documentation) , you may use the ";binary" option with the attribute name. For example, if you want to get the value of the attribute "mySpecialKey" back as a byte array, you would use the name "mySpecialKey;binary".

Note: The Netscape Directory Server 3.11 supports the ";binary" option only for a limited set of attributes. For all other attributes, it treats ";binary" as part of the attribute name and fails to find the attribute.

If you are not requesting the attribute specifically, then you need to add the attribute's name to the list of binary 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 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");

Note: Version 1.0.1 and earlier releases of the LDAP provider do not treat the letter casing of attribute names in the java.naming.ldap.attribute.binary environment property correctly. To work around this, you need to specify the attribute names in lowercase.

Suppressing the Return of Attribute Values

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

Here's an example that gets a list of the names of the attributes of an entry:

// Indicate that we only want 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");

It 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}


Previous | Next | Trail Map | Tips for LDAP Users | Miscellaneous