![]() ![]() ![]() ![]() |
Miscellaneous |
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
interface, while 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 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 Directorylesson 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
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()and DirContext.search()
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()or SearchControls.setReturningAttributes()
, 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()and DirContext.search()
methods. When invoking search(), if you've specified that objects are to be returned (by passing "true" to SearchControls.setReturningObjFlag()
), 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}
![]() ![]() ![]() ![]() |
Miscellaneous |