0N/A/*
2362N/A * Copyright (c) 1999, 2009, Oracle and/or its affiliates. All rights reserved.
0N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
0N/A *
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
2362N/A * published by the Free Software Foundation. Oracle designates this
0N/A * particular file as subject to the "Classpath" exception as provided
2362N/A * by Oracle in the LICENSE file that accompanied this code.
0N/A *
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 *
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 *
2362N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
2362N/A * or visit www.oracle.com if you need additional information or have any
2362N/A * questions.
0N/A */
0N/A
0N/Apackage javax.naming;
0N/A
0N/Aimport java.util.Hashtable;
0N/Aimport javax.naming.spi.NamingManager;
0N/Aimport com.sun.naming.internal.ResourceManager;
0N/A
0N/A/**
0N/A * This class is the starting context for performing naming operations.
0N/A *<p>
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 *<p>
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 * <a href=Context.html#RESOURCEFILES>application resource files</a>.
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 * <a href=Context.html#field_detail><tt>Context</tt></a> and
0N/A * <a href=ldap/LdapContext.html#field_detail><tt>LdapContext</tt></a>
0N/A * interface documentation.
0N/A *<p>
0N/A * JNDI determines each property's value by merging
0N/A * the values from the following two sources, in order:
0N/A * <ol>
0N/A * <li>
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 * <li>
0N/A * The application resource files (<tt>jndi.properties</tt>).
0N/A * </ol>
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 * factories (see <a href=Context.html#LISTPROPS><tt>Context</tt></a>),
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 *
0N/A *<p>
0N/A * The initial context implementation is determined at runtime.
0N/A * The default policy uses the environment property
0N/A * "{@link Context#INITIAL_CONTEXT_FACTORY java.naming.factory.initial}",
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 * below.
0N/A *<p>
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>"java.naming.factory.initial"</tt> is used. Similarly, when a
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 *<p>
0N/A * This default policy of locating the initial context and URL context
0N/A * factories may be overridden
0N/A * by calling
0N/A * <tt>NamingManager.setInitialContextFactoryBuilder()</tt>.
0N/A *<p>
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 *<p>
0N/A * When the environment property "java.naming.factory.initial" is
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 *<p>
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 *
0N/A * @author Rosanna Lee
0N/A * @author Scott Seligman
0N/A *
0N/A * @see Context
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 */
0N/A
0N/Apublic class InitialContext implements Context {
0N/A
0N/A /**
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 */
0N/A protected Hashtable<Object,Object> myProps = null;
0N/A
0N/A /**
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 */
0N/A protected Context defaultInitCtx = null;
0N/A
0N/A /**
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 */
0N/A protected boolean gotDefault = false;
0N/A
0N/A /**
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 *
0N/A * @param lazy
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 *
0N/A * @see #init(Hashtable)
0N/A * @since 1.3
0N/A */
0N/A protected InitialContext(boolean lazy) throws NamingException {
0N/A if (!lazy) {
0N/A init(null);
0N/A }
0N/A }
0N/A
0N/A /**
0N/A * Constructs an initial context.
0N/A * No environment properties are supplied.
0N/A * Equivalent to <tt>new InitialContext(null)</tt>.
0N/A *
0N/A * @throws NamingException if a naming exception is encountered
0N/A *
0N/A * @see #InitialContext(Hashtable)
0N/A */
0N/A public InitialContext() throws NamingException {
0N/A init(null);
0N/A }
0N/A
0N/A /**
0N/A * Constructs an initial context using the supplied environment.
0N/A * Environment properties are discussed in the class description.
0N/A *
0N/A * <p> This constructor will not modify <tt>environment</tt>
0N/A * or save a reference to it, but may save a clone.
1954N/A * Caller should not modify mutable keys and values in
1954N/A * <tt>environment</tt> after it has been passed to the constructor.
0N/A *
0N/A * @param environment
0N/A * environment used to create the initial context.
0N/A * Null indicates an empty environment.
0N/A *
0N/A * @throws NamingException if a naming exception is encountered
0N/A */
0N/A public InitialContext(Hashtable<?,?> environment)
0N/A throws NamingException
0N/A {
0N/A if (environment != null) {
0N/A environment = (Hashtable)environment.clone();
0N/A }
0N/A init(environment);
0N/A }
0N/A
0N/A /**
0N/A * Initializes the initial context using the supplied environment.
0N/A * Environment properties are discussed in the class description.
0N/A *
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 *
0N/A * @param environment
0N/A * environment used to create the initial context.
0N/A * Null indicates an empty environment.
0N/A *
0N/A * @throws NamingException if a naming exception is encountered
0N/A *
0N/A * @see #InitialContext(boolean)
0N/A * @since 1.3
0N/A */
0N/A protected void init(Hashtable<?,?> environment)
0N/A throws NamingException
0N/A {
0N/A myProps = ResourceManager.getInitialEnvironment(environment);
0N/A
0N/A if (myProps.get(Context.INITIAL_CONTEXT_FACTORY) != null) {
0N/A // user has specified initial context factory; try to get it
0N/A getDefaultInitCtx();
0N/A }
0N/A }
0N/A
0N/A /**
0N/A * A static method to retrieve the named object.
0N/A * This is a shortcut method equivalent to invoking:
0N/A * <p>
0N/A * <code>
0N/A * InitialContext ic = new InitialContext();
0N/A * Object obj = ic.lookup();
0N/A * </code>
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 * concurrently).
0N/A *
0N/A * @param name
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 *
0N/A * @see #doLookup(String)
0N/A * @see #lookup(Name)
0N/A * @since 1.6
0N/A */
0N/A public static <T> T doLookup(Name name)
0N/A throws NamingException {
0N/A return (T) (new InitialContext()).lookup(name);
0N/A }
0N/A
0N/A /**
0N/A * A static method to retrieve the named object.
0N/A * See {@link #doLookup(Name)} for details.
0N/A * @param name
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 * @since 1.6
0N/A */
0N/A public static <T> T doLookup(String name)
0N/A throws NamingException {
0N/A return (T) (new InitialContext()).lookup(name);
0N/A }
0N/A
0N/A private static String getURLScheme(String str) {
0N/A int colon_posn = str.indexOf(':');
0N/A int slash_posn = str.indexOf('/');
0N/A
0N/A if (colon_posn > 0 && (slash_posn == -1 || colon_posn < slash_posn))
0N/A return str.substring(0, colon_posn);
0N/A return null;
0N/A }
0N/A
0N/A /**
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 */
0N/A protected Context getDefaultInitCtx() throws NamingException{
0N/A if (!gotDefault) {
0N/A defaultInitCtx = NamingManager.getInitialContext(myProps);
0N/A gotDefault = true;
0N/A }
0N/A if (defaultInitCtx == null)
0N/A throw new NoInitialContextException();
0N/A
0N/A return defaultInitCtx;
0N/A }
0N/A
0N/A /**
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 *<p>
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 */
0N/A protected Context getURLOrDefaultInitCtx(String name)
0N/A throws NamingException {
0N/A if (NamingManager.hasInitialContextFactoryBuilder()) {
0N/A return getDefaultInitCtx();
0N/A }
0N/A String scheme = getURLScheme(name);
0N/A if (scheme != null) {
0N/A Context ctx = NamingManager.getURLContext(scheme, myProps);
0N/A if (ctx != null) {
0N/A return ctx;
0N/A }
0N/A }
0N/A return getDefaultInitCtx();
0N/A }
0N/A
0N/A /**
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 *<p>
0N/A * When creating a subclass of InitialContext, use this method as
0N/A * follows.
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 * } else {
0N/A * throw new NotContextException("Not an XXXContext");
0N/A * }
0N/A * }
0N/A * return (XXXContext)answer;
0N/A * }
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 * }
0N/A * </pre></blockquote>
0N/A *
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 *
0N/A * @see javax.naming.spi.NamingManager#getURLContext
0N/A */
0N/A protected Context getURLOrDefaultInitCtx(Name name)
0N/A throws NamingException {
0N/A if (NamingManager.hasInitialContextFactoryBuilder()) {
0N/A return getDefaultInitCtx();
0N/A }
0N/A if (name.size() > 0) {
0N/A String first = name.get(0);
0N/A String scheme = getURLScheme(first);
0N/A if (scheme != null) {
0N/A Context ctx = NamingManager.getURLContext(scheme, myProps);
0N/A if (ctx != null) {
0N/A return ctx;
0N/A }
0N/A }
0N/A }
0N/A return getDefaultInitCtx();
0N/A }
0N/A
0N/A// Context methods
0N/A// Most Javadoc is deferred to the Context interface.
0N/A
0N/A public Object lookup(String name) throws NamingException {
0N/A return getURLOrDefaultInitCtx(name).lookup(name);
0N/A }
0N/A
0N/A public Object lookup(Name name) throws NamingException {
0N/A return getURLOrDefaultInitCtx(name).lookup(name);
0N/A }
0N/A
0N/A public void bind(String name, Object obj) throws NamingException {
0N/A getURLOrDefaultInitCtx(name).bind(name, obj);
0N/A }
0N/A
0N/A public void bind(Name name, Object obj) throws NamingException {
0N/A getURLOrDefaultInitCtx(name).bind(name, obj);
0N/A }
0N/A
0N/A public void rebind(String name, Object obj) throws NamingException {
0N/A getURLOrDefaultInitCtx(name).rebind(name, obj);
0N/A }
0N/A
0N/A public void rebind(Name name, Object obj) throws NamingException {
0N/A getURLOrDefaultInitCtx(name).rebind(name, obj);
0N/A }
0N/A
0N/A public void unbind(String name) throws NamingException {
0N/A getURLOrDefaultInitCtx(name).unbind(name);
0N/A }
0N/A
0N/A public void unbind(Name name) throws NamingException {
0N/A getURLOrDefaultInitCtx(name).unbind(name);
0N/A }
0N/A
0N/A public void rename(String oldName, String newName) throws NamingException {
0N/A getURLOrDefaultInitCtx(oldName).rename(oldName, newName);
0N/A }
0N/A
0N/A public void rename(Name oldName, Name newName)
0N/A throws NamingException
0N/A {
0N/A getURLOrDefaultInitCtx(oldName).rename(oldName, newName);
0N/A }
0N/A
0N/A public NamingEnumeration<NameClassPair> list(String name)
0N/A throws NamingException
0N/A {
0N/A return (getURLOrDefaultInitCtx(name).list(name));
0N/A }
0N/A
0N/A public NamingEnumeration<NameClassPair> list(Name name)
0N/A throws NamingException
0N/A {
0N/A return (getURLOrDefaultInitCtx(name).list(name));
0N/A }
0N/A
0N/A public NamingEnumeration<Binding> listBindings(String name)
0N/A throws NamingException {
0N/A return getURLOrDefaultInitCtx(name).listBindings(name);
0N/A }
0N/A
0N/A public NamingEnumeration<Binding> listBindings(Name name)
0N/A throws NamingException {
0N/A return getURLOrDefaultInitCtx(name).listBindings(name);
0N/A }
0N/A
0N/A public void destroySubcontext(String name) throws NamingException {
0N/A getURLOrDefaultInitCtx(name).destroySubcontext(name);
0N/A }
0N/A
0N/A public void destroySubcontext(Name name) throws NamingException {
0N/A getURLOrDefaultInitCtx(name).destroySubcontext(name);
0N/A }
0N/A
0N/A public Context createSubcontext(String name) throws NamingException {
0N/A return getURLOrDefaultInitCtx(name).createSubcontext(name);
0N/A }
0N/A
0N/A public Context createSubcontext(Name name) throws NamingException {
0N/A return getURLOrDefaultInitCtx(name).createSubcontext(name);
0N/A }
0N/A
0N/A public Object lookupLink(String name) throws NamingException {
0N/A return getURLOrDefaultInitCtx(name).lookupLink(name);
0N/A }
0N/A
0N/A public Object lookupLink(Name name) throws NamingException {
0N/A return getURLOrDefaultInitCtx(name).lookupLink(name);
0N/A }
0N/A
0N/A public NameParser getNameParser(String name) throws NamingException {
0N/A return getURLOrDefaultInitCtx(name).getNameParser(name);
0N/A }
0N/A
0N/A public NameParser getNameParser(Name name) throws NamingException {
0N/A return getURLOrDefaultInitCtx(name).getNameParser(name);
0N/A }
0N/A
0N/A /**
0N/A * Composes the name of this context with a name relative to
0N/A * this context.
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 */
0N/A public String composeName(String name, String prefix)
0N/A throws NamingException {
0N/A return name;
0N/A }
0N/A
0N/A /**
0N/A * Composes the name of this context with a name relative to
0N/A * this context.
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.
0N/A */
0N/A public Name composeName(Name name, Name prefix)
0N/A throws NamingException
0N/A {
0N/A return (Name)name.clone();
0N/A }
0N/A
0N/A public Object addToEnvironment(String propName, Object propVal)
0N/A throws NamingException {
0N/A myProps.put(propName, propVal);
0N/A return getDefaultInitCtx().addToEnvironment(propName, propVal);
0N/A }
0N/A
0N/A public Object removeFromEnvironment(String propName)
0N/A throws NamingException {
0N/A myProps.remove(propName);
0N/A return getDefaultInitCtx().removeFromEnvironment(propName);
0N/A }
0N/A
0N/A public Hashtable<?,?> getEnvironment() throws NamingException {
0N/A return getDefaultInitCtx().getEnvironment();
0N/A }
0N/A
0N/A public void close() throws NamingException {
0N/A myProps = null;
0N/A if (defaultInitCtx != null) {
0N/A defaultInitCtx.close();
0N/A defaultInitCtx = null;
0N/A }
0N/A gotDefault = false;
0N/A }
0N/A
0N/A public String getNameInNamespace() throws NamingException {
0N/A return getDefaultInitCtx().getNameInNamespace();
0N/A }
0N/A};