1 /* 2 * Copyright (c) 1999, 2014, 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 * <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 * {@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 * <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><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 * <h4>Connection Request Controls</h4> 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 * <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 {@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 * <h3>Parameters</h3> 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 /** | 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 * <h2>Context Request Controls</h2> 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 * <h2>Connection Request Controls</h2> 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 * <h2>Service Provider Requirements</h2> 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 /** |