svn commit: r936610 - in /websites/staging/directory/trunk/content: ./ api/user-guide/2.6-modifying.html

[bu...@apache.org]

Author: buildbot
Date: Sun Jan 18 10:03:01 2015
New Revision: 936610

Log:
Staging update by buildbot for directory

Modified:
    websites/staging/directory/trunk/content/   (props changed)
    websites/staging/directory/trunk/content/api/user-guide/2.6-modifying.html

Propchange: websites/staging/directory/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Sun Jan 18 10:03:01 2015
@@ -1 +1 @@
-1652711
+1652721

Modified: websites/staging/directory/trunk/content/api/user-guide/2.6-modifying.html
==============================================================================
--- websites/staging/directory/trunk/content/api/user-guide/2.6-modifying.html (original)
+++ websites/staging/directory/trunk/content/api/user-guide/2.6-modifying.html Sun Jan 18 10:03:01 2015
@@ -292,7 +292,92 @@
 <p>Otherwise, the server might forbid you to modify the entry, due to the ACL that rules this entry.</p>
 <p>Last, not least, but this is quite obvious, the entry <em>must</em> exist !</p>
 <h2 id="adding-removing-or-replacing-attributes-values">Adding, removing or replacing attributes' values</h2>
-<p>TODO</p>
+<p>You can now update the attribute's values themselve, atomically, instead of brutally removing a full attribute, and add it back but with updated values. We use the exact same <em>Modification</em> instance, with the same three <em>ModificationOperation</em>, except that the semantic will slightly change.</p>
+<p>Typically, here is what happens when you use one of the three <em>ModificationOperation</em> on an attribute :</p>
+<ul>
+<li>ModificationOperation.ADD_ATTRIBUTE : add values in an attribute. If the ATtribute does not exist, it will be added</li>
+<li>ModificationOperation.REMOVE_ATTRIBUTE : remove values from an attribute.</li>
+<li>ModificationOperation.REPLACE_ATTRIBUTE : replace all the values from an attribute by the provided new values</li>
+</ul>
+<h3 id="add-values">Add values</h3>
+<p>Let's see with the addition of values. Here, we will assume we have an entry like :</p>
+<div class="codehilite"><pre><span class="n">dn</span><span class="o">:</span> <span class="n">uid</span><span class="o">=</span><span class="n">jDoe</span><span class="o">,</span><span class="n">dc</span><span class="o">=</span><span class="n">acme</span><span class="o">,</span><span class="n">dc</span><span class="o">=</span><span class="n">com</span>
+<span class="n">objectClass</span><span class="o">:</span> <span class="n">person</span>
+<span class="n">objectClass</span><span class="o">:</span> <span class="n">organizationalPerson</span>
+<span class="n">objectClass</span><span class="o">:</span> <span class="n">inetOrgPerson</span>
+<span class="n">uid</span><span class="o">:</span> <span class="n">jDoe</span>
+<span class="n">userPassword</span><span class="o">:</span> <span class="n">secret</span>
+<span class="n">sn</span><span class="o">:</span> <span class="n">John</span> <span class="n">Tom</span> <span class="n">Doe</span>
+<span class="n">cn</span><span class="o">:</span> <span class="n">Doe</span>
+<span class="n">givenName</span><span class="o">:</span> <span class="n">John</span>
+</pre></div>
+
+
+<p>We will add the 'Tom' given name to the <em>givenName</em> attribute in this entry :</p>
+<div class="codehilite"><pre><span class="o">...</span>
+<span class="n">Modification</span> <span class="n">addedGivenNameValue</span> <span class="o">=</span> <span class="k">new</span> <span class="n">DefaultModification</span><span class="o">(</span> <span class="n">ModificationOperation</span><span class="o">.</span><span class="na">ADD_ATTRIBUTE</span><span class="o">,</span> <span class="s">&quot;givenName&quot;</span><span class="o">,</span> <span class="s">&quot;Tom&quot;</span> <span class="o">);</span>
+
+<span class="n">connection</span><span class="o">.</span><span class="na">modify</span><span class="o">(</span> <span class="s">&quot;uid=Doe,dc=acme,dc=com&quot;</span><span class="o">,</span> <span class="n">addedGivenNameValue</span> <span class="o">);</span>
+<span class="o">...</span>
+</pre></div>
+
+
+<p>The entry now has two values for th <em>giveName</em> attribute :</p>
+<div class="codehilite"><pre><span class="n">dn</span><span class="o">:</span> <span class="n">uid</span><span class="o">=</span><span class="n">jDoe</span><span class="o">,</span><span class="n">dc</span><span class="o">=</span><span class="n">acme</span><span class="o">,</span><span class="n">dc</span><span class="o">=</span><span class="n">com</span>
+<span class="n">objectClass</span><span class="o">:</span> <span class="n">person</span>
+<span class="n">objectClass</span><span class="o">:</span> <span class="n">organizationalPerson</span>
+<span class="n">objectClass</span><span class="o">:</span> <span class="n">inetOrgPerson</span>
+<span class="n">uid</span><span class="o">:</span> <span class="n">jDoe</span>
+<span class="n">userPassword</span><span class="o">:</span> <span class="n">secret</span>
+<span class="n">sn</span><span class="o">:</span> <span class="n">John</span> <span class="n">Tom</span> <span class="n">Doe</span>
+<span class="n">cn</span><span class="o">:</span> <span class="n">Doe</span>
+<span class="n">givenName</span><span class="o">:</span> <span class="n">John</span>
+<span class="n">givenName</span><span class="o">:</span> <span class="n">Tom</span>
+</pre></div>
+
+
+<h4 id="errors_2">Errors</h4>
+<p>Again, such an operation might fail for many reasons. Let's see what are the possible errors :</p>
+<p>First, the attribute's value already exists. You will get such an error :</p>
+<div class="codehilite"><pre><span class="n">org</span><span class="p">.</span><span class="n">apache</span><span class="p">.</span><span class="n">directory</span><span class="p">.</span><span class="n">api</span><span class="p">.</span><span class="n">ldap</span><span class="p">.</span><span class="n">model</span><span class="p">.</span><span class="n">exception</span><span class="p">.</span><span class="n">LdapAttributeInUseException</span><span class="p">:</span> <span class="n">ATTRIBUTE_OR_VALUE_EXISTS</span><span class="p">:</span> <span class="n">failed</span> <span class="k">for</span> <span class="n">MessageType</span> <span class="p">:</span> 
+<span class="n">MODIFY_REQUEST</span>
+<span class="n">Message</span> <span class="n">ID</span> <span class="p">:</span> 5
+    <span class="n">Modify</span> <span class="n">Request</span>
+        <span class="n">Object</span> <span class="p">:</span> <span class="s">&#39;uid=admin,ou=system&#39;</span>
+            <span class="n">Modification</span><span class="p">[</span>0<span class="p">]</span>
+                <span class="n">Operation</span> <span class="p">:</span>  <span class="n">add</span>
+                <span class="n">Modification</span>
+                    <span class="n">givenName</span><span class="p">:</span> <span class="n">John</span>
+<span class="n">org</span><span class="p">.</span><span class="n">apache</span><span class="p">.</span><span class="n">directory</span><span class="p">.</span><span class="n">api</span><span class="p">.</span><span class="n">ldap</span><span class="p">.</span><span class="n">model</span><span class="p">.</span><span class="n">message</span><span class="p">.</span><span class="n">ModifyRequestImpl</span><span class="p">@</span>867<span class="n">e79fe</span><span class="p">:</span> <span class="n">ERR_54</span> <span class="n">Cannot</span> <span class="n">add</span> <span class="n">a</span> <span class="n">value</span> <span class="n">which</span> <span class="n">is</span> <span class="n">already</span> <span class="n">present</span> <span class="p">:</span> <span class="n">John</span>
+    <span class="n">at</span> <span class="n">org</span><span class="p">.</span><span class="n">apache</span><span class="p">.</span><span class="n">directory</span><span class="p">.</span><span class="n">api</span><span class="p">.</span><span class="n">ldap</span><span class="p">.</span><span class="n">model</span><span class="p">.</span><span class="n">message</span><span class="p">.</span><span class="n">ResultCodeEnum</span><span class="p">.</span><span class="n">processResponse</span><span class="p">(</span><span class="n">ResultCodeEnum</span><span class="p">.</span><span class="n">java</span><span class="p">:</span>2064<span class="p">)</span>
+    <span class="n">at</span> <span class="n">org</span><span class="p">.</span><span class="n">apache</span><span class="p">.</span><span class="n">directory</span><span class="p">.</span><span class="n">ldap</span><span class="p">.</span><span class="n">client</span><span class="p">.</span><span class="n">api</span><span class="p">.</span><span class="n">LdapNetworkConnection</span><span class="p">.</span><span class="n">modify</span><span class="p">(</span><span class="n">LdapNetworkConnection</span><span class="p">.</span><span class="n">java</span><span class="p">:</span>2300<span class="p">)</span>
+    <span class="n">at</span> <span class="n">org</span><span class="p">.</span><span class="n">apache</span><span class="p">.</span><span class="n">directory</span><span class="p">.</span><span class="n">ldap</span><span class="p">.</span><span class="n">client</span><span class="p">.</span><span class="n">api</span><span class="p">.</span><span class="n">LdapNetworkConnection</span><span class="p">.</span><span class="n">modify</span><span class="p">(</span><span class="n">LdapNetworkConnection</span><span class="p">.</span><span class="n">java</span><span class="p">:</span>2309<span class="p">)</span>
+    <span class="n">at</span> <span class="n">org</span><span class="p">.</span><span class="n">apache</span><span class="p">.</span><span class="n">directory</span><span class="p">.</span><span class="n">shared</span><span class="p">.</span><span class="n">client</span><span class="p">.</span><span class="n">api</span><span class="p">.</span><span class="n">operations</span><span class="p">.</span><span class="n">ClientModifyRequestTest</span><span class="p">.</span><span class="n">testModifyRemoveAttribute</span><span class="p">(</span><span class="n">ClientModifyRequestTest</span><span class="p">.</span><span class="n">java</span><span class="p">:</span>303<span class="p">)</span>
+</pre></div>
+
+
+<p>Note that depending on the attribute's syntax, you may get such an error because you tried to enter a value with different casing when the syntax is case insensitive. Typically, if the attribute contains the value 'John' and you try to add the value 'JOHN', you will get this very same error message. Be sure you know wht the attribute syntax allows you to do...</p>
+<p>Second, the attribute is single valued : it's not possible to add a second value in the Attribute. You'll get the following error message :</p>
+<div class="codehilite"><pre><span class="n">org</span><span class="p">.</span><span class="n">apache</span><span class="p">.</span><span class="n">directory</span><span class="p">.</span><span class="n">api</span><span class="p">.</span><span class="n">ldap</span><span class="p">.</span><span class="n">model</span><span class="p">.</span><span class="n">exception</span><span class="p">.</span><span class="n">LdapInvalidAttributeValueException</span><span class="p">:</span> <span class="n">CONSTRAINT_VIOLATION</span><span class="p">:</span> <span class="n">failed</span> <span class="k">for</span> <span class="n">MessageType</span> <span class="p">:</span> <span class="n">MODIFY_REQUEST</span>
+<span class="n">Message</span> <span class="n">ID</span> <span class="p">:</span> 3
+    <span class="n">Modify</span> <span class="n">Request</span>
+        <span class="n">Object</span> <span class="p">:</span> <span class="s">&#39;c=FR,ou=users,ou=system&#39;</span>
+            <span class="n">Modification</span><span class="p">[</span>0<span class="p">]</span>
+                <span class="n">Operation</span> <span class="p">:</span>  <span class="n">add</span>
+                <span class="n">Modification</span>
+                    <span class="n">c</span><span class="p">:</span> <span class="n">US</span>
+<span class="n">org</span><span class="p">.</span><span class="n">apache</span><span class="p">.</span><span class="n">directory</span><span class="p">.</span><span class="n">api</span><span class="p">.</span><span class="n">ldap</span><span class="p">.</span><span class="n">model</span><span class="p">.</span><span class="n">message</span><span class="p">.</span><span class="n">ModifyRequestImpl</span><span class="p">@</span><span class="n">cdf2ed2f</span><span class="p">:</span> <span class="n">ERR_278</span> <span class="n">More</span> <span class="n">than</span> <span class="n">one</span> <span class="n">value</span> <span class="n">has</span> <span class="n">been</span> <span class="n">provided</span> <span class="k">for</span> <span class="n">the</span> <span class="n">single</span><span class="o">-</span><span class="n">valued</span> <span class="n">attribute</span><span class="p">:</span> <span class="n">c</span>
+    <span class="n">at</span> <span class="n">org</span><span class="p">.</span><span class="n">apache</span><span class="p">.</span><span class="n">directory</span><span class="p">.</span><span class="n">api</span><span class="p">.</span><span class="n">ldap</span><span class="p">.</span><span class="n">model</span><span class="p">.</span><span class="n">message</span><span class="p">.</span><span class="n">ResultCodeEnum</span><span class="p">.</span><span class="n">processResponse</span><span class="p">(</span><span class="n">ResultCodeEnum</span><span class="p">.</span><span class="n">java</span><span class="p">:</span>2127<span class="p">)</span>
+    <span class="n">at</span> <span class="n">org</span><span class="p">.</span><span class="n">apache</span><span class="p">.</span><span class="n">directory</span><span class="p">.</span><span class="n">ldap</span><span class="p">.</span><span class="n">client</span><span class="p">.</span><span class="n">api</span><span class="p">.</span><span class="n">LdapNetworkConnection</span><span class="p">.</span><span class="n">modify</span><span class="p">(</span><span class="n">LdapNetworkConnection</span><span class="p">.</span><span class="n">java</span><span class="p">:</span>2300<span class="p">)</span>
+    <span class="n">at</span> <span class="n">org</span><span class="p">.</span><span class="n">apache</span><span class="p">.</span><span class="n">directory</span><span class="p">.</span><span class="n">ldap</span><span class="p">.</span><span class="n">client</span><span class="p">.</span><span class="n">api</span><span class="p">.</span><span class="n">LdapNetworkConnection</span><span class="p">.</span><span class="n">modify</span><span class="p">(</span><span class="n">LdapNetworkConnection</span><span class="p">.</span><span class="n">java</span><span class="p">:</span>2309<span class="p">)</span>
+    <span class="n">at</span> <span class="n">org</span><span class="p">.</span><span class="n">apache</span><span class="p">.</span><span class="n">directory</span><span class="p">.</span><span class="n">shared</span><span class="p">.</span><span class="n">client</span><span class="p">.</span><span class="n">api</span><span class="p">.</span><span class="n">operations</span><span class="p">.</span><span class="n">ClientModifyRequestTest</span><span class="p">.</span><span class="n">testModifyRemoveAttribute</span><span class="p">(</span><span class="n">ClientModifyRequestTest</span><span class="p">.</span><span class="n">java</span><span class="p">:</span>297<span class="p">)</span>
+</pre></div>
+
+
+<p>Third, the ACLs you have set on the server may not allow you to update an entry or an attribute.</p>
+<p>Last, not least, the entry must exist...</p>
+<h3 id="remove-values">Remove values</h3>
+<p>TODO...</p>
 
 
     <div class="nav">