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

The methods available to class SearchDescriptor

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

• void readSearchDescriptor(java.io.InputStream input)
• void readSearchDescriptor(java.io.Reader input)

The XML used would look like:

<dsml>
   <search base="o=javaworld.com" scope="subtree" 
filter="(uid=stigger)">
   </search>
</dsml>

Exporter uses the SearchDescriptor to determine what information to get from the directory server. To invoke exporting, Exporter includes two method calls:

• void export(java.io.OutputStream output, boolean serverSchema, boolean importPolicy)
• void export(java.io.Writer output, boolean serverSchema, boolean importPolicy)

Both methods require two flags, although we yielded the same result regardless of the their settings (no documentation on the flags’ meaning was forthcoming).

Consumers (importing)

Castor can consume level 1 documents. The org.exolab.castor.dsml.Importer class puts directory information into a directory server.

Importer uses the base constructor and defines three methods for importing DSML:

• void importDocument(java.io.InputStream stream)
• void importDocument(org.xml.sax.Parser parser, org.xml.sax.InputSource input)
• void importDocument(java.io.Reader reader)

These methods take the DSML that you want to import. In addition to the DSML, you can also define an ImportDescriptor. The ImportDescriptor defines the location to where you are importing and configures restrictions on deleting or updating attributes. The following methods, which take XML as input, are used to set up the ImportDescriptor:

• void readImportDescriptor(java.io.InputStream input)
• void readImportDescriptor(java.io.Reader input)

The XML used with the readImportDescriptor() method would look something like this:

<dsml>
  <import-policies>
     <import-policy dn="o=javaworld.com" delete-empty="true"
                    replace-attr="true" refresh-only="false"/>
  </import-policies>
</dsml>

The example

In a directory server, it’s useful to have users separated into groups. As such, in our example we will create a dynamic way to distribute our users into groups through a Web interface. By retrieving a list of all the users in our organization, we can select the users we want to be in a group and load the new group into our directory server.

This example will illustrate two uses of DSML: data extraction for presentation purposes and directory-service entry creation with XSL and Castor.

To accomplish our task, we’ll employ a servlet that uses the Castor API to retrieve data from a directory server. Then we will transform the resulting DSML into HTML using XSL.

Retrieve a list of users

The servlet below — DisplayUser.java — retrieves DSML from a DirectoryServer using Castor’s Exporter class. It then strips the namespace off the DSML because the Xalan processor cannot handle namespaces in source XML. Finally, the servlet uses XSL to style the DSML in order to create HTML. Figure 1 shows a static HTML page used to perform the search of a directory server.

Here’s the DisplayUser.java servlet’s code:

import java.io.*;
import javax.servlet.*;
import javax.servlet.http.*;
import javax.naming.directory.InitialDirContext;
import javax.naming.Context;
import netscape.ldap.LDAPConnection;
import java.util.Hashtable;
import org.exolab.castor.dsml.Exporter;
import org.exolab.castor.dsml.jndi.JNDIExporter;
import org.exolab.castor.dsml.SearchDescriptor;
import RemoveNamespace;
public class DisplayUser extends HttpServlet
{
  InitialDirContext ctx;
  public void init()
  {
      LDAPConnection conn;
      Hashtable env;
      try
      {
        //connect to LDAP Server
        env = new Hashtable();
        env.put(Context.INITIAL_CONTEXT_FACTORY,
"com.sun.jndi.ldap.LdapCtxFactory");
        env.put(Context.SECURITY_AUTHENTICATION, "simple");
        env.put(Context.PROVIDER_URL, "ldap://localhost:389");
        env.put(Context.SECURITY_PRINCIPAL, "cn=Directory Manager");
        env.put(Context.SECURITY_CREDENTIALS, "password");
        ctx = new InitialDirContext(env);
      }
      catch(Exception ex)
      {
        ex.printStackTrace();
      }
   }
   public void doPost(HttpServletRequest req, HttpServletResponse res)
   {
      try
      {
        RemoveNamespace remover = new RemoveNamespace();
        Search search = new Search(ctx);
        StringBuffer xsl = new StringBuffer();
        String results = "";
        String dsml = "";
        //get parameters
        String attributeName = req.getParameter("attributeName");
        String searchValue = req.getParameter("searchValue");
        //search directory
        results = search.doSearch(attributeName,searchValue);
        //remove the namespace from dsml
        dsml = remover.remove(results);
        //style search results
        XSLUtil xslUtil = new XSLUtil();
        File file = new File("DisplayUser.xsl");
        String html = xslUtil.styleXSL(file, dsml);
        PrintWriter out = res.getWriter();
        res.setContentType("text/html");
        out.write(html.toString());
      }
      catch(Exception e)
      {
        e.printStackTrace();
      }
   }
   public String doSearch(String attribute, String searchValue)
   {
      Exporter exporter = new JNDIExporter(ctx);
      SearchDescriptor sd = new SearchDescriptor();
      StringWriter writer = new StringWriter();
      try
      {
        //configure the search descriptor
        //set the domain name to search
        sd.setBaseDN("o=javaworld.com");
        //set the scope of the search
        sd.setScope(3);  //scope 1 = base, 2 = onelevel, 3 = subtree
        //setFilter for Directory Server
        //in our case the attribute is departmentnumber
        sd.setFilter(attribute+"="+searchValue);
        //assign search descriptor
        exporter.setSearchDescriptor(sd);
        //perform the search of the Directory Server
        exporter.export(writer,false,true);
      }
      catch(Exception e)
      {
        e.printStackTrace();
      }
      //return String (dsml) of search results
      return writer.toString();
   }
}

Next, let’s take a look at the XSL code used to transform the DSML pulled from LDAP into HTML:

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0"
xmlns:xsl="
xmlns:dsml="
<xsl:template match="/">
  <html>
   <head><title>Search Results</title></head>
   <body>
    <form action="CreateGroup" method="post">
     <table class="legacyTable" border="1" width="100%">
      <tr>
       <th> Employee Name</th>
       <th> User ID</th>
       <th>E-Mail</th>
       <th>Phone</th>
       <th>Fax</th>
       <th>Update</th>
      </tr>
      <xsl:for-each select="dsml/directory-entries/entry">
      <tr>
        <td>
         <xsl:value-of select="attr[@name="cn"]/value"/>
        </td>
        <td>
         <xsl:value-of select="attr[@name="uid"]/value"/>
        </td>
        <td>
         <xsl:value-of select="attr[@name="mail"]/value"/>
        </td>
        <td>
         <xsl:value-of select="attr[@name="telephonenumber"]/value"/>
        </td>
        <td>
         <xsl:value-of
select="attr[@name="facsimiletelephonenumber"]/value"/>
        </td>
        <td>
         <xsl:element name="input">
          <xsl:attribute name="type">checkbox</xsl:attribute>
          <xsl:attribute name="name">member</xsl:attribute>
          <xsl:attribute name="value"><xsl:value-of
select="@dn"/></xsl:attribute>
         </xsl:element>
        </td>
       </tr>
       </xsl:for-each>
     </table>
     <hr width="100%" noshade="true"></hr>
     <table class="legacyTable">
      <tr>
       <td>
        Group Name:
        <input type="text" size="20" name="GroupName"/>
       </td>
       <td>
        <input type="submit" value="Submit"/>
       </td>
       <td>
        <input type="reset" value="Reset"/>
       </td>
      </tr>
     </table>
    </form>
   </body>
  </html>
  </xsl:template>
</xsl:stylesheet>

In Figure 2, we see the HTML that results after the XSL styles the DSML.

Create a group in DSML

Next, the CreateGroup.java servlet will take the HTTPRequest and format the parameters into XML. For example:

CreateGroup?member=uid=lpoe,ou=People&member=uid=mball,ou=People&GroupName=Accountants

would be translated into:

  <data>
    <member>uid=lpoe,ou=People</member>
    <member>uid=mball,ou=People</member>
    <GroupName>Developers</GroupName>
  </data>

The XSL stylesheet below then takes the XML and styles it into DSML:

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0"
xmlns:xsl=">
<xsl:template match="/">
<xsl:element name="dsml">
  <xsl:element name="directory-entries">
   <xsl:element name="entry">
     <xsl:attribute name="dn">cn=<xsl:value-of
select="data/GroupName"/>,ou=Groups,o=aici.com</xsl:attribute>
     <xsl:element name="objectclass"><xsl:element
name="oc-value">top</xsl:element><xsl:element
name="oc-value">groupofuniquenames</xsl:element></xsl:element>
     <xsl:element name="attr">
      <xsl:attribute name="name">cn</xsl:attribute>
      <xsl:element name="value">
       <xsl:value-of select="data/GroupName"/>
      </xsl:element>
     </xsl:element>
     <xsl:element name="attr">
      <xsl:attribute name="name">uniquemember</xsl:attribute>
      <xsl:for-each select="data/member">
       <xsl:element name="value"><xsl:value-of
select="."/>,o=javaworld.com</xsl:element>
      </xsl:for-each>
     </xsl:element>
    </xsl:element>
  </xsl:element>
</xsl:element>
</xsl:template>
</xsl:stylesheet>

The XSL stylesheet above creates the following DSML:

<?xml version="1.0" encoding="UTF-8"?>
<dsml>
<directory-entries>
  <entry dn="cn=Developers,ou=Groups,o=aici.com">
   <objectclass>
    <oc-value>top</oc-value>
    <oc-value>groupofuniquenames</oc-value>
   </objectclass>
   <attr name="cn">
    <value>Developers</value></attr>
   <attr name="uniquemember">
    <value>uid=LDPoe,ou=People,o=aici.com</value>
    <value>uid=MWBall,ou=People,o=aici.com</value>
   </attr>
  </entry>
</directory-entries>
</dsml>

Now that we’ve created the DSML, we can load it into the directory server using the Importer class:

public String doCreate(String dsml)
  {
      Importer importer = new JNDIImporter(ctx);
      PrintImportListener printer;
      StringWriter out = new StringWriter();
      try
      {
        StringWriter writer = new StringWriter();
        //set writer
        printer = new PrintImportListener( new PrintWriter( out ) );
        //set event listener
        importer.setImportEventListener( printer );
        //set the import policy
        importer.readImportDescriptor(new FileReader("import.xml"));
        //insert records into LDAP
    importer.importDocument(new StringReader(dsml));
      }
      catch(Exception e)
      {
        e.printStackTrace();
      }
      return out.toString();
  }

We can now confirm that the group entry, as well as its two new members, was added to LDAP, as illustrated in Figure 3.

Taking from the example general concepts such as data extraction and object generation, we can open up a world of opportunities to use and manage the data stored in your directory-service.

Conclusion

Directory services are powerful tools common in most of today’s architectures. They store information about people, hardware, and even objects. But as directory-service use becomes more pervasive, a standard way to manipulate the information inside of them and transfer data between them becomes necessary. By taking advantage of the power of XML, DSML provides a powerful interface into directory servers. As XML tools become more and more common, using them to access DSML will become easier, and your directory servers will become more useful and dynamic.