directory-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r1022862 - in /websites/staging/directory/trunk/content: ./ api/user-guide/6.7-control.html
Date Fri, 29 Dec 2017 03:17:56 GMT
Author: buildbot
Date: Fri Dec 29 03:17:56 2017
New Revision: 1022862

Log:
Staging update by buildbot for directory

Modified:
    websites/staging/directory/trunk/content/   (props changed)
    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 Fri Dec 29 03:17:56 2017
@@ -1 +1 @@
-1819438
+1819462

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 Fri Dec 29 03:17:56
2017
@@ -184,13 +184,15 @@
 }
 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. 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>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 :</p>
+<ul>
+<li>An identifier, the control <em>OID</em></li>
+<li>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)</li>
+<li>A value which is generally <em>BER</em> encoded</li>
+</ul>
 <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>
+<p>One or more control can be added to any operation. </p>
+<p>Note that either the client or the server might not know about the controls being
used, and if the <em>criticality</em> flag is set to <em>FALSE</em>,
the server will ignore the control in this case.</p>
 <h2 id="managed-controls">Managed controls<a class="headerlink" href="#managed-controls"
title="Permanent link">&para;</a></h2>
 <p>Here is the list of <em>control</em>s the LDAP API currently know about.
The following short names are used to name the LDAP Servers that support each control.</p>
 <ul>
@@ -389,7 +391,8 @@ h2:hover > .headerlink, h3:hover > .head
 
 
 <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>
+<p>Note that you have to create an instance of teh operation you want to send to the
server, if yu want to add a control to 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 the 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>
@@ -409,36 +412,49 @@ h2:hover > .headerlink, h3:hover > .head
 
     <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="c1">// Add the PagedSearch control to the 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="c1">// Loop on all the 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">// Check if we have reached the size limit</span>
+            <span class="k">if</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">getLdapResult</span><span class="o">().</span><span
class="na">getResultCode</span><span class="o">()</span> <span class="o">==</span>
<span class="n">ResultCodeEnum</span><span class="o">.</span><span
class="na">SIZE_LIMIT_EXCEEDED</span> <span class="o">)</span>
+            <span class="o">{</span>
+                <span class="k">break</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">responseControl</span> <span class="o">!=</span> <span class="kc">null</span>
<span class="o">)</span>
+            <span class="o">{</span>
+                <span class="c1">// check if this is over, ie the 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="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="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="k">else</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>
 
@@ -447,7 +463,112 @@ h2:hover > .headerlink, h3:hover > .head
 </pre></div>
 
 
+<p>This sounds like a bit complex, but actually, this control is complex. What we are
interested in is the way we get the control returned by the server. In this case, the control
we are interested in is attached to the <em>SearchResultDone</em> response, which
is the last result we have when reading the cursor. As we may have more than one control,
the response conains a <em>Map</em> of controls, ot of which we should be able
to retreive the <em>PagedSearch</em> control from its <em>OID</em>.
This is what does this piece of code :</p>
+<div class="codehilite"><pre>            <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="o">...</span>
+</pre></div>
+
+
+<p>If it's not null, we can proceed with the control.</p>
 <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>
+<h2 id="managed-controls-detail">Managed Controls detail<a class="headerlink" href="#managed-controls-detail"
title="Permanent link">&para;</a></h2>
+<h3 id="addirsync">AdDirSync<a class="headerlink" href="#addirsync" title="Permanent
link">&para;</a></h3>
+<p>A control used to initiate a synchronization with an <em>Active Directory</em>
server, and get back the results. Check <a href="https://tools.ietf.org/html/draft-armijo-ldap-dirsync-01">Microsoft
LDAP Control for Directory Synchronization</a> for a better understanding on how to
use this control.</p>
+<ul>
+<li>OID : 1.2.840.113556.1.4.841</li>
+<li>Criticality : TRUE</li>
+<li>ASN.1 description :</li>
+</ul>
+<p>Sent to the server :</p>
+<div class="codehilite"><pre>realReplControlValue ::= SEQUENCE {
+    flags                 integer
+    maxBytes              integer
+    cookie                OCTET STRING
+}
+</pre></div>
+
+
+<p>This control is only valid when send with a <em>SearchRequest</em>.
</p>
+<p>Received from the server :</p>
+<div class="codehilite"><pre>realReplControlValue ::= SEQUENCE {
+    flag                  integer
+    maxReturnLength       integer
+    cookie                OCTET STRING
+}
+</pre></div>
+
+
+<p>The cookie read from this control has to be injected in the control sent to the
server for the next search.</p>
+<h3 id="adpolicyhints">AdPolicyHints<a class="headerlink" href="#adpolicyhints"
title="Permanent link">&para;</a></h3>
+<ul>
+<li>OID : 1.2.840.113556.1.4.223</li>
+</ul>
+<h3 id="adshowdeleted">AdShowDeleted<a class="headerlink" href="#adshowdeleted"
title="Permanent link">&para;</a></h3>
+<ul>
+<li>OID : 1.2.840.113556.1.4.417</li>
+</ul>
+<h3 id="cascade">Cascade<a class="headerlink" href="#cascade" title="Permanent link">&para;</a></h3>
+<ul>
+<li>OID : 1.3.6.1.4.1.18060.0.0.1</li>
+</ul>
+<h3 id="entrychange">EntryChange<a class="headerlink" href="#entrychange" title="Permanent
link">&para;</a></h3>
+<ul>
+<li>OID : 2.16.840.1.113730.3.4.7</li>
+</ul>
+<h3 id="managedsait">ManageDSAIT<a class="headerlink" href="#managedsait" title="Permanent
link">&para;</a></h3>
+<ul>
+<li>OID : 2.16.840.1.113730.3.4.2</li>
+</ul>
+<h3 id="passwordpolicy">PasswordPolicy<a class="headerlink" href="#passwordpolicy"
title="Permanent link">&para;</a></h3>
+<ul>
+<li>OID : 1.3.6.1.4.1.42.2.27.8.5.1</li>
+</ul>
+<h3 id="permissivemodify">PermissiveModify<a class="headerlink" href="#permissivemodify"
title="Permanent link">&para;</a></h3>
+<ul>
+<li>OID : 1.2.840.113556.1.4.1413</li>
+</ul>
+<h3 id="persistentsearch">PersistentSearch<a class="headerlink" href="#persistentsearch"
title="Permanent link">&para;</a></h3>
+<ul>
+<li>OID : 2.16.840.1.113730.3.4.3</li>
+</ul>
+<h3 id="proxiedauthz">ProxiedAuthz<a class="headerlink" href="#proxiedauthz" title="Permanent
link">&para;</a></h3>
+<ul>
+<li>OID : 2.16.840.1.113730.3.4.18</li>
+</ul>
+<h3 id="sortrequest">SortRequest<a class="headerlink" href="#sortrequest" title="Permanent
link">&para;</a></h3>
+<ul>
+<li>OID : 1.2.840.113556.1.4.473</li>
+</ul>
+<h3 id="sortresponse">SortResponse<a class="headerlink" href="#sortresponse" title="Permanent
link">&para;</a></h3>
+<ul>
+<li>OID : 1.2.840.113556.1.4.474</li>
+</ul>
+<h3 id="subentries">Subentries<a class="headerlink" href="#subentries" title="Permanent
link">&para;</a></h3>
+<ul>
+<li>OID : 1.3.6.1.4.1.4203.1.10.1</li>
+</ul>
+<h3 id="syncdonevalue">SyncDoneValue<a class="headerlink" href="#syncdonevalue"
title="Permanent link">&para;</a></h3>
+<ul>
+<li>OID : 1.3.6.1.4.1.4203.1.9.1.3</li>
+</ul>
+<h3 id="syncrequestvalue">SyncRequestValue<a class="headerlink" href="#syncrequestvalue"
title="Permanent link">&para;</a></h3>
+<ul>
+<li>OID : 1.3.6.1.4.1.4203.1.9.1.1</li>
+</ul>
+<h3 id="syncstatevalue">SyncStateValue<a class="headerlink" href="#syncstatevalue"
title="Permanent link">&para;</a></h3>
+<ul>
+<li>OID : 1.3.6.1.4.1.4203.1.9.1.2</li>
+</ul>
+<h3 id="virtuallistviewrequest">VirtualListViewRequest<a class="headerlink" href="#virtuallistviewrequest"
title="Permanent link">&para;</a></h3>
+<ul>
+<li>OID : 2.16.840.1.113730.3.4.9</li>
+</ul>
+<h3 id="virtuallistviewresponse">VirtualListViewResponse<a class="headerlink" href="#virtuallistviewresponse"
title="Permanent link">&para;</a></h3>
+<ul>
+<li>OID : 2.16.840.1.113730.3.4.10</li>
+</ul>
 
 
     <div class="nav">



Mime
View raw message