-
Notifications
You must be signed in to change notification settings - Fork 5
/
Copy pathoverview.html
239 lines (231 loc) · 11.6 KB
/
overview.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
<!--
Copyright (c) 2002, OpenLDAP Foundation, All Rights Reserved.
Author: Kurt Zeilenga ([email protected])
Modified: 2002-01-10 17:02:49.
Generated from ``overview.wml'' via WML 2.0.6 (25-Oct-2000).
by Kurt Zeilenga ([email protected])
on 2002-01-10 17:04:14.
DO NOT EDIT THIS FILE DIRECTLY! INSTEAD EDIT ``overview.wml''.
-->
<!--
name: Java LDAP Overview
id:
$OpenLDAP$
site: OpenLDAP
area: jldap
subarea: overview
page: main (logo) (on)
select: main
-->
<HTML>
<HEAD>
<TITLE>OpenLDAP, Java LDAP Overview</TITLE>
<META NAME="Copyright" CONTENT="Copyright 2002, OpenLDAP Foundation, All Rights Reserved.">
<META NAME="Author" CONTENT="Kurt Zeilenga, [email protected]" >
<META NAME="Generator" CONTENT="WML 2.0.6 (25-Oct-2000)" >
<META NAME="Modified" CONTENT="2002-01-10 17:02:49" >
<SCRIPT TYPE="text/javascript" LANGUAGE="JavaScript">
<!-- Hiding the code
// don't frame me
if(window.location != window.parent.location) {
window.parent.location = window.location;
}
// done hiding -->
</SCRIPT>
<META NAME="swish-keywords" CONTENT="Java, JLDAP, overview">
<META NAME="keywords" CONTENT="OpenLDAP, Open, LDAP, X.500, Directory, Open Source, OpenSource, Source, Java, JLDAP, overview">
<META NAME="description" CONTENT="This documents an overview of JLDAP">
</HEAD>
<BODY BGCOLOR="#ffffff" TEXT="#000000" LINK="#0000ff" ALINK="#ff0000" VLINK="#800080">
<H1>
<A ALT="OpenLDAP" HREF="/"><IMG BORDER="0"
SRC="/images/headers/LDAPlogo.gif" ALT=""></A>
Java LDAP Overview</H1>
<FONT FACE="Arial,Verdana,Helvetica">
<!-- BEGIN OF ACTUAL PAGE CONTENTS -->
<!--
******************************************************************************
* Copyright (C) 1999, 2000, 2001 Novell, Inc. All Rights Reserved.
*
* THIS WORK IS SUBJECT TO U.S. AND INTERNATIONAL COPYRIGHT LAWS AND
* TREATIES. USE, MODIFICATION, AND REDISTRIBUTION OF THIS WORK IS SUBJECT
* TO VERSION 2.0.1 OF THE OPENLDAP PUBLIC LICENSE, A COPY OF WHICH IS
* AVAILABLE AT HTTP://WWW.OPENLDAP.ORG/LICENSE.HTML OR IN THE FILE "LICENSE"
* IN THE TOP-LEVEL DIRECTORY OF THE DISTRIBUTION. ANY USE OR EXPLOITATION
* OF THIS WORK OTHER THAN AS AUTHORIZED IN VERSION 2.0.1 OF THE OPENLDAP
* PUBLIC LICENSE, OR OTHER PRIOR WRITTEN CONSENT FROM NOVELL, COULD SUBJECT
* THE PERPETRATOR TO CRIMINAL AND CIVIL LIABILITY.
******************************************************************************
-->
The LDAP Class Libraries for Java (JLDAP) allow you to write applications to
access, manage, update, and search for information stored in directories
accessible using LDAPv3.
<H3>README</H3>
See the <TT>README</TT> for information about dependencies,
installation notes, and SSL integration.
<UL>
<LI><A HREF="README">README</A>
</UL>
<H3><A NAME="sc">Sample code</A></H3>
The LDAP Class Libraries for Java contain a number of samples
demonstrating common operations. These samples are available on
the <A HREF="http://developer.novell.com/ndk/">Novell Developer
Kit</A>.
<UL>
<LI><A HREF="http://developer.novell.com/ndk/doc/samplecode/jldap_sample/index.htm">Java LDAP Sample Code</A>
</UL>
<H3>Introduction</H3>
JLDAP is designed to provide powerful, yet simple, access to LDAP
directory services. This API defines both asynchronous and synchronous
interfaces to LDAP to suit a wide variety of applications. This
document gives a brief overview of the LDAP model, then an overview
of the constituents of the class library.
<H3>Overview of the LDAP model</H3>
LDAP is the lightweight directory access protocol, described in
RFC 2251-2256,2829-2830. It defines a lightweight access mechanism
in which clients send requests to and receive responses from LDAP
servers.
<P>The LDAP information model comes from X.500 and is based on the
entry, which contains information about some object (e.g., a person).
Entries are composed of attributes, which have a type and one or more
values. Each attribute has a syntax that determines what kinds of
values are allowed in the attribute (e.g., ASCII characters, a jpeg
photograph, etc.) and how those values behave during directory
operations (e.g., is case significant during comparisons).
<P>Entries may be organized in a tree structure, usually based on
political, geographical, and organizational boundaries. Other
structures are possible, including a flat namespace. Each entry is
uniquely named relative to its sibling entries by its relative
distinguished name (RDN) consisting of one or more distinguished
attribute values from the entry. At most one value from each
attribute may be used in the RDN. For example, the entry for the
person Babs Jensen might be named with the "Barbara Jensen" value
from the CN (commonName) attribute.
<P>A globally unique name for an entry, called a distinguished name
or DN, is constructed by concatenating the sequence of RDNs from
the entry up to the root of the tree. For example, if Babs worked
for the University of Michigan, the DN of her U-M entry might be
"cn=Barbara Jensen,o=University of Michigan,c=US". The DN format
used by LDAP is defined in RFC2253.
<P>Operations are provided to authenticate, search for and retrieve
information, modify information, and add and delete entries from the
tree.
<P>An LDAP server may return referrals if it cannot completely
service a request (for example if the request specifies a directory
base outside of the tree managed by the server). JLDAP offers the
programmer three options: the programmer can catch these referrals
as exceptions and explicitly issue new requests to the referred-to
servers, the programmer can provide an object to establish a new
connection to a referred-to server, or the programmer can let the
library automatically follow the referrals. In the latter case,
the programmer may also provide a reauthentication object, allowing
automatic referrals to proceed with appropriate credentials. If no
such object is provided, referrals are followed with anonymous
credentials, and the protocol level of the original connection is
used. If the original connection used a socket factory or TLS, the
referral connection will use the same.
<P>Before the client encodes and sends a string value to a server, the
string values are converted from the Java 16-bit Unicode format to
UTF-8 format, which is the standard string encoding for LDAPv3
servers. The integrity of double-byte and other non-ASCII character
sets is fully preserved.
<H3>Overview of JLDAP</H3>
The central LDAP class is LDAPConnection. It provides methods to
establish an authenticated or anonymous connection to an LDAP server,
as well as methods to search for, modify, compare, and delete entries
in the directory.
<P>The LDAPConnection class also provides fields for storing settings
that are specific to the LDAP session (such as limits on the number
of results returned or timeout limits). An LDAPConnection object can
be cloned, allowing objects to share a single network connection but
use different settings (using LDAPConstraints or
LDAPSearchConstraints).
<P>A synchronous search conducted by an LDAPConnection object returns
results in an LDAPSearchResults object, which can be enumerated to
access the entries found. Each entry (represented by an LDAPEntry
object) provides access to the attributes (represented by
LDAPAttribute objects) returned for that entry. Each attribute can
produce the values found as byte arrays or as Strings.
<H3>The LDAP asynchronous methods</H3>
The LDAP protocol provides synchronous as well as asynchronous
directory access methods. All asynchronous methods return listener
objects (either LDAPResponseListener or LDAPSearchListener) and also
take a listener object as input. The listener is a message queue
associated with the request, and it is the responsibility of the
client to read messages out of the queue and process them.
<P>Messages retrieved from an LDAPResponseListener are result objects
derived from LDAPResponse. Messages retrieved from an
LDAPSearchListener are either result objects derived from
LDAPResponse, search results, or search result references.
<P>An asynchronous search conducted by an LDAPConnection object returns
results via the getResponse method of the LDAPSearchListener returned
by the search operation. The getResponse method typically returns an
LDAPSearchResult object which has a getEntry method that returns the
LDAPEntry that represents the search entry.
<P>None of the ancillary asynchronous classes are intended to be
instantiated by a client, so they lack public constructors.
<H3>Overview of LDAP API Use</H3>
An application generally uses the LDAP API in four steps.
<UL>
<LI>Construct an LDAPConnection. Initialize an LDAP session with a
directory server. The LDAPConnection.connect() call establishes
a handle to the session, allowing multiple sessions to be open
at once, on different instances of LDAPConnection.
<LI>Authenticate to the LDAP server with LDAPConnection.bind().
<LI>Perform some LDAP operations and obtain some results. The
synchronous version of LDAPConnection.search() returns an
LDAPSearchResults which can be enumerated to access all entries
found. The asynchronous version of LDAPConnection.search() returns
an LDAPSearchListener, which is used to read the results of the
search. LDAPConnection.read() returns a single entry.
<LI>Close the connection. The LDAPConnection.disconnect() call
closes the connection.
</UL>
<P>There are both synchronous and asynchronous versions of the LDAP
protocol operations in this API. Synchronous methods do not return
until the operation has completed.
<P>Asynchronous methods take a listener parameter (either
LDAPResponseListener or LDAPSearchListener) and return a listener
object which is used to enumerate the responses from the server.
A loop is typically used to read from the listener object, which
blocks until there is a response available, until the operation
has completed.
<P>An LDAPResponseListener may be shared between operations, for
multiplexing the results. In this case, the object returned on one
operation is passed in to one or more other operations, rather than
passing in null.
<P>For the asynchronous methods, exceptions are raised only for
connection errors. LDAP result messages are converted into LDAPResponse
objects which are to be checked by the client for errors and
referrals, whereas the synchronous methods throw an LDAPException
on result codes other than 0.
<P>To facilitate user feedback during synchronous searches,
intermediate search results can be obtained before the entire search
operation is completed by specifying the number of entries to return
at a time. Standard Java Enumerations are used to parse synchronous
search results.
<P>Errors result in the throwing of an LDAPException, with a specific
error code and context-specific textual information available.
<P>If null is passed as the value of an LDAPConstraints or
LDAPSearchConstraints parameter to an operation, the default
constraints are used for that operation.
<P>If null is passed as the value of a DN to an operation it is
treated as if it was the empty string.
<P>The API doesn't distinguish between LDAP search continuation
references and LDAP referrals, presenting a unified interface to
the client for handling the two.
<P>Implementations of the API MUST ensure that the LDAPConnection
class is thread-safe. Other classes and methods MAY be thread-safe
and the implementor MUST indicate which classes and methods are
thread-safe.
<!-- END OF ACTUAL PAGE CONTENTS -->
</FONT>
<P>
<FONT COLOR="#808080" FACE="Arial,Verdana,Helvetica" SIZE="1"><B>
________________<BR>
<SMALL>© Copyright 2002, <A HREF="http://www.OpenLDAP.org/foundation/">OpenLDAP Foundation</A>, <A HREF="mailto:[email protected]">[email protected]</A></SMALL>
<BR>
$OpenLDAP$
</B></FONT>
</BODY>
</HTML>