directory-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r1007590 - in /websites/staging/directory/trunk/content: ./ api/user-guide/2.3-searching.html
Date Thu, 02 Mar 2017 20:31:17 GMT
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">&quot;ou=system&quot;</span><span class="o">,</span>
<span class="s">&quot;(objectclass=*)&quot;</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">&para;</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">&quot;ou=system&quot;</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">&quot;ou=system&quot;</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">&quot;(objectclass=*)&quot;</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">&para;</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">&para;</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 (&amp; (node1) (node2) ... (nodeN))</p>
+<p>Connectors use a prefix notation, followed by as many expression nodes as necessary,
like in (&amp; (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">&amp;</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>&amp; : 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">&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>
-
-
+<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>&gt;=</code> Superior expression node : the entry should
be superior to the right part</li>
+<li><code>&lt;=</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">&para;</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">&#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 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>



Mime
View raw message