|
JavaTM 2 Platform Std. Ed. v1.4.1 |
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--java.lang.ClassLoader
A class loader is an object that is responsible for loading
classes. The class ClassLoader
is an abstract class.
Given the name of a class, a class loader 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.
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 Class.getClassLoader()
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.
Applications implement subclasses of ClassLoader
in
order to extend the manner in which the Java virtual machine
dynamically loads classes.
Class loaders may typically be used by security managers to indicate security domains.
The ClassLoader
class uses a delegation model to
search for classes and resources. Each instance of
ClassLoader
has an associated parent class loader.
When called upon to find a class or resource, a
ClassLoader
instance will delegate the search for
the class or resource to its parent class loader before
attempting to find the class or resource itself. The virtual
machine's built-in class loader, called the bootstrap class loader,
does not itself have a parent but may serve as the parent of a
ClassLoader
instance.
Normally, the Java virtual machine loads classes from the local
file system in a platform-dependent manner. For example, on UNIX
systems, the virtual machine loads classes from the directory
defined by the CLASSPATH
environment variable.
However, some classes may not originate from a file; they may
originate from other sources, such as the network, or they could
be constructed by an application. The method
defineClass
converts an array of bytes into an
instance of class Class
. Instances of this newly
defined class can be created using the newInstance
method in class Class
.
The methods and constructors of objects created by a class loader
may reference other classes. To determine the class(es) referred
to, the Java virtual machine calls the loadClass
method of the class loader that originally created the class.
For example, an application could create a network class loader to download class files from a server. Sample code might look like:
ClassLoader loader = new NetworkClassLoader(host, port); Object main = loader.loadClass("Main", true).newInstance(); . . .
The network class loader subclass must define the methods
findClass
and loadClassData
to load a class from the network. Once it
has downloaded the bytes that make up the class, it should use the
method defineClass
to create a class instance. A
sample implementation is:
class NetworkClassLoader extends ClassLoader { String host; int port; public Class findClass(String name) { byte[] b = loadClassData(name); return defineClass(name, b, 0, b.length); } private byte[] loadClassData(String name) { // load the class data from the connection . . . } }
Class
,
Class.newInstance()
,
defineClass(byte[], int, int)
,
loadClass(java.lang.String, boolean)
,
resolveClass(java.lang.Class)
Constructor Summary | |
protected |
ClassLoader()
Creates a new class loader using the ClassLoader
returned by the method getSystemClassLoader() as the
parent class loader. |
protected |
ClassLoader(ClassLoader parent)
Creates a new class loader using the specified parent class loader for delegation. |
Method Summary | |
void |
clearAssertionStatus()
Sets the default assertion status for this class loader to false and discards any package defaults or class assertion status settings associated with the class loader. |
protected Class |
defineClass(byte[] b,
int off,
int len)
Deprecated. Replaced by defineClass(java.lang.String, byte[], int, int) |
protected Class |
defineClass(String name,
byte[] b,
int off,
int len)
Converts an array of bytes into an instance of class Class . |
protected Class |
defineClass(String name,
byte[] b,
int off,
int len,
ProtectionDomain protectionDomain)
Converts an array of bytes into an instance of class Class, with an optional ProtectionDomain. |
protected Package |
definePackage(String name,
String specTitle,
String specVersion,
String specVendor,
String implTitle,
String implVersion,
String implVendor,
URL sealBase)
Defines a package by name in this ClassLoader. |
protected Class |
findClass(String name)
Finds the specified class. |
protected String |
findLibrary(String libname)
Returns the absolute path name of a native library. |
protected Class |
findLoadedClass(String name)
Finds the class with the given name if it had been previously loaded through this class loader. |
protected URL |
findResource(String name)
Finds the resource with the given name. |
protected Enumeration |
findResources(String name)
Returns an Enumeration of URLs representing all the resources with the given name. |
protected Class |
findSystemClass(String name)
Finds a class with the specified name, loading it if necessary. |
protected Package |
getPackage(String name)
Returns a Package that has been defined by this class loader or any of its ancestors. |
protected Package[] |
getPackages()
Returns all of the Packages defined by this class loader and its ancestors. |
ClassLoader |
getParent()
Returns the parent class loader for delegation. |
URL |
getResource(String name)
Finds the resource with the given name. |
InputStream |
getResourceAsStream(String name)
Returns an input stream for reading the specified resource. |
Enumeration |
getResources(String name)
Finds all the resources with the given name. |
static ClassLoader |
getSystemClassLoader()
Returns the system class loader for delegation. |
static URL |
getSystemResource(String name)
Find a resource of the specified name from the search path used to load classes. |
static InputStream |
getSystemResourceAsStream(String name)
Open for reading, a resource of the specified name from the search path used to load classes. |
static Enumeration |
getSystemResources(String name)
Finds all resources of the specified name from the search path used to load classes. |
Class |
loadClass(String name)
Loads the class with the specified name. |
protected Class |
loadClass(String name,
boolean resolve)
Loads the class with the specified name. |
protected void |
resolveClass(Class c)
Links the specified class. |
void |
setClassAssertionStatus(String className,
boolean enabled)
Sets the desired assertion status for the named top-level class in this class loader and any nested classes contained therein. |
void |
setDefaultAssertionStatus(boolean enabled)
Sets the default assertion status for this class loader. |
void |
setPackageAssertionStatus(String packageName,
boolean enabled)
Sets the package default assertion status for the named package. |
protected void |
setSigners(Class c,
Object[] signers)
Sets the signers of a class. |
Methods inherited from class java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Constructor Detail |
protected ClassLoader(ClassLoader parent)
If there is a security manager, its checkCreateClassLoader
method is called. This may result in a security exception.
parent
- the parent class loader
SecurityException
- if a security manager exists and its
checkCreateClassLoader
method doesn't allow creation of a
new class loader.SecurityException
,
SecurityManager.checkCreateClassLoader()
protected ClassLoader()
ClassLoader
returned by the method getSystemClassLoader()
as the
parent class loader.
If there is a security manager, its checkCreateClassLoader
method is called. This may result in a security exception.
SecurityException
- if a security manager exists and its checkCreateClassLoader
method doesn't allow creation of a new class loader.SecurityException
,
SecurityManager.checkCreateClassLoader()
Method Detail |
public Class loadClass(String name) throws ClassNotFoundException
loadClass(String, boolean)
method. It is called by the Java virtual machine to resolve class
references. Calling this method is equivalent to calling
loadClass(name, false)
.
name
- the name of the class
Class
object
ClassNotFoundException
- if the class was not foundprotected Class loadClass(String name, boolean resolve) throws ClassNotFoundException
findLoadedClass(String)
to check if the class has
already been loaded.
loadClass
method on the parent class
loader. If the parent is null
the class loader
built-in to the virtual machine is used, instead.
findClass(String)
method to find the class.
resolve
flag is true, this method will then call the
resolveClass(Class)
method on the resulting class object.
From the Java 2 SDK, v1.2, subclasses of ClassLoader are
encouraged to override
findClass(String)
, rather than this method.
name
- the name of the classresolve
- if true
then resolve the class
Class
object
ClassNotFoundException
- if the class could not be foundprotected Class findClass(String name) throws ClassNotFoundException
loadClass
method after checking the parent class loader for the requested class.
The default implementation throws ClassNotFoundException
.
name
- the name of the class
Class
object
ClassNotFoundException
- if the class could not be foundprotected final Class defineClass(byte[] b, int off, int len) throws ClassFormatError
Class
. Before the Class can be used it must be
resolved. This method is deprecated in favor of the version
that takes the class name as its first argument, and is more
secure.
b
- the bytes that make up the class data. The bytes in
positions off
through off+len-1
should have the format of a valid class file as defined
by the
Java
Virtual Machine Specification.off
- the start offset in b
of the class datalen
- the length of the class data
Class
object that was created from the
specified class data
ClassFormatError
- if the data did not contain a valid class
IndexOutOfBoundsException
- if either off
or
len
is negative, or if
off+len
is greater than b.length
.loadClass(java.lang.String, boolean)
,
resolveClass(java.lang.Class)
protected final Class defineClass(String name, byte[] b, int off, int len) throws ClassFormatError
Class
.
Before the Class can be used it must be resolved.
This method assigns a default ProtectionDomain
to
the newly defined class. The ProtectionDomain
contains the set of permissions granted when
a call to Policy.getPolicy().getPermissions()
is made with
a code source of null,null
. The default domain is
created on the first invocation of defineClass
, and
re-used on subsequent calls.
To assign a specific ProtectionDomain
to the class,
use the defineClass
method that takes a
ProtectionDomain
as one of its arguments.
name
- the expected name of the class, or null
if not known, using '.' and not '/' as the separator
and without a trailing ".class" suffix.b
- the bytes that make up the class data. The bytes in
positions off
through off+len-1
should have the format of a valid class file as defined
by the
Java
Virtual Machine Specification.off
- the start offset in b
of the class datalen
- the length of the class data
Class
object that was created from the
specified class data
ClassFormatError
- if the data did not contain a valid class
IndexOutOfBoundsException
- if either off
or
len
is negative, or if
off+len
is greater than b.length
.
SecurityException
- if an attempt is made to add this class
to a package that contains classes that were signed by
a different set of certificates than this class (which
is unsigned), or if the class name begins with "java.".loadClass(java.lang.String, boolean)
,
resolveClass(java.lang.Class)
,
ProtectionDomain
,
Policy
,
CodeSource
,
SecureClassLoader
protected final Class defineClass(String name, byte[] b, int off, int len, ProtectionDomain protectionDomain) throws ClassFormatError
null
,
then a default domain will be assigned to the class as specified
in the documentation for defineClass(String,byte[],int,int)
.
Before the class can be used it must be resolved.
The first class defined in a package determines the exact set of
certificates that all subsequent classes defined in that package must
contain. The set of certificates for a class is obtained from the
CodeSource
within the ProtectionDomain
of
the class. Any classes added to that package must contain
the same set of certificates or a SecurityException
will be thrown. Note that if the name
argument is
null, this check is not performed. You should always pass in the
name of the class you are defining as well as the bytes. This
ensures that the class you are defining is indeed the class
you think it is.
The specified class name cannot begin with "java.", since all classes in the java.* packages can only be defined by the bootstrap class loader. If the name parameter is not null, it must be equal to the name of the class specified by the byte array b, otherwise a ClassFormatError is raised.
name
- the expected name of the class, or null
if not known, using '.' and not '/' as the separator
and without a trailing ".class" suffix.b
- the bytes that make up the class data. The bytes in
positions off
through off+len-1
should have the format of a valid class file as defined
by the
Java
Virtual Machine Specification.off
- the start offset in b
of the class datalen
- the length of the class dataprotectionDomain
- the ProtectionDomain of the class
Class
object created from the data,
and optional ProtectionDomain.
ClassFormatError
- if the data did not contain a valid class
IndexOutOfBoundsException
- if either off
or
len
is negative, or if
off+len
is greater than b.length
.
SecurityException
- if an attempt is made to add this class
to a package that contains classes that were signed by
a different set of certificates than this class, or if
the class name begins with "java.".protected final void resolveClass(Class c)
c
has already been linked,
then this method simply returns. Otherwise, the class is linked
as described in the "Execution" chapter of the Java Language
Specification.
c
- the class to link
NullPointerException
- if c
is null
.defineClass(java.lang.String,byte[],int,int)
protected final Class findSystemClass(String name) throws ClassNotFoundException
Prior to the Java 2 SDK, this method loads a class from the local file system in a platform-dependent manner, and returns a class object that has no associated class loader.
Since the Java 2 SDK v1.2, this method loads the class through the
system class loader(see getSystemClassLoader()
). Class objects
returned might have ClassLoader
s associated with them.
Subclasses of ClassLoader
need not usually call this
method, because most class loaders need to override just findClass(String)
.
name
- the name of the class that is to be found
Class
object for the specified
name
ClassNotFoundException
- if the class could not be foundClassLoader(ClassLoader)
,
getParent()
public final ClassLoader getParent()
null
to represent the bootstrap class
loader. This method will return null
in such
implementations if this class loader's parent is the bootstrap
class loader.
If a security manager is present, and the caller's class loader is
not null and is not an ancestor of this class loader, then
this method calls the security manager's checkPermission
method with a RuntimePermission("getClassLoader")
permission to ensure it's ok to access the parent class loader.
If not, a SecurityException
will be thrown.
ClassLoader
SecurityException
- if a security manager exists and its
checkPermission
method doesn't allow
access to this class loader's parent class loader.SecurityManager.checkPermission(java.security.Permission)
,
RuntimePermission
protected final void setSigners(Class c, Object[] signers)
c
- the Class
objectsigners
- the signers for the classprotected final Class findLoadedClass(String name)
name
- the class name
Class
object, or null
if
the class has not been loadedpublic URL getResource(String name)
The name of a resource is a "/"-separated path name that identifies the resource.
This method will first search the parent class loader for the resource;
if the parent is null
the path of the class loader
built-in to the virtual machine is searched. That failing, this method
will call findResource
to find the resource.
name
- resource name
null
if
the resource could not be found or the caller doesn't have
adequate privileges to get the resource.findResource(String)
public final Enumeration getResources(String name) throws IOException
The name of a resource is a "/"-separated path name that identifies the resource.
The search order is described in the documentation for getResource(String)
.
name
- resource name
IOException
- if I/O errors occurgetResource(java.lang.String)
,
findResources(java.lang.String)
protected Enumeration findResources(String name) throws IOException
name
- the resource name
IOException
- if I/O errors occurprotected URL findResource(String name)
name
- the resource name
null
if the resource could not be foundpublic static URL getSystemResource(String name)
In JDK1.1, the search path used is that of the virtual machine's built-in class loader.
Since the Java 2 SDK v1.2, this method locates the resource through the system class
loader (see getSystemClassLoader()
).
name
- the resource name
null
if
the resource could not be foundpublic static Enumeration getSystemResources(String name) throws IOException
Enumeration
of URL
objects.
The search order is described in the documentation for getSystemResource(String)
.
name
- the resource name
IOException
- if I/O errors occurpublic InputStream getResourceAsStream(String name)
getResource(String)
.
name
- the resource name
null
if the resource could not be foundpublic static InputStream getSystemResourceAsStream(String name)
The search order is described in the documentation for getSystemResource(String)
.
name
- the resource name
null
if the resource could not be foundpublic static ClassLoader getSystemClassLoader()
ClassLoader
instances, and
is typically the class loader used to start the application.
This method is first invoked early in the runtime's startup sequence, at which point it creates the system class loader and sets it as the context class loader of the invoking Thread.
The default system class loader is an implementation-dependent instance of this class.
If the system property java.system.class.loader is defined when this method is first invoked then the value of that property is taken to be the name of a class that will be returned as the system class loader. The class is loaded using the default system class loader and must define a public constructor that takes a single parameter of type ClassLoader which is used as the delegation parent. An instance is then created using this constructor with the default system class loader as the parameter. The resulting class loader is defined to be the system class loader.
If a security manager is present, and the caller's class loader is
not null and the caller's class loader is not 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 it's ok to access the system class loader.
If not, a SecurityException
will be thrown.
ClassLoader
for delegation, or
null
if none
SecurityException
- if a security manager exists and its
checkPermission
method doesn't allow
access to the system class loader.
IllegalStateException
- if invoked recursively during the construction
of the class loader specified by the
java.system.class.loader
property.
Error
- if the system property java.system.class.loader
is defined but the named class could not be loaded, the
provider class does not define the required constructor, or an
exception is thrown by that constructor when it is invoked. The
underlying cause of the error can be retrieved via the
Throwable.getCause()
method.SecurityManager.checkPermission(java.security.Permission)
,
RuntimePermission
protected Package definePackage(String name, String specTitle, String specVersion, String specVendor, String implTitle, String implVersion, String implVendor, URL sealBase) throws IllegalArgumentException
name
- the package namespecTitle
- the specification titlespecVersion
- the specification versionspecVendor
- the specification vendorimplTitle
- the implementation titleimplVersion
- the implementation versionimplVendor
- the implementation vendorsealBase
- If not null, then this package is sealed with
respect to the given code source URL. Otherwise,
the package is not sealed.
Package
object
IllegalArgumentException
- if package name duplicates an
existing package either in this class loader or one of
its ancestorsprotected Package getPackage(String name)
name
- the package name
protected Package[] getPackages()
Package
objects defined by this
ClassLoader
protected String findLibrary(String libname)
null
, the VM searches the library along the path
specified as the java.library.path
property.
libname
- the library name
System.loadLibrary(java.lang.String)
,
System.mapLibraryName(java.lang.String)
public void setDefaultAssertionStatus(boolean enabled)
setPackageAssertionStatus(String,boolean)
or setClassAssertionStatus(String,boolean)
.
enabled
- true if classes loaded by this class loader
will henceforth have assertions enabled by default,
false if they will have assertions disabled by default.public void setPackageAssertionStatus(String packageName, boolean enabled)
A subpackage of a package named p is any package whose name begins with "p." . For example, javax.swing.text is a subpackage of javax.swing, and both java.util and java.lang.reflect are subpackages of java.
In the event that multiple package defaults apply to a given class, the package default pertaining to the most specific package takes precedence over the others. For example, if javax.lang and javax.lang.reflect both have package defaults associated with them, the latter package default applies to classes in javax.lang.reflect.
Package defaults take precedence over the class loader's default
assertion status, and may be overridden on a per-class basis by
invoking setClassAssertionStatus(String,boolean)
.
packageName
- the name of the package whose package default
assertion status is to be set. A null value
indicates the unnamed package that is "current"
(JLS 7.4.2).enabled
- true if classes loaded by this classloader
and belonging to the named package or any of its subpackages
will have assertions enabled by default, false if they
will have assertions disabled by default.public void setClassAssertionStatus(String className, boolean enabled)
If the named class is not a top-level class, this call will have no effect on the actual assertion status of any class, and its return value is undefined.
className
- the fully qualified class name of the top-level class
whose assertion status is to be set.enabled
- true if the named class is to have assertions
enabled when (and if) it is initialized, false if the
class is to have assertions disabled.public void clearAssertionStatus()
|
JavaTM 2 Platform Std. Ed. v1.4.1 |
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
Copyright 2002 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.