213 lines
9.8 KiB
Plaintext
213 lines
9.8 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="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 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 < 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>
|