Overview  Package   Class  Use  Deprecated  Index
Home >> All >> java >> [ lang overview ]	PREV CLASS  NEXT CLASS
SUMMARY:  JAVADOC |  SOURCE |  DOWNLOAD | NESTED | FIELD | CONSTR | METHOD	DETAIL: FIELD | CONSTR | METHOD

---

java.lang
Class ClassLoader  

java.lang.Object
  java.lang.ClassLoader

---

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 anonymous inner class of ClassLoader and a subclass of java.net.URLClassLoader.

Users of a ClassLoader will normally just use the methods

• loadClass() to load a class.
• getResource() or getResourceAsStream() to access a resource.
• getResources() to get an Enumeration of URLs to all the resources provided by the classloader and its parents with the same name.

Subclasses should implement the methods

• findClass() which is called by loadClass() when the parent classloader cannot provide a named class.
• findResource() which is called by getResource() when the parent classloader cannot provide a named resource.
• findResources() which is called by getResource() to combine all the resources with the same name from the classloader and its parents.
• findLibrary() which is called by Runtime.loadLibrary() when a class defined by the classloader wants to load a native library.

Since:

1.0

---

Nested Class Summary
(package private) static class	ClassLoader.StaticData

 

Field Summary
(package private)  java.util.Map	classAssertionStatus           The map of class assertion status overrides, or null if no class overrides have been specified yet.
(package private)  boolean	defaultAssertionStatus           The desired assertion status of classes loaded by this loader, if not overridden by package or class instructions.
(package private)  java.util.HashMap	definedPackages           All packages defined by this classloader.
private  boolean	initialized           This is true if this classloader was successfully initialized.
(package private)  java.util.Map	packageAssertionStatus           The map of package assertion status overrides, or null if no package overrides have been specified yet.
private  ClassLoader	parent           The classloader that is consulted before this classloader.
(package private)  Object	vmdata           VM private data.

 

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

 

Method Summary
private static void	addFileURL(java.util.ArrayList list, String file)
private  void	checkInitialized()           Before doing anything "dangerous" please call this method to make sure this class loader instance was properly constructed (and not obtained by exploiting the finalizer attack)
void	clearAssertionStatus()           Resets the default assertion status of this classloader, its packages and classes, all to false.
(package private) static ClassLoader	createAuxiliarySystemClassLoader(ClassLoader parent)
(package private) static ClassLoader	createExtClassLoader(java.net.URL[] urls, ClassLoader parent)
(package private) static ClassLoader	createSystemClassLoader(java.net.URL[] urls, ClassLoader parent)
(package private) static ClassLoader	defaultGetSystemClassLoader()
protected  Class	defineClass(byte[] data, int offset, int len)           Deprecated. use defineClass(String, byte[], int, int) 55 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, java.security.ProtectionDomain domain)           Helper to define a class using a string of bytes.
protected  Class	defineClass(String name, java.nio.ByteBuffer buf, java.security.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, java.net.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  java.net.URL	findResource(String name)           Called whenever a resource is needed that could not be provided by one of the parents of this classloader.
protected  java.util.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.
private static java.net.URL[]	getExtClassLoaderUrls()
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.
java.net.URL	getResource(String name)           Get the URL to a resource using this classloader or one of its parents.
java.io.InputStream	getResourceAsStream(String name)           Get a resource as stream using this classloader or one of its parents.
java.util.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.
private static java.net.URL[]	getSystemClassLoaderUrls()
static java.net.URL	getSystemResource(String name)           Get the URL to a resource using the system classloader.
static java.io.InputStream	getSystemResourceAsStream(String name)           Get a resource using the system classloader.
static java.util.Enumeration	getSystemResources(String name)           Get an Enumeration of URLs to resources with a given name using the the system classloader.
(package private)  boolean	isAncestorOf(ClassLoader loader)           Return true if this loader is either the specified class loader or an ancestor thereof.
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, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

 

Field Detail

definedPackages

final java.util.HashMap definedPackages

All packages defined by this classloader. It is not private in order to allow native code (and trusted subclasses) access to this field.

---

parent

private final ClassLoader parent

The classloader that is consulted before this classloader. If null then the parent is the bootstrap classloader.

---

initialized

private final boolean initialized

This is true if this classloader was successfully initialized. This flag is needed to avoid a class loader attack: even if the security manager rejects an attempt to create a class loader, the malicious class could have a finalize method which proceeds to define classes.

---

defaultAssertionStatus

boolean defaultAssertionStatus

The desired assertion status of classes loaded by this loader, if not overridden by package or class instructions.

---

packageAssertionStatus

java.util.Map packageAssertionStatus

The map of package assertion status overrides, or null if no package overrides have been specified yet. The values of the map should be Boolean.TRUE or Boolean.FALSE, and the unnamed package is represented by the null key. This map must be synchronized on this instance.

---

classAssertionStatus

java.util.Map classAssertionStatus

The map of class assertion status overrides, or null if no class overrides have been specified yet. The values of the map should be Boolean.TRUE or Boolean.FALSE. This map must be synchronized on this instance.

---

vmdata

transient Object vmdata

VM private data.

Constructor Detail

ClassLoader

protected ClassLoader()
               throws SecurityException

Create a new ClassLoader with as parent the system classloader. There may be a security check for checkCreateClassLoader.

---

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.

Since:

1.2

Method Detail

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.

---

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.

---

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.

Since:

1.2

---

defineClass

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

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

Helper to define a class using a string of bytes. This version is not secure.

---

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)).

Since:

1.1

---

defineClass

protected final Class defineClass(String name,
                                  byte[] data,
                                  int offset,
                                  int len,
                                  java.security.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.

Since:

1.2

---

defineClass

protected final Class defineClass(String name,
                                  java.nio.ByteBuffer buf,
                                  java.security.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.

Since:

1.5

---

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.

---

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).

---

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").

Since:

1.2

---

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.

Since:

1.1

---

findLoadedClass

protected final Class findLoadedClass(String name)

Helper to find an already-loaded class in this ClassLoader.

Since:

1.1

---

getResource

public java.net.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.

---

getResources

public java.util.Enumeration getResources(String name)
                                   throws java.io.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.

Since:

1.2

---

findResources

protected java.util.Enumeration findResources(String name)
                                       throws java.io.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.

Since:

1.2

---

findResource

protected java.net.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.

Since:

1.2

---

getSystemResource

public static final java.net.URL getSystemResource(String name)

Get the URL to a resource using the system classloader.

Since:

1.1

---

getSystemResources

public static java.util.Enumeration getSystemResources(String name)
                                                throws java.io.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.

Since:

1.2

---

getResourceAsStream

public java.io.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.

Since:

1.1

---

getSystemResourceAsStream

public static final java.io.InputStream getSystemResourceAsStream(String name)

Get a resource using the system classloader.

Since:

1.1

---

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.

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

Since:

1.2

---

definePackage

protected Package definePackage(String name,
                                String specTitle,
                                String specVendor,
                                String specVersion,
                                String implTitle,
                                String implVendor,
                                String implVersion,
                                java.net.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()).

Since:

1.2

---

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.

Since:

1.2

---

getPackages

protected Package[] getPackages()

Returns all Package objects defined by this classloader and its parents.

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).

Since:

1.2

---

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.

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.

Since:

1.4

---

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.

Since:

1.4

---

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

---

isAncestorOf

final boolean isAncestorOf(ClassLoader loader)

Return true if this loader is either the specified class loader or an ancestor thereof.

---

getExtClassLoaderUrls

private static java.net.URL[] getExtClassLoaderUrls()

---

addFileURL

private static void addFileURL(java.util.ArrayList list,
                               String file)

---

getSystemClassLoaderUrls

private static java.net.URL[] getSystemClassLoaderUrls()

---

defaultGetSystemClassLoader

static ClassLoader defaultGetSystemClassLoader()

---

createExtClassLoader

static ClassLoader createExtClassLoader(java.net.URL[] urls,
                                        ClassLoader parent)

---

createSystemClassLoader

static ClassLoader createSystemClassLoader(java.net.URL[] urls,
                                           ClassLoader parent)

---

createAuxiliarySystemClassLoader

static ClassLoader createAuxiliarySystemClassLoader(ClassLoader parent)

---

checkInitialized

private void checkInitialized()

Before doing anything "dangerous" please call this method to make sure this class loader instance was properly constructed (and not obtained by exploiting the finalizer attack)

---

Overview  Package   Class  Use  Deprecated  Index
Home >> All >> java >> [ lang overview ]	PREV CLASS  NEXT CLASS
SUMMARY:  JAVADOC |  SOURCE |  DOWNLOAD | NESTED | FIELD | CONSTR | METHOD	DETAIL: FIELD | CONSTR | METHOD

---