Draft. May throw this chapter out when moving the dev guide content inside ...

Mark Craig

09.00.2012 bad8b0261c9943dbe2743487bb37bd0ae58b6a0d

Draft. May throw this chapter out when moving the dev guide content inside the Javadoc.

 opendj3/src/main/docbkx/dev-guide/chap-using-the-sdk.xml

@@ -20,7 +20,7 @@
  !
  ! CCPL HEADER END
  !
  !      Copyright 2011 ForgeRock AS
  !      Copyright 2011-2012 ForgeRock AS
  !    
-->
<chapter xml:id='chap-using-the-sdk'
@@ -29,22 +29,139 @@
 xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
 xmlns:xlink='http://www.w3.org/1999/xlink'
 xmlns:xinclude='http://www.w3.org/2001/XInclude'>
 <title>Using the SDK</title>
 <title>Using the LDAP SDK</title>

 <para>TODO</para>
 <para>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
 <literal>LDAPConnectionFactory</literal>, 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.</para>


 <section xml:id="sync-vs-async">
  <title>Synchronous &amp; Asynchronous Operations</title>
  <para>TODO</para>

  <para>For synchronous operations your application gets a connection from
  the <literal>LDAPConnectionFactory</literal> and requests operations on
  the connection. When finished, your application closes the connection.</para>

  <programlisting language="java">
final LDAPConnectionFactory factory = new LDAPConnectionFactory(host, port);
Connection connection = null;

try {
    connection = factory.getConnection();

    // Perform operations on the connection, such as connection.bind(),
    // connection.search(), connection.modify(), etc.

    } catch (final ErrorResultException e) {
        System.err.println(e.getMessage());
        System.exit(e.getResult().getResultCode().intValue());
        return;
    } finally {
        if (connection != null) {
            connection.close();
        }
    }
</programlisting>

  <para>For asynchronous operations, your application passes a result handler
  to <literal>LDAPConnectionFactory.getConnectionAsync()</literal> that
  implements the <literal>ResultHandler&lt;Connection&gt;</literal>
  interface.</para>

  <programlisting language="java">
private static final class ConnectResultHandlerImpl
        implements ResultHandler&lt;Connection&gt; {
    @Override
    public void handleErrorResult(final ErrorResultException error) {
        ...
    }

    @Override
    public void handleResult(final Connection connection) {
        // Connect succeeded: save connection and initiate bind.
        SearchAsync.connection = connection;

        final BindRequest request =
                Requests.newSimpleBindRequest(userName, password.toCharArray());
        connection.bindAsync(request, null, new BindResultHandlerImpl());
    }
}

// Main method initiates async operations by getting a connection...
final LDAPConnectionFactory factory = new LDAPConnectionFactory(hostName, port);
factory.getConnectionAsync(new ConnectResultHandlerImpl());

...

if (connection != null) {
    connection.close();
}
</programlisting>

  <para>When the connection result handler gets a connection, your application
  can pass result handlers for other operations using methods on the connection
  named <literal>*Async()</literal>. For most operations, your application
  implements <literal>ResultHandler</literal>. For searches, your application
  implements <literal>SearchResultHandler</literal>. The result handler is
  notified upon completion of the operation.</para>

  <para>Asynchronous methods are non-blocking, returning a
  <literal>FutureResult</literal> whose <literal>get()</literal> method lets
  you retrieve the result. Your application must coordinate concurrency when
  you use asynchronous operations. See <filename>SearchAsync.java</filename>
  for an example.</para>
 </section>
 

 <section xml:id="error-handling">
  <title>Managing Errors</title>
  <para>TODO</para>

  <para>LDAP <link xlink:href="http://tools.ietf.org/html/rfc4511#appendix-A"
  xlink:show="new">defines many result codes</link> to deal with conditions
  other than success. The <literal>ResultCode</literal> class encapsulates the
  LDAP codes and additional client-side codes specific to the SDK.</para>

  <para>Your application deals with most non-success result codes when it
  catches one of the LDAP SDK exceptions corresponding to the operation you
  requested. <literal>ErrorResultException</literal> is a common way for the
  SDK to indicate a non-successful result. Your application can then take
  remedial action based on the result code, as in the following synchronous
  excerpt.</para>

  <programlisting language="java">
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 ErrorResultException 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();
    }
}
</programlisting>

  <para>Also notice the methods <literal>ResultCode.getName()</literal> that
  provides a short, human-readable version of the result code, and
  <literal>Result.getDiagnosticMessage()</literal> that can also help debug
  problems after the fact.</para>
 </section>
 

 <section xml:id="referral-handling">
  <title>Managing Referrals</title>

  <para>TODO</para>
 </section>
</chapter>