<!--

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.

-->
<preface id="preface"><title>Preface</title>
<highlights>&abstract;
</highlights>
<sect1 id="who-should-read"><title>Who Should Use This Book</title>
<para>This guide is intended for developers creating directory client applications.
</para>
<itemizedlist>
<para>Before using this guide, you must be familiar with the following:</para>
<listitem><para>&cnDirectoryServer; functionality</para></listitem>
<listitem><para>Developing programs in the <trademark>Java</trademark> programming
language</para></listitem>
<listitem><para>Specifications for LDAP and related protocols, such as DSML
v2</para></listitem>
<listitem><para>Internet and World Wide Web technologies</para></listitem>
</itemizedlist>
</sect1>
<sect1 id="before-you-read"><title>Before You Read This Book</title>
<para>Before developing directory client applications, install &DirectorySDKForJava;.
</para>
<!-- TODO: Need an XREF to installation instructions -->
</sect1>
<sect1 id="reading-for-developers"><title>Additional Recommended Reading</title>
<itemizedlist>
<para>Directory client application developers might benefit from reading the
following books:</para>
<listitem><para><citetitle>LDAP Programming with Java</citetitle> by Weltman
and Dabhura (ISBN 0-201-65758-96)</para></listitem>
<listitem><para><citetitle>LDAP Programming, Management and Integration</citetitle> by
Donley (ISBN 1930110405)</para></listitem>
<listitem><para><citetitle>LDAP: Programming Directory-Enabled Applications
with Lightweight Directory Access Protocol</citetitle> by Howes and Smith
(ISBN 1-57870-000-00)</para></listitem>
<listitem><para><citetitle>Understanding and Deploying LDAP Directory Services</citetitle> by
Howes, et al. (ISBN 1-57870-070-10)</para></listitem>
</itemizedlist>
<itemizedlist>
<para>In addition, keep bookmarks to the following IETF documents:</para>
<listitem><para><ulink url="http://www.ietf.org/rfc/rfc2251.txt" type="text_url">
RFC 2251</ulink>, <citetitle>Lightweight Directory Access Protocol (v3)</citetitle></para>
</listitem>
<listitem><para><ulink url="http://www.ietf.org/rfc/rfc2252.txt" type="text_url">
RFC 2252</ulink>, <citetitle>Lightweight Directory Access Protocol (v3): Attribute
Syntax Definitions</citetitle></para></listitem>
<listitem><para><ulink url="http://www.ietf.org/rfc/rfc2253.txt" type="text_url">
RFC 2253</ulink>, <citetitle>Lightweight Directory Access Protocol (v3): UTF-8
String Representation of Distinguished Names</citetitle></para></listitem>
<listitem><para><ulink url="http://www.ietf.org/rfc/rfc2254.txt" type="text_url">
RFC 2254</ulink>, <citetitle>The String Representation of LDAP Search Filters</citetitle></para>
</listitem>
<listitem><para><ulink url="http://www.ietf.org/rfc/rfc2255.txt" type="text_url">
RFC 2255</ulink>, <citetitle>The LDAP URL Format</citetitle></para></listitem>
<listitem><para><ulink url="http://www.ietf.org/rfc/rfc2256.txt" type="text_url">
RFC 2256</ulink>, <citetitle>A Summary of the X.500(96) User Schema for use
with LDAPv3</citetitle></para></listitem>
<listitem><para><ulink url="http://www.ietf.org/rfc/rfc2829.txt" type="text_url">
RFC 2829</ulink>, <citetitle>Authentication Methods for LDAP</citetitle></para>
</listitem>
<listitem><para><ulink url="http://www.ietf.org/rfc/rfc2830.txt" type="text_url">
RFC 2830</ulink>, <citetitle>Lightweight Directory Access Protocol (v3): Extension
for Transport Layer Security</citetitle></para></listitem>
<listitem><para><ulink url="http://www.ietf.org/rfc/rfc2849.txt" type="text_url">
RFC 2849</ulink>, <citetitle>The LDAP Data Interchange Format (LDIF) - Technical
Specification</citetitle></para></listitem>
<listitem><para><ulink url="http://www.ietf.org/rfc/rfc3377.txt" type="text_url">
RFC 3377</ulink>, <citetitle>Lightweight Directory Access Protocol (v3): Technical
Specification</citetitle></para></listitem>
</itemizedlist>
</sect1>
<sect1 id="organization"><title>How This Book Is Organized</title>
<itemizedlist>
<para>This guide includes the following chapters.</para>
<listitem><para><olink targetptr="understanding-ldap">Chapter&nbsp;1, Understanding LDAP</olink> describes LDAP and directory concepts.</para></listitem>
<listitem><para><olink targetptr="best-practices-choose">Chapter&nbsp;2, Choosing a Client SDK</olink> covers what to consider when choosing a software development kit for building directory client applications.</para></listitem>
<listitem><para><olink targetptr="best-practices-overview">Chapter&nbsp;3,
Best Practices for Writing Client Applications</olink> reviews what and what
not to do when building directory client applications.</para></listitem>
<listitem><para><olink targetptr="quickstart-jdk">Chapter&nbsp;1, Getting
Started With Directory SDK for Java</olink> gets you started using &DirectorySDKForJava;</para>
</listitem>
<listitem><para><olink targetptr="writing-client">Chapter&nbsp;2, Writing an LDAP Client With Directory SDK for Java</olink> covers the basics of writing
a directory client application</para></listitem>
<listitem><para><olink targetptr="common-classes">Chapter&nbsp;3, Using the LDAP Java Classes</olink> provides a look how &DirectorySDKForJava; is
structured</para></listitem>
<listitem><para><olink targetptr="searching">Chapter&nbsp;4, Searching the Directory With Directory SDK for Java</olink> shows you how to write client
application code for searching a directory</para></listitem>
<!--<listitem><para><olink targetptr="filter-conf"></olink> shows you
how to write client application code for searching
a directory using filter configuration files</para>
</listitem>-->
<listitem><para><olink targetptr="adding">Chapter&nbsp;5, Adding, Updating, and Deleting Entries With Directory SDK for Java</olink> shows you how to
write client application code for changing directory entries</para></listitem>
<listitem><para><olink targetptr="comparing">Chapter&nbsp;6, Comparing Attribute Values With Directory SDK for Java</olink> shows you how to comparing attribute
values in a directory with known values</para></listitem>
<listitem><para><olink targetptr="ldap-urls">Chapter&nbsp;7, LDAP URLs With Directory SDK for Java</olink> shows you how to handle LDAP URLs</para>
</listitem>
<listitem><para><olink targetptr="server-info">Chapter&nbsp;8, Getting Server Information With Directory SDK for Java</olink> shows you how to retrieve
information about the directory and directory service</para></listitem>
<listitem><para><olink targetptr="ssl">Chapter&nbsp;9, SSL Connections With Directory SDK for Java</olink> shows you how to write client application code
that connects to the directory over SSL</para></listitem>
<listitem><para><olink targetptr="controls">Chapter&nbsp;10, LDAP Controls With Directory SDK for Java</olink> shows you how to handle supported LDAP
controls</para></listitem>
<listitem><para><olink targetptr="sasl">Chapter&nbsp;11, SASL Authentication With Directory SDK for Java</olink> shows you how to connect to the directory
by using SASL</para></listitem>
<listitem><para><olink targetptr="extended-ops">Chapter&nbsp;12, Extended Operations With Directory SDK for Java</olink> shows you how to write client
application code for handling LDAP v3 extended operations</para></listitem>
<listitem><para><olink targetptr="asynchronous">Chapter&nbsp;13, Writing Asynchronous Clients With Directory SDK for Java</olink> shows you how to write applications
that do not block waiting for results</para></listitem>
<listitem><para><olink targetptr="share-alike">Appendix A, Creative Commons Attribution-ShareAlike 2.5</olink> provides the full text of the license governing this guide</para>
</listitem>
</itemizedlist>
</sect1>
<sect1 id="related-reading"><title>Related Reading</title>
<para><indexterm>
<primary>SLAMD Distributed Load Generation Engine</primary>
</indexterm>The SLAMD Distributed Load Generation Engine (SLAMD) is a <trademark>
Java</trademark> application that is designed to stress test and analyze the
performance of network-based applications. It was originally developed by
Sun Microsystems, Inc. to benchmark and analyze the performance of LDAP directory
servers. SLAMD is available as an open source application under the Sun Public
License, an OSI-approved open source license. To obtain information about
SLAMD, go to <ulink url="http://www.slamd.com/" type="url"></ulink>. SLAMD
is also available as a java.net project. See <ulink
url="https://slamd.dev.java.net/" type="url"></ulink>.</para>
<para><indexterm>
<primary>Java Naming and Directory Interface</primary>
</indexterm>Java Naming and Directory Interface (JNDI) technology supports
accessing the Directory Server using LDAP and DSML v2 from Java applications.
For information about JNDI, see <ulink url="http://java.sun.com/products/jndi/"
type="url"></ulink>. The <citetitle>JNDI Tutorial</citetitle> contains detailed
descriptions and examples of how to use JNDI. This tutorial is at <ulink
url="http://java.sun.com/products/jndi/tutorial/" type="url"></ulink>.</para>
</sect1>
<sect1 id="FWBKX"><title>Typographic Conventions</title>
<para>The following table describes the typographic changes that are used
in this book.</para>
<table frame="topbot" id="FWBTE"><title>Typographic Conventions</title>
<tgroup cols="3" colsep="0" rowsep="0"><colspec colwidth="15*"><colspec
colwidth="40*"><colspec colwidth="45*">
<thead>
<row rowsep="1">
<entry align="left">
<para>Typeface</para></entry>
<entry align="left">
<para>Meaning</para></entry>
<entry align="left">
<para>Example</para></entry>
</row>
</thead>
<tbody>
<row>
<entry>
<para><literal>AaBbCc123</literal></para></entry>
<entry>
<para>The names of commands, files, and directories, and onscreen computer
output</para></entry>
<entry>
<para>Edit your <filename>.login</filename> file.</para>
<para>Use <command>ls <option>a</option></command> to list all files.</para>
<para><computeroutput>machine_name% you have mail.</computeroutput></para>
</entry>
</row>
<row>
<entry>
<para><userinput>AaBbCc123</userinput></para></entry>
<entry>
<para>What you type, contrasted with onscreen computer output</para></entry>
<entry>
<para><computeroutput>machine_name%</computeroutput>  <userinput>su</userinput></para>
<para><computeroutput>Password:</computeroutput></para></entry>
</row>
<row>
<entry>
<para><replaceable>AaBbCc123</replaceable></para></entry>
<entry>
<para>A placeholder to be replaced with a real name or value</para></entry>
<entry>
<para>The command to remove a file is  <command>rm</command> <replaceable>filename
</replaceable>.</para></entry>
</row>
<row>
<entry>
<para><emphasis>AaBbCc123</emphasis></para></entry>
<entry>
<para>Book titles, new terms, and terms to be emphasized (note that some emphasized
items appear bold online)</para></entry>
<entry>
<para>Read Chapter 6 in the <citetitle>User's Guide</citetitle>.</para>
<para>A <emphasis>cache</emphasis> is a copy that is stored locally.</para>
<para>Do <emphasis>not</emphasis> save the file.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect1>
<sect1 id="FWBMK"><title>Shell Prompts in Command Examples</title>
<para>The following table shows default system prompts and superuser prompts.</para>
<table frame="topbot" id="GCTTT"><title>Shell Prompts</title>
<tgroup cols="2" colsep="0" rowsep="0"><colspec colwidth="75*"><colspec
colwidth="25*">
<thead>
<row rowsep="1">
<entry>
<para>Shell</para></entry>
<entry>
<para>Prompt</para></entry>
</row>
</thead>
<tbody>
<row>
<entry>
<para>C shell on UNIX and Linux systems</para></entry>
<entry>
<para><literal>machine_name%</literal></para></entry>
</row>
<row>
<entry>
<para>C shell superuser on UNIX and Linux systems</para></entry>
<entry>
<para><literal>machine_name#</literal></para></entry>
</row>
<row>
<entry>
<para>Bourne shell and Korn shell on UNIX and Linux systems</para></entry>
<entry>
<para><literal>$</literal></para></entry>
</row>
<row>
<entry>
<para>Bourne shell and Korn shell superuser on UNIX and Linux systems</para>
</entry>
<entry>
<para><literal>#</literal></para></entry>
</row>
<row>
<entry>
<para>Microsoft Windows command line</para></entry>
<entry>
<para><literal>C:\</literal></para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect1>
<sect1 id="FQUVC"><title>Symbol Conventions</title>
<para>The following table explains symbols that might be used in this book.</para>
<table frame="topbot" id="FQUVR"><title>Symbol Conventions</title>
<tgroup cols="4" colsep="0" rowsep="0"><colspec colnum="1" colwidth="8*"
align="center"><colspec colnum="2" colwidth="28*"><colspec colnum="3"
colwidth="28*"><colspec colnum="4" colwidth="36*">
<thead>
<row rowsep="1">
<entry>
<para>Symbol</para></entry>
<entry>
<para>Description</para></entry>
<entry>
<para>Example</para></entry>
<entry>
<para>Meaning</para></entry>
</row>
</thead>
<tbody>
<row>
<entry>
<para><literal>[ ]</literal></para></entry>
<entry>
<para>Contains optional arguments and command options.</para></entry>
<entry>
<para><literal>ls [-l]</literal></para></entry>
<entry>
<para>The <literal>-l</literal> option is not required.</para></entry>
</row>
<row>
<entry>
<para><literal>{ | }</literal></para></entry>
<entry>
<para>Contains a set of choices for a required command option.</para></entry>
<entry>
<para><literal>-d {y|n}</literal></para></entry>
<entry>
<para>The <literal>-d</literal> option requires that you use either the <literal>
y</literal> argument or the <literal>n</literal> argument.</para></entry>
</row>
<row>
<entry>
<para><literal>${ }</literal></para></entry>
<entry>
<para>Indicates a variable reference.</para></entry>
<entry>
<para><literal>${com.sun.javaRoot}</literal></para></entry>
<entry>
<para>References the value of the <literal>com.sun.javaRoot</literal> variable.</para>
</entry>
</row>
<row>
<entry>
<para>-</para></entry>
<entry>
<para>Joins simultaneous multiple keystrokes.</para></entry>
<entry>
<para>Control-A</para></entry>
<entry>
<para>Press the Control key while you press the A key.</para></entry>
</row>
<row>
<entry>
<para>+</para></entry>
<entry>
<para>Joins consecutive multiple keystrokes.</para></entry>
<entry>
<para>Ctrl+A+N</para></entry>
<entry>
<para>Press the Control key, release it, and then press the subsequent keys.</para>
</entry>
</row>
<row>
<entry>
<para>&rarr;</para></entry>
<entry>
<para>Indicates menu item selection in a graphical user interface.</para>
</entry>
<entry>
<para>File &rarr; New &rarr; Templates</para></entry>
<entry>
<para>From the File menu, choose New. From the New submenu, choose Templates.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect1>
</preface>
