001/* ClassLoader.java -- responsible for loading classes into the VM
002   Copyright (C) 1998, 1999, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
003
004This file is part of GNU Classpath.
005
006GNU Classpath is free software; you can redistribute it and/or modify
007it under the terms of the GNU General Public License as published by
008the Free Software Foundation; either version 2, or (at your option)
009any later version.
010
011GNU Classpath is distributed in the hope that it will be useful, but
012WITHOUT ANY WARRANTY; without even the implied warranty of
013MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014General Public License for more details.
015
016You should have received a copy of the GNU General Public License
017along with GNU Classpath; see the file COPYING.  If not, write to the
018Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
01902110-1301 USA.
020
021Linking this library statically or dynamically with other modules is
022making a combined work based on this library.  Thus, the terms and
023conditions of the GNU General Public License cover the whole
024combination.
025
026As a special exception, the copyright holders of this library give you
027permission to link this library with independent modules to produce an
028executable, regardless of the license terms of these independent
029modules, and to copy and distribute the resulting executable under
030terms of your choice, provided that you also meet, for each linked
031independent module, the terms and conditions of the license of that
032module.  An independent module is a module which is not derived from
033or based on this library.  If you modify this library, you may extend
034this exception to your version of the library, but you are not
035obligated to do so.  If you do not wish to do so, delete this
036exception statement from your version. */
037
038
039package java.lang;
040
041import gnu.classpath.SystemProperties;
042import gnu.classpath.VMStackWalker;
043import gnu.java.util.DoubleEnumeration;
044import gnu.java.util.EmptyEnumeration;
045
046import java.io.IOException;
047import java.io.InputStream;
048import java.lang.ref.WeakReference;
049import java.net.URL;
050import java.nio.ByteBuffer;
051import java.security.CodeSource;
052import java.security.PermissionCollection;
053import java.security.Policy;
054import java.security.ProtectionDomain;
055import java.util.Enumeration;
056import java.util.HashMap;
057import java.util.Map;
058
059import java.util.concurrent.ConcurrentHashMap;
060import java.lang.annotation.Annotation;
061
062/**
063 * The ClassLoader is a way of customizing the way Java gets its classes
064 * and loads them into memory.  The verifier and other standard Java things
065 * still run, but the ClassLoader is allowed great flexibility in determining
066 * where to get the classfiles and when to load and resolve them. For that
067 * matter, a custom ClassLoader can perform on-the-fly code generation or
068 * modification!
069 *
070 * <p>Every classloader has a parent classloader that is consulted before
071 * the 'child' classloader when classes or resources should be loaded.
072 * This is done to make sure that classes can be loaded from an hierarchy of
073 * multiple classloaders and classloaders do not accidentially redefine
074 * already loaded classes by classloaders higher in the hierarchy.
075 *
076 * <p>The grandparent of all classloaders is the bootstrap classloader, which
077 * loads all the standard system classes as implemented by GNU Classpath. The
078 * other special classloader is the system classloader (also called
079 * application classloader) that loads all classes from the CLASSPATH
080 * (<code>java.class.path</code> system property). The system classloader
081 * is responsible for finding the application classes from the classpath,
082 * and delegates all requests for the standard library classes to its parent
083 * the bootstrap classloader. Most programs will load all their classes
084 * through the system classloaders.
085 *
086 * <p>The bootstrap classloader in GNU Classpath is implemented as a couple of
087 * static (native) methods on the package private class
088 * <code>java.lang.VMClassLoader</code>, the system classloader is an
089 * instance of <code>gnu.java.lang.SystemClassLoader</code>
090 * (which is a subclass of <code>java.net.URLClassLoader</code>).
091 *
092 * <p>Users of a <code>ClassLoader</code> will normally just use the methods
093 * <ul>
094 *  <li> <code>loadClass()</code> to load a class.</li>
095 *  <li> <code>getResource()</code> or <code>getResourceAsStream()</code>
096 *       to access a resource.</li>
097 *  <li> <code>getResources()</code> to get an Enumeration of URLs to all
098 *       the resources provided by the classloader and its parents with the
099 *       same name.</li>
100 * </ul>
101 *
102 * <p>Subclasses should implement the methods
103 * <ul>
104 *  <li> <code>findClass()</code> which is called by <code>loadClass()</code>
105 *       when the parent classloader cannot provide a named class.</li>
106 *  <li> <code>findResource()</code> which is called by
107 *       <code>getResource()</code> when the parent classloader cannot provide
108 *       a named resource.</li>
109 *  <li> <code>findResources()</code> which is called by
110 *       <code>getResource()</code> to combine all the resources with the
111 *       same name from the classloader and its parents.</li>
112 *  <li> <code>findLibrary()</code> which is called by
113 *       <code>Runtime.loadLibrary()</code> when a class defined by the
114 *       classloader wants to load a native library.</li>
115 * </ul>
116 *
117 * @author John Keiser
118 * @author Mark Wielaard
119 * @author Eric Blake (ebb9@email.byu.edu)
120 * @see Class
121 * @since 1.0
122 */
123public abstract class ClassLoader
124{
125  /**
126   * All classes loaded by this classloader. VM's may choose to implement
127   * this cache natively; but it is here available for use if necessary. It
128   * is not private in order to allow native code (and trusted subclasses)
129   * access to this field.
130   */
131  final HashMap loadedClasses = new HashMap();
132
133  /**
134   * Loading constraints registered with this classloader.  This maps
135   * a class name to a weak reference to a class.  When the reference
136   * is non-null, it means that a reference to the name must resolve
137   * to the indicated class.
138   */
139  final HashMap<String, WeakReference<Class>> loadingConstraints
140    = new HashMap<String, WeakReference<Class>>();
141
142  /**
143   * All packages defined by this classloader. It is not private in order to
144   * allow native code (and trusted subclasses) access to this field.
145   */
146  final HashMap definedPackages = new HashMap();
147
148  /**
149   * The classloader that is consulted before this classloader.
150   * If null then the parent is the bootstrap classloader.
151   */
152  private final ClassLoader parent;
153
154  /**
155   * This is true if this classloader was successfully initialized.
156   * This flag is needed to avoid a class loader attack: even if the
157   * security manager rejects an attempt to create a class loader, the
158   * malicious class could have a finalize method which proceeds to
159   * define classes.
160   */
161  private final boolean initialized;
162
163  /**
164   * System/Application classloader: defaults to an instance of
165   * gnu.java.lang.SystemClassLoader, unless the first invocation of
166   * getSystemClassLoader loads another class loader because of the
167   * java.system.class.loader property. The initialization of this field
168   * is somewhat circular - getSystemClassLoader() checks whether this
169   * field is null in order to bypass a security check.
170   */
171  static final ClassLoader systemClassLoader =
172    VMClassLoader.getSystemClassLoader();
173
174  /**
175   * This cache maps from a Class to its associated annotations.  It's
176   * declared here so that when this class loader becomes unreachable,
177   * so will the corresponding cache.
178   */
179
180  private final ConcurrentHashMap<AnnotationsKey,Object[]> 
181    declaredAnnotations 
182      = new ConcurrentHashMap<AnnotationsKey,Object[]>();
183  
184  static final class AnnotationsKey
185  {
186    final int /* jv_attr_type */ member_type;
187    final int member_index;
188    final int /* jv_attr_kind */ kind_req;
189    final Class declaringClass;
190    final int hashCode;
191
192    public AnnotationsKey (Class declaringClass,
193                           int member_type,
194                           int member_index,
195                           int kind_req)
196    {
197      this.member_type = member_type;
198      this.member_index = member_index;
199      this.kind_req = kind_req;
200      this.declaringClass = declaringClass;
201      hashCode = (member_type ^ member_index ^ kind_req
202                  ^ declaringClass.hashCode());
203    }
204
205    public boolean equals(Object obj)
206    {
207      AnnotationsKey other = (AnnotationsKey)obj;
208      return (this.member_type == other.member_type
209              && this.member_index == other.member_index
210              && this.kind_req == other.kind_req
211              && this.declaringClass == other.declaringClass);
212    }
213
214    public int hashCode()
215    {
216      return hashCode;
217    }
218
219    public static final Annotation[] NIL = new Annotation[0];
220  }
221  
222  final Object[] getDeclaredAnnotations(Class declaringClass,
223                                        int member_type,
224                                        int member_index,
225                                        int kind_req)
226  {
227    Object[] result 
228      = declaredAnnotations.get (new AnnotationsKey
229                                 (declaringClass,
230                                  member_type,
231                                  member_index,
232                                  kind_req));
233    if (result != AnnotationsKey.NIL && result != null)
234      return (Object[])result.clone();
235    return null;
236  }
237
238  final Object[] putDeclaredAnnotations(Class declaringClass,
239                                        int member_type,
240                                        int member_index,
241                                        int kind_req,
242                                        Object[] annotations)
243  {
244    declaredAnnotations.put 
245      (new AnnotationsKey
246       (declaringClass, member_type,
247        member_index, kind_req), 
248       annotations == null ? AnnotationsKey.NIL : annotations);
249
250    return annotations == null ? null : (Object[])annotations.clone();
251  }
252
253  static
254  {
255    // Find out if we have to install a default security manager. Note
256    // that this is done here because we potentially need the system
257    // class loader to load the security manager and note also that we
258    // don't need the security manager until the system class loader
259    // is created.  If the runtime chooses to use a class loader that
260    // doesn't have the system class loader as its parent, it is
261    // responsible for setting up a security manager before doing so.
262    String secman = SystemProperties.getProperty("java.security.manager");
263    if (secman != null && SecurityManager.current == null)
264    {
265      if (secman.equals("") || secman.equals("default"))
266      {
267        SecurityManager.current = new SecurityManager();
268      }
269      else
270      {
271        try
272        {
273          Class cl = Class.forName(secman, false, systemClassLoader);
274          SecurityManager.current = (SecurityManager) cl.newInstance();
275        }
276        catch (Exception x)
277        {
278          throw (InternalError)
279            new InternalError("Unable to create SecurityManager")
280                .initCause(x);
281        }
282      }
283    }
284  }
285
286  /**
287   * The default protection domain, used when defining a class with a null
288   * paramter for the domain.
289   */
290  static final ProtectionDomain defaultProtectionDomain;
291  static
292  {
293    CodeSource cs = new CodeSource(null, null);
294    PermissionCollection perm = Policy.getPolicy().getPermissions(cs);
295    defaultProtectionDomain = new ProtectionDomain(cs, perm);
296  }
297
298  /**
299   * The desired assertion status of classes loaded by this loader, if not
300   * overridden by package or class instructions.
301   */
302  // Package visible for use by Class.
303  boolean defaultAssertionStatus = VMClassLoader.defaultAssertionStatus();
304
305  /**
306   * The command-line state of the package assertion status overrides. This
307   * map is never modified, so it does not need to be synchronized.
308   */
309  // Package visible for use by Class.
310  static final Map systemPackageAssertionStatus
311    = VMClassLoader.packageAssertionStatus();
312
313  /**
314   * The map of package assertion status overrides, or null if no package
315   * overrides have been specified yet. The values of the map should be
316   * Boolean.TRUE or Boolean.FALSE, and the unnamed package is represented
317   * by the null key. This map must be synchronized on this instance.
318   */
319  // Package visible for use by Class.
320  Map packageAssertionStatus;
321
322  /**
323   * The command-line state of the class assertion status overrides. This
324   * map is never modified, so it does not need to be synchronized.
325   */
326  // Package visible for use by Class.
327  static final Map systemClassAssertionStatus
328    = VMClassLoader.classAssertionStatus();
329
330  /**
331   * The map of class assertion status overrides, or null if no class
332   * overrides have been specified yet. The values of the map should be
333   * Boolean.TRUE or Boolean.FALSE. This map must be synchronized on this
334   * instance.
335   */
336  // Package visible for use by Class.
337  Map classAssertionStatus;
338
339  /**
340   * Create a new ClassLoader with as parent the system classloader. There
341   * may be a security check for <code>checkCreateClassLoader</code>.
342   *
343   * @throws SecurityException if the security check fails
344   */
345  protected ClassLoader() throws SecurityException
346  {
347    this(systemClassLoader);
348  }
349
350  /**
351   * Create a new ClassLoader with the specified parent. The parent will
352   * be consulted when a class or resource is requested through
353   * <code>loadClass()</code> or <code>getResource()</code>. Only when the
354   * parent classloader cannot provide the requested class or resource the
355   * <code>findClass()</code> or <code>findResource()</code> method
356   * of this classloader will be called. There may be a security check for
357   * <code>checkCreateClassLoader</code>.
358   *
359   * @param parent the classloader's parent, or null for the bootstrap
360   *        classloader
361   * @throws SecurityException if the security check fails
362   * @since 1.2
363   */
364  protected ClassLoader(ClassLoader parent)
365  {
366    // May we create a new classloader?
367    SecurityManager sm = System.getSecurityManager();
368    if (sm != null)
369      sm.checkCreateClassLoader();
370    this.parent = parent;
371    this.initialized = true;
372  }
373
374  /**
375   * Load a class using this ClassLoader or its parent, without resolving
376   * it. Calls <code>loadClass(name, false)</code>.
377   *
378   * <p>Subclasses should not override this method but should override
379   * <code>findClass()</code> which is called by this method.</p>
380   *
381   * @param name the name of the class relative to this ClassLoader
382   * @return the loaded class
383   * @throws ClassNotFoundException if the class cannot be found
384   */
385  public Class<?> loadClass(String name) throws ClassNotFoundException
386  {
387    return loadClass(name, false);
388  }
389
390  private native Class loadClassFromSig(String name)
391    throws ClassNotFoundException;
392
393  /**
394   * Load a class using this ClassLoader or its parent, possibly resolving
395   * it as well using <code>resolveClass()</code>. It first tries to find
396   * out if the class has already been loaded through this classloader by
397   * calling <code>findLoadedClass()</code>. Then it calls
398   * <code>loadClass()</code> on the parent classloader (or when there is
399   * no parent it uses the VM bootclassloader). If the class is still
400   * not loaded it tries to create a new class by calling
401   * <code>findClass()</code>. Finally when <code>resolve</code> is
402   * <code>true</code> it also calls <code>resolveClass()</code> on the
403   * newly loaded class.
404   *
405   * <p>Subclasses should not override this method but should override
406   * <code>findClass()</code> which is called by this method.</p>
407   *
408   * @param name the fully qualified name of the class to load
409   * @param resolve whether or not to resolve the class
410   * @return the loaded class
411   * @throws ClassNotFoundException if the class cannot be found
412   */
413  protected synchronized Class<?> loadClass(String name, boolean resolve)
414    throws ClassNotFoundException
415  {
416    SecurityManager sm = SecurityManager.current;
417    if (sm != null)
418      {
419        int lastDot = name.lastIndexOf('.');
420        if (lastDot != -1)
421          sm.checkPackageAccess(name.substring(0, lastDot));
422      }
423
424    // Arrays are handled specially.
425    Class c;
426    if (name.length() > 0 && name.charAt(0) == '[')
427      c = loadClassFromSig(name);
428    else
429      {
430        // Have we already loaded this class?
431        c = findLoadedClass(name);
432        if (c == null)
433          {
434            // Can the class be loaded by a parent?
435            try
436              {
437                if (parent == null)
438                  {
439                    c = VMClassLoader.loadClass(name, resolve);
440                    if (c != null)
441                      return c;
442                  }
443                else
444                  {
445                    return parent.loadClass(name, resolve);
446                  }
447              }
448            catch (ClassNotFoundException e)
449              {
450              }
451            // Still not found, we have to do it ourself.
452            c = findClass(name);
453          }
454      }
455    if (resolve)
456      resolveClass(c);
457    return c;
458  }
459
460  /**
461   * Called for every class name that is needed but has not yet been
462   * defined by this classloader or one of its parents. It is called by
463   * <code>loadClass()</code> after both <code>findLoadedClass()</code> and
464   * <code>parent.loadClass()</code> couldn't provide the requested class.
465   *
466   * <p>The default implementation throws a
467   * <code>ClassNotFoundException</code>. Subclasses should override this
468   * method. An implementation of this method in a subclass should get the
469   * class bytes of the class (if it can find them), if the package of the
470   * requested class doesn't exist it should define the package and finally
471   * it should call define the actual class. It does not have to resolve the
472   * class. It should look something like the following:<br>
473   *
474   * <pre>
475   * // Get the bytes that describe the requested class
476   * byte[] classBytes = classLoaderSpecificWayToFindClassBytes(name);
477   * // Get the package name
478   * int lastDot = name.lastIndexOf('.');
479   * if (lastDot != -1)
480   *   {
481   *     String packageName = name.substring(0, lastDot);
482   *     // Look if the package already exists
483   *     if (getPackage(packageName) == null)
484   *       {
485   *         // define the package
486   *         definePackage(packageName, ...);
487   *       }
488   *   }
489   * // Define and return the class
490   *  return defineClass(name, classBytes, 0, classBytes.length);
491   * </pre>
492   *
493   * <p><code>loadClass()</code> makes sure that the <code>Class</code>
494   * returned by <code>findClass()</code> will later be returned by
495   * <code>findLoadedClass()</code> when the same class name is requested.
496   *
497   * @param name class name to find (including the package name)
498   * @return the requested Class
499   * @throws ClassNotFoundException when the class can not be found
500   * @since 1.2
501   */
502  protected Class<?> findClass(String name) throws ClassNotFoundException
503  {
504    throw new ClassNotFoundException(name);
505  }
506
507  /**
508   * Helper to define a class using a string of bytes. This version is not
509   * secure.
510   *
511   * @param data the data representing the classfile, in classfile format
512   * @param offset the offset into the data where the classfile starts
513   * @param len the length of the classfile data in the array
514   * @return the class that was defined
515   * @throws ClassFormatError if data is not in proper classfile format
516   * @throws IndexOutOfBoundsException if offset or len is negative, or
517   *         offset + len exceeds data
518   * @deprecated use {@link #defineClass(String, byte[], int, int)} instead
519   */
520  protected final Class<?> defineClass(byte[] data, int offset, int len)
521    throws ClassFormatError
522  {
523    return defineClass(null, data, offset, len);
524  }
525
526  /**
527   * Helper to define a class using a string of bytes without a
528   * ProtectionDomain. Subclasses should call this method from their
529   * <code>findClass()</code> implementation. The name should use '.'
530   * separators, and discard the trailing ".class".  The default protection
531   * domain has the permissions of
532   * <code>Policy.getPolicy().getPermissions(new CodeSource(null, null))</code>.
533   *
534   * @param name the name to give the class, or null if unknown
535   * @param data the data representing the classfile, in classfile format
536   * @param offset the offset into the data where the classfile starts
537   * @param len the length of the classfile data in the array
538   * @return the class that was defined
539   * @throws ClassFormatError if data is not in proper classfile format
540   * @throws IndexOutOfBoundsException if offset or len is negative, or
541   *         offset + len exceeds data
542   * @throws SecurityException if name starts with "java."
543   * @since 1.1
544   */
545  protected final Class<?> defineClass(String name, byte[] data, int offset,
546                                       int len) throws ClassFormatError
547  {
548    return defineClass(name, data, offset, len, null);
549  }
550
551  /**
552   * Helper to define a class using a string of bytes. Subclasses should call
553   * this method from their <code>findClass()</code> implementation. If the
554   * domain is null, the default of
555   * <code>Policy.getPolicy().getPermissions(new CodeSource(null, null))</code>
556   * is used. Once a class has been defined in a package, all further classes
557   * in that package must have the same set of certificates or a
558   * SecurityException is thrown.
559   *
560   * @param name the name to give the class.  null if unknown
561   * @param data the data representing the classfile, in classfile format
562   * @param offset the offset into the data where the classfile starts
563   * @param len the length of the classfile data in the array
564   * @param domain the ProtectionDomain to give to the class, null for the
565   *        default protection domain
566   * @return the class that was defined
567   * @throws ClassFormatError if data is not in proper classfile format
568   * @throws IndexOutOfBoundsException if offset or len is negative, or
569   *         offset + len exceeds data
570   * @throws SecurityException if name starts with "java.", or if certificates
571   *         do not match up
572   * @since 1.2
573   */
574  protected final synchronized Class<?> defineClass(String name, byte[] data,
575                                                    int offset, int len,
576                                                    ProtectionDomain domain)
577    throws ClassFormatError
578  {
579    checkInitialized();
580    if (domain == null)
581      domain = defaultProtectionDomain;
582    
583    Class retval = VMClassLoader.defineClass(this, name, data,
584                                             offset, len, domain);
585    loadedClasses.put(retval.getName(), retval);
586    return retval;
587  }
588
589  /**
590   * Helper to define a class using the contents of a byte buffer. If
591   * the domain is null, the default of
592   * <code>Policy.getPolicy().getPermissions(new CodeSource(null,
593   * null))</code> is used. Once a class has been defined in a
594   * package, all further classes in that package must have the same
595   * set of certificates or a SecurityException is thrown.
596   *
597   * @param name the name to give the class.  null if unknown
598   * @param buf a byte buffer containing bytes that form a class.
599   * @param domain the ProtectionDomain to give to the class, null for the
600   *        default protection domain
601   * @return the class that was defined
602   * @throws ClassFormatError if data is not in proper classfile format
603   * @throws NoClassDefFoundError if the supplied name is not the same as
604   *                              the one specified by the byte buffer.
605   * @throws SecurityException if name starts with "java.", or if certificates
606   *         do not match up
607   * @since 1.5
608   */
609  protected final Class<?> defineClass(String name, ByteBuffer buf,
610                                       ProtectionDomain domain)
611    throws ClassFormatError
612  {
613    byte[] data = new byte[buf.remaining()];
614    buf.get(data);
615    return defineClass(name, data, 0, data.length, domain);
616  }
617
618  /**
619   * Links the class, if that has not already been done. Linking basically
620   * resolves all references to other classes made by this class.
621   *
622   * @param c the class to resolve
623   * @throws NullPointerException if c is null
624   * @throws LinkageError if linking fails
625   */
626  protected final void resolveClass(Class<?> c)
627  {
628    checkInitialized();
629    VMClassLoader.resolveClass(c);
630  }
631
632  /**
633   * Helper to find a Class using the system classloader, possibly loading it.
634   * A subclass usually does not need to call this, if it correctly
635   * overrides <code>findClass(String)</code>.
636   *
637   * @param name the name of the class to find
638   * @return the found class
639   * @throws ClassNotFoundException if the class cannot be found
640   */
641  protected final Class<?> findSystemClass(String name)
642    throws ClassNotFoundException
643  {
644    checkInitialized();
645    return Class.forName(name, false, systemClassLoader);
646  }
647
648  /**
649   * Returns the parent of this classloader. If the parent of this
650   * classloader is the bootstrap classloader then this method returns
651   * <code>null</code>. A security check may be performed on
652   * <code>RuntimePermission("getClassLoader")</code>.
653   *
654   * @return the parent <code>ClassLoader</code>
655   * @throws SecurityException if the security check fails
656   * @since 1.2
657   */
658  public final ClassLoader getParent()
659  {
660    // Check if we may return the parent classloader.
661    SecurityManager sm = System.getSecurityManager();
662    if (sm != null)
663      {
664        ClassLoader cl = VMStackWalker.getCallingClassLoader();
665        if (cl != null && ! cl.isAncestorOf(this))
666          sm.checkPermission(new RuntimePermission("getClassLoader"));
667      }
668    return parent;
669  }
670
671  /**
672   * Helper to set the signers of a class. This should be called after
673   * defining the class.
674   *
675   * @param c the Class to set signers of
676   * @param signers the signers to set
677   * @since 1.1
678   */
679  protected final void setSigners(Class<?> c, Object[] signers)
680  {
681    checkInitialized();
682    c.setSigners(signers);
683  }
684
685  /**
686   * Helper to find an already-loaded class in this ClassLoader.
687   *
688   * @param name the name of the class to find
689   * @return the found Class, or null if it is not found
690   * @since 1.1
691   */
692  protected final synchronized Class<?> findLoadedClass(String name)
693  {
694    checkInitialized();
695    // NOTE: If the VM is keeping its own cache, it may make sense to have
696    // this method be native.
697    return (Class) loadedClasses.get(name);
698  }
699
700  /**
701   * Get the URL to a resource using this classloader or one of its parents.
702   * First tries to get the resource by calling <code>getResource()</code>
703   * on the parent classloader. If the parent classloader returns null then
704   * it tries finding the resource by calling <code>findResource()</code> on
705   * this classloader. The resource name should be separated by '/' for path
706   * elements.
707   *
708   * <p>Subclasses should not override this method but should override
709   * <code>findResource()</code> which is called by this method.
710   *
711   * @param name the name of the resource relative to this classloader
712   * @return the URL to the resource or null when not found
713   */
714  public URL getResource(String name)
715  {
716    URL result;
717
718    if (parent == null)
719      result = VMClassLoader.getResource(name);
720    else
721      result = parent.getResource(name);
722
723    if (result == null)
724      result = findResource(name);
725    return result;
726  }
727
728  /**
729   * Returns an Enumeration of all resources with a given name that can
730   * be found by this classloader and its parents. Certain classloaders
731   * (such as the URLClassLoader when given multiple jar files) can have
732   * multiple resources with the same name that come from multiple locations.
733   * It can also occur that a parent classloader offers a resource with a
734   * certain name and the child classloader also offers a resource with that
735   * same name. <code>getResource()</code> only offers the first resource (of the
736   * parent) with a given name. This method lists all resources with the
737   * same name. The name should use '/' as path separators.
738   *
739   * <p>The Enumeration is created by first calling <code>getResources()</code>
740   * on the parent classloader and then calling <code>findResources()</code>
741   * on this classloader.</p>
742   *
743   * @param name the resource name
744   * @return an enumaration of all resources found
745   * @throws IOException if I/O errors occur in the process
746   * @since 1.2
747   * @specnote this was <code>final</code> prior to 1.5
748   */
749  public Enumeration<URL> getResources(String name) throws IOException
750  {
751    Enumeration<URL> parentResources;
752    if (parent == null)
753      parentResources = VMClassLoader.getResources(name);
754    else
755      parentResources = parent.getResources(name);
756    return new DoubleEnumeration<URL>(parentResources, findResources(name));
757  }
758
759  /**
760   * Called whenever all locations of a named resource are needed.
761   * It is called by <code>getResources()</code> after it has called
762   * <code>parent.getResources()</code>. The results are combined by
763   * the <code>getResources()</code> method.
764   *
765   * <p>The default implementation always returns an empty Enumeration.
766   * Subclasses should override it when they can provide an Enumeration of
767   * URLs (possibly just one element) to the named resource.
768   * The first URL of the Enumeration should be the same as the one
769   * returned by <code>findResource</code>.
770   *
771   * @param name the name of the resource to be found
772   * @return a possibly empty Enumeration of URLs to the named resource
773   * @throws IOException if I/O errors occur in the process
774   * @since 1.2
775   */
776  protected Enumeration<URL> findResources(String name) throws IOException
777  {
778    return new EmptyEnumeration<URL>();
779  }
780
781  /**
782   * Called whenever a resource is needed that could not be provided by
783   * one of the parents of this classloader. It is called by
784   * <code>getResource()</code> after <code>parent.getResource()</code>
785   * couldn't provide the requested resource.
786   *
787   * <p>The default implementation always returns null. Subclasses should
788   * override this method when they can provide a way to return a URL
789   * to a named resource.
790   *
791   * @param name the name of the resource to be found
792   * @return a URL to the named resource or null when not found
793   * @since 1.2
794   */
795  protected URL findResource(String name)
796  {
797    return null;
798  }
799
800  /**
801   * Get the URL to a resource using the system classloader.
802   *
803   * @param name the name of the resource relative to the system classloader
804   * @return the URL to the resource
805   * @since 1.1
806   */
807  public static final URL getSystemResource(String name)
808  {
809    return systemClassLoader.getResource(name);
810  }
811
812  /**
813   * Get an Enumeration of URLs to resources with a given name using the
814   * the system classloader. The enumeration firsts lists the resources with
815   * the given name that can be found by the bootstrap classloader followed
816   * by the resources with the given name that can be found on the classpath.
817   *
818   * @param name the name of the resource relative to the system classloader
819   * @return an Enumeration of URLs to the resources
820   * @throws IOException if I/O errors occur in the process
821   * @since 1.2
822   */
823  public static Enumeration<URL> getSystemResources(String name)
824    throws IOException
825  {
826    return systemClassLoader.getResources(name);
827  }
828
829  /**
830   * Get a resource as stream using this classloader or one of its parents.
831   * First calls <code>getResource()</code> and if that returns a URL to
832   * the resource then it calls and returns the InputStream given by
833   * <code>URL.openStream()</code>.
834   *
835   * <p>Subclasses should not override this method but should override
836   * <code>findResource()</code> which is called by this method.
837   *
838   * @param name the name of the resource relative to this classloader
839   * @return an InputStream to the resource, or null
840   * @since 1.1
841   */
842  public InputStream getResourceAsStream(String name)
843  {
844    try
845      {
846        URL url = getResource(name);
847        if (url == null)
848          return null;
849        return url.openStream();
850      }
851    catch (IOException e)
852      {
853        return null;
854      }
855  }
856
857  /**
858   * Get a resource using the system classloader.
859   *
860   * @param name the name of the resource relative to the system classloader
861   * @return an input stream for the resource, or null
862   * @since 1.1
863   */
864  public static final InputStream getSystemResourceAsStream(String name)
865  {
866    try
867      {
868        URL url = getSystemResource(name);
869        if (url == null)
870          return null;
871        return url.openStream();
872      }
873    catch (IOException e)
874      {
875        return null;
876      }
877  }
878
879  /**
880   * Returns the system classloader. The system classloader (also called
881   * the application classloader) is the classloader that is used to
882   * load the application classes on the classpath (given by the system
883   * property <code>java.class.path</code>. This is set as the context
884   * class loader for a thread. The system property
885   * <code>java.system.class.loader</code>, if defined, is taken to be the
886   * name of the class to use as the system class loader, which must have
887   * a public constructor which takes a ClassLoader as a parent. The parent
888   * class loader passed in the constructor is the default system class
889   * loader.
890   *
891   * <p>Note that this is different from the bootstrap classloader that
892   * actually loads all the real "system" classes (the bootstrap classloader
893   * is the parent of the returned system classloader).
894   *
895   * <p>A security check will be performed for
896   * <code>RuntimePermission("getClassLoader")</code> if the calling class
897   * is not a parent of the system class loader.
898   *
899   * @return the system class loader
900   * @throws SecurityException if the security check fails
901   * @throws IllegalStateException if this is called recursively
902   * @throws Error if <code>java.system.class.loader</code> fails to load
903   * @since 1.2
904   */
905  public static ClassLoader getSystemClassLoader()
906  {
907    // Check if we may return the system classloader
908    SecurityManager sm = System.getSecurityManager();
909    if (sm != null)
910      {
911        ClassLoader cl = VMStackWalker.getCallingClassLoader();
912        if (cl != null && cl != systemClassLoader)
913          sm.checkPermission(new RuntimePermission("getClassLoader"));
914      }
915
916    return systemClassLoader;
917  }
918
919  /**
920   * Defines a new package and creates a Package object. The package should
921   * be defined before any class in the package is defined with
922   * <code>defineClass()</code>. The package should not yet be defined
923   * before in this classloader or in one of its parents (which means that
924   * <code>getPackage()</code> should return <code>null</code>). All
925   * parameters except the <code>name</code> of the package may be
926   * <code>null</code>.
927   *
928   * <p>Subclasses should call this method from their <code>findClass()</code>
929   * implementation before calling <code>defineClass()</code> on a Class
930   * in a not yet defined Package (which can be checked by calling
931   * <code>getPackage()</code>).
932   *
933   * @param name the name of the Package
934   * @param specTitle the name of the specification
935   * @param specVendor the name of the specification designer
936   * @param specVersion the version of this specification
937   * @param implTitle the name of the implementation
938   * @param implVendor the vendor that wrote this implementation
939   * @param implVersion the version of this implementation
940   * @param sealed if sealed the origin of the package classes
941   * @return the Package object for the specified package
942   * @throws IllegalArgumentException if the package name is null or it
943   *         was already defined by this classloader or one of its parents
944   * @see Package
945   * @since 1.2
946   */
947  protected Package definePackage(String name, String specTitle,
948                                  String specVendor, String specVersion,
949                                  String implTitle, String implVendor,
950                                  String implVersion, URL sealed)
951  {
952    if (getPackage(name) != null)
953      throw new IllegalArgumentException("Package " + name
954                                         + " already defined");
955    Package p = new Package(name, specTitle, specVendor, specVersion,
956                            implTitle, implVendor, implVersion, sealed, this);
957    synchronized (definedPackages)
958      {
959        definedPackages.put(name, p);
960      }
961    return p;
962  }
963
964  /**
965   * Returns the Package object for the requested package name. It returns
966   * null when the package is not defined by this classloader or one of its
967   * parents.
968   *
969   * @param name the package name to find
970   * @return the package, if defined
971   * @since 1.2
972   */
973  protected Package getPackage(String name)
974  {
975    Package p;
976    if (parent == null)
977      p = VMClassLoader.getPackage(name);
978    else
979      p = parent.getPackage(name);
980
981    if (p == null)
982      {
983        synchronized (definedPackages)
984          {
985            p = (Package) definedPackages.get(name);
986          }
987      }
988    return p;
989  }
990
991  /**
992   * Returns all Package objects defined by this classloader and its parents.
993   *
994   * @return an array of all defined packages
995   * @since 1.2
996   */
997  protected Package[] getPackages()
998  {
999    // Get all our packages.
1000    Package[] packages;
1001    synchronized(definedPackages)
1002      {
1003        packages = new Package[definedPackages.size()];
1004        definedPackages.values().toArray(packages);
1005      }
1006
1007    // If we have a parent get all packages defined by our parents.
1008    Package[] parentPackages;
1009    if (parent == null)
1010      parentPackages = VMClassLoader.getPackages();
1011    else
1012      parentPackages = parent.getPackages();
1013
1014    Package[] allPackages = new Package[parentPackages.length
1015                                        + packages.length];
1016    System.arraycopy(parentPackages, 0, allPackages, 0,
1017                     parentPackages.length);
1018    System.arraycopy(packages, 0, allPackages, parentPackages.length,
1019                     packages.length);
1020    return allPackages;
1021  }
1022
1023  /**
1024   * Called by <code>Runtime.loadLibrary()</code> to get an absolute path
1025   * to a (system specific) library that was requested by a class loaded
1026   * by this classloader. The default implementation returns
1027   * <code>null</code>. It should be implemented by subclasses when they
1028   * have a way to find the absolute path to a library. If this method
1029   * returns null the library is searched for in the default locations
1030   * (the directories listed in the <code>java.library.path</code> system
1031   * property).
1032   *
1033   * @param name the (system specific) name of the requested library
1034   * @return the full pathname to the requested library, or null
1035   * @see Runtime#loadLibrary(String)
1036   * @since 1.2
1037   */
1038  protected String findLibrary(String name)
1039  {
1040    return null;
1041  }
1042
1043  /**
1044   * Set the default assertion status for classes loaded by this classloader,
1045   * used unless overridden by a package or class request.
1046   *
1047   * @param enabled true to set the default to enabled
1048   * @see #setClassAssertionStatus(String, boolean)
1049   * @see #setPackageAssertionStatus(String, boolean)
1050   * @see #clearAssertionStatus()
1051   * @since 1.4
1052   */
1053  public void setDefaultAssertionStatus(boolean enabled)
1054  {
1055    defaultAssertionStatus = enabled;
1056  }
1057  
1058  /**
1059   * Set the default assertion status for packages, used unless overridden
1060   * by a class request. This default also covers subpackages, unless they
1061   * are also specified. The unnamed package should use null for the name.
1062   *
1063   * @param name the package (and subpackages) to affect
1064   * @param enabled true to set the default to enabled
1065   * @see #setDefaultAssertionStatus(boolean)
1066   * @see #setClassAssertionStatus(String, boolean)
1067   * @see #clearAssertionStatus()
1068   * @since 1.4
1069   */
1070  public synchronized void setPackageAssertionStatus(String name,
1071                                                     boolean enabled)
1072  {
1073    if (packageAssertionStatus == null)
1074      packageAssertionStatus
1075        = new HashMap(systemPackageAssertionStatus);
1076    packageAssertionStatus.put(name, Boolean.valueOf(enabled));
1077  }
1078  
1079  /**
1080   * Set the default assertion status for a class. This only affects the
1081   * status of top-level classes, any other string is harmless.
1082   *
1083   * @param name the class to affect
1084   * @param enabled true to set the default to enabled
1085   * @throws NullPointerException if name is null
1086   * @see #setDefaultAssertionStatus(boolean)
1087   * @see #setPackageAssertionStatus(String, boolean)
1088   * @see #clearAssertionStatus()
1089   * @since 1.4
1090   */
1091  public synchronized void setClassAssertionStatus(String name,
1092                                                   boolean enabled)
1093  {
1094    if (classAssertionStatus == null)
1095      classAssertionStatus = new HashMap(systemClassAssertionStatus);
1096    // The toString() hack catches null, as required.
1097    classAssertionStatus.put(name.toString(), Boolean.valueOf(enabled));
1098  }
1099  
1100  /**
1101   * Resets the default assertion status of this classloader, its packages
1102   * and classes, all to false. This allows overriding defaults inherited
1103   * from the command line.
1104   *
1105   * @see #setDefaultAssertionStatus(boolean)
1106   * @see #setClassAssertionStatus(String, boolean)
1107   * @see #setPackageAssertionStatus(String, boolean)
1108   * @since 1.4
1109   */
1110  public synchronized void clearAssertionStatus()
1111  {
1112    defaultAssertionStatus = false;
1113    packageAssertionStatus = new HashMap();
1114    classAssertionStatus = new HashMap();
1115  }
1116
1117  /**
1118   * Return true if this loader is either the specified class loader
1119   * or an ancestor thereof.
1120   * @param loader the class loader to check
1121   */
1122  final boolean isAncestorOf(ClassLoader loader)
1123  {
1124    while (loader != null)
1125      {
1126        if (this == loader)
1127          return true;
1128        loader = loader.parent;
1129      }
1130    return false;
1131  }
1132
1133  /**
1134   * Before doing anything "dangerous" please call this method to make sure
1135   * this class loader instance was properly constructed (and not obtained
1136   * by exploiting the finalizer attack)
1137   * @see #initialized
1138   */
1139  private void checkInitialized()
1140  {
1141    if (! initialized)
1142      throw new SecurityException("attempt to use uninitialized class loader");
1143  }
1144}