<!--

Copyright 2000-2007 Sun Microsystems, Inc. All Rights Reserved.
Portions copyright 1999 Netscape Communications Corporation. All
Rights Reserved.

The contents of this document are subject to the terms of the
Creative Commons Attribution-ShareAlike 2.5 license or any later
version (the "License"). You may not use this document except in
compliance with the License.

See the License for the specific language governing
permissions and limitations under the License. You can obtain
a copy of the License at
http://creativecommons.org/licenses/by-sa/2.5/legalcode.

-->
<chapter id="ldap-urls"><title>LDAP URLs With &DirectorySDKForJava;</title>
<highlights>
<para>This chapter describes how to use LDAP URLs to search and retrieve data
from the directory.</para>
<itemizedlist>
<para>This chapter covers the following topics:</para>
<listitem><para><olink targetptr="url-components">Getting the Components of
an LDAP URL With Directory SDK for Java</olink></para></listitem>
<listitem><para><olink targetptr="url-processing">Processing an LDAP URL With
Directory SDK for Java</olink></para></listitem>
<listitem><para><olink targetptr="url-search-example">Searching Using an LDAP
URL With Directory SDK for Java</olink></para></listitem>
</itemizedlist>
</highlights>
<sect1 id="url-components"><title>Getting the Components of an LDAP URL With &DirectorySDKForJava;</title>
<itemizedlist>
<para>To get the individual components of an LDAP URL, pass the URL to the <literal>
LDAPUrl</literal> constructor to create a new <classname>LDAPUrl</classname> object.
Then, use the following methods:</para>
<listitem><para>To get an array of the attributes that should be returned
in the search results, use the <literal>getAttributeArray</literal> method.
To get these attributes as an enumeration, use the <literal>getAttributes</literal> method.
</para></listitem>
<listitem><para>To get the host name of the LDAP server, use the <literal>getHost
</literal> method.</para></listitem>
<listitem><para>To get the port number of the LDAP server, use the <literal>getPort
</literal> method.</para></listitem>
<listitem><para>To get the base DN, use the <literal>getDN</literal> method.</para>
</listitem>
<listitem><para>To get the scope of the search, use the <literal>getScope</literal> method.
</para></listitem>
<listitem><para>To get the search filter, use the <literal>getFilter</literal> method.
</para></listitem>
</itemizedlist>
</sect1>
<sect1 id="url-processing"><title>Processing an LDAP URL With &DirectorySDKForJava;</title>
<itemizedlist>
<para>To process the search request specified by an LDAP URL, you can invoke
one of the following methods, passing in the <classname>LDAPUrl</classname> object:
</para>
<listitem><para>If the URL specifies a base search for a single entry, invoke
the <literal>read</literal> method of the <classname>LDAPConnection</classname> object.
This method reads the entry from the directory.</para></listitem>
<listitem><para>Otherwise, invoke the <literal>search</literal> method of
the <classname>LDAPConnection</classname> object to perform the search.</para>
</listitem>
</itemizedlist>
<para>Both methods create a new <classname>LDAPConnection</classname> object
and connect to the LDAP server specified in the URL. Next, the methods perform
the search. Then the methods disconnect.</para></sect1>
<sect1 id="url-search-example"><title>Searching Using an LDAP URL With &DirectorySDKForJava;</title>
<para>The following example demonstrates a search that uses an LDAP URL, invoking
the <literal>search</literal> method of the <classname>LDAPConnection</classname> object
to perform the search. Before the search is performed, the LDAP URL is exploded
using the methods suggested previously in this chapter.</para>
<programlisting>import netscape.ldap.*;
import netscape.ldap.util.*;
import java.net.MalformedURLException;
import java.util.*;

public class SrchUrl {
    public static void main( String[] args ) {
        LDAPConnection ld = null;
        LDAPEntry findEntry = null;
        int status = -1;
        try {
            UserArgs userArgs = new UserArgs("SrchUrl", args, false);
            ld = new LDAPConnection();
            ld.connect(userArgs.getHost(), userArgs.getPort());

            LDAPUrl myUrl = new LDAPUrl(
                "ldap://" +
                userArgs.getHost() +            // server host
                ":" +
                userArgs.getPort() +            // server port
                "/" +
                "dc=example,dc=com" +           // base DN
                "?" +
                "cn,sn,mail,telephonenumber" +  // attrs to retrieve
                "?" +
                "sub" +                         // search scope
                "?" +
                "(uid=bjensen)");               // search filter

            System.out.println( "LDAP URL : " + myUrl.toString() );
            System.out.println( "   host  : " + myUrl.getHost() );
            System.out.println( "   port  : " + myUrl.getPort() );
            System.out.println( "   baseDN: " + myUrl.getDN() );
            String [] myAttrs = myUrl.getAttributeArray();
            for ( String myAttr: myAttrs ) {
                 System.out.println( "   attrs : " + myAttr );
            }
            System.out.println( "   scope : " + myUrl.getScope() );
            System.out.println( "   filter: " + myUrl.getFilter() );

            LDAPSearchResults res = ld.search( myUrl );

            /* Loop on results until finished; will only be one! */
            while ( res.hasMoreElements() ) {

                /* Next directory entry, really only one at most */
                try {
                    findEntry = res.next();
                } catch ( LDAPReferralException e ) {
                    System.out.println( "Search reference: " );
                    LDAPUrl refUrls[] = e.getURLs();
                    for (int i=0; i&lt;refUrls.length; i++) {
                        System.out.println( "\t" + refUrls[i].getUrl() );
                    }
                    continue;
                } catch ( LDAPException e ) {
                    System.err.println( "Error: " + e.toString() );
                    continue;
                }

                /* Get the attributes of the entry */
                LDAPAttributeSet findAttrs = findEntry.getAttributeSet();
                Enumeration enumAttrs = findAttrs.getAttributes();

                /* Loop on attributes */
                while ( enumAttrs.hasMoreElements() ) {
                    LDAPAttribute anAttr =
                        (LDAPAttribute)enumAttrs.nextElement();
                    String attrName = anAttr.getName();
                    if ( attrName.equals( "cn" ) )
                        System.out.println( "Full name:" );
                    else if ( attrName.equals( "sn" ) )
                        System.out.println( "Last name (surname):" );
                    else if ( attrName.equals( "mail" ) )
                        System.out.println( "Email address:" );
                    else if ( attrName.equals( "telephonenumber" ) )
                        System.out.println( "Telephone number:" );
                    /* Loop on values for this attribute */
                    Enumeration enumVals = anAttr.getStringValues();
                    if (enumVals != null) {
                        while ( enumVals.hasMoreElements() ) {
                            String aVal = ( String )enumVals.nextElement();
                            System.out.println( "\t" + aVal );
                        }
                    }
                }
            }
        }
        catch( LDAPException e ) {
            System.err.println( "Error: " + e.toString() );
        }
        catch( MalformedURLException e ) {
            System.err.println( "Error: " + e.toString() );
        }

        /* Done, so disconnect */
        if ( (ld != null) &amp;&amp; ld.isConnected() ) {
            try {
                ld.disconnect();
            } catch ( LDAPException e ) {
                System.out.println( "Error: " + e.toString() );
            }
        }
        System.exit(status);
    }
}</programlisting>
<para>When this program is compiled and run against a directory that holds
Barbara Jensen's entry, the program generates the following output.</para>
<screen>$ <userinput>java SrchUrl -h myhost -p 1389</userinput>
LDAP URL : ldap://myhost:1389/dc=example,dc=com?cn,sn,mail,telephonenumber?sub?(uid=bjensen)
   host  : mykryten
   port  : 1389
   baseDN: dc=example,dc=com
   attrs : cn
   attrs : sn
   attrs : mail
   attrs : telephonenumber
   scope : 2
   filter: (uid=bjensen)
Full name:
        Barbara Jensen
        Babs Jensen
Last name (surname):
        Jensen
Email address:
        bjensen@example.com
Telephone number:
        +1 408 555 1862</screen>
</sect1>
</chapter>
