ojluni/src/main/java/javax/naming/ldap/InitialLdapContext.java - platform/libcore - Git at Google

 /*
  * 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.
   *<p>
   * See <tt>javax.naming.InitialContext</tt> and
   * <tt>javax.naming.InitialDirContext</tt> for details on synchronization,
   * and the policy for how an initial context is created.
   *
   * <h4>Request Controls</h4>
   * When you create an initial context (<tt>InitialLdapContext</tt>),
   * 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 <tt>getConnectControls()</tt> 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
   * <tt>setRequestControls()</tt>.
   *<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
   * (<tt>critConnCtls</tt>), and then sets the context's request controls
   * (<tt>critModCtls</tt>) for the context operation. If for some reason
   * <tt>lctx</tt> needs to reconnect to the server, it will use
   * <tt>critConnCtls</tt>. See the <tt>LdapContext</tt> interface for
   * more discussion about request controls.
   *<p>
   * Service provider implementors should read the "Service Provider" section
   * in the <tt>LdapContext</tt> 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 <tt>new InitialLdapContext(null, null)</tt>.
      *
      * @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 <tt>javax.naming.InitialContext</tt> 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
      * <tt>environment</tt> after it has been passed to the constructor.
      *
      * <p> <tt>connCtls</tt> 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
      */
     public InitialLdapContext(Hashtable<?,?> environment,
                               Control[] connCtls)
             throws NamingException {
         super(true); // don't initialize yet

         // Clone environment since caller owns it.
         Hashtable env = (environment == null)
             ? new Hashtable(11)
             : (Hashtable)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 <tt>LdapContext</tt>.
      * @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();
     }
 }
	/*
	* 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.
	*<p>
	* See <tt>javax.naming.InitialContext</tt> and
	* <tt>javax.naming.InitialDirContext</tt> for details on synchronization,
	* and the policy for how an initial context is created.
	*
	* <h4>Request Controls</h4>
	* When you create an initial context (<tt>InitialLdapContext</tt>),
	* 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 <tt>getConnectControls()</tt> 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
	* <tt>setRequestControls()</tt>.
	*<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
	* (<tt>critConnCtls</tt>), and then sets the context's request controls
	* (<tt>critModCtls</tt>) for the context operation. If for some reason
	* <tt>lctx</tt> needs to reconnect to the server, it will use
	* <tt>critConnCtls</tt>. See the <tt>LdapContext</tt> interface for
	* more discussion about request controls.
	*<p>
	* Service provider implementors should read the "Service Provider" section
	* in the <tt>LdapContext</tt> 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 <tt>new InitialLdapContext(null, null)</tt>.
	*
	* @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 <tt>javax.naming.InitialContext</tt> 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
	* <tt>environment</tt> after it has been passed to the constructor.
	*
	* <p> <tt>connCtls</tt> 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
	*/
	public InitialLdapContext(Hashtable<?,?> environment,
	Control[] connCtls)
	throws NamingException {
	super(true); // don't initialize yet

	// Clone environment since caller owns it.
	Hashtable env = (environment == null)
	? new Hashtable(11)
	: (Hashtable)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 <tt>LdapContext</tt>.
	* @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();
	}
	}