java.lang

Class ClassLoader

Known Direct Subclasses:
CombinedClassLoader, SecureClassLoader, SharedLibLoader

public abstract class ClassLoader
extends Object

The ClassLoader is a way of customizing the way Java gets its classes and loads them into memory. The verifier and other standard Java things still run, but the ClassLoader is allowed great flexibility in determining where to get the classfiles and when to load and resolve them. For that matter, a custom ClassLoader can perform on-the-fly code generation or modification!

Every classloader has a parent classloader that is consulted before the 'child' classloader when classes or resources should be loaded. This is done to make sure that classes can be loaded from an hierarchy of multiple classloaders and classloaders do not accidentially redefine already loaded classes by classloaders higher in the hierarchy.

The grandparent of all classloaders is the bootstrap classloader, which loads all the standard system classes as implemented by GNU Classpath. The other special classloader is the system classloader (also called application classloader) that loads all classes from the CLASSPATH (java.class.path system property). The system classloader is responsible for finding the application classes from the classpath, and delegates all requests for the standard library classes to its parent the bootstrap classloader. Most programs will load all their classes through the system classloaders.

The bootstrap classloader in GNU Classpath is implemented as a couple of static (native) methods on the package private class java.lang.VMClassLoader, the system classloader is an instance of gnu.java.lang.SystemClassLoader (which is a subclass of java.net.URLClassLoader).

Users of a ClassLoader will normally just use the methods

Subclasses should implement the methods

Since:
1.0
See Also:
Class

Constructor Summary

ClassLoader()
Create a new ClassLoader with as parent the system classloader.
ClassLoader(ClassLoader parent)
Create a new ClassLoader with the specified parent.

Method Summary

void
clearAssertionStatus()
Resets the default assertion status of this classloader, its packages and classes, all to false.
protected Class
defineClass(byte[] data, int offset, int len)
Deprecated. use defineClass(String,byte[],int,int) instead
protected Class
defineClass(String name, byte[] data, int offset, int len)
Helper to define a class using a string of bytes without a ProtectionDomain.
protected Class
defineClass(String name, byte[] data, int offset, int len, ProtectionDomain domain)
Helper to define a class using a string of bytes.
protected Class
defineClass(String name, ByteBuffer buf, ProtectionDomain domain)
Helper to define a class using the contents of a byte buffer.
protected Package
definePackage(String name, String specTitle, String specVendor, String specVersion, String implTitle, String implVendor, String implVersion, URL sealed)
Defines a new package and creates a Package object.
protected Class
findClass(String name)
Called for every class name that is needed but has not yet been defined by this classloader or one of its parents.
protected String
findLibrary(String name)
Called by Runtime.loadLibrary() to get an absolute path to a (system specific) library that was requested by a class loaded by this classloader.
protected Class
findLoadedClass(String name)
Helper to find an already-loaded class in this ClassLoader.
protected URL
findResource(String name)
Called whenever a resource is needed that could not be provided by one of the parents of this classloader.
protected Enumeration
findResources(String name)
Called whenever all locations of a named resource are needed.
protected Class
findSystemClass(String name)
Helper to find a Class using the system classloader, possibly loading it.
protected Package
getPackage(String name)
Returns the Package object for the requested package name.
protected Package[]
getPackages()
Returns all Package objects defined by this classloader and its parents.
ClassLoader
getParent()
Returns the parent of this classloader.
URL
getResource(String name)
Get the URL to a resource using this classloader or one of its parents.
InputStream
getResourceAsStream(String name)
Get a resource as stream using this classloader or one of its parents.
Enumeration
getResources(String name)
Returns an Enumeration of all resources with a given name that can be found by this classloader and its parents.
static ClassLoader
getSystemClassLoader()
Returns the system classloader.
static URL
getSystemResource(String name)
Get the URL to a resource using the system classloader.
static InputStream
getSystemResourceAsStream(String name)
Get a resource using the system classloader.
static Enumeration
getSystemResources(String name)
Get an Enumeration of URLs to resources with a given name using the the system classloader.
Class
loadClass(String name)
Load a class using this ClassLoader or its parent, without resolving it.
protected Class
loadClass(String name, boolean resolve)
Load a class using this ClassLoader or its parent, possibly resolving it as well using resolveClass().
protected void
resolveClass(Class c)
Links the class, if that has not already been done.
void
setClassAssertionStatus(String name, boolean enabled)
Set the default assertion status for a class.
void
setDefaultAssertionStatus(boolean enabled)
Set the default assertion status for classes loaded by this classloader, used unless overridden by a package or class request.
void
setPackageAssertionStatus(String name, boolean enabled)
Set the default assertion status for packages, used unless overridden by a class request.
protected void
setSigners(Class c, Object[] signers)
Helper to set the signers of a class.

Methods inherited from class java.lang.Object

clone, equals, extends Object> getClass, finalize, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

ClassLoader

protected ClassLoader()
            throws SecurityException
Create a new ClassLoader with as parent the system classloader. There may be a security check for checkCreateClassLoader.
Throws:
SecurityException - if the security check fails

ClassLoader

protected ClassLoader(ClassLoader parent)
Create a new ClassLoader with the specified parent. The parent will be consulted when a class or resource is requested through loadClass() or getResource(). Only when the parent classloader cannot provide the requested class or resource the findClass() or findResource() method of this classloader will be called. There may be a security check for checkCreateClassLoader.
Parameters:
parent - the classloader's parent, or null for the bootstrap classloader
Throws:
SecurityException - if the security check fails
Since:
1.2

Method Details

clearAssertionStatus

public void clearAssertionStatus()
Resets the default assertion status of this classloader, its packages and classes, all to false. This allows overriding defaults inherited from the command line.
Since:
1.4

defineClass

protected final Class defineClass(byte[] data,
                                     int offset,
                                     int len)
            throws ClassFormatError

Deprecated. use defineClass(String,byte[],int,int) instead

Helper to define a class using a string of bytes. This version is not secure.
Parameters:
data - the data representing the classfile, in classfile format
offset - the offset into the data where the classfile starts
len - the length of the classfile data in the array
Returns:
the class that was defined
Throws:
ClassFormatError - if data is not in proper classfile format
IndexOutOfBoundsException - if offset or len is negative, or offset + len exceeds data

defineClass

protected final Class defineClass(String name,
                                     byte[] data,
                                     int offset,
                                     int len)
            throws ClassFormatError
Helper to define a class using a string of bytes without a ProtectionDomain. Subclasses should call this method from their findClass() implementation. The name should use '.' separators, and discard the trailing ".class". The default protection domain has the permissions of Policy.getPolicy().getPermissions(new CodeSource(null, null)).
Parameters:
name - the name to give the class, or null if unknown
data - the data representing the classfile, in classfile format
offset - the offset into the data where the classfile starts
len - the length of the classfile data in the array
Returns:
the class that was defined
Throws:
ClassFormatError - if data is not in proper classfile format
IndexOutOfBoundsException - if offset or len is negative, or offset + len exceeds data
SecurityException - if name starts with "java."
Since:
1.1

defineClass

protected final Class defineClass(String name,
                                     byte[] data,
                                     int offset,
                                     int len,
                                     ProtectionDomain domain)
            throws ClassFormatError
Helper to define a class using a string of bytes. Subclasses should call this method from their findClass() implementation. If the domain is null, the default of Policy.getPolicy().getPermissions(new CodeSource(null, null)) is used. Once a class has been defined in a package, all further classes in that package must have the same set of certificates or a SecurityException is thrown.
Parameters:
name - the name to give the class. null if unknown
data - the data representing the classfile, in classfile format
offset - the offset into the data where the classfile starts
len - the length of the classfile data in the array
domain - the ProtectionDomain to give to the class, null for the default protection domain
Returns:
the class that was defined
Throws:
ClassFormatError - if data is not in proper classfile format
IndexOutOfBoundsException - if offset or len is negative, or offset + len exceeds data
SecurityException - if name starts with "java.", or if certificates do not match up
Since:
1.2

defineClass

protected final Class defineClass(String name,
                                     ByteBuffer buf,
                                     ProtectionDomain domain)
            throws ClassFormatError
Helper to define a class using the contents of a byte buffer. If the domain is null, the default of Policy.getPolicy().getPermissions(new CodeSource(null, null)) is used. Once a class has been defined in a package, all further classes in that package must have the same set of certificates or a SecurityException is thrown.
Parameters:
name - the name to give the class. null if unknown
buf - a byte buffer containing bytes that form a class.
domain - the ProtectionDomain to give to the class, null for the default protection domain
Returns:
the class that was defined
Throws:
ClassFormatError - if data is not in proper classfile format
SecurityException - if name starts with "java.", or if certificates do not match up
Since:
1.5

definePackage

protected Package definePackage(String name,
                                String specTitle,
                                String specVendor,
                                String specVersion,
                                String implTitle,
                                String implVendor,
                                String implVersion,
                                URL sealed)
Defines a new package and creates a Package object. The package should be defined before any class in the package is defined with defineClass(). The package should not yet be defined before in this classloader or in one of its parents (which means that getPackage() should return null). All parameters except the name of the package may be null.

Subclasses should call this method from their findClass() implementation before calling defineClass() on a Class in a not yet defined Package (which can be checked by calling getPackage()).

Parameters:
name - the name of the Package
specTitle - the name of the specification
specVendor - the name of the specification designer
specVersion - the version of this specification
implTitle - the name of the implementation
implVendor - the vendor that wrote this implementation
implVersion - the version of this implementation
sealed - if sealed the origin of the package classes
Returns:
the Package object for the specified package
Throws:
IllegalArgumentException - if the package name is null or it was already defined by this classloader or one of its parents
Since:
1.2
See Also:
Package

findClass

protected Class findClass(String name)
            throws ClassNotFoundException
Called for every class name that is needed but has not yet been defined by this classloader or one of its parents. It is called by loadClass() after both findLoadedClass() and parent.loadClass() couldn't provide the requested class.

The default implementation throws a ClassNotFoundException. Subclasses should override this method. An implementation of this method in a subclass should get the class bytes of the class (if it can find them), if the package of the requested class doesn't exist it should define the package and finally it should call define the actual class. It does not have to resolve the class. It should look something like the following:

 // Get the bytes that describe the requested class
 byte[] classBytes = classLoaderSpecificWayToFindClassBytes(name);
 // Get the package name
 int lastDot = name.lastIndexOf('.');
 if (lastDot != -1)
   {
     String packageName = name.substring(0, lastDot);
     // Look if the package already exists
     if (getPackage(packageName) == null)
       {
         // define the package
         definePackage(packageName, ...);
       }
   }
 // Define and return the class
  return defineClass(name, classBytes, 0, classBytes.length);
 

loadClass() makes sure that the Class returned by findClass() will later be returned by findLoadedClass() when the same class name is requested.

Parameters:
name - class name to find (including the package name)
Returns:
the requested Class
Throws:
ClassNotFoundException - when the class can not be found
Since:
1.2

findLibrary

protected String findLibrary(String name)
Called by Runtime.loadLibrary() to get an absolute path to a (system specific) library that was requested by a class loaded by this classloader. The default implementation returns null. It should be implemented by subclasses when they have a way to find the absolute path to a library. If this method returns null the library is searched for in the default locations (the directories listed in the java.library.path system property).
Parameters:
name - the (system specific) name of the requested library
Returns:
the full pathname to the requested library, or null
Since:
1.2

findLoadedClass

protected final Class findLoadedClass(String name)
Helper to find an already-loaded class in this ClassLoader.
Parameters:
name - the name of the class to find
Returns:
the found Class, or null if it is not found
Since:
1.1

findResource

protected URL findResource(String name)
Called whenever a resource is needed that could not be provided by one of the parents of this classloader. It is called by getResource() after parent.getResource() couldn't provide the requested resource.

The default implementation always returns null. Subclasses should override this method when they can provide a way to return a URL to a named resource.

Parameters:
name - the name of the resource to be found
Returns:
a URL to the named resource or null when not found
Since:
1.2

findResources

protected Enumeration findResources(String name)
            throws IOException
Called whenever all locations of a named resource are needed. It is called by getResources() after it has called parent.getResources(). The results are combined by the getResources() method.

The default implementation always returns an empty Enumeration. Subclasses should override it when they can provide an Enumeration of URLs (possibly just one element) to the named resource. The first URL of the Enumeration should be the same as the one returned by findResource.

Parameters:
name - the name of the resource to be found
Returns:
a possibly empty Enumeration of URLs to the named resource
Throws:
IOException - if I/O errors occur in the process
Since:
1.2

findSystemClass

protected final Class findSystemClass(String name)
            throws ClassNotFoundException
Helper to find a Class using the system classloader, possibly loading it. A subclass usually does not need to call this, if it correctly overrides findClass(String).
Parameters:
name - the name of the class to find
Returns:
the found class
Throws:
ClassNotFoundException - if the class cannot be found

getPackage

protected Package getPackage(String name)
Returns the Package object for the requested package name. It returns null when the package is not defined by this classloader or one of its parents.
Parameters:
name - the package name to find
Returns:
the package, if defined
Since:
1.2

getPackages

protected Package[] getPackages()
Returns all Package objects defined by this classloader and its parents.
Returns:
an array of all defined packages
Since:
1.2

getParent

public final ClassLoader getParent()
Returns the parent of this classloader. If the parent of this classloader is the bootstrap classloader then this method returns null. A security check may be performed on RuntimePermission("getClassLoader").
Returns:
the parent ClassLoader
Throws:
SecurityException - if the security check fails
Since:
1.2

getResource

public URL getResource(String name)
Get the URL to a resource using this classloader or one of its parents. First tries to get the resource by calling getResource() on the parent classloader. If the parent classloader returns null then it tries finding the resource by calling findResource() on this classloader. The resource name should be separated by '/' for path elements.

Subclasses should not override this method but should override findResource() which is called by this method.

Parameters:
name - the name of the resource relative to this classloader
Returns:
the URL to the resource or null when not found

getResourceAsStream

public InputStream getResourceAsStream(String name)
Get a resource as stream using this classloader or one of its parents. First calls getResource() and if that returns a URL to the resource then it calls and returns the InputStream given by URL.openStream().

Subclasses should not override this method but should override findResource() which is called by this method.

Parameters:
name - the name of the resource relative to this classloader
Returns:
an InputStream to the resource, or null
Since:
1.1

getResources

public Enumeration getResources(String name)
            throws IOException
Returns an Enumeration of all resources with a given name that can be found by this classloader and its parents. Certain classloaders (such as the URLClassLoader when given multiple jar files) can have multiple resources with the same name that come from multiple locations. It can also occur that a parent classloader offers a resource with a certain name and the child classloader also offers a resource with that same name. getResource() only offers the first resource (of the parent) with a given name. This method lists all resources with the same name. The name should use '/' as path separators.

The Enumeration is created by first calling getResources() on the parent classloader and then calling findResources() on this classloader.

Parameters:
name - the resource name
Returns:
an enumaration of all resources found
Throws:
IOException - if I/O errors occur in the process
Since:
1.2

getSystemClassLoader

public static ClassLoader getSystemClassLoader()
Returns the system classloader. The system classloader (also called the application classloader) is the classloader that is used to load the application classes on the classpath (given by the system property java.class.path. This is set as the context class loader for a thread. The system property java.system.class.loader, if defined, is taken to be the name of the class to use as the system class loader, which must have a public constructor which takes a ClassLoader as a parent. The parent class loader passed in the constructor is the default system class loader.

Note that this is different from the bootstrap classloader that actually loads all the real "system" classes (the bootstrap classloader is the parent of the returned system classloader).

A security check will be performed for RuntimePermission("getClassLoader") if the calling class is not a parent of the system class loader.

Returns:
the system class loader
Throws:
SecurityException - if the security check fails
IllegalStateException - if this is called recursively
Since:
1.2

getSystemResource

public static final URL getSystemResource(String name)
Get the URL to a resource using the system classloader.
Parameters:
name - the name of the resource relative to the system classloader
Returns:
the URL to the resource
Since:
1.1

getSystemResourceAsStream

public static final InputStream getSystemResourceAsStream(String name)
Get a resource using the system classloader.
Parameters:
name - the name of the resource relative to the system classloader
Returns:
an input stream for the resource, or null
Since:
1.1

getSystemResources

public static Enumeration getSystemResources(String name)
            throws IOException
Get an Enumeration of URLs to resources with a given name using the the system classloader. The enumeration firsts lists the resources with the given name that can be found by the bootstrap classloader followed by the resources with the given name that can be found on the classpath.
Parameters:
name - the name of the resource relative to the system classloader
Returns:
an Enumeration of URLs to the resources
Throws:
IOException - if I/O errors occur in the process
Since:
1.2

loadClass

public Class loadClass(String name)
            throws ClassNotFoundException
Load a class using this ClassLoader or its parent, without resolving it. Calls loadClass(name, false).

Subclasses should not override this method but should override findClass() which is called by this method.

Parameters:
name - the name of the class relative to this ClassLoader
Returns:
the loaded class
Throws:
ClassNotFoundException - if the class cannot be found

loadClass

protected Class loadClass(String name,
                             boolean resolve)
            throws ClassNotFoundException
Load a class using this ClassLoader or its parent, possibly resolving it as well using resolveClass(). It first tries to find out if the class has already been loaded through this classloader by calling findLoadedClass(). Then it calls loadClass() on the parent classloader (or when there is no parent it uses the VM bootclassloader). If the class is still not loaded it tries to create a new class by calling findClass(). Finally when resolve is true it also calls resolveClass() on the newly loaded class.

Subclasses should not override this method but should override findClass() which is called by this method.

Parameters:
name - the fully qualified name of the class to load
resolve - whether or not to resolve the class
Returns:
the loaded class
Throws:
ClassNotFoundException - if the class cannot be found

resolveClass

protected final void resolveClass(Class c)
Links the class, if that has not already been done. Linking basically resolves all references to other classes made by this class.
Parameters:
c - the class to resolve
Throws:
NullPointerException - if c is null

setClassAssertionStatus

public void setClassAssertionStatus(String name,
                                    boolean enabled)
Set the default assertion status for a class. This only affects the status of top-level classes, any other string is harmless.
Parameters:
name - the class to affect
enabled - true to set the default to enabled
Throws:
NullPointerException - if name is null
Since:
1.4

setDefaultAssertionStatus

public void setDefaultAssertionStatus(boolean enabled)
Set the default assertion status for classes loaded by this classloader, used unless overridden by a package or class request.
Parameters:
enabled - true to set the default to enabled
Since:
1.4

setPackageAssertionStatus

public void setPackageAssertionStatus(String name,
                                      boolean enabled)
Set the default assertion status for packages, used unless overridden by a class request. This default also covers subpackages, unless they are also specified. The unnamed package should use null for the name.
Parameters:
name - the package (and subpackages) to affect
enabled - true to set the default to enabled
Since:
1.4

setSigners

protected final void setSigners(Class c,
                                Object[] signers)
Helper to set the signers of a class. This should be called after defining the class.
Parameters:
c - the Class to set signers of
signers - the signers to set
Since:
1.1

ClassLoader.java -- responsible for loading classes into the VM Copyright (C) 1998, 1999, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc. This file is part of GNU Classpath. GNU Classpath is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. GNU Classpath is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with GNU Classpath; see the file COPYING. If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. Linking this library statically or dynamically with other modules is making a combined work based on this library. Thus, the terms and conditions of the GNU General Public License cover the whole combination. As a special exception, the copyright holders of this library give you permission to link this library with independent modules to produce an executable, regardless of the license terms of these independent modules, and to copy and distribute the resulting executable under terms of your choice, provided that you also meet, for each linked independent module, the terms and conditions of the license of that module. An independent module is a module which is not derived from or based on this library. If you modify this library, you may extend this exception to your version of the library, but you are not obligated to do so. If you do not wish to do so, delete this exception statement from your version.