As LDAP relies on a connection from the client to the directory server, the starting point for working with the LDAP SDK is a new LDAPConnectionFactory, from which you then get either a synchronous connection, or pass in a handler to an asynchronous connection. You then use the connection to make requests and get responses from the directory server.

Connections Asynchronous Connections Synchronous For synchronous operations your application gets a connection from the LDAPConnectionFactory and requests operations on the connection. When finished, your application closes the connection. [jcp:org.forgerock.opendj.examples.Search:--- JCite ---] For a complete example in context, see Search.java, one of the OpenDJ LDAP SDK examples. For asynchronous operations, your application obtains a connection with LDAPConnectionFactory.getConnectionAsync(), and then uses promises to handle the bind, the subsequent operations, the results, and any errors in asynchronous fashion. [jcp:org.forgerock.opendj.examples.SearchAsync:--- Using Promises ---] When the factory gets a connection, your application passes an AsyncFunction to apply to the connection to handle the bind by using the thenAsync() method in the fluent style. Your application uses thenAsync() again to pass another AsyncFunction to perform the operation. In the sample shown here, the second call to thenAsync() passes a function that performs a search, passing in a handler to deal with the search results returned by the directory server. The call to onSuccess() handles the final result, with the call to onFailure() dealing with exceptions. Asynchronous methods are non-blocking, returning a Promise, so that you can chain methods in the fluent style. Your application must coordinate concurrency when you use asynchronous operations. For a complete example in context, see SearchAsync.java, one of the OpenDJ LDAP SDK examples.

Errors LDAP defines many result codes to deal with conditions other than success. The ResultCode class encapsulates the LDAP codes and additional client-side codes specific to the SDK. Your application deals with most non-success result codes by catching LdapException objects or handling them when supplied to FailureHandler objects passed to onFailure() methods. Your application can then take remedial action based on the result code, as in the following synchronous example. final LDAPConnectionFactory factory = new LDAPConnectionFactory(host, port); Connection connection = null; try { connection = factory.getConnection(); connection.bind(name, password); // Perform operations on the connection... } catch (final LdapException e) { // Take remedial action based on the result code... // e.getResult().getResultCode() returns the code for you to interpret. } finally { if (connection != null) { connection.close(); } } Also notice the methods ResultCode.getName() that provides a short, human-readable version of the result code, and Result.getDiagnosticMessage() that can help to debug problems after the fact. When you have completely finished with a connection, then use the close() method on it.