413 lines
16 KiB
Plaintext
413 lines
16 KiB
Plaintext
<!--
|
|
|
|
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 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>
|