1 /*
   2  * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package javax.naming.spi;
  27 
  28 import java.util.*;
  29 import java.net.MalformedURLException;
  30 
  31 import javax.naming.*;
  32 import com.sun.naming.internal.VersionHelper;
  33 import com.sun.naming.internal.ResourceManager;
  34 import com.sun.naming.internal.FactoryEnumeration;
  35 
  36 /**
  37  * This class contains methods for creating context objects
  38  * and objects referred to by location information in the naming
  39  * or directory service.
  40  *<p>
  41  * This class cannot be instantiated.  It has only static methods.
  42  *<p>
  43  * The mention of URL in the documentation for this class refers to
  44  * a URL string as defined by RFC 1738 and its related RFCs. It is
  45  * any string that conforms to the syntax described therein, and
  46  * may not always have corresponding support in the java.net.URL
  47  * class or Web browsers.
  48  *<p>
  49  * NamingManager is safe for concurrent access by multiple threads.
  50  *<p>
  51  * Except as otherwise noted,
  52  * a <tt>Name</tt> or environment parameter
  53  * passed to any method is owned by the caller.
  54  * The implementation will not modify the object or keep a reference
  55  * to it, although it may keep a reference to a clone or copy.
  56  *
  57  * @author Rosanna Lee
  58  * @author Scott Seligman
  59  * @since 1.3
  60  */
  61 
  62 public class NamingManager {
  63 
  64     /*
  65      * Disallow anyone from creating one of these.
  66      * Made package private so that DirectoryManager can subclass.
  67      */
  68 
  69     NamingManager() {}
  70 
  71     // should be protected and package private
  72     static final VersionHelper helper = VersionHelper.getVersionHelper();
  73 
  74 // --------- object factory stuff
  75 
  76     /**
  77      * Package-private; used by DirectoryManager and NamingManager.
  78      */
  79     private static ObjectFactoryBuilder object_factory_builder = null;
  80 
  81     /**
  82      * The ObjectFactoryBuilder determines the policy used when
  83      * trying to load object factories.
  84      * See getObjectInstance() and class ObjectFactory for a description
  85      * of the default policy.
  86      * setObjectFactoryBuilder() overrides this default policy by installing
  87      * an ObjectFactoryBuilder. Subsequent object factories will
  88      * be loaded and created using the installed builder.
  89      *<p>
  90      * The builder can only be installed if the executing thread is allowed
  91      * (by the security manager's checkSetFactory() method) to do so.
  92      * Once installed, the builder cannot be replaced.
  93      *
  94      * @param builder The factory builder to install. If null, no builder
  95      *                  is installed.
  96      * @exception SecurityException builder cannot be installed
  97      *          for security reasons.
  98      * @exception NamingException builder cannot be installed for
  99      *         a non-security-related reason.
 100      * @exception IllegalStateException If a factory has already been installed.
 101      * @see #getObjectInstance
 102      * @see ObjectFactory
 103      * @see ObjectFactoryBuilder
 104      * @see java.lang.SecurityManager#checkSetFactory
 105      */
 106     public static synchronized void setObjectFactoryBuilder(
 107             ObjectFactoryBuilder builder) throws NamingException {
 108         if (object_factory_builder != null)
 109             throw new IllegalStateException("ObjectFactoryBuilder already set");
 110 
 111         SecurityManager security = System.getSecurityManager();
 112         if (security != null) {
 113             security.checkSetFactory();
 114         }
 115         object_factory_builder = builder;
 116     }
 117 
 118     /**
 119      * Used for accessing object factory builder.
 120      */
 121     static synchronized ObjectFactoryBuilder getObjectFactoryBuilder() {
 122         return object_factory_builder;
 123     }
 124 
 125 
 126     /**
 127      * Retrieves the ObjectFactory for the object identified by a reference,
 128      * using the reference's factory class name and factory codebase
 129      * to load in the factory's class.
 130      * @param ref The non-null reference to use.
 131      * @param factoryName The non-null class name of the factory.
 132      * @return The object factory for the object identified by ref; null
 133      * if unable to load the factory.
 134      */
 135     static ObjectFactory getObjectFactoryFromReference(
 136         Reference ref, String factoryName)
 137         throws IllegalAccessException,
 138         InstantiationException,
 139         MalformedURLException {
 140         Class<?> clas = null;
 141 
 142         // Try to use current class loader
 143         try {
 144              clas = helper.loadClass(factoryName);
 145         } catch (ClassNotFoundException e) {
 146             // ignore and continue
 147             // e.printStackTrace();
 148         }
 149         // All other exceptions are passed up.
 150 
 151         // Not in class path; try to use codebase
 152         String codebase;
 153         if (clas == null &&
 154                 (codebase = ref.getFactoryClassLocation()) != null) {
 155             try {
 156                 clas = helper.loadClass(factoryName, codebase);
 157             } catch (ClassNotFoundException e) {
 158             }
 159         }
 160 
 161         return (clas != null) ? (ObjectFactory) clas.newInstance() : null;
 162     }
 163 
 164 
 165     /**
 166      * Creates an object using the factories specified in the
 167      * <tt>Context.OBJECT_FACTORIES</tt> property of the environment
 168      * or of the provider resource file associated with <tt>nameCtx</tt>.
 169      *
 170      * @return factory created; null if cannot create
 171      */
 172     private static Object createObjectFromFactories(Object obj, Name name,
 173             Context nameCtx, Hashtable<?,?> environment) throws Exception {
 174 
 175         FactoryEnumeration factories = ResourceManager.getFactories(
 176             Context.OBJECT_FACTORIES, environment, nameCtx);
 177 
 178         if (factories == null)
 179             return null;
 180 
 181         // Try each factory until one succeeds
 182         ObjectFactory factory;
 183         Object answer = null;
 184         while (answer == null && factories.hasMore()) {
 185             factory = (ObjectFactory)factories.next();
 186             answer = factory.getObjectInstance(obj, name, nameCtx, environment);
 187         }
 188         return answer;
 189     }
 190 
 191     private static String getURLScheme(String str) {
 192         int colon_posn = str.indexOf(':');
 193         int slash_posn = str.indexOf('/');
 194 
 195         if (colon_posn > 0 && (slash_posn == -1 || colon_posn < slash_posn))
 196             return str.substring(0, colon_posn);
 197         return null;
 198     }
 199 
 200     /**
 201      * Creates an instance of an object for the specified object
 202      * and environment.
 203      * <p>
 204      * If an object factory builder has been installed, it is used to
 205      * create a factory for creating the object.
 206      * Otherwise, the following rules are used to create the object:
 207      *<ol>
 208      * <li>If <code>refInfo</code> is a <code>Reference</code>
 209      *    or <code>Referenceable</code> containing a factory class name,
 210      *    use the named factory to create the object.
 211      *    Return <code>refInfo</code> if the factory cannot be created.
 212      *    Under JDK 1.1, if the factory class must be loaded from a location
 213      *    specified in the reference, a <tt>SecurityManager</tt> must have
 214      *    been installed or the factory creation will fail.
 215      *    If an exception is encountered while creating the factory,
 216      *    it is passed up to the caller.
 217      * <li>If <tt>refInfo</tt> is a <tt>Reference</tt> or
 218      *    <tt>Referenceable</tt> with no factory class name,
 219      *    and the address or addresses are <tt>StringRefAddr</tt>s with
 220      *    address type "URL",
 221      *    try the URL context factory corresponding to each URL's scheme id
 222      *    to create the object (see <tt>getURLContext()</tt>).
 223      *    If that fails, continue to the next step.
 224      * <li> Use the object factories specified in
 225      *    the <tt>Context.OBJECT_FACTORIES</tt> property of the environment,
 226      *    and of the provider resource file associated with
 227      *    <tt>nameCtx</tt>, in that order.
 228      *    The value of this property is a colon-separated list of factory
 229      *    class names that are tried in order, and the first one that succeeds
 230      *    in creating an object is the one used.
 231      *    If none of the factories can be loaded,
 232      *    return <code>refInfo</code>.
 233      *    If an exception is encountered while creating the object, the
 234      *    exception is passed up to the caller.
 235      *</ol>
 236      *<p>
 237      * Service providers that implement the <tt>DirContext</tt>
 238      * interface should use
 239      * <tt>DirectoryManager.getObjectInstance()</tt>, not this method.
 240      * Service providers that implement only the <tt>Context</tt>
 241      * interface should use this method.
 242      * <p>
 243      * Note that an object factory (an object that implements the ObjectFactory
 244      * interface) must be public and must have a public constructor that
 245      * accepts no arguments.
 246      * <p>
 247      * The <code>name</code> and <code>nameCtx</code> parameters may
 248      * optionally be used to specify the name of the object being created.
 249      * <code>name</code> is the name of the object, relative to context
 250      * <code>nameCtx</code>.  This information could be useful to the object
 251      * factory or to the object implementation.
 252      *  If there are several possible contexts from which the object
 253      *  could be named -- as will often be the case -- it is up to
 254      *  the caller to select one.  A good rule of thumb is to select the
 255      * "deepest" context available.
 256      * If <code>nameCtx</code> is null, <code>name</code> is relative
 257      * to the default initial context.  If no name is being specified, the
 258      * <code>name</code> parameter should be null.
 259      *
 260      * @param refInfo The possibly null object for which to create an object.
 261      * @param name The name of this object relative to <code>nameCtx</code>.
 262      *          Specifying a name is optional; if it is
 263      *          omitted, <code>name</code> should be null.
 264      * @param nameCtx The context relative to which the <code>name</code>
 265      *          parameter is specified.  If null, <code>name</code> is
 266      *          relative to the default initial context.
 267      * @param environment The possibly null environment to
 268      *          be used in the creation of the object factory and the object.
 269      * @return An object created using <code>refInfo</code>; or
 270      *          <code>refInfo</code> if an object cannot be created using
 271      *          the algorithm described above.
 272      * @exception NamingException if a naming exception was encountered
 273      *  while attempting to get a URL context, or if one of the
 274      *          factories accessed throws a NamingException.
 275      * @exception Exception if one of the factories accessed throws an
 276      *          exception, or if an error was encountered while loading
 277      *          and instantiating the factory and object classes.
 278      *          A factory should only throw an exception if it does not want
 279      *          other factories to be used in an attempt to create an object.
 280      *  See ObjectFactory.getObjectInstance().
 281      * @see #getURLContext
 282      * @see ObjectFactory
 283      * @see ObjectFactory#getObjectInstance
 284      */
 285     public static Object
 286         getObjectInstance(Object refInfo, Name name, Context nameCtx,
 287                           Hashtable<?,?> environment)
 288         throws Exception
 289     {
 290 
 291         ObjectFactory factory;
 292 
 293         // Use builder if installed
 294         ObjectFactoryBuilder builder = getObjectFactoryBuilder();
 295         if (builder != null) {
 296             // builder must return non-null factory
 297             factory = builder.createObjectFactory(refInfo, environment);
 298             return factory.getObjectInstance(refInfo, name, nameCtx,
 299                 environment);
 300         }
 301 
 302         // Use reference if possible
 303         Reference ref = null;
 304         if (refInfo instanceof Reference) {
 305             ref = (Reference) refInfo;
 306         } else if (refInfo instanceof Referenceable) {
 307             ref = ((Referenceable)(refInfo)).getReference();
 308         }
 309 
 310         Object answer;
 311 
 312         if (ref != null) {
 313             String f = ref.getFactoryClassName();
 314             if (f != null) {
 315                 // if reference identifies a factory, use exclusively
 316 
 317                 factory = getObjectFactoryFromReference(ref, f);
 318                 if (factory != null) {
 319                     return factory.getObjectInstance(ref, name, nameCtx,
 320                                                      environment);
 321                 }
 322                 // No factory found, so return original refInfo.
 323                 // Will reach this point if factory class is not in
 324                 // class path and reference does not contain a URL for it
 325                 return refInfo;
 326 
 327             } else {
 328                 // if reference has no factory, check for addresses
 329                 // containing URLs
 330 
 331                 answer = processURLAddrs(ref, name, nameCtx, environment);
 332                 if (answer != null) {
 333                     return answer;
 334                 }
 335             }
 336         }
 337 
 338         // try using any specified factories
 339         answer =
 340             createObjectFromFactories(refInfo, name, nameCtx, environment);
 341         return (answer != null) ? answer : refInfo;
 342     }
 343 
 344     /*
 345      * Ref has no factory.  For each address of type "URL", try its URL
 346      * context factory.  Returns null if unsuccessful in creating and
 347      * invoking a factory.
 348      */
 349     static Object processURLAddrs(Reference ref, Name name, Context nameCtx,
 350                                   Hashtable<?,?> environment)
 351             throws NamingException {
 352 
 353         for (int i = 0; i < ref.size(); i++) {
 354             RefAddr addr = ref.get(i);
 355             if (addr instanceof StringRefAddr &&
 356                 addr.getType().equalsIgnoreCase("URL")) {
 357 
 358                 String url = (String)addr.getContent();
 359                 Object answer = processURL(url, name, nameCtx, environment);
 360                 if (answer != null) {
 361                     return answer;
 362                 }
 363             }
 364         }
 365         return null;
 366     }
 367 
 368     private static Object processURL(Object refInfo, Name name,
 369                                      Context nameCtx, Hashtable<?,?> environment)
 370             throws NamingException {
 371         Object answer;
 372 
 373         // If refInfo is a URL string, try to use its URL context factory
 374         // If no context found, continue to try object factories.
 375         if (refInfo instanceof String) {
 376             String url = (String)refInfo;
 377             String scheme = getURLScheme(url);
 378             if (scheme != null) {
 379                 answer = getURLObject(scheme, refInfo, name, nameCtx,
 380                                       environment);
 381                 if (answer != null) {
 382                     return answer;
 383                 }
 384             }
 385         }
 386 
 387         // If refInfo is an array of URL strings,
 388         // try to find a context factory for any one of its URLs.
 389         // If no context found, continue to try object factories.
 390         if (refInfo instanceof String[]) {
 391             String[] urls = (String[])refInfo;
 392             for (int i = 0; i <urls.length; i++) {
 393                 String scheme = getURLScheme(urls[i]);
 394                 if (scheme != null) {
 395                     answer = getURLObject(scheme, refInfo, name, nameCtx,
 396                                           environment);
 397                     if (answer != null)
 398                         return answer;
 399                 }
 400             }
 401         }
 402         return null;
 403     }
 404 
 405 
 406     /**
 407      * Retrieves a context identified by <code>obj</code>, using the specified
 408      * environment.
 409      * Used by ContinuationContext.
 410      *
 411      * @param obj       The object identifying the context.
 412      * @param name      The name of the context being returned, relative to
 413      *                  <code>nameCtx</code>, or null if no name is being
 414      *                  specified.
 415      *                  See the <code>getObjectInstance</code> method for
 416      *                  details.
 417      * @param nameCtx   The context relative to which <code>name</code> is
 418      *                  specified, or null for the default initial context.
 419      *                  See the <code>getObjectInstance</code> method for
 420      *                  details.
 421      * @param environment Environment specifying characteristics of the
 422      *                  resulting context.
 423      * @return A context identified by <code>obj</code>.
 424      *
 425      * @see #getObjectInstance
 426      */
 427     static Context getContext(Object obj, Name name, Context nameCtx,
 428                               Hashtable<?,?> environment) throws NamingException {
 429         Object answer;
 430 
 431         if (obj instanceof Context) {
 432             // %%% Ignore environment for now.  OK since method not public.
 433             return (Context)obj;
 434         }
 435 
 436         try {
 437             answer = getObjectInstance(obj, name, nameCtx, environment);
 438         } catch (NamingException e) {
 439             throw e;
 440         } catch (Exception e) {
 441             NamingException ne = new NamingException();
 442             ne.setRootCause(e);
 443             throw ne;
 444         }
 445 
 446         return (answer instanceof Context)
 447             ? (Context)answer
 448             : null;
 449     }
 450 
 451     // Used by ContinuationContext
 452     static Resolver getResolver(Object obj, Name name, Context nameCtx,
 453                                 Hashtable<?,?> environment) throws NamingException {
 454         Object answer;
 455 
 456         if (obj instanceof Resolver) {
 457             // %%% Ignore environment for now.  OK since method not public.
 458             return (Resolver)obj;
 459         }
 460 
 461         try {
 462             answer = getObjectInstance(obj, name, nameCtx, environment);
 463         } catch (NamingException e) {
 464             throw e;
 465         } catch (Exception e) {
 466             NamingException ne = new NamingException();
 467             ne.setRootCause(e);
 468             throw ne;
 469         }
 470 
 471         return (answer instanceof Resolver)
 472             ? (Resolver)answer
 473             : null;
 474     }
 475 
 476 
 477     /***************** URL Context implementations ***************/
 478 
 479     /**
 480      * Creates a context for the given URL scheme id.
 481      * <p>
 482      * The resulting context is for resolving URLs of the
 483      * scheme <code>scheme</code>. The resulting context is not tied
 484      * to a specific URL. It is able to handle arbitrary URLs with
 485      * the specified scheme.
 486      *<p>
 487      * The class name of the factory that creates the resulting context
 488      * has the naming convention <i>scheme-id</i>URLContextFactory
 489      * (e.g. "ftpURLContextFactory" for the "ftp" scheme-id),
 490      * in the package specified as follows.
 491      * The <tt>Context.URL_PKG_PREFIXES</tt> environment property (which
 492      * may contain values taken from system properties,
 493      * or application resource files)
 494      * contains a colon-separated list of package prefixes.
 495      * Each package prefix in
 496      * the property is tried in the order specified to load the factory class.
 497      * The default package prefix is "com.sun.jndi.url" (if none of the
 498      * specified packages work, this default is tried).
 499      * The complete package name is constructed using the package prefix,
 500      * concatenated with the scheme id.
 501      *<p>
 502      * For example, if the scheme id is "ldap", and the
 503      * <tt>Context.URL_PKG_PREFIXES</tt> property
 504      * contains "com.widget:com.wiz.jndi",
 505      * the naming manager would attempt to load the following classes
 506      * until one is successfully instantiated:
 507      *<ul>
 508      * <li>com.widget.ldap.ldapURLContextFactory
 509      *  <li>com.wiz.jndi.ldap.ldapURLContextFactory
 510      *  <li>com.sun.jndi.url.ldap.ldapURLContextFactory
 511      *</ul>
 512      * If none of the package prefixes work, null is returned.
 513      *<p>
 514      * If a factory is instantiated, it is invoked with the following
 515      * parameters to produce the resulting context.
 516      * <p>
 517      * <code>factory.getObjectInstance(null, environment);</code>
 518      * <p>
 519      * For example, invoking getObjectInstance() as shown above
 520      * on a LDAP URL context factory would return a
 521      * context that can resolve LDAP urls
 522      * (e.g. "ldap://ldap.wiz.com/o=wiz,c=us",
 523      * "ldap://ldap.umich.edu/o=umich,c=us", ...).
 524      *<p>
 525      * Note that an object factory (an object that implements the ObjectFactory
 526      * interface) must be public and must have a public constructor that
 527      * accepts no arguments.
 528      *
 529      * @param scheme    The non-null scheme-id of the URLs supported by the context.
 530      * @param environment The possibly null environment properties to be
 531      *           used in the creation of the object factory and the context.
 532      * @return A context for resolving URLs with the
 533      *         scheme id <code>scheme</code>;
 534      *  <code>null</code> if the factory for creating the
 535      *         context is not found.
 536      * @exception NamingException If a naming exception occurs while creating
 537      *          the context.
 538      * @see #getObjectInstance
 539      * @see ObjectFactory#getObjectInstance
 540      */
 541     public static Context getURLContext(String scheme,
 542                                         Hashtable<?,?> environment)
 543         throws NamingException
 544     {
 545         // pass in 'null' to indicate creation of generic context for scheme
 546         // (i.e. not specific to a URL).
 547 
 548             Object answer = getURLObject(scheme, null, null, null, environment);
 549             if (answer instanceof Context) {
 550                 return (Context)answer;
 551             } else {
 552                 return null;
 553             }
 554     }
 555 
 556     private static final String defaultPkgPrefix = "com.sun.jndi.url";
 557 
 558     /**
 559      * Creates an object for the given URL scheme id using
 560      * the supplied urlInfo.
 561      * <p>
 562      * If urlInfo is null, the result is a context for resolving URLs
 563      * with the scheme id 'scheme'.
 564      * If urlInfo is a URL, the result is a context named by the URL.
 565      * Names passed to this context is assumed to be relative to this
 566      * context (i.e. not a URL). For example, if urlInfo is
 567      * "ldap://ldap.wiz.com/o=Wiz,c=us", the resulting context will
 568      * be that pointed to by "o=Wiz,c=us" on the server 'ldap.wiz.com'.
 569      * Subsequent names that can be passed to this context will be
 570      * LDAP names relative to this context (e.g. cn="Barbs Jensen").
 571      * If urlInfo is an array of URLs, the URLs are assumed
 572      * to be equivalent in terms of the context to which they refer.
 573      * The resulting context is like that of the single URL case.
 574      * If urlInfo is of any other type, that is handled by the
 575      * context factory for the URL scheme.
 576      * @param scheme the URL scheme id for the context
 577      * @param urlInfo information used to create the context
 578      * @param name name of this object relative to <code>nameCtx</code>
 579      * @param nameCtx Context whose provider resource file will be searched
 580      *          for package prefix values (or null if none)
 581      * @param environment Environment properties for creating the context
 582      * @see javax.naming.InitialContext
 583      */
 584     private static Object getURLObject(String scheme, Object urlInfo,
 585                                        Name name, Context nameCtx,
 586                                        Hashtable<?,?> environment)
 587             throws NamingException {
 588 
 589         // e.g. "ftpURLContextFactory"
 590         ObjectFactory factory = (ObjectFactory)ResourceManager.getFactory(
 591             Context.URL_PKG_PREFIXES, environment, nameCtx,
 592             "." + scheme + "." + scheme + "URLContextFactory", defaultPkgPrefix);
 593 
 594         if (factory == null)
 595           return null;
 596 
 597         // Found object factory
 598         try {
 599             return factory.getObjectInstance(urlInfo, name, nameCtx, environment);
 600         } catch (NamingException e) {
 601             throw e;
 602         } catch (Exception e) {
 603             NamingException ne = new NamingException();
 604             ne.setRootCause(e);
 605             throw ne;
 606         }
 607 
 608     }
 609 
 610 
 611 // ------------ Initial Context Factory Stuff
 612     private static InitialContextFactoryBuilder initctx_factory_builder = null;
 613 
 614     /**
 615      * Use this method for accessing initctx_factory_builder while
 616      * inside an unsynchronized method.
 617      */
 618     private static synchronized InitialContextFactoryBuilder
 619     getInitialContextFactoryBuilder() {
 620         return initctx_factory_builder;
 621     }
 622 
 623     /**
 624      * Creates an initial context using the specified environment
 625      * properties.
 626      * <p>
 627      * This is done as follows:
 628      * <ul>
 629      * <li>If an InitialContextFactoryBuilder has been installed,
 630      *     it is used to create the factory for creating the initial
 631      *     context</li>
 632      * <li>Otherwise, the class specified in the
 633      *     <tt>Context.INITIAL_CONTEXT_FACTORY</tt> environment property
 634      *     is used
 635      *     <ul>
 636      *     <li>First, the {@linkplain java.util.ServiceLoader ServiceLoader}
 637      *         mechanism tries to locate an {@code InitialContextFactory}
 638      *         provider with system classloader</li>
 639      *     <li>Failing that, this implementation tries to locate a suitable
 640      *         {@code InitialContextFactory} using a built-in mechanism
 641      *         <br>
 642      *         (Note that an initial context factory (an object that implements
 643      *         the InitialContextFactory interface) must be public and must have
 644      *         a public constructor that accepts no arguments)</li>
 645      *     </ul>
 646      * </li>
 647      * </ul>
 648      * @param env The possibly null environment properties used when
 649      *                  creating the context.
 650      * @return A non-null initial context.
 651      * @exception NoInitialContextException If the
 652      *          <tt>Context.INITIAL_CONTEXT_FACTORY</tt> property
 653      *         is not found or names a nonexistent
 654      *         class or a class that cannot be instantiated,
 655      *          or if the initial context could not be created for some other
 656      *          reason.
 657      * @exception NamingException If some other naming exception was encountered.
 658      * @see javax.naming.InitialContext
 659      * @see javax.naming.directory.InitialDirContext
 660      */
 661     public static Context getInitialContext(Hashtable<?,?> env)
 662         throws NamingException {
 663         InitialContextFactory factory = null;
 664 
 665         InitialContextFactoryBuilder builder = getInitialContextFactoryBuilder();
 666         if (builder == null) {
 667             // No builder installed, use property
 668             // Get initial context factory class name
 669 
 670             String className = env != null ?
 671                 (String)env.get(Context.INITIAL_CONTEXT_FACTORY) : null;
 672             if (className == null) {
 673                 NoInitialContextException ne = new NoInitialContextException(
 674                     "Need to specify class name in environment or system " +
 675                     "property, or in an application resource file: " +
 676                     Context.INITIAL_CONTEXT_FACTORY);
 677                 throw ne;
 678             }
 679 
 680             ServiceLoader<InitialContextFactory> loader =
 681                     ServiceLoader.load(InitialContextFactory.class,
 682                             ClassLoader.getSystemClassLoader());
 683 
 684             Iterator<InitialContextFactory> iterator = loader.iterator();
 685             try {
 686                 while (iterator.hasNext()) {
 687                     InitialContextFactory f = iterator.next();
 688                     if (f.getClass().getName().equals(className)) {
 689                         factory = f;
 690                         break;
 691                     }
 692                 }
 693             } catch (ServiceConfigurationError e) {
 694                 NoInitialContextException ne =
 695                         new NoInitialContextException(
 696                                 "Cannot load initial context factory "
 697                                         + "'" + className + "'");
 698                 ne.setRootCause(e);
 699                 throw ne;
 700             }
 701 
 702             if (factory == null) {
 703                 try {
 704                     factory = (InitialContextFactory)
 705                             helper.loadClass(className).newInstance();
 706                 } catch (Exception e) {
 707                     NoInitialContextException ne =
 708                             new NoInitialContextException(
 709                                     "Cannot instantiate class: " + className);
 710                     ne.setRootCause(e);
 711                     throw ne;
 712                 }
 713             }
 714         } else {
 715             factory = builder.createInitialContextFactory(env);
 716         }
 717 
 718         return factory.getInitialContext(env);
 719     }
 720 
 721 
 722     /**
 723      * Sets the InitialContextFactory builder to be builder.
 724      *
 725      *<p>
 726      * The builder can only be installed if the executing thread is allowed by
 727      * the security manager to do so. Once installed, the builder cannot
 728      * be replaced.
 729      * @param builder The initial context factory builder to install. If null,
 730      *                no builder is set.
 731      * @exception SecurityException builder cannot be installed for security
 732      *                  reasons.
 733      * @exception NamingException builder cannot be installed for
 734      *         a non-security-related reason.
 735      * @exception IllegalStateException If a builder was previous installed.
 736      * @see #hasInitialContextFactoryBuilder
 737      * @see java.lang.SecurityManager#checkSetFactory
 738      */
 739     public static synchronized void setInitialContextFactoryBuilder(
 740         InitialContextFactoryBuilder builder)
 741         throws NamingException {
 742             if (initctx_factory_builder != null)
 743                 throw new IllegalStateException(
 744                     "InitialContextFactoryBuilder already set");
 745 
 746             SecurityManager security = System.getSecurityManager();
 747             if (security != null) {
 748                 security.checkSetFactory();
 749             }
 750             initctx_factory_builder = builder;
 751     }
 752 
 753     /**
 754      * Determines whether an initial context factory builder has
 755      * been set.
 756      * @return true if an initial context factory builder has
 757      *           been set; false otherwise.
 758      * @see #setInitialContextFactoryBuilder
 759      */
 760     public static boolean hasInitialContextFactoryBuilder() {
 761         return (getInitialContextFactoryBuilder() != null);
 762     }
 763 
 764 // -----  Continuation Context Stuff
 765 
 766     /**
 767      * Constant that holds the name of the environment property into
 768      * which <tt>getContinuationContext()</tt> stores the value of its
 769      * <tt>CannotProceedException</tt> parameter.
 770      * This property is inherited by the continuation context, and may
 771      * be used by that context's service provider to inspect the
 772      * fields of the exception.
 773      *<p>
 774      * The value of this constant is "java.naming.spi.CannotProceedException".
 775      *
 776      * @see #getContinuationContext
 777      * @since 1.3
 778      */
 779     public static final String CPE = "java.naming.spi.CannotProceedException";
 780 
 781     /**
 782      * Creates a context in which to continue a context operation.
 783      *<p>
 784      * In performing an operation on a name that spans multiple
 785      * namespaces, a context from one naming system may need to pass
 786      * the operation on to the next naming system.  The context
 787      * implementation does this by first constructing a
 788      * <code>CannotProceedException</code> containing information
 789      * pinpointing how far it has proceeded.  It then obtains a
 790      * continuation context from JNDI by calling
 791      * <code>getContinuationContext</code>.  The context
 792      * implementation should then resume the context operation by
 793      * invoking the same operation on the continuation context, using
 794      * the remainder of the name that has not yet been resolved.
 795      *<p>
 796      * Before making use of the <tt>cpe</tt> parameter, this method
 797      * updates the environment associated with that object by setting
 798      * the value of the property <a href="#CPE"><tt>CPE</tt></a>
 799      * to <tt>cpe</tt>.  This property will be inherited by the
 800      * continuation context, and may be used by that context's
 801      * service provider to inspect the fields of this exception.
 802      *
 803      * @param cpe
 804      *          The non-null exception that triggered this continuation.
 805      * @return A non-null Context object for continuing the operation.
 806      * @exception NamingException If a naming exception occurred.
 807      */
 808     @SuppressWarnings("unchecked")
 809     public static Context getContinuationContext(CannotProceedException cpe)
 810             throws NamingException {
 811 
 812         Hashtable<Object,Object> env = (Hashtable<Object,Object>)cpe.getEnvironment();
 813         if (env == null) {
 814             env = new Hashtable<>(7);
 815         } else {
 816             // Make a (shallow) copy of the environment.
 817             env = (Hashtable<Object,Object>)env.clone();
 818         }
 819         env.put(CPE, cpe);
 820 
 821         ContinuationContext cctx = new ContinuationContext(cpe, env);
 822         return cctx.getTargetContext();
 823     }
 824 
 825 // ------------ State Factory Stuff
 826 
 827     /**
 828      * Retrieves the state of an object for binding.
 829      * <p>
 830      * Service providers that implement the <tt>DirContext</tt> interface
 831      * should use <tt>DirectoryManager.getStateToBind()</tt>, not this method.
 832      * Service providers that implement only the <tt>Context</tt> interface
 833      * should use this method.
 834      *<p>
 835      * This method uses the specified state factories in
 836      * the <tt>Context.STATE_FACTORIES</tt> property from the environment
 837      * properties, and from the provider resource file associated with
 838      * <tt>nameCtx</tt>, in that order.
 839      *    The value of this property is a colon-separated list of factory
 840      *    class names that are tried in order, and the first one that succeeds
 841      *    in returning the object's state is the one used.
 842      * If no object's state can be retrieved in this way, return the
 843      * object itself.
 844      *    If an exception is encountered while retrieving the state, the
 845      *    exception is passed up to the caller.
 846      * <p>
 847      * Note that a state factory
 848      * (an object that implements the StateFactory
 849      * interface) must be public and must have a public constructor that
 850      * accepts no arguments.
 851      * <p>
 852      * The <code>name</code> and <code>nameCtx</code> parameters may
 853      * optionally be used to specify the name of the object being created.
 854      * See the description of "Name and Context Parameters" in
 855      * {@link ObjectFactory#getObjectInstance
 856      *          ObjectFactory.getObjectInstance()}
 857      * for details.
 858      * <p>
 859      * This method may return a <tt>Referenceable</tt> object.  The
 860      * service provider obtaining this object may choose to store it
 861      * directly, or to extract its reference (using
 862      * <tt>Referenceable.getReference()</tt>) and store that instead.
 863      *
 864      * @param obj The non-null object for which to get state to bind.
 865      * @param name The name of this object relative to <code>nameCtx</code>,
 866      *          or null if no name is specified.
 867      * @param nameCtx The context relative to which the <code>name</code>
 868      *          parameter is specified, or null if <code>name</code> is
 869      *          relative to the default initial context.
 870      *  @param environment The possibly null environment to
 871      *          be used in the creation of the state factory and
 872      *  the object's state.
 873      * @return The non-null object representing <tt>obj</tt>'s state for
 874      *  binding.  It could be the object (<tt>obj</tt>) itself.
 875      * @exception NamingException If one of the factories accessed throws an
 876      *          exception, or if an error was encountered while loading
 877      *          and instantiating the factory and object classes.
 878      *          A factory should only throw an exception if it does not want
 879      *          other factories to be used in an attempt to create an object.
 880      *  See <tt>StateFactory.getStateToBind()</tt>.
 881      * @see StateFactory
 882      * @see StateFactory#getStateToBind
 883      * @see DirectoryManager#getStateToBind
 884      * @since 1.3
 885      */
 886     public static Object
 887         getStateToBind(Object obj, Name name, Context nameCtx,
 888                        Hashtable<?,?> environment)
 889         throws NamingException
 890     {
 891 
 892         FactoryEnumeration factories = ResourceManager.getFactories(
 893             Context.STATE_FACTORIES, environment, nameCtx);
 894 
 895         if (factories == null) {
 896             return obj;
 897         }
 898 
 899         // Try each factory until one succeeds
 900         StateFactory factory;
 901         Object answer = null;
 902         while (answer == null && factories.hasMore()) {
 903             factory = (StateFactory)factories.next();
 904             answer = factory.getStateToBind(obj, name, nameCtx, environment);
 905         }
 906 
 907         return (answer != null) ? answer : obj;
 908     }
 909 }