View Javadoc
1   /*
2    * Copyright (c) 1999, 2013, 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   * <li><tt>ldapContext.newInstance(<strong>reqCtls</strong>)</tt>
82   * <li><tt>ldapContext.setRequestControls(<strong>reqCtls</strong>)</tt>
83   * </ol>
84   * where <tt>ldapContext</tt> is an instance of <tt>LdapContext</tt>.
85   * Specifying <tt>null</tt> or an empty array for <tt>reqCtls</tt>
86   * means no request controls.
87   * <tt>newInstance()</tt> creates a new instance of a context using
88   * <tt>reqCtls</tt>, while <tt>setRequestControls()</tt>
89   * updates an existing context instance's request controls to <tt>reqCtls</tt>.
90   * <p>
91   * Unlike environment properties, request controls of a context instance
92   * <em>are not inherited</em> by context instances that are derived from
93   * it.  Derived context instances have <tt>null</tt> as their context
94   * request controls.  You must set the request controls of a derived context
95   * instance explicitly using <tt>setRequestControls()</tt>.
96   * <p>
97   * A context instance's request controls are retrieved using
98   * the method <tt>getRequestControls()</tt>.
99   *
100  * <h4>Connection Request Controls</h4>
101  * There are three ways in which connection request controls are set:
102  * <ol>
103  * <li><tt>
104  * new InitialLdapContext(env, <strong>connCtls</strong>)</tt>
105  * <li><tt>refException.getReferralContext(env, <strong>connCtls</strong>)</tt>
106  * <li><tt>ldapContext.reconnect(<strong>connCtls</strong>);</tt>
107  * </ol>
108  * where <tt>refException</tt> is an instance of
109  * <tt>LdapReferralException</tt>, and <tt>ldapContext</tt> is an
110  * instance of <tt>LdapContext</tt>.
111  * Specifying <tt>null</tt> or an empty array for <tt>connCtls</tt>
112  * means no connection request controls.
113  * <p>
114  * Like environment properties, connection request controls of a context
115  * <em>are inherited</em> by contexts that are derived from it.
116  * Typically, you initialize the connection request controls using the
117  * <tt>InitialLdapContext</tt> constructor or
118  * <tt>LdapReferralContext.getReferralContext()</tt>. These connection
119  * request controls are inherited by contexts that share the same
120  * connection--that is, contexts derived from the initial or referral
121  * contexts.
122  * <p>
123  * Use <tt>reconnect()</tt> to change the connection request controls of
124  * a context.
125  * Invoking <tt>ldapContext.reconnect()</tt> affects only the
126  * connection used by <tt>ldapContext</tt> and any new contexts instances that are
127  * derived form <tt>ldapContext</tt>. Contexts that previously shared the
128  * connection with <tt>ldapContext</tt> remain unchanged. That is, a context's
129  * connection request controls must be explicitly changed and is not
130  * affected by changes to another context's connection request
131  * controls.
132  * <p>
133  * A context instance's connection request controls are retrieved using
134  * the method <tt>getConnectControls()</tt>.
135  *
136  * <h4>Service Provider Requirements</h4>
137  *
138  * A service provider supports connection and context request controls
139  * in the following ways.  Context request controls must be associated on
140  * a per context instance basis while connection request controls must be
141  * associated on a per connection instance basis.  The service provider
142  * must look for the connection request controls in the environment
143  * property "java.naming.ldap.control.connect" and pass this environment
144  * property on to context instances that it creates.
145  *
146  * <h3>Response Controls</h3>
147  *
148  * The method <tt>LdapContext.getResponseControls()</tt> is used to
149  * retrieve the response controls generated by LDAP operations executed
150  * as the result of invoking a <tt>Context</tt>/<tt>DirContext</tt>
151  * operation. The result is all of the responses controls generated
152  * by the underlying LDAP operations, including any implicit reconnection.
153  * To get only the reconnection response controls,
154  * use <tt>reconnect()</tt> followed by <tt>getResponseControls()</tt>.
155  *
156  * <h3>Parameters</h3>
157  *
158  * A <tt>Control[]</tt> array
159  * passed as a parameter to any method is owned by the caller.
160  * The service provider will not modify the array or keep a reference to it,
161  * although it may keep references to the individual <tt>Control</tt> objects
162  * in the array.
163  * A <tt>Control[]</tt> array returned by any method is immutable, and may
164  * not subsequently be modified by either the caller or the service provider.
165  *
166  * @author Rosanna Lee
167  * @author Scott Seligman
168  * @author Vincent Ryan
169  *
170  * @see InitialLdapContext
171  * @see LdapReferralException#getReferralContext(java.util.Hashtable,javax.naming.ldap.Control[])
172  * @since 1.3
173  */
174 
175 public interface LdapContext extends DirContext {
176    /**
177     * Performs an extended operation.
178     *
179     * This method is used to support LDAPv3 extended operations.
180     * @param request The non-null request to be performed.
181     * @return The possibly null response of the operation. null means
182     * the operation did not generate any response.
183     * @throws NamingException If an error occurred while performing the
184     * extended operation.
185     */
186     public ExtendedResponse extendedOperation(ExtendedRequest request)
187         throws NamingException;
188 
189     /**
190      * Creates a new instance of this context initialized using request controls.
191      *
192      * This method is a convenience method for creating a new instance
193      * of this context for the purposes of multithreaded access.
194      * For example, if multiple threads want to use different context
195      * request controls,
196      * each thread may use this method to get its own copy of this context
197      * and set/get context request controls without having to synchronize with other
198      * threads.
199      *<p>
200      * The new context has the same environment properties and connection
201      * request controls as this context. See the class description for details.
202      * Implementations might also allow this context and the new context
203      * to share the same network connection or other resources if doing
204      * so does not impede the independence of either context.
205      *
206      * @param requestControls The possibly null request controls
207      * to use for the new context.
208      * If null, the context is initialized with no request controls.
209      *
210      * @return A non-null <tt>LdapContext</tt> instance.
211      * @exception NamingException If an error occurred while creating
212      * the new instance.
213      * @see InitialLdapContext
214      */
215     public LdapContext newInstance(Control[] requestControls)
216         throws NamingException;
217 
218     /**
219      * Reconnects to the LDAP server using the supplied controls and
220      * this context's environment.
221      *<p>
222      * This method is a way to explicitly initiate an LDAP "bind" operation.
223      * For example, you can use this method to set request controls for
224      * the LDAP "bind" operation, or to explicitly connect to the server
225      * to get response controls returned by the LDAP "bind" operation.
226      *<p>
227      * This method sets this context's <tt>connCtls</tt>
228      * to be its new connection request controls. This context's
229      * context request controls are not affected.
230      * After this method has been invoked, any subsequent
231      * implicit reconnections will be done using <tt>connCtls</tt>.
232      * <tt>connCtls</tt> are also used as
233      * connection request controls for new context instances derived from this
234      * context.
235      * These connection request controls are not
236      * affected by <tt>setRequestControls()</tt>.
237      *<p>
238      * Service provider implementors should read the "Service Provider" section
239      * in the class description for implementation details.
240      * @param connCtls The possibly null controls to use. If null, no
241      * controls are used.
242      * @exception NamingException If an error occurred while reconnecting.
243      * @see #getConnectControls
244      * @see #newInstance
245      */
246     public void reconnect(Control[] connCtls) throws NamingException;
247 
248     /**
249      * Retrieves the connection request controls in effect for this context.
250      * The controls are owned by the JNDI implementation and are
251      * immutable. Neither the array nor the controls may be modified by the
252      * caller.
253      *
254      * @return A possibly-null array of controls. null means no connect controls
255      * have been set for this context.
256      * @exception NamingException If an error occurred while getting the request
257      * controls.
258      */
259     public Control[] getConnectControls() throws NamingException;
260 
261     /**
262      * Sets the request controls for methods subsequently
263      * invoked on this context.
264      * The request controls are owned by the JNDI implementation and are
265      * immutable. Neither the array nor the controls may be modified by the
266      * caller.
267      * <p>
268      * This removes any previous request controls and adds
269      * <tt>requestControls</tt>
270      * for use by subsequent methods invoked on this context.
271      * This method does not affect this context's connection request controls.
272      *<p>
273      * Note that <tt>requestControls</tt> will be in effect until the next
274      * invocation of <tt>setRequestControls()</tt>. You need to explicitly
275      * invoke <tt>setRequestControls()</tt> with <tt>null</tt> or an empty
276      * array to clear the controls if you don't want them to affect the
277      * context methods any more.
278      * To check what request controls are in effect for this context, use
279      * <tt>getRequestControls()</tt>.
280      * @param requestControls The possibly null controls to use. If null, no
281      * controls are used.
282      * @exception NamingException If an error occurred while setting the
283      * request controls.
284      * @see #getRequestControls
285      */
286     public void setRequestControls(Control[] requestControls)
287         throws NamingException;
288 
289     /**
290      * Retrieves the request controls in effect for this context.
291      * The request controls are owned by the JNDI implementation and are
292      * immutable. Neither the array nor the controls may be modified by the
293      * caller.
294      *
295      * @return A possibly-null array of controls. null means no request controls
296      * have been set for this context.
297      * @exception NamingException If an error occurred while getting the request
298      * controls.
299      * @see #setRequestControls
300      */
301     public Control[] getRequestControls() throws NamingException;
302 
303     /**
304      * Retrieves the response controls produced as a result of the last
305      * method invoked on this context.
306      * The response controls are owned by the JNDI implementation and are
307      * immutable. Neither the array nor the controls may be modified by the
308      * caller.
309      *<p>
310      * These response controls might have been generated by a successful or
311      * failed operation.
312      *<p>
313      * When a context method that may return response controls is invoked,
314      * response controls from the previous method invocation are cleared.
315      * <tt>getResponseControls()</tt> returns all of the response controls
316      * generated by LDAP operations used by the context method in the order
317      * received from the LDAP server.
318      * Invoking <tt>getResponseControls()</tt> does not
319      * clear the response controls. You can call it many times (and get
320      * back the same controls) until the next context method that may return
321      * controls is invoked.
322      *<p>
323      * @return A possibly null array of controls. If null, the previous
324      * method invoked on this context did not produce any controls.
325      * @exception NamingException If an error occurred while getting the response
326      * controls.
327      */
328     public Control[] getResponseControls() throws NamingException;
329 
330     /**
331      * Constant that holds the name of the environment property
332      * for specifying the list of control factories to use. The value
333      * of the property should be a colon-separated list of the fully
334      * qualified class names of factory classes that will create a control
335      * given another control. See
336      * <tt>ControlFactory.getControlInstance()</tt> for details.
337      * This property may be specified in the environment, an applet
338      * parameter, a system property, or one or more resource files.
339      *<p>
340      * The value of this constant is "java.naming.factory.control".
341      *
342      * @see ControlFactory
343      * @see javax.naming.Context#addToEnvironment
344      * @see javax.naming.Context#removeFromEnvironment
345      */
346     static final String CONTROL_FACTORIES = "java.naming.factory.control";
347 }