3853N/A * Copyright (c) 1999, 2004, Oracle and/or its affiliates. All rights reserved. 3853N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 3853N/A * This code is free software; you can redistribute it and/or modify it 3853N/A * under the terms of the GNU General Public License version 2 only, as 3853N/A * published by the Free Software Foundation. Oracle designates this 3853N/A * particular file as subject to the "Classpath" exception as provided 3853N/A * by Oracle in the LICENSE file that accompanied this code. 3853N/A * This code is distributed in the hope that it will be useful, but WITHOUT 3853N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 3853N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 3853N/A * version 2 for more details (a copy is included in the LICENSE file that 3853N/A * You should have received a copy of the GNU General Public License version 3853N/A * 2 along with this work; if not, write to the Free Software Foundation, 3853N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 3853N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 3853N/A * or visit www.oracle.com if you need additional information or have any * This class contains methods for supporting <tt>DirContext</tt> * This class is an extension of <tt>NamingManager</tt>. It contains methods * for use by service providers for accessing object factories and * state factories, and for getting continuation contexts for * <tt>DirectoryManager</tt> is safe for concurrent access by multiple threads. * Except as otherwise noted, * a <tt>Name</tt>, <tt>Attributes</tt>, or environment parameter * passed to any method is owned by the caller. * The implementation will not modify the object or keep a reference * to it, although it may keep a reference to a clone or copy. * Disallow anyone from creating one of these. * Creates a context in which to continue a <tt>DirContext</tt> operation. * Operates just like <tt>NamingManager.getContinuationContext()</tt>, * only the continuation context returned is a <tt>DirContext</tt>. * The non-null exception that triggered this continuation. * @return A non-null <tt>DirContext</tt> object for continuing the operation. * @exception NamingException If a naming exception occurred. * @see NamingManager#getContinuationContext(CannotProceedException) // Make a (shallow) copy of the environment. * Creates an instance of an object for the specified object, * attributes, and environment. * This method is the same as <tt>NamingManager.getObjectInstance</tt> * except for the following differences: * It accepts an <tt>Attributes</tt> parameter that contains attributes * associated with the object. The <tt>DirObjectFactory</tt> might use these * attributes to save having to look them up from the directory. * The object factories tried must implement either * <tt>ObjectFactory</tt> or <tt>DirObjectFactory</tt>. * If it implements <tt>DirObjectFactory</tt>, * <tt>DirObjectFactory.getObjectInstance()</tt> is used, otherwise, * <tt>ObjectFactory.getObjectInstance()</tt> is used. * Service providers that implement the <tt>DirContext</tt> interface * should use this method, not <tt>NamingManager.getObjectInstance()</tt>. * @param refInfo The possibly null object for which to create an object. * @param name The name of this object relative to <code>nameCtx</code>. * Specifying a name is optional; if it is * omitted, <code>name</code> should be null. * @param nameCtx The context relative to which the <code>name</code> * parameter is specified. If null, <code>name</code> is * relative to the default initial context. * @param environment The possibly null environment to * be used in the creation of the object factory and the object. * @param attrs The possibly null attributes associated with refInfo. * This might not be the complete set of attributes for refInfo; * you might be able to read more attributes from the directory. * @return An object created using <code>refInfo</code> and <tt>attrs</tt>; or * <code>refInfo</code> if an object cannot be created by * @exception NamingException If a naming exception was encountered * while attempting to get a URL context, or if one of the * factories accessed throws a NamingException. * @exception Exception If one of the factories accessed throws an * exception, or if an error was encountered while loading * and instantiating the factory and object classes. * A factory should only throw an exception if it does not want * other factories to be used in an attempt to create an object. * See <tt>DirObjectFactory.getObjectInstance()</tt>. * @see NamingManager#getURLContext * @see DirObjectFactory#getObjectInstance // builder must return non-null factory // use reference if possible // if reference identifies a factory, use exclusively // No factory found, so return original refInfo. // Will reach this point if factory class is not in // class path and reference does not contain a URL for it // if reference has no factory, check for addresses // ignore name & attrs params; not used in URL factory // try using any specified factories // Try each factory until one succeeds * Retrieves the state of an object for binding when given the original * object and its attributes. * This method is like <tt>NamingManager.getStateToBind</tt> except * for the following differences: *<li>It accepts an <tt>Attributes</tt> parameter containing attributes * that were passed to the <tt>DirContext.bind()</tt> method. *<li>It returns a non-null <tt>DirStateFactory.Result</tt> instance * containing the object to be bound, and the attributes to * accompany the binding. Either the object or the attributes may be null. * The state factories tried must each implement either * <tt>StateFactory</tt> or <tt>DirStateFactory</tt>. * If it implements <tt>DirStateFactory</tt>, then * <tt>DirStateFactory.getStateToBind()</tt> is called; otherwise, * <tt>StateFactory.getStateToBind()</tt> is called. * Service providers that implement the <tt>DirContext</tt> interface * should use this method, not <tt>NamingManager.getStateToBind()</tt>. * See NamingManager.getStateToBind() for a description of how * the list of state factories to be tried is determined. * The object returned by this method is owned by the caller. * The implementation will not subsequently modify it. * It will contain either a new <tt>Attributes</tt> object that is * likewise owned by the caller, or a reference to the original * <tt>attrs</tt> parameter. * @param obj The non-null object for which to get state to bind. * @param name The name of this object relative to <code>nameCtx</code>, * or null if no name is specified. * @param nameCtx The context relative to which the <code>name</code> * parameter is specified, or null if <code>name</code> is * relative to the default initial context. * @param environment The possibly null environment to * be used in the creation of the state factory and * @param attrs The possibly null Attributes that is to be bound with the * @return A non-null DirStateFactory.Result containing * the object and attributes to be bound. * If no state factory returns a non-null answer, the result will contain * the object (<tt>obj</tt>) itself with the original attributes. * @exception NamingException If a naming exception was encountered * while using the factories. * A factory should only throw an exception if it does not want * other factories to be used in an attempt to create an object. * See <tt>DirStateFactory.getStateToBind()</tt>. * @see DirStateFactory#getStateToBind * @see NamingManager#getStateToBind // Get list of state factories // no factories to try; just return originals // Try each factory until one succeeds