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/17 19:34:02 UTC
svn commit: r936554 - in /websites/staging/directory/trunk/content: ./
api/user-guide/2.6-modifying.html
Author: buildbot
Date: Sat Jan 17 18:34:02 2015
New Revision: 936554
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 Sat Jan 17 18:34:02 2015
@@ -1 +1 @@
-1652141
+1652653
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 Sat Jan 17 18:34:02 2015
@@ -167,7 +167,86 @@
</div>
-<h1 id="26-modifying-entries-e">2.6 - Modifying entries (e)</h1>
+<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>
+<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>
+<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>
+<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>
+<li>ModificationOperation.REPLACE_ATTRIBUTE : replace some existing values from an entry</li>
+</ul>
+<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>
+<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>
+
+<span class="n">connection</span><span class="o">.</span><span class="na">modify</span><span class="o">(</span> <span class="s">"uid=Doe,dc=acme,dc=com"</span><span class="o">,</span> <span class="n">addedGivenName</span> <span class="o">);</span>
+<span class="o">...</span>
+</pre></div>
+
+
+<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>
+<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>
+<span class="n">Modification</span> <span class="n">addedInitials</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">"initials"</span><span class="o">,</span>
+ <span class="s">"JD"</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">"uid=Doe,dc=acme,dc=com"</span><span class="o">,</span> <span class="n">addedGivenName</span><span class="o">,</span> <span class="n">addedInitials</span> <span class="o">);</span>
+<span class="o">...</span>
+</pre></div>
+
+
+<p>You can add as many <em>Modification</em> instances as needed.</p>
+<h4 id="errors">Errors</h4>
+<p>If you try to add an attribute that already exists, you will get an error, like this one :</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>
+<span class="n">Modification</span> <span class="n">addedUid</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">"uid"</span><span class="o">,</span>
+ <span class="s">"Ted"</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">"uid=Doe,dc=acme,dc=com"</span><span class="o">,</span> <span class="n">addedGivenName</span><span class="o">,</span> <span class="n">addedUid</span> <span class="o">);</span>
+<span class="o">...</span>
+</pre></div>
+
+
+<p>results in :
+ org.apache.directory.api.ldap.model.exception.LdapAttributeInUseException: ATTRIBUTE_OR_VALUE_EXISTS: failed for MessageType : MODIFY_REQUEST
+ Message ID : 3
+ Modify Request
+ Object : 'uid=Doe,dc=acme,dc=com'
+ Modification[0]
+ Operation : add
+ Modification
+ givenName: John
+ givenName: Peter <br />
+ Modification[1]
+ Operation : add
+ Modification
+ uid: Ted
+ org.apache.directory.api.ldap.model.message.ModifyRequestImpl@13532916: ERR_54 Cannot add a value which is already present : admin
+ at org.apache.directory.api.ldap.model.message.ResultCodeEnum.processResponse(ResultCodeEnum.java:2064)
+ at org.apache.directory.ldap.client.api.LdapNetworkConnection.modify(LdapNetworkConnection.java:2300)
+ at org.apache.directory.ldap.client.api.LdapNetworkConnection.modify(LdapNetworkConnection.java:2309)
+ ...</p>
+<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>Last, not least, but this is quite obvious, the entry <em>must</em> exist !</p>
+<h3 id="removing-an-attribute">Removing an attribute</h3>
<div class="nav">