java.lang
Class ClassLoader

java.lang.Object
  java.lang.ClassLoader

Direct Known Subclasses:

BootClassLoader, DexClassLoader, PathClassLoader, SecureClassLoader, TestCaseClassLoader, TouchDexLoader

public abstract class ClassLoader
extends Object

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.

Since:

Android 1.0

See Also:

Class

Constructor Summary

protected	ClassLoader() Constructs a new instance of this class with the system class loader as its parent.
protected	ClassLoader(ClassLoader parentLoader) Constructs a new instance of this class with the specified class loader as its parent.

Method Summary

void	clearAssertionStatus() Sets the default assertion status for this class loader to false and removes any package default and class assertion status settings.
protected Class<?>	defineClass(byte[] classRep, int offset, int length) Deprecated. Use defineClass(String, byte[], int, int)
protected 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.
protected 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.
protected 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.
protected 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.
protected Class<?>	findClass(String className) Overridden by subclasses, throws a ClassNotFoundException by default.
protected String	findLibrary(String libName) Returns the absolute path of the native library with the specified name, or null.
protected 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.
protected URL	findResource(String resName) Finds the URL of the resource with the specified name.
protected Enumeration<URL>	findResources(String resName) Finds an enumeration of URLs for the resource with the specified name.
protected Class<?>	findSystemClass(String className) Finds the class with the specified name, loading it using the system class loader if necessary.
(package private) boolean	getClassAssertionStatus(String cname) Returns the assertion status of the named class Returns the assertion status of the class or nested class if it has been set.
(package private) boolean	getDefaultAssertionStatus() Returns the default assertion status
(package private) static Package	getPackage(ClassLoader loader, String name) Gets the package with the specified name, searching it in the specified class loader.
protected Package	getPackage(String name) Returns the package with the specified name.
(package private) boolean	getPackageAssertionStatus(String pname) Returns the assertion status of the named package Returns the assertion status of the named package or superpackage if that has been set.
protected Package[]	getPackages() Returns all the packages known to this class loader.
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.
(package private) Object[]	getSigners(Class<?> c) Gets the signers of the specified class.
(package private) static ClassLoader	getStackClassLoader(int depth) This must be provided by the VM vendor.
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.
(package private) boolean	isAncestorOf(ClassLoader child) Returns true if the receiver is ancestor of another class loader.
(package private) boolean	isSystemClassLoader() Indicates whether this class loader is the system class loader.
Class<?>	loadClass(String className) Loads the class with the specified name.
protected Class<?>	loadClass(String className, boolean resolve) Loads the class with the specified name, optionally linking it after loading.
(package private) static void	loadLibraryWithClassLoader(String libName, ClassLoader loader) This method must be provided by the VM vendor, as it is called by java.lang.System.loadLibrary().
(package private) static void	loadLibraryWithPath(String libName, ClassLoader loader, String libraryPath) This method must be provided by the VM vendor, as it is called by java.lang.System.load().
protected void	resolveClass(Class<?> clazz) Forces a class to be linked (initialized).
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 void	setSigners(Class<?> c, Object[] signers) Sets the signers of the specified class.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ClassLoader

protected ClassLoader()

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.

Since:

Android 1.0

ClassLoader

protected ClassLoader(ClassLoader parentLoader)

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.

Since:

Android 1.0

Method Detail

getSystemClassLoader

public static ClassLoader getSystemClassLoader()

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.

Since:

Android 1.0

getSystemResource

public static URL getSystemResource(String resName)

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.

Since:

Android 1.0

See Also:

Class.getResource(java.lang.String)

getSystemResources

public static Enumeration<URL> getSystemResources(String resName)
                                           throws IOException

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.

Since:

Android 1.0

getSystemResourceAsStream

public static InputStream getSystemResourceAsStream(String resName)

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.

Since:

Android 1.0

See Also:

Class.getResourceAsStream(java.lang.String)

defineClass

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

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.

Since:

Android 1.0

defineClass

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

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.

Since:

Android 1.0

defineClass

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

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.

Since:

Android 1.0

defineClass

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

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.

Since:

Android 1.0

findClass

protected Class<?> findClass(String className)
                      throws ClassNotFoundException

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.

Since:

Android 1.0

findLoadedClass

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

Parameters:

className - the name of the class to look for.

Returns:

the Class object or null if the requested class has not been loaded.

Since:

Android 1.0

findSystemClass

protected final Class<?> findSystemClass(String className)
                                  throws ClassNotFoundException

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.

Since:

Android 1.0

getParent

public final ClassLoader getParent()

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.

Since:

Android 1.0

getResource

public URL getResource(String resName)

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.

Since:

Android 1.0

See Also:

Class.getResource(java.lang.String)

getResources

public Enumeration<URL> getResources(String resName)
                              throws IOException

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.

Since:

Android 1.0

getResourceAsStream

public InputStream getResourceAsStream(String resName)

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.

Since:

Android 1.0

See Also:

Class.getResourceAsStream(java.lang.String)

loadClass

public Class<?> loadClass(String className)
                   throws ClassNotFoundException

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.

Since:

Android 1.0

loadClass

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

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.

Since:

Android 1.0

resolveClass

protected final void resolveClass(Class<?> clazz)

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.

Since:

Android 1.0

isSystemClassLoader

final boolean isSystemClassLoader()

Indicates whether this class loader is the system class loader. This method must be provided by the virtual machine vendor, as it is used by other provided class implementations in this package. A sample implementation of this method is provided by the reference implementation. This method is used by SecurityManager.classLoaderDepth(), currentClassLoader() and currentLoadedClass(). Returns true if the receiver is a system class loader.

Note that this method has package visibility only. It is defined here to avoid the security manager check in getSystemClassLoader, which would be required to implement this method anywhere else.

Returns:

true if the receiver is a system class loader

See Also:

Class.getClassLoaderImpl()

isAncestorOf

final boolean isAncestorOf(ClassLoader child)

Returns true if the receiver is ancestor of another class loader. It also returns true if the two class loader are equal.

Note that this method has package visibility only. It is defined here to avoid the security manager check in getParent, which would be required to implement this method anywhere else. The method is also required in other places where class loaders are accesses.

Parameters:

child - A child candidate

Returns:

true if the receiver is ancestor of, or equal to, the parameter

findResource

protected URL findResource(String resName)

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.

Since:

Android 1.0

findResources

protected Enumeration<URL> findResources(String resName)
                                  throws IOException

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.

Since:

Android 1.0

findLibrary

protected String findLibrary(String libName)

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.

Since:

Android 1.0

getPackage

protected Package getPackage(String name)

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.

Since:

Android 1.0

getPackage

static Package getPackage(ClassLoader loader,
                          String name)

Gets the package with the specified name, searching it in the specified class loader.

Parameters:

loader - the class loader to search the package in.

name - the name of the package to find.

Returns:

the package with the requested name; null if the package can not be found.

Since:

Android 1.0

getPackages

protected Package[] getPackages()

Returns all the packages known to this class loader.

Returns:

an array with all packages known to this class loader.

Since:

Android 1.0

definePackage

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

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.

Since:

Android 1.0

getSigners

final Object[] getSigners(Class<?> c)

Gets the signers of the specified class. This implementation returns null.

Parameters:

c - the Class object for which to get the signers.

Returns:

signers the signers of c.

Since:

Android 1.0

setSigners

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

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.

Since:

Android 1.0

getStackClassLoader

static final ClassLoader getStackClassLoader(int depth)

This must be provided by the VM vendor. It is used by SecurityManager.checkMemberAccess() with depth = 3. Note that checkMemberAccess() assumes the following stack when called:

          < user code &gt; <- want this class
          Class.getDeclared*();
          Class.checkMemberAccess();
          SecurityManager.checkMemberAccess(); <- current frame
 

Returns the ClassLoader of the method (including natives) at the specified depth on the stack of the calling thread. Frames representing the VM implementation of java.lang.reflect are not included in the list.

Notes:

• This method operates on the defining classes of methods on stack. NOT the classes of receivers.
• The item at depth zero is the caller of this method

Parameters:

depth - the stack depth of the requested ClassLoader

Returns:

the ClassLoader at the specified depth

loadLibraryWithClassLoader

static void loadLibraryWithClassLoader(String libName,
                                       ClassLoader loader)

This method must be provided by the VM vendor, as it is called by java.lang.System.loadLibrary(). System.loadLibrary() cannot call Runtime.loadLibrary() because this method loads the library using the ClassLoader of the calling method. Loads and links the library specified by the argument.

Parameters:

libName - the name of the library to load

loader - the classloader in which to load the library

Throws:

UnsatisfiedLinkError - if the library could not be loaded

SecurityException - if the library was not allowed to be loaded

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

loadLibraryWithPath

static void loadLibraryWithPath(String libName,
                                ClassLoader loader,
                                String libraryPath)

This method must be provided by the VM vendor, as it is called by java.lang.System.load(). System.load() cannot call Runtime.load() because the library is loaded using the ClassLoader of the calling method. Loads and links the library specified by the argument. No security check is done.

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

Parameters:

libName - the name of the library to load

loader - the classloader in which to load the library

libraryPath - the library path to search, or null

Throws:

UnsatisfiedLinkError - if the library could not be loaded

setClassAssertionStatus

public void setClassAssertionStatus(String cname,
                                    boolean enable)

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.

Since:

Android 1.0

setPackageAssertionStatus

public void setPackageAssertionStatus(String pname,
                                      boolean enable)

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.

Since:

Android 1.0

setDefaultAssertionStatus

public void setDefaultAssertionStatus(boolean enable)

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.

Since:

Android 1.0

clearAssertionStatus

public void clearAssertionStatus()

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.

Since:

Android 1.0

getClassAssertionStatus

boolean getClassAssertionStatus(String cname)

Returns the assertion status of the named class Returns the assertion status of the class or nested class if it has been set. Otherwise returns the assertion status of its package or superpackage if that has been set. Otherwise returns the default assertion status. Returns 1 for enabled and 0 for disabled.

Parameters:

cname - the name of class.

Returns:

the assertion status.

getPackageAssertionStatus

boolean getPackageAssertionStatus(String pname)

Returns the assertion status of the named package Returns the assertion status of the named package or superpackage if that has been set. Otherwise returns the default assertion status. Returns 1 for enabled and 0 for disabled.

Parameters:

pname - the name of package.

Returns:

the assertion status.

getDefaultAssertionStatus

boolean getDefaultAssertionStatus()

Returns the default assertion status

Returns:

the default assertion status.