You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@directory.apache.org by se...@apache.org on 2017/03/02 20:31:08 UTC
svn commit: r1785192 -
/directory/site/trunk/content/api/user-guide/2.3-searching.mdtext
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: