Java tutorial
/* * 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. *<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 {@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 {@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. * * @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(); } }