directory-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject svn commit: r1022853 - in /websites/staging/directory/trunk/content: ./ api/user-guide.html api/user-guide/6.7-control.html
Date Thu, 28 Dec 2017 19:34:30 GMT
Author: buildbot
Date: Thu Dec 28 19:34:30 2017
New Revision: 1022853

Staging update by buildbot for directory

    websites/staging/directory/trunk/content/   (props changed)

Propchange: websites/staging/directory/trunk/content/
--- cms:source-revision (original)
+++ cms:source-revision Thu Dec 28 19:34:30 2017
@@ -1 +1 @@

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
@@ -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">&para;</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
@@ -375,6 +378,76 @@ h2:hover > .headerlink, h3:hover > .head
+<h2 id="how-to-use-controls">How to use controls<a class="headerlink" href="#how-to-use-controls"
title="Permanent link">&para;</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>
+<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">&quot;MyServer&quot;</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">&quot;cn=user,ou=system&quot;</span><span
class="o">,</span> <span class="s">&quot;secret&quot;</span>
<span class="o">);</span>
+    <span class="c1">// Create the control, and tell it we want 4 entries for every
+    <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
+    <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">&lt;</span><span
class="n">Entry</span><span class="o">&gt;</span> <span class="n">results</span>
<span class="o">=</span> <span class="k">new</span> <span class="n">ArrayList</span><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
+    <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">&quot;dc=users,ou=system&quot;</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">&quot;(cn=*)&quot;</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
+            <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">&lt;</span><span
class="n">String</span><span class="o">,</span> <span class="n">Control</span><span
class="o">&gt;</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>
+<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">

View raw message