https://openjdk.java.net/ 
/*
 * Copyright (c) 1999, 2012, 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.spi;

import java.util.Enumeration;
import java.util.Hashtable;
import java.util.StringTokenizer;
import java.net.MalformedURLException;

import javax.naming.*;
import com.sun.naming.internal.VersionHelper;
import com.sun.naming.internal.ResourceManager;
import com.sun.naming.internal.FactoryEnumeration;


This class contains methods for creating context objects
and objects referred to by location information in the naming
or directory service.


This class cannot be instantiated.  It has only static methods.


The mention of URL in the documentation for this class refers to
a URL string as defined by RFC 1738 and its related RFCs. It is
any string that conforms to the syntax described therein, and
may not always have corresponding support in the java.net.URL
class or Web browsers.


NamingManager is safe for concurrent access by multiple threads.


Except as otherwise noted,
a Name 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.

Author:Rosanna Lee, Scott Seligman
Since:1.3
/**
 * This class contains methods for creating context objects
 * and objects referred to by location information in the naming
 * or directory service.
 *<p>
 * This class cannot be instantiated.  It has only static methods.
 *<p>
 * The mention of URL in the documentation for this class refers to
 * a URL string as defined by RFC 1738 and its related RFCs. It is
 * any string that conforms to the syntax described therein, and
 * may not always have corresponding support in the java.net.URL
 * class or Web browsers.
 *<p>
 * NamingManager is safe for concurrent access by multiple threads.
 *<p>
 * Except as otherwise noted,
 * a <tt>Name</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.
 *
 * @author Rosanna Lee
 * @author Scott Seligman
 * @since 1.3
 */

public class NamingManager {

    /*
     * Disallow anyone from creating one of these.
     * Made package private so that DirectoryManager can subclass.
     */

    NamingManager() {}

    // should be protected and package private
    static final VersionHelper helper = VersionHelper.getVersionHelper();

// --------- object factory stuff

    
Package-private; used by DirectoryManager and NamingManager.

/**
     * Package-private; used by DirectoryManager and NamingManager.
     */
    private static ObjectFactoryBuilder object_factory_builder = null;

    
The ObjectFactoryBuilder determines the policy used when
trying to load object factories.
See getObjectInstance() and class ObjectFactory for a description
of the default policy.
setObjectFactoryBuilder() overrides this default policy by installing
an ObjectFactoryBuilder. Subsequent object factories will
be loaded and created using the installed builder.


The builder can only be installed if the executing thread is allowed
(by the security manager's checkSetFactory() method) to do so.
Once installed, the builder cannot be replaced.



Params:
  • builder – The factory builder to install. If null, no builder
                 is installed.
Throws:
See Also:
/**
     * The ObjectFactoryBuilder determines the policy used when
     * trying to load object factories.
     * See getObjectInstance() and class ObjectFactory for a description
     * of the default policy.
     * setObjectFactoryBuilder() overrides this default policy by installing
     * an ObjectFactoryBuilder. Subsequent object factories will
     * be loaded and created using the installed builder.
     *<p>
     * The builder can only be installed if the executing thread is allowed
     * (by the security manager's checkSetFactory() method) to do so.
     * Once installed, the builder cannot be replaced.
     *<p>
     * @param builder The factory builder to install. If null, no builder
     *                  is installed.
     * @exception SecurityException builder cannot be installed
     *          for security reasons.
     * @exception NamingException builder cannot be installed for
     *         a non-security-related reason.
     * @exception IllegalStateException If a factory has already been installed.
     * @see #getObjectInstance
     * @see ObjectFactory
     * @see ObjectFactoryBuilder
     * @see java.lang.SecurityManager#checkSetFactory
     */
    public static synchronized void setObjectFactoryBuilder(
            ObjectFactoryBuilder builder) throws NamingException {
        if (object_factory_builder != null)
            throw new IllegalStateException("ObjectFactoryBuilder already set");

        SecurityManager security = System.getSecurityManager();
        if (security != null) {
            security.checkSetFactory();
        }
        object_factory_builder = builder;
    }

    
Used for accessing object factory builder.

/**
     * Used for accessing object factory builder.
     */
    static synchronized ObjectFactoryBuilder getObjectFactoryBuilder() {
        return object_factory_builder;
    }


    
Retrieves the ObjectFactory for the object identified by a reference,
using the reference's factory class name and factory codebase
to load in the factory's class.

Params:
  • ref – The non-null reference to use.
  • factoryName – The non-null class name of the factory.
Returns:The object factory for the object identified by ref; null
if unable to load the factory.
/**
     * Retrieves the ObjectFactory for the object identified by a reference,
     * using the reference's factory class name and factory codebase
     * to load in the factory's class.
     * @param ref The non-null reference to use.
     * @param factoryName The non-null class name of the factory.
     * @return The object factory for the object identified by ref; null
     * if unable to load the factory.
     */
    static ObjectFactory getObjectFactoryFromReference(
        Reference ref, String factoryName)
        throws IllegalAccessException,
        InstantiationException,
        MalformedURLException {
        Class<?> clas = null;

        // Try to use current class loader
        try {
             clas = helper.loadClass(factoryName);
        } catch (ClassNotFoundException e) {
            // ignore and continue
            // e.printStackTrace();
        }
        // All other exceptions are passed up.

        // Not in class path; try to use codebase
        String codebase;
        if (clas == null &&
                (codebase = ref.getFactoryClassLocation()) != null) {
            try {
                clas = helper.loadClass(factoryName, codebase);
            } catch (ClassNotFoundException e) {
            }
        }

        return (clas != null) ? (ObjectFactory) clas.newInstance() : null;
    }


    
Creates an object using the factories specified in the
Context.OBJECT_FACTORIES property of the environment
or of the provider resource file associated with nameCtx.

Returns:factory created; null if cannot create
/**
     * Creates an object using the factories specified in the
     * <tt>Context.OBJECT_FACTORIES</tt> property of the environment
     * or of the provider resource file associated with <tt>nameCtx</tt>.
     *
     * @return factory created; null if cannot create
     */
    private static Object createObjectFromFactories(Object obj, Name name,
            Context nameCtx, Hashtable<?,?> environment) throws Exception {

        FactoryEnumeration factories = ResourceManager.getFactories(
            Context.OBJECT_FACTORIES, environment, nameCtx);

        if (factories == null)
            return null;

        // Try each factory until one succeeds
        ObjectFactory factory;
        Object answer = null;
        while (answer == null && factories.hasMore()) {
            factory = (ObjectFactory)factories.next();
            answer = factory.getObjectInstance(obj, name, nameCtx, environment);
        }
        return answer;
    }

    private static String getURLScheme(String str) {
        int colon_posn = str.indexOf(':');
        int slash_posn = str.indexOf('/');

        if (colon_posn > 0 && (slash_posn == -1 || colon_posn < slash_posn))
            return str.substring(0, colon_posn);
        return null;
    }

    
Creates an instance of an object for the specified object
and environment.


If an object factory builder has been installed, it is used to
create a factory for creating the object.
Otherwise, the following rules are used to create the object:

    

  1. If refInfo is a Reference
   or Referenceable containing a factory class name,
   use the named factory to create the object.
   Return refInfo if the factory cannot be created.
   Under JDK 1.1, if the factory class must be loaded from a location
   specified in the reference, a SecurityManager must have
   been installed or the factory creation will fail.
   If an exception is encountered while creating the factory,
   it is passed up to the caller.

  2. If refInfo is a Reference or
   Referenceable with no factory class name,
   and the address or addresses are StringRefAddrs with
   address type "URL",
   try the URL context factory corresponding to each URL's scheme id
   to create the object (see getURLContext()).
   If that fails, continue to the next step.

  3.  Use the object factories specified in
   the Context.OBJECT_FACTORIES property of the environment,
   and of the provider resource file associated with
   nameCtx, in that order.
   The value of this property is a colon-separated list of factory
   class names that are tried in order, and the first one that succeeds
   in creating an object is the one used.
   If none of the factories can be loaded,
   return refInfo.
   If an exception is encountered while creating the object, the
   exception is passed up to the caller.




Service providers that implement the DirContext
interface should use
DirectoryManager.getObjectInstance(), not this method.
Service providers that implement only the Context
interface should use this method.


Note that an object factory (an object that implements the ObjectFactory
interface) must be public and must have a public constructor that
accepts no arguments.


The name and nameCtx parameters may
optionally be used to specify the name of the object being created.
name is the name of the object, relative to context
nameCtx.  This information could be useful to the object
factory or to the object implementation.
 If there are several possible contexts from which the object
 could be named -- as will often be the case -- it is up to
 the caller to select one.  A good rule of thumb is to select the
"deepest" context available.
If nameCtx is null, name is relative
to the default initial context.  If no name is being specified, the
name parameter should be null.

Params:
  • refInfo – The possibly null object for which to create an object.
  • name – The name of this object relative to nameCtx.
         Specifying a name is optional; if it is
         omitted, name should be null.
  • nameCtx – The context relative to which the name
         parameter is specified.  If null, name is
         relative to the default initial context.
  • environment – The possibly null environment to
         be used in the creation of the object factory and the object.
Throws:
  • 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 – 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 ObjectFactory.getObjectInstance().
See Also:
Returns:An object created using refInfo; or
         refInfo if an object cannot be created using
         the algorithm described above.
/**
     * Creates an instance of an object for the specified object
     * and environment.
     * <p>
     * If an object factory builder has been installed, it is used to
     * create a factory for creating the object.
     * Otherwise, the following rules are used to create the object:
     *<ol>
     * <li>If <code>refInfo</code> is a <code>Reference</code>
     *    or <code>Referenceable</code> containing a factory class name,
     *    use the named factory to create the object.
     *    Return <code>refInfo</code> if the factory cannot be created.
     *    Under JDK 1.1, if the factory class must be loaded from a location
     *    specified in the reference, a <tt>SecurityManager</tt> must have
     *    been installed or the factory creation will fail.
     *    If an exception is encountered while creating the factory,
     *    it is passed up to the caller.
     * <li>If <tt>refInfo</tt> is a <tt>Reference</tt> or
     *    <tt>Referenceable</tt> with no factory class name,
     *    and the address or addresses are <tt>StringRefAddr</tt>s with
     *    address type "URL",
     *    try the URL context factory corresponding to each URL's scheme id
     *    to create the object (see <tt>getURLContext()</tt>).
     *    If that fails, continue to the next step.
     * <li> Use the object factories specified in
     *    the <tt>Context.OBJECT_FACTORIES</tt> property of the environment,
     *    and of the provider resource file associated with
     *    <tt>nameCtx</tt>, in that order.
     *    The value of this property is a colon-separated list of factory
     *    class names that are tried in order, and the first one that succeeds
     *    in creating an object is the one used.
     *    If none of the factories can be loaded,
     *    return <code>refInfo</code>.
     *    If an exception is encountered while creating the object, the
     *    exception is passed up to the caller.
     *</ol>
     *<p>
     * Service providers that implement the <tt>DirContext</tt>
     * interface should use
     * <tt>DirectoryManager.getObjectInstance()</tt>, not this method.
     * Service providers that implement only the <tt>Context</tt>
     * interface should use this method.
     * <p>
     * Note that an object factory (an object that implements the ObjectFactory
     * interface) must be public and must have a public constructor that
     * accepts no arguments.
     * <p>
     * The <code>name</code> and <code>nameCtx</code> parameters may
     * optionally be used to specify the name of the object being created.
     * <code>name</code> is the name of the object, relative to context
     * <code>nameCtx</code>.  This information could be useful to the object
     * factory or to the object implementation.
     *  If there are several possible contexts from which the object
     *  could be named -- as will often be the case -- it is up to
     *  the caller to select one.  A good rule of thumb is to select the
     * "deepest" context available.
     * If <code>nameCtx</code> is null, <code>name</code> is relative
     * to the default initial context.  If no name is being specified, the
     * <code>name</code> parameter should be null.
     *
     * @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.
     * @return An object created using <code>refInfo</code>; or
     *          <code>refInfo</code> if an object cannot be created using
     *          the algorithm described above.
     * @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 ObjectFactory.getObjectInstance().
     * @see #getURLContext
     * @see ObjectFactory
     * @see ObjectFactory#getObjectInstance
     */
    public static Object
        getObjectInstance(Object refInfo, Name name, Context nameCtx,
                          Hashtable<?,?> environment)
        throws Exception
    {

        ObjectFactory factory;

        // Use builder if installed
        ObjectFactoryBuilder builder = getObjectFactoryBuilder();
        if (builder != null) {
            // builder must return non-null factory
            factory = builder.createObjectFactory(refInfo, environment);
            return factory.getObjectInstance(refInfo, name, nameCtx,
                environment);
        }

        // Use reference if possible
        Reference ref = null;
        if (refInfo instanceof Reference) {
            ref = (Reference) refInfo;
        } else if (refInfo instanceof Referenceable) {
            ref = ((Referenceable)(refInfo)).getReference();
        }

        Object answer;

        if (ref != null) {
            String f = ref.getFactoryClassName();
            if (f != null) {
                // if reference identifies a factory, use exclusively

                factory = getObjectFactoryFromReference(ref, f);
                if (factory != null) {
                    return factory.getObjectInstance(ref, name, nameCtx,
                                                     environment);
                }
                // 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
                return refInfo;

            } else {
                // if reference has no factory, check for addresses
                // containing URLs

                answer = processURLAddrs(ref, name, nameCtx, environment);
                if (answer != null) {
                    return answer;
                }
            }
        }

        // try using any specified factories
        answer =
            createObjectFromFactories(refInfo, name, nameCtx, environment);
        return (answer != null) ? answer : refInfo;
    }

    /*
     * Ref has no factory.  For each address of type "URL", try its URL
     * context factory.  Returns null if unsuccessful in creating and
     * invoking a factory.
     */
    static Object processURLAddrs(Reference ref, Name name, Context nameCtx,
                                  Hashtable<?,?> environment)
            throws NamingException {

        for (int i = 0; i < ref.size(); i++) {
            RefAddr addr = ref.get(i);
            if (addr instanceof StringRefAddr &&
                addr.getType().equalsIgnoreCase("URL")) {

                String url = (String)addr.getContent();
                Object answer = processURL(url, name, nameCtx, environment);
                if (answer != null) {
                    return answer;
                }
            }
        }
        return null;
    }

    private static Object processURL(Object refInfo, Name name,
                                     Context nameCtx, Hashtable<?,?> environment)
            throws NamingException {
        Object answer;

        // If refInfo is a URL string, try to use its URL context factory
        // If no context found, continue to try object factories.
        if (refInfo instanceof String) {
            String url = (String)refInfo;
            String scheme = getURLScheme(url);
            if (scheme != null) {
                answer = getURLObject(scheme, refInfo, name, nameCtx,
                                      environment);
                if (answer != null) {
                    return answer;
                }
            }
        }

        // If refInfo is an array of URL strings,
        // try to find a context factory for any one of its URLs.
        // If no context found, continue to try object factories.
        if (refInfo instanceof String[]) {
            String[] urls = (String[])refInfo;
            for (int i = 0; i <urls.length; i++) {
                String scheme = getURLScheme(urls[i]);
                if (scheme != null) {
                    answer = getURLObject(scheme, refInfo, name, nameCtx,
                                          environment);
                    if (answer != null)
                        return answer;
                }
            }
        }
        return null;
    }


    
Retrieves a context identified by obj, using the specified
environment.
Used by ContinuationContext.

Params:
  • obj –       The object identifying the context.
  • name –      The name of the context being returned, relative to
                 nameCtx, or null if no name is being
                 specified.
                 See the getObjectInstance method for
                 details.
  • nameCtx –   The context relative to which name is
                 specified, or null for the default initial context.
                 See the getObjectInstance method for
                 details.
  • environment – Environment specifying characteristics of the
                 resulting context.
See Also:
Returns:A context identified by obj.
/**
     * Retrieves a context identified by <code>obj</code>, using the specified
     * environment.
     * Used by ContinuationContext.
     *
     * @param obj       The object identifying the context.
     * @param name      The name of the context being returned, relative to
     *                  <code>nameCtx</code>, or null if no name is being
     *                  specified.
     *                  See the <code>getObjectInstance</code> method for
     *                  details.
     * @param nameCtx   The context relative to which <code>name</code> is
     *                  specified, or null for the default initial context.
     *                  See the <code>getObjectInstance</code> method for
     *                  details.
     * @param environment Environment specifying characteristics of the
     *                  resulting context.
     * @return A context identified by <code>obj</code>.
     *
     * @see #getObjectInstance
     */
    static Context getContext(Object obj, Name name, Context nameCtx,
                              Hashtable<?,?> environment) throws NamingException {
        Object answer;

        if (obj instanceof Context) {
            // %%% Ignore environment for now.  OK since method not public.
            return (Context)obj;
        }

        try {
            answer = getObjectInstance(obj, name, nameCtx, environment);
        } catch (NamingException e) {
            throw e;
        } catch (Exception e) {
            NamingException ne = new NamingException();
            ne.setRootCause(e);
            throw ne;
        }

        return (answer instanceof Context)
            ? (Context)answer
            : null;
    }

    // Used by ContinuationContext
    static Resolver getResolver(Object obj, Name name, Context nameCtx,
                                Hashtable<?,?> environment) throws NamingException {
        Object answer;

        if (obj instanceof Resolver) {
            // %%% Ignore environment for now.  OK since method not public.
            return (Resolver)obj;
        }

        try {
            answer = getObjectInstance(obj, name, nameCtx, environment);
        } catch (NamingException e) {
            throw e;
        } catch (Exception e) {
            NamingException ne = new NamingException();
            ne.setRootCause(e);
            throw ne;
        }

        return (answer instanceof Resolver)
            ? (Resolver)answer
            : null;
    }


    /***************** URL Context implementations ***************/

    
Creates a context for the given URL scheme id.


The resulting context is for resolving URLs of the
scheme scheme. The resulting context is not tied
to a specific URL. It is able to handle arbitrary URLs with
the specified scheme.


The class name of the factory that creates the resulting context
has the naming convention scheme-idURLContextFactory
(e.g. "ftpURLContextFactory" for the "ftp" scheme-id),
in the package specified as follows.
The Context.URL_PKG_PREFIXES environment property (which
may contain values taken from applet parameters, system properties,
or application resource files)
contains a colon-separated list of package prefixes.
Each package prefix in
the property is tried in the order specified to load the factory class.
The default package prefix is "com.sun.jndi.url" (if none of the
specified packages work, this default is tried).
The complete package name is constructed using the package prefix,
concatenated with the scheme id.


For example, if the scheme id is "ldap", and the
Context.URL_PKG_PREFIXES property
contains "com.widget:com.wiz.jndi",
the naming manager would attempt to load the following classes
until one is successfully instantiated:

    

  • com.widget.ldap.ldapURLContextFactory
 
  • com.wiz.jndi.ldap.ldapURLContextFactory
 
  • com.sun.jndi.url.ldap.ldapURLContextFactory


If none of the package prefixes work, null is returned.


If a factory is instantiated, it is invoked with the following
parameters to produce the resulting context.


factory.getObjectInstance(null, environment);


For example, invoking getObjectInstance() as shown above
on a LDAP URL context factory would return a
context that can resolve LDAP urls
(e.g. "ldap://ldap.wiz.com/o=wiz,c=us",
"ldap://ldap.umich.edu/o=umich,c=us", ...).


Note that an object factory (an object that implements the ObjectFactory
interface) must be public and must have a public constructor that
accepts no arguments.

Params:
  • scheme –    The non-null scheme-id of the URLs supported by the context.
  • environment – The possibly null environment properties to be
          used in the creation of the object factory and the context.
Throws:
  • NamingException – If a naming exception occurs while creating
         the context.
See Also:
Returns:A context for resolving URLs with the
        scheme id scheme;
 null if the factory for creating the
        context is not found.
/**
     * Creates a context for the given URL scheme id.
     * <p>
     * The resulting context is for resolving URLs of the
     * scheme <code>scheme</code>. The resulting context is not tied
     * to a specific URL. It is able to handle arbitrary URLs with
     * the specified scheme.
     *<p>
     * The class name of the factory that creates the resulting context
     * has the naming convention <i>scheme-id</i>URLContextFactory
     * (e.g. "ftpURLContextFactory" for the "ftp" scheme-id),
     * in the package specified as follows.
     * The <tt>Context.URL_PKG_PREFIXES</tt> environment property (which
     * may contain values taken from applet parameters, system properties,
     * or application resource files)
     * contains a colon-separated list of package prefixes.
     * Each package prefix in
     * the property is tried in the order specified to load the factory class.
     * The default package prefix is "com.sun.jndi.url" (if none of the
     * specified packages work, this default is tried).
     * The complete package name is constructed using the package prefix,
     * concatenated with the scheme id.
     *<p>
     * For example, if the scheme id is "ldap", and the
     * <tt>Context.URL_PKG_PREFIXES</tt> property
     * contains "com.widget:com.wiz.jndi",
     * the naming manager would attempt to load the following classes
     * until one is successfully instantiated:
     *<ul>
     * <li>com.widget.ldap.ldapURLContextFactory
     *  <li>com.wiz.jndi.ldap.ldapURLContextFactory
     *  <li>com.sun.jndi.url.ldap.ldapURLContextFactory
     *</ul>
     * If none of the package prefixes work, null is returned.
     *<p>
     * If a factory is instantiated, it is invoked with the following
     * parameters to produce the resulting context.
     * <p>
     * <code>factory.getObjectInstance(null, environment);</code>
     * <p>
     * For example, invoking getObjectInstance() as shown above
     * on a LDAP URL context factory would return a
     * context that can resolve LDAP urls
     * (e.g. "ldap://ldap.wiz.com/o=wiz,c=us",
     * "ldap://ldap.umich.edu/o=umich,c=us", ...).
     *<p>
     * Note that an object factory (an object that implements the ObjectFactory
     * interface) must be public and must have a public constructor that
     * accepts no arguments.
     *
     * @param scheme    The non-null scheme-id of the URLs supported by the context.
     * @param environment The possibly null environment properties to be
     *           used in the creation of the object factory and the context.
     * @return A context for resolving URLs with the
     *         scheme id <code>scheme</code>;
     *  <code>null</code> if the factory for creating the
     *         context is not found.
     * @exception NamingException If a naming exception occurs while creating
     *          the context.
     * @see #getObjectInstance
     * @see ObjectFactory#getObjectInstance
     */
    public static Context getURLContext(String scheme,
                                        Hashtable<?,?> environment)
        throws NamingException
    {
        // pass in 'null' to indicate creation of generic context for scheme
        // (i.e. not specific to a URL).

            Object answer = getURLObject(scheme, null, null, null, environment);
            if (answer instanceof Context) {
                return (Context)answer;
            } else {
                return null;
            }
    }

    private static final String defaultPkgPrefix = "com.sun.jndi.url";

    
Creates an object for the given URL scheme id using
the supplied urlInfo.


If urlInfo is null, the result is a context for resolving URLs
with the scheme id 'scheme'.
If urlInfo is a URL, the result is a context named by the URL.
Names passed to this context is assumed to be relative to this
context (i.e. not a URL). For example, if urlInfo is
"ldap://ldap.wiz.com/o=Wiz,c=us", the resulting context will
be that pointed to by "o=Wiz,c=us" on the server 'ldap.wiz.com'.
Subsequent names that can be passed to this context will be
LDAP names relative to this context (e.g. cn="Barbs Jensen").
If urlInfo is an array of URLs, the URLs are assumed
to be equivalent in terms of the context to which they refer.
The resulting context is like that of the single URL case.
If urlInfo is of any other type, that is handled by the
context factory for the URL scheme.

Params:
  • scheme – the URL scheme id for the context
  • urlInfo – information used to create the context
  • name – name of this object relative to nameCtx
  • nameCtx – Context whose provider resource file will be searched
         for package prefix values (or null if none)
  • environment – Environment properties for creating the context
See Also:
/**
     * Creates an object for the given URL scheme id using
     * the supplied urlInfo.
     * <p>
     * If urlInfo is null, the result is a context for resolving URLs
     * with the scheme id 'scheme'.
     * If urlInfo is a URL, the result is a context named by the URL.
     * Names passed to this context is assumed to be relative to this
     * context (i.e. not a URL). For example, if urlInfo is
     * "ldap://ldap.wiz.com/o=Wiz,c=us", the resulting context will
     * be that pointed to by "o=Wiz,c=us" on the server 'ldap.wiz.com'.
     * Subsequent names that can be passed to this context will be
     * LDAP names relative to this context (e.g. cn="Barbs Jensen").
     * If urlInfo is an array of URLs, the URLs are assumed
     * to be equivalent in terms of the context to which they refer.
     * The resulting context is like that of the single URL case.
     * If urlInfo is of any other type, that is handled by the
     * context factory for the URL scheme.
     * @param scheme the URL scheme id for the context
     * @param urlInfo information used to create the context
     * @param name name of this object relative to <code>nameCtx</code>
     * @param nameCtx Context whose provider resource file will be searched
     *          for package prefix values (or null if none)
     * @param environment Environment properties for creating the context
     * @see javax.naming.InitialContext
     */
    private static Object getURLObject(String scheme, Object urlInfo,
                                       Name name, Context nameCtx,
                                       Hashtable<?,?> environment)
            throws NamingException {

        // e.g. "ftpURLContextFactory"
        ObjectFactory factory = (ObjectFactory)ResourceManager.getFactory(
            Context.URL_PKG_PREFIXES, environment, nameCtx,
            "." + scheme + "." + scheme + "URLContextFactory", defaultPkgPrefix);

        if (factory == null)
          return null;

        // Found object factory
        try {
            return factory.getObjectInstance(urlInfo, name, nameCtx, environment);
        } catch (NamingException e) {
            throw e;
        } catch (Exception e) {
            NamingException ne = new NamingException();
            ne.setRootCause(e);
            throw ne;
        }

    }


// ------------ Initial Context Factory Stuff
    private static InitialContextFactoryBuilder initctx_factory_builder = null;

    
Use this method for accessing initctx_factory_builder while
inside an unsynchronized method.

/**
     * Use this method for accessing initctx_factory_builder while
     * inside an unsynchronized method.
     */
    private static synchronized InitialContextFactoryBuilder
    getInitialContextFactoryBuilder() {
        return initctx_factory_builder;
    }

    
Creates an initial context using the specified environment
properties.


If an InitialContextFactoryBuilder has been installed,
it is used to create the factory for creating the initial context.
Otherwise, the class specified in the
Context.INITIAL_CONTEXT_FACTORY environment property is used.
Note that an initial context factory (an object that implements the
InitialContextFactory interface) must be public and must have a
public constructor that accepts no arguments.

Params:
  • env – The possibly null environment properties used when
                 creating the context.
Throws:
  • NoInitialContextException – If the
         Context.INITIAL_CONTEXT_FACTORY property
        is not found or names a nonexistent
        class or a class that cannot be instantiated,
         or if the initial context could not be created for some other
         reason.
  • NamingException – If some other naming exception was encountered.
See Also:
Returns:A non-null initial context.
/**
     * Creates an initial context using the specified environment
     * properties.
     *<p>
     * If an InitialContextFactoryBuilder has been installed,
     * it is used to create the factory for creating the initial context.
     * Otherwise, the class specified in the
     * <tt>Context.INITIAL_CONTEXT_FACTORY</tt> environment property is used.
     * Note that an initial context factory (an object that implements the
     * InitialContextFactory interface) must be public and must have a
     * public constructor that accepts no arguments.
     *
     * @param env The possibly null environment properties used when
     *                  creating the context.
     * @return A non-null initial context.
     * @exception NoInitialContextException If the
     *          <tt>Context.INITIAL_CONTEXT_FACTORY</tt> property
     *         is not found or names a nonexistent
     *         class or a class that cannot be instantiated,
     *          or if the initial context could not be created for some other
     *          reason.
     * @exception NamingException If some other naming exception was encountered.
     * @see javax.naming.InitialContext
     * @see javax.naming.directory.InitialDirContext
     */
    public static Context getInitialContext(Hashtable<?,?> env)
        throws NamingException {
        InitialContextFactory factory;

        InitialContextFactoryBuilder builder = getInitialContextFactoryBuilder();
        if (builder == null) {
            // No factory installed, use property
            // Get initial context factory class name

            String className = env != null ?
                (String)env.get(Context.INITIAL_CONTEXT_FACTORY) : null;
            if (className == null) {
                NoInitialContextException ne = new NoInitialContextException(
                    "Need to specify class name in environment or system " +
                    "property, or as an applet parameter, or in an " +
                    "application resource file:  " +
                    Context.INITIAL_CONTEXT_FACTORY);
                throw ne;
            }

            try {
                factory = (InitialContextFactory)
                    helper.loadClass(className).newInstance();
            } catch(Exception e) {
                NoInitialContextException ne =
                    new NoInitialContextException(
                        "Cannot instantiate class: " + className);
                ne.setRootCause(e);
                throw ne;
            }
        } else {
            factory = builder.createInitialContextFactory(env);
        }

        return factory.getInitialContext(env);
    }


    
Sets the InitialContextFactory builder to be builder.


The builder can only be installed if the executing thread is allowed by
the security manager to do so. Once installed, the builder cannot
be replaced.

Params:
  • builder – The initial context factory builder to install. If null,
               no builder is set.
Throws:
See Also:
/**
     * Sets the InitialContextFactory builder to be builder.
     *
     *<p>
     * The builder can only be installed if the executing thread is allowed by
     * the security manager to do so. Once installed, the builder cannot
     * be replaced.
     * @param builder The initial context factory builder to install. If null,
     *                no builder is set.
     * @exception SecurityException builder cannot be installed for security
     *                  reasons.
     * @exception NamingException builder cannot be installed for
     *         a non-security-related reason.
     * @exception IllegalStateException If a builder was previous installed.
     * @see #hasInitialContextFactoryBuilder
     * @see java.lang.SecurityManager#checkSetFactory
     */
    public static synchronized void setInitialContextFactoryBuilder(
        InitialContextFactoryBuilder builder)
        throws NamingException {
            if (initctx_factory_builder != null)
                throw new IllegalStateException(
                    "InitialContextFactoryBuilder already set");

            SecurityManager security = System.getSecurityManager();
            if (security != null) {
                security.checkSetFactory();
            }
            initctx_factory_builder = builder;
    }

    
Determines whether an initial context factory builder has
been set.

See Also:
Returns:true if an initial context factory builder has
          been set; false otherwise.
/**
     * Determines whether an initial context factory builder has
     * been set.
     * @return true if an initial context factory builder has
     *           been set; false otherwise.
     * @see #setInitialContextFactoryBuilder
     */
    public static boolean hasInitialContextFactoryBuilder() {
        return (getInitialContextFactoryBuilder() != null);
    }

// -----  Continuation Context Stuff

    
Constant that holds the name of the environment property into
which getContinuationContext() stores the value of its
CannotProceedException parameter.
This property is inherited by the continuation context, and may
be used by that context's service provider to inspect the
fields of the exception.


The value of this constant is "java.naming.spi.CannotProceedException".

See Also:
  • getContinuationContext
Since:1.3
/**
     * Constant that holds the name of the environment property into
     * which <tt>getContinuationContext()</tt> stores the value of its
     * <tt>CannotProceedException</tt> parameter.
     * This property is inherited by the continuation context, and may
     * be used by that context's service provider to inspect the
     * fields of the exception.
     *<p>
     * The value of this constant is "java.naming.spi.CannotProceedException".
     *
     * @see #getContinuationContext
     * @since 1.3
     */
    public static final String CPE = "java.naming.spi.CannotProceedException";

    
Creates a context in which to continue a context operation.


In performing an operation on a name that spans multiple
namespaces, a context from one naming system may need to pass
the operation on to the next naming system.  The context
implementation does this by first constructing a
CannotProceedException containing information
pinpointing how far it has proceeded.  It then obtains a
continuation context from JNDI by calling
getContinuationContext.  The context
implementation should then resume the context operation by
invoking the same operation on the continuation context, using
the remainder of the name that has not yet been resolved.


Before making use of the cpe parameter, this method
updates the environment associated with that object by setting
the value of the property CPE
to cpe.  This property will be inherited by the
continuation context, and may be used by that context's
service provider to inspect the fields of this exception.

Params:
  • cpe – 
         The non-null exception that triggered this continuation.
Throws:
Returns:A non-null Context object for continuing the operation.
/**
     * Creates a context in which to continue a context operation.
     *<p>
     * In performing an operation on a name that spans multiple
     * namespaces, a context from one naming system may need to pass
     * the operation on to the next naming system.  The context
     * implementation does this by first constructing a
     * <code>CannotProceedException</code> containing information
     * pinpointing how far it has proceeded.  It then obtains a
     * continuation context from JNDI by calling
     * <code>getContinuationContext</code>.  The context
     * implementation should then resume the context operation by
     * invoking the same operation on the continuation context, using
     * the remainder of the name that has not yet been resolved.
     *<p>
     * Before making use of the <tt>cpe</tt> parameter, this method
     * updates the environment associated with that object by setting
     * the value of the property <a href="#CPE"><tt>CPE</tt></a>
     * to <tt>cpe</tt>.  This property will be inherited by the
     * continuation context, and may be used by that context's
     * service provider to inspect the fields of this exception.
     *
     * @param cpe
     *          The non-null exception that triggered this continuation.
     * @return A non-null Context object for continuing the operation.
     * @exception NamingException If a naming exception occurred.
     */
    @SuppressWarnings("unchecked")
    public static Context getContinuationContext(CannotProceedException cpe)
            throws NamingException {

        Hashtable<Object,Object> env = (Hashtable<Object,Object>)cpe.getEnvironment();
        if (env == null) {
            env = new Hashtable<>(7);
        } else {
            // Make a (shallow) copy of the environment.
            env = (Hashtable<Object,Object>)env.clone();
        }
        env.put(CPE, cpe);

        ContinuationContext cctx = new ContinuationContext(cpe, env);
        return cctx.getTargetContext();
    }

// ------------ State Factory Stuff

    
Retrieves the state of an object for binding.


Service providers that implement the DirContext interface
should use DirectoryManager.getStateToBind(), not this method.
Service providers that implement only the Context interface
should use this method.


This method uses the specified state factories in
the Context.STATE_FACTORIES property from the environment
properties, and from the provider resource file associated with
nameCtx, in that order.
   The value of this property is a colon-separated list of factory
   class names that are tried in order, and the first one that succeeds
   in returning the object's state is the one used.
If no object's state can be retrieved in this way, return the
object itself.
   If an exception is encountered while retrieving the state, the
   exception is passed up to the caller.


Note that a state factory
(an object that implements the StateFactory
interface) must be public and must have a public constructor that
accepts no arguments.


The name and nameCtx parameters may optionally be used to specify the name of the object being created. See the description of "Name and Context Parameters" in 
         ObjectFactory.getObjectInstance() for details. 

This method may return a Referenceable object.  The
service provider obtaining this object may choose to store it
directly, or to extract its reference (using
Referenceable.getReference()) and store that instead.

Params:
  • obj – The non-null object for which to get state to bind.
  • name – The name of this object relative to nameCtx,
         or null if no name is specified.
  • nameCtx – The context relative to which the name
         parameter is specified, or null if name is
         relative to the default initial context.
 @param environment The possibly null environment to
         be used in the creation of the state factory and
 the object's state.
Throws:
  • NamingException – 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 StateFactory.getStateToBind().
See Also:
Returns:The non-null object representing obj's state for
 binding.  It could be the object (obj) itself.
Since:1.3
/**
     * Retrieves the state of an object for binding.
     * <p>
     * Service providers that implement the <tt>DirContext</tt> interface
     * should use <tt>DirectoryManager.getStateToBind()</tt>, not this method.
     * Service providers that implement only the <tt>Context</tt> interface
     * should use this method.
     *<p>
     * This method uses the specified state factories in
     * the <tt>Context.STATE_FACTORIES</tt> property from the environment
     * properties, and from the provider resource file associated with
     * <tt>nameCtx</tt>, in that order.
     *    The value of this property is a colon-separated list of factory
     *    class names that are tried in order, and the first one that succeeds
     *    in returning the object's state is the one used.
     * If no object's state can be retrieved in this way, return the
     * object itself.
     *    If an exception is encountered while retrieving the state, the
     *    exception is passed up to the caller.
     * <p>
     * Note that a state factory
     * (an object that implements the StateFactory
     * interface) must be public and must have a public constructor that
     * accepts no arguments.
     * <p>
     * The <code>name</code> and <code>nameCtx</code> parameters may
     * optionally be used to specify the name of the object being created.
     * See the description of "Name and Context Parameters" in
     * {@link ObjectFactory#getObjectInstance
     *          ObjectFactory.getObjectInstance()}
     * for details.
     * <p>
     * This method may return a <tt>Referenceable</tt> object.  The
     * service provider obtaining this object may choose to store it
     * directly, or to extract its reference (using
     * <tt>Referenceable.getReference()</tt>) and store that instead.
     *
     * @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
     *  the object's state.
     * @return The non-null object representing <tt>obj</tt>'s state for
     *  binding.  It could be the object (<tt>obj</tt>) itself.
     * @exception NamingException 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>StateFactory.getStateToBind()</tt>.
     * @see StateFactory
     * @see StateFactory#getStateToBind
     * @see DirectoryManager#getStateToBind
     * @since 1.3
     */
    public static Object
        getStateToBind(Object obj, Name name, Context nameCtx,
                       Hashtable<?,?> environment)
        throws NamingException
    {

        FactoryEnumeration factories = ResourceManager.getFactories(
            Context.STATE_FACTORIES, environment, nameCtx);

        if (factories == null) {
            return obj;
        }

        // Try each factory until one succeeds
        StateFactory factory;
        Object answer = null;
        while (answer == null && factories.hasMore()) {
            factory = (StateFactory)factories.next();
            answer = factory.getStateToBind(obj, name, nameCtx, environment);
        }

        return (answer != null) ? answer : obj;
    }
}