ATG Repository Guide

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 would have attributes named 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 a ATG LDAP repository and an LDAP directory, the repository’s item descriptors would 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. We might want to make the corresponding Profile property required, so that when new profiles are created, the user password is required to be specified. In addition, the inetorgPerson object class schema contains some attributes we may not care about in our Web application, such as seealso or x500uniqueidentifier. We wouldn’t want to expose these unnecessary attributes 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 ATG profile repository, you would want the name of the Profile property to be password, and its type to be String. An LDAP attribute such as age would be represented in Java as a String. You would probably want the type of the Profile age property to be an Integer. In addition, you would probably want to provide default values for some of the properties.

The LDAP repository allows you to specify an item descriptor with all of the capabilities mentioned above. To demonstrate, the following is a portion of the sample XML template that describes our user item descriptor. Pieces of the item descriptor definition have been omitted for clarity; these will be discussed later on. You can see the complete Sample LDAP Repository Definition File later in this chapter. All of the 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 -->
  <object-class>top</object-class>
  <object-class>person</object-class>
  <object-class>organizationalPerson</object-class>
  <object-class>inetorgPerson</object-class>

  <!-- properties -->
  <property name="login" ldap-name="uid" data-type="string" required="true"/>
  <property name="password" ldap-name="userpassword" data-type="string"
    required="true"/>
  <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"
    required="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 -->
  ...

</item-descriptor>

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 that 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:

In addition, the user item descriptor exposes only those attributes that we care about, 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.

Note that although the 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 will ignore all but one of the returned values. It is not specified which of the values will be 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, since 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.