Package net.rim.device.api.ldap

Lightweight Data Access Protocol (LDAP) Classes and Definitions.

See:
Description

Interface Summary

LDAPAttribute	This class represents one attribute in an LDAP entry.
LDAPEntry	Represents an LDAP entry.
LDAPListener	Contains the functionality for the LDAP listener.

Class Summary

LDAPComparator	Contains the functionality required for comparing LDAP objects.
LDAPPasswordCache	Deprecated. No longer for 3rd party use.
LDAPQuery	Contains the functionality for performing LDAP queries.

Exception Summary

LDAPBadSyntaxException	Represents an LDAP bad syntax exception.
LDAPException	Represents an LDAP exception.
LDAPInvalidOperationException	Represents the LDAP query in progress exception.
LDAPNoSuchAttributeException	Represents the LDAP no such attribute exception.

Package net.rim.device.api.ldap Description

Lightweight Data Access Protocol (LDAP) Classes and Definitions.

LDAP is a client-server protocol used for accessing directories. It allows you to access and browse through information on remote directory servers.

This package contains Research In Motion's implementation of a simple LDAP client. This library is designed to be used to perform anonymous queries from corporate or public LDAP servers. The main "worker class" of this API is the LDAPQuery object, which acts as a interface to the MDS (Mobile Data Service) LDAP component. This class is used to formulate a query based on the encoding rules defined in RFC 2255.

The components of this API are:

• LDAPQuery - This class works with the MDS (Mobile Data Service) LDAP component to perform the requested query.
• LDAPEntry - Represents a returned entry from the LDAP directory. Contains a set of LDAPAttributes.
• LDAPAttribute - Represents a set of values for a particular attribute in an LDAP entry. Contains a set of strings or byte arrays.
• LDAPComparator - This class is used to sort LDAPEntry objects according to a set of sorting attributes. This class is useful when displaying LDAPEntry objects to the user.
• LDAPListener - This interface is used when more detailed status information on the state of the LDAP query is desired.

Tutorial

The following tutorial outlines the basic steps in performing a query to a known LDAP server.

First, the query object is created.

LDAPQuery query = new LDAPQuery();

Notice the empty parameter list, the developer can optionally provide the LDAP URL to the query, or can provide an object that implements the LDAPListener interface to recieve more detailed status reports from the query.

Next, the LDAP server parameters are set.

query.setHost("ldap.rim.net",389,"ou=people,o=rim.net");

This specifies the host to contact ("ldap.rim.net"), the port to connect to (389) and the base query to use ("ou=people,o=rim.net").

Next, the scope of the query is set.

query.setScope(LDAPQuery.LDAP_SCOPE_SUB);

The scope determines what entries are returned from a query.

• A "base"-level scope ("LDAPQuery.LDAP_SCOPE_BASE") returns the entry adddressed by the base query.
• A "one"-level scope ("LDAPQuery.LDAP_SCOPE_ONE") returns all the entries one level below the entry addressed by the base query.
• A "sub"-level scope ("LDAPQuery.LDAP_SCOPE_SUB") returns all the entries below the entry addressed by the base query.

Next, the attributes to be returned from the query are set.

query.addAttribute("mail");

Next, the filter to apply to the results is set.

query.addFilter("givenname","bob");

In this example, we have selected to only get entries who's first name is "bob". Below, the query is started.

query.start();

Finally, the results of the query are stored in an enumeration called enum.

Enumeration enum = query.getResults();

In this case we are calling the blocking method getResults which will return an enumeration of the results of the query. If a non-blocking call is desired, the LDAPListener interface can provide an application with more detailed status reports of when the query starts/stops or entries start arriving.

Next, final result of the query is returned.

if (query.getErrorCode() != LDAPQuery.LDAP_SUCCESS) {
    // An error occured, so we should report an error
}

Assuming there wasn't an error in the above code the results are now parsed.

while (enum.hasMoreElements()) {

   LDAPEntry   entry      = (LDAPEntry)enum.nextElement();
   Enumeration attributes = entry.getAttributes();

   while (attributes.hasMoreElements()) {

      LDAPAttribute attribute = (LDAPAttribute)attributes.nextElement();
      Enumeration   values    = attribute.getValues();

      while (values.hasMoreElements()) {

         Object value = values.nextElement();
         if (value instanceof String) {
            // we got a String value.
         }
         else {
            // we got a byte array
         }
      }
   }
}

Finally, there is a possibility that one of the arguments passed into a method may contain illegal characters or a configuration method may be called at an inappropriate time, so there are two exceptions that must be caught:

LDAPInvalidOperationException:
    This error means the application tried to do something out of order.
    For instance, adding an attribute or filter to a running query will throw this exception.

LDAPBadSyntaxException
    This error means that one of the strings passed to a query method contains illegal characters or violates encoding rules.
    For instance, having a question mark (?) in any string will throw this exception.