directory-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r936554 - in /websites/staging/directory/trunk/content: ./ api/user-guide/2.6-modifying.html
Date Sat, 17 Jan 2015 18:34:02 GMT
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">&quot;givenName&quot;</span><span class="o">,</span>
<span class="s">&quot;John&quot;</span><span class="o">,</span>
<span class="s">&quot;Peter&quot;</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">&quot;givenName&quot;</span><span class="o">,</span>
+    <span class="s">&quot;John&quot;</span><span class="o">,</span>
<span class="s">&quot;Peter&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">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">&quot;givenName&quot;</span><span class="o">,</span>
+    <span class="s">&quot;John&quot;</span><span class="o">,</span>
<span class="s">&quot;Peter&quot;</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">&quot;initials&quot;</span><span class="o">,</span>
+    <span class="s">&quot;JD&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">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">&quot;givenName&quot;</span><span class="o">,</span>
+    <span class="s">&quot;John&quot;</span><span class="o">,</span>
<span class="s">&quot;Peter&quot;</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">&quot;uid&quot;</span><span class="o">,</span>
+    <span class="s">&quot;Ted&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">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">



Mime
View raw message