svn commit: r1022886 - in /websites/staging/directory/trunk/content: ./ api/user-guide/6.7-control.html

[bu...@apache.org]

Author: buildbot
Date: Fri Dec 29 18:48:58 2017
New Revision: 1022886

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 18:48:58 2017
@@ -1 +1 @@
-1819466
+1819503

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 18:48:58 2017
@@ -525,6 +525,53 @@ h2:hover > .headerlink, h3:hover > .head
 <ul>
 <li>OID : 2.16.840.1.113730.3.4.2</li>
 </ul>
+<p>This is oe of the simplest control : it has no value, and he criticality flag may be absent. </p>
+<p>It's used to get access to special objects, like <em>referrals</em> or <em>subentries</em> as normal objects. Let's see what that means for <em>referrals</em>.</p>
+<p>A  <em>Referral</em> is a special object which once returned to the client, will automatically will redirect the client to another part of teh <em>DIT</em> (or to another <em>LDAP</em> server). So to speak, the end user does not see the <em>referral</em>, but the reffered entry. The question is : how do we set a <em>referral</em>, or how do we modify it ? We use the <em>ManageDsaIT</em> control.</p>
+<p>Let say we have such an entry, which is actually a referal :</p>
+<div class="codehilite"><pre>dn: uid=entryRef,ou=users,dc=acme,dc=com
+objectClass: extensibleObject
+objectClass: referral
+objectClass: top
+uid: entryref&quot;
+ref: ldap://localhost:10389/uid=entry,ou=users,dc=acme,dc=com
+ref: ldap://trust:10389/uid=entry,ou=users,dc=trust,dc=com
+</pre></div>
+
+
+<p>A client searchingg for <em>uid=entryRef,ou=users,dc=acme,dc=com</em> will be redirected to <em>uid=entry,ou=users,dc=acme,dc=com</em> on the local server or on <em>uid=entry,ou=users,dc=trust,dc=com</em> on the <em>trust</em> server (it's up to the client to decide which entry to fetch).</p>
+<p>If we want to modify this referral, we need to add the <em>ManageDsaIT</em> control :</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">// modify the referral </span>
+    <span class="n">ModifyRequest</span> <span class="n">modifyRequest</span> <span class="o">=</span> <span class="k">new</span> <span class="n">ModifyRequestImpl</span><span class="o">();</span>
+    <span class="n">modifyRequest</span><span class="o">.</span><span class="na">setName</span><span class="o">(</span> <span class="k">new</span> <span class="n">Dn</span><span class="o">(</span> <span class="s">&quot;uid=entryRef,ou=users,dc=acme,dc=com&quot;</span> <span class="o">)</span> <span class="o">);</span>
+    <span class="n">modifyRequest</span><span class="o">.</span><span class="na">add</span><span class="o">(</span> <span class="s">&quot;ref&quot;</span><span class="o">,</span> <span class="s">&quot;ldap://subsidiary:10389/uid=entry,ou=users,dc=subsidiary,dc=com&quot;</span> <span class="o">);</span>
+
+    <span class="c1">// Add the control</span>
+    <span class="n">modifyRequest</span><span class="o">.</span><span class="na">addControl</span><span class="o">(</span> <span class="k">new</span> <span class="n">ManageDsaITImpl</span><span class="o">()</span> <span class="o">);</span>
+
+    <span class="c1">// And apply the modification</span>
+    <span class="n">connection</span><span class="o">.</span><span class="na">modify</span><span class="o">(</span> <span class="n">modifyRequest</span> <span class="o">);</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>Now, if we fetch the entry (still using the control), it will looks like :</p>
+<div class="codehilite"><pre>dn: uid=entryRef,ou=users,dc=acme,dc=com
+objectClass: extensibleObject
+objectClass: referral
+objectClass: top
+uid: entryref&quot;
+ref: ldap://localhost:10389/uid=entry,ou=users,dc=acme,dc=com
+ref: ldap://trust:10389/uid=entry,ou=users,dc=trust,dc=com
+ref: ldap://subsidiary:10389/uid=entry,ou=users,dc=subsidiary,dc=com
+</pre></div>
+
+
+<p>As you can see, a third <em>ref</em> value has been added.</p>
 <h3 id="pagedresults">PagedResults<a class="headerlink" href="#pagedresults" title="Permanent link">&para;</a></h3>
 <ul>
 <li>OID : 1.2.840.113556.1.4.319</li>