/* * Copyright (c) 1999, 2009, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ package javax.naming.ldap; import javax.naming.*; import javax.naming.directory.*; import java.util.Hashtable; /** * This class is the starting context for performing * LDAPv3-style extended operations and controls. *
* See javax.naming.InitialContext and * javax.naming.InitialDirContext for details on synchronization, * and the policy for how an initial context is created. * *
* The request controls supplied to the initial context constructor * are not used as the context request controls * for subsequent context operations such as searches and lookups. * Context request controls are set and updated by using * setRequestControls(). *
* As shown, there can be two different sets of request controls * associated with a context: connection request controls and context * request controls. * This is required for those applications needing to send critical * controls that might not be applicable to both the context operation and * any implicit LDAP "bind" operation. * A typical user program would do the following: *
* It specifies first the critical controls for creating the initial context * (critConnCtls), and then sets the context's request controls * (critModCtls) for the context operation. If for some reason * lctx needs to reconnect to the server, it will use * critConnCtls. See the LdapContext interface for * more discussion about request controls. ** InitialLdapContext lctx = new InitialLdapContext(env, critConnCtls); * lctx.setRequestControls(critModCtls); * lctx.modifyAttributes(name, mods); * Controls[] respCtls = lctx.getResponseControls(); *
* Service provider implementors should read the "Service Provider" section * in the LdapContext class description for implementation details. * * @author Rosanna Lee * @author Scott Seligman * @author Vincent Ryan * * @see LdapContext * @see javax.naming.InitialContext * @see javax.naming.directory.InitialDirContext * @see javax.naming.spi.NamingManager#setInitialContextFactoryBuilder * @since 1.3 */ public class InitialLdapContext extends InitialDirContext implements LdapContext { private static final String BIND_CONTROLS_PROPERTY = "java.naming.ldap.control.connect"; /** * Constructs an initial context using no environment properties or * connection request controls. * Equivalent to new InitialLdapContext(null, null). * * @throws NamingException if a naming exception is encountered */ public InitialLdapContext() throws NamingException { super(null); } /** * Constructs an initial context * using environment properties and connection request controls. * See javax.naming.InitialContext for a discussion of * environment properties. * *
This constructor will not modify its parameters or * save references to them, but may save a clone or copy. * Caller should not modify mutable keys and values in * environment after it has been passed to the constructor. * *
connCtls is used as the underlying context instance's * connection request controls. See the class description * for details. * * @param environment * environment used to create the initial DirContext. * Null indicates an empty environment. * @param connCtls * connection request controls for the initial context. * If null, no connection request controls are used. * * @throws NamingException if a naming exception is encountered * * @see #reconnect * @see LdapContext#reconnect */ @SuppressWarnings("unchecked") public InitialLdapContext(Hashtable,?> environment, Control[] connCtls) throws NamingException { super(true); // don't initialize yet // Clone environment since caller owns it. Hashtable