DSML gives you the power to access your LDAP information as XML

The Directory Service Markup Language adds XML functionality to your directory services

By Lanette Poe and Michael Ball, JavaWorld.com, 11/10/00

DSML, in conjunction with technologies like XSL and EJB, provides a unique way to solve many business problems, such as supply chain management and customer support. The technology was developed out of work done by Bowstreet and completed by the DSML Working Group; the latter submitted the technology to the W3C and OASIS standards groups in December 1999.

Numerous products now support DSML, including Sun's recently released DSML Service Provider 1.2 technology, released for use with J2EE 1.2, and Exolab's Castor API, which provides services to extract information from LDAP as DSML, as well as . With the DSML Service Provider, which implements the javax.naming.directory.DirContext interface, you can access a DSML document, manipulate and update its contents by using the JNDI APIs, and then re-export the contents in DSML format.

In this article, we will discuss how to create dynamic content and manipulate a directory server with DSML. We will do this using Exolab's Castor, servlets, and XSL. We will not cover information on how to use XSL or servlets, but for more information you can refer to Michael Ball's earlier article, "XSL Gives Your XML Some Style" (JavaWorld, June 30, 2000).

Download the source code associated with this article.

The DSML specification

The DSML specification provides both a DTD and a schema for reference (see Resources for download information).

The DSML namespace is: http://www.dsml.org/DSML; it should be referenced in all your DSML documents, as in:

<dsml:dsml xmlsn:dsml:"http://www.dsml.org/DSML"/>

A DSML document can describe directory entries, a directory structure, or both. The root node in a DSML document is always dsml. Children can be directory-schema and/or directory-entries.

<dsml:dsml xmlns:dsml=http://www.dsml.org/DSML>
<dsml:directory-schema>
...
</dsml:directory-schema>
<dsml:directory-entries>
...
</dsml:directory-entries>
</dsml>

A directory-entries node has one or more directory-entry nodes as its children. Each of these directory-entry nodes contains the object class information as well as attributes for the information, as seen below:

<dsml:directory-entries>
  <dsml:directory-entry dn="uid=mball, ou=consultant, 
o=sark.com,c=us">
    <dsml:objectclass>
      <dsml:oc-value>top</dsml:oc-value>
      <dsml:oc-value>person</dsml:oc-value>
      <dsml:oc-value>organizationalPerson</dsml:oc-value>
      <dsml:oc-value>inetOrgPerson</dsml:oc-value>
    </dsml:objectclass>
    <dsml:attr 
name="sn"><dsml:value>Ball</dsml:value></dsml:attr>
    <dsml:attr 
name="uid"><dsml:value>mball</dsml:value></dsml:attr>
    <dsml:attr
name="mail"><dsml:value>mball@sark.com</dsml:value></dsml:attr>
    <dsml:attr 
name="givenname"><dsml:value>Michael</dsml:value></dsml:attr>
    <dsml:attr name="cn"><dsml:value>Michael 
Ball</dsml:value></dsml:attr>
  </dsml:entry>
</dsml:directory-entries>

If an attribute is multivalued, there would be many <dsml:value> nodes under the <dsml:attr> node.

The directory-schema node contains information about the object classes and the attributes. As an example, take a look at this sample XML pulled from the DSML specification:

<dsml: class
    id="person"
    superior="#top"
    type="structural">
  <dsml:name>person</dsml:name>
  <dsml:description>...</dsml:description>
  <dsml:object-identifier>2.5.6.6</object-identifier>
  <dsml:attribute ref="#sn" required="true"/>
  <dsml:attribute ref="#cn" required="true"/>
  <dsml:attribute ref="#userPassword" required="false"/>
  <dsml:attribute ref="#telephoneNumber" required="false"/>
  <dsml:attribute ref="#seeAlso" required="false"/>
  <dsml:attribute ref="#description" required="false"/>
</dsml:class>

Using DSML with Exolab's Castor API

Exolab, according to its homepage, works on the development of open source enterprise software projects, of which the Castor API is one. DSML is a subset of Castor. Be aware that the documentation for the DSML portion of Castor is scarce. With that in mind, we'll try to highlight the basic functionality of the API.

Note: In this article, we used Castor version 0.8.5.

Castor's DSML API

Castor can import and export directory information. Meanwhile, the DSML specification describes producers (used for exporting) and consumers (used for importing). Both of these services are divided into types 1 and 2 based on the document levels that they can handle. The four document levels are:

• Level 1: A document containing no schema information, just directory entries
• Level 2: A document containing directory entry information and a link to an external schema
• Level 3: A document containing only a directory schema
• Level 4: A document containing a directory schema and directory entries

A type 1 producer can handle the level 1 documents, while a type 2 producer can handle document levels 2, 3, and 4.

Meanwhile, a type 1 consumer must handle all four document levels. A type 2 consumer must handle all four document levels and make use of schema information.

Castor supports type 1 producers and consumers.

Producers (exporting)

Castor can provide level 1 and level 4 documents. The class org.exolab.castor.dsml.Exporter retrieves directory information from a directory server.

The Exporter class uses a org.exolab.castor.dsml.SearchDescriptor to define search parameters. The SearchDescriptor can be configured by calling setters on it. Table 1 defines some of the important methods available in the SearchDescriptor class.

To use XML to define the search configuration, Exporter employs the following methods: