home *** CD-ROM | disk | FTP | other *** search
/ DOS/V Power Report 1998 February / VPR9802A.ISO / APP_DEMO / VC / MAIN.BIN / ClassLoader.java < prev    next >
Text File  |  1997-10-27  |  16KB  |  418 lines
  1. /*
  2.  * @(#)ClassLoader.java    1.56 97/02/10
  3.  * 
  4.  * Copyright (c) 1995, 1996 Sun Microsystems, Inc. All Rights Reserved.
  5.  * 
  6.  * This software is the confidential and proprietary information of Sun
  7.  * Microsystems, Inc. ("Confidential Information").  You shall not
  8.  * disclose such Confidential Information and shall use it only in
  9.  * accordance with the terms of the license agreement you entered into
  10.  * with Sun.
  11.  * 
  12.  * SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF THE
  13.  * SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
  14.  * IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
  15.  * PURPOSE, OR NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR ANY DAMAGES
  16.  * SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR DISTRIBUTING
  17.  * THIS SOFTWARE OR ITS DERIVATIVES.
  18.  * 
  19.  * CopyrightVersion 1.1_beta
  20.  * 
  21.  */
  22.  
  23. package java.lang;
  24.  
  25. import java.io.InputStream;
  26. import java.util.Hashtable;
  27.  
  28. /**
  29.  * The class <code>ClassLoader</code> is an abstract class. 
  30.  * Applications implement subclasses of <code>ClassLoader</code> in 
  31.  * order to extend the manner in which the Java Virtual Machine 
  32.  * dynamically loads classes. 
  33.  * <p>
  34.  * Normally, the Java Virtual Machine loads classes from the local 
  35.  * file system in a platform-dependent manner. For example, on UNIX 
  36.  * systems, the Virtual Machine loads classes from the directory 
  37.  * defined by the <code>CLASSPATH</code> environment variable. 
  38.  * <p>
  39.  * However, some classes may not originate from a file; they may 
  40.  * originate from other sources, such as the network, or they could 
  41.  * be constructed by an application. The method 
  42.  * <code>defineClass</code> converts an array of bytes into an 
  43.  * instance of class <code>Class</code>. Instances of this newly 
  44.  * defined class can be created using the <code>newInstance</code> 
  45.  * method in class <code>Class</code>. 
  46.  * <p>
  47.  * The methods and constructors of objects created by a class loader 
  48.  * may reference other classes. To determine the class(es) referred 
  49.  * to, the Java Virtual Machine calls the <code>loadClass</code> 
  50.  * method of the class loader that originally created the class. If 
  51.  * the Java Virtual Machine only needs to determine if the class 
  52.  * exists and if it does exist to know its superclass, the 
  53.  * <code>resolve</code> flag is set to <code>false</code>. However, 
  54.  * if an instance of the class is being created or any of its methods 
  55.  * are being called, the class must also be resolved. In this case 
  56.  * the <code>resolve</code> flag is set to <code>true</code>, and the 
  57.  * <code>resolveClass</code> method should be called. 
  58.  * <p>
  59.  * For example, an application could create a network class loader 
  60.  * to download class files from a server. Sample code might look like:
  61.  * <ul><code>
  62.  *   ClassLoader loader = new NetworkClassLoader(host, port);<br>
  63.  *   Object main = loader.loadClass("Main", true).newInstance();<br>
  64.  *      . . .
  65.  * </code></ul>
  66.  * <p>
  67.  * The network class loader subclass must define the method 
  68.  * <code>loadClass</code> to load a class from the network. Once it 
  69.  * has downloaded the bytes that make up the class, it should use the 
  70.  * method <code>defineClass</code> to create a class instance. A 
  71.  * sample implementation is: 
  72.  * <p><hr><blockquote><pre>
  73.  *     class NetworkClassLoader {
  74.  *         String host;
  75.  *         int port;
  76.  *         Hashtable cache = new Hashtable();
  77.  *         private byte loadClassData(String name)[] {
  78.  *         // load the class data from the connection
  79.  *          . . .
  80.  *         }
  81.  * 
  82.  *         public synchronized Class loadClass(String name,
  83.  *                                             boolean resolve) {
  84.  *             Class c = cache.get(name);
  85.  *             if (c == null) {
  86.  *                 byte data[] = loadClassData(name);
  87.  *                 c = defineClass(data, 0, data.length);
  88.  *                 cache.put(name, c);
  89.  *             }
  90.  *             if (resolve)
  91.  *                 resolveClass(c);
  92.  *             return c;
  93.  *         }
  94.  *     }
  95.  * </pre></blockquote><hr>
  96.  *
  97.  * @author  Arthur van Hoff
  98.  * @version 1.56, 02/10/97
  99.  * @see     java.lang.Class
  100.  * @see     java.lang.Class#newInstance()
  101.  * @see     java.lang.ClassLoader#defineClass(byte[], int, int)
  102.  * @see     java.lang.ClassLoader#loadClass(java.lang.String, boolean)
  103.  * @see     java.lang.ClassLoader#resolveClass(java.lang.Class)
  104.  * @since   JDK1.0
  105.  */
  106. public abstract class ClassLoader {
  107.     /**
  108.      * If initialization succeed this is set to true and security checks will
  109.      * succeed. Otherwise the object is not initialized and the object is
  110.      * useless.
  111.      */
  112.     private boolean initialized = false;
  113.  
  114.     /**
  115.      * This is a mapping of all String => Class done by this classloader.
  116.      * Each Class in the table will either have a null class loader, or 
  117.      * "this" as its classloader
  118.      */
  119.     private Hashtable classes = new Hashtable();
  120.  
  121.     /**
  122.      * Constructs a new class loader and initializes it. 
  123.      * <p>
  124.      * If there is a security manager, its 
  125.      * <code>checkCreateClassLoader</code> method is called. This may 
  126.      * result in a security exception. 
  127.      *
  128.      * @exception  SecurityException  if the current thread does not have
  129.      *               permission to create a new class loader.
  130.      * @see       java.lang.SecurityException
  131.      * @see       java.lang.SecurityManager#checkCreateClassLoader()
  132.      * @since     JDK1.0
  133.      */
  134.     protected ClassLoader() {
  135.     SecurityManager security = System.getSecurityManager();
  136.     if (security != null) {
  137.         security.checkCreateClassLoader();
  138.     }
  139.     init();
  140.     initialized = true;
  141.     }
  142.  
  143.     /**
  144.      * Requests the class loader to load a class with the specified 
  145.      * name. The <code>loadClass</code> method is called by the Java 
  146.      * Virtual Machine when a class loaded by a class loader first 
  147.      * references another class. Every subclass of class 
  148.      * <code>ClassLoader</code> must define this method. 
  149.      * <p>
  150.      * If the <code>resolve</code> flag is true, the method should call 
  151.      * the <code>resolveClass</code> method on the resulting class object.
  152.      * <p>
  153.      * Class loaders should use a hashtable or other cache to avoid 
  154.      * defining classes with the same name multiple times. 
  155.      *
  156.      * @param      name      the name of the desired <code>Class</code>.
  157.      * @param      resolve   <code>true</code> if the <code>Class</code>
  158.      *                       must be resolved.
  159.      * @return     the resulting <code>Class</code>, or <code>null</code>
  160.      *             if it was not found.
  161.      * @exception  ClassNotFoundException  if the class loader cannot find
  162.      *               a definition for the class.
  163.      * @since      JDK1.0
  164.      */
  165.     public Class loadClass(String name) throws ClassNotFoundException
  166.     {
  167.     return loadClass(name, true);
  168.     }
  169.  
  170.     /**
  171.      * Resolves the specified name to a Class. The method loadClass() is 
  172.      * called by the virtual machine.
  173.      * As an abstract method, loadClass() must be defined in a subclass of 
  174.      * ClassLoader. By using a Hashtable, you can avoid loading the same 
  175.      * Class more than once.
  176.      * 
  177.      * @param       name     the name of the desired Class.
  178.      * @param      resolve  true if the Class needs to be resolved.
  179.      * @return       the resulting Class, or null if it was not found.
  180.      * @exception  ClassNotFoundException  if the class loader cannot find
  181.      *               a definition for the class.
  182.      * @see       java.util.Hashtable
  183.      * @since      JDK1.1
  184.      */
  185.     protected abstract Class loadClass(String name, boolean resolve)
  186.     throws ClassNotFoundException;
  187.  
  188.     /**
  189.      * Converts an array of bytes into an instance of class 
  190.      * <code>Class</code>. 
  191.      * Before the Class can be used it must be resolved.  This
  192.      * method is deprecated in favor of the version that takes a
  193.      * "name" as a first argument, and is more secure.
  194.      *
  195.      * @param      data     the bytes that make up the <code>Class</code>.
  196.      * @param      offset   the start offset of the <code>Class</code> data.
  197.      * @param      length   the length of the <code>Class</code> data.
  198.      * @return     the <code>Class</code> object that was created from the data.
  199.      * @exception  ClassFormatError  if the data does not contain a valid Class.
  200.      * @see        ClassLoader#loadClass(java.lang.String, boolean)
  201.      * @see        ClassLoader#resolveClass(java.lang.Class)
  202.      * @since      JDK1.0
  203.      * @deprecated Replaced by defineClass(java.lang.String, byte[], int, int).
  204.      */
  205.     protected final Class defineClass(byte data[], int offset, int length) { 
  206.     return defineClass(null, data, offset, length);
  207.     }
  208.  
  209.     /**
  210.      * Converts an array of bytes to an instance of class
  211.      * Class. Before the Class can be used it must be resolved.
  212.      *
  213.      * @param       name     the expected name of the class; null if unknown;
  214.      *                      using '.' and not '/' as separator, and without
  215.      *                      a trailing ".class" suffix.
  216.      * @param      data     the bytes that make up the <code>Class</code>.
  217.      * @param      offset   the start offset of the <code>Class</code> data.
  218.      * @param      length   the length of the <code>Class</code> data.
  219.      * @return     the <code>Class</code> object that was created from the data.
  220.      * @exception  ClassFormatError  if the data does not contain a valid Class.
  221.      * @see        ClassLoader#loadClass(java.lang.String, boolean)
  222.      * @see        ClassLoader#resolveClass(java.lang.Class)
  223.      * @since      JDK1.1
  224.      */
  225.     protected final Class defineClass(String name,
  226.                       byte data[], int offset, int length) { 
  227.     check();
  228.     Class result = defineClass0(name, data, offset, length);
  229.     if (result != null) 
  230.         classes.put(result.getName(), result);
  231.     return result;
  232.     }
  233.  
  234.     /**
  235.      * Resolves the class so that an instance of the class can be 
  236.      * created, or so that one of its methods can be called. This method 
  237.      * should be called by <code>loadClass</code> if the resolve flag is 
  238.      * <code>true</code>. 
  239.      *
  240.      * @param   c   the <code>Class</code> instance to be resolved.
  241.      * @see     java.lang.ClassLoader#defineClass(java.lang.String, byte[], int, int)
  242.      * @since   JDK1.0
  243.      */
  244.     protected final void resolveClass(Class c) { 
  245.     check();
  246.     resolveClass0(c);
  247.     }
  248.  
  249.     /**
  250.      * Finds the system class with the specified name, loading it in if 
  251.      * necessary. 
  252.      * <p>
  253.      * A system class is a class loaded from the local file system in a 
  254.      * platform- dependent way. It has no class loader. 
  255.      *
  256.      * @param      name   the name of the system <code>class</code>.
  257.      * @return     a system class with the given name.
  258.      * @exception  ClassNotFoundException  if it could not find a definition
  259.      *               for the class.
  260.      * @exception  NoClassDefFoundError    if the class is not found.
  261.      * @since      JDK1.0
  262.      */
  263.     protected final Class findSystemClass(String name) 
  264.     throws ClassNotFoundException {
  265.     check();
  266.     return findSystemClass0(name);
  267.     }
  268.  
  269.     /**
  270.      * Sets the signers of a class. This is called after defining a class,
  271.      * by signature-aware class loading code.
  272.      *
  273.      * @since   JDK1.1
  274.      */
  275.     protected final void setSigners(Class cl, Object[] signers) {
  276.         check();
  277.     // make a check which will take cl.getClassLoader and
  278.     // check if it is != this.
  279.     cl.setSigners(signers);
  280.     }
  281.  
  282.     /**
  283.      * Initializes the Class loader.
  284.      */
  285.     private native void init();
  286.     private native Class defineClass0(String name, 
  287.                       byte data[], int offset, int length);
  288.     private native void resolveClass0(Class c);
  289.     private native Class findSystemClass0(String name) 
  290.         throws ClassNotFoundException;
  291.  
  292.     private void check() { 
  293.     if (initialized == true) 
  294.         return;
  295.     throw new SecurityException("ClassLoader object not initialized.");
  296.     }
  297.  
  298.     /**
  299.      * @since   JDK1.1
  300.      */
  301.     final protected Class findLoadedClass(String name) { 
  302.     return (Class)classes.get(name);
  303.     }
  304.  
  305.     /**
  306.      * Load and resolve a class.
  307.      */
  308.     final Class loadClassInternal(String name, boolean resolve) 
  309.                     throws ClassNotFoundException {
  310.     name = name.replace('/', '.');
  311.     Class cl = (Class)classes.get(name);
  312.     if (cl == null) {
  313.         cl = loadClass(name, false);
  314.         if (cl == null) 
  315.         throw new ClassNotFoundException(name);
  316.         String realName = cl.getName();
  317.         if (!realName.equals(name)) { 
  318.         throw new ClassNotFoundException(name);
  319.         }
  320.         classes.put(realName, cl);
  321.     }
  322.     if (resolve) 
  323.         resolveClass(cl);
  324.     return cl;
  325.     }
  326.  
  327.     /**
  328.      * A resource is some data (images, audio, text, etc) that wants to be
  329.      * accessed by some class code in a way that is independent of the
  330.      * location of the code.  Resources are found with cooperation of the
  331.      * class loaders, since they are the only ones who know where the class
  332.      * actually came from. <p>
  333.      *
  334.      * System resources are those that are handled by the host implemenation
  335.      * directly.  For example, they may be located in the CLASSPATH.<p>
  336.      *
  337.      * The name of a resource is a "/"-separated sequence of identifiers.
  338.      * The class Class provides convenience methods for accessing resources;
  339.      * the methods implement a convention where the package name is prefixed
  340.      * to the short name of the resource.<p>
  341.      * 
  342.      * Resources can be accessed as an InputStream, or as a URL.
  343.      *
  344.      * @see    Class
  345.      */
  346.  
  347.     /**
  348.      * Get an InputStream on a given resource..  Will return null if no
  349.      * resource with this name is found. <p>
  350.      *
  351.      * The resource name may be any system resource (e.g. follows CLASSPATH
  352.      * order).
  353.      *
  354.      * @param    name    the name of the resource, to be used as is.
  355.      * @return    an InputStream on the resource, or null if not found.
  356.      * @since   JDK1.1
  357.      */
  358.     public static final InputStream getSystemResourceAsStream(String name) {
  359.     // REMIND - This is equivalent to getSystemResource() call plus a openStream()
  360.     return getSystemResourceAsStream0(name);
  361.     }
  362.  
  363.     /**
  364.      * Find a resource with a given name.  The return is a URL to the resource
  365.      * Doing a getContent() on the URL may return an Image, an AudioClip, or
  366.      * an InputStream.<p>
  367.      *
  368.      * The resource name may be any system resource (e.g. follows CLASSPATH
  369.      * order).
  370.      *
  371.      * @param    name    the name of the resource, to be used as is.
  372.      * @return    the URL on the resource, or null if not found.
  373.      * @since   JDK1.1
  374.      */
  375.     public static final java.net.URL getSystemResource(String name) {
  376.     String s = getSystemResourceAsName0(name);
  377.     java.net.URL back;
  378.     try {
  379.         back = new java.net.URL(s);
  380.     } catch (Exception ex) {
  381.         back = null;
  382.     }
  383.     return back;
  384.     }
  385.  
  386.     /**
  387.      * Get an InputStream on a given resource.  Will return null if no
  388.      * resource with this name is found. <p>
  389.      *
  390.      * The class loader can choose what to do to locate the resource.
  391.      *
  392.      * @param    name    the name of the resource, to be used as is.
  393.      * @return    an InputStream on the resource, or null if not found.
  394.      * @since   JDK1.1
  395.      */
  396.     public InputStream getResourceAsStream(String name) {
  397.     return null;
  398.     }
  399.  
  400.     /**
  401.      * Find a resource with a given name.  The return is a URL to the resource.
  402.      * Doing a getContent() on the URL may return an Image, an AudioClip,
  403.      * or an InputStream.<p>
  404.      *
  405.      * The class loader can choose what to do to locate the resource.
  406.      *
  407.      * @param    name    the name of the resource, to be used as is.
  408.      * @return    an InputStream on the resource, or null if not found.
  409.      * @since   JDK1.1
  410.      */
  411.     public java.net.URL getResource(String name) {
  412.     return null;
  413.     }
  414.  
  415.     private static native InputStream getSystemResourceAsStream0(String name);
  416.     private static native String getSystemResourceAsName0(String name);
  417. }
  418.