directory-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From seelm...@apache.org
Subject svn commit: r1785192 - /directory/site/trunk/content/api/user-guide/2.3-searching.mdtext
Date Thu, 02 Mar 2017 20:31:08 GMT
Author: seelmann
Date: Thu Mar  2 20:31:08 2017
New Revision: 1785192

URL: http://svn.apache.org/viewvc?rev=1785192&view=rev
Log:
Fix code examples
Fix formatting
Typos

Modified:
    directory/site/trunk/content/api/user-guide/2.3-searching.mdtext

Modified: directory/site/trunk/content/api/user-guide/2.3-searching.mdtext
URL: http://svn.apache.org/viewvc/directory/site/trunk/content/api/user-guide/2.3-searching.mdtext?rev=1785192&r1=1785191&r2=1785192&view=diff
==============================================================================
--- directory/site/trunk/content/api/user-guide/2.3-searching.mdtext (original)
+++ directory/site/trunk/content/api/user-guide/2.3-searching.mdtext Thu Mar  2 20:31:08 2017
@@ -35,13 +35,12 @@ Let's first look at a simple search. To
     :::java
     EntryCursor cursor = connection.search( "ou=system", "(objectclass=*)", SearchScope.ONELEVEL
);
     
-    while ( cursor.next() )
+    for ( Entry entry : cursor )
     {
-        Entry entry = cursor.getEntry();
         assertNotNull( entry );
         System.out.println( entry );
     }
-
+    
     cursor.close();
 
 
@@ -53,24 +52,23 @@ That's pretty much it!
 
 But this is not really enough, there are many possible options.
 
->**Note** Don't forget to close the cursor, otherwise the associated data remains in memory
forever (causing a memory leak)!
+>**Note** 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.
 
 ### Searching using a DN
 
 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!
 
     :::java
-    DN systemDn = new Dn( "ou=system" );
+    Dn systemDn = new Dn( "ou=system" );
     ...
     EntryCursor cursor = connection.search( systemDn, "(objectclass=*)", SearchScope.ONELEVEL
);
     
-    while ( cursor.next() )
+    for ( Entry entry : cursor )
     {
-        Entry entry = cursor.getEntry();
         assertNotNull( entry );
         System.out.println( entry );
     }
-
+    
     cursor.close();
 
 This is it!
@@ -78,55 +76,57 @@ This is it!
 ### Scope 
 
 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.
+
+* SearchScope.OBJECT : return the entry for a given DN, if it exists. Note that you could
use `LdapConnection.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.
 
 ### Filter
 
 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.
 
-Connrectors use a prefix notation, followed by as many expression nodes as necessary, like
in (& (node1) (node2) ... (nodeN))
+Connectors use a prefix notation, followed by as many expression nodes as necessary, like
in (& (node1) (node2) ... (nodeN))
 
 Expression nodes are always contained within parenthesis, with a left part - the attributeType,
and a right part - the value -.
 
 Here is the list of possible connectors:
 
-    * & : n-ary AND connector, all the nodes must evaluate to TRUE
-    * | : n-ary OR connector, at least one of the node must evaluate to true
-    * ! : 1-ary NOT connector, the node must evaluate to false
+* & : n-ary AND connector, all the nodes must evaluate to TRUE
+* | : n-ary OR connector, at least one of the node must evaluate to true
+* ! : 1-ary NOT connector, the node must evaluate to false
 
 And here is the list of possible expression nodes, assuming that an expression node:
 
-    * = Equality expression node : the selected entry matches the right part
-    * =* Presence expression node : tehentry has the Attribute on the left side
-    * >= Superior expression node : the entry should be superior to the right part
-    * <= Inferior expression node : the entry should be superior to the right part
-    * = [start][*][middle][*][final] Substring expression nose : the entry should match a
usbstring
+* `=` Equality expression node : the selected entry matches the right part
+* `=*` Presence expression node : the entry has the Attribute on the left side
+* `>=` Superior expression node : the entry should be superior to the right part
+* `<=` Inferior expression node : the entry should be superior to the right part
+* `=[start][*][middle][*][final]` Substring expression node : the entry should match a substring
 
 >**Note:**  As of Apache DS 2.0, we don't support approx matches nor extensible matches.
 
 ## More complex searches
 
-Sometimes, you want to have more control over the search opetation, either with the parameters
in use, or the results that are returned.
+Sometimes, you want to have more control over the search operation, either with the parameters
in use, or the results that are returned.
 
-A search things other than entries. In fact, you can get three different kinds of responses:
-    
-    * When it's done, you will receive a SearchResultDone
-    * When the response is a reference to another entry, you will get a SearchResultReference
-    * In some cases, you may also receive an IntermediateResponse.
-
-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:
-
-    * The base DN 
-    * The filter
-    * The Scope (one of OBJECT, ONELEVEL or SUBTREE)
-    * The size limit
-    * The time limit
-    * The list of attributes to return
-    * The alias dereferencing mode (one of DEREF_ALWAYS, DEREF_FINDING_BASE_OBJ, DEREF_IN_SEARCHING
or NEVER_DEREF_ALIASES)
-    * The TypesOnly flag (to get the AttributeTypes but no values)
-    * The controls
+A search can return other things than entries. In fact, you can get four different kinds
of responses:
+
+* When it's a normal entry, you will receive a SearchResultEntry
+* When it's done, you will receive a SearchResultDone
+* When the response is a reference to another entry, you will get a SearchResultReference
+* In some cases, you may also receive an IntermediateResponse.
+
+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:
+
+* The base DN 
+* The filter
+* The scope (one of OBJECT, ONELEVEL or SUBTREE)
+* The size limit
+* The time limit
+* The list of attributes to return
+* The alias dereferencing mode (one of DEREF_ALWAYS, DEREF_FINDING_BASE_OBJ, DEREF_IN_SEARCHING
or NEVER_DEREF_ALIASES)
+* The TypesOnly flag (to get the AttributeTypes but no values)
+* The controls
 
 In both cases, you should fill the _SearchRequest_ message and send it to the server:
 



Mime
View raw message