Package net.rim.device.api.ldap Description

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.

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.