Source for java.lang.ClassLoader

   1: /* ClassLoader.java -- responsible for loading classes into the VM
   2:    Copyright (C) 1998, 1999, 2001, 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
   3: 
   4: This file is part of GNU Classpath.
   5: 
   6: GNU Classpath is free software; you can redistribute it and/or modify
   7: it under the terms of the GNU General Public License as published by
   8: the Free Software Foundation; either version 2, or (at your option)
   9: any later version.
  10: 
  11: GNU Classpath is distributed in the hope that it will be useful, but
  12: WITHOUT ANY WARRANTY; without even the implied warranty of
  13: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14: General Public License for more details.
  15: 
  16: You should have received a copy of the GNU General Public License
  17: along with GNU Classpath; see the file COPYING.  If not, write to the
  18: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19: 02110-1301 USA.
  20: 
  21: Linking this library statically or dynamically with other modules is
  22: making a combined work based on this library.  Thus, the terms and
  23: conditions of the GNU General Public License cover the whole
  24: combination.
  25: 
  26: As a special exception, the copyright holders of this library give you
  27: permission to link this library with independent modules to produce an
  28: executable, regardless of the license terms of these independent
  29: modules, and to copy and distribute the resulting executable under
  30: terms of your choice, provided that you also meet, for each linked
  31: independent module, the terms and conditions of the license of that
  32: module.  An independent module is a module which is not derived from
  33: or based on this library.  If you modify this library, you may extend
  34: this exception to your version of the library, but you are not
  35: obligated to do so.  If you do not wish to do so, delete this
  36: exception statement from your version. */
  37: 
  38: 
  39: package java.lang;
  40: 
  41: import gnu.classpath.SystemProperties;
  42: import gnu.java.util.DoubleEnumeration;
  43: import gnu.java.util.EmptyEnumeration;
  44: 
  45: import java.io.IOException;
  46: import java.io.InputStream;
  47: import java.net.URL;
  48: import java.security.CodeSource;
  49: import java.security.PermissionCollection;
  50: import java.security.Policy;
  51: import java.security.ProtectionDomain;
  52: import java.util.Enumeration;
  53: import java.util.HashMap;
  54: import java.util.Map;
  55: 
  56: /**
  57:  * The ClassLoader is a way of customizing the way Java gets its classes
  58:  * and loads them into memory.  The verifier and other standard Java things
  59:  * still run, but the ClassLoader is allowed great flexibility in determining
  60:  * where to get the classfiles and when to load and resolve them. For that
  61:  * matter, a custom ClassLoader can perform on-the-fly code generation or
  62:  * modification!
  63:  *
  64:  * <p>Every classloader has a parent classloader that is consulted before
  65:  * the 'child' classloader when classes or resources should be loaded.
  66:  * This is done to make sure that classes can be loaded from an hierarchy of
  67:  * multiple classloaders and classloaders do not accidentially redefine
  68:  * already loaded classes by classloaders higher in the hierarchy.
  69:  *
  70:  * <p>The grandparent of all classloaders is the bootstrap classloader, which
  71:  * loads all the standard system classes as implemented by GNU Classpath. The
  72:  * other special classloader is the system classloader (also called
  73:  * application classloader) that loads all classes from the CLASSPATH
  74:  * (<code>java.class.path</code> system property). The system classloader
  75:  * is responsible for finding the application classes from the classpath,
  76:  * and delegates all requests for the standard library classes to its parent
  77:  * the bootstrap classloader. Most programs will load all their classes
  78:  * through the system classloaders.
  79:  *
  80:  * <p>The bootstrap classloader in GNU Classpath is implemented as a couple of
  81:  * static (native) methods on the package private class
  82:  * <code>java.lang.VMClassLoader</code>, the system classloader is an
  83:  * instance of <code>gnu.java.lang.SystemClassLoader</code>
  84:  * (which is a subclass of <code>java.net.URLClassLoader</code>).
  85:  *
  86:  * <p>Users of a <code>ClassLoader</code> will normally just use the methods
  87:  * <ul>
  88:  *  <li> <code>loadClass()</code> to load a class.</li>
  89:  *  <li> <code>getResource()</code> or <code>getResourceAsStream()</code>
  90:  *       to access a resource.</li>
  91:  *  <li> <code>getResources()</code> to get an Enumeration of URLs to all
  92:  *       the resources provided by the classloader and its parents with the
  93:  *       same name.</li>
  94:  * </ul>
  95:  *
  96:  * <p>Subclasses should implement the methods
  97:  * <ul>
  98:  *  <li> <code>findClass()</code> which is called by <code>loadClass()</code>
  99:  *       when the parent classloader cannot provide a named class.</li>
 100:  *  <li> <code>findResource()</code> which is called by
 101:  *       <code>getResource()</code> when the parent classloader cannot provide
 102:  *       a named resource.</li>
 103:  *  <li> <code>findResources()</code> which is called by
 104:  *       <code>getResource()</code> to combine all the resources with the
 105:  *       same name from the classloader and its parents.</li>
 106:  *  <li> <code>findLibrary()</code> which is called by
 107:  *       <code>Runtime.loadLibrary()</code> when a class defined by the
 108:  *       classloader wants to load a native library.</li>
 109:  * </ul>
 110:  *
 111:  * @author John Keiser
 112:  * @author Mark Wielaard
 113:  * @author Eric Blake (ebb9@email.byu.edu)
 114:  * @see Class
 115:  * @since 1.0
 116:  * @status still missing 1.4 functionality
 117:  */
 118: public abstract class ClassLoader
 119: {
 120:   /**
 121:    * All classes loaded by this classloader. VM's may choose to implement
 122:    * this cache natively; but it is here available for use if necessary. It
 123:    * is not private in order to allow native code (and trusted subclasses)
 124:    * access to this field.
 125:    */
 126:   final HashMap loadedClasses = new HashMap();
 127: 
 128:   /**
 129:    * All packages defined by this classloader. It is not private in order to
 130:    * allow native code (and trusted subclasses) access to this field.
 131:    */
 132:   final HashMap definedPackages = new HashMap();
 133: 
 134:   /**
 135:    * The classloader that is consulted before this classloader.
 136:    * If null then the parent is the bootstrap classloader.
 137:    */
 138:   private final ClassLoader parent;
 139: 
 140:   /**
 141:    * This is true if this classloader was successfully initialized.
 142:    * This flag is needed to avoid a class loader attack: even if the
 143:    * security manager rejects an attempt to create a class loader, the
 144:    * malicious class could have a finalize method which proceeds to
 145:    * define classes.
 146:    */
 147:   private final boolean initialized;
 148: 
 149:   /**
 150:    * System/Application classloader: defaults to an instance of
 151:    * gnu.java.lang.SystemClassLoader, unless the first invocation of
 152:    * getSystemClassLoader loads another class loader because of the
 153:    * java.system.class.loader property. The initialization of this field
 154:    * is somewhat circular - getSystemClassLoader() checks whether this
 155:    * field is null in order to bypass a security check.
 156:    */
 157:   static final ClassLoader systemClassLoader =
 158:     VMClassLoader.getSystemClassLoader();
 159: 
 160:   static
 161:   {
 162:     // Find out if we have to install a default security manager. Note
 163:     // that this is done here because we potentially need the system
 164:     // class loader to load the security manager and note also that we
 165:     // don't need the security manager until the system class loader
 166:     // is created.  If the runtime chooses to use a class loader that
 167:     // doesn't have the system class loader as its parent, it is
 168:     // responsible for setting up a security manager before doing so.
 169:     String secman = SystemProperties.getProperty("java.security.manager");
 170:     if (secman != null && SecurityManager.current == null)
 171:     {
 172:       if (secman.equals("") || secman.equals("default"))
 173:       {
 174:     SecurityManager.current = new SecurityManager();
 175:       }
 176:       else
 177:       {
 178:     try
 179:     {
 180:       Class cl = Class.forName(secman, false, systemClassLoader);
 181:       SecurityManager.current = (SecurityManager) cl.newInstance();
 182:     }
 183:     catch (Exception x)
 184:     {
 185:       throw (InternalError)
 186:         new InternalError("Unable to create SecurityManager")
 187:             .initCause(x);
 188:     }
 189:       }
 190:     }
 191:   }
 192: 
 193:   /**
 194:    * The default protection domain, used when defining a class with a null
 195:    * paramter for the domain.
 196:    */
 197:   static final ProtectionDomain defaultProtectionDomain;
 198:   static
 199:   {
 200:     CodeSource cs = new CodeSource(null, null);
 201:     PermissionCollection perm = Policy.getPolicy().getPermissions(cs);
 202:     defaultProtectionDomain = new ProtectionDomain(cs, perm);
 203:   }
 204: 
 205:   /**
 206:    * The desired assertion status of classes loaded by this loader, if not
 207:    * overridden by package or class instructions.
 208:    */
 209:   // Package visible for use by Class.
 210:   boolean defaultAssertionStatus = VMClassLoader.defaultAssertionStatus();
 211: 
 212:   /**
 213:    * The command-line state of the package assertion status overrides. This
 214:    * map is never modified, so it does not need to be synchronized.
 215:    */
 216:   // Package visible for use by Class.
 217:   static final Map systemPackageAssertionStatus
 218:     = VMClassLoader.packageAssertionStatus();
 219: 
 220:   /**
 221:    * The map of package assertion status overrides, or null if no package
 222:    * overrides have been specified yet. The values of the map should be
 223:    * Boolean.TRUE or Boolean.FALSE, and the unnamed package is represented
 224:    * by the null key. This map must be synchronized on this instance.
 225:    */
 226:   // Package visible for use by Class.
 227:   Map packageAssertionStatus;
 228: 
 229:   /**
 230:    * The command-line state of the class assertion status overrides. This
 231:    * map is never modified, so it does not need to be synchronized.
 232:    */
 233:   // Package visible for use by Class.
 234:   static final Map systemClassAssertionStatus
 235:     = VMClassLoader.classAssertionStatus();
 236: 
 237:   /**
 238:    * The map of class assertion status overrides, or null if no class
 239:    * overrides have been specified yet. The values of the map should be
 240:    * Boolean.TRUE or Boolean.FALSE. This map must be synchronized on this
 241:    * instance.
 242:    */
 243:   // Package visible for use by Class.
 244:   Map classAssertionStatus;
 245: 
 246:   /**
 247:    * Create a new ClassLoader with as parent the system classloader. There
 248:    * may be a security check for <code>checkCreateClassLoader</code>.
 249:    *
 250:    * @throws SecurityException if the security check fails
 251:    */
 252:   protected ClassLoader() throws SecurityException
 253:   {
 254:     this(systemClassLoader);
 255:   }
 256: 
 257:   /**
 258:    * Create a new ClassLoader with the specified parent. The parent will
 259:    * be consulted when a class or resource is requested through
 260:    * <code>loadClass()</code> or <code>getResource()</code>. Only when the
 261:    * parent classloader cannot provide the requested class or resource the
 262:    * <code>findClass()</code> or <code>findResource()</code> method
 263:    * of this classloader will be called. There may be a security check for
 264:    * <code>checkCreateClassLoader</code>.
 265:    *
 266:    * @param parent the classloader's parent, or null for the bootstrap
 267:    *        classloader
 268:    * @throws SecurityException if the security check fails
 269:    * @since 1.2
 270:    */
 271:   protected ClassLoader(ClassLoader parent)
 272:   {
 273:     // May we create a new classloader?
 274:     SecurityManager sm = System.getSecurityManager();
 275:     if (sm != null)
 276:       sm.checkCreateClassLoader();
 277:     this.parent = parent;
 278:     this.initialized = true;
 279:   }
 280: 
 281:   /**
 282:    * Load a class using this ClassLoader or its parent, without resolving
 283:    * it. Calls <code>loadClass(name, false)</code>.
 284:    *
 285:    * <p>Subclasses should not override this method but should override
 286:    * <code>findClass()</code> which is called by this method.</p>
 287:    *
 288:    * @param name the name of the class relative to this ClassLoader
 289:    * @return the loaded class
 290:    * @throws ClassNotFoundException if the class cannot be found
 291:    */
 292:   public Class loadClass(String name) throws ClassNotFoundException
 293:   {
 294:     return loadClass(name, false);
 295:   }
 296: 
 297:   private native Class loadClassFromSig(String name)
 298:     throws ClassNotFoundException;
 299: 
 300:   /**
 301:    * Load a class using this ClassLoader or its parent, possibly resolving
 302:    * it as well using <code>resolveClass()</code>. It first tries to find
 303:    * out if the class has already been loaded through this classloader by
 304:    * calling <code>findLoadedClass()</code>. Then it calls
 305:    * <code>loadClass()</code> on the parent classloader (or when there is
 306:    * no parent it uses the VM bootclassloader). If the class is still
 307:    * not loaded it tries to create a new class by calling
 308:    * <code>findClass()</code>. Finally when <code>resolve</code> is
 309:    * <code>true</code> it also calls <code>resolveClass()</code> on the
 310:    * newly loaded class.
 311:    *
 312:    * <p>Subclasses should not override this method but should override
 313:    * <code>findClass()</code> which is called by this method.</p>
 314:    *
 315:    * @param name the fully qualified name of the class to load
 316:    * @param resolve whether or not to resolve the class
 317:    * @return the loaded class
 318:    * @throws ClassNotFoundException if the class cannot be found
 319:    */
 320:   protected synchronized Class loadClass(String name, boolean resolve)
 321:     throws ClassNotFoundException
 322:   {
 323:     // Arrays are handled specially.
 324:     Class c;
 325:     if (name.length() > 0 && name.charAt(0) == '[')
 326:       c = loadClassFromSig(name);
 327:     else
 328:       {
 329:     // Have we already loaded this class?
 330:     c = findLoadedClass(name);
 331:     if (c == null)
 332:       {
 333:         // Can the class be loaded by a parent?
 334:         try
 335:           {
 336:         if (parent == null)
 337:           {
 338:             c = VMClassLoader.loadClass(name, resolve);
 339:             if (c != null)
 340:               return c;
 341:           }
 342:         else
 343:           {
 344:             return parent.loadClass(name, resolve);
 345:           }
 346:           }
 347:         catch (ClassNotFoundException e)
 348:           {
 349:           }
 350:         // Still not found, we have to do it ourself.
 351:         c = findClass(name);
 352:       }
 353:       }
 354:     if (resolve)
 355:       resolveClass(c);
 356:     return c;
 357:   }
 358: 
 359:   /**
 360:    * Called for every class name that is needed but has not yet been
 361:    * defined by this classloader or one of its parents. It is called by
 362:    * <code>loadClass()</code> after both <code>findLoadedClass()</code> and
 363:    * <code>parent.loadClass()</code> couldn't provide the requested class.
 364:    *
 365:    * <p>The default implementation throws a
 366:    * <code>ClassNotFoundException</code>. Subclasses should override this
 367:    * method. An implementation of this method in a subclass should get the
 368:    * class bytes of the class (if it can find them), if the package of the
 369:    * requested class doesn't exist it should define the package and finally
 370:    * it should call define the actual class. It does not have to resolve the
 371:    * class. It should look something like the following:<br>
 372:    *
 373:    * <pre>
 374:    * // Get the bytes that describe the requested class
 375:    * byte[] classBytes = classLoaderSpecificWayToFindClassBytes(name);
 376:    * // Get the package name
 377:    * int lastDot = name.lastIndexOf('.');
 378:    * if (lastDot != -1)
 379:    *   {
 380:    *     String packageName = name.substring(0, lastDot);
 381:    *     // Look if the package already exists
 382:    *     if (getPackage(packageName) == null)
 383:    *       {
 384:    *         // define the package
 385:    *         definePackage(packageName, ...);
 386:    *       }
 387:    *   }
 388:    * // Define and return the class
 389:    *  return defineClass(name, classBytes, 0, classBytes.length);
 390:    * </pre>
 391:    *
 392:    * <p><code>loadClass()</code> makes sure that the <code>Class</code>
 393:    * returned by <code>findClass()</code> will later be returned by
 394:    * <code>findLoadedClass()</code> when the same class name is requested.
 395:    *
 396:    * @param name class name to find (including the package name)
 397:    * @return the requested Class
 398:    * @throws ClassNotFoundException when the class can not be found
 399:    * @since 1.2
 400:    */
 401:   protected Class findClass(String name) throws ClassNotFoundException
 402:   {
 403:     throw new ClassNotFoundException(name);
 404:   }
 405: 
 406:   /**
 407:    * Helper to define a class using a string of bytes. This version is not
 408:    * secure.
 409:    *
 410:    * @param data the data representing the classfile, in classfile format
 411:    * @param offset the offset into the data where the classfile starts
 412:    * @param len the length of the classfile data in the array
 413:    * @return the class that was defined
 414:    * @throws ClassFormatError if data is not in proper classfile format
 415:    * @throws IndexOutOfBoundsException if offset or len is negative, or
 416:    *         offset + len exceeds data
 417:    * @deprecated use {@link #defineClass(String, byte[], int, int)} instead
 418:    */
 419:   protected final Class defineClass(byte[] data, int offset, int len)
 420:     throws ClassFormatError
 421:   {
 422:     return defineClass(null, data, offset, len);
 423:   }
 424: 
 425:   /**
 426:    * Helper to define a class using a string of bytes without a
 427:    * ProtectionDomain. Subclasses should call this method from their
 428:    * <code>findClass()</code> implementation. The name should use '.'
 429:    * separators, and discard the trailing ".class".  The default protection
 430:    * domain has the permissions of
 431:    * <code>Policy.getPolicy().getPermissions(new CodeSource(null, null))</code>.
 432:    *
 433:    * @param name the name to give the class, or null if unknown
 434:    * @param data the data representing the classfile, in classfile format
 435:    * @param offset the offset into the data where the classfile starts
 436:    * @param len the length of the classfile data in the array
 437:    * @return the class that was defined
 438:    * @throws ClassFormatError if data is not in proper classfile format
 439:    * @throws IndexOutOfBoundsException if offset or len is negative, or
 440:    *         offset + len exceeds data
 441:    * @throws SecurityException if name starts with "java."
 442:    * @since 1.1
 443:    */
 444:   protected final Class defineClass(String name, byte[] data, int offset,
 445:                                     int len) throws ClassFormatError
 446:   {
 447:     return defineClass(name, data, offset, len, null);
 448:   }
 449: 
 450:   /**
 451:    * Helper to define a class using a string of bytes. Subclasses should call
 452:    * this method from their <code>findClass()</code> implementation. If the
 453:    * domain is null, the default of
 454:    * <code>Policy.getPolicy().getPermissions(new CodeSource(null, null))</code>
 455:    * is used. Once a class has been defined in a package, all further classes
 456:    * in that package must have the same set of certificates or a
 457:    * SecurityException is thrown.
 458:    *
 459:    * @param name the name to give the class.  null if unknown
 460:    * @param data the data representing the classfile, in classfile format
 461:    * @param offset the offset into the data where the classfile starts
 462:    * @param len the length of the classfile data in the array
 463:    * @param domain the ProtectionDomain to give to the class, null for the
 464:    *        default protection domain
 465:    * @return the class that was defined
 466:    * @throws ClassFormatError if data is not in proper classfile format
 467:    * @throws IndexOutOfBoundsException if offset or len is negative, or
 468:    *         offset + len exceeds data
 469:    * @throws SecurityException if name starts with "java.", or if certificates
 470:    *         do not match up
 471:    * @since 1.2
 472:    */
 473:   protected final synchronized Class defineClass(String name, byte[] data,
 474:                          int offset, int len,
 475:                          ProtectionDomain domain)
 476:     throws ClassFormatError
 477:   {
 478:     if (domain == null)
 479:       domain = defaultProtectionDomain;
 480:     if (! initialized)
 481:       throw new SecurityException("attempt to define class from uninitialized class loader");
 482:     
 483:     Class retval = VMClassLoader.defineClass(this, name, data,
 484:                          offset, len, domain);
 485:     loadedClasses.put(retval.getName(), retval);
 486:     return retval;
 487:   }
 488: 
 489:   /**
 490:    * Links the class, if that has not already been done. Linking basically
 491:    * resolves all references to other classes made by this class.
 492:    *
 493:    * @param c the class to resolve
 494:    * @throws NullPointerException if c is null
 495:    * @throws LinkageError if linking fails
 496:    */
 497:   protected final void resolveClass(Class c)
 498:   {
 499:     VMClassLoader.resolveClass(c);
 500:   }
 501: 
 502:   /**
 503:    * Helper to find a Class using the system classloader, possibly loading it.
 504:    * A subclass usually does not need to call this, if it correctly
 505:    * overrides <code>findClass(String)</code>.
 506:    *
 507:    * @param name the name of the class to find
 508:    * @return the found class
 509:    * @throws ClassNotFoundException if the class cannot be found
 510:    */
 511:   protected final Class findSystemClass(String name)
 512:     throws ClassNotFoundException
 513:   {
 514:     return Class.forName(name, false, systemClassLoader);
 515:   }
 516: 
 517:   /**
 518:    * Returns the parent of this classloader. If the parent of this
 519:    * classloader is the bootstrap classloader then this method returns
 520:    * <code>null</code>. A security check may be performed on
 521:    * <code>RuntimePermission("getClassLoader")</code>.
 522:    *
 523:    * @return the parent <code>ClassLoader</code>
 524:    * @throws SecurityException if the security check fails
 525:    * @since 1.2
 526:    */
 527:   public final ClassLoader getParent()
 528:   {
 529:     // Check if we may return the parent classloader.
 530:     SecurityManager sm = System.getSecurityManager();
 531:     if (sm != null)
 532:       {
 533:         Class c = VMSecurityManager.getClassContext(ClassLoader.class)[0];
 534:         ClassLoader cl = c.getClassLoader();
 535:     if (cl != null && ! cl.isAncestorOf(this))
 536:           sm.checkPermission(new RuntimePermission("getClassLoader"));
 537:       }
 538:     return parent;
 539:   }
 540: 
 541:   /**
 542:    * Helper to set the signers of a class. This should be called after
 543:    * defining the class.
 544:    *
 545:    * @param c the Class to set signers of
 546:    * @param signers the signers to set
 547:    * @since 1.1
 548:    */
 549:   protected final void setSigners(Class c, Object[] signers)
 550:   {
 551:     c.setSigners(signers);
 552:   }
 553: 
 554:   /**
 555:    * Helper to find an already-loaded class in this ClassLoader.
 556:    *
 557:    * @param name the name of the class to find
 558:    * @return the found Class, or null if it is not found
 559:    * @since 1.1
 560:    */
 561:   protected final synchronized Class findLoadedClass(String name)
 562:   {
 563:     // NOTE: If the VM is keeping its own cache, it may make sense to have
 564:     // this method be native.
 565:     return (Class) loadedClasses.get(name);
 566:   }
 567: 
 568:   /**
 569:    * Get the URL to a resource using this classloader or one of its parents.
 570:    * First tries to get the resource by calling <code>getResource()</code>
 571:    * on the parent classloader. If the parent classloader returns null then
 572:    * it tries finding the resource by calling <code>findResource()</code> on
 573:    * this classloader. The resource name should be separated by '/' for path
 574:    * elements.
 575:    *
 576:    * <p>Subclasses should not override this method but should override
 577:    * <code>findResource()</code> which is called by this method.
 578:    *
 579:    * @param name the name of the resource relative to this classloader
 580:    * @return the URL to the resource or null when not found
 581:    */
 582:   public URL getResource(String name)
 583:   {
 584:     URL result;
 585: 
 586:     if (parent == null)
 587:       result = VMClassLoader.getResource(name);
 588:     else
 589:       result = parent.getResource(name);
 590: 
 591:     if (result == null)
 592:       result = findResource(name);
 593:     return result;
 594:   }
 595: 
 596:   /**
 597:    * Returns an Enumeration of all resources with a given name that can
 598:    * be found by this classloader and its parents. Certain classloaders
 599:    * (such as the URLClassLoader when given multiple jar files) can have
 600:    * multiple resources with the same name that come from multiple locations.
 601:    * It can also occur that a parent classloader offers a resource with a
 602:    * certain name and the child classloader also offers a resource with that
 603:    * same name. <code>getResource()</code> only offers the first resource (of the
 604:    * parent) with a given name. This method lists all resources with the
 605:    * same name. The name should use '/' as path separators.
 606:    *
 607:    * <p>The Enumeration is created by first calling <code>getResources()</code>
 608:    * on the parent classloader and then calling <code>findResources()</code>
 609:    * on this classloader.</p>
 610:    *
 611:    * @param name the resource name
 612:    * @return an enumaration of all resources found
 613:    * @throws IOException if I/O errors occur in the process
 614:    * @since 1.2
 615:    */
 616:   public final Enumeration getResources(String name) throws IOException
 617:   {
 618:     Enumeration parentResources;
 619:     if (parent == null)
 620:       parentResources = VMClassLoader.getResources(name);
 621:     else
 622:       parentResources = parent.getResources(name);
 623:     return new DoubleEnumeration(parentResources, findResources(name));
 624:   }
 625: 
 626:   /**
 627:    * Called whenever all locations of a named resource are needed.
 628:    * It is called by <code>getResources()</code> after it has called
 629:    * <code>parent.getResources()</code>. The results are combined by
 630:    * the <code>getResources()</code> method.
 631:    *
 632:    * <p>The default implementation always returns an empty Enumeration.
 633:    * Subclasses should override it when they can provide an Enumeration of
 634:    * URLs (possibly just one element) to the named resource.
 635:    * The first URL of the Enumeration should be the same as the one
 636:    * returned by <code>findResource</code>.
 637:    *
 638:    * @param name the name of the resource to be found
 639:    * @return a possibly empty Enumeration of URLs to the named resource
 640:    * @throws IOException if I/O errors occur in the process
 641:    * @since 1.2
 642:    */
 643:   protected Enumeration findResources(String name) throws IOException
 644:   {
 645:     return EmptyEnumeration.getInstance();
 646:   }
 647: 
 648:   /**
 649:    * Called whenever a resource is needed that could not be provided by
 650:    * one of the parents of this classloader. It is called by
 651:    * <code>getResource()</code> after <code>parent.getResource()</code>
 652:    * couldn't provide the requested resource.
 653:    *
 654:    * <p>The default implementation always returns null. Subclasses should
 655:    * override this method when they can provide a way to return a URL
 656:    * to a named resource.
 657:    *
 658:    * @param name the name of the resource to be found
 659:    * @return a URL to the named resource or null when not found
 660:    * @since 1.2
 661:    */
 662:   protected URL findResource(String name)
 663:   {
 664:     return null;
 665:   }
 666: 
 667:   /**
 668:    * Get the URL to a resource using the system classloader.
 669:    *
 670:    * @param name the name of the resource relative to the system classloader
 671:    * @return the URL to the resource
 672:    * @since 1.1
 673:    */
 674:   public static final URL getSystemResource(String name)
 675:   {
 676:     return systemClassLoader.getResource(name);
 677:   }
 678: 
 679:   /**
 680:    * Get an Enumeration of URLs to resources with a given name using the
 681:    * the system classloader. The enumeration firsts lists the resources with
 682:    * the given name that can be found by the bootstrap classloader followed
 683:    * by the resources with the given name that can be found on the classpath.
 684:    *
 685:    * @param name the name of the resource relative to the system classloader
 686:    * @return an Enumeration of URLs to the resources
 687:    * @throws IOException if I/O errors occur in the process
 688:    * @since 1.2
 689:    */
 690:   public static Enumeration getSystemResources(String name) throws IOException
 691:   {
 692:     return systemClassLoader.getResources(name);
 693:   }
 694: 
 695:   /**
 696:    * Get a resource as stream using this classloader or one of its parents.
 697:    * First calls <code>getResource()</code> and if that returns a URL to
 698:    * the resource then it calls and returns the InputStream given by
 699:    * <code>URL.openStream()</code>.
 700:    *
 701:    * <p>Subclasses should not override this method but should override
 702:    * <code>findResource()</code> which is called by this method.
 703:    *
 704:    * @param name the name of the resource relative to this classloader
 705:    * @return an InputStream to the resource, or null
 706:    * @since 1.1
 707:    */
 708:   public InputStream getResourceAsStream(String name)
 709:   {
 710:     try
 711:       {
 712:         URL url = getResource(name);
 713:         if (url == null)
 714:           return null;
 715:         return url.openStream();
 716:       }
 717:     catch (IOException e)
 718:       {
 719:         return null;
 720:       }
 721:   }
 722: 
 723:   /**
 724:    * Get a resource using the system classloader.
 725:    *
 726:    * @param name the name of the resource relative to the system classloader
 727:    * @return an input stream for the resource, or null
 728:    * @since 1.1
 729:    */
 730:   public static final InputStream getSystemResourceAsStream(String name)
 731:   {
 732:     try
 733:       {
 734:         URL url = getSystemResource(name);
 735:         if (url == null)
 736:           return null;
 737:         return url.openStream();
 738:       }
 739:     catch (IOException e)
 740:       {
 741:         return null;
 742:       }
 743:   }
 744: 
 745:   /**
 746:    * Returns the system classloader. The system classloader (also called
 747:    * the application classloader) is the classloader that was used to
 748:    * load the application classes on the classpath (given by the system
 749:    * property <code>java.class.path</code>. This is set as the context
 750:    * class loader for a thread. The system property
 751:    * <code>java.system.class.loader</code>, if defined, is taken to be the
 752:    * name of the class to use as the system class loader, which must have
 753:    * a public constructor which takes a ClassLoader as a parent; otherwise this
 754:    * uses gnu.java.lang.SystemClassLoader.
 755:    *
 756:    * <p>Note that this is different from the bootstrap classloader that
 757:    * actually loads all the real "system" classes (the bootstrap classloader
 758:    * is the parent of the returned system classloader).
 759:    *
 760:    * <p>A security check will be performed for
 761:    * <code>RuntimePermission("getClassLoader")</code> if the calling class
 762:    * is not a parent of the system class loader.
 763:    *
 764:    * @return the system class loader
 765:    * @throws SecurityException if the security check fails
 766:    * @throws IllegalStateException if this is called recursively
 767:    * @throws Error if <code>java.system.class.loader</code> fails to load
 768:    * @since 1.2
 769:    */
 770:   public static ClassLoader getSystemClassLoader()
 771:   {
 772:     // Check if we may return the system classloader
 773:     SecurityManager sm = System.getSecurityManager();
 774:     if (sm != null)
 775:       {
 776:     Class c = VMSecurityManager.getClassContext(ClassLoader.class)[0];
 777:     ClassLoader cl = c.getClassLoader();
 778:     if (cl != null && cl != systemClassLoader)
 779:       sm.checkPermission(new RuntimePermission("getClassLoader"));
 780:       }
 781: 
 782:     return systemClassLoader;
 783:   }
 784: 
 785:   /**
 786:    * Defines a new package and creates a Package object. The package should
 787:    * be defined before any class in the package is defined with
 788:    * <code>defineClass()</code>. The package should not yet be defined
 789:    * before in this classloader or in one of its parents (which means that
 790:    * <code>getPackage()</code> should return <code>null</code>). All
 791:    * parameters except the <code>name</code> of the package may be
 792:    * <code>null</code>.
 793:    *
 794:    * <p>Subclasses should call this method from their <code>findClass()</code>
 795:    * implementation before calling <code>defineClass()</code> on a Class
 796:    * in a not yet defined Package (which can be checked by calling
 797:    * <code>getPackage()</code>).
 798:    *
 799:    * @param name the name of the Package
 800:    * @param specTitle the name of the specification
 801:    * @param specVendor the name of the specification designer
 802:    * @param specVersion the version of this specification
 803:    * @param implTitle the name of the implementation
 804:    * @param implVendor the vendor that wrote this implementation
 805:    * @param implVersion the version of this implementation
 806:    * @param sealed if sealed the origin of the package classes
 807:    * @return the Package object for the specified package
 808:    * @throws IllegalArgumentException if the package name is null or it
 809:    *         was already defined by this classloader or one of its parents
 810:    * @see Package
 811:    * @since 1.2
 812:    */
 813:   protected Package definePackage(String name, String specTitle,
 814:                                   String specVendor, String specVersion,
 815:                                   String implTitle, String implVendor,
 816:                                   String implVersion, URL sealed)
 817:   {
 818:     if (getPackage(name) != null)
 819:       throw new IllegalArgumentException("Package " + name
 820:                                          + " already defined");
 821:     Package p = new Package(name, specTitle, specVendor, specVersion,
 822:                             implTitle, implVendor, implVersion, sealed);
 823:     synchronized (definedPackages)
 824:       {
 825:         definedPackages.put(name, p);
 826:       }
 827:     return p;
 828:   }
 829: 
 830:   /**
 831:    * Returns the Package object for the requested package name. It returns
 832:    * null when the package is not defined by this classloader or one of its
 833:    * parents.
 834:    *
 835:    * @param name the package name to find
 836:    * @return the package, if defined
 837:    * @since 1.2
 838:    */
 839:   protected Package getPackage(String name)
 840:   {
 841:     Package p;
 842:     if (parent == null)
 843:       p = VMClassLoader.getPackage(name);
 844:     else
 845:       p = parent.getPackage(name);
 846: 
 847:     if (p == null)
 848:       {
 849:     synchronized (definedPackages)
 850:       {
 851:         p = (Package) definedPackages.get(name);
 852:       }
 853:       }
 854:     return p;
 855:   }
 856: 
 857:   /**
 858:    * Returns all Package objects defined by this classloader and its parents.
 859:    *
 860:    * @return an array of all defined packages
 861:    * @since 1.2
 862:    */
 863:   protected Package[] getPackages()
 864:   {
 865:     // Get all our packages.
 866:     Package[] packages;
 867:     synchronized(definedPackages)
 868:       {
 869:         packages = new Package[definedPackages.size()];
 870:         definedPackages.values().toArray(packages);
 871:       }
 872: 
 873:     // If we have a parent get all packages defined by our parents.
 874:     Package[] parentPackages;
 875:     if (parent == null)
 876:       parentPackages = VMClassLoader.getPackages();
 877:     else
 878:       parentPackages = parent.getPackages();
 879: 
 880:     Package[] allPackages = new Package[parentPackages.length
 881:                     + packages.length];
 882:     System.arraycopy(parentPackages, 0, allPackages, 0,
 883:                      parentPackages.length);
 884:     System.arraycopy(packages, 0, allPackages, parentPackages.length,
 885:                      packages.length);
 886:     return allPackages;
 887:   }
 888: 
 889:   /**
 890:    * Called by <code>Runtime.loadLibrary()</code> to get an absolute path
 891:    * to a (system specific) library that was requested by a class loaded
 892:    * by this classloader. The default implementation returns
 893:    * <code>null</code>. It should be implemented by subclasses when they
 894:    * have a way to find the absolute path to a library. If this method
 895:    * returns null the library is searched for in the default locations
 896:    * (the directories listed in the <code>java.library.path</code> system
 897:    * property).
 898:    *
 899:    * @param name the (system specific) name of the requested library
 900:    * @return the full pathname to the requested library, or null
 901:    * @see Runtime#loadLibrary()
 902:    * @since 1.2
 903:    */
 904:   protected String findLibrary(String name)
 905:   {
 906:     return null;
 907:   }
 908: 
 909:   /**
 910:    * Set the default assertion status for classes loaded by this classloader,
 911:    * used unless overridden by a package or class request.
 912:    *
 913:    * @param enabled true to set the default to enabled
 914:    * @see #setClassAssertionStatus(String, boolean)
 915:    * @see #setPackageAssertionStatus(String, boolean)
 916:    * @see #clearAssertionStatus()
 917:    * @since 1.4
 918:    */
 919:   public void setDefaultAssertionStatus(boolean enabled)
 920:   {
 921:     defaultAssertionStatus = enabled;
 922:   }
 923:   
 924:   /**
 925:    * Set the default assertion status for packages, used unless overridden
 926:    * by a class request. This default also covers subpackages, unless they
 927:    * are also specified. The unnamed package should use null for the name.
 928:    *
 929:    * @param name the package (and subpackages) to affect
 930:    * @param enabled true to set the default to enabled
 931:    * @see #setDefaultAssertionStatus(String, boolean)
 932:    * @see #setClassAssertionStatus(String, boolean)
 933:    * @see #clearAssertionStatus()
 934:    * @since 1.4
 935:    */
 936:   public synchronized void setPackageAssertionStatus(String name,
 937:                                                      boolean enabled)
 938:   {
 939:     if (packageAssertionStatus == null)
 940:       packageAssertionStatus
 941:         = new HashMap(systemPackageAssertionStatus);
 942:     packageAssertionStatus.put(name, Boolean.valueOf(enabled));
 943:   }
 944:   
 945:   /**
 946:    * Set the default assertion status for a class. This only affects the
 947:    * status of top-level classes, any other string is harmless.
 948:    *
 949:    * @param name the class to affect
 950:    * @param enabled true to set the default to enabled
 951:    * @throws NullPointerException if name is null
 952:    * @see #setDefaultAssertionStatus(String, boolean)
 953:    * @see #setPackageAssertionStatus(String, boolean)
 954:    * @see #clearAssertionStatus()
 955:    * @since 1.4
 956:    */
 957:   public synchronized void setClassAssertionStatus(String name,
 958:                                                    boolean enabled)
 959:   {
 960:     if (classAssertionStatus == null)
 961:       classAssertionStatus = new HashMap(systemClassAssertionStatus);
 962:     // The toString() hack catches null, as required.
 963:     classAssertionStatus.put(name.toString(), Boolean.valueOf(enabled));
 964:   }
 965:   
 966:   /**
 967:    * Resets the default assertion status of this classloader, its packages
 968:    * and classes, all to false. This allows overriding defaults inherited
 969:    * from the command line.
 970:    *
 971:    * @see #setDefaultAssertionStatus(boolean)
 972:    * @see #setClassAssertionStatus(String, boolean)
 973:    * @see #setPackageAssertionStatus(String, boolean)
 974:    * @since 1.4
 975:    */
 976:   public synchronized void clearAssertionStatus()
 977:   {
 978:     defaultAssertionStatus = false;
 979:     packageAssertionStatus = new HashMap();
 980:     classAssertionStatus = new HashMap();
 981:   }
 982: 
 983:   /**
 984:    * Return true if this loader is either the specified class loader
 985:    * or an ancestor thereof.
 986:    * @param loader the class loader to check
 987:    */
 988:   final boolean isAncestorOf(ClassLoader loader)
 989:   {
 990:     while (loader != null)
 991:       {
 992:     if (this == loader)
 993:       return true;
 994:     loader = loader.parent;
 995:       }
 996:     return false;
 997:   }
 998: }