LdapContext


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