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 2015/01/18 12:16:52 UTC
svn commit: r936616 - in /websites/staging/directory/trunk/content: ./
api/user-guide/2.6-modifying.html
Author: buildbot
Date: Sun Jan 18 11:16:52 2015
New Revision: 936616
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 11:16:52 2015
@@ -1 +1 @@
-1652721
+1652736
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 11:16:52 2015
@@ -168,16 +168,16 @@
<h1 id="26-modifying-entries">2.6 - Modifying entries</h1>
-<p>There are several ways an entry can be modified. Mainly, it's about adding or deleting an attribute, or it's about modifying the values associated with an existing attribute. We will expose the methods that can be used for those two main cases.</p>
-<p>It's important to understand that you can apply many modifications to a single entry, too. All those modifications will be effective as if the entry was modified as a whole, ie the modifications will be fully applied, or none of the modifications will be applied (for instance, if teh server crashes while applying the modifications, it's guaranteed that the entry will remain consistent, and if one of the modifications is invalid, then no modification will be applied)</p>
+<p>There are several ways an entry can be modified. Mainly, it's about adding or deleting an attribute, or it's about modifying the values associated with an existing attribute.</p>
+<p>It's important to understand that many modifications can be applied on a single entry. All those modifications will be applied in a all or none fashion. For instance, if any one of the modifications is invalid, then none of the modifications will be applied. Also if the server crashes while applying the modifications, it's guaranteed that the entry will remain consistent.</p>
<h2 id="how-it-works">How it works ?</h2>
-<p>As we may have more than one modification, we use an intermediate class to carry the elements to be changed : a <em>Modification</em> instance. You create such an instance this way :</p>
+<p>Each modification to be applied on an entry is encapsulated in an intermediate class : a <em>Modification</em> instance, which can be created as :</p>
<div class="codehilite"><pre><span class="n">Modification</span> <span class="n">addedGivenName</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">"givenName"</span><span class="o">,</span> <span class="s">"John"</span><span class="o">,</span> <span class="s">"Peter"</span> <span class="o">);</span>
</pre></div>
-<p>Here, we just have created an instance that will add the <em>giveName</em> attribute, with the "John" and "Peter" values (the <em>givenName</em> attribute can have more than one value).</p>
-<p>There are three different kind of modification :</p>
+<p>Here, the modification instance represents addition of values "John" and "Peter" to the <em>giveName</em> attribute (the <em>givenName</em> attribute can have more than one value).</p>
+<p>There are three different kind of modifications :</p>
<ul>
<li>ModificationOperation.ADD_ATTRIBUTE : add an attribute and values to an entry</li>
<li>ModificationOperation.REMOVE_ATTRIBUTE : remove an attribute and values from an entry</li>
@@ -186,7 +186,7 @@
<h2 id="adding-or-removing-full-attributes">Adding or removing full attributes</h2>
<p>The two following operations are dealing with complete addition or removal of attributes.</p>
<h3 id="adding-new-attributes">Adding new attributes</h3>
-<p>First of all, let's see haw we proceed when it comes to add an attribute. You need to know the entry you want to modify, which means you have its Dn. Then, you have to create the <em>Modification</em> instance that will be applied on the entry. Here is the code that is used to add a <em>givenName</em> attribute to an existing entry :</p>
+<p>First of all, let's see how we proceed when it comes to adding an attribute. You need to know the entry you want to modify, which means you have to know its Dn. Then, you have to create the <em>Modification</em> instance that will be applied on the entry. Here is the code that is used to add a <em>givenName</em> attribute to an existing entry :</p>
<div class="codehilite"><pre><span class="o">...</span>
<span class="n">Modification</span> <span class="n">addedGivenName</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">"givenName"</span><span class="o">,</span>
<span class="s">"John"</span><span class="o">,</span> <span class="s">"Peter"</span> <span class="o">);</span>
@@ -198,7 +198,7 @@
<h4 id="adding-more-than-one-attribute">Adding more than one attribute</h4>
<p>What if you want to apply more than one modification to the entry ?</p>
-<p>Easy : create more than one <em>Modification</em> instances, and add them when calling the <em>modify</em> method :</p>
+<p>Easy : create more than one <em>Modification</em> instance, and add them before calling the <em>modify</em> method :</p>
<div class="codehilite"><pre><span class="o">...</span>
<span class="n">Modification</span> <span class="n">addedGivenName</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">"givenName"</span><span class="o">,</span>
<span class="s">"John"</span><span class="o">,</span> <span class="s">"Peter"</span> <span class="o">);</span>
@@ -246,11 +246,12 @@
</pre></div>
-<p>Here, we have tried to add the <em>uid</em> attribute which already exists, and the error trace says so.</p>
-<p>Anothe potential error you can get is when you try to add an attribute that is not allowed in an entry. This can be because the Entry ObjectClass does not allow such an attribute to be added, or because the server forbid you to modify the entry, due to the ACL that rules this entry.</p>
+<p>Here, we have tried to add the <em>uid</em> attribute which already exists, and the error trace says so
+as expected.</p>
+<p>Anothe potential error you can get is when you try to add an attribute that is not allowed in an entry. This can be because the Entry's ObjectClass does not allow such an attribute, or because the server forbid you to modify the entry, due to the ACIs applied on this entry.</p>
<p>Last, not least, but this is quite obvious, the entry <em>must</em> exist !</p>
<h3 id="removing-an-attribute">Removing an attribute</h3>
-<p>Removing an attribute is actually a bit simpler than adding an attribute, as you don't have to specify the values of the attribute to remove. Here is an exemple where we will remove the <em>giveName</em> attrinute from an entry :</p>
+<p>Removing an attribute is actually a bit simpler than adding an attribute, as you don't have to specify the values of the attribute to remove. Here is an example where we will remove the <em>giveName</em> attrinute from an entry :</p>
<div class="codehilite"><pre><span class="o">...</span>
<span class="n">Modification</span> <span class="n">deletedGivenName</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">REMOVE_ATTRIBUTE</span><span class="o">,</span> <span class="s">"givenName"</span> <span class="o">);</span>
@@ -289,13 +290,13 @@
<p>Here, the entry does not contain the <em>givenName</em> attribute.</p>
<p>Anothe potential error you can get is when you try to remove an attribute which is a mandatory attribute, per the entry's ObjectClass constraints.</p>
-<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>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>Otherwise, the server might forbid you to modify the entry, due to the ACIs that are applicable to this entry.</p>
+<p>Again the entry <em>must</em> exist before performing a modification!</p>
+<h2 id="adding-removing-or-replacing-attribute-values">Adding, removing or replacing attribute values</h2>
+<p>You can now update an attribute's values themselves, atomically, instead of 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 semantics slightly differ.</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.ADD_ATTRIBUTE : add values to 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>
@@ -356,7 +357,7 @@
</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>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
@@ -374,8 +375,7 @@
</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>
+<p>Third, the ACIs you have set on the server may not allow you to update an entry or an attribute.</p>
<h3 id="remove-values">Remove values</h3>
<p>TODO...</p>