From df849b3a64f3d5d90540f588db9a89cba37229ad Mon Sep 17 00:00:00 2001 From: Mark Craig <mark.craig@forgerock.com> Date: Tue, 15 May 2012 11:55:42 +0000 Subject: [PATCH] Begin the dev-guide chapter looking at the Proxy example, which makes use of async connections and methods --- /dev/null | 45 --------------- opendj3/src/main/docbkx/dev-guide/index.xml | 1 opendj3/src/main/docbkx/dev-guide/chap-simple-proxy.xml | 84 ++++++++++++++++++++++++--- 3 files changed, 74 insertions(+), 56 deletions(-) diff --git a/opendj3/src/main/docbkx/dev-guide/chap-multithreading.xml b/opendj3/src/main/docbkx/dev-guide/chap-multithreading.xml deleted file mode 100644 index 82335d0..0000000 --- a/opendj3/src/main/docbkx/dev-guide/chap-multithreading.xml +++ /dev/null @@ -1,45 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!-- - ! CCPL HEADER START - ! - ! This work is licensed under the Creative Commons - ! Attribution-NonCommercial-NoDerivs 3.0 Unported License. - ! To view a copy of this license, visit - ! http://creativecommons.org/licenses/by-nc-nd/3.0/ - ! or send a letter to Creative Commons, 444 Castro Street, - ! Suite 900, Mountain View, California, 94041, USA. - ! - ! You can also obtain a copy of the license at - ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt. - ! See the License for the specific language governing permissions - ! and limitations under the License. - ! - ! If applicable, add the following below this CCPL HEADER, with the fields - ! enclosed by brackets "[]" replaced with your own identifying information: - ! Portions Copyright [yyyy] [name of copyright owner] - ! - ! CCPL HEADER END - ! - ! Copyright 2011 ForgeRock AS - ! ---> -<chapter xml:id='chap-multithreading' - xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en' - xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' - 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>Writing Multithreaded Applications</title> - - <para>TODO</para> - - <section xml:id="async-operations"> - <title>Asynchronous Operations</title> - <para>TODO</para> - </section> - - <section xml:id="connection-pooling"> - <title>Connection Pooling</title> - <para>TODO</para> - </section> -</chapter> diff --git a/opendj3/src/main/docbkx/dev-guide/chap-simple-proxy.xml b/opendj3/src/main/docbkx/dev-guide/chap-simple-proxy.xml index 8e93535..f14770c 100644 --- a/opendj3/src/main/docbkx/dev-guide/chap-simple-proxy.xml +++ b/opendj3/src/main/docbkx/dev-guide/chap-simple-proxy.xml @@ -20,7 +20,7 @@ ! ! CCPL HEADER END ! - ! Copyright 2011 ForgeRock AS + ! Copyright 2011-2012 ForgeRock AS ! --> <chapter xml:id='chap-simple-proxy' @@ -31,20 +31,84 @@ xmlns:xinclude='http://www.w3.org/2001/XInclude'> <title>Writing a Simple LDAP Proxy</title> - <para>TODO</para> + <para>The OpenDJ LDAP SDK <link xlink:show="new" + xlink:href="http://opendj.forgerock.org/opendj-ldap-sdk-examples/xref/org/forgerock/opendj/examples/Proxy.html" + >example Proxy</link> demonstrates a simple LDAP proxy that forwards requests + to one or more remote directory servers. Although the implementation is + intended as an example, it does demonstrate use of the asynchronous API, + load balancing, and connection pooling.</para> - <section xml:id="load-balancing"> - <title>Load Balancing</title> - <para>TODO</para> + <para>The Proxy example sets up connections pools with load balancing to the + directory servers. It passes the connection factories to a + <literal>ProxyBackend</literal> that handles the requests passed back + to the directory servers. It also sets up an LDAP listener to receive incoming + connections from clients of the Proxy.</para> + + <para>The <literal>ProxyBackend</literal> uses separate connection factories, + one for bind operations, the other for other operations. It uses the proxied + authorization control to ensure operations are performed using the bind + identity for the operation.</para> + + <para>The <literal>ProxyBackend</literal>'s function is to handle each client + request, encapsulating the result handlers that allow it to deal with each + basic operation. It authenticates to the directory server to check incoming + credentials, and adds the proxied authorization control to requests other than + binds. The <literal>ProxyBackend</literal> handles all operations using + asynchronous connections and methods.</para> + + <section xml:id="connection-pooling"> + <title>Connection Pooling</title> + + <para>As shown in the Proxy example, the + <literal>Connections.newFixedConnectionPool()</literal> returns a connection + pool of the maximum size you specify.</para> + + <programlisting language="java" +>final List<ConnectionFactory> factories = new LinkedList<ConnectionFactory>(); + +factories.add(Connections.newFixedConnectionPool(new LDAPConnectionFactory( + remoteAddress, remotePort), Integer.MAX_VALUE));</programlisting> + + <para>Connections are returned to the pool when you <literal>close()</literal> + them. Notice that <literal>Connections</literal> also provides methods to + return <literal>ConnectionFactory</literal>s with a heart beat check on + connections provided by the factory, and connection factories that + authenticate connections before returning them.</para> + + <para>Connections in the pool are intended for reuse. Therefore when you + <literal>close()</literal> a connection from the pool, the OpenDJ LDAP SDK + does not perform an <literal>unbind()</literal>. You must therefore be careful + about how you manage authentication on connections from a pool. As a rule, + either bind separately and use proxied authorization as in the Proxy example, + or make sure that the first operation on a connection retrieved from the pool + is a bind that correctly authenticates the user currently served by the + connection.</para> </section> - - <section xml:id="managing-failover"> - <title>Performing Failover</title> - <para>TODO</para> + + <section xml:id="load-balancing-and-failover"> + <title>Load Balancing & Failover</title> + + <para>The <literal>Connections.newLoadBalancer()</literal> method returns a + load balancer based on the algorithm you choose. Algorithms include both + round robin for equitably sharing load across local directory servers, and + also failover usually used for switching automatically from an unresponsive + server group to an alternative server group. The algorithms take collections + of connection factories, such as those that you set up for connection + pooling.</para> + + <programlisting language="java" +>final RoundRobinLoadBalancingAlgorithm algorithm = + new RoundRobinLoadBalancingAlgorithm(factories); + +final ConnectionFactory factory = Connections.newLoadBalancer(algorithm);</programlisting> + + <para>The algorithms also include constructors that let you adjust timeouts + and so forth.</para> </section> - + <section xml:id="dn-attr-rewriting"> <title>DN & Attribute Rewriting</title> + <para>TODO</para> </section> </chapter> diff --git a/opendj3/src/main/docbkx/dev-guide/index.xml b/opendj3/src/main/docbkx/dev-guide/index.xml index f542a35..d713b7a 100644 --- a/opendj3/src/main/docbkx/dev-guide/index.xml +++ b/opendj3/src/main/docbkx/dev-guide/index.xml @@ -67,7 +67,6 @@ <xinclude:include href='chap-ldif.xml' /> <xinclude:include href='chap-controls.xml' /> <xinclude:include href='chap-extended-ops.xml' /> - <xinclude:include href='chap-multithreading.xml' /> <xinclude:include href='chap-i18n.xml' /> <xinclude:include href='chap-simple-proxy.xml' /> -- Gitblit v1.10.0