<!--

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="quickstart-jdk"><title>Getting Started With &DirectorySDKForJava;</title>
<highlights>
<para>This chapter shows how to develop a first LDAP client with the &DirectorySDKForJava;.
</para>
<itemizedlist>
<para>This chapter covers the following topics:</para>
<listitem><para><olink targetptr="understanding-java-classes">Understanding
the LDAP Java Classes</olink></para></listitem>
<listitem><para><olink targetptr="understanding-sample">Understanding the
Sample Java Client</olink></para></listitem>
<listitem><para><olink targetptr="sample-code">Sample Java Code</olink></para>
</listitem>
</itemizedlist>
</highlights>
<sect1 id="understanding-java-classes"><title>Understanding the LDAP Java
Classes</title>
<indexterm>
<primary>packages</primary>
<secondary>summary of</secondary>
</indexterm><indexterm>
<primary>&DirectorySDKForJava;</primary>
<secondary>packages</secondary>
</indexterm>
<para>&DirectorySDKForJava; includes the LDAP Java classes, which you use
to build LDAP clients. The LDAP Java classes allow you to write client applications
that connect to LDAP servers. The classes also allow you to perform standard
LDAP operations. For example, you can search for entries. You can also add,
update, or delete entries.</para>
<para>The classes are organized in the following packages.</para>
<variablelist>
<varlistentry><term><literal>com.netscape.sasl</literal></term>
<listitem><para>Contains the interfaces and classes that you can use to enable
your client to authenticate by using a SASL mechanism.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>com.netscape.sasl.mechanisms</literal></term>
<listitem><para>Contains an implementation of the <literal>EXTERNAL</literal> SASL
mechanism driver.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>netscape.ldap</literal></term>
<listitem><para>Contains the main LDAP Java classes, including classes that
allow you to connect to an LDAP server, manipulate entries and attributes,
and retrieve search results.</para>
</listitem>
</varlistentry>
<!--<varlistentry><term><literal>netscape.ldap.beans</literal></term>
<listitem><para>Contains LDAP <trademark>JavaBeans
</trademark> technology. You can use LDAP JavaBeans
classes in a development environment such as Sun Java
Studio.</para>
</listitem>
</varlistentry>-->
<varlistentry><term><literal>netscape.ldap.ber.stream</literal></term>
<listitem><para>Contains the LDAP Java classes that implement the <firstterm>Basic
Encoding Rules</firstterm> (BER) for transfer syntax. For more information
about BER, see ISO-IEC 8825 at <ulink url="http://www.iso.ch/" type="url">http://www.iso.ch/
</ulink>.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>netscape.ldap.controls</literal></term>
<listitem><para>Contains the LDAP Java classes that implement specific LDAP
v3 controls. The implementations include controls to request server-side sorting
and persistent searches.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>netscape.ldap.factory</literal></term>
<listitem><para>Contains classes that allow you to create an SSL socket connection
to a server.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>netscape.ldap.util</literal></term>
<listitem><para>Contains utility classes, such as classes to parse LDIF data
and filters that allow regular expression matching.</para>
</listitem>
</varlistentry>
</variablelist>
<para>Clients typically execute methods in &DirectorySDKForJava; synchronously.
All LDAP operations block until the operations are completed, except for the <literal>
search</literal> method, which can return information before all the results
have been received.</para>
<para>An asynchronous interface is also provided for circumstances that require
low-level interaction with an LDAP server. The asynchronous interface is discussed
more fully in <olink targetptr="asynchronous">Chapter&nbsp;13, Writing Asynchronous Clients With Directory SDK for Java</olink>.</para></sect1>
<sect1 id="understanding-sample"><title>Understanding the Sample Java Client</title>
<para>The sample client in this chapter retrieves the full name (<literal>cn</literal>),
last name (<literal>sn</literal>), email address (<literal>mail</literal>),
and telephone number (<literal>telephoneNumber</literal>) of Barbara Jensen.
You can find the program in the <filename>GetAttrs.java</filename> file in
the <filename class="directory">examples/java</filename> directory.</para>
<orderedlist>
<para>The client does the following:</para>
<listitem><para>Creates a new <classname>LDAPConnection</classname> object,
which represents the connection to the LDAP server</para></listitem>
<listitem><para>Connects to the server</para></listitem>
<listitem><para>Searches for a single entry, identified by the DN using the
following search criteria:</para>
<itemizedlist>
<listitem><para>The base DN, the starting point for the search, is <literal>uid=bjensen,ou=People,dc=example,dc=com
</literal>.</para></listitem>
<listitem><para>The search scope is <literal>LDAPConnection.SCOPE_BASE</literal>,
meaning only the base DN.</para></listitem>
<listitem><para>The search filter is <literal>"objectclass=*"</literal>, meaning
the filter matches any entry.</para><para>As the scope narrows the search
to a single entry, the search filter does not need to be more specific. </para>
</listitem>
</itemizedlist>
<para>To invoke a search on a single entry with these parameters is equivalent
to using the <literal>LDAPConnection.read</literal> method.</para>
</listitem>
<listitem><para>Iterates through the enumerated search results to retrieve
and print the values of the <literal>cn</literal>, <literal>sn</literal>, <literal>
mail</literal>, and <literal>telephoneNumber</literal> attributes</para><para>This
iteration also allows the client to obtain multiple values for a single attribute.
</para></listitem>
<listitem><para>Disconnects from the server</para></listitem></orderedlist>
<para>Before you compile the sample client, make sure that the <filename>packages/ldapjdk.jar
</filename> file is in your <envar>CLASSPATH</envar>.</para></sect1>
<sect1 id="sample-code"><title>Sample Java Code</title>
<programlisting>import netscape.ldap.*;
import netscape.ldap.util.*;
import java.util.*;

public class GetAttrs {
    public static void main( String[] args ) {
        try {
            UserArgs userArgs = new UserArgs("GetAttrs", args, false);
            LDAPConnection ld = new LDAPConnection();
            ld.connect(userArgs.getHost(), userArgs.getPort());

            String ENTRYDN = "uid=bjensen, ou=People, dc=example,dc=com";
            String[] attrNames = {
                "cn",               // Get canonical name(s) (full name)
                "sn",               // Get surname(s) (last name)
                "mail",             // Get email address(es)
                "telephonenumber"}; // Get telephone number(s)
            LDAPSearchResults res =
                ld.search(ENTRYDN, ld.SCOPE_BASE, "(objectclass=*)",
                    attrNames, false );

            /* Loop on results until finished; only one entry here */
            while (res.hasMoreElements()) {
                LDAPEntry findEntry = null;
                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.out.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);
                        }
                    }
                }
            }

            ld.disconnect();
        }
        catch(LDAPException e) {
            System.out.println("Error: " + e.toString());
        }
    }
}</programlisting>
</sect1>
</chapter>
