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 2017/03/02 20:31:17 UTC
svn commit: r1007590 - in /websites/staging/directory/trunk/content: ./
api/user-guide/2.3-searching.html
Author: buildbot
Date: Thu Mar 2 20:31:17 2017
New Revision: 1007590
Log:
Staging update by buildbot for directory
Modified:
websites/staging/directory/trunk/content/ (props changed)
websites/staging/directory/trunk/content/api/user-guide/2.3-searching.html
Propchange: websites/staging/directory/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Thu Mar 2 20:31:17 2017
@@ -1 +1 @@
-1785190
+1785192
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 Thu Mar 2 20:31:17 2017
@@ -190,9 +190,8 @@ h2:hover > .headerlink, h3:hover > .head
<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>
+<span class="k">for</span> <span class="o">(</span> <span class="n">Entry</span> <span class="n">entry</span> <span class="o">:</span> <span class="n">cursor</span> <span class="o">)</span>
<span class="o">{</span>
- <span class="n">Entry</span> <span class="n">entry</span> <span class="o">=</span> <span class="n">cursor</span><span class="o">.</span><span class="na">getEntry</span><span class="o">();</span>
<span class="n">assertNotNull</span><span class="o">(</span> <span class="n">entry</span> <span class="o">);</span>
<span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span> <span class="n">entry</span> <span class="o">);</span>
<span class="o">}</span>
@@ -206,17 +205,16 @@ h2:hover > .headerlink, h3:hover > .head
<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 remains in memory forever (causing a memory leak)!</p>
+<p><strong>Note</strong> Don't forget to close the cursor, otherwise the associated data remains in memory forever (causing a memory leak)! Best practice is to use try-with-resources statement.</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. 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>
+<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>
-<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>
+<span class="k">for</span> <span class="o">(</span> <span class="n">Entry</span> <span class="n">entry</span> <span class="o">:</span> <span class="n">cursor</span> <span class="o">)</span>
<span class="o">{</span>
- <span class="n">Entry</span> <span class="n">entry</span> <span class="o">=</span> <span class="n">cursor</span><span class="o">.</span><span class="na">getEntry</span><span class="o">();</span>
<span class="n">assertNotNull</span><span class="o">(</span> <span class="n">entry</span> <span class="o">);</span>
<span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span> <span class="n">entry</span> <span class="o">);</span>
<span class="o">}</span>
@@ -227,55 +225,54 @@ h2:hover > .headerlink, h3:hover > .head
<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 : 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>
+<p>There are three different different scopes you can use to search for data:</p>
+<ul>
+<li>SearchScope.OBJECT : return the entry for a given DN, if it exists. Note that you could use <code>LdapConnection.lookup</code> if the filter is irrelevent.</li>
+<li>SearchScope.ONELEVEL : return all elements below the current DN, but not the element associated with the DN.</li>
+<li>SearchScope.SUBLEVEL : return all the elements starting from the given DN, including the element associated with the DN, whatever the depth of the tree.</li>
+</ul>
<h3 id="filter">Filter<a class="headerlink" href="#filter" title="Permanent link">¶</a></h3>
<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>Connectors 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>
-</pre></div>
-
-
+<ul>
+<li>& : n-ary AND connector, all the nodes must evaluate to TRUE</li>
+<li>| : n-ary OR connector, at least one of the node must evaluate to true</li>
+<li>! : 1-ary NOT connector, the node must evaluate to false</li>
+</ul>
<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>
-<span class="o">*</span> <span class="o"><</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>
-
-
+<ul>
+<li><code>=</code> Equality expression node : the selected entry matches the right part</li>
+<li><code>=*</code> Presence expression node : the entry has the Attribute on the left side</li>
+<li><code>>=</code> Superior expression node : the entry should be superior to the right part</li>
+<li><code><=</code> Inferior expression node : the entry should be superior to the right part</li>
+<li><code>=[start][*][middle][*][final]</code> Substring expression node : the entry should match a substring</li>
+</ul>
<blockquote>
<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>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 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>
-<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>Sometimes, you want to have more control over the search operation, either with the parameters in use, or the results that are returned.</p>
+<p>A search can return other things than entries. In fact, you can get four different kinds of responses:</p>
+<ul>
+<li>When it's a normal entry, you will receive a SearchResultEntry</li>
+<li>When it's done, you will receive a SearchResultDone</li>
+<li>When the response is a reference to another entry, you will get a SearchResultReference</li>
+<li>In some cases, you may also receive an IntermediateResponse.</li>
+</ul>
+<p>You may also add a Control to the search request, or request some specific AttributeType to be returned. The parameters that may be injected into a SearchRequest are as follows:</p>
+<ul>
+<li>The base DN </li>
+<li>The filter</li>
+<li>The scope (one of OBJECT, ONELEVEL or SUBTREE)</li>
+<li>The size limit</li>
+<li>The time limit</li>
+<li>The list of attributes to return</li>
+<li>The alias dereferencing mode (one of DEREF_ALWAYS, DEREF_FINDING_BASE_OBJ, DEREF_IN_SEARCHING or NEVER_DEREF_ALIASES)</li>
+<li>The TypesOnly flag (to get the AttributeTypes but no values)</li>
+<li>The controls</li>
+</ul>
<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>