You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@directory.apache.org by bu...@apache.org on 2017/12/28 19:34:30 UTC
svn commit: r1022853 - in /websites/staging/directory/trunk/content: ./
api/user-guide.html api/user-guide/6.7-control.html
Author: buildbot
Date: Thu Dec 28 19:34:30 2017
New Revision: 1022853
Log:
Staging update by buildbot for directory
Modified:
websites/staging/directory/trunk/content/ (props changed)
websites/staging/directory/trunk/content/api/user-guide.html
websites/staging/directory/trunk/content/api/user-guide/6.7-control.html
Propchange: websites/staging/directory/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Thu Dec 28 19:34:30 2017
@@ -1 +1 @@
-1819334
+1819438
Modified: websites/staging/directory/trunk/content/api/user-guide.html
==============================================================================
--- websites/staging/directory/trunk/content/api/user-guide.html (original)
+++ websites/staging/directory/trunk/content/api/user-guide.html Thu Dec 28 19:34:30 2017
@@ -253,7 +253,7 @@ Other pages are finished (but may be rev
<li><a href="user-guide/6.4-attribute-type.html">6.4 - AttributeType (...)</a></li>
<li><a href="user-guide/6.5-ava.html">6.5 - Ava</a></li>
<li><a href="user-guide/6.6-csn.html">6.6 - Csn</a></li>
-<li><a href="user-guide/6.7-control.html">6.7 - Control (e)</a></li>
+<li><a href="user-guide/6.7-control.html">6.7 - Control (...)</a></li>
<li><a href="user-guide/6.8-cursor.html">6.8 - Cursor (e)</a></li>
<li><a href="user-guide/6.9-dn.html">6.9 - Dn</a></li>
<li><a href="user-guide/6.10-dit-content-rule.html">6.10 - DITContentRule (e)</a></li>
Modified: websites/staging/directory/trunk/content/api/user-guide/6.7-control.html
==============================================================================
--- websites/staging/directory/trunk/content/api/user-guide/6.7-control.html (original)
+++ websites/staging/directory/trunk/content/api/user-guide/6.7-control.html Thu Dec 28 19:34:30 2017
@@ -184,7 +184,10 @@
}
h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style>
<h1 id="67-control">6.7 - Control (...)<a class="headerlink" href="#67-control" title="Permanent link">¶</a></h1>
-<p>A <em>LDAP</em> <em>Control</em> is an extension to an operation. It tells the server to do something aside the standard operation, or it let the server send back some information to the client.</p>
+<p>A <em>LDAP</em> <em>Control</em> is an extension to an operation. It tells the server to do something aside the standard operation, or it let the server send back some information to the client. A <em>Control</em> contains three different parts :
+<em> An identifier, the control </em>OID<em>
+</em> A flag telling the server what to do if it does not know about the control or if it results in an error (either return an error or ignore the control)
+<em> A value which is generally </em>BER* encoded</p>
<p>There are many controls available, some being standardized, other being server specific.</p>
<p>In any case, you can always add onr or more control to any operation. </p>
<p>Note that either the client or the server might not know about the controls being used.</p>
@@ -375,6 +378,76 @@ h2:hover > .headerlink, h3:hover > .head
</tr>
</tbody>
</table>
+<h2 id="how-to-use-controls">How to use controls<a class="headerlink" href="#how-to-use-controls" title="Permanent link">¶</a></h2>
+<p>It's quite simple. You just have to instanciate the control you want to use, set its value, and add it to the request you will send to the server. Here is an example with the <em>ManageDsaIT</em> control :</p>
+<div class="codehilite"><pre><span class="n">AddRequest</span> <span class="n">addRequest</span> <span class="o">=</span> <span class="k">new</span> <span class="n">AddRequestImpl</span><span class="o">();</span> <span class="c1">// Create the request</span>
+<span class="n">ManageDsaIT</span> <span class="n">manageDSAIT</span> <span class="o">=</span> <span class="k">new</span> <span class="n">ManageDsaITImpl</span><span class="o">();</span> <span class="c1">// Instanciate the control</span>
+<span class="n">manageDSAIT</span><span class="o">.</span><span class="na">setCritical</span><span class="o">(</span> <span class="kc">true</span> <span class="o">);</span> <span class="c1">// Set a value</span>
+<span class="n">addRequest</span><span class="o">.</span><span class="na">addControl</span><span class="o">(</span> <span class="n">manageDSAIT</span> <span class="o">);</span> <span class="c1">// Add the control to the request</span>
+<span class="o">...</span>
+</pre></div>
+
+
+<p>and that's it !</p>
+<p>On the client side, you may want to check if there is a control and read it if so. This is a bit more complex, because you need to know which kind of control you are expecting. We will see with a more complex control, the <em>Paged Search</em> control (which allows the user to get a specific number of enries at each call). Here, we will fetch 4 entries in one go, until all the entries have been read, and as we have 10 entries to read, we will send 3 <em>SearchRequest</em>, teh first two will return 4 entries and teh last one only 2.</p>
+<div class="codehilite"><pre><span class="k">try</span> <span class="o">(</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">"MyServer"</span><span class="o">,</span> <span class="mi">389</span> <span class="o">)</span> <span class="o">)</span>
+<span class="o">{</span>
+ <span class="n">connection</span><span class="o">.</span><span class="na">bind</span><span class="o">(</span> <span class="s">"cn=user,ou=system"</span><span class="o">,</span> <span class="s">"secret"</span> <span class="o">);</span>
+
+ <span class="c1">// Create the control, and tell it we want 4 entries for every call</span>
+ <span class="n">PagedResults</span> <span class="n">pagedControl</span> <span class="o">=</span> <span class="k">new</span> <span class="n">PagedResultsImpl</span><span class="o">();</span>
+ <span class="n">pagedControl</span><span class="o">.</span><span class="na">setSize</span><span class="o">(</span> <span class="mi">4</span> <span class="o">);</span>
+
+ <span class="c1">// Read all the elements</span>
+ <span class="n">List</span><span class="o"><</span><span class="n">Entry</span><span class="o">></span> <span class="n">results</span> <span class="o">=</span> <span class="k">new</span> <span class="n">ArrayList</span><span class="o"><>();</span>
+
+ <span class="c1">// Create the SearchRequest</span>
+ <span class="n">SearchRequest</span> <span class="n">searchRequest</span> <span class="o">=</span> <span class="k">new</span> <span class="n">SearchRequestImpl</span><span class="o">();</span>
+ <span class="n">searchRequest</span><span class="o">.</span><span class="na">setBase</span><span class="o">(</span> <span class="k">new</span> <span class="n">Dn</span><span class="o">(</span> <span class="s">"dc=users,ou=system"</span> <span class="o">)</span> <span class="o">);</span>
+ <span class="n">searchRequest</span><span class="o">.</span><span class="na">setFilter</span><span class="o">(</span> <span class="s">"(cn=*)"</span> <span class="o">);</span>
+ <span class="n">searchRequest</span><span class="o">.</span><span class="na">setScope</span><span class="o">(</span> <span class="n">SearchScope</span><span class="o">.</span><span class="na">SUBTREE</span> <span class="o">);</span>
+
+ <span class="k">while</span> <span class="o">(</span> <span class="kc">true</span> <span class="o">)</span>
+ <span class="o">{</span>
+ <span class="c1">// Add the PagedSearch control to teh SearchRequest</span>
+ <span class="n">searchRequest</span><span class="o">.</span><span class="na">addControl</span><span class="o">(</span> <span class="n">pagedControl</span> <span class="o">);</span>
+
+ <span class="c1">// Do the search now</span>
+ <span class="k">try</span> <span class="o">(</span> <span class="n">SearchCursor</span> <span class="n">cursor</span> <span class="o">=</span> <span class="n">connection</span><span class="o">.</span><span class="na">search</span><span class="o">(</span> <span class="n">searchRequest</span> <span class="o">)</span> <span class="o">)</span>
+ <span class="o">{</span>
+ <span class="c1">// Loop on all teh entries we got back (Should be 4, or less)</span>
+ <span class="k">while</span> <span class="o">(</span> <span class="n">cursor</span><span class="o">.</span><span class="na">next</span><span class="o">()</span> <span class="o">)</span>
+ <span class="o">{</span>
+ <span class="n">Entry</span> <span class="n">result</span> <span class="o">=</span> <span class="n">cursor</span><span class="o">.</span><span class="na">getEntry</span><span class="o">();</span>
+ <span class="n">results</span><span class="o">.</span><span class="na">add</span><span class="o">(</span> <span class="n">result</span> <span class="o">);</span>
+ <span class="o">}</span>
+
+ <span class="c1">// Now check the returned controls</span>
+ <span class="n">Map</span><span class="o"><</span><span class="n">String</span><span class="o">,</span> <span class="n">Control</span><span class="o">></span> <span class="n">controls</span> <span class="o">=</span> <span class="n">cursor</span><span class="o">.</span><span class="na">getSearchResultDone</span><span class="o">().</span><span class="na">getControls</span><span class="o">();</span>
+
+ <span class="c1">// We should get a PagedResult response</span>
+ <span class="n">PagedResults</span> <span class="n">responseControl</span> <span class="o">=</span> <span class="o">(</span> <span class="n">PagedResults</span> <span class="o">)</span> <span class="n">controls</span><span class="o">.</span><span class="na">get</span><span class="o">(</span> <span class="n">PagedResults</span><span class="o">.</span><span class="na">OID</span> <span class="o">);</span>
+
+ <span class="c1">// check if this is over, ie teh cookie is empty</span>
+ <span class="kt">byte</span><span class="o">[]</span> <span class="n">cookie</span> <span class="o">=</span> <span class="n">responseControl</span><span class="o">.</span><span class="na">getCookie</span><span class="o">();</span>
+
+ <span class="k">if</span> <span class="o">(</span> <span class="n">Strings</span><span class="o">.</span><span class="na">isEmpty</span><span class="o">(</span> <span class="n">cookie</span> <span class="o">)</span> <span class="o">)</span>
+ <span class="o">{</span>
+ <span class="c1">// Ok, we are done</span>
+ <span class="k">break</span><span class="o">;</span>
+ <span class="o">}</span>
+
+ <span class="c1">// Prepare the next iteration, sending a bad cookie</span>
+ <span class="n">pagedControl</span><span class="o">.</span><span class="na">setCookie</span><span class="o">(</span> <span class="n">cookie</span> <span class="o">);</span>
+ <span class="o">}</span>
+ <span class="o">}</span>
+
+ <span class="c1">// At this point, we should have read 10 entries</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>Side note : in this piece of code, we don't close the connection nor the cursor, because they are <em>Closeable</em> : They will be close when we exit the <em>try</em> scope. This is a feature added in <em>Java 7</em>, called <em>try with resources</em></p>
<div class="nav">