InitialContext.java revision 0
0N/A * Copyright 1999-2005 Sun Microsystems, Inc. All Rights Reserved. 0N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 0N/A * This code is free software; you can redistribute it and/or modify it 0N/A * under the terms of the GNU General Public License version 2 only, as 0N/A * published by the Free Software Foundation. Sun designates this 0N/A * particular file as subject to the "Classpath" exception as provided 0N/A * by Sun in the LICENSE file that accompanied this code. 0N/A * This code is distributed in the hope that it will be useful, but WITHOUT 0N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 0N/A * version 2 for more details (a copy is included in the LICENSE file that 0N/A * accompanied this code). 0N/A * You should have received a copy of the GNU General Public License version 0N/A * 2 along with this work; if not, write to the Free Software Foundation, 0N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 0N/A * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, 0N/A * CA 95054 USA or visit www.sun.com if you need additional information or 0N/A * have any questions. 0N/A * This class is the starting context for performing naming operations. 0N/A * All naming operations are relative to a context. 0N/A * The initial context implements the Context interface and 0N/A * provides the starting point for resolution of names. 0N/A * <a name=ENVIRONMENT></a> 0N/A * When the initial context is constructed, its environment 0N/A * is initialized with properties defined in the environment parameter 0N/A * passed to the constructor, and in any 0N/A * In addition, a small number of standard JNDI properties may 0N/A * be specified as system properties or as applet parameters 0N/A * (through the use of {@link Context#APPLET}). 0N/A * These special properties are listed in the field detail sections of the 0N/A * interface documentation. 0N/A * JNDI determines each property's value by merging 0N/A * the values from the following two sources, in order: 0N/A * The first occurrence of the property from the constructor's 0N/A * environment parameter and (for appropriate properties) the applet 0N/A * parameters and system properties. 0N/A * For each property found in both of these two sources, or in 0N/A * more than one application resource file, the property's value 0N/A * is determined as follows. If the property is 0N/A * one of the standard JNDI properties that specify a list of JNDI 0N/A * all of the values are 0N/A * concatenated into a single colon-separated list. For other 0N/A * properties, only the first value found is used. 0N/A * The initial context implementation is determined at runtime. 0N/A * The default policy uses the environment property 0N/A * which contains the class name of the initial context factory. 0N/A * An exception to this policy is made when resolving URL strings, as described 0N/A * When a URL string (a <tt>String</tt> of the form 0N/A * <em>scheme_id:rest_of_name</em>) is passed as a name parameter to 0N/A * any method, a URL context factory for handling that scheme is 0N/A * located and used to resolve the URL. If no such factory is found, 0N/A * the initial context specified by 0N/A * <tt>CompositeName</tt> object whose first component is a URL string is 0N/A * passed as a name parameter to any method, a URL context factory is 0N/A * located and used to resolve the first name component. 0N/A * See {@link NamingManager#getURLContext 0N/A * <tt>NamingManager.getURLContext()</tt>} for a description of how URL 0N/A * context factories are located. 0N/A * This default policy of locating the initial context and URL context 0N/A * factories may be overridden 0N/A * <tt>NamingManager.setInitialContextFactoryBuilder()</tt>. 0N/A * NoInitialContextException is thrown when an initial context cannot 0N/A * be instantiated. This exception can be thrown during any interaction 0N/A * with the InitialContext, not only when the InitialContext is constructed. 0N/A * For example, the implementation of the initial context might lazily 0N/A * retrieve the context only when actual methods are invoked on it. 0N/A * The application should not have any dependency on when the existence 0N/A * of an initial context is determined. 0N/A * non-null, the InitialContext constructor will attempt to create the 0N/A * initial context specified therein. At that time, the initial context factory 0N/A * involved might throw an exception if a problem is encountered. However, 0N/A * it is provider implementation-dependent when it verifies and indicates 0N/A * to the users of the initial context any environment property- or 0N/A * connection- related problems. It can do so lazily--delaying until 0N/A * an operation is performed on the context, or eagerly, at the time 0N/A * the context is constructed. 0N/A * An InitialContext instance is not synchronized against concurrent 0N/A * access by multiple threads. Multiple threads each manipulating a 0N/A * different InitialContext instance need not synchronize. 0N/A * Threads that need to access a single InitialContext instance 0N/A * concurrently should synchronize amongst themselves and provide the 0N/A * necessary locking. 0N/A * @author Rosanna Lee 0N/A * @author Scott Seligman 0N/A * @see NamingManager#setInitialContextFactoryBuilder 0N/A * NamingManager.setInitialContextFactoryBuilder 0N/A * @since JNDI 1.1 / Java 2 Platform, Standard Edition, v 1.3 0N/A * The environment associated with this InitialContext. 0N/A * It is initialized to null and is updated by the constructor 0N/A * that accepts an environment or by the <tt>init()</tt> method. 0N/A * @see #addToEnvironment 0N/A * @see #removeFromEnvironment 0N/A * @see #getEnvironment 0N/A * Field holding the result of calling NamingManager.getInitialContext(). 0N/A * It is set by getDefaultInitCtx() the first time getDefaultInitCtx() 0N/A * is called. Subsequent invocations of getDefaultInitCtx() return 0N/A * the value of defaultInitCtx. 0N/A * @see #getDefaultInitCtx 0N/A * Field indicating whether the initial context has been obtained 0N/A * by calling NamingManager.getInitialContext(). 0N/A * If true, its result is in <code>defaultInitCtx</code>. 0N/A * Constructs an initial context with the option of not 0N/A * initializing it. This may be used by a constructor in 0N/A * a subclass when the value of the environment parameter 0N/A * is not yet known at the time the <tt>InitialContext</tt> 0N/A * constructor is called. The subclass's constructor will 0N/A * call this constructor, compute the value of the environment, 0N/A * and then call <tt>init()</tt> before returning. 0N/A * true means do not initialize the initial context; false 0N/A * is equivalent to calling <tt>new InitialContext()</tt> 0N/A * @throws NamingException if a naming exception is encountered 0N/A * @see #init(Hashtable) 0N/A * Constructs an initial context. 0N/A * No environment properties are supplied. 0N/A * Equivalent to <tt>new InitialContext(null)</tt>. 0N/A * @throws NamingException if a naming exception is encountered 0N/A * @see #InitialContext(Hashtable) 0N/A * Constructs an initial context using the supplied environment. 0N/A * Environment properties are discussed in the class description. 0N/A * <p> This constructor will not modify <tt>environment</tt> 0N/A * or save a reference to it, but may save a clone. 0N/A * @param environment 0N/A * environment used to create the initial context. 0N/A * Null indicates an empty environment. 0N/A * @throws NamingException if a naming exception is encountered 0N/A * Initializes the initial context using the supplied environment. 0N/A * Environment properties are discussed in the class description. 0N/A * <p> This method will modify <tt>environment</tt> and save 0N/A * a reference to it. The caller may no longer modify it. 0N/A * @param environment 0N/A * environment used to create the initial context. 0N/A * Null indicates an empty environment. 0N/A * @throws NamingException if a naming exception is encountered 0N/A * @see #InitialContext(boolean) 0N/A // user has specified initial context factory; try to get it 0N/A * A static method to retrieve the named object. 0N/A * This is a shortcut method equivalent to invoking: 0N/A * InitialContext ic = new InitialContext(); 0N/A * Object obj = ic.lookup(); 0N/A * <p> If <tt>name</tt> is empty, returns a new instance of this context 0N/A * (which represents the same naming context as this context, but its 0N/A * environment may be modified independently and it may be accessed 0N/A * the name of the object to look up 0N/A * @return the object bound to <tt>name</tt> 0N/A * @throws NamingException if a naming exception is encountered 0N/A * @see #doLookup(String) 0N/A * @see #lookup(Name) 0N/A * A static method to retrieve the named object. 0N/A * See {@link #doLookup(Name)} for details. 0N/A * the name of the object to look up 0N/A * @return the object bound to <tt>name</tt> 0N/A * @throws NamingException if a naming exception is encountered 0N/A * Retrieves the initial context by calling 0N/A * <code>NamingManager.getInitialContext()</code> 0N/A * and cache it in defaultInitCtx. 0N/A * Set <code>gotDefault</code> so that we know we've tried this before. 0N/A * @return The non-null cached initial context. 0N/A * @exception NoInitialContextException If cannot find an initial context. 0N/A * @exception NamingException If a naming exception was encountered. 0N/A * Retrieves a context for resolving the string name <code>name</code>. 0N/A * If <code>name</code> name is a URL string, then attempt 0N/A * to find a URL context for it. If none is found, or if 0N/A * <code>name</code> is not a URL string, then return 0N/A * <code>getDefaultInitCtx()</code>. 0N/A * See getURLOrDefaultInitCtx(Name) for description 0N/A * of how a subclass should use this method. 0N/A * @param name The non-null name for which to get the context. 0N/A * @return A URL context for <code>name</code> or the cached 0N/A * initial context. The result cannot be null. 0N/A * @exception NoInitialContextException If cannot find an initial context. 0N/A * @exception NamingException In a naming exception is encountered. 0N/A * @see javax.naming.spi.NamingManager#getURLContext 0N/A * Retrieves a context for resolving <code>name</code>. 0N/A * If the first component of <code>name</code> name is a URL string, 0N/A * then attempt to find a URL context for it. If none is found, or if 0N/A * the first component of <code>name</code> is not a URL string, 0N/A * then return <code>getDefaultInitCtx()</code>. 0N/A * When creating a subclass of InitialContext, use this method as 0N/A * Define a new method that uses this method to get an initial 0N/A * context of the desired subclass. 0N/A * <p><blockquote><pre> 0N/A * protected XXXContext getURLOrDefaultInitXXXCtx(Name name) 0N/A * throws NamingException { 0N/A * Context answer = getURLOrDefaultInitCtx(name); 0N/A * if (!(answer instanceof XXXContext)) { 0N/A * if (answer == null) { 0N/A * throw new NoInitialContextException(); 0N/A * throw new NotContextException("Not an XXXContext"); 0N/A * return (XXXContext)answer; 0N/A * </pre></blockquote> 0N/A * When providing implementations for the new methods in the subclass, 0N/A * use this newly defined method to get the initial context. 0N/A * <p><blockquote><pre> 0N/A * public Object XXXMethod1(Name name, ...) { 0N/A * throws NamingException { 0N/A * return getURLOrDefaultInitXXXCtx(name).XXXMethod1(name, ...); 0N/A * </pre></blockquote> 0N/A * @param name The non-null name for which to get the context. 0N/A * @return A URL context for <code>name</code> or the cached 0N/A * initial context. The result cannot be null. 0N/A * @exception NoInitialContextException If cannot find an initial context. 0N/A * @exception NamingException In a naming exception is encountered. 0N/A * @see javax.naming.spi.NamingManager#getURLContext 0N/A// Most Javadoc is deferred to the Context interface. 0N/A * Composes the name of this context with a name relative to 0N/A * Since an initial context may never be named relative 0N/A * to any context other than itself, the value of the 0N/A * <tt>prefix</tt> parameter must be an empty name (<tt>""</tt>). 0N/A * Composes the name of this context with a name relative to 0N/A * Since an initial context may never be named relative 0N/A * to any context other than itself, the value of the 0N/A * <tt>prefix</tt> parameter must be an empty name.