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:

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.

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.






Copyright 1999-2010 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.