directory-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From lucasthei...@apache.org
Subject svn commit: r1774097 - /directory/site/trunk/content/api/user-guide/2.1-connection-disconnection.mdtext
Date Tue, 13 Dec 2016 20:37:32 GMT
Author: lucastheisen
Date: Tue Dec 13 20:37:32 2016
New Revision: 1774097

URL: http://svn.apache.org/viewvc?rev=1774097&view=rev
Log:
DIRAPI-287: Documentation is wrong for connection pooling

Modified:
    directory/site/trunk/content/api/user-guide/2.1-connection-disconnection.mdtext

Modified: directory/site/trunk/content/api/user-guide/2.1-connection-disconnection.mdtext
URL: http://svn.apache.org/viewvc/directory/site/trunk/content/api/user-guide/2.1-connection-disconnection.mdtext?rev=1774097&r1=1774096&r2=1774097&view=diff
==============================================================================
--- directory/site/trunk/content/api/user-guide/2.1-connection-disconnection.mdtext (original)
+++ directory/site/trunk/content/api/user-guide/2.1-connection-disconnection.mdtext Tue Dec
13 20:37:32 2016
@@ -73,19 +73,46 @@ Once you don't need to use the connectio
 
 ## Using a pool of connections
 
-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.
+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 _connection pool_.
 
-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 :
+This process is slightly more complex given that there are many parameters that can be used
to tune the pool.  Here is an example:
 
     :::Java
     LdapConnectionConfig config = new LdapConnectionConfig();
-    config.setLdapHost( "localhost" );
-    config.setLdapPort( 389 );
-    config.setName( "uid=admin,ou=system" );
-    config.setCredentials( "secret" );
-    PoolableLdapConnectionFactory factory = new PoolableLdapConnectionFactory( config );
-    LdapConnectionPool pool = new LdapConnectionPool( factory );
-    pool.setTestOnBorrow( true );
+    config.setLdapHost( hostname );
+    config.setLdapPort( port );
+    config.setName( adminDn );
+    config.setCredentials( adminPassword );
 
-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.
+    DefaultLdapConnectionFactory factory = new DefaultLdapConnectionFactory( config );
+    factory.setTimeOut( connectionTimeout );
+
+    // optional, values below are defaults
+    GenericObjectPool.Config poolConfig = new GenericObjectPool.Config();
+    poolConfig.lifo = true;
+    poolConfig.maxActive = 8;
+    poolConfig.maxIdle = 8;
+    poolConfig.maxWait = -1L;
+    poolConfig.minEvictableIdleTimeMillis = 1000L * 60L * 30L;
+    poolConfig.minIdle = 0;
+    poolConfig.numTestsPerEvictionRun = 3;
+    poolConfig.softMinEvictableIdleTimeMillis = -1L;
+    poolConfig.testOnBorrow = false;
+    poolConfig.testOnReturn = false;
+    poolConfig.testWhileIdle = false;
+    poolConfig.timeBetweenEvictionRunsMillis = -1L;
+    poolConfig.whenExhaustedAction = GenericObjectPool.WHEN_EXHAUSTED_BLOCK;
+
+    LdapConnectionPool pool = new LdapConnectionPool(
+        new DefaultPoolableLdapConnectionFactory( factory ), poolConfig ) );
+
+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.
+
+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:
+
+    :::Java
+    ...
+    PoolableLdapConnectionFactory factory = new ValidatingPoolableLdapConnectionFactory(
config );
+    ...
+
+A connection pool using this factory will unbind and rebind any connection that was modified
while it was borrowed (_see the javadoc for more detail_).  This will be slower due to the
additional operations, but not too significantly.



Mime
View raw message