https://openjdk.java.net/ 
/*
 * Copyright (c) 1999, 2019, 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. 
Request Controls
 When you create an initial context (InitialLdapContext), you can specify a list of request controls. These controls will be used as the request controls for any implicit LDAP "bind" operation performed by the context or contexts derived from the context. These are called connection request controls. Use getConnectControls() to get a context's connection request controls. 

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:

InitialLdapContext lctx = new InitialLdapContext(env, critConnCtls);
lctx.setRequestControls(critModCtls);
lctx.modifyAttributes(name, mods);
Controls[] respCtls =  lctx.getResponseControls();

 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. 
 Service provider implementors should read the "Service Provider" section in the LdapContext class description for implementation details. 
Author:Rosanna Lee, Scott Seligman, Vincent Ryan
See Also:
Since:1.3
/**
  * This class is the starting context for performing
  * LDAPv3-style extended operations and controls.
  *<p>
  * See {@code javax.naming.InitialContext} and
  * {@code javax.naming.InitialDirContext} for details on synchronization,
  * and the policy for how an initial context is created.
  *
  * <h2>Request Controls</h2>
  * When you create an initial context ({@code InitialLdapContext}),
  * you can specify a list of request controls.
  * These controls will be used as the request controls for any
  * implicit LDAP "bind" operation performed by the context or contexts
  * derived from the context. These are called <em>connection request controls</em>.
  * Use {@code getConnectControls()} to get a context's connection request
  * controls.
  *<p>
  * The request controls supplied to the initial context constructor
  * are <em>not</em> used as the context request controls
  * for subsequent context operations such as searches and lookups.
  * Context request controls are set and updated by using
  * {@code setRequestControls()}.
  *<p>
  * 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:
  *<blockquote><pre>
  * InitialLdapContext lctx = new InitialLdapContext(env, critConnCtls);
  * lctx.setRequestControls(critModCtls);
  * lctx.modifyAttributes(name, mods);
  * Controls[] respCtls =  lctx.getResponseControls();
  *</pre></blockquote>
  * It specifies first the critical controls for creating the initial context
  * ({@code critConnCtls}), and then sets the context's request controls
  * ({@code critModCtls}) for the context operation. If for some reason
  * {@code lctx} needs to reconnect to the server, it will use
  * {@code critConnCtls}. See the {@code LdapContext} interface for
  * more discussion about request controls.
  *<p>
  * Service provider implementors should read the "Service Provider" section
  * in the {@code 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:
/**
     * Constructs an initial context using no environment properties or
     * connection request controls.
     * Equivalent to {@code 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. 
Params:
  • environment – 
         environment used to create the initial DirContext.
         Null indicates an empty environment.
  • connCtls – 
         connection request controls for the initial context.
         If null, no connection request controls are used.
Throws:
See Also:
/**
     * Constructs an initial context
     * using environment properties and connection request controls.
     * See {@code javax.naming.InitialContext} for a discussion of
     * environment properties.
     *
     * <p> 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
     * {@code environment} after it has been passed to the constructor.
     *
     * <p> {@code 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<Object,Object> env = (environment == null)
            ? new Hashtable<>(11)
            : (Hashtable<Object,Object>)environment.clone();

        // Put connect controls into environment.  Copy them first since
        // caller owns the array.
        if (connCtls != null) {
            Control[] copy = new Control[connCtls.length];
            System.arraycopy(connCtls, 0, copy, 0, connCtls.length);
            env.put(BIND_CONTROLS_PROPERTY, copy);
        }
        // set version to LDAPv3
        env.put("java.naming.ldap.version", "3");

        // Initialize with updated environment
        init(env);
    }

    
Retrieves the initial LDAP context.

Throws:
Returns:The non-null cached initial context.
/**
     * Retrieves the initial LDAP context.
     *
     * @return The non-null cached initial context.
     * @exception NotContextException If the initial context is not an
     * instance of {@code LdapContext}.
     * @exception NamingException If a naming exception was encountered.
     */
    private LdapContext getDefaultLdapInitCtx() throws NamingException{
        Context answer = getDefaultInitCtx();

        if (!(answer instanceof LdapContext)) {
            if (answer == null) {
                throw new NoInitialContextException();
            } else {
                throw new NotContextException(
                    "Not an instance of LdapContext");
            }
        }
        return (LdapContext)answer;
    }

// LdapContext methods
// Most Javadoc is deferred to the LdapContext interface.

    public ExtendedResponse extendedOperation(ExtendedRequest request)
            throws NamingException {
        return getDefaultLdapInitCtx().extendedOperation(request);
    }

    public LdapContext newInstance(Control[] reqCtls)
        throws NamingException {
            return getDefaultLdapInitCtx().newInstance(reqCtls);
    }

    public void reconnect(Control[] connCtls) throws NamingException {
        getDefaultLdapInitCtx().reconnect(connCtls);
    }

    public Control[] getConnectControls() throws NamingException {
        return getDefaultLdapInitCtx().getConnectControls();
    }

    public void setRequestControls(Control[] requestControls)
        throws NamingException {
            getDefaultLdapInitCtx().setRequestControls(requestControls);
    }

    public Control[] getRequestControls() throws NamingException {
        return getDefaultLdapInitCtx().getRequestControls();
    }

    public Control[] getResponseControls() throws NamingException {
        return getDefaultLdapInitCtx().getResponseControls();
    }
}