directory-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From elecha...@apache.org
Subject svn commit: r1819438 - in /directory/site/trunk/content/api: user-guide.mdtext user-guide/6.7-control.mdtext
Date Thu, 28 Dec 2017 19:34:21 GMT
Author: elecharny
Date: Thu Dec 28 19:34:21 2017
New Revision: 1819438

URL: http://svn.apache.org/viewvc?rev=1819438&view=rev
Log:
Added a more complex example of control usage from teh clinet POV

Modified:
    directory/site/trunk/content/api/user-guide.mdtext
    directory/site/trunk/content/api/user-guide/6.7-control.mdtext

Modified: directory/site/trunk/content/api/user-guide.mdtext
URL: http://svn.apache.org/viewvc/directory/site/trunk/content/api/user-guide.mdtext?rev=1819438&r1=1819437&r2=1819438&view=diff
==============================================================================
--- directory/site/trunk/content/api/user-guide.mdtext (original)
+++ directory/site/trunk/content/api/user-guide.mdtext Thu Dec 28 19:34:21 2017
@@ -100,7 +100,7 @@ We are interested in improving the conte
     *  [6.4 - AttributeType (...)](user-guide/6.4-attribute-type.html)
     *  [6.5 - Ava](user-guide/6.5-ava.html)
     *  [6.6 - Csn](user-guide/6.6-csn.html)
-    *  [6.7 - Control (e)](user-guide/6.7-control.html)
+    *  [6.7 - Control (...)](user-guide/6.7-control.html)
     *  [6.8 - Cursor (e)](user-guide/6.8-cursor.html)
     *  [6.9 - Dn](user-guide/6.9-dn.html)
     *  [6.10 - DITContentRule (e)](user-guide/6.10-dit-content-rule.html)

Modified: directory/site/trunk/content/api/user-guide/6.7-control.mdtext
URL: http://svn.apache.org/viewvc/directory/site/trunk/content/api/user-guide/6.7-control.mdtext?rev=1819438&r1=1819437&r2=1819438&view=diff
==============================================================================
--- directory/site/trunk/content/api/user-guide/6.7-control.mdtext (original)
+++ directory/site/trunk/content/api/user-guide/6.7-control.mdtext Thu Dec 28 19:34:21 2017
@@ -24,7 +24,10 @@ Notice: Licensed to the Apache Software
 
 # 6.7 - Control (...)
 
-A *LDAP* *Control* is an extension to an operation. It tells the server to do something aside
the standard operation, or it let the server send back some information to the client.
+A *LDAP* *Control* is an extension to an operation. It tells the server to do something aside
the standard operation, or it let the server send back some information to the client. A *Control*
contains three different parts :
+* An identifier, the control *OID*
+* A flag telling the server what to do if it does not know about the control or if it results
in an error (either return an error or ignore the control)
+* A value which is generally *BER* encoded
 
 There are many controls available, some being standardized, other being server specific.
 
@@ -70,3 +73,78 @@ The C/S column indicate if the control i
 | SyncStateValue | 1.3.6.1.4.1.4203.1.9.1.2 | Gives the syncrepl state | C | [RFC 4533](https://tools.ietf.org/html/rfc4533)
| AP/OL |
 | VirtualListViewRequest | 2.16.840.1.113730.3.4.9 | Sent to the server to request a subset
of results | S | [Scrolling View Browsing of Search Results](https://tools.ietf.org/html/draft-ietf-ldapext-ldapv3-vlv-09)
| AP |
 | VirtualListViewResponse | 2.16.840.1.113730.3.4.10 | Sent back to the client to give the
search current status | C | [Scrolling View Browsing of Search Results](https://tools.ietf.org/html/draft-ietf-ldapext-ldapv3-vlv-09)
| AP |
+
+## How to use controls
+
+It's quite simple. You just have to instanciate the control you want to use, set its value,
and add it to the request you will send to the server. Here is an example with the *ManageDsaIT*
control :
+
+    :::Java
+    AddRequest addRequest = new AddRequestImpl();       // Create the request
+    ManageDsaIT manageDSAIT = new ManageDsaITImpl();    // Instanciate the control
+    manageDSAIT.setCritical( true );                    // Set a value
+    addRequest.addControl( manageDSAIT );               // Add the control to the request
+    ...
+
+
+and that's it !
+
+On the client side, you may want to check if there is a control and read it if so. This is
a bit more complex, because you need to know which kind of control you are expecting. We will
see with a more complex control, the *Paged Search* control (which allows the user to get
a specific number of enries at each call). Here, we will fetch 4 entries in one go, until
all the entries have been read, and as we have 10 entries to read, we will send 3 *SearchRequest*,
teh first two will return 4 entries and teh last one only 2.
+
+
+    :::Java
+    try ( LdapConnection connection = new LdapNetworkConnection( "MyServer", 389 ) )
+    {
+        connection.bind( "cn=user,ou=system", "secret" );
+
+        // Create the control, and tell it we want 4 entries for every call
+        PagedResults pagedControl = new PagedResultsImpl();
+        pagedControl.setSize( 4 );
+    
+        // Read all the elements
+        List<Entry> results = new ArrayList<>();
+
+        // Create the SearchRequest
+        SearchRequest searchRequest = new SearchRequestImpl();
+        searchRequest.setBase( new Dn( "dc=users,ou=system" ) );
+        searchRequest.setFilter( "(cn=*)" );
+        searchRequest.setScope( SearchScope.SUBTREE );
+    
+        while ( true )
+        {
+            // Add the PagedSearch control to teh SearchRequest
+            searchRequest.addControl( pagedControl );
+                
+            // Do the search now
+            try ( SearchCursor cursor = connection.search( searchRequest ) )
+            {
+                // Loop on all teh entries we got back (Should be 4, or less)
+                while ( cursor.next() )
+                {
+                    Entry result = cursor.getEntry();
+                    results.add( result );
+                }
+        
+                // Now check the returned controls
+                Map<String, Control> controls =  cursor.getSearchResultDone().getControls();
+
+                // We should get a PagedResult response
+                PagedResults responseControl = ( PagedResults ) controls.get( PagedResults.OID
);
+
+                // check if this is over, ie teh cookie is empty
+                byte[] cookie = responseControl.getCookie();
+                
+                if ( Strings.isEmpty( cookie ) )
+                {
+                    // Ok, we are done
+                    break;
+                }
+
+                // Prepare the next iteration, sending a bad cookie
+                pagedControl.setCookie( cookie );
+            }
+        }
+
+        // At this point, we should have read 10 entries
+    }
+ 
+Side note : in this piece of code, we don't close the connection nor the cursor, because
they are *Closeable* : They will be close when we exit the _try_ scope. This is a feature
added in *Java 7*, called *try with resources*
\ No newline at end of file



Mime
View raw message