directory-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r909072 - in /websites/staging/directory/trunk/content: ./ api/user-guide/2.10-ldap-connection-template.html
Date Sat, 17 May 2014 12:43:28 GMT
Author: buildbot
Date: Sat May 17 12:43:28 2014
New Revision: 909072

Log:
Staging update by buildbot for directory

Added:
    websites/staging/directory/trunk/content/api/user-guide/2.10-ldap-connection-template.html
Modified:
    websites/staging/directory/trunk/content/   (props changed)

Propchange: websites/staging/directory/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Sat May 17 12:43:28 2014
@@ -1 +1 @@
-1593711
+1595458

Added: websites/staging/directory/trunk/content/api/user-guide/2.10-ldap-connection-template.html
==============================================================================
--- websites/staging/directory/trunk/content/api/user-guide/2.10-ldap-connection-template.html
(added)
+++ websites/staging/directory/trunk/content/api/user-guide/2.10-ldap-connection-template.html
Sat May 17 12:43:28 2014
@@ -0,0 +1,287 @@
+<!DOCTYPE html>
+<!--
+    Licensed to the Apache Software Foundation (ASF) under one or more
+    contributor license agreements.  See the NOTICE file distributed with
+    this work for additional information regarding copyright ownership.
+    The ASF licenses this file to You under the Apache License, Version 2.0
+    (the "License"); you may not use this file except in compliance with
+    the License.  You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+-->
+<html>
+	<head>
+		<title>2.1 - The LdapConnectionTemplate &mdash; Apache Directory</title>
+		
+	    <link href="./../../css/common.css" rel="stylesheet" type="text/css">
+	    <link href="./../../css/brown.css" rel="stylesheet" type="text/css">
+    
+        
+        <link rel="shortcut icon" href="./../../images/api-icon_16x16.png">
+    
+        <!-- Google Analytics -->
+        <script src="http://www.google-analytics.com/urchin.js" type="text/javascript"></script>
+        <script type="text/javascript">
+            _uacct = "UA-1358462-1";
+            urchinTracker();
+        </script>
+	</head>
+	<body>
+	    <div id="container">
+            <div id="header">
+                <div id="subProjectsNavBar">
+                    <a href="./../../">
+                        
+                        Apache Directory Project
+                        
+                    </a>
+                    &nbsp;|&nbsp;
+                    <a href="./../../apacheds">
+                        
+                        ApacheDS
+                        
+                    </a>
+                    &nbsp;|&nbsp;
+                    <a href="./../../studio">
+                        
+                        Apache Directory Studio
+                        
+                    </a>
+                    &nbsp;|&nbsp;
+                    <a href="./../../api">
+                        
+                        <STRONG>Apache LDAP API</STRONG>
+                        
+                    </a>
+                    &nbsp;|&nbsp;
+                    <a href="./../../mavibot">
+                        
+                        Mavibot
+                        
+                    </a>
+                    &nbsp;|&nbsp;
+                    <a href="./../../escimo">
+                        
+                        eSCIMo
+                        
+                    </a>
+                </div><!-- subProjectsNavBar -->
+            </div><!-- header -->
+            <div id="content">
+                <div id="leftColumn">
+                    
+<div id="navigation">
+    
+    <h5>LDAP API 1.0</h5>
+    <ul>
+        <li><a href="./../../api/">Home</a></li>
+        <li><a href="./../../api/news.html">News</a></li>
+    </ul>
+    <h5>Downloads</h5>
+    <ul>
+	    <li><a href="./../../api/downloads.html">Version 1.0.0-M22</a>&nbsp;&nbsp;<IMG
src="./../../images/new_badge.gif" alt="" style="margin-bottom:-3px;" border="0"></li>
+        <li><a href="./../../api/download-old-versions.html">Older versions</a></li>
+    </ul>
+    <h5>Getting Started</h5>
+    <ul>
+        <li><a href="./../../api/vision.html">Vision</a></li>
+        <li><a href="./../../api/java-api.html">Java API</a></li>
+        <li><a href="./../../api/groovy-ldap.html">Groovy API</a></li>
+    </ul>
+    <h5>Documentation</h5>
+    <ul>
+	    <li><a href="./../../api/five-minutes-tutorial.html">Five minutes tutorial</a></li>
+	    <li><a href="./../../api/user-guide.html">User Guide</a></li>
+        <li><a href="./../../api/gen-docs/latest/apidocs/">JavaDocs</a></li>
+        <!--li><a href="./../../api/gen-docs/latest/">Generated Reports</a></li-->
+        <li><a href="./../../api/developer-guide.html">Developer Guide</a></li>
+    </ul>
+    
+    
+    <h5>Support</h5>
+    <ul>
+        <li><a href="./../../mailing-lists-and-irc.html">Mailing Lists &amp;
IRC</a></li>
+        <li><a href="./../../sources.html">Sources</a></li>
+        <li><a href="./../../issue-tracking.html">Issue Tracking</a></li>
+        <li><a href="./../../commercial-support.html">Commercial Support</a></li>
+    </ul>
+    <h5>Community</h5>
+    <ul>
+        <li><a href="./../../contribute.html">How to Contribute</a></li>
+        <li><a href="./../../team.html">Team</a></li>
+        <li><a href="./../../original-project-proposal.html">Original Project
Proposal</a></li>
+        <li><a href="./../../special-thanks.html" class="external-link" rel="nofollow">Special
Thanks</a></li>
+    </ul>
+    <h5>About Apache</h5>
+    <ul>
+        <li><a href="http://www.apache.org/">Apache</a></li>
+        <li><a href="http://www.apache.org/licenses/">License</a></li>
+        <li><a href="http://www.apache.org/foundation/sponsorship.html">Sponsorship</a></li>
+        <li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
+        <li><a href="http://www.apache.org/security/">Security</a></li>
+    </ul>
+    
+</div><!-- navigation -->
+
+                </div><!-- leftColumn -->
+                <div id="rightColumn">
+
+
+    <div class="nav">
+        <div class="nav_prev">
+        
+            <a href="2.9-exception-management.mdtext">2.9 - Exception management</a>
+		
+        </div>
+        <div class="nav_up">
+        
+            <a href="2-basic-ldap-api-usage.html">2 - Basic LDAP API usage</a>
+		
+        </div>
+        <div class="nav_next">
+        
+            <a href="3-advanced-ldap-api-usage.mdtext">3 - Advanced LDAP API Usage</a>
+		
+        </div>
+        <div class="clearfix"></div>
+    </div>
+
+
+<h1 id="21-why-use-the-ldapconnectiontemplate">2.1 - Why use the LdapConnectionTemplate</h1>
+<p>The LdapConnectionTemplate provides simplified access to the API functions.  It
does so by</p>
+<ul>
+<li><a href="#managing-connections">Managing Connections</a></li>
+<li>Providing Factory Methods For Model Objects</li>
+<li>Providing CRUD Methods</li>
+<li>Handling Search Result Iteration</li>
+<li>Providing Simplified, Password Policy Aware, Authentication/Password Modification
Methods</li>
+</ul>
+<p>The concept is basically that of the Template Method design pattern in that it does
all the boiler plate work for you and hands back control as necessary.</p>
+<h2 id="managing-connections">Managing Connections</h2>
+<p>The connection template manages connections through a connection pool.  The connection
pool must be supplied to the constructor:</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="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">LdapConnectionTemplate</span> <span class="n">ldapConnectionTemplate</span>
<span class="o">=</span> 
+    <span class="k">new</span> <span class="nf">LdapConnectionTemplate</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">PoolableLdapConnectionFactory</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 may look like a lot, but most of it is optional and it is the last you will
have to think about connections.</p>
+<h2 id="providing-factory-methods-for-model-objects">Providing Factory Methods For
Model Objects</h2>
+<p>The connection template implements an interface called ModelFactory.  Any implementation
of this factory can be injected into the template once it is constructed.  By default, it
uses ModelFactoryImpl which in turn constructs the standard Apache LDAP API model objects.
 This abstractions frees you from having to be concerned with implementation details while
still giving you the power to override the default behavior as you see fit.</p>
+<div class="codehilite"><pre><span class="n">ModelFactory</span>
<span class="n">modelFactory</span> <span class="o">=</span> <span
class="k">new</span> <span class="n">MyCustomModelFactory</span><span
class="o">();</span>
+<span class="n">ldapConnectionTemplate</span><span class="o">.</span><span
class="na">setModelFactory</span><span class="o">(</span> <span class="n">modelFactory</span>
<span class="o">);</span>
+
+
+
+<span class="o">:::</span><span class="n">Java</span>
+<span class="n">LdapConnection</span> <span class="n">connection</span>
<span class="o">=</span> <span class="k">new</span> <span class="n">LdapNetworkConnection</span><span
class="o">(</span> <span class="s">&quot;localhost&quot;</span><span
class="o">,</span> <span class="mi">389</span> <span class="o">);</span>
+</pre></div>
+
+
+<p>Here, we just created an unsafe connection locally, using the 389 port. Quite simple...</p>
+<h3 id="secure-connection">Secure connection</h3>
+<p>Although the <strong>LDAPS</strong> (<strong>LDAP</strong>
over <strong>SSL</strong>) is now considered as deprecated, many people continue
to use it. The big advantage of not using <strong>LDAPS</strong> is that you don't
need to setup two different listening ports (one for <strong>LDAP</strong> -389-
and another one for <strong>LDAPS</strong> -636- ).</p>
+<p>The only difference with the previous example is that we have to tell the connection
that it has to use <strong>SSL</strong>, by passing <strong><em>true</em></strong>
as a third parameter (incidentally, passing <strong><em>false</em></strong>
set a unsafe connection).</p>
+<p>Here is an example</p>
+<div class="codehilite"><pre><span class="n">LdapConnection</span>
<span class="n">connection</span> <span class="o">=</span> <span
class="k">new</span> <span class="n">LdapNetworkConnection</span><span
class="o">(</span> <span class="s">&quot;localhost&quot;</span><span
class="o">,</span> <span class="mi">636</span><span class="o">,</span>
<span class="kc">true</span> <span class="o">);</span>
+</pre></div>
+
+
+<h2 id="maintaining-the-connection-opened">Maintaining the connection opened</h2>
+<p>We keep the connection opened for a limited period of time, defaulting to 30 seconds.
This might be not long enough, so one can change this delay by calling the <em>setTimeOut()</em>
method :</p>
+<div class="codehilite"><pre><span class="n">LdapConnection</span>
<span class="n">connection</span> <span class="o">=</span> <span
class="k">new</span> <span class="n">LdapNetworkConnection</span><span
class="o">(</span> <span class="s">&quot;localhost&quot;</span><span
class="o">,</span> <span class="mi">389</span> <span class="o">);</span>
+<span class="n">connection</span><span class="o">.</span><span
class="na">setTimeOut</span><span class="o">(</span> <span class="mi">0</span>
<span class="o">);</span>
+<span class="o">...</span>
+<span class="n">connection</span><span class="o">.</span><span
class="na">close</span><span class="o">();</span>
+</pre></div>
+
+
+<blockquote>
+<p><strong>Note:</strong> Setting a value equal or below 0 will keep the
connection opened for ever (or a soon as the connection is not explicitly closed).</p>
+</blockquote>
+<h2 id="closing-the-connection">Closing the connection</h2>
+<p>Once you don't need to use the connection anymore (remember that hodling a connection
keeps a session opened on the server, and a socket opened between the client and the server),
then you have to close it. This is done by calling the <em>close()</em> method
:</p>
+<div class="codehilite"><pre><span class="n">LdapConnection</span>
<span class="n">connection</span> <span class="o">=</span> <span
class="k">new</span> <span class="n">LdapNetworkConnection</span><span
class="o">(</span> <span class="s">&quot;localhost&quot;</span><span
class="o">,</span> <span class="mi">389</span> <span class="o">);</span>
+<span class="o">...</span>
+<span class="n">connection</span><span class="o">.</span><span
class="na">close</span><span class="o">();</span>
+</pre></div>
+
+
+<h2 id="using-a-pool-of-connections">Using a pool of connections</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>
+<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>
+</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>
+
+
+    <div class="nav">
+        <div class="nav_prev">
+        
+            <a href="2.9-exception-management.mdtext">2.9 - Exception management</a>
+		
+        </div>
+        <div class="nav_up">
+        
+            <a href="2-basic-ldap-api-usage.html">2 - Basic LDAP API usage</a>
+		
+        </div>
+        <div class="nav_next">
+        
+            <a href="3-advanced-ldap-api-usage.mdtext">3 - Advanced LDAP API Usage</a>
+		
+        </div>
+        <div class="clearfix"></div>
+    </div>
+
+
+                </div><!-- rightColumn -->
+                <div id="endContent"></div>
+            </div><!-- content -->
+            <div id="footer">&copy; 2003-2014, <a href="http://www.apache.org">The
Apache Software Foundation</a> - <a href="./../../privacy-policy.html">Privacy
Policy</a><br />
+                Apache Directory, ApacheDS, Apache Directory Server, Apache Directory Studio,
Apache LDAP API, Apache Triplesec, Triplesec, Apache Mavibot, Mavibot, Apache eSCIMo, eSCIMo,
Apache, the Apache feather logo, and the Apache Directory project logos are trademarks of
The Apache Software Foundation.
+            </div>
+        </div><!-- container -->
+    </body>
+</html>
\ No newline at end of file



Mime
View raw message