directory-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r871764 - in /websites/staging/directory/trunk/content: ./ api/user-guide/2.3-searching.html
Date Mon, 29 Jul 2013 20:26:31 GMT
Author: buildbot
Date: Mon Jul 29 20:26:31 2013
New Revision: 871764

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 Mon Jul 29 20:26:31 2013
@@ -1 +1 @@
-1508132
+1508195

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
20:26:31 2013
@@ -140,37 +140,69 @@
 <h1 id="23-searching">2.3 - Searching (...)</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>
-<DIV class="worning" markdown="1">
-This part of the API is very likely to change in the next milestone, to provide an easier
way to get the results in the simple cases.
-</DIV>
-
 <h2 id="simple-search">Simple search</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>
-<div class="codehilite"><pre><span class="nd">@Test</span>
-<span class="kd">public</span> <span class="kt">void</span> <span
class="nf">testSimpleSearch</span><span class="o">()</span> <span
class="kd">throws</span> <span class="n">Exception</span>
+<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="o">{</span>
-    <span class="n">SearchCursor</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="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>
 
-    <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="o">{</span>
-        <span class="n">Response</span> <span class="n">response</span>
<span class="o">=</span> <span class="n">cursor</span><span class="o">.</span><span
class="na">get</span><span class="o">();</span>
-        <span class="n">assertNotNull</span><span class="o">(</span>
<span class="n">response</span> <span class="o">);</span>
-        <span class="n">assertTrue</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="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="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="n">cursor</span><span class="o">.</span><span class="na">close</span><span
class="o">();</span>
+</pre></div>
 
-    <span class="n">SearchResultDone</span> <span class="n">done</span>
<span class="o">=</span> <span class="n">cursor</span><span class="o">.</span><span
class="na">getSearchResultDone</span><span class="o">();</span>
 
-    <span class="n">assertNotNull</span><span class="o">(</span>
<span class="n">done</span> <span class="o">);</span>
-    <span class="n">assertEquals</span><span class="o">(</span> <span
class="n">ResultCodeEnum</span><span class="o">.</span><span class="na">SUCCESS</span><span
class="o">,</span> <span class="n">done</span><span class="o">.</span><span
class="na">getLdapResult</span><span class="o">().</span><span class="na">getResultCode</span><span
class="o">()</span> <span class="o">);</span>
+<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>
+<blockquote>
+<p><strong>Note</strong> Don't forget to close the cursor, otherwise the
associated data will remain in memory foreever !</p>
+</blockquote>
+<h3 id="searching-using-a-dn">Searching using a DN</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>
+<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="n">cursor</span><span class="o">.</span><span
class="na">close</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="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>
+
+<span class="n">cursor</span><span class="o">.</span><span class="na">close</span><span
class="o">();</span>
 </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, which can be walked forward. Every call to the <em>get()</em>
method will return a response, which will be either a <em>SearchResultEntry</em>,
a <em>SearchResultReference</em> or an <em>IntermediateResponse</em>.</p>
+<p>This is it !</p>
+<h3 id="scope">Scope</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>
+<h3 id="filter">Filter</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 (&amp; (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>
+<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>
+
+
+<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>
+</pre></div>
 
 
     <div class="nav">



Mime
View raw message