From bad8b0261c9943dbe2743487bb37bd0ae58b6a0d Mon Sep 17 00:00:00 2001
From: Mark Craig <mark.craig@forgerock.com>
Date: Wed, 09 May 2012 13:00:27 +0000
Subject: [PATCH] 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 | 131 +++++++++++++++++++++++++++++++++++++++++--
1 files changed, 124 insertions(+), 7 deletions(-)
diff --git a/opendj3/src/main/docbkx/dev-guide/chap-using-the-sdk.xml b/opendj3/src/main/docbkx/dev-guide/chap-using-the-sdk.xml
index fd7abb8..566b038 100644
--- a/opendj3/src/main/docbkx/dev-guide/chap-using-the-sdk.xml
+++ b/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 & 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<Connection></literal>
+ interface.</para>
+
+ <programlisting language="java">
+private static final class ConnectResultHandlerImpl
+ implements ResultHandler<Connection> {
+ @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>
\ No newline at end of file
--
Gitblit v1.10.0