1 /* 2 * Copyright (c) 1999, 2019, 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 {@code javax.naming.directory.DirContext} 39 * should be used instead. 40 * 41 * <h2>Usage Details About Controls</h2> 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 * {@code Context}/{@code DirContext} 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 * <h2>Request Controls</h2> 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 * <h3>Context Request Controls</h3> 79 * There are two ways in which a context instance gets its request controls: 80 * <ol> 81 * <li><code>ldapContext.newInstance(<strong>reqCtls</strong>)</code> 82 * <li><code>ldapContext.setRequestControls(<strong>reqCtls</strong>)</code> 83 * </ol> 84 * where {@code ldapContext} is an instance of {@code LdapContext}. 85 * Specifying {@code null} or an empty array for {@code reqCtls} 86 * means no request controls. 87 * {@code newInstance()} creates a new instance of a context using 88 * {@code reqCtls}, while {@code setRequestControls()} 89 * updates an existing context instance's request controls to {@code reqCtls}. 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 {@code null} as their context 94 * request controls. You must set the request controls of a derived context 95 * instance explicitly using {@code setRequestControls()}. 96 * <p> 97 * A context instance's request controls are retrieved using 98 * the method {@code getRequestControls()}. 99 * 100 * <h3>Connection Request Controls</h3> 101 * There are three ways in which connection request controls are set: 102 * <ol> 103 * <li><code> 104 * new InitialLdapContext(env, <strong>connCtls</strong>)</code> 105 * <li><code>refException.getReferralContext(env, <strong>connCtls</strong>)</code> 106 * <li><code>ldapContext.reconnect(<strong>connCtls</strong>);</code> 107 * </ol> 108 * where {@code refException} is an instance of 109 * {@code LdapReferralException}, and {@code ldapContext} is an 110 * instance of {@code LdapContext}. 111 * Specifying {@code null} or an empty array for {@code connCtls} 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 * {@code InitialLdapContext} constructor or 118 * {@code LdapReferralContext.getReferralContext()}. 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 {@code reconnect()} to change the connection request controls of 124 * a context. 125 * Invoking {@code ldapContext.reconnect()} affects only the 126 * connection used by {@code ldapContext} and any new contexts instances that are 127 * derived form {@code ldapContext}. Contexts that previously shared the 128 * connection with {@code ldapContext} 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 {@code getConnectControls()}. 135 * 136 * <h3>Service Provider Requirements</h3> 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 * <h2>Response Controls</h2> 147 * 148 * The method {@code LdapContext.getResponseControls()} is used to 149 * retrieve the response controls generated by LDAP operations executed 150 * as the result of invoking a {@code Context}/{@code DirContext} 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 {@code reconnect()} followed by {@code getResponseControls()}. 155 * 156 * <h2>Parameters</h2> 157 * 158 * A {@code Control[]} 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 {@code Control} objects 162 * in the array. 163 * A {@code Control[]} 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 {@code LdapContext} 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 {@code connCtls} 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 {@code connCtls}. 232 * {@code connCtls} 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 {@code setRequestControls()}. 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 * {@code requestControls} 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 {@code requestControls} will be in effect until the next 274 * invocation of {@code setRequestControls()}. You need to explicitly 275 * invoke {@code setRequestControls()} with {@code null} 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 * {@code getRequestControls()}. 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 * {@code getResponseControls()} 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 {@code getResponseControls()} 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 * 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 * {@code ControlFactory.getControlInstance()} for details. 337 * This property may be specified in the environment, a system property, 338 * 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 }