<!--

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="understanding-jdk"><title>Understanding the &DirectorySDKForJava;</title>
<highlights>
<para>This chapter describes the LDAP Java classes and the &DirectorySDKForJava;,
including the following sections:</para>
<itemizedlist>
<listitem><para><olink targetptr="understanding-java-classes">Understanding the LDAP
Java Classes</olink></para></listitem>
<listitem><para><olink targetptr="getting-started">About &DirectorySDKForJava;</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>The &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 and perform standard LDAP operations. For example, you can
search for entries or 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 EXTERNAL 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 on 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.
These 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 the &DirectorySDKForJava; synchronously.
All LDAP operations block until they 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 requiring low-level
interaction with an LDAP server. The asynchronous interface is discussed more fully
in <olink targetptr="asynchronous">Chapter&nbsp;33, Writing Asynchronous Clients With Directory SDK for Java</olink>.</para></sect1>
<sect1 id="getting-started"><title>About &DirectorySDKForJava;</title>
<para>This section covers the following topics:</para>
<itemizedlist>
<!--<listitem><para><olink targetptr="install-jdk">Getting
and Installing the Directory SDK for Java</olink></para>
</listitem>-->
<listitem><para><olink targetptr="explore-jdk">Exploring the Directory SDK for Java
</olink></para></listitem>
<listitem><para><olink targetptr="prepare-jdk">Preparing to Use Directory SDK for
Java</olink></para></listitem>
<!--<listitem><para><olink targetptr="applets-jdk"></olink></para>
</listitem><listitem><para><olink targetptr="version-jdk"></olink></para>
</listitem><listitem><para><olink targetptr="javabeans-jdk"></olink></para>
</listitem><listitem><para><olink targetptr="javascript-jdk"></olink></para>
</listitem>-->
</itemizedlist>
<!--<sect2 id="install-jdk"><title>Getting and Installing
the &DirectorySDKForJava;</title>
<indexterm>
<primary>&DirectorySDKForJava;</primary>
<secondary>installing</secondary>
</indexterm>
<para>TODO</para></sect2>-->
<sect2 id="explore-jdk"><title>Exploring the &DirectorySDKForJava;</title>
<indexterm>
<primary>&DirectorySDKForJava;</primary>
<secondary>contents</secondary>
</indexterm>
<para>TODO: verify this is all still true</para>
<para>The &DirectorySDKForJava; contains the following directories:</para>
<variablelist>
<!--<varlistentry><term><filename class="directory">beans
</filename></term>
<listitem><para>This directory contains the LDAP JavaBeans
class files from the <literal>netscape.ldap.beans
</literal> package.</para>
<para>If you are writing applications or applets that
use these classes, make sure to provide these classes
to your users.</para>
<para>This directory also contains a script to create
JAR files for the LDAP JavaBeans classes.</para>
</listitem>
</varlistentry><varlistentry><term><filename class="directory">
examples</filename></term>
<listitem><para>This directory contains sample source
code for LDAP Java applications. The examples are
organized in different subdirectories:</para>
<variablelist>
<varlistentry><term><filename class="directory">java
</filename></term>
<listitem><para>Contains examples of the standard
LDAP operations, such as adding an entry and searching
for entries. This directory also contains examples
using LDAP controls.</para>
</listitem>
</varlistentry>
<varlistentry><term><filename class="directory">java/beans
</filename></term>
<listitem><para>Contains examples uses of the LDAP
JavaBeans classes.</para>
</listitem>
</varlistentry>
<varlistentry><term><filename class="directory">java/ldapfilt
</filename></term>
<listitem><para>Contains an example uses of an LDAP
filter configuration file with the LDAP filter classes.
</para>
</listitem>
</varlistentry>
<varlistentry><term><filename class="directory">js
</filename></term>
<listitem><para>Contains an example of using LiveConnect
to create and manipulate LDAP Java objects from JavaScript.
LiveConnect enables communication in a single page
between a variety of elements such as JavaScript code,
HTML, browser plug-ins, and Java applets.</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>-->
<varlistentry><term><filename class="directory">packages</filename></term>
<listitem><para>This directory contains the following JAR file<!--s-->:</para>
<variablelist>
<varlistentry><indexterm>
<primary>ldapjdk.jar</primary>
</indexterm><term><filename>ldapjdk.jar</filename></term>
<listitem><para>Contains classes for all packages listed in <olink targetptr="understanding-java-classes">
Understanding the LDAP Java Classes</olink><!--, but does not contain the filter classes-->
</para>
</listitem>
</varlistentry>
<!--<varlistentry><indexterm>
<primary>ldapfilt.jar</primary>
</indexterm><term><filename>ldapfilt.jar</filename></term>
<listitem><para>Contains the filter classes in the <literal>
netscape.ldap.util</literal> package, and the underlying
regular expression classes needed by the filter classes
</para>
</listitem>
</varlistentry>-->
</variablelist>
</listitem>
</varlistentry>
<varlistentry><term><filename class="directory">tools</filename></term>
<listitem><para>This directory contains Java classes for the <command>LDAPDelete</command>, <command>
LDAPModify</command>, and <command>LDAPSearch</command> commands.</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2 id="prepare-jdk"><title>Preparing to Use &DirectorySDKForJava;</title>
<indexterm>
<primary><envar>CLASSPATH</envar></primary>
<secondary>setting</secondary>
</indexterm>
<para>TODO: is this right?</para>
<para>Before compiling applications, add the following to your <envar>CLASSPATH</envar> environment
variable:</para>
<variablelist>
<!--<varlistentry><term><filename>beans/*.jar</filename></term>
<listitem><para>Containing the LDAP JavaBeans classes
</para>
</listitem>
</varlistentry>-->
<varlistentry><term><filename>packages/ldapjdk.jar</filename></term>
<listitem><para>Containing the main LDAP Java classes</para>
</listitem>
</varlistentry>
<!--<varlistentry><term><filename>packages/ldapfilt.jar
</filename></term>
<listitem><para>Containing the LDAP classes for handling
search filters</para>
</listitem>
</varlistentry>-->
</variablelist>
</sect2>
<!--<sect2 id="applets-jdk"><title>Writing Applets with
the &DirectorySDKForJava;</title>
<indexterm>
<primary>applets</primary>
<secondary>security framework and</secondary>
</indexterm><indexterm>
<primary>&DirectorySDKForJava;</primary>
<secondary>writing applets for</secondary>
</indexterm><indexterm>
<primary>LDAP clients</primary>
<secondary>writing applets</secondary>
</indexterm>
<para>TODO: Get this up to date. None of it seems
to work.</para>
<para>In <trademark>Netscape</trademark> Communicator,
an applet can connect to servers on hosts other than
the host that served the applet. This capability is
part of the new signed applet security framework.
 To take advantage of this capability, your applet
class, the class making an LDAP connection, must be
signed. Your applet class needs to request certain
special rights before connecting to other servers.
</para>
<para>The steps to enable your applet to connect to
other LDAP servers are as follows:</para>
<orderedlist>
<listitem><para>Get a certificate from your organization's
certificate authority or from a third-party certificate
authority, such as RSA, Verisign, or ATT.</para><para>
Users should have the certificate from the certificate
authority in the Communicator certificate database.
</para></listitem>
<listitem><para>Create a JAR file with your classes
and have them signed.</para></listitem>
<listitem><para>Add the following line to your applet
code in the thread where you invoke <literal>LDAPConnection.connect
</literal>:</para>
<programlisting>PrivilegeManager.enablePrivilege("UniversalConnect");
</programlisting>
<para>At this point in the code, the user of your
applet will be prompted with a dialog box identifying
the author of the signed class and asking permission
to grant the right to access the LDAP server. The
user can either allow access for this time only or
forever.</para></listitem></orderedlist>
<para>TODO: fix this.</para>
<para>If you want to test the ability for your applet
to connect to hosts other than the originating one
without using object signing and certificates, in
case you want to test your applet while waiting for
your certificate to be issued for example, you can
configure Netscape Communicator to bypass this check.
</para>
<orderedlist>
<listitem><para>Exit Communicator or make sure that
it is not running.</para></listitem>
<listitem><para>Add the following line to the <filename>
prefs.js</filename> file: </para>
<programlisting>user_pref("signed.applets.codebase_principal_support", true);
</programlisting>
</listitem></orderedlist>
</sect2><sect2 id="version-jdk"><title>Checking the
Version of Classes from an Applet</title>
<indexterm>
<primary>applets</primary>
<secondary>checking version of LDAP classes</secondary>
</indexterm>
<para>To get the version number, invoke the <literal>
LDAPConnection.getProperty</literal> method and pass
in the constant <literal>LDAPConnection.LDAP_PROPERTY_SDK
</literal>. The version number is a <classname>Float
</classname> type. For example:</para>
<programlisting>Float sdkVersion = (Float)myConn.getProperty(myConn.LDAP_PROPERTY_SDK);
System.out.println("LDAP Java Classes version: " + sdkVersion);
</programlisting>
</sect2><sect2 id="javabeans-jdk"><title>Working with
LDAP JavaBeans Classes</title>
<indexterm>
<primary>JavaBeans classes</primary>
</indexterm><indexterm>
<primary>LDAP JavaBeans classes</primary>
</indexterm><indexterm>
<primary>&DirectorySDKForJava;</primary>
<secondary>LDAP JavaBeans classes</secondary>
</indexterm>
<para>The JavaBeans classes are part of the <literal>
netscape.ldap.beans</literal> package. Class files
are located in the <filename class="directory">beans
</filename> directory. The following JavaBeans classes
are included with the &DirectorySDKForJava;:</para>
<variablelist>
<varlistentry><term><classname>DisplayString</classname></term>
<listitem><para>Extends <classname>java.awt.TextArea
</classname> to help you display results from some
of the JavaBeans classes.</para>
</listitem>
</varlistentry>
<varlistentry><term><classname>LDAPBasePropertySupport
</classname></term>
<listitem><para>Exists as a base class specifying
accessor methods inherited by the other LDAP JavaBeans
classes.</para>
</listitem>
</varlistentry>
<varlistentry><term><classname>LDAPGetEntries</classname></term>
<listitem><para>Allows you to search the directory
and get an array of the DNs found by the search.</para>
<para>You can use the properties of this class to
specify the search criteria. The <literal>getEntries
</literal> method performs the search and sets the <property>
Result</property> property to the array of DNs found.
</para>
</listitem>
</varlistentry>
<varlistentry><term><classname>LDAPGetProperty</classname></term>
<listitem><para>Allows you to find an entry in the
directory and get the values of a specified attribute
in that entry.</para>
<para>You can use the properties of this class to
specify the search criteria. The <literal>getProperty
</literal> method performs the search and sets the <property>
Result</property> property to the array of the string
values of the specified attribute.</para>
</listitem>
</varlistentry>
<varlistentry><term><classname>LDAPIsMember</classname></term>
<listitem><para>Determines whether a user belongs
to a group.</para>
<para>Both the user and group can be specified as
properties of the class. The <literal>isMember</literal> method
sets the <property>Result</property> property to the
string <literal>Y</literal>or <literal>N</literal> to
indicate whether the user is a member.</para>
</listitem>
</varlistentry>
<varlistentry><term><classname>LDAPSimpleAuth</classname></term>
<listitem><para>Authenticates to an LDAP server.</para>
<para>After attempting to authenticate, the <literal>
authenticate</literal> method sets the <property>
Result</property> property to the string <literal>
Y</literal>or <literal>N</literal> to indicate whether
the authentication was successful.</para>
</listitem>
</varlistentry>
</variablelist>
<para>TODO: explain how to set this up with Java Studio
or Java Studio Creator</para>
<para>The LDAP JavaBeans classes have a <property>
Debug</property> property you can set to have debugging
information displayed. This information is printed
to standard output. TODO: what happens when you use
Java Studio or Creator?</para></sect2><sect2 id="javascript-jdk">
<title>Using the Classes from <trademark>JavaScript
</trademark> Code</title>
<indexterm>
<primary>JavaScript</primary>
</indexterm><indexterm>
<primary>LiveConnect</primary>
</indexterm><indexterm>
<primary>LDAP Java classes</primary>
<secondary>JavaScript and</secondary>
</indexterm><indexterm>
<primary>LDAP Java classes</primary>
<secondary>LiveConnect and</secondary>
</indexterm>
<para>TODO: Update all this. The code doesn't appear
to work with Mozilla.</para>
<para>Using Netscape Communicator's LiveConnect capabilities,
you can use the LDAP Java classes from within JavaScript
code in an HTML page. LiveConnect enables communication
between JavaScript and Java applets in a page and
between JavaScript and plug-ins loaded on a page.
</para>
<para>To see an example of how you can do this, see
the sample JavaScript code in the HTML file in the <filename
class="directory">examples/js</filename> directory.
</para></sect2>-->
</sect1>
</chapter>
