LDAP and LDAP Directory Search
LDAP is a hierarchical way of storing data. It's commonly used by system administrators to store system and user information. LDAP stores data in a directory structure similar to the Unix file system. The basic unit of information in a directory is an entry. An entry has attributes, each of which has a type and one or more values. Figure 2 shows how employee information may be represented in LDAP.

In Figure 2, the top entry is an organization that has attri- butes dc=whitehorn, dc=com. Note that for the same attribute type dc, you can have more than one value. Under the organization entry you can have children, which are also entries. For example, location newyork and location toronto are both child entries of organization. To identify an entry uniquely, a DN (distinguished name) is used. DN is similar to the concept of a primary key in a database. In this example, the DN of John Doe is represented as:

Uid=100012, ou=Employee,
dc=newyork,dc=whitehorn,dc=com

Inside the John Doe entry you'll find other attributes such as lastName, firstName, phone, and e-mail.

An LDAP search operation is used to search a directory and retrieve individual directory entries. The LDAP search operation has eight parameters. I'll describe only three of them here, which should be sufficient for a simple query. (Refer to the links in the Resources section to learn more about LDAP searches.)

1. Search Base: This indicates the top of the tree where you want to start the search from. It's expressed in the form of a DN.
2. Attributes: Similar to the Select clause in the SQL, this is a list of attributes to be returned for each matching entry.
3. Search Filter: An expression that describes the types of entries to be returned. It's similar to the Where clause in SQL. A filter can be in the following form:

Querying LDAP In Java Code
In Java you can use Java Naming and Directory Interface s(JNDI) to do a directory search on the LDAP server. JNDI is an API that provides naming and directory functionality to applications written using Java. JNDI is included in the Java 2 SDK, v1.3, and later releases. If you're using earlier Java versions, you'll need to include the JNDI extension package in your classpath.

JNDI is defined to be independent of any specific directory service implementation. To use LDAP as the directory ser-vice implementation, add ldapbp.jar, ldap.jar, and providerutil.jar to your classpath to access the LDAP service provider classes. You can download the LDAP service provider release from http://java.sun.com/products/jndi/ #download.

In my example, the LDAP server I used is Netscape Directory Server, but it really doesn't matter what LDAP server you're using: the code should still be the same.

To access the LDAP server I need to specify information on how to get to it. I put this information in the properties file "ldap.properties" as shown below. This information includes the name of the service class provider (in this case, the Sun LDAP service provider class), the URL to the LDAP server, and the user login and password to the LDAP server.

java.naming.factory.initial=com.sun.jndi.ldap.LdapCtx Factory
java.naming.provider.url=ldap:/localhost:1100/dc=ny,dc =whs,dc=com
java.naming.security.principal=user
java.naming.security.credentials=password

In my initialization code below, I load the properties file into a Properties object and then create an InitialDirConext:

Properties p= Util.getProperties("ldap.properties"):
DirContext ctx = new InitialDirContext(p);

Now that I have an InitialDirContext, I can use it to look up all the employee entries using the code below:

String searchRoot = "ou=Employee" ;
String filter="(uid=*) ";
String[] attrIDs ={"uid", "givenname", "sn", "tele-
                            phonenumber", "mail"};
SearchControls ctls = new SearchControls();
ctls.setReturningAttributes(attrIDs);
List employeeList = new ArrayList ();
NamingEnumeration list =
                ctx.search(searchRoot, filter, new SearchControls());
while (list.hasMore())
{
               SearchResult nc = (SearchResult)list.next();
               Attributes attrs = nc.getAttributes();
               Attribute attrId = (Attribute) attrs.get("uid");
               String id = (String) attrId.get();
               Employee e = new Employee(id);
               // ...similarly get other fields to fill out
               emplyeeList.add(employee);
}

This code does the following:

1. Specifies the three parameters for directory search: searchRoot, filter, and attributes
2. Using the initial context, does a search base on these conditions and returns a List of SearchResult
3. Iterates through the SearchResult, and for each Entry return retrieves its attributes and assembles the Employee object
4. Adds the Employee object to the employeeList

XML and XPath
XML may not be the way to persist data, but with the B2B nature of applications, it's likely that we don't get our information directly from its persistence storage. For example, we could be getting the employee information from another Web service that will send us the information as an XML file, as shown in employees.xml in Listing 4.

XPath is a language used to query XML, commonly used inside an XSLT stylesheet for XML transformation. It describes how to locate specific elements (and attributes, processing instructions, etc.) in a document. Similar to the LDAP search, which has a search base, XPath has the concept of the "context node", which is where you start from. Everything you search is relative to the starting location.

I'll now show you some examples of an XPath query using the XML in Listing 4. The basic syntax of XPath is similar to file system addressing. You can use an absolute path by starting with/or a relative path. For example, /Employees/ Employee/phone returns all the phone elements under Employees/Employee. Specifying * will get you all the elements located in the preceding path, so //Employee /* will return all elements (e.g., lastName, phone) under any Employee element in the document.

Expression in a square bracket can further specify an element. This is similar to a Where clause in a SQL. For example, Employee[starts-with(./lastName/text(),'D')] returns all employees with a lastName beginning in D. You can also specify the position of an element as in //Emp- loyees/Employee[2], which returns the second Employee child of Employees.

Attributes are specified by an @prefix. For example, // @city returns all the city attributes in the document. Attributes can also be used inside the square bracket to specify an element. An example is Addr[@city='newyork'], which returns all the Address elements that have an attribute city=newyork.

You can use a Boolean operation inside the square bracket. For example:

1. Employee[boolean(./lastName) or boolean (./e-mail)]
2. Employee[boolean(./lastName) and boolean (./e- mail)]

The first query represents an employee that has lastName or e-mail attributes, while the second query represents an employee that has both lastName and e-mail attributes. There are lists of functions for Node-Set, Boolean, Number, and String that you can use within an expression (see the Resources section).

You can apply more conditions in sequence by entering square brackets one after another. This is similar to a subquery in SQL. In addition, if the query is sequence-dependent, the result will depend on which condition you specify first. This can be seen in the example below:

1. //Employees/Employee[1][starts-
with(./lastName/text(),'D') ]
2. //Employees/Employee[starts-
with(./lastName/text(),'D') ][1]

Query 1 first selects all the first Employee elements under any Employees element, and then from that list, selects the ones that have a lastName beginning with "D." Query 2 first gets all the Employee elements under employees that have lastName D, and then from that list, selects the first one. The result and number of elements returned from these two queries may be different in this case.

There are many more powerful features of XPath that I haven't described here. Refer to the Resources section to learn more.

Querying XML in Java Code
To query XML using XPath, we can use the JAXP ( Java API for XML Parsing) API. JAXP provides a common interface for creating and using the standard SAX, DOM, and XSLT APIs in Java, regardless of which vendor's implementation is actually being used. JAXP API 1.1. is included in the J2SE 1.4, or you can get it from http://java.sun.com/xml/download.html to be used as an optional package for JDK 1.1.8 and above.

In my example, I use the Xerces XML parser and Xalan XSLT processor, both from Apache (www.apache.org), but you can use any other parsers or XSLT processors that implement the JAXP API. In my classpath I need to include xerces.jar and xalan.jar so that the Apache classes can be found. The following code prepares for an XPath query by creating a DOM parser first. It uses the Xerces implementation of the DocumentBuilderFactory to create a Xerces DOM parser.

DocumentBuilderFactory factory =
DocumentBuilderFactory.newInstance();
domParser = factory.newDocumentBuilder();

Now that I have a DOM parser, I can use the following code to do an XPath query to get all the Employees elements.

URL cfgURL = Util.createURL("employees.xml");
Document d = domParser.parse(cfgURL.toString());

String XPath = "//Employee
List employeeList = new ArrayList();
NodeList nl = XPathAPI.selectNodeList(d, XPath );
for (int i = 0; i< nl.getLength(); i++)
{
          Node n = nl.item(i);
          // id is an attribute
          Node nm = n.getAttributes().getNamedItem("id");
          Employee emp = new Employee (nm.getNodeValue());

          // Other fields are elements
          NodeList childNodes = n.getChildNodes();
          Node lastname = lookup (childNodes, "lastName");
          // ...do similarly for other fields

emp.setLastName(lastname.getFirstChild().getNodeValue());
         employeeList.add (emp);
}

This code does the following:

1. Creates a DOM document from the XML file employees.xml (see Listing 4) by parsing the XML file
2. Calls org.apache.xpath.XPathAPI.selectNodeList (from Xalan API) to run a query on the document using the XPath query statement
3. Iterates the result (NodeList) to assemble the Employee object; (note that in this XML, id is an attribute of Employee and it's retrieved in a different way than the other fields, e.g., lastName or firstName, which are elements of Employee)
4. Adds the Employee object to the EmployeeList

A Mode Complicated Query
To further illustrate the various ways to query the data, I'll now explain how to assemble the respective queries based on the same search condition as shown below:

1. (Lastname begins with 'D%' OR firstname begins with 'M%') AND
   
2. Does not have an e-mail attribute

The SQL query for this search is:

select id, lastName, firstName, phone, e-mail from Employee
where (lastName like 'D%' or firstName like 'M%')
and e-mail = null

Figure 3 shows the result of running this query in a SQL tool.
The LDAP query for this search is:

Search Base:          ou=Employee,dc=newyork, dc=white
                              horn,dc=com
Search Filter:          (& (|(givenname=M*)(sn=D*))
                              (!(mail=*)))
Attributes:              uid, sn, givenName, telephoneNumber, mail

The result of running this query in the query tool of an LDAP browser is shown in Figure 4.
The XPath query for this search is:

//Employee[starts-with(./lastName/text(),'D') or
starts-with(./firstName/text(),'M')]
     [not(boolean(./e-mail/text()))]

Figure 5 shows the result of running this in XPath using a tool called Cooktop XML editor (a free XML editor that can be downloaded at www.xmleverywhere.com/cooktop).

You can easily put the queries we constructed here back into the code we wrote in the last section, and have the results returned programatically in Java.

Common Interface
Depending on where the data is stored or comes from, the implementation for the Employee Search Application will be different. We could apply the Bridge pattern from the book, Design Patterns, to write the client for the Employee Search Application. The Bridge pattern separates a class interface from its implementation, so you can vary or replace the implementation without changing the client code. To do so I define the following interface:

Interface EmployeeQuery
{
      // Does initialization e.g. connect to server
      init();

      // Generate query based on Condition and return
         List of Employee
      List search (Condition c);
}

The client can then call methods in this interface without knowing what the underlying implementation is like. In my test client program, I create a method call runTest that calls init() and then does a search with empty conditions. This returns a list of all employees, printing their first and last names.

public static void runTest(EmployeeQuery eq)
 {
            System.out.println ("Running class " + eq.getClass().toString());
            eq.init();
            List l = eq.search (new Conditions());
            Iterator i = l.iterator();
            while (i.hasNext())
            {
                    Employee e = (Employee) i.next();
                    System.out.println (e.getId() + ":" +
                    e.getFirstName() + " " + e.getLastName() );
             }
}

Then I create the database, XML and LDAP implementations of EmployeeQuery, and call runTest on them, respectively, to test out the implementation.

public static void main(String[] args)
{
        runTest(new DBImpl());
        runTest(new XMLImpl());
        runTest(new LDAPImpl());
}

You can find the complete source code of DBImpl, LDAPImpl, and XMLImpl shown, respectively, in Listing 2, Listing 3, and Listing 5. Because this is only an example, currently all they do is return all the employees in their system. It doesn't use the condition parameter passed in to generate the query. You can do more work to specify conditions from a GUI, which you turn into the respective query to run and return the matching items.

Conclusion
I've shown you three ways of implementing the same client based on how the data is stored. It's unlikely that you'll have to implement an application in all three different ways. The purpose of this article is to show you the different syntaxes and code APIs you can use, so you can easily tackle each kind of query with minimal effort when you need to. I've only touched briefly on SQL, LDAP, and XPath. Each of them is in itself a big subject that you can study in detail when you have time.

A final point to bear in mind when developing your client: it's possible that the underlying implementation may change or that your client may be used with more than one implementation. In that case, your system will benefit if you use an interface when designing your code.

Resources

Relational databases and SQL:
1. JDBC API Doc: http://java.sun.com/j2se/1.3/docs/api /java/sql/package-summary.html
   LDAP:
   
2. JNDI API Doc: http://java.sun.com/products/jndi/javadoc/index.html
   
3. Excerpts from an LDAP book: http://developer.netscape.com/docs/books/macmillan/ldap/ldapbk.html
   
4. Sun JNDI tutorial: http://java.sun.com/products/ jndi/tutorial/TOC.html
   XML and XPath:
   
5. JAXP API Doc: http://java.sun.com/xml/jaxp-1.1/docs/ api/
   
6. Official W3C site: www.w3.org/TR/XPath
   
7. Quick Reference Card: www.mulberrytech.com/quickref/index.html
   
8. XPath example: www.zvon.org/xxl/XPathTutorial/General/ examples.html