Every {@link Class Class} object contains a {@link + * Class#getClassLoader() reference} to the ClassLoader that defined + * it. + * + *
Class objects for array classes are not created by class + * loaders, but are created automatically as required by the Java runtime. + * The class loader for an array class, as returned by {@link + * Class#getClassLoader()} is the same as the class loader for its element + * type; if the element type is a primitive type, then the array class has no + * class loader. + * + *
Applications implement subclasses of ClassLoader in order to + * extend the manner in which the Java virtual machine dynamically loads + * classes. + * + *
Class loaders may typically be used by security managers to indicate + * security domains. + * + *
The ClassLoader class uses a delegation model to search for + * classes and resources. Each instance of ClassLoader has an + * associated parent class loader. When requested to find a class or + * resource, a ClassLoader instance will delegate the search for the + * class or resource to its parent class loader before attempting to find the + * class or resource itself. The virtual machine's built-in class loader, + * called the "bootstrap class loader", does not itself have a parent but may + * serve as the parent of a ClassLoader instance. + * + *
Class loaders that support concurrent loading of classes are known as
+ * parallel capable class loaders and are required to register
+ * themselves at their class initialization time by invoking the
+ * {@link
+ * #registerAsParallelCapable ClassLoader.registerAsParallelCapable}
+ * method. Note that the ClassLoader class is registered as parallel
+ * capable by default. However, its subclasses still need to register themselves
+ * if they are parallel capable.
+ * In environments in which the delegation model is not strictly
+ * hierarchical, class loaders need to be parallel capable, otherwise class
+ * loading can lead to deadlocks because the loader lock is held for the
+ * duration of the class loading process (see {@link #loadClass
+ * loadClass} methods).
+ *
+ *
Normally, the Java virtual machine loads classes from the local file + * system in a platform-dependent manner. For example, on UNIX systems, the + * virtual machine loads classes from the directory defined by the + * CLASSPATH environment variable. + * + *
However, some classes may not originate from a file; they may originate + * from other sources, such as the network, or they could be constructed by an + * application. The method {@link #defineClass(String, byte[], int, int) + * defineClass} converts an array of bytes into an instance of class + * Class. Instances of this newly defined class can be created using + * {@link Class#newInstance Class.newInstance}. + * + *
The methods and constructors of objects created by a class loader may + * reference other classes. To determine the class(es) referred to, the Java + * virtual machine invokes the {@link #loadClass loadClass} method of + * the class loader that originally created the class. + * + *
For example, an application could create a network class loader to + * download class files from a server. Sample code might look like: + * + *
+ * ClassLoader loader = new NetworkClassLoader(host, port);
+ * Object main = loader.loadClass("Main", true).newInstance();
+ * . . .
+ * The network class loader subclass must define the methods {@link + * #findClass findClass} and loadClassData to load a class + * from the network. Once it has downloaded the bytes that make up the class, + * it should use the method {@link #defineClass defineClass} to + * create a class instance. A sample implementation is: + * + *
+ * class NetworkClassLoader extends ClassLoader {
+ * String host;
+ * int port;
+ *
+ * public Class findClass(String name) {
+ * byte[] b = loadClassData(name);
+ * return defineClass(name, b, 0, b.length);
+ * }
+ *
+ * private byte[] loadClassData(String name) {
+ * // load the class data from the connection
+ * . . .
+ * }
+ * }
+ * Any class name provided as a {@link String} parameter to methods in + * ClassLoader must be a binary name as defined by + * The Java™ Language Specification. + * + *
Examples of valid class names include: + *
+ * + * @see #resolveClass(Class) + * @since 1.0 + */ +public abstract class ClassLoader { + + @JavaScriptBody(args = {}, body = "") + private static native void registerNatives(); + static { + registerNatives(); + } + + // The parent class loader for delegation + // Note: VM hardcoded the offset of this field, thus all new fields + // must be added *after* it. + private final ClassLoader parent; + + + /** + * Creates a new class loader using the specified parent class loader for + * delegation. + * + *+ * "java.lang.String" + * "javax.swing.JSpinner$DefaultEditor" + * "java.security.KeyStore$Builder$FileBuilder$1" + * "java.net.URLClassLoader$3$1" + *
If there is a security manager, its {@link + * SecurityManager#checkCreateClassLoader() + * checkCreateClassLoader} method is invoked. This may result in + * a security exception.
+ * + * @param parent + * The parent class loader + * + * @throws SecurityException + * If a security manager exists and its + * checkCreateClassLoader method doesn't allow creation + * of a new class loader. + * + * @since 1.2 + */ + protected ClassLoader(ClassLoader parent) { + throw new SecurityException(); + } + + /** + * Creates a new class loader using the ClassLoader returned by + * the method {@link #getSystemClassLoader() + * getSystemClassLoader()} as the parent class loader. + * + *If there is a security manager, its {@link + * SecurityManager#checkCreateClassLoader() + * checkCreateClassLoader} method is invoked. This may result in + * a security exception.
+ * + * @throws SecurityException + * If a security manager exists and its + * checkCreateClassLoader method doesn't allow creation + * of a new class loader. + */ + protected ClassLoader() { + throw new SecurityException(); + } + + // -- Class -- + + /** + * Loads the class with the specified binary name. + * This method searches for classes in the same manner as the {@link + * #loadClass(String, boolean)} method. It is invoked by the Java virtual + * machine to resolve class references. Invoking this method is equivalent + * to invoking {@link #loadClass(String, boolean) loadClass(name, + * false)}. + * + * @param name + * The binary name of the class + * + * @return The resulting Class object + * + * @throws ClassNotFoundException + * If the class was not found + */ + public Class loadClass(String name) throws ClassNotFoundException { + return loadClass(name, false); + } + + /** + * Loads the class with the specified binary name. The + * default implementation of this method searches for classes in the + * following order: + * + *Invoke {@link #findLoadedClass(String)} to check if the class + * has already been loaded.
Invoke the {@link #loadClass(String) loadClass} method + * on the parent class loader. If the parent is null the class + * loader built-in to the virtual machine is used, instead.
Invoke the {@link #findClass(String)} method to find the + * class.
If the class was found using the above steps, and the + * resolve flag is true, this method will then invoke the {@link + * #resolveClass(Class)} method on the resulting Class object. + * + *
Subclasses of ClassLoader are encouraged to override {@link + * #findClass(String)}, rather than this method.
+ * + *Unless overridden, this method synchronizes on the result of + * {@link #getClassLoadingLock getClassLoadingLock} method + * during the entire class loading process. + * + * @param name + * The binary name of the class + * + * @param resolve + * If true then resolve the class + * + * @return The resulting Class object + * + * @throws ClassNotFoundException + * If the class could not be found + */ + protected Class loadClass(String name, boolean resolve) + throws ClassNotFoundException + { + synchronized (getClassLoadingLock(name)) { + // First, check if the class has already been loaded + Class c = findLoadedClass(name); + if (c == null) { + try { + if (parent != null) { + c = parent.loadClass(name, false); + } else { + c = findBootstrapClassOrNull(name); + } + } catch (ClassNotFoundException e) { + // ClassNotFoundException thrown if class not found + // from the non-null parent class loader + } + + if (c == null) { + // If still not found, then invoke findClass in order + // to find the class. + c = findClass(name); + +// // this is the defining class loader; record the stats +// sun.misc.PerfCounter.getParentDelegationTime().addTime(t1 - t0); +// sun.misc.PerfCounter.getFindClassTime().addElapsedTimeFrom(t1); +// sun.misc.PerfCounter.getFindClasses().increment(); + } + } + if (resolve) { + resolveClass(c); + } + return c; + } + } + + /** + * Returns the lock object for class loading operations. + * For backward compatibility, the default implementation of this method + * behaves as follows. If this ClassLoader object is registered as + * parallel capable, the method returns a dedicated object associated + * with the specified class name. Otherwise, the method returns this + * ClassLoader object.
+ * + * @param className + * The name of the to-be-loaded class + * + * @return the lock for class loading operations + * + * @throws NullPointerException + * If registered as parallel capable and className is null + * + * @see #loadClass(String, boolean) + * + * @since 1.7 + */ + protected Object getClassLoadingLock(String className) { + Object lock = this; + return lock; + } + + /** + * Finds the class with the specified binary name. + * This method should be overridden by class loader implementations that + * follow the delegation model for loading classes, and will be invoked by + * the {@link #loadClass loadClass} method after checking the + * parent class loader for the requested class. The default implementation + * throws a ClassNotFoundException. + * + * @param name + * The binary name of the class + * + * @return The resulting Class object + * + * @throws ClassNotFoundException + * If the class could not be found + * + * @since 1.2 + */ + protected Class findClass(String name) throws ClassNotFoundException { + throw new ClassNotFoundException(name); + } + + /** + * Converts an array of bytes into an instance of class Class. + * Before the Class can be used it must be resolved. This method + * is deprecated in favor of the version that takes a binary name as its first argument, and is more secure. + * + * @param b + * The bytes that make up the class data. The bytes in positions + * off through off+len-1 should have the format + * of a valid class file as defined by + * The Java™ Virtual Machine Specification. + * + * @param off + * The start offset in b of the class data + * + * @param len + * The length of the class data + * + * @return The Class object that was created from the specified + * class data + * + * @throws ClassFormatError + * If the data did not contain a valid class + * + * @throws IndexOutOfBoundsException + * If either off or len is negative, or if + * off+len is greater than b.length. + * + * @throws SecurityException + * If an attempt is made to add this class to a package that + * contains classes that were signed by a different set of + * certificates than this class, or if an attempt is made + * to define a class in a package with a fully-qualified name + * that starts with "{@code java.}". + * + * @see #loadClass(String, boolean) + * @see #resolveClass(Class) + * + * @deprecated Replaced by {@link #defineClass(String, byte[], int, int) + * defineClass(String, byte[], int, int)} + */ + @Deprecated + protected final Class defineClass(byte[] b, int off, int len) + throws ClassFormatError + { + throw new SecurityException(); + } + + /** + * Converts an array of bytes into an instance of class Class. + * Before the Class can be used it must be resolved. + * + *This method assigns a default {@link java.security.ProtectionDomain + * ProtectionDomain} to the newly defined class. The + * ProtectionDomain is effectively granted the same set of + * permissions returned when {@link + * java.security.Policy#getPermissions(java.security.CodeSource) + * Policy.getPolicy().getPermissions(new CodeSource(null, null))} + * is invoked. The default domain is created on the first invocation of + * {@link #defineClass(String, byte[], int, int) defineClass}, + * and re-used on subsequent invocations. + * + *
To assign a specific ProtectionDomain to the class, use + * the {@link #defineClass(String, byte[], int, int, + * java.security.ProtectionDomain) defineClass} method that takes a + * ProtectionDomain as one of its arguments.
+ * + * @param name + * The expected binary name of the class, or + * null if not known + * + * @param b + * The bytes that make up the class data. The bytes in positions + * off through off+len-1 should have the format + * of a valid class file as defined by + * The Java™ Virtual Machine Specification. + * + * @param off + * The start offset in b of the class data + * + * @param len + * The length of the class data + * + * @return The Class object that was created from the specified + * class data. + * + * @throws ClassFormatError + * If the data did not contain a valid class + * + * @throws IndexOutOfBoundsException + * If either off or len is negative, or if + * off+len is greater than b.length. + * + * @throws SecurityException + * If an attempt is made to add this class to a package that + * contains classes that were signed by a different set of + * certificates than this class (which is unsigned), or if + * name begins with "java.". + * + * @see #loadClass(String, boolean) + * @see #resolveClass(Class) + * @see java.security.CodeSource + * @see java.security.SecureClassLoader + * + * @since 1.1 + */ + protected final Class defineClass(String name, byte[] b, int off, int len) + throws ClassFormatError + { + throw new SecurityException(); + } + + /** + * Links the specified class. This (misleadingly named) method may be + * used by a class loader to link a class. If the class c has + * already been linked, then this method simply returns. Otherwise, the + * class is linked as described in the "Execution" chapter of + * The Java™ Language Specification. + * + * + * @param c + * The class to link + * + * @throws NullPointerException + * If c is null. + * + * @see #defineClass(String, byte[], int, int) + */ + protected final void resolveClass(Class c) { + resolveClass0(c); + } + + private native void resolveClass0(Class c); + + + /** + * Returns the class with the given binary name if this + * loader has been recorded by the Java virtual machine as an initiating + * loader of a class with that binary name. Otherwise + * null is returned. + * + * @param name + * The binary name of the class + * + * @return The Class object, or null if the class has + * not been loaded + * + * @since 1.1 + */ + protected final Class findLoadedClass(String name) { + if (!checkName(name)) + return null; + return findLoadedClass0(name); + } + + private native final Class findLoadedClass0(String name); + + /** + * Sets the signers of a class. This should be invoked after defining a + * class. + * + * @param c + * The Class object + * + * @param signers + * The signers for the class + * + * @since 1.1 + */ + protected final void setSigners(Class c, Object[] signers) { + //c.setSigners(signers); + throw new UnsupportedOperationException(); + } + + + // -- Resource -- + + /** + * Finds the resource with the given name. A resource is some data + * (images, audio, text, etc) that can be accessed by class code in a way + * that is independent of the location of the code. + * + *The name of a resource is a '/'-separated path name that + * identifies the resource. + * + *
This method will first search the parent class loader for the + * resource; if the parent is null the path of the class loader + * built-in to the virtual machine is searched. That failing, this method + * will invoke {@link #findResource(String)} to find the resource.
+ * + * @param name + * The resource name + * + * @return A URL object for reading the resource, or + * null if the resource could not be found or the invoker + * doesn't have adequate privileges to get the resource. + * + * @since 1.1 + */ + public URL getResource(String name) { + URL url; + if (parent != null) { + url = parent.getResource(name); + } else { + url = getBootstrapResource(name); + } + if (url == null) { + url = findResource(name); + } + return url; + } + + /** + * Finds all the resources with the given name. A resource is some data + * (images, audio, text, etc) that can be accessed by class code in a way + * that is independent of the location of the code. + * + *The name of a resource is a /-separated path name that + * identifies the resource. + * + *
The search order is described in the documentation for {@link + * #getResource(String)}.
+ * + * @param name + * The resource name + * + * @return An enumeration of {@link java.net.URL URL} objects for + * the resource. If no resources could be found, the enumeration + * will be empty. Resources that the class loader doesn't have + * access to will not be in the enumeration. + * + * @throws IOException + * If I/O errors occur + * + * @see #findResources(String) + * + * @since 1.2 + */ + public EnumerationThe search order is described in the documentation for {@link + * #getSystemResource(String)}.
+ * + * @param name + * The resource name + * + * @return An enumeration of resource {@link java.net.URL URL} + * objects + * + * @throws IOException + * If I/O errors occur + + * @since 1.2 + */ + public static EnumerationThe search order is described in the documentation for {@link + * #getResource(String)}.
+ * + * @param name + * The resource name + * + * @return An input stream for reading the resource, or null + * if the resource could not be found + * + * @since 1.1 + */ + public InputStream getResourceAsStream(String name) { + URL url = getResource(name); + try { + return url != null ? url.openStream() : null; + } catch (IOException e) { + return null; + } + } + + /** + * Open for reading, a resource of the specified name from the search path + * used to load classes. This method locates the resource through the + * system class loader (see {@link #getSystemClassLoader()}). + * + * @param name + * The resource name + * + * @return An input stream for reading the resource, or null + * if the resource could not be found + * + * @since 1.1 + */ + public static InputStream getSystemResourceAsStream(String name) { + URL url = getSystemResource(name); + try { + return url != null ? url.openStream() : null; + } catch (IOException e) { + return null; + } + } + + + // -- Hierarchy -- + + /** + * Returns the parent class loader for delegation. Some implementations may + * use null to represent the bootstrap class loader. This method + * will return null in such implementations if this class loader's + * parent is the bootstrap class loader. + * + *If a security manager is present, and the invoker's class loader is + * not null and is not an ancestor of this class loader, then this + * method invokes the security manager's {@link + * SecurityManager#checkPermission(java.security.Permission) + * checkPermission} method with a {@link + * RuntimePermission#RuntimePermission(String) + * RuntimePermission("getClassLoader")} permission to verify + * access to the parent class loader is permitted. If not, a + * SecurityException will be thrown.
+ * + * @return The parent ClassLoader + * + * @throws SecurityException + * If a security manager exists and its checkPermission + * method doesn't allow access to this class loader's parent class + * loader. + * + * @since 1.2 + */ + public final ClassLoader getParent() { + throw new SecurityException(); + } + + /** + * Returns the system class loader for delegation. This is the default + * delegation parent for new ClassLoader instances, and is + * typically the class loader used to start the application. + * + *This method is first invoked early in the runtime's startup + * sequence, at which point it creates the system class loader and sets it + * as the context class loader of the invoking Thread. + * + *
The default system class loader is an implementation-dependent + * instance of this class. + * + *
If the system property "java.system.class.loader" is defined + * when this method is first invoked then the value of that property is + * taken to be the name of a class that will be returned as the system + * class loader. The class is loaded using the default system class loader + * and must define a public constructor that takes a single parameter of + * type ClassLoader which is used as the delegation parent. An + * instance is then created using this constructor with the default system + * class loader as the parameter. The resulting class loader is defined + * to be the system class loader. + * + *
If a security manager is present, and the invoker's class loader is + * not null and the invoker's class loader is not the same as or + * an ancestor of the system class loader, then this method invokes the + * security manager's {@link + * SecurityManager#checkPermission(java.security.Permission) + * checkPermission} method with a {@link + * RuntimePermission#RuntimePermission(String) + * RuntimePermission("getClassLoader")} permission to verify + * access to the system class loader. If not, a + * SecurityException will be thrown.
+ * + * @return The system ClassLoader for delegation, or + * null if none + * + * @throws SecurityException + * If a security manager exists and its checkPermission + * method doesn't allow access to the system class loader. + * + * @throws IllegalStateException + * If invoked recursively during the construction of the class + * loader specified by the "java.system.class.loader" + * property. + * + * @throws Error + * If the system property "java.system.class.loader" + * is defined but the named class could not be loaded, the + * provider class does not define the required constructor, or an + * exception is thrown by that constructor when it is invoked. The + * underlying cause of the error can be retrieved via the + * {@link Throwable#getCause()} method. + * + * @revised 1.4 + */ + public static ClassLoader getSystemClassLoader() { + throw new SecurityException(); + } + + // Returns true if the specified class loader can be found in this class + // loader's delegation chain. + boolean isAncestor(ClassLoader cl) { + ClassLoader acl = this; + do { + acl = acl.parent; + if (cl == acl) { + return true; + } + } while (acl != null); + return false; + } + + private boolean checkName(String name) { + throw new UnsupportedOperationException(); + } + + private Class findBootstrapClassOrNull(String name) { + throw new UnsupportedOperationException(); + } + + private static URL getBootstrapResource(String name) { + throw new UnsupportedOperationException(); + } + + private static Enumeration