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 }