|
JavaTM 2 Platform Std. Ed. v1.3 |
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
java.lang.Object | +--java.lang.ClassLoader
The class ClassLoader is an abstract class.
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.
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 | |
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. |
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 loaderSecurityException - 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.
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.
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 classClass objectClassNotFoundException - if the class was not found
protected 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 classClass objectClassNotFoundException - if the class could not be found
protected 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 classClass objectClassNotFoundException - if the class could not be found
protected 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 of the class datalen - the length of the class dataClass object that was created from the
specified class dataClassFormatError - if the data did not contain a valid classloadClass(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 Codesource 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 of the class datalen - the length of the class dataClass object that was created from the
specified class dataClassFormatError - if the data did not contain a valid classIndexOutOfBoundsException - 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 then this class, which
is unsigned.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.
name - the name of the classb - the class bytesoff - the start offset of the class byteslen - the length of the class bytesprotectionDomain - the ProtectionDomain of the classClass object created from the data,
and optional ProtectionDomain.ClassFormatError - if the data did not contain a valid classIndexOutOfBoundsException - 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 linkNullPointerException - 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 ClassLoaders 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 foundClass object for the specified
nameClassNotFoundException - 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.
ClassLoaderSecurityException - 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 nameClass 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 namenull 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 nameIOException - if I/O errors occurgetResource(java.lang.String),
findResources(java.lang.String)
protected Enumeration findResources(String name)
throws IOException
name - the resource nameIOException - if I/O errors occurprotected URL findResource(String name)
name - the resource namenull
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 namenull if
the resource could not be found
public 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 nameIOException - if I/O errors occurpublic InputStream getResourceAsStream(String name)
getResource(String).name - the resource namenull
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 namenull
if the resource could not be foundpublic static ClassLoader getSystemClassLoader()
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
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 noneSecurityException - if a security manager exists and its
checkPermission method doesn't allow
access to the system class loader.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 objectIllegalArgumentException - if package name duplicates an
existing package either in this class loader or one of
its ancestorsprotected Package getPackage(String name)
name - the package nameprotected Package[] getPackages()
Package objects defined by this
ClassLoaderprotected String findLibrary(String libname)
null, the VM searches the library along the path
specified as the java.library.path property.libname - the library nameSystem.loadLibrary(java.lang.String),
System.mapLibraryName(java.lang.String)
|
JavaTM 2 Platform Std. Ed. v1.3 |
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
Java, Java 2D, and JDBC are trademarks or registered trademarks of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2000 Sun Microsystems, Inc. 901 San Antonio Road
Palo Alto, California, 94303, U.S.A. All Rights Reserved.