From commits-return-27263-apmail-directory-commits-archive=directory.apache.org@directory.apache.org Wed Sep 01 13:34:02 2010
Return-Path: <commits-return-27263-apmail-directory-commits-archive=directory.apache.org@directory.apache.org>
Delivered-To: apmail-directory-commits-archive@www.apache.org
Received: (qmail 86548 invoked from network); 1 Sep 2010 13:34:02 -0000
Received: from unknown (HELO mail.apache.org) (140.211.11.3)
  by 140.211.11.9 with SMTP; 1 Sep 2010 13:34:02 -0000
Received: (qmail 39089 invoked by uid 500); 1 Sep 2010 13:34:01 -0000
Delivered-To: apmail-directory-commits-archive@directory.apache.org
Received: (qmail 39028 invoked by uid 500); 1 Sep 2010 13:34:00 -0000
Mailing-List: contact commits-help@directory.apache.org; run by ezmlm
Precedence: bulk
List-Help: <mailto:commits-help@directory.apache.org>
List-Unsubscribe: <mailto:commits-unsubscribe@directory.apache.org>
List-Post: <mailto:commits@directory.apache.org>
List-Id: <commits.directory.apache.org>
Reply-To: dev@directory.apache.org
Delivered-To: mailing list commits@directory.apache.org
Received: (qmail 39020 invoked by uid 99); 1 Sep 2010 13:33:59 -0000
Received: from nike.apache.org (HELO nike.apache.org) (192.87.106.230)
    by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 01 Sep 2010 13:33:59 +0000
X-ASF-Spam-Status: No, hits=-2000.0 required=10.0
	tests=ALL_TRUSTED
X-Spam-Check-By: apache.org
Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4)
    by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 01 Sep 2010 13:33:51 +0000
Received: by eris.apache.org (Postfix, from userid 65534)
	id 6FDB223889ED; Wed,  1 Sep 2010 13:32:32 +0000 (UTC)
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Subject: svn commit: r991532 -
 /directory/apacheds-manuals/trunk/src/basic-user-guide/handling-of-data-3-operations.xml
Date: Wed, 01 Sep 2010 13:32:32 -0000
To: commits@directory.apache.org
From: szoerner@apache.org
X-Mailer: svnmailer-1.0.8
Message-Id: <20100901133232.6FDB223889ED@eris.apache.org>
X-Virus-Checked: Checked by ClamAV on apache.org

Author: szoerner
Date: Wed Sep  1 13:32:32 2010
New Revision: 991532

URL: http://svn.apache.org/viewvc?rev=991532&view=rev
Log:
Added some content for search (command line tools, JNDI)

Modified:
    directory/apacheds-manuals/trunk/src/basic-user-guide/handling-of-data-3-operations.xml

Modified: directory/apacheds-manuals/trunk/src/basic-user-guide/handling-of-data-3-operations.xml
URL: http://svn.apache.org/viewvc/directory/apacheds-manuals/trunk/src/basic-user-guide/handling-of-data-3-operations.xml?rev=991532&r1=991531&r2=991532&view=diff
==============================================================================
--- directory/apacheds-manuals/trunk/src/basic-user-guide/handling-of-data-3-operations.xml (original)
+++ directory/apacheds-manuals/trunk/src/basic-user-guide/handling-of-data-3-operations.xml Wed Sep  1 13:32:32 2010
@@ -243,6 +243,10 @@ under the License.
           <table>
           <title>Search operators</title>
           <tgroup cols="4">
+          <colspec colnum="1" colname="col1" colwidth="2*"/>
+          <colspec colnum="2" colname="col2" colwidth="1*"/>
+          <colspec colnum="3" colname="col3" colwidth="3*"/>
+          <colspec colnum="4" colname="col4" colwidth="3*"/>
 
           <thead>
             <row>
@@ -303,6 +307,10 @@ under the License.
             <table>
             <title>Boolean operators in search filters</title>
             <tgroup cols="4">
+            <colspec colnum="1" colname="col1" colwidth="1*"/>
+            <colspec colnum="2" colname="col2" colwidth="1*"/>
+            <colspec colnum="3" colname="col3" colwidth="4*"/>
+            <colspec colnum="4" colname="col4" colwidth="4*"/>
 
             <thead>
               <row>
@@ -361,13 +369,169 @@ under the License.
      <section id="Searching with a command line tool">
        <title>Searching with a command line tool</title>
        <para>
+       If you connect to ApacheDS with command line tools, you execute searches against the directory with the ldapsearch command.
+       </para>          
+       <para>
+       Here is an example: The query searches all entries below "ou=people,o=sevenSeas" 
+       which match the filter 
+       <![CDATA[(&(objectClass=person)(givenName=William))]]>, 
+       and therefore all persons called William.
+       </para>
+       <programlisting><![CDATA[
+$ ldapsearch -h zanzibar -p 10389 -D "uid=admin,ou=system" -w secret \\ 
+    -b "ou=people,o=sevenSeas" -s sub "(&(objectClass=person)(givenName=William))" uid mail 
+    
+dn: cn=William Bush,ou=people,o=sevenSeas 
+uid: wbush 
+mail: wbush@royalnavy.mod.uk
+
+dn: cn=William Bligh,ou=people,o=sevenSeas 
+uid: wbligh 
+mail: wbligh@royalnavy.mod.uk 
+$
+       ]]></programlisting>
+         
+       <para>
+       The tool returns the attribute values for the attributes given in the command line (uid and mail). 
+       If no attributes are provided, all attributes the user is allowed to read will be returned.
        </para>
+       
+       <table>
+         <title>Command line options used in the search example</title>
+         <tgroup cols="3">
+         <colspec colnum="1" colname="col1" colwidth="1*"/>
+         <colspec colnum="2" colname="col2" colwidth="3*"/>
+         <colspec colnum="3" colname="col3" colwidth="4*"/>
+         <thead>
+           <row>
+             <entry>Option</entry>
+             <entry>Example value</entry>
+             <entry>Meaning</entry>
+           </row>
+         </thead>
+         <tbody>
+            <row>
+              <entry>-h</entry>
+              <entry>zanzibar</entry>
+              <entry>Hostname of LDAP server to connect to (default is localhost)</entry>
+            </row>
+            <row>
+              <entry>-p</entry>
+              <entry>10389</entry>
+              <entry>Port on which the server listens (default is 389)</entry>
+            </row>
+            <row>
+              <entry>-D</entry>
+              <entry>"uid=admin,ou=system"</entry>
+              <entry>Distinguished name of bind user</entry>
+            </row>
+            <row>
+              <entry>-w</entry>
+              <entry>secret</entry>
+              <entry>Password of bind user</entry>
+            </row>
+            <row>
+              <entry>-b</entry>
+              <entry>"ou=people,o=sevenSeas"</entry>
+              <entry>search base</entry>
+            </row>            
+            <row>
+              <entry>-s</entry>
+              <entry>sub</entry>
+              <entry>search scope, one of "base", "one", or "sub" (default is sub)</entry>
+            </row>            
+            
+        </tbody>
+        </tgroup>
+        </table>
+       
+     
      </section>
 
      <section id="Searching with a Java program">
        <title>Searching with a Java program</title>
        <para>
+       Here is the same search as above, performed against the "Seven seas" example from within a Java program with the help of JNDI.
        </para>
+       <programlisting><![CDATA[
+package search;
+
+import java.util.Hashtable;
+
+import javax.naming.Context;
+import javax.naming.NamingEnumeration;
+import javax.naming.NamingException;
+import javax.naming.directory.Attribute;
+import javax.naming.directory.Attributes;
+import javax.naming.directory.DirContext;
+import javax.naming.directory.InitialDirContext;
+import javax.naming.directory.SearchControls;
+import javax.naming.directory.SearchResult;
+
+public class SimpleSearch {
+
+    public static void main(String[] args) throws NamingException {
+
+        // JNDI connection data, move them to jndi.properties
+        Hashtable env = new Hashtable();
+        env.put(Context.INITIAL_CONTEXT_FACTORY, "com.sun.jndi.ldap.LdapCtxFactory");
+        env.put(Context.PROVIDER_URL, "ldap://zanzibar:10389/");
+        env.put(Context.SECURITY_AUTHENTICATION, "simple");
+        env.put(Context.SECURITY_PRINCIPAL, "uid=admin,ou=system");
+        env.put(Context.SECURITY_CREDENTIALS, "secret");
+
+        try {
+            DirContext ctx = new InitialDirContext(env);
+
+            String base = "ou=people,o=sevenSeas";
+            String filter = "(&(objectClass=person)(givenName=William))";
+
+            SearchControls ctls = new SearchControls();
+            ctls.setSearchScope(SearchControls.SUBTREE_SCOPE);
+            ctls.setReturningAttributes(new String[] { "uid", "mail" });
+
+            NamingEnumeration resultEnum = ctx.search(base, filter, ctls);
+            while (resultEnum.hasMore()) {
+                SearchResult result = (SearchResult) resultEnum.next();
+                
+                // print DN of entry
+                System.out.println(result.getNameInNamespace());
+                
+                // print attributes returned by search
+                Attributes attrs = result.getAttributes();
+                NamingEnumeration e = attrs.getAll();
+                while (e.hasMore()) {
+                    Attribute attr = (Attribute) e.next();
+                    System.out.println(attr);
+                }
+                System.out.println();
+            }
+
+            ctx.close();
+        } catch (NamingException e) {
+            System.out.println(e.getMessage());
+        }
+    }
+}
+       ]]></programlisting>       
+       <para>
+       the output of the program looks like this:
+       </para>
+       <programlisting><![CDATA[
+cn=William Bush,ou=people,o=sevenSeas
+mail: wbush@royalnavy.mod.uk
+uid: wbush
+
+cn=William Bligh,ou=people,o=sevenSeas
+mail: wbligh@royalnavy.mod.uk
+uid: wbligh
+       ]]></programlisting>  
+     <para>
+     Key for LDAP searches with JNDI are the search methods in the <emphasis>javax.naming.directory.DirContext</emphasis> interface 
+     (<link xlink:href="http://java.sun.com/j2se/1.5.0/docs/api/javax/naming/directory/DirContext.html">javadoc</link>). 
+     Learn more about JNDI and how to perform searches against an LDAP directory with it in the 
+     <link xlink:href="http://java.sun.com/products/jndi/tutorial/">JNDI tutorial</link>
+     </para>
      </section>
 
      <section id="Searching with a graphical client tool">