directory-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r871776 - in /websites/staging/directory/trunk/content: ./ api/user-guide/2.1-connection-disconnection.html api/user-guide/2.3-searching.html api/user-guide/2.4-adding.html api/user-guide/2.5-deleting.html
Date Mon, 29 Jul 2013 22:47:02 GMT
Author: buildbot
Date: Mon Jul 29 22:47:02 2013
New Revision: 871776

Log:
Staging update by buildbot for directory

Modified:
    websites/staging/directory/trunk/content/   (props changed)
    websites/staging/directory/trunk/content/api/user-guide/2.1-connection-disconnection.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

Propchange: websites/staging/directory/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Mon Jul 29 22:47:02 2013
@@ -1 +1 @@
-1508195
+1508223

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
Mon Jul 29 22:47:02 2013
@@ -176,7 +176,7 @@
 </pre></div>
 
 
-<h2 id="using-a-pool-of-connection">Using a pool of connection</h2>
+<h2 id="using-a-pool-of-connections">Using a pool of connections</h2>
 <p>Creating a connection is expensive. If you are to reuse a connection over and over,
or if you are writing an application that will need many LDAP conenctions, you may want to
use a pool of connections.</p>
 <p>This is slightly more complex than simply opening a new connection, as you have
a lot of parametrs that can come into play when creating a pool.
 Here is an example of creation of a pool of connections :</p>

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 Mon Jul 29
22:47:02 2013
@@ -198,13 +198,67 @@
 
 <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="o">*</span><span class="p">=</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">&gt;</span><span
class="p">=</span> <span class="n">Superior</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>
-<span class="o">*</span> <span class="o">&lt;</span><span
class="p">=</span>
-<span class="o">*</span> <span class="o">~=</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">&gt;</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>
+<span class="o">*</span> <span class="o">&lt;</span><span
class="p">=</span> <span class="n">Inferior</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>
+<span class="o">*</span> <span class="p">=</span> <span class="p">[</span><span
class="n">start</span><span class="p">][</span><span class="o">*</span><span
class="p">][</span><span class="n">middle</span><span class="p">][</span><span
class="o">*</span><span class="p">][</span><span class="n">final</span><span
class="p">]</span> <span class="n">Substring</span> <span class="n">expression</span>
<span class="n">nose</span> <span class="p">:</span> <span class="n">the</span>
<span class="n">entry</span> <span class="n">should</span> <span
class="n">match</span> <span class="n">a</span> <span class="n">usbstring</span>
 </pre></div>
 
 
+<blockquote>
+<p><strong>Note:</strong>  As of Apache DS 2.0, we don't support approx
matches not extensible matches.</p>
+</blockquote>
+<h2 id="more-complex-searches">More complex searches</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>
+<div class="codehilite"><pre><span class="o">*</span> <span class="n">When</span>
<span class="n">it</span><span class="o">&#39;</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>
+<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>
+<span class="o">*</span> <span class="n">The</span> <span class="nb">size</span>
<span class="n">limit</span>
+<span class="o">*</span> <span class="n">The</span> <span class="n">time</span>
<span class="n">limit</span>
+<span class="o">*</span> <span class="n">The</span> <span class="n">list</span>
<span class="n">of</span> <span class="n">attributes</span> <span
class="n">to</span> <span class="k">return</span>
+<span class="o">*</span> <span class="n">The</span> <span class="n">alias</span>
<span class="n">dereferencing</span> <span class="n">mode</span> <span
class="p">(</span><span class="n">one</span> <span class="n">of</span>
<span class="n">DEREF_ALWAYS</span><span class="p">,</span> <span
class="n">DEREF_FINDING_BASE_OBJ</span><span class="p">,</span> <span
class="n">DEREF_IN_SEARCHING</span> <span class="n">or</span> <span
class="n">NEVER_DEREF_ALIASES</span><span class="p">)</span>
+<span class="o">*</span> <span class="n">The</span> <span class="n">TypesOnly</span>
<span class="n">flag</span> <span class="p">(</span><span class="n">to</span>
<span class="n">get</span> <span class="n">the</span> <span class="n">AttributeTypes</span>
<span class="n">but</span> <span class="n">no</span> <span class="n">values</span><span
class="p">)</span>
+<span class="o">*</span> <span class="n">The</span> <span class="n">controls</span>
+</pre></div>
+
+
+<p>In both case, you should fill a <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>
+<span class="n">req</span><span class="o">.</span><span class="na">addAttributes</span><span
class="o">(</span> <span class="s">&quot;*&quot;</span> <span
class="o">);</span>
+<span class="n">req</span><span class="o">.</span><span class="na">setTimeLimit</span><span
class="o">(</span> <span class="mi">0</span> <span class="o">);</span>
+<span class="n">req</span><span class="o">.</span><span class="na">setBase</span><span
class="o">(</span> <span class="k">new</span> <span class="n">Dn</span><span
class="o">(</span> <span class="s">&quot;ou=system&quot;</span>
<span class="o">)</span> <span class="o">);</span>
+<span class="n">req</span><span class="o">.</span><span class="na">setFilter</span><span
class="o">(</span> <span class="s">&quot;(cn=user1)&quot;</span>
<span class="o">);</span>
+
+<span class="c1">// Process the request</span>
+<span class="n">SearchCursor</span> <span class="n">searchCursor</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">req</span> <span class="o">);</span>
+
+<span class="k">while</span> <span class="o">(</span> <span class="n">searchCursor</span><span
class="o">.</span><span class="na">next</span><span class="o">()</span>
<span class="o">)</span>
+<span class="o">{</span>
+    <span class="n">Response</span> <span class="n">response</span>
<span class="o">=</span> <span class="n">searchCursor</span><span
class="o">.</span><span class="na">get</span><span class="o">();</span>
+
+    <span class="c1">// process the SearchResultEntry</span>
+    <span class="k">if</span> <span class="o">(</span> <span class="n">response</span>
<span class="k">instanceof</span> <span class="n">SearchResultEntry</span>
<span class="o">)</span>
+    <span class="o">{</span>
+        <span class="n">Entry</span> <span class="n">resultEntry</span>
<span class="o">=</span> <span class="o">(</span> <span class="o">(</span>
<span class="n">SearchResultEntry</span> <span class="o">)</span>
<span class="n">response</span> <span class="o">).</span><span
class="na">getEntry</span><span class="o">();</span>
+        <span class="o">...</span>
+    <span class="o">}</span>
+<span class="o">}</span>
+</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>
+
+
     <div class="nav">
         <div class="nav_prev">
         

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 Mon Jul 29 22:47:02
2013
@@ -140,7 +140,7 @@
 <h1 id="24-adding-entries">2.4 - Adding entries</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>
 <h2 id="adding-an-entry">Adding an entry</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 <strong><a href="">Dn</a></strong>) and
the list of its <strong><a href="">Attributes</a></strong>.</p>
+<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>
 <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>
@@ -189,7 +189,7 @@ 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>
-<h2 id="sending-an-addrequest">Sending an <strong><a href="">AddRequest</a></strong></h2>
+<h2 id="sending-an-addrequest">Sending an <em>AddRequest</em></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>
 <div class="codehilite"><pre><span class="nd">@Test</span>
@@ -251,16 +251,16 @@ Note that it is possible to use some var
 <h2 id="do-dont">Do, Don't</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>
 <ul>
-<li>The entry must have at least one <strong>Structural</strong> <strong><a
href="">ObjectClass</a></strong></li>
-<li>If the entry has more than one <strong>Structural</strong> <strong><a
href="">ObjectClass</a></strong>, then they must be hierarchically related</li>
-<li>The <em>[DIRAPI:ObjectClass]es</em> define the list of allowed <strong>Structural</strong>
<strong><a href="">AttributeTypes</a></strong> that can be used (<strong>MAY</strong>
and <strong>MUST</strong>)</li>
+<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>
+<li>The <em>ObjectClasses</em> define the list of allowed <strong>Structural</strong>
<em>AttributeTypes</em> that can be used (<strong>MAY</strong> and
<strong>MUST</strong>)</li>
 <li>All the <strong>MUST</strong> <strong><a href="">AttributeTypes</a></strong>
must be present</li>
-<li>Each added value must follow the <strong>[DIRAPI:AttributeType]</strong>
<strong><a href="">Syntax</a></strong></li>
-<li>If the <strong>[DIRAPI:AttributeType]</strong> is single valued, then
you can't add more than one value</li>
-<li>The entry's <strong><a href="">Dn</a></strong> must have
a parent</li>
+<li>Each added value must follow the <em>AttributeType</em> <em>Syntax</em></li>
+<li>If the <em>AttributeType</em> is single valued, then you can't add
more than one value</li>
+<li>The entry's <em>Dn</em> must have a parent</li>
 <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
<strong><a href="">NameForms</a></strong>, <strong><a href="">DITStructureRules</a></strong>
or <em><a href="">DITContentRules</a></em>*.</p>
+<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>
 <h2 id="errors">Errors</h2>
 <DIV class="note" markdown="1">
@@ -270,7 +270,7 @@ In any other case, the server will simpl
 </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 <strong><a href="">LdapResult</a></strong> in the response
will give you a clue about what going on.</p>
+<p>The <em>LdapResult</em> in the response will give you a clue about what
going on.</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 Mon Jul 29 22:47:02
2013
@@ -138,9 +138,9 @@
 
 
 <h1 id="25-deleting-entries">2.5 - Deleting entries</h1>
-<p>Deleting an entry is really easy. It's just a matter to know its <strong><a
href="">Dn</a></strong>. 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 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>
 <h2 id="simple-entry-deletion">Simple entry deletion</h2>
-<p>We can ask the deletion by providing the entry's <strong><a href="">Dn</a></strong>,
like what is done in the following example :</p>
+<p>We can ask the deletion by providing the entry's <em>DN</em>, like what
is done 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>
@@ -188,7 +188,7 @@
 
 
 <h2 id="sending-a-deleterequest-with-a-control">Sending a DeleteRequest with a control</h2>
-<p>It's also possible to associate a <strong>[Control]</strong> with the
delete request. In order to do that, you have to create a <strong><a href="">DelRequest</a></strong>
instance. In the following example, we will add the Delete Tree control (this make this call
equivalent to the <em>deleteTree()</em> method).</p>
+<p>It's also possible to associate a <strong>[Control]</strong> with the
delete request. In order to do that, you have to create a <em>DelRequest</em>
instance. In the following example, we will add the Delete Tree control (this make this call
equivalent to the <em>deleteTree()</em> method).</p>
 <div class="codehilite"><pre><span class="nd">@Test</span>
 <span class="kd">public</span> <span class="kt">void</span> <span
class="nf">testDeleteWithControl</span><span class="o">()</span> <span
class="kd">throws</span> <span class="n">Exception</span>
 <span class="o">{</span>



Mime
View raw message