public abstract class

ClassLoader

extends Object
java.lang.Object
   ↳ java.lang.ClassLoader
Known Direct Subclasses
Known Indirect Subclasses

Class Overview

Loads classes and resources from a repository. One or more class loaders are installed at runtime. These are consulted whenever the runtime system needs a specific class that is not yet available in-memory. Typically, class loaders are grouped into a tree where child class loaders delegate all requests to parent class loaders. Only if the parent class loader cannot satisfy the request, the child class loader itself tries to handle it.

ClassLoader is an abstract class that implements the common infrastructure required by all class loaders. Android provides several concrete implementations of the class, with PathClassLoader being the one typically used. Other applications may implement subclasses of ClassLoader to provide special ways for loading classes.

See Also

Summary

Protected Constructors
ClassLoader()
Constructs a new instance of this class with the system class loader as its parent.
ClassLoader(ClassLoader parentLoader)
Constructs a new instance of this class with the specified class loader as its parent.
Public Methods
void clearAssertionStatus()
Sets the default assertion status for this class loader to false and removes any package default and class assertion status settings.
final ClassLoader getParent()
Returns this class loader's parent.
URL getResource(String resName)
Returns the URL of the resource with the specified name.
InputStream getResourceAsStream(String resName)
Returns a stream for the resource with the specified name.
Enumeration<URL> getResources(String resName)
Returns an enumeration of URLs for the resource with the specified name.
static ClassLoader getSystemClassLoader()
Returns the system class loader.
static URL getSystemResource(String resName)
Finds the URL of the resource with the specified name.
static InputStream getSystemResourceAsStream(String resName)
Returns a stream for the resource with the specified name.
static Enumeration<URL> getSystemResources(String resName)
Returns an enumeration of URLs for the resource with the specified name.
Class<?> loadClass(String className)
Loads the class with the specified name.
void setClassAssertionStatus(String cname, boolean enable)
Sets the assertion status of the class with the specified name.
void setDefaultAssertionStatus(boolean enable)
Sets the default assertion status for this class loader.
void setPackageAssertionStatus(String pname, boolean enable)
Sets the assertion status of the package with the specified name.
Protected Methods
final Class<?> defineClass(byte[] classRep, int offset, int length)
This method is deprecated. Use defineClass(String, byte[], int, int)
final Class<?> defineClass(String name, ByteBuffer b, ProtectionDomain protectionDomain)
Defines a new class with the specified name, byte code from the byte buffer and the optional protection domain.
final Class<?> defineClass(String className, byte[] classRep, int offset, int length, ProtectionDomain protectionDomain)
Constructs a new class from an array of bytes containing a class definition in class file format and assigns the specified protection domain to the new class.
final Class<?> defineClass(String className, byte[] classRep, int offset, int length)
Constructs a new class from an array of bytes containing a class definition in class file format.
Package definePackage(String name, String specTitle, String specVersion, String specVendor, String implTitle, String implVersion, String implVendor, URL sealBase)
Defines and returns a new Package using the specified information.
Class<?> findClass(String className)
Overridden by subclasses, throws a ClassNotFoundException by default.
String findLibrary(String libName)
Returns the absolute path of the native library with the specified name, or null.
final Class<?> findLoadedClass(String className)
Returns the class with the specified name if it has already been loaded by the virtual machine or null if it has not yet been loaded.
URL findResource(String resName)
Finds the URL of the resource with the specified name.
Enumeration<URL> findResources(String resName)
Finds an enumeration of URLs for the resource with the specified name.
final Class<?> findSystemClass(String className)
Finds the class with the specified name, loading it using the system class loader if necessary.
Package getPackage(String name)
Returns the package with the specified name.
Package[] getPackages()
Returns all the packages known to this class loader.
Class<?> loadClass(String className, boolean resolve)
Loads the class with the specified name, optionally linking it after loading.
final void resolveClass(Class<?> clazz)
Forces a class to be linked (initialized).
final void setSigners(Class<?> c, Object[] signers)
Sets the signers of the specified class.
[Expand]
Inherited Methods
From class java.lang.Object

Protected Constructors

protected ClassLoader ()

Since: API Level 1

Constructs a new instance of this class with the system class loader as its parent.

Throws
SecurityException if a security manager exists and it does not allow the creation of a new ClassLoader.

protected ClassLoader (ClassLoader parentLoader)

Since: API Level 1

Constructs a new instance of this class with the specified class loader as its parent.

Parameters
parentLoader The ClassLoader to use as the new class loader's parent.
Throws
SecurityException if a security manager exists and it does not allow the creation of new a new ClassLoader.

Public Methods

public void clearAssertionStatus ()

Since: API Level 1

Sets the default assertion status for this class loader to false and removes any package default and class assertion status settings.

Note: This method does nothing in the Android reference implementation.

public final ClassLoader getParent ()

Since: API Level 1

Returns this class loader's parent.

Returns
  • this class loader's parent or null.
Throws
SecurityException if a security manager exists and it does not allow to retrieve the parent class loader.

public URL getResource (String resName)

Since: API Level 1

Returns the URL of the resource with the specified name. This implementation first tries to use the parent class loader to find the resource; if this fails then findResource(String) is called to find the requested resource.

Parameters
resName the name of the resource to find.
Returns
  • the URL object for the requested resource or null if either the resource can not be found or a security manager does not allow to access the resource.
See Also

public InputStream getResourceAsStream (String resName)

Since: API Level 1

Returns a stream for the resource with the specified name. See getResource(String) for a description of the lookup algorithm used to find the resource.

Parameters
resName the name of the resource to find.
Returns
  • a stream for the resource or null if either the resource can not be found or a security manager does not allow to access the resource.
See Also

public Enumeration<URL> getResources (String resName)

Since: API Level 1

Returns an enumeration of URLs for the resource with the specified name. This implementation first uses this class loader's parent to find the resource, then it calls findResources(String) to get additional URLs. The returned enumeration contains the URL objects of both find operations.

Parameters
resName the name of the resource to find.
Returns
  • an enumeration of URL objects for the requested resource.
Throws
IOException if an I/O error occurs.

public static ClassLoader getSystemClassLoader ()

Since: API Level 1

Returns the system class loader. This is the parent for new ClassLoader instances and is typically the class loader used to start the application. If a security manager is present and the caller's class loader is neither null nor the same as or an ancestor of the system class loader, then this method calls the security manager's checkPermission method with a RuntimePermission("getClassLoader") permission to ensure that it is ok to access the system class loader. If not, a SecurityException is thrown.

Returns
  • the system class loader.
Throws
SecurityException if a security manager exists and it does not allow access to the system class loader.

public static URL getSystemResource (String resName)

Since: API Level 1

Finds the URL of the resource with the specified name. The system class loader's resource lookup algorithm is used to find the resource.

Parameters
resName the name of the resource to find.
Returns
  • the URL object for the requested resource or null if the resource can not be found.
See Also

public static InputStream getSystemResourceAsStream (String resName)

Since: API Level 1

Returns a stream for the resource with the specified name. The system class loader's resource lookup algorithm is used to find the resource. Basically, the contents of the java.class.path are searched in order, looking for a path which matches the specified resource.

Parameters
resName the name of the resource to find.
Returns
  • a stream for the resource or null.
See Also

public static Enumeration<URL> getSystemResources (String resName)

Since: API Level 1

Returns an enumeration of URLs for the resource with the specified name. The system class loader's resource lookup algorithm is used to find the resource.

Parameters
resName the name of the resource to find.
Returns
  • an enumeration of URL objects containing the requested resources.
Throws
IOException if an I/O error occurs.

public Class<?> loadClass (String className)

Since: API Level 1

Loads the class with the specified name. Invoking this method is equivalent to calling loadClass(className, false).

Note: In the Android reference implementation, the second parameter of loadClass(String, boolean) is ignored anyway.

Parameters
className the name of the class to look for.
Returns
  • the Class object.
Throws
ClassNotFoundException if the class can not be found.

public void setClassAssertionStatus (String cname, boolean enable)

Since: API Level 1

Sets the assertion status of the class with the specified name.

Note: This method does nothing in the Android reference implementation.

Parameters
cname the name of the class for which to set the assertion status.
enable the new assertion status.

public void setDefaultAssertionStatus (boolean enable)

Since: API Level 1

Sets the default assertion status for this class loader.

Note: This method does nothing in the Android reference implementation.

Parameters
enable the new assertion status.

public void setPackageAssertionStatus (String pname, boolean enable)

Since: API Level 1

Sets the assertion status of the package with the specified name.

Note: This method does nothing in the Android reference implementation.

Parameters
pname the name of the package for which to set the assertion status.
enable the new assertion status.

Protected Methods

protected final Class<?> defineClass (byte[] classRep, int offset, int length)

Since: API Level 1

This method is deprecated.
Use defineClass(String, byte[], int, int)

Constructs a new class from an array of bytes containing a class definition in class file format.

Parameters
classRep the memory image of a class file.
offset the offset into classRep.
length the length of the class file.
Returns
  • the Class object created from the specified subset of data in classRep.
Throws
ClassFormatError if classRep does not contain a valid class.
IndexOutOfBoundsException if offset < 0, length < 0 or if offset + length is greater than the length of classRep.

protected final Class<?> defineClass (String name, ByteBuffer b, ProtectionDomain protectionDomain)

Since: API Level 1

Defines a new class with the specified name, byte code from the byte buffer and the optional protection domain. If the provided protection domain is null then a default protection domain is assigned to the class.

Parameters
name the expected name of the new class, may be null if not known.
b the byte buffer containing the byte code of the new class.
protectionDomain the protection domain to assign to the loaded class, may be null.
Returns
  • the Class object created from the data in b.
Throws
ClassFormatError if b does not contain a valid class.
NoClassDefFoundError if className is not equal to the name of the class contained in b.

protected final Class<?> defineClass (String className, byte[] classRep, int offset, int length, ProtectionDomain protectionDomain)

Since: API Level 1

Constructs a new class from an array of bytes containing a class definition in class file format and assigns the specified protection domain to the new class. If the provided protection domain is null then a default protection domain is assigned to the class.

Parameters
className the expected name of the new class, may be null if not known.
classRep the memory image of a class file.
offset the offset into classRep.
length the length of the class file.
protectionDomain the protection domain to assign to the loaded class, may be null.
Returns
  • the Class object created from the specified subset of data in classRep.
Throws
ClassFormatError if classRep does not contain a valid class.
IndexOutOfBoundsException if offset < 0, length < 0 or if offset + length is greater than the length of classRep.
NoClassDefFoundError if className is not equal to the name of the class contained in classRep.

protected final Class<?> defineClass (String className, byte[] classRep, int offset, int length)

Since: API Level 1

Constructs a new class from an array of bytes containing a class definition in class file format.

Parameters
className the expected name of the new class, may be null if not known.
classRep the memory image of a class file.
offset the offset into classRep.
length the length of the class file.
Returns
  • the Class object created from the specified subset of data in classRep.
Throws
ClassFormatError if classRep does not contain a valid class.
IndexOutOfBoundsException if offset < 0, length < 0 or if offset + length is greater than the length of classRep.

protected Package definePackage (String name, String specTitle, String specVersion, String specVendor, String implTitle, String implVersion, String implVendor, URL sealBase)

Since: API Level 1

Defines and returns a new Package using the specified information. If sealBase is null, the package is left unsealed. Otherwise, the package is sealed using this URL.

Parameters
name the name of the package.
specTitle the title of the specification.
specVersion the version of the specification.
specVendor the vendor of the specification.
implTitle the implementation title.
implVersion the implementation version.
implVendor the specification vendor.
sealBase the URL used to seal this package or null to leave the package unsealed.
Returns
  • the Package object that has been created.
Throws
IllegalArgumentException if a package with the specified name already exists.

protected Class<?> findClass (String className)

Since: API Level 1

Overridden by subclasses, throws a ClassNotFoundException by default. This method is called by loadClass after the parent ClassLoader has failed to find a loaded class of the same name.

Parameters
className the name of the class to look for.
Returns
  • the Class object that is found.
Throws
ClassNotFoundException if the class cannot be found.

protected String findLibrary (String libName)

Since: API Level 1

Returns the absolute path of the native library with the specified name, or null. If this method returns null then the virtual machine searches the directories specified by the system property "java.library.path".

This implementation always returns null.

Parameters
libName the name of the library to find.
Returns
  • the absolute path of the library.

protected final Class<?> findLoadedClass (String className)

Since: API Level 1

Returns the class with the specified name if it has already been loaded by the virtual machine or null if it has not yet been loaded.

Parameters
className the name of the class to look for.
Returns
  • the Class object or null if the requested class has not been loaded.

protected URL findResource (String resName)

Since: API Level 1

Finds the URL of the resource with the specified name. This implementation just returns null; it should be overridden in subclasses.

Parameters
resName the name of the resource to find.
Returns
  • the URL object for the requested resource.

protected Enumeration<URL> findResources (String resName)

Since: API Level 1

Finds an enumeration of URLs for the resource with the specified name. This implementation just returns an empty Enumeration; it should be overridden in subclasses.

Parameters
resName the name of the resource to find.
Returns
  • an enumeration of URL objects for the requested resource.
Throws
IOException if an I/O error occurs.

protected final Class<?> findSystemClass (String className)

Since: API Level 1

Finds the class with the specified name, loading it using the system class loader if necessary.

Parameters
className the name of the class to look for.
Returns
  • the Class object with the requested className.
Throws
ClassNotFoundException if the class can not be found.

protected Package getPackage (String name)

Since: API Level 1

Returns the package with the specified name. Package information is searched in this class loader.

Parameters
name the name of the package to find.
Returns
  • the package with the requested name; null if the package can not be found.

protected Package[] getPackages ()

Since: API Level 1

Returns all the packages known to this class loader.

Returns
  • an array with all packages known to this class loader.

protected Class<?> loadClass (String className, boolean resolve)

Since: API Level 1

Loads the class with the specified name, optionally linking it after loading. The following steps are performed:

  1. Call findLoadedClass(String) to determine if the requested class has already been loaded.
  2. If the class has not yet been loaded: Invoke this method on the parent class loader.
  3. If the class has still not been loaded: Call findClass(String) to find the class.

Note: In the Android reference implementation, the resolve parameter is ignored; classes are never linked.

Parameters
className the name of the class to look for.
resolve Indicates if the class should be resolved after loading. This parameter is ignored on the Android reference implementation; classes are not resolved.
Returns
  • the Class object.
Throws
ClassNotFoundException if the class can not be found.

protected final void resolveClass (Class<?> clazz)

Since: API Level 1

Forces a class to be linked (initialized). If the class has already been linked this operation has no effect.

Note: In the Android reference implementation, this method has no effect.

Parameters
clazz the class to link.

protected final void setSigners (Class<?> c, Object[] signers)

Since: API Level 1

Sets the signers of the specified class. This implementation does nothing.

Parameters
c the Class object for which to set the signers.
signers the signers for c.