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