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
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!--
Copyright (c) 1999, 2006, Oracle and/or its affiliates. All rights reserved.
DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
This code is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License version 2 only, as
published by the Free Software Foundation. Oracle designates this
particular file as subject to the "Classpath" exception as provided
by Oracle in the LICENSE file that accompanied this code.
This code is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
version 2 for more details (a copy is included in the LICENSE file that
accompanied this code).
You should have received a copy of the GNU General Public License version
2 along with this work; if not, write to the Free Software Foundation,
Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
CA 95054 USA or visit www.sun.com if you need additional information or
have any questions.
-->
</head>
<body bgcolor="white">
Provides support for LDAPv3 extended operations and controls.
<p>
This package extends the directory operations of the Java Naming and
Directory Interface<font size=-2><sup>TM</sup></font> (JNDI).
JNDI provides naming and directory functionality to applications
written in the Java programming language. It is designed to be
independent of any specific naming or directory service
implementation. Thus a variety of services--new, emerging, and
already deployed ones--can be accessed in a common way.
<p>
This package is for applications and service providers that deal with
LDAPv3 extended operations and controls, as defined by
<a href=http://www.ietf.org/rfc/rfc2251.txt>RFC 2251</a>.
The core interface in this package is <tt>LdapContext</tt>, which defines
methods on a context for performing extended operations and handling
controls.
<h4>Extended Operations</h4>
<p>
This package defines the interface <tt>ExtendedRequest</tt>
to represent the argument to an extended operation,
and the interface <tt>ExtendedResponse</tt> to represent the result
of the extended operation.
An extended response is always paired with an extended request
but not necessarily vice versa. That is, you can have an extended request
that has no corresponding extended response.
<p>
An application typically does not deal directly with these interfaces.
Instead, it deals with classes that <em>implement</em> these
interfaces.
The application gets these classes either as part of a
repertoire of extended operations standardized through the IETF, or
from directory vendors for vendor-specific extended operations.
The request classes should have constructors that accept
arguments in a type-safe and user-friendly manner, while the
response classes should have access methods for getting the data
of the response in a type-safe and user-friendly manner.
Internally, the request/response classes deal with encoding and decoding
BER values.
<p>
For example, suppose an LDAP server supports a "get time" extended operation.
It would supply classes such as
<tt>GetTimeRequest</tt> and <tt>GetTimeResponse</tt>,
so that applications can use this feature.
An application would use these classes as follows:
<blockquote><pre>
GetTimeResponse resp =
(GetTimeResponse) ectx.extendedOperation(new GetTimeRequest());
long time = resp.getTime();
</pre></blockquote>
<p>
The <tt>GetTimeRequest</tt> and <tt>GetTimeResponse</tt> classes might
be defined as follows:
<blockquote><pre>
public class GetTimeRequest implements ExtendedRequest {
// User-friendly constructor
public GetTimeRequest() {
};
// Methods used by service providers
public String getID() {
return GETTIME_REQ_OID;
}
public byte[] getEncodedValue() {
return null; // no value needed for get time request
}
public ExtendedResponse createExtendedResponse(
String id, byte[] berValue, int offset, int length) throws NamingException {
return new GetTimeResponse(id, berValue, offset, length);
}
}
public class GetTimeResponse() implements ExtendedResponse {
long time;
// called by GetTimeRequest.createExtendedResponse()
public GetTimeResponse(String id, byte[] berValue, int offset, int length)
throws NamingException {
// check validity of id
long time = ... // decode berValue to get time
}
// Type-safe and User-friendly methods
public java.util.Date getDate() { return new java.util.Date(time); }
public long getTime() { return time; }
// Low level methods
public byte[] getEncodedValue() {
return // berValue saved;
}
public String getID() {
return GETTIME_RESP_OID;
}
}
</pre></blockquote>
<h4>Controls</h4>
This package defines the interface <tt>Control</tt> to represent an LDAPv3
control. It can be a control that is sent to an LDAP server
(<em>request control</em>) or a control returned by an LDAP server
(<em>response control</em>). Unlike extended requests and responses,
there is not necessarily any pairing between request controls and
response controls. You can send request controls and expect no
response controls back, or receive response controls without sending
any request controls.
<p>
An application typically does not deal directly with this interface.
Instead, it deals with classes that <em>implement</em> this interface.
The application gets control classes either as part of a repertoire of
controls standardized through the IETF, or from directory vendors for
vendor-specific controls. The request control classes should have
constructors that accept arguments in a type-safe and user-friendly
manner, while the response control classes should have access methods
for getting the data of the response in a type-safe and user-friendly
manner. Internally, the request/response control classes deal with
encoding and decoding BER values.
<p>
For example, suppose an LDAP server supports a "signed results"
request control, which when sent with a request, asks the
server to digitally sign the results of an operation.
It would supply a class <tt>SignedResultsControl</tt> so that applications
can use this feature.
An application would use this class as follows:
<blockquote>
<pre>
Control[] reqCtls = new Control[] {new SignedResultsControl(Control.CRITICAL)};
ectx.setRequestControls(reqCtls);
NamingEnumeration enum = ectx.search(...);
</pre>
</blockquote>
The <tt>SignedResultsControl</tt> class might be defined as follows:
<blockquote><pre>
public class SignedResultsControl implements Control {
// User-friendly constructor
public SignedResultsControl(boolean criticality) {
// assemble the components of the request control
};
// Methods used by service providers
public String getID() {
return // control's object identifier
}
public byte[] getEncodedValue() {
return // ASN.1 BER encoded control value
}
...
}
</pre></blockquote>
<p>
When a service provider receives response controls, it uses
the <tt>ControlFactory</tt> class to produce specific classes
that implement the <tt>Control</tt> interface.
<p>
An LDAP server can send back response controls with an LDAP operation
and also with enumeration results, such as those returned
by a list or search operation.
The <tt>LdapContext</tt> provides a method (<tt>getResponseControls()</tt>)
for getting the response controls sent with an LDAP operation,
while the <tt>HasControls</tt> interface is used to retrieve
response controls associated with enumeration results.
<p>
For example, suppose an LDAP server sends back a "change ID" control in response
to a successful modification. It would supply a class <tt>ChangeIDControl</tt>
so that the application can use this feature.
An application would perform an update, and then try to get the change ID.
<blockquote><pre>
// Perform update
Context ctx = ectx.createSubsubcontext("cn=newobj");
// Get response controls
Control[] respCtls = ectx.getResponseControls();
if (respCtls != null) {
// Find the one we want
for (int i = 0; i < respCtls; i++) {
if(respCtls[i] instanceof ChangeIDControl) {
ChangeIDControl cctl = (ChangeIDControl)respCtls[i];
System.out.println(cctl.getChangeID());
}
}
}
</pre></blockquote>
The vendor might supply the following <tt>ChangeIDControl</tt> and
<tt>VendorXControlFactory</tt> classes. The <tt>VendorXControlFactory</tt>
will be used by the service provider when the provider receives response
controls from the LDAP server.
<blockquote><pre>
public class ChangeIDControl implements Control {
long id;
// Constructor used by ControlFactory
public ChangeIDControl(String OID, byte[] berVal) throws NamingException {
// check validity of OID
id = // extract change ID from berVal
};
// Type-safe and User-friendly method
public long getChangeID() {
return id;
}
// Low-level methods
public String getID() {
return CHANGEID_OID;
}
public byte[] getEncodedValue() {
return // original berVal
}
...
}
public class VendorXControlFactory extends ControlFactory {
public VendorXControlFactory () {
}
public Control getControlInstance(Control orig) throws NamingException {
if (isOneOfMyControls(orig.getID())) {
...
// determine which of ours it is and call its constructor
return (new ChangeIDControl(orig.getID(), orig.getEncodedValue()));
}
return null; // not one of ours
}
}
</pre></blockquote>
<p>
<h2>Package Specification</h2>
The JNDI API Specification and related documents can be found in the
<a href="../../../../technotes/guides/jndi/index.html">JNDI documentation</a>.
@since 1.3
</body>
</html>
|
