1 /*
2 * Copyright (c) 1999, 2000, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package javax.naming.ldap;
27
28 import javax.naming.NamingException;
29 import javax.naming.directory.DirContext;
30 import java.util.Hashtable;
31
32 /**
33 * This interface represents a context in which you can perform
34 * operations with LDAPv3-style controls and perform LDAPv3-style
35 * extended operations.
36 *
37 * For applications that do not require such controls or extended
38 * operations, the more generic <tt>javax.naming.directory.DirContext</tt>
39 * should be used instead.
40 *
41 * <h3>Usage Details About Controls</h3>
42 *
43 * This interface provides support for LDAP v3 controls.
44 * At a high level, this support allows a user
45 * program to set request controls for LDAP operations that are executed
46 * in the course of the user program's invocation of
47 * <tt>Context</tt>/<tt>DirContext</tt>
48 * methods, and read response controls resulting from LDAP operations.
49 * At the implementation level, there are some details that developers of
50 * both the user program and service providers need to understand in order
51 * to correctly use request and response controls.
52 *
53 * <h3>Request Controls</h3>
54 * <p>
55 * There are two types of request controls:
56 * <ul>
57 * <li>Request controls that affect how a connection is created
58 * <li>Request controls that affect context methods
59 * </ul>
60 *
61 * The former is used whenever a connection needs to be established or
62 * re-established with an LDAP server. The latter is used when all other
63 * LDAP operations are sent to the LDAP server. The reason why a
64 * distinction between these two types of request controls is necessary
65 * is because JNDI is a high-level API that does not deal directly with
66 * connections. It is the job of service providers to do any necessary
67 * connection management. Consequently, a single
68 * connection may be shared by multiple context instances, and a service provider
69 * is free to use its own algorithms to conserve connection and network
70 * usage. Thus, when a method is invoked on the context instance, the service
71 * provider might need to do some connection management in addition to
72 * performing the corresponding LDAP operations. For connection management,
73 * it uses the <em>connection request controls</em>, while for the normal
74 * LDAP operations, it uses the <em>context request controls</em>.
75 *<p>Unless explicitly qualified, the term "request controls" refers to
76 * context request controls.
77 *
78 * <h4>Context Request Controls</h4>
79 * There are two ways in which a context instance gets its request controls:
80 * <ol>
81 * <tt>
82 * <li>ldapContext.newInstance(<strong>reqCtls</strong>)
83 * <li>ldapContext.setRequestControls(<strong>reqCtls</strong>)
84 * </tt>
85 * </ol>
86 * where <tt>ldapContext</tt> is an instance of <tt>LdapContext</tt>.
87 * Specifying <tt>null</tt> or an empty array for <tt>reqCtls</tt>
88 * means no request controls.
89 * <tt>newInstance()</tt> creates a new instance of a context using
90 * <tt>reqCtls</tt>, while <tt>setRequestControls()</tt>
91 * updates an existing context instance's request controls to <tt>reqCtls</tt>.
92 * <p>
93 * Unlike environment properties, request controls of a context instance
94 * <em>are not inherited</em> by context instances that are derived from
95 * it. Derived context instances have <tt>null</tt> as their context
96 * request controls. You must set the request controls of a derived context
97 * instance explicitly using <tt>setRequestControls()</tt>.
98 * <p>
99 * A context instance's request controls are retrieved using
100 * the method <tt>getRequestControls()</tt>.
101 *
102 * <h4>Connection Request Controls</h4>
103 * There are three ways in which connection request controls are set:
104 * <ol>
105 * <tt>
106 * <li>
107 * new InitialLdapContext(env, <strong>connCtls</strong>)
108 * <li>refException.getReferralContext(env, <strong>connCtls</strong>)
109 * <li>ldapContext.reconnect(<strong>connCtls</strong>);
110 * </tt>
111 * </ol>
112 * where <tt>refException</tt> is an instance of
113 * <tt>LdapReferralException</tt>, and <tt>ldapContext</tt> is an
114 * instance of <tt>LdapContext</tt>.
115 * Specifying <tt>null</tt> or an empty array for <tt>connCtls</tt>
116 * means no connection request controls.
117 * <p>
118 * Like environment properties, connection request controls of a context
119 * <em>are inherited</em> by contexts that are derived from it.
120 * Typically, you initialize the connection request controls using the
121 * <tt>InitialLdapContext</tt> constructor or
122 * <tt>LdapReferralContext.getReferralContext()</tt>. These connection
123 * request controls are inherited by contexts that share the same
124 * connection--that is, contexts derived from the initial or referral
125 * contexts.
126 * <p>
127 * Use <tt>reconnect()</tt> to change the connection request controls of
128 * a context.
129 * Invoking <tt>ldapContext.reconnect()</tt> affects only the
130 * connection used by <tt>ldapContext</tt> and any new contexts instances that are
131 * derived form <tt>ldapContext</tt>. Contexts that previously shared the
132 * connection with <tt>ldapContext</tt> remain unchanged. That is, a context's
133 * connection request controls must be explicitly changed and is not
134 * affected by changes to another context's connection request
135 * controls.
136 * <p>
137 * A context instance's connection request controls are retrieved using
138 * the method <tt>getConnectControls()</tt>.
139 *
140 * <h4>Service Provider Requirements</h4>
141 *
142 * A service provider supports connection and context request controls
143 * in the following ways. Context request controls must be associated on
144 * a per context instance basis while connection request controls must be
145 * associated on a per connection instance basis. The service provider
146 * must look for the connection request controls in the environment
147 * property "java.naming.ldap.control.connect" and pass this environment
148 * property on to context instances that it creates.
149 *
150 * <h3>Response Controls</h3>
151 *
152 * The method <tt>LdapContext.getResponseControls()</tt> is used to
153 * retrieve the response controls generated by LDAP operations executed
154 * as the result of invoking a <tt>Context</tt>/<tt>DirContext</tt>
155 * operation. The result is all of the responses controls generated
156 * by the underlying LDAP operations, including any implicit reconnection.
157 * To get only the reconnection response controls,
158 * use <tt>reconnect()</tt> followed by <tt>getResponseControls()</tt>.
159 *
160 * <h3>Parameters</h3>
161 *
162 * A <tt>Control[]</tt> array
163 * passed as a parameter to any method is owned by the caller.
164 * The service provider will not modify the array or keep a reference to it,
165 * although it may keep references to the individual <tt>Control</tt> objects
166 * in the array.
167 * A <tt>Control[]</tt> array returned by any method is immutable, and may
168 * not subsequently be modified by either the caller or the service provider.
169 *
170 * @author Rosanna Lee
171 * @author Scott Seligman
172 * @author Vincent Ryan
173 *
174 * @see InitialLdapContext
175 * @see LdapReferralException#getReferralContext(java.util.Hashtable,javax.naming.ldap.Control[])
176 * @since 1.3
177 */
178
179 public interface LdapContext extends DirContext {
180 /**
181 * Performs an extended operation.
182 *
183 * This method is used to support LDAPv3 extended operations.
184 * @param request The non-null request to be performed.
185 * @return The possibly null response of the operation. null means
186 * the operation did not generate any response.
187 * @throws NamingException If an error occurred while performing the
188 * extended operation.
189 */
190 public ExtendedResponse extendedOperation(ExtendedRequest request)
191 throws NamingException;
192
193 /**
194 * Creates a new instance of this context initialized using request controls.
195 *
196 * This method is a convenience method for creating a new instance
197 * of this context for the purposes of multithreaded access.
198 * For example, if multiple threads want to use different context
199 * request controls,
200 * each thread may use this method to get its own copy of this context
201 * and set/get context request controls without having to synchronize with other
202 * threads.
203 *<p>
204 * The new context has the same environment properties and connection
205 * request controls as this context. See the class description for details.
206 * Implementations might also allow this context and the new context
207 * to share the same network connection or other resources if doing
208 * so does not impede the independence of either context.
209 *
210 * @param requestControls The possibly null request controls
211 * to use for the new context.
212 * If null, the context is initialized with no request controls.
213 *
214 * @return A non-null <tt>LdapContext</tt> instance.
215 * @exception NamingException If an error occurred while creating
216 * the new instance.
217 * @see InitialLdapContext
218 */
219 public LdapContext newInstance(Control[] requestControls)
220 throws NamingException;
221
222 /**
223 * Reconnects to the LDAP server using the supplied controls and
224 * this context's environment.
225 *<p>
226 * This method is a way to explicitly initiate an LDAP "bind" operation.
227 * For example, you can use this method to set request controls for
228 * the LDAP "bind" operation, or to explicitly connect to the server
229 * to get response controls returned by the LDAP "bind" operation.
230 *<p>
231 * This method sets this context's <tt>connCtls</tt>
232 * to be its new connection request controls. This context's
233 * context request controls are not affected.
234 * After this method has been invoked, any subsequent
235 * implicit reconnections will be done using <tt>connCtls</tt>.
236 * <tt>connCtls</tt> are also used as
237 * connection request controls for new context instances derived from this
238 * context.
239 * These connection request controls are not
240 * affected by <tt>setRequestControls()</tt>.
241 *<p>
242 * Service provider implementors should read the "Service Provider" section
243 * in the class description for implementation details.
244 * @param connCtls The possibly null controls to use. If null, no
245 * controls are used.
246 * @exception NamingException If an error occurred while reconnecting.
247 * @see #getConnectControls
248 * @see #newInstance
249 */
250 public void reconnect(Control[] connCtls) throws NamingException;
251
252 /**
253 * Retrieves the connection request controls in effect for this context.
254 * The controls are owned by the JNDI implementation and are
255 * immutable. Neither the array nor the controls may be modified by the
256 * caller.
257 *
258 * @return A possibly-null array of controls. null means no connect controls
259 * have been set for this context.
260 * @exception NamingException If an error occurred while getting the request
261 * controls.
262 */
263 public Control[] getConnectControls() throws NamingException;
264
265 /**
266 * Sets the request controls for methods subsequently
267 * invoked on this context.
268 * The request controls are owned by the JNDI implementation and are
269 * immutable. Neither the array nor the controls may be modified by the
270 * caller.
271 * <p>
272 * This removes any previous request controls and adds
273 * <tt>requestControls</tt>
274 * for use by subsequent methods invoked on this context.
275 * This method does not affect this context's connection request controls.
276 *<p>
277 * Note that <tt>requestControls</tt> will be in effect until the next
278 * invocation of <tt>setRequestControls()</tt>. You need to explicitly
279 * invoke <tt>setRequestControls()</tt> with <tt>null</tt> or an empty
280 * array to clear the controls if you don't want them to affect the
281 * context methods any more.
282 * To check what request controls are in effect for this context, use
283 * <tt>getRequestControls()</tt>.
284 * @param requestControls The possibly null controls to use. If null, no
285 * controls are used.
286 * @exception NamingException If an error occurred while setting the
287 * request controls.
288 * @see #getRequestControls
289 */
290 public void setRequestControls(Control[] requestControls)
291 throws NamingException;
292
293 /**
294 * Retrieves the request controls in effect for this context.
295 * The request controls are owned by the JNDI implementation and are
296 * immutable. Neither the array nor the controls may be modified by the
297 * caller.
298 *
299 * @return A possibly-null array of controls. null means no request controls
300 * have been set for this context.
301 * @exception NamingException If an error occurred while getting the request
302 * controls.
303 * @see #setRequestControls
304 */
305 public Control[] getRequestControls() throws NamingException;
306
307 /**
308 * Retrieves the response controls produced as a result of the last
309 * method invoked on this context.
310 * The response controls are owned by the JNDI implementation and are
311 * immutable. Neither the array nor the controls may be modified by the
312 * caller.
313 *<p>
314 * These response controls might have been generated by a successful or
315 * failed operation.
316 *<p>
317 * When a context method that may return response controls is invoked,
318 * response controls from the previous method invocation are cleared.
319 * <tt>getResponseControls()</tt> returns all of the response controls
320 * generated by LDAP operations used by the context method in the order
321 * received from the LDAP server.
322 * Invoking <tt>getResponseControls()</tt> does not
323 * clear the response controls. You can call it many times (and get
324 * back the same controls) until the next context method that may return
325 * controls is invoked.
326 *<p>
327 * @return A possibly null array of controls. If null, the previous
328 * method invoked on this context did not produce any controls.
329 * @exception NamingException If an error occurred while getting the response
330 * controls.
331 */
332 public Control[] getResponseControls() throws NamingException;
333
334 /**
335 * Constant that holds the name of the environment property
336 * for specifying the list of control factories to use. The value
337 * of the property should be a colon-separated list of the fully
338 * qualified class names of factory classes that will create a control
339 * given another control. See
340 * <tt>ControlFactory.getControlInstance()</tt> for details.
341 * This property may be specified in the environment, an applet
342 * parameter, a system property, or one or more resource files.
343 *<p>
344 * The value of this constant is "java.naming.factory.control".
345 *<p>
346 * @see ControlFactory
347 * @see javax.naming.Context#addToEnvironment
348 * @see javax.naming.Context#removeFromEnvironment
349 */
350 static final String CONTROL_FACTORIES = "java.naming.factory.control";
351 }