|
JavaTM 2 Platform Std. Ed. v1.3.1 |
|||||||||
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 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 classClass
objectClassNotFoundException
- 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 classClass
objectClassNotFoundException
- 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 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 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 foundClass
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 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 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 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
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 nameSystem.loadLibrary(java.lang.String)
,
System.mapLibraryName(java.lang.String)
|
JavaTM 2 Platform Std. Ed. v1.3.1 |
|||||||||
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 Oracle and/or its affiliates, in the US and other countries.
Copyright © 1995, 2010 Oracle and/or its affiliates. All rights reserved.