The repository items in an LDAP repository are defined by one or more item descriptors. Each item descriptor defines the properties that a repository item can have. There is a natural mapping between a repository item descriptor and an object class of an LDAP directory. For example, a repository might include a user item descriptor that describes people, with properties such as login, password, firstName, lastName, phone, and so on. In the LDAP directory, this item descriptor corresponds to an object class such as inetorgPerson. The object class named inetorgPerson has attributes uid, userpassword, givenName, sn, and telephonenumber, corresponding to the properties of the item descriptor. In other words, the user item descriptor is analogous to the inetorgPerson object class schema.

Mapping an LDAP Schema onto an Item Descriptor

In the most straightforward mapping between an Oracle ATG Web Commerce LDAP repository and an LDAP directory, the repository’s item descriptors have the same required and optional properties as the corresponding object classes of the LDAP directory. However, it is often desirable for the item descriptor to present a slightly different view of the LDAP directory schema. For example, the LDAP userpassword attribute is not required for the inetorgPerson object class. You might want to make the corresponding Profile property required, so when new profiles are created, the user password must be specified. Also, the inetorgPerson object class schema contains some attributes that might not be important to your Web application, such as seealso or x500uniqueidentifier. Unnecessary attributes should not be exposed as properties in the repository item descriptor.

Similarly, although each attribute in the LDAP directory already has a schema associated with it, it is often desirable for the repository’s item descriptors to present a somewhat different view of the attribute schema. For example, the password attribute in the LDAP schema has the name userpassword, and a Binary syntax (in other words, it is represented in Java as byte[]). In the Oracle ATG Web Commerce profile repository, the name of the Profile property should be password, and its type should be String. An LDAP attribute such as age is represented in Java as a String. The Profile’s age property type should probably be an Integer. Also, you probably want to provide default values for some of the properties.

The LDAP repository lets you specify an item descriptor with all the capabilities previously mentioned. To demonstrate, the following is a portion of the sample XML template that describes the user item descriptor. Pieces of the item descriptor definition are omitted for clarity; these are discussed later on. You can see the complete Sample LDAP Repository Definition File later in this chapter. All tags you can use in the XML file that defines the LDAP repository are described in the LDAP Repository Definition Tag Reference in this chapter.

<item-descriptor name="user">

  <!-- special properties -->

  <!-- object classes -->

  <!-- properties -->
  <property name="login" ldap-name="uid" data-type="string" required="true"/>
  <property name="password" ldap-name="userpassword" data-type="string"
  <property name="lastName" ldap-name="sn" data-type="string" required="true"/>
  <property name="firstName" ldap-name="givenName" data-type="string"/>
  <property name="names" ldap-name="cn" data-type="string" multi="true"
  <property name="email" ldap-name="mail" data-type="string"/>
  <property name="phone" ldap-name="telephonenumber" data-type="string"/>
  <property name="fax" ldap-name="facsimiletelephonenumber" data-type="string"
    default="(617) 555-1211"/>
  <property name="department" ldap-name="ou" data-type="string"/>
  <property name="title" data-type="string"/>
  <property name="employeeNumber" data-type="long"/>

  <!-- new item creation -->


The object-class tags specify all the object class values corresponding to the given item descriptor. If the object class has ancestor object classes, they must all be specified, as demonstrated above. The object class information is required so when a new item is created for the given item descriptor and added to the repository, the corresponding LDAP entry is created with the given object class values. Thus, for example, if an item is created in the context of the user item descriptor, the new LDAP directory entry has objectclass attribute values of top, person, organizationalPerson, and inetorgPerson.

The LDAP repository definition uses <property> tags to map Profile properties to LDAP attributes. Each such <property>tag describes a property descriptor of its item descriptor. The <property>tags in the example above demonstrate that:

  • Repository item property names can be different from LDAP attribute names. For example, the lastName property in the item descriptor maps to the sn attribute in the LDAP directory schema. If the ldap-name tag attribute is not specified, the repository item property name and the LDAP attribute name are the same.

  • Repository item property types can be different from JNDI service provider types. For example, userpassword is exposed as a binary type by Oracle’s LDAP service provider, but is a String property in the repository; employeeNumber is a String in Oracle’s LDAP service provider, but a Long in the repository.

  • Repository item properties can have default values. For example, the fax property has a default value of (617) 555-1211.

Also, the user item descriptor exposes only those attributes that are meaningful, and promotes some of the optional attributes into required ones. For example, the password attribute is optional in LDAP, but required in the Profile repository item.

Although attributes such as givenName and sn are multi-valued in the LDAP directory, they are exposed as single-valued properties in the repository. When getting the values for these properties, the LDAP repository ignores all but one of the returned values. It is not specified which of the values are returned. On the other hand, the LDAP repository item’s names property is multi-valued, and corresponds to the LDAP directory’s multi-valued cn attribute; in this case, the attribute value is returned as a String array.

For all of this to work, the repository item descriptor must not violate the LDAP directory schema. For example, because cn is a required attribute for the inetorgPerson class, one of the properties specified in the item descriptor must map to the cn attribute, and it must be required. As another example, the item descriptor cannot contain a property that does not correspond to an LDAP attribute. That is, the ldap-name tag attribute value must be a legal LDAP attribute name. The LDAP repository does no checking to ensure that the item descriptor conforms to the LDAP schema. If the schema is violated, a runtime exception (an object schema violation) is thrown by JNDI.