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 2016/12/31 02:55:54 UTC
svn commit: r1003807 - in /websites/staging/directory/trunk/content: ./ api/
api/user-guide/
Author: buildbot
Date: Sat Dec 31 02:55:54 2016
New Revision: 1003807
Log:
Staging update by buildbot for directory
Modified:
websites/staging/directory/trunk/content/ (props changed)
websites/staging/directory/trunk/content/api/user-guide.html
websites/staging/directory/trunk/content/api/user-guide/2.1-connection-disconnection.html
websites/staging/directory/trunk/content/api/user-guide/2.2-binding-unbinding.html
websites/staging/directory/trunk/content/api/user-guide/2.3-searching.html
websites/staging/directory/trunk/content/api/user-guide/2.4-adding.html
websites/staging/directory/trunk/content/api/user-guide/2.5-deleting.html
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 Dec 31 02:55:54 2016
@@ -1 +1 @@
-1776673
+1776679
Modified: websites/staging/directory/trunk/content/api/user-guide.html
==============================================================================
--- websites/staging/directory/trunk/content/api/user-guide.html (original)
+++ websites/staging/directory/trunk/content/api/user-guide.html Sat Dec 31 02:55:54 2016
@@ -167,10 +167,9 @@ h2:hover > .headerlink, h3:hover > .head
<h1 id="users-guide">Users guide<a class="headerlink" href="#users-guide" title="Permanent link">¶</a></h1>
<DIV class="note" markdown="1">
<strong>Work in progress</strong>
-
- * Pages with a (e) at the end of the title are empty pages.
- * Pages with a (...) at the end of the title are not yet completed.
- * Other pages are finished (but may be reviewed)
+Pages with a (e) at the end of the title are empty pages.
+Pages with a (...) at the end of the title are not yet completed.
+Other pages are finished (but may be reviewed).
</DIV>
<p>This document is about the LDAP API, developed at the Apache Software Foundation. It's a replacement for outdated Java/LDAP libraries like (<a href="http://www.openldap.org/jldap/">jLdap</a>, <a href="http://www.mozilla.org/directory/">Mozilla LDAP SDK</a> and <a href="http://www.oracle.com/technetwork/java/jndi/index.html">JNDI</a>).</p>
Modified: websites/staging/directory/trunk/content/api/user-guide/2.1-connection-disconnection.html
==============================================================================
--- websites/staging/directory/trunk/content/api/user-guide/2.1-connection-disconnection.html (original)
+++ websites/staging/directory/trunk/content/api/user-guide/2.1-connection-disconnection.html Sat Dec 31 02:55:54 2016
@@ -184,26 +184,26 @@
}
h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style>
<h1 id="21-connection-and-disconnection">2.1 - Connection and disconnection<a class="headerlink" href="#21-connection-and-disconnection" title="Permanent link">¶</a></h1>
-<p><strong>LDAP</strong> is a protocol which requires the user to be connected - and likely identified - in order to be able to send requests to the server. We maintain this connection potentially forever. What make the <strong>LDAP</strong> protocol different from, say, the <strong>HTTP</strong> protocol is that the connection must be issued explicitly. Let's see how we do that.</p>
+<p><strong>LDAP</strong> is a protocol which requires users to be connected - and likely identified (authenticated) - before sending requests to the server. This connection can potentially be maintained forever. What makes the <strong>LDAP</strong> protocol different from, say, the <strong>HTTP</strong> protocol is that the connections are issued explicitly. Here's we'll see how that is done.</p>
<h2 id="opening-a-connection">Opening a connection<a class="headerlink" href="#opening-a-connection" title="Permanent link">¶</a></h2>
<p>We can open a secure or a standard connection. </p>
<h3 id="standard-connection">Standard connection<a class="headerlink" href="#standard-connection" title="Permanent link">¶</a></h3>
-<p>We can first establish a standard connection, where the data are sent and received in clear text (encoded in ASN.1 BER, but still not encrypted). This example expose the way it's done :</p>
+<p>We can first establish a standard connection, where the data is sent and received in clear text (encoded in ASN.1 BER, but not encrypted). This example shows how it's done:</p>
<div class="codehilite"><pre><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">"localhost"</span><span class="o">,</span> <span class="mi">389</span> <span class="o">);</span>
</pre></div>
-<p>Here, we just created an unsafe connection locally, using the 389 port. Quite simple...</p>
+<p>Here we created an unsafe connection locally using the 389 port. Which is quite simple to do but not safe because data is not encrypted.</p>
<h3 id="secure-connection">Secure connection<a class="headerlink" href="#secure-connection" title="Permanent link">¶</a></h3>
-<p>Although the <strong>LDAPS</strong> (<strong>LDAP</strong> over <strong>SSL</strong>) is now considered as deprecated, many people continue to use it. The big advantage of not using <strong>LDAPS</strong> is that you don't need to setup two different listening ports (one for <strong>LDAP</strong> -389- and another one for <strong>LDAPS</strong> -636- ).</p>
-<p>The only difference with the previous example is that we have to tell the connection that it has to use <strong>SSL</strong>, by passing <strong><em>true</em></strong> as a third parameter (incidentally, passing <strong><em>false</em></strong> set a unsafe connection).</p>
+<p>Although the <strong>LDAPS</strong> (<strong>LDAP</strong> over <strong>SSL</strong>) is now considered as deprecated, many people still use it. The big advantage of not using <strong>LDAPS</strong> is that you don't need two different listening ports (one for <strong>LDAP</strong> -389- and another one for <strong>LDAPS</strong> -636- ).</p>
+<p>The only difference with the previous example is that we tell the connection to use <strong>SSL</strong>, by passing <strong><em>true</em></strong> as a third parameter (incidentally, passing <strong><em>false</em></strong> sets an unsafe connection).</p>
<p>Here is an example</p>
<div class="codehilite"><pre><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">"localhost"</span><span class="o">,</span> <span class="mi">636</span><span class="o">,</span> <span class="kc">true</span> <span class="o">);</span>
</pre></div>
<h2 id="maintaining-the-connection-opened">Maintaining the connection opened<a class="headerlink" href="#maintaining-the-connection-opened" title="Permanent link">¶</a></h2>
-<p>We keep the connection opened for a limited period of time, defaulting to 30 seconds. This might be not long enough, so one can change this delay by calling the <em>setTimeOut()</em> method :</p>
+<p>We keep the connection open for a limited period of time, defaulting to 30 seconds. This might be not long enough, so one can change this delay by calling the <em>setTimeOut()</em> method :</p>
<div class="codehilite"><pre><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">"localhost"</span><span class="o">,</span> <span class="mi">389</span> <span class="o">);</span>
<span class="n">connection</span><span class="o">.</span><span class="na">setTimeOut</span><span class="o">(</span> <span class="mi">0</span> <span class="o">);</span>
<span class="o">...</span>
@@ -212,10 +212,10 @@ h2:hover > .headerlink, h3:hover > .head
<blockquote>
-<p><strong>Note:</strong> Setting a value equal or below 0 will keep the connection opened for ever (or a soon as the connection is not explicitly closed).</p>
+<p><strong>Note:</strong> Setting a value equal or below 0 will keep the connection open forever (assuming the connection is not explicitly closed by the client).</p>
</blockquote>
<h2 id="closing-the-connection">Closing the connection<a class="headerlink" href="#closing-the-connection" title="Permanent link">¶</a></h2>
-<p>Once you don't need to use the connection anymore (remember that hodling a connection keeps a session opened on the server, and a socket opened between the client and the server), then you have to close it. This is done by calling the <em>close()</em> method :</p>
+<p>Once the connection is no longer needed (remember that holding a connection keeps the session open on the server and a socket is held open between the client and the server), then you must close it. This is done by calling the <em>close()</em> method :</p>
<div class="codehilite"><pre><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">"localhost"</span><span class="o">,</span> <span class="mi">389</span> <span class="o">);</span>
<span class="o">...</span>
<span class="n">connection</span><span class="o">.</span><span class="na">close</span><span class="o">();</span>
@@ -255,8 +255,8 @@ h2:hover > .headerlink, h3:hover > .head
</pre></div>
-<p>This will create a pool of connections that will be pre-authenticated. If you do not setName and setCredentials, then the pool will contain unauthenticated connections.</p>
-<p>The DefaultPoolableLdapConnectionFactory is sufficient for many cases. However, certain operations result in modifications to the connection itself. For example, when the pool is created, a bind operation will occur with the credentials supplied as part of the config. If you borrow a connection and perform a bind yourself, that would result in the connection being re-bound as a different user. The next time that connection gets borrowed, things are likely to break. If you perform any operation that results in a modification of the connection, you should instead use ValidatingPoolableLdapConnectionFactory:</p>
+<p>This creates a pool of connections that are pre-authenticated. If you don't setName and setCredentials, then the pool will contain unauthenticated connections.</p>
+<p>The DefaultPoolableLdapConnectionFactory is sufficient for many cases. However some operations result in modifications to the connection itself. For example, when the pool is created, a bind operation will occur with the credentials supplied as part of the config. If you borrow a connection and perform a bind yourself, that would result in the connection being re-bound as a different user. The next time that connection gets borrowed, things are likely to break. If you perform any operation that results in a modification of the connection, you should instead use ValidatingPoolableLdapConnectionFactory:</p>
<div class="codehilite"><pre><span class="o">...</span>
<span class="n">LdapConnectionPool</span> <span class="n">pool</span> <span class="o">=</span> <span class="k">new</span> <span class="n">LdapConnectionPool</span><span class="o">(</span>
<span class="k">new</span> <span class="nf">ValidatingPoolableLdapConnectionFactory</span><span class="o">(</span> <span class="n">factory</span> <span class="o">),</span> <span class="n">poolConfig</span> <span class="o">)</span> <span class="o">);</span>
@@ -264,7 +264,7 @@ h2:hover > .headerlink, h3:hover > .head
</pre></div>
-<p>A connection pool using this factory will unbind and rebind any connection that was modified while it was borrowed (<em>see the javadoc for more detail</em>). This will be slower due to the additional operations, but not too significantly.</p>
+<p>A connection pool using this factory will unbind and rebind any connection that was modified while it was borrowed (<em>see the javadoc for more detail</em>). This will be slower due to the additional operations, but not significantly.</p>
<div class="nav">
Modified: websites/staging/directory/trunk/content/api/user-guide/2.2-binding-unbinding.html
==============================================================================
--- websites/staging/directory/trunk/content/api/user-guide/2.2-binding-unbinding.html (original)
+++ websites/staging/directory/trunk/content/api/user-guide/2.2-binding-unbinding.html Sat Dec 31 02:55:54 2016
@@ -184,26 +184,26 @@
}
h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style>
<h1 id="22-binding-and-unbinding">2.2 - Binding and unbinding<a class="headerlink" href="#22-binding-and-unbinding" title="Permanent link">¶</a></h1>
-<p>In <strong>LDAP</strong>, if one wants to access the data in the base, the common way to do it is to bind on the server. However, it's important to understand that binding is a different beast than connection.</p>
-<p>Creating a connection to a <strong>LDAP</strong> server is just about opening a socket between the client and the server. You just need to provide the address and the port. </p>
-<p>The <strong>bind</strong> operation, on the other hand, create a <em>Session</em> which will hold some user's information for the time being of the session. Those information are quite limited, they include the user's credentials.</p>
-<p>But it's important to know that it's possible to bind as anonymous, providing no name and password, and still be able to request the server (note though that the server can forbid such anonymous bind).</p>
-<p>Once the user has finished to request the server, then he can unbind, destroying his session on the server. That does not close the connection, because, one more time, <em>bind != connection</em>.</p>
+<p>In <strong>LDAP</strong>, if one wants to access the data in the base, the common way to do it is to bind to the server. However, it's important to understand that binding is a different from connecting.</p>
+<p>Creating a connection to an <strong>LDAP</strong> server is opens a socket between the client and the server. You must provide the address and the port in order to do this. </p>
+<p>The <strong>bind</strong> operation, on the other hand, creates a <em>Session</em> which will hold user information for the duration of the session. This information is limited, but includes the user's credentials.</p>
+<p>But it's important to know that it's possible to bind anonymously, which doesn't require a user or password, and still be able to send requests to the server (although the server can forbid anonymous binds).</p>
+<p>Once the user has finished interacting with the server, they can unbind, destroying the session held on the server. This operation does not close the connection, because, again <em>bind != connection</em>!</p>
<h2 id="binding">Binding<a class="headerlink" href="#binding" title="Permanent link">¶</a></h2>
-<p>You have two possible types of binds in <em>LDAP</em> :</p>
+<p>There are two possible types of binds in <em>LDAP</em>:</p>
<ul>
<li><strong>Simple</strong></li>
<li><strong>SASL</strong></li>
</ul>
-<p>The first one is based on a user/password being send to the server, which check that they are valid. It's also possible to proceed an Anonymous bind explicitly.</p>
-<p>The second one is more complex, and is used if you want to proceed an authentication with some specific mechanism, like <strong>DIGEST-MD5</strong>, <strong>Kerberos</strong> or certificate based.</p>
+<p>The first one is based on a userid/password sent to the server, which verifies the credentials are valid. It's also possible to proceed with an anonymous bind explicitly.</p>
+<p>The second type is more complicated, and is used whenever authentication with a specific mechanism, like <strong>DIGEST-MD5</strong>, <strong>Kerberos</strong> or certificate based is required.</p>
<h3 id="simple-bind">Simple Bind<a class="headerlink" href="#simple-bind" title="Permanent link">¶</a></h3>
-<p>One can issue three kind of Simple bind :
+<p>One can issue three kinds of simple binds:
<em> <em>anonymous bind</em></em> <em>name/password bind</em>
* <em>unauthenticated authentication bind</em></p>
-<p>The first one is the easiest one, but depending on the server configuration, it will be accepted or rejected (all the servers don't allow anonymous binds)</p>
-<p>Most of the time, the <em>bind</em> operation will not return anything. You will get bound, or you'll get an <em>LdapException</em> if an error is met.</p>
-<p>Issuing an anonymous bind is very simple, you just provide no user name nor any password :</p>
+<p>The first one is the easiest, but depending on the server's configuration, will be accepted or rejected (not all servers allow anonymous binds)</p>
+<p>Most of the time, the <em>bind</em> operation will not return anything. You either get bound, or will receive an <em>LdapException</em> if an error occurs.</p>
+<p>Issuing an anonymous bind is simple, you neither provide a user or password:</p>
<div class="codehilite"><pre><span class="nd">@Test</span>
<span class="kd">public</span> <span class="kt">void</span> <span class="nf">testAnonymousBindRequest</span><span class="o">()</span> <span class="kd">throws</span> <span class="n">Exception</span>
<span class="o">{</span>
@@ -212,7 +212,7 @@ h2:hover > .headerlink, h3:hover > .head
</pre></div>
-<p>Issuing a user/password bind is just slightly more complex, you just have to provide your user name and its password :</p>
+<p>Issuing a user/password bind is slightly more complex, because those credentials must be included:</p>
<div class="codehilite"><pre><span class="nd">@Test</span>
<span class="kd">public</span> <span class="kt">void</span> <span class="nf">testSimpleBindRequest</span><span class="o">()</span> <span class="kd">throws</span> <span class="n">Exception</span>
<span class="o">{</span>
@@ -236,7 +236,7 @@ h2:hover > .headerlink, h3:hover > .head
<h3 id="rebinding">Rebinding<a class="headerlink" href="#rebinding" title="Permanent link">¶</a></h3>
-<p>It's possible to issue a <strong>Bind</strong> on an already bound connection : the existing Ldap session will be terminated, and replaced by a new Ldap session. In any case, the connection is not dropped when doing so. Note that if the connection was encrypted, it will remain encrypted.</p>
+<p>It's possible to issue a <strong>Bind</strong> on an already bound connection and the existing LDAP session will be terminated, and replaced by a new LDAP session. In any case, the connection is not dropped when doing so. Note that if the connection was encrypted, it remains encrypted.</p>
<div class="codehilite"><pre><span class="nd">@Test</span>
<span class="kd">public</span> <span class="kt">void</span> <span class="nf">testDoubleSimpleBindValid</span><span class="o">()</span> <span class="kd">throws</span> <span class="n">Exception</span>
<span class="o">{</span>
@@ -254,7 +254,7 @@ h2:hover > .headerlink, h3:hover > .head
<p>If you issue a <em>bind</em> on the same connection with some different credentials, then the existing session will be terminated on the server, and a new one will be created. All the pending requests for the initial session will be lost.</p>
<h3 id="unbinding">Unbinding<a class="headerlink" href="#unbinding" title="Permanent link">¶</a></h3>
<p>This is a trivial operation : you just send an <strong>UnbindRequest</strong> to the server, which will invalidate your session. </p>
-<p>It's important to know that when you issue an <strong>Unbind</strong>, the connection is dropped. You can then do such a thing :</p>
+<p>It's important to know that when you issue an <strong>Unbind</strong>, the connection is dropped. It's done like this:</p>
<div class="codehilite"><pre><span class="nd">@Test</span>
<span class="kd">public</span> <span class="kt">void</span> <span class="nf">testDoubleSimpleBindValid</span><span class="o">()</span> <span class="kd">throws</span> <span class="n">Exception</span>
<span class="o">{</span>
@@ -271,7 +271,7 @@ h2:hover > .headerlink, h3:hover > .head
</pre></div>
-<p>Last, not least, if you close the connection, then the session will also be terminated.</p>
+<p>Last, but not least, if you close the connection, the session also terminates.</p>
<div class="nav">
Modified: websites/staging/directory/trunk/content/api/user-guide/2.3-searching.html
==============================================================================
--- websites/staging/directory/trunk/content/api/user-guide/2.3-searching.html (original)
+++ websites/staging/directory/trunk/content/api/user-guide/2.3-searching.html Sat Dec 31 02:55:54 2016
@@ -184,10 +184,10 @@
}
h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style>
<h1 id="23-searching">2.3 - Searching (...)<a class="headerlink" href="#23-searching" title="Permanent link">¶</a></h1>
-<p>Searching is the most important operation in <strong>LDAP</strong>. It has to be fast, very fast. On the other hand, as the server does not a lot of processing while looking for entries, the client has to provide many information in order to get some accurate results.</p>
-<p>The idea is to define a search <strong>API</strong> which is easy to use in the simplest cases, but provides all the necessary bolts if you need to send complex search requests.</p>
+<p>Searching is the most important operation in <strong>LDAP</strong>. It has to be fast, very fast. On the other hand, as the server does the processing while looking for entries, the client must provide information to get accurate results.</p>
+<p>The idea is to define a search <strong>API</strong> which is easy to use in the simplest cases, but provides all the capability to send complex search requests.</p>
<h2 id="simple-search">Simple search<a class="headerlink" href="#simple-search" title="Permanent link">¶</a></h2>
-<p>Let's first look at a simple search. What we basically need to process a search is a starting point in the tree, a filter, a scope. Here is an example :</p>
+<p>Let's first look at a simple search. To process a search we need a starting point in the tree, a filter, and a scope. Here's an example:</p>
<div class="codehilite"><pre><span class="n">EntryCursor</span> <span class="n">cursor</span> <span class="o">=</span> <span class="n">connection</span><span class="o">.</span><span class="na">search</span><span class="o">(</span> <span class="s">"ou=system"</span><span class="o">,</span> <span class="s">"(objectclass=*)"</span><span class="o">,</span> <span class="n">SearchScope</span><span class="o">.</span><span class="na">ONELEVEL</span> <span class="o">);</span>
<span class="k">while</span> <span class="o">(</span> <span class="n">cursor</span><span class="o">.</span><span class="na">next</span><span class="o">()</span> <span class="o">)</span>
@@ -201,15 +201,15 @@ h2:hover > .headerlink, h3:hover > .head
</pre></div>
-<p>In this example, the <em>connection</em> has been previously created. We just search for all the entries starting at <em>ou=system</em> and their children, which have an <em>ObjectClass</em> attribute (all the entries have such an attribute, so we should get back all the entries). The scope (<em>ONELEVEL</em>) says we just search one level under the starting base.</p>
-<p>We get back a cursor on entries, which can be walked forward. Every call to the <em>getEntry()</em> method will return an entry.</p>
-<p>This is pretty much it !</p>
-<p>But this is not really enough , there are many possible options.</p>
+<p>In this example, the <em>connection</em> has been previously created. We search for all entries starting at <em>ou=system</em> along with its children, which have an <em>ObjectClass</em> attribute (all the entries have such an attribute, so we should get back all the entries). The scope (<em>ONELEVEL</em>) searches one level under the starting base.</p>
+<p>A cursor of entries is returned, which can be iterated over. Every call to the <em>getEntry()</em> method returns the next entry in the LDAP result set.</p>
+<p>That's pretty much it!</p>
+<p>But this is not really enough, there are many possible options.</p>
<blockquote>
-<p><strong>Note</strong> Don't forget to close the cursor, otherwise the associated data will remain in memory foreever !</p>
+<p><strong>Note</strong> Don't forget to close the cursor, otherwise the associated data remains in memory forever (causing a memory leak)!</p>
</blockquote>
<h3 id="searching-using-a-dn">Searching using a DN<a class="headerlink" href="#searching-using-a-dn" title="Permanent link">¶</a></h3>
-<p>In the previous sample, we used a String to define the starting point of the search. Sometime, you will find it more convenient to start a search using a DN (for instance because you got back a DN from an other operation). In this case, no need to transform the DN into a String before doing your search : simply use the DN !</p>
+<p>In the previous sample, we used a String to define the starting point of the search. Sometimes it's convenient to start a search with a DN (i.e. because you got the DN from another operation). In this case, no need to transform the DN into a String before doing your search, simply use the DN!</p>
<div class="codehilite"><pre><span class="n">DN</span> <span class="n">systemDn</span> <span class="o">=</span> <span class="k">new</span> <span class="n">Dn</span><span class="o">(</span> <span class="s">"ou=system"</span> <span class="o">);</span>
<span class="o">...</span>
<span class="n">EntryCursor</span> <span class="n">cursor</span> <span class="o">=</span> <span class="n">connection</span><span class="o">.</span><span class="na">search</span><span class="o">(</span> <span class="n">systemDn</span><span class="o">,</span> <span class="s">"(objectclass=*)"</span><span class="o">,</span> <span class="n">SearchScope</span><span class="o">.</span><span class="na">ONELEVEL</span> <span class="o">);</span>
@@ -225,24 +225,24 @@ h2:hover > .headerlink, h3:hover > .head
</pre></div>
-<p>This is it !</p>
+<p>This is it!</p>
<h3 id="scope">Scope<a class="headerlink" href="#scope" title="Permanent link">¶</a></h3>
-<p>There are three different different scopes you can use to search for data :
- * SearchScope.OBJECT : you will just get back the entry for the given DN, if it exists. Note that you could use a lookup if the filter is irrelevent.
- * SearchScope.ONELEVEL : you will get back all the elements just under the current DN, but not the element associated with the DN.
- * SearchScope.SUBLEVEL : you will get back all the elements starting from the given DN, including the element associated with the DN, whatever the depth of the tree.</p>
+<p>There are three different different scopes you can use to search for data:
+ * SearchScope.OBJECT : return the entry for a given DN, if it exists. Note that you could use a lookup if the filter is irrelevent.
+ * SearchScope.ONELEVEL : return all elements below the current DN, but not the element associated with the DN.
+ * SearchScope.SUBLEVEL : return all the elements starting from the given DN, including the element associated with the DN, whatever the depth of the tree.</p>
<h3 id="filter">Filter<a class="headerlink" href="#filter" title="Permanent link">¶</a></h3>
-<p>The filter is used to define the elements that will be selected. There are various possibilities to construct a filter, using one or more connectors,a nd one or more expression nodes.</p>
-<p>Connrectors are using a prefix notation, followed by as many expression node as necessary, like in (& (node1) (node2) ... (nodeN))</p>
-<p>Expression nodes are always contane din parenthesis, with a left part - the attributeType and a right part - the value -.</p>
-<p>Here is the list of possible connectors :</p>
+<p>The filter is used to define the elements that are targeted. There are various possibilities to construct a filter, using one or more connectors, and one or more expression nodes.</p>
+<p>Connrectors use a prefix notation, followed by as many expression nodes as necessary, like in (& (node1) (node2) ... (nodeN))</p>
+<p>Expression nodes are always contained within parenthesis, with a left part - the attributeType, and a right part - the value -.</p>
+<p>Here is the list of possible connectors:</p>
<div class="codehilite"><pre><span class="o">*</span> <span class="o">&</span> <span class="p">:</span> <span class="n">n</span><span class="o">-</span><span class="n">ary</span> <span class="n">AND</span> <span class="n">connector</span><span class="p">,</span> <span class="n">all</span> <span class="n">the</span> <span class="n">nodes</span> <span class="n">must</span> <span class="n">evaluate</span> <span class="n">to</span> <span class="n">TRUE</span>
<span class="o">*</span> <span class="o">|</span> <span class="p">:</span> <span class="n">n</span><span class="o">-</span><span class="n">ary</span> <span class="n">OR</span> <span class="n">connector</span><span class="p">,</span> <span class="n">at</span> <span class="n">least</span> <span class="n">one</span> <span class="n">of</span> <span class="n">the</span> <span class="n">node</span> <span class="n">must</span> <span class="n">evaluate</span> <span class="n">to</span> <span class="n">true</span>
-<span class="o">*</span> ! <span class="p">:</span> 1<span class="o">-</span><span class="n">ary</span> <span class="n">NOT</span> <span class="n">connector</span> <span class="p">:</span> <span class="n">the</span> <span class="n">node</span> <span class="n">must</span> <span class="n">evaluate</span> <span class="n">to</span> <span class="n">false</span>
+<span class="o">*</span> ! <span class="p">:</span> 1<span class="o">-</span><span class="n">ary</span> <span class="n">NOT</span> <span class="n">connector</span><span class="p">,</span> <span class="n">the</span> <span class="n">node</span> <span class="n">must</span> <span class="n">evaluate</span> <span class="n">to</span> <span class="n">false</span>
</pre></div>
-<p>And here is the list of possible expression nodes, assuming that an expression node :</p>
+<p>And here is the list of possible expression nodes, assuming that an expression node:</p>
<div class="codehilite"><pre><span class="o">*</span> <span class="p">=</span> <span class="n">Equality</span> <span class="n">expression</span> <span class="n">node</span> <span class="p">:</span> <span class="n">the</span> <span class="n">selected</span> <span class="n">entry</span> <span class="n">matches</span> <span class="n">the</span> <span class="n">right</span> <span class="n">part</span>
<span class="o">*</span> <span class="p">=</span><span class="o">*</span> <span class="n">Presence</span> <span class="n">expression</span> <span class="n">node</span> <span class="p">:</span> <span class="n">tehentry</span> <span class="n">has</span> <span class="n">the</span> <span class="n">Attribute</span> <span class="n">on</span> <span class="n">the</span> <span class="n">left</span> <span class="n">side</span>
<span class="o">*</span> <span class="o">></span><span class="p">=</span> <span class="n">Superior</span> <span class="n">expression</span> <span class="n">node</span> <span class="p">:</span> <span class="n">the</span> <span class="n">entry</span> <span class="n">should</span> <span class="n">be</span> <span class="n">superior</span> <span class="n">to</span> <span class="n">the</span> <span class="n">right</span> <span class="n">part</span>
@@ -252,18 +252,18 @@ h2:hover > .headerlink, h3:hover > .head
<blockquote>
-<p><strong>Note:</strong> As of Apache DS 2.0, we don't support approx matches not extensible matches.</p>
+<p><strong>Note:</strong> As of Apache DS 2.0, we don't support approx matches nor extensible matches.</p>
</blockquote>
<h2 id="more-complex-searches">More complex searches<a class="headerlink" href="#more-complex-searches" title="Permanent link">¶</a></h2>
-<p>Sometime, you way want to have more control on the search opetation, either on the parameters you want to use, or on the results you get.</p>
-<p>A search can return something else than an entry. In fact, you can get three different kind of response</p>
+<p>Sometimes, you want to have more control over the search opetation, either with the parameters in use, or the results that are returned.</p>
+<p>A search things other than entries. In fact, you can get three different kinds of responses:</p>
<div class="codehilite"><pre><span class="o">*</span> <span class="n">When</span> <span class="n">it</span><span class="o">'</span><span class="n">s</span> <span class="n">done</span><span class="p">,</span> <span class="n">you</span> <span class="n">will</span> <span class="n">receive</span> <span class="n">a</span> <span class="n">SearchResultDone</span>
<span class="o">*</span> <span class="n">When</span> <span class="n">the</span> <span class="n">response</span> <span class="n">is</span> <span class="n">a</span> <span class="n">reference</span> <span class="n">to</span> <span class="n">another</span> <span class="n">entry</span><span class="p">,</span> <span class="n">you</span> <span class="n">will</span> <span class="n">get</span> <span class="n">a</span> <span class="n">SearchResultReference</span>
<span class="o">*</span> <span class="n">In</span> <span class="n">some</span> <span class="n">cases</span><span class="p">,</span> <span class="n">you</span> <span class="n">may</span> <span class="n">also</span> <span class="n">receive</span> <span class="n">an</span> <span class="n">IntermediateResponse</span><span class="p">.</span>
</pre></div>
-<p>You may also add a Control to the searchRequest, or request some specific AttributeType to be returned. The parameter you can inject into a SearchRequest are the following :</p>
+<p>You may also add a Control to the searchRequest, or request some specific AttributeType to be returned. The parameters that may be injected into a SearchRequest are as follows:</p>
<div class="codehilite"><pre><span class="o">*</span> <span class="n">The</span> <span class="n">base</span> <span class="n">DN</span>
<span class="o">*</span> <span class="n">The</span> <span class="n">filter</span>
<span class="o">*</span> <span class="n">The</span> <span class="n">Scope</span> <span class="p">(</span><span class="n">one</span> <span class="n">of</span> <span class="n">OBJECT</span><span class="p">,</span> <span class="n">ONELEVEL</span> <span class="n">or</span> <span class="n">SUBTREE</span><span class="p">)</span>
@@ -276,7 +276,7 @@ h2:hover > .headerlink, h3:hover > .head
</pre></div>
-<p>In both case, you should fill a <em>SearchRequest</em> message and send it to the server :</p>
+<p>In both cases, you should fill the <em>SearchRequest</em> message and send it to the server:</p>
<div class="codehilite"><pre><span class="c1">// Create the SearchRequest object</span>
<span class="n">SearchRequest</span> <span class="n">req</span> <span class="o">=</span> <span class="k">new</span> <span class="n">SearchRequestImpl</span><span class="o">();</span>
<span class="n">req</span><span class="o">.</span><span class="na">setScope</span><span class="o">(</span> <span class="n">SearchScope</span><span class="o">.</span><span class="na">SUBTREE</span> <span class="o">);</span>
@@ -302,7 +302,7 @@ h2:hover > .headerlink, h3:hover > .head
</pre></div>
-<p>As we can see, the response is different : we get back a <em>SearchCursor</em> instance, and we have to check the response type before being able to process it.</p>
+<p>As we can see, the response is different, we are returned a <em>SearchCursor</em> instance, and we must verify the response type before being able to process it.</p>
<div class="nav">
Modified: websites/staging/directory/trunk/content/api/user-guide/2.4-adding.html
==============================================================================
--- websites/staging/directory/trunk/content/api/user-guide/2.4-adding.html (original)
+++ websites/staging/directory/trunk/content/api/user-guide/2.4-adding.html Sat Dec 31 02:55:54 2016
@@ -184,10 +184,10 @@
}
h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style>
<h1 id="24-adding-entries">2.4 - Adding entries<a class="headerlink" href="#24-adding-entries" title="Permanent link">¶</a></h1>
-<p>Adding entries is one of the base operation a user can do on a <strong>LDAP</strong> server. Nevertheless, such an operation implies a lot of checks, and frequently the user gets some weird error messages. We will see how we can add an entry using the <strong>LDAP API</strong>, and then analyze the different error cases we can face.</p>
+<p>Adding entries is one of the base operations a user can do on an <strong>LDAP</strong> server. Nevertheless, it's an operation that implies many checks, and frequently the user receives strange error messages. We will see how to add an entry using the <strong>LDAP API</strong>, and analyze the various error cases that can occur.</p>
<h2 id="adding-an-entry">Adding an entry<a class="headerlink" href="#adding-an-entry" title="Permanent link">¶</a></h2>
-<p>We will first see the easiest way to add an entry into the server, assuming that the entry is correct. In order to add an entry, you only have to provide the place where this entry will be stored (its <em>Dn</em>) and the list of its <em>Attributes</em>.</p>
-<p>Here is two examples where we inject the entry using <strong>LDIF</strong> :</p>
+<p>Here is the simplest way to add an entry into the server, assuming that the entry is correct. In order to add an entry, you must provide the location where the entry is stored (its <em>Dn</em>) and the list of its <em>Attributes</em> contained within it.</p>
+<p>Here are two examples where the entry is injected using <strong>LDIF</strong>:</p>
<div class="codehilite"><pre><span class="nd">@Test</span>
<span class="kd">public</span> <span class="kt">void</span> <span class="nf">testAddLdif</span><span class="o">()</span> <span class="kd">throws</span> <span class="n">Exception</span>
<span class="o">{</span>
@@ -234,10 +234,10 @@ Note that it is possible to use some var
<p>Down the line, what is important is that the <em>add()</em> operation is taking a full <strong><a href="6.12-entry.html">Entry</a></strong>. </p>
-<p>We can also create the <strong><a href="6.12-entry.html">Entry</a></strong> in a different way, which will be exposed in the following paragraphs.</p>
+<p>We can also create the <strong><a href="6.12-entry.html">Entry</a></strong> in a different way, which is shown in the following paragraphs.</p>
<h2 id="sending-an-addrequest">Sending an <em>AddRequest</em><a class="headerlink" href="#sending-an-addrequest" title="Permanent link">¶</a></h2>
-<p>Sometimes, we want more control. We can ask the server to add an entry by sending an <strong><a href="">AddRequest</a></strong>, which allows you to send a <strong><a href="">Control</a></strong> at the same time.</p>
-<p>Here is an example (note that the control is just injected to demonstrate the feature, it simply does nothing in this case):</p>
+<p>When more control is needed we ask the server to add an entry by sending an <strong><a href="">AddRequest</a></strong>, which allows a <strong><a href="">Control</a></strong> to be included in the request.</p>
+<p>Here is an example (note that the control is just injected to demonstrate the feature, it doesn't really do anything special in this example):</p>
<div class="codehilite"><pre><span class="nd">@Test</span>
<span class="kd">public</span> <span class="kt">void</span> <span class="nf">testAddWithControl</span><span class="o">()</span> <span class="kd">throws</span> <span class="n">Exception</span>
<span class="o">{</span>
@@ -266,7 +266,7 @@ Note that it is possible to use some var
<h3 id="asynchronous-addition">Asynchronous addition<a class="headerlink" href="#asynchronous-addition" title="Permanent link">¶</a></h3>
-<p>Some may want to add an entry, but will not check the result immediately. It's just a matter of calling the <em>addAsync()</em> method, which will return a <em>Future</em> that can be checked somewhere else in the code:</p>
+<p>Sometimes we need to add an entry, but not check the result immediately. It's just a matter of calling the <em>addAsync()</em> method, which returns a <em>Future</em> that can be checked somewhere else in the code:</p>
<div class="codehilite"><pre><span class="nd">@Test</span>
<span class="kd">public</span> <span class="kt">void</span> <span class="nf">testAddAsyncLdif</span><span class="o">()</span> <span class="kd">throws</span> <span class="n">Exception</span>
<span class="o">{</span>
@@ -295,7 +295,7 @@ Note that it is possible to use some var
<h2 id="do-dont">Do, Don't<a class="headerlink" href="#do-dont" title="Permanent link">¶</a></h2>
-<p>Successfully adding an entry assume that the entry is correct, ie that the attributes and the value are compatible with the schema. There are many things checked by the server. Here is a list of constraints that you should respect in order to get your entry injected:</p>
+<p>Successfully adding an entry assumes that the entry was correct, i.e. the attributes and values are compatible with the LDAP schema. There are many things checked by the server. Here is a list of constraints that you should respect in order to get your entry injected:</p>
<ul>
<li>The entry must have at least one <strong>Structural</strong> <em>ObjectClass</em></li>
<li>If the entry has more than one <strong>Structural</strong> <em>ObjectClass</em>, then they must be hierarchically related</li>
@@ -307,7 +307,7 @@ Note that it is possible to use some var
<li>You are not allowed as a user to inject operational attributes, unless they have the <strong>USER-MODIFICATION</strong> flag set to true.</li>
</ul>
<p>There are also some other constraints, depending on the server, if it implements <em>NameForms</em>, <em>DITStructureRules</em> or <em>DITContentRules</em>.</p>
-<p>One other reason your entry can be rejected is that you don't have enough privilege to add it. You have to check that the server configuration allows you to add an entry where you want to add it.</p>
+<p>Another reason an entry can be rejected is that there aren't enough privilege to add it. You must ensure the LDAP server's configuration allows you to add an entry in the correct location.</p>
<h2 id="errors">Errors<a class="headerlink" href="#errors" title="Permanent link">¶</a></h2>
<DIV class="note" markdown="1">
At first, you might expect to get an exception if the entry addition has failed. If the server is rejecting the addition, *you will get NO exception*. Exceptions are only thrown client side if the entry is not built correctly, or if the connection is not opened.
@@ -315,8 +315,8 @@ At first, you might expect to get an exc
In any other case, the server will simply return a **[LdapResult]()** instance containing either **SUCCESS** or the cause of the rejection.
</DIV>
-<p>Usually, if you get an error while adding an entry, the message might be pretty tedious. Most of the cases it's because either your entry already exists, or because your entry has some schema violation.</p>
-<p>The <em>LdapResult</em> in the response will give you a clue about what going on.</p>
+<p>Usually, if you get an error while adding an entry, the message is hard to read. Most of the errors occur because the entry already exists, or because the entry has an LDAP schema violation.</p>
+<p>The <em>LdapResult</em> in the response will provide helpful clues as to what the root cause is.</p>
<div class="nav">
Modified: websites/staging/directory/trunk/content/api/user-guide/2.5-deleting.html
==============================================================================
--- websites/staging/directory/trunk/content/api/user-guide/2.5-deleting.html (original)
+++ websites/staging/directory/trunk/content/api/user-guide/2.5-deleting.html Sat Dec 31 02:55:54 2016
@@ -184,9 +184,9 @@
}
h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style>
<h1 id="25-deleting-entries">2.5 - Deleting entries<a class="headerlink" href="#25-deleting-entries" title="Permanent link">¶</a></h1>
-<p>Deleting an entry is really easy. It's just a matter to know its <em>DN</em>. There is one important thing to understand though : if this entry has some children, it won't be deleted.</p>
+<p>Deleting an entry is pretty easy, it just requires the entry's <em>DN</em>. There is one important thing to understand though, if the entry has children, the operation will fail.</p>
<h2 id="simple-entry-deletion">Simple entry deletion<a class="headerlink" href="#simple-entry-deletion" title="Permanent link">¶</a></h2>
-<p>We can ask the deletion by providing the entry's <em>DN</em>, like what is done in the following example :</p>
+<p>We request a deletion by providing the entry's <em>DN</em>, as in the following example:</p>
<div class="codehilite"><pre><span class="nd">@Test</span>
<span class="kd">public</span> <span class="kt">void</span> <span class="nf">testDeleteLeafNode</span><span class="o">()</span> <span class="kd">throws</span> <span class="n">Exception</span>
<span class="o">{</span>
@@ -201,7 +201,7 @@ h2:hover > .headerlink, h3:hover > .head
</pre></div>
-<p>Trying to delete the parent alone would leads to an error (NOT_ALLOWED_ON_NON_LEAF) :</p>
+<p>Trying to delete a parent node would result in an error (NOT_ALLOWED_ON_NON_LEAF) :</p>
<div class="codehilite"><pre><span class="nd">@Test</span>
<span class="kd">public</span> <span class="kt">void</span> <span class="nf">testDeleteNonLeafFailure</span><span class="o">()</span> <span class="kd">throws</span> <span class="n">Exception</span>
<span class="o">{</span>
@@ -217,7 +217,7 @@ h2:hover > .headerlink, h3:hover > .head
<h2 id="recursive-deletion-of-entries">Recursive deletion of entries<a class="headerlink" href="#recursive-deletion-of-entries" title="Permanent link">¶</a></h2>
-<p>Usually, you can't delete an entry and all of its children. However, some server accept such a request if you send a delete request and a TreeDelete control. This control is a <a href="http://tools.ietf.org/html/draft-armijo-ldap-treedelete-02">draft</a>, which has been implemented by <strong>Microsoft</strong>, <strong>OpenDS</strong>, <strong>OpenDJ</strong>. It will delete all the children and the entry itself. We don't use a normal <em>delete()</em> method, there is a specific method, <em>deleteTree()</em>. Here is an example :</p>
+<p>Usually, you can't delete an entry and all of its children in one operation. However, some servers accept such requests if you send a delete request and a TreeDelete control. This control is a <a href="http://tools.ietf.org/html/draft-armijo-ldap-treedelete-02">draft</a>, which has been implemented by <strong>Microsoft</strong>, <strong>OpenDS</strong>, <strong>OpenDJ</strong>. It will delete all the children and the entry itself. We don't use a normal <em>delete()</em> method, there is a specific method, <em>deleteTree()</em>. Here is an example :</p>
<div class="codehilite"><pre><span class="nd">@Test</span>
<span class="kd">public</span> <span class="kt">void</span> <span class="nf">testDeleteWithCascadeControl</span><span class="o">()</span> <span class="kd">throws</span> <span class="n">Exception</span>
<span class="o">{</span>
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 Dec 31 02:55:54 2016
@@ -184,25 +184,25 @@
}
h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style>
<h1 id="26-modifying-entries">2.6 - Modifying entries<a class="headerlink" href="#26-modifying-entries" title="Permanent link">¶</a></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.</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 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>
+<p>There are several ways an entry can be modified. Mainly, it's about adding or deleting an attribute, or 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 an all or none fashion. i.e., if any of the modifications are invalid, none of them will occur. Also if the server crashes while applying the mods, it's guaranteed that the entry will remain consistent.</p>
<h2 id="how-it-works">How it works ?<a class="headerlink" href="#how-it-works" title="Permanent link">¶</a></h2>
-<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>
+<p>Each modification to be applied on an entry is encapsulated into 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, 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>
+<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>
-<li>ModificationOperation.REPLACE_ATTRIBUTE : replace some existing values from an entry</li>
+<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<a class="headerlink" href="#adding-or-removing-full-attributes" title="Permanent link">¶</a></h2>
-<p>The two following operations are dealing with complete addition or removal of attributes.</p>
+<p>The following two operations completely add or remove attributes.</p>
<h3 id="adding-new-attributes">Adding new attributes<a class="headerlink" href="#adding-new-attributes" title="Permanent link">¶</a></h3>
-<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>
+<p>First of all, let's learn how to add an attribute. First you must know which entry to modify, which means you must know its Dn. Next, you must create the <em>Modification</em> instance which is applied to 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>
@@ -262,12 +262,11 @@ h2:hover > .headerlink, h3:hover > .head
</pre></div>
-<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>
+<p>Here, we've tried to add the <em>uid</em> attribute that already exists, and the error trace tells us as much.</p>
+<p>Another potential error occurs when adding an attribute type that isn't allowed on that entry. This occurs because the Entry's ObjectClass does not allow such an attribute (per the schema), or because the server forbids modification of that entry, due to the ACIs applied on this entry.</p>
+<p>Last, but not least, and hopefully this is obvious, the entry <em>must</em> exist prior to modification!</p>
<h3 id="removing-an-attribute">Removing an attribute<a class="headerlink" href="#removing-an-attribute" title="Permanent link">¶</a></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 example where we will remove the <em>giveName</em> attrinute from an entry :</p>
+<p>Removing an attribute is actually a bit simpler than adding one, because the values for the attribute don't need to be specified. Here's an example where the <em>givenName</em> attrinute is removed 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>
@@ -276,10 +275,10 @@ as expected.</p>
</pre></div>
-<p>Here, we have created a modification, specifying that the <em>givenName</em> attribute has to be removed, and we applied the modification on the entry.</p>
-<p>Again, you can delete more than one attribute from an entry, it's just a matter of creating more than one <em>Modification</em> instances and applying them to the entry.</p>
+<p>Here, we've created a modification, specifying the <em>givenName</em> attribute must be removed, and we apply the modification request to the entry.</p>
+<p>Again, more than one attribute may be deleted from an entry. It's a matter of creating more than one <em>Modification</em> instances and applying them to the entry.</p>
<h4 id="errors_1">Errors<a class="headerlink" href="#errors_1" title="Permanent link">¶</a></h4>
-<p>If you try to delete an attribute that does not exist in the entry, you will get this error :</p>
+<p>If you try to delete an attribute that does not exist in the entry, you will get this error:</p>
<div class="codehilite"><pre><span class="n">org</span><span class="o">.</span><span class="na">apache</span><span class="o">.</span><span class="na">directory</span><span class="o">.</span><span class="na">api</span><span class="o">.</span><span class="na">ldap</span><span class="o">.</span><span class="na">model</span><span class="o">.</span><span class="na">exception</span><span class="o">.</span><span class="na">LdapNoSuchAttributeException</span><span class="o">:</span> <span class="nl">NO_SUCH_ATTRIBUTE:</span> <span class="n">failed</span> <span class="k">for</span> <span class="n">MessageType</span> <span class="o">:</span> <span class="n">MODIFY_REQUEST</span>
<span class="n">Message</span> <span class="n">ID</span> <span class="o">:</span> <span class="mi">3</span>
<span class="n">Modify</span> <span class="n">Request</span>
@@ -305,19 +304,19 @@ as expected.</p>
<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 ACIs that are applicable to this entry.</p>
-<p>Again the entry <em>must</em> exist before performing a modification!</p>
+<p>Another potential error is when you trying to remove a mandatory attribute, per the entry's ObjectClass constraints.</p>
+<p>Otherwise, the server might forbid modification of entry due to the ACIs that are applicable to it.</p>
+<p>Again the entry <em>must</em> exist prior to performing the modification!</p>
<h2 id="adding-removing-or-replacing-attribute-values">Adding, removing or replacing attribute values<a class="headerlink" href="#adding-removing-or-replacing-attribute-values" title="Permanent link">¶</a></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>
+<p>You can now update an attribute's values themselves, atomically, instead of removing the 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, this is what happens when using one of the three <em>ModificationOperation</em> on an attribute:</p>
<ul>
<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>
<h3 id="add-values">Add values<a class="headerlink" href="#add-values" title="Permanent link">¶</a></h3>
-<p>Let's see with the addition of values. Here, we will assume we have an entry like :</p>
+<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>
@@ -354,8 +353,8 @@ as expected.</p>
<h4 id="errors_2">Errors<a class="headerlink" href="#errors_2" title="Permanent link">¶</a></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>
+<p>Again, such an operation might fail for many reasons. Let's see what are the possible errors:</p>
+<p>First, if the attribute's value already exists. You will get an error like this:</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
@@ -373,8 +372,8 @@ as expected.</p>
</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>
+<p>Note that depending on the attribute's syntax, you may get this type of error because you entered 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 error message. Be sure you know what the attribute syntax allows you to do...</p>
+<p>Second, if the attribute is single valued, it will not be possible to add another value to it. When this happens 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>
@@ -391,9 +390,9 @@ as expected.</p>
</pre></div>
-<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<a class="headerlink" href="#remove-values" title="Permanent link">¶</a></h3>
-<p>Removing values follow the same scheme : select the entry, chose the attribute, and list the values you want to be removed from this attribute. Here is an exemple :</p>
+<p>Third, the ACIs set on the server may not allow updating an entry or its attribute.</p>
+<h3 id="removing-values">Removing values<a class="headerlink" href="#removing-values" title="Permanent link">¶</a></h3>
+<p>Removing values follow the same pattern. First select the entry, choose its attribute, and list the values to be removed from it. Here is an exemple:</p>
<div class="codehilite"><pre><span class="o">...</span>
<span class="n">Modification</span> <span class="n">removedGivenNameValue</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> <span class="s">"Tom"</span> <span class="o">);</span>
@@ -402,11 +401,11 @@ as expected.</p>
</pre></div>
-<p>The value 'Tom' we just have added should now be removed from the <em>givenName</em> attribute, but the value 'John' should still be present.</p>
-<p>Whet if you remove the last value of an attribute ? That quite simple : the attribute itself will be removed from the entry, if this is allowed (see below).</p>
+<p>The value 'Tom' just added should now be removed from the <em>givenName</em> attribute, but the value 'John' should still be present.</p>
+<p>How do we remove the last value of an attribute? It's quite simple. The attribute itself must be removed from the entry, if this is allowed (see below).</p>
<h4 id="errors_3">Errors<a class="headerlink" href="#errors_3" title="Permanent link">¶</a></h4>
-<p>There are more potential erros with this operation. let's list all of them.</p>
-<p>First, the value you want to remove does not exist. You will get such an error :</p>
+<p>There are more potential erros with this operation. Let's list them all.</p>
+<p>First, the value you want to remove does not exist. 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">LdapNoSuchAttributeException</span><span class="p">:</span> <span class="n">NO_SUCH_ATTRIBUTE</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
@@ -431,7 +430,7 @@ as expected.</p>
</pre></div>
-<p>Second, you try to remove the last value of an attribute which is mandatory You will get such an error :</p>
+<p>Second, if you try to remove the last value of an attribute which was declared mandatory (in the schema) the following error will occur:</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">LdapSchemaViolationException</span><span class="p">:</span> <span class="n">OBJECT_CLASS_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
@@ -450,7 +449,7 @@ as expected.</p>
<p>Here, we tried to remove the <em>sn</em> attribute's last value from an entry where it's a required attribute.</p>
-<p>Third, you try to remove a value which is used as the entry's <em>RDN</em> : this is not allowed. Typically, for the 'uid=billyd,ou=users,ou=system' entry, you can't remove the 'billyd' value from the 'uid' attribute. Here is the error you get when you try to apply such a modifcation :</p>
+<p>Third, if you try to remove a value which was used as part of the entry's <em>RDN</em> : which is never allowed. Typically, for the 'uid=billyd,ou=users,ou=system' entry, you can't remove the 'billyd' value from the 'uid' attribute. This is the error that occurs when such a modification is attempted:</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">LdapSchemaViolationException</span><span class="p">:</span> <span class="n">NOT_ALLOWED_ON_RDN</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
@@ -468,12 +467,12 @@ as expected.</p>
</pre></div>
-<p>Then you have the classical errors : the ACLs forbids you to remove a velue, or the entry simply does not exist.</p>
+<p>There are also classical errors, when ACLs forbid the removal of a value, or the entry doesn't exist.</p>
<h3 id="replace-values">Replace values<a class="headerlink" href="#replace-values" title="Permanent link">¶</a></h3>
<p>Here, what we want to do is to replaces all the values from an attribute with some new values. All in all, this is equivalent to first remove the values, then inject the new values, using modifications, except that in some cases, doing so will not work.</p>
-<p>An exemple where such an operation is mandatory is when you want to replace the value of a mandatory attribute with something different : with two successive operation, that would fail. A replace will work.</p>
-<p>What is important here is that the operation simply replace <em>all the existing values</em> by new ones, removing the previous ones.</p>
-<p>Let's see how it works with a simple example, with an entry containing :</p>
+<p>An example where such an operation is mandatory is when replacing the values of a mandatory attribute with something different: with two successive operations, that would fail. A replace will work.</p>
+<p>What is important here is that the operation simply replace <em>all the existing values</em> with new ones, removing the previous ones.</p>
+<p>Let's see how it works with a simple example, with an entry containing:</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>
@@ -487,7 +486,7 @@ as expected.</p>
</pre></div>
-<p>We will try to replace the <em>givenName</em> :</p>
+<p>We will try to replace the <em>givenName</em>:</p>
<div class="codehilite"><pre><span class="n">Modification</span> <span class="n">replaceGn</span> <span class="p">=</span> <span class="n">new</span> <span class="n">DefaultModification</span><span class="p">(</span> <span class="n">ModificationOperation</span><span class="p">.</span><span class="n">REPLACE_ATTRIBUTE</span><span class="p">,</span> "<span class="n">givenName</span>"<span class="p">,</span>
"<span class="n">Jack</span>" <span class="p">);</span>
@@ -496,15 +495,15 @@ as expected.</p>
<p>The modified entry will have its <em>givenName</em> value replaced by 'Jack', the two previous values will have been removed.</p>
-<p>There is one corner case with this operation : if you create a <em>Modification</em> instances where you specify an Attribute with no value, then the attribute will be removed from the entry.</p>
+<p>There is one corner case with this operation: creating a <em>Modification</em> instance where the attribute has no value, then the attribute will be removed from the entry.</p>
<h4 id="errors_4">Errors<a class="headerlink" href="#errors_4" title="Permanent link">¶</a></h4>
-<p>You will get the same errors seen in the two previous operation (ADD and REMOVE) for the very same use cases. Be sure you don't :</p>
+<p>You will get the same errors seen in the two previous operation (ADD and REMOVE) for the very same use cases. Here are some more things to watch out for:</p>
<ul>
-<li>inject more than one value in a SINGLE_VALUE attribute</li>
-<li>remove a value which is used by the RDN</li>
-<li>delete all the values of a mandatory attribute</li>
-<li>have the right to modify the entry</li>
-<li>try to update a non existent entry</li>
+<li>never inject more than one value in a SINGLE_VALUE attribute</li>
+<li>never remove a value which is used by the RDN</li>
+<li>never delete all the values of a mandatory attribute</li>
+<li>always have the right to modify the entry</li>
+<li>never try to update a non-existent entry</li>
</ul>