svn commit: r1002748 - in /websites/staging/directory/trunk/content: ./ api/user-guide/2.1-connection-disconnection.html

[bu...@apache.org]

Author: buildbot
Date: Tue Dec 13 20:37:41 2016
New Revision: 1002748

Log:
Staging update by buildbot for directory

Modified:
    websites/staging/directory/trunk/content/   (props changed)
    websites/staging/directory/trunk/content/api/user-guide/2.1-connection-disconnection.html

Propchange: websites/staging/directory/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Tue Dec 13 20:37:41 2016
@@ -1 +1 @@
-1770592
+1774097

Modified: websites/staging/directory/trunk/content/api/user-guide/2.1-connection-disconnection.html
==============================================================================
--- websites/staging/directory/trunk/content/api/user-guide/2.1-connection-disconnection.html (original)
+++ websites/staging/directory/trunk/content/api/user-guide/2.1-connection-disconnection.html Tue Dec 13 20:37:41 2016
@@ -223,21 +223,47 @@ h2:hover > .headerlink, h3:hover > .head
 
 
 <h2 id="using-a-pool-of-connections">Using a pool of connections<a class="headerlink" href="#using-a-pool-of-connections" title="Permanent link">&para;</a></h2>
-<p>Creating a connection is expensive. If you are to reuse a connection over and over, or if you are writing an application that will need many LDAP conenctions, you may want to use a pool of connections.</p>
-<p>This is slightly more complex than simply opening a new connection, as you have a lot of parametrs that can come into play when creating a pool.
-Here is an example of creation of a pool of connections :</p>
+<p>Creating a connection is expensive. If that connection will be reused, or if your application needs multiple connections, you may want to consider using a <em>connection pool</em>.</p>
+<p>This process is slightly more complex given that there are many parameters that can be used to tune the pool.  Here is an example:</p>
 <div class="codehilite"><pre><span class="n">LdapConnectionConfig</span> <span class="n">config</span> <span class="o">=</span> <span class="k">new</span> <span class="n">LdapConnectionConfig</span><span class="o">();</span>
-<span class="n">config</span><span class="o">.</span><span class="na">setLdapHost</span><span class="o">(</span> <span class="s">&quot;localhost&quot;</span> <span class="o">);</span>
-<span class="n">config</span><span class="o">.</span><span class="na">setLdapPort</span><span class="o">(</span> <span class="mi">389</span> <span class="o">);</span>
-<span class="n">config</span><span class="o">.</span><span class="na">setName</span><span class="o">(</span> <span class="s">&quot;uid=admin,ou=system&quot;</span> <span class="o">);</span>
-<span class="n">config</span><span class="o">.</span><span class="na">setCredentials</span><span class="o">(</span> <span class="s">&quot;secret&quot;</span> <span class="o">);</span>
-<span class="n">PoolableLdapConnectionFactory</span> <span class="n">factory</span> <span class="o">=</span> <span class="k">new</span> <span class="n">PoolableLdapConnectionFactory</span><span class="o">(</span> <span class="n">config</span> <span class="o">);</span>
-<span class="n">LdapConnectionPool</span> <span class="n">pool</span> <span class="o">=</span> <span class="k">new</span> <span class="n">LdapConnectionPool</span><span class="o">(</span> <span class="n">factory</span> <span class="o">);</span>
-<span class="n">pool</span><span class="o">.</span><span class="na">setTestOnBorrow</span><span class="o">(</span> <span class="kc">true</span> <span class="o">);</span>
+<span class="n">config</span><span class="o">.</span><span class="na">setLdapHost</span><span class="o">(</span> <span class="n">hostname</span> <span class="o">);</span>
+<span class="n">config</span><span class="o">.</span><span class="na">setLdapPort</span><span class="o">(</span> <span class="n">port</span> <span class="o">);</span>
+<span class="n">config</span><span class="o">.</span><span class="na">setName</span><span class="o">(</span> <span class="n">adminDn</span> <span class="o">);</span>
+<span class="n">config</span><span class="o">.</span><span class="na">setCredentials</span><span class="o">(</span> <span class="n">adminPassword</span> <span class="o">);</span>
+
+<span class="n">DefaultLdapConnectionFactory</span> <span class="n">factory</span> <span class="o">=</span> <span class="k">new</span> <span class="n">DefaultLdapConnectionFactory</span><span class="o">(</span> <span class="n">config</span> <span class="o">);</span>
+<span class="n">factory</span><span class="o">.</span><span class="na">setTimeOut</span><span class="o">(</span> <span class="n">connectionTimeout</span> <span class="o">);</span>
+
+<span class="c1">// optional, values below are defaults</span>
+<span class="n">GenericObjectPool</span><span class="o">.</span><span class="na">Config</span> <span class="n">poolConfig</span> <span class="o">=</span> <span class="k">new</span> <span class="n">GenericObjectPool</span><span class="o">.</span><span class="na">Config</span><span class="o">();</span>
+<span class="n">poolConfig</span><span class="o">.</span><span class="na">lifo</span> <span class="o">=</span> <span class="kc">true</span><span class="o">;</span>
+<span class="n">poolConfig</span><span class="o">.</span><span class="na">maxActive</span> <span class="o">=</span> <span class="mi">8</span><span class="o">;</span>
+<span class="n">poolConfig</span><span class="o">.</span><span class="na">maxIdle</span> <span class="o">=</span> <span class="mi">8</span><span class="o">;</span>
+<span class="n">poolConfig</span><span class="o">.</span><span class="na">maxWait</span> <span class="o">=</span> <span class="o">-</span><span class="mi">1L</span><span class="o">;</span>
+<span class="n">poolConfig</span><span class="o">.</span><span class="na">minEvictableIdleTimeMillis</span> <span class="o">=</span> <span class="mi">1000L</span> <span class="o">*</span> <span class="mi">60L</span> <span class="o">*</span> <span class="mi">30L</span><span class="o">;</span>
+<span class="n">poolConfig</span><span class="o">.</span><span class="na">minIdle</span> <span class="o">=</span> <span class="mi">0</span><span class="o">;</span>
+<span class="n">poolConfig</span><span class="o">.</span><span class="na">numTestsPerEvictionRun</span> <span class="o">=</span> <span class="mi">3</span><span class="o">;</span>
+<span class="n">poolConfig</span><span class="o">.</span><span class="na">softMinEvictableIdleTimeMillis</span> <span class="o">=</span> <span class="o">-</span><span class="mi">1L</span><span class="o">;</span>
+<span class="n">poolConfig</span><span class="o">.</span><span class="na">testOnBorrow</span> <span class="o">=</span> <span class="kc">false</span><span class="o">;</span>
+<span class="n">poolConfig</span><span class="o">.</span><span class="na">testOnReturn</span> <span class="o">=</span> <span class="kc">false</span><span class="o">;</span>
+<span class="n">poolConfig</span><span class="o">.</span><span class="na">testWhileIdle</span> <span class="o">=</span> <span class="kc">false</span><span class="o">;</span>
+<span class="n">poolConfig</span><span class="o">.</span><span class="na">timeBetweenEvictionRunsMillis</span> <span class="o">=</span> <span class="o">-</span><span class="mi">1L</span><span class="o">;</span>
+<span class="n">poolConfig</span><span class="o">.</span><span class="na">whenExhaustedAction</span> <span class="o">=</span> <span class="n">GenericObjectPool</span><span class="o">.</span><span class="na">WHEN_EXHAUSTED_BLOCK</span><span class="o">;</span>
+
+<span class="n">LdapConnectionPool</span> <span class="n">pool</span> <span class="o">=</span> <span class="k">new</span> <span class="n">LdapConnectionPool</span><span class="o">(</span>
+    <span class="k">new</span> <span class="nf">DefaultPoolableLdapConnectionFactory</span><span class="o">(</span> <span class="n">factory</span> <span class="o">),</span> <span class="n">poolConfig</span> <span class="o">)</span> <span class="o">);</span>
+</pre></div>
+
+
+<p>This will create a pool of connections that will be pre-authenticated.  If you do not setName and setCredentials, then the pool will contain unauthenticated connections.</p>
+<p>The DefaultPoolableLdapConnectionFactory is sufficient for many cases.  However, certain operations result in modifications to the connection itself.  For example, when the pool is created, a bind operation will occur with the credentials supplied as part of the config.  If you borrow a connection and perform a bind yourself, that would result in the connection being re-bound as a different user.  The next time that connection gets borrowed, things are likely to break.  If you perform any operation that results in a modification of the connection, you should instead use ValidatingPoolableLdapConnectionFactory:</p>
+<div class="codehilite"><pre><span class="o">...</span>
+<span class="n">PoolableLdapConnectionFactory</span> <span class="n">factory</span> <span class="o">=</span> <span class="k">new</span> <span class="n">ValidatingPoolableLdapConnectionFactory</span><span class="o">(</span> <span class="n">config</span> <span class="o">);</span>
+<span class="o">...</span>
 </pre></div>
 
 
-<p>Here, we just have created a pool of connections which all are unthenticated using the administrator user. You can create anonymous connections, it's just a matter of not setting any name or credentials in the config.</p>
+<p>A connection pool using this factory will unbind and rebind any connection that was modified while it was borrowed (<em>see the javadoc for more detail</em>).  This will be slower due to the additional operations, but not too significantly.</p>
 
 
     <div class="nav">