20.14 The Class java.lang.ClassLoader

A class loader is an object that is responsible for loading classes. Given the name of a class, it should attempt to locate or generate data that constitutes a definition for the class. A typical strategy is to transform the name into a file name and then read a "class file" of that name from a file system.

Every Class object contains a reference to the ClassLoader that defined it (§20.3.7). Whenever executable Java code needs to use a class that has not yet been loaded, the loadClass method is invoked for the class loader of the class containing the code in question.

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 the getClassLoader method of class Class (§20.3.7), 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.

Class loaders may typically be used by security managers (§20.17) to indicate security domains: two classes may considered to be "friendly" or "related" to each other only if they were defined by the same class loader.

public abstract class ClassLoader {
	protected ClassLoader()

		throws SecurityException;
	protected abstract Class loadClass(String name,
		      boolean resolve)

		throws ClassNotFoundException;
	protected final Class defineClass(byte data[],
		      int offset, int length)

		throws NullPointerException, IndexOutOfBoundsException,
			ClassFormatError;
	protected final void resolveClass(Class c);
	protected final Class findSystemClass(String name)

		throws ClassNotFoundException;
}

20.14.1 protected ClassLoader() throws SecurityException

This constructor is invoked for every newly created class loader. Because the class ClassLoader is abstract, it is not possible to create a new instance of the class ClassLoader itself; however, every constructor for a subclass of ClassLoader necessarily invokes this constructor, explicitly or implicitly, directly or indirectly.

All this constructor does is to enforce a security check: if there is a security manager, its checkCreateClassLoader method (§20.17.10) is called.

20.14.2 protected abstract Class loadClass(String name,
boolean link)
throws ClassNotFoundException

Every subclass of ClassLoader that is not itself abstract must provide an implementation of the method loadClass.

The general contract of loadClass is that, given the name of a class, it either returns the Class object for the class or throws a ClassNotFoundException.

If a Class object is to be returned and link is true, then the Class object should be linked (§12.3, §20.14.4) before it is returned.

In most cases, it is wise for a subclass of ClassLoader (§20.14) to implement the loadClass method as a synchronized method.

20.14.3 protected final Class defineClass(byte data[],
int offset, int length)
throws NullPointerException, IndexOutOfBoundsException, ClassFormatError

This method may be used by a class loader to define a new class.

The bytes in the array data in positions offset through offset+length-1 should have the format of a valid class file as defined by the Java Virtual Machine Specification.

If data is null, then a NullPointerException is thrown.

An IndexOutOfBoundsException is thrown if any of the following are true:

• offset is negative
• length is negative
• offset+length is greater than data.length

If the indicated bytes of data do not constitute a valid class definition, then a ClassFormatError is thrown. Otherwise, this method creates and returns a Class object as described by the data bytes

20.14.4 protected final void resolveClass(Class c)
throws NullPointerException

This (misleadingly named) method may be used by a class loader to link (§12.3, §20.14.4) a class.

If c is null, then a NullPointerException is thrown.

If the Class object c has already been linked, then this method simply returns.

Otherwise, the class is linked as described in §12.3.

20.14.5 protected final Class findSystemClass(String name)
throws ClassNotFoundException

This method may be used by a class loader to locate a class that has no class loader. This includes built-in classes such as java.lang.Object, as well as classes that the host implementation may keep in, for example, a local file system.

Given the name of a class, this method, like the loadClass method, either returns the Class object for the class or throws a ClassNotFoundException.