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: