Java Class Loader
Java Class Loader
Java Class Loader
Table of Contents
If you're viewing this document online, you can click any of the topics below to link directly to that section.
1. Tutorial tips 2
2. Introduction 3
3. The ClassLoader structure 5
4. The CompilingClassLoader 8
5. ClassLoader changes in Java 2 10
6. The source code 12
7. Wrapup 17
This tutorial provides an overview of the Java ClassLoader and takes you through the
construction of an example ClassLoader that automatically compiles your code before loading
it. You'll learn exactly what a ClassLoader does and what you need to do to create your own.
A basic understanding of Java programming, including the ability to create, compile, and
execute simple command-line Java programs, as well as an understanding of the class file
paradigm is sufficient background to take this tutorial.
Getting help
For questions about the content of this tutorial, contact the author, Greg Travis, at
mito@panix.com .
Greg Travis is a freelance programmer living in New York City. His interest in computers can
be traced back to that episode of "The Bionic Woman" where Jamie is trying to escape a
building whose lights and doors are controlled by an evil artificial intelligence, which mocks her
through loudspeakers. Greg is a firm believer that, when a computer program works, it's a
complete coincidence.
Section 2. Introduction
What is a ClassLoader?
Among commercially popular programming languages, the Java language distinguishes itself
by running on a Java virtual machine (JVM). This means that compiled programs are
expressed in a special, platform-independent format, rather than in the format of the machine
they are running on. This format differs from traditional executable program formats in a
number of important ways.
In particular, a Java program, unlike one written in C or C++, isn't a single executable file, but
instead is composed of many individual class files, each of which corresponds to a single Java
class.
Additionally, these class files are not loaded into memory all at once, but rather are loaded on
demand, as needed by the program. The ClassLoader is the part of the JVM that loads classes
into memory.
The Java ClassLoader, furthermore, is written in the Java language itself. This means that it's
easy to create your own ClassLoader without having to understand the finer details of the JVM.
But one of the most innovative things about the Java language is that it makes it easy for the
JVM to get classes from places other than the local hard drive or network. For example,
browsers use a custom ClassLoader to load executable content from a Web site.
There are many other ways to get class files. Besides simply loading files from the local disk or
from a network, you can use a custom ClassLoader to:
* Automatically verify a digital signature before executing untrusted code
* Transparently decrypt code with a user-supplied password
* Create dynamically built classes customized to the user's specific needs
Anything you can think of to write that can generate Java bytecode can be integrated into your
application.
When Sun initially released the Java language, one of the most exciting things was watching
how this new technology executed code that it had loaded on the fly from a remote Web
server. (This was before we'd realized something more exciting -- that Java technology
provided a great language for writing code.) There was just something thrilling about it
executing bytecode that had just been sent through an HTTP connection from a distant Web
server.
What made this feat possible was the ability of the Java language to install a custom
ClassLoader. The appletviewer contains a ClassLoader that, instead of looking in the local
filesystem for classes, accesses a Web site on a remote server, loads the raw bytecode files
via HTTP, and turns them into classes inside the JVM.
The ClassLoaders in browsers and appletviewers do other things as well: they take care of
security and keep different applets on different pages from interfering with each other.
Echidna by Luke Gorrie is an open-source software package that allows you to safely run
multiple Java applications inside a single virtual machine. (See Further reading and references
on page 17.) It uses a custom ClassLoader to prevent the applications from interfering with
each other, by giving each application its own copy of the class files.
Note: Before we go any further, it's important to note that some aspects of the ClassLoader
system have been improved in JDK version 1.2 (also known as the Java 2 platform). This
tutorial was written with JDK versions 1.0 and 1.1 in mind, but everything in it works under later
versions as well.
ClassLoader changes in Java 2 on page 10describes the changes in Java version 1.2 and
provides details for modifying our ClassLoader to take advantage of these changes.
By overriding different methods corresponding to different stages of this process, you can
create a custom ClassLoader.
In the remainder of this section, you'll learn about the critical methods of the Java ClassLoader.
You'll find out what each one does and how it fits into the process of loading class files. You'll
also find out what code you'll need to write when creating your own ClassLoader.
In the next section, you'll put that knowledge to work with our example ClassLoader, the
CompilingClassLoader.
Method loadClass
ClassLoader.loadClass() is the entry point to the ClassLoader. Its signature is as
follows:
The name parameter specifies the name of the class that the JVM needs, in package notation,
such as Foo or java.lang.Object.
The resolve parameter tells the method whether or not the class needs to be resolved. You
can think of class resolution as the task of completely preparing the class for execution.
Resolution is not always needed. If the JVM needs only to determine that the class exists or to
find out what its superclass is, then resolution is not required.
In Java version 1.1 and earlier, the loadClass method is the only method that you need to
override to create a custom ClassLoader. (ClassLoader changes in Java 2 on page 10provides
information about the findClass() method available in Java 1.2.)
Method defineClass
The defineClass method is the central mystery of the ClassLoader. This method takes a
raw array of bytes and turns it into a Class object. The raw array contains the data that, for
example, was loaded from the filesystem or across the network.
aspects of the JVM -- it parses the bytecode format into a run-time data structure, checks for
validity, and so on. But don't worry, you don't have to write it yourself. In fact, you couldn't
override it even if you wanted to because it's marked as final.
Method findSystemClass
The findSystemClass method loads files from the local filesystem. It looks for a class file in
the local filesystem, and if it's there, turns it into a class using defineClass to convert raw
bytes into a Class object. This is the default mechanism for how the JVM normally loads
classes when you are running a Java application. (ClassLoader changes in Java 2 on page 10
provides details on changes to this process in Java version 1.2.)
For our custom ClassLoader, we'll use findSystemClass only after we've tried everything
else to load a class. The reason is simple: our ClassLoader is responsible for carrying out
special steps for loading classes, but not for all classes. For example, even if our ClassLoader
loads some classes from a remote Web site, there are still plenty of basic Java libraries on the
local machine that must also be loaded. These classes aren't our concern, so we ask the JVM
to load them in the default way: from the local filesystem. This is what findSystemClass
does.
In most custom ClassLoaders, you would want to call findSystemClass first to save time
spent looking on the remote Web site for the many Java library classes that are typically
loaded. However, as we'll see in the next section, we don't want to let the JVM load a class
from the local filesystem until we've made sure that we've automatically compiled our
application's code.
Method resolveClass
As I mentioned previously, loading a class can be done partially (without resolution) or
completely (with resolution). When we write our version of loadClass, we may need to call
resolveClass, depending on the value of the resolve parameter to loadClass.
Method findLoadedClass
findLoadedClass serves as a cache: when loadClass is asked to load a class, it can call
this method to see if the class has already been loaded by this ClassLoader, saving the trouble
of reloading a class that has already been loaded. This method should be called first.
Our example implementation of loadClass carries out the following steps. (We won't specify
here what special technique will be used to get the class file -- it might be loaded from the
Net, or pulled out of an archive, or compiled on the fly. Whatever it is, it's the special magic that
gets us our raw class file bytes.)
Taking stock
Now that you have a working knowledge of ClassLoaders, it's time to build one. In the next
section, we'll bring CCL to life.
* When a class is requested, see if it exists on disk, in the current directory, or in the
appropriate subdirectory.
* If the class is not available, but the source is, call the Java compiler to generate the class
file.
* If the class file does exist, check to see if it is older than its source code. If it is older than
the source, call the Java compiler to regenerate the class file.
* If the compilation fails, or if for any other reason the class file could not be generated from
the existing source, throw a ClassNotFoundException.
* If we still don't have the class, maybe it's in some other library, so call
findSystemClass to see if that will work.
* If we still don't have the class, throw a ClassNotFoundException.
* Otherwise, return the class.
The CCL will compile each class in our application, one by one, that needs to be compiled.
But, generally speaking, after the compiler compiles the first class, the CCL will find that all the
other classes that needed to be compiled have in fact been compiled. Why? The Java compiler
employs a rule similar to the one we are using: if a class doesn't exist or is out of date with
respect to its source, then it needs to be compiled. In essence, the Java compiler is one step
ahead of the CCL, and takes care of most of the work for it.
The CCL reports on what application classes it is compiling as it compiles them. In most cases,
you'll see it call the compiler on the main class in your program, and that will be all it does -- a
single invocation of the compiler is enough.
There is a case, however, in which some classes don't get compiled on the first pass. If you
load a class by name, using the Class.forName method, the Java compiler won't know that
this class is needed. In this case, you'll see the CCL run the Java compiler again to compile
this class. The example in The source code on page 12illustrates this process.
CCLRun is a special stub program that creates a CompilingClassLoader and uses it to load up
the main class of our program, ensuring that the entire program will be loaded through the
CompilingClassLoader. CCLRun uses the Java Reflection API to call the main method of the
specified class and to pass the arguments to it. For more details, see The source code on
page 12.
Example run
Included with the source is a set of small classes that illustrate how things work. The main
program is a class called Foo, which creates an instance of class Bar. Class Bar creates an
instance of another class called Baz, which is inside a package called baz in order to illustrate
that the CCL works with code in subpackages. Bar also loads a class by name, namely class
Boo, to illustrate this ability also works with the CCL.
Each class announces that it has been loaded and run. Use The source code on page 12and
try it out now. Compile CCLRun and CompilingClassLoader. Make sure you don't compile the
other classes (Foo, Bar, Baz, and Boo) or the CCL won't be of any use, because the classes
will already have been compiled.
Note that the first call to the compiler, for Foo.java, takes care of Bar and baz.Baz as well.
Boo doesn't get called until Bar tries to load it by name, at which point our CCL has to invoke
the compiler again to compile it.
The new model is a delegation model, which means that if your ClassLoader can't find a class,
it asks its parent ClassLoader to do it. At the root of all ClassLoaders is the system
ClassLoader, which loads classes the default way -- that is, from the local filesystem.
The default implementation of loadClass in Java 1.2 embodies the most common approach
to finding a class and lets you customize it by overriding the new findClass method, which
loadClass calls at the appropriate time.
The advantage of this approach is that you probably don't have to override loadClass; you
only have to override findClass, which is less work.
The parent of a ClassLoader is defined as the ClassLoader of the object containing the code
that created that ClassLoader.
// $Id$
import java.io.*;
/*
*/
// Create an array that's just the right size for the file's
// contents
byte raw[] = new byte[(int)len];
try {
// Try to compile it. If this doesn't work, then
// we must declare failure. (It's not good enough to use
// and already-existing, but out-of-date, classfile)
if (!compile( javaFilename ) || !classFile.exists()) {
throw new ClassNotFoundException( "Compile failed: "+javaFilename );
}
} catch( IOException ie ) {
CCRun.java
Here is the source code for CCRun.java
// $Id$
import java.lang.reflect.*;
/*
*/
// Create a CompilingClassLoader
CompilingClassLoader ccl = new CompilingClassLoader();
Foo.java
Here is the source code for Foo.java
// $Id$
Bar.java
Here is the source code for Bar.java
// $Id$
import baz.*;
try {
Class booClass = Class.forName( "Boo" );
Object boo = booClass.newInstance();
} catch( Exception e ) {
e.printStackTrace();
}
}
}
baz/Baz.java
Here is the source code for baz/Baz.java
// $Id$
package baz;
Boo.java
Here is the source code for Boo.java
// $Id$
Section 7. Wrapup
Wrapup
As you have seen in this short tutorial, knowing how to create a custom ClassLoader can really
help you get at the guts of the JVM. The ability to load class files from any source, or even to
generate them on the fly, can extend the reach of your JVM and allow you to do some really
interesting and powerful things.
* Security. Your ClassLoader could examine classes before they are handed off to the
JVM to see if they have a proper digital signature. You can also create a kind of
"sandbox" that disallows certain kinds of method calls by examining the source code and
rejecting classes that try to do things outside the sandbox.
* Encryption. It's possible to create a ClassLoader that decrypts on the fly, so that your
class files on disk are not readable by someone with a decompiler. The user must supply
a password to run the program, and the password is used to decrypt the code.
* Archiving. Want to distribute your code in a special format or with special compression?
Your ClassLoader can pull raw class file bytes from any source it wants.
* Self-extracting programs. It's possible to compile an entire Java application into a
single executable class file that contains compressed and/or encrypted class file data,
along with an integral ClassLoader; when the program is run, it unpacks itself entirely in
memory -- no need to install first.
* Dynamic generation. They sky's the limit here. You can generate classes that refer to
other classes that haven't been generated yet -- create entire classes on the fly and
bring them into the JVM without missing a beat.
* Read the online documentation for the ClassLoader class on the Sun Web site.
* The Java Developer Connection has a custom ClassLoader tutorial .
* Learn about class file loading in The Java Language Specification .
* The Java Virtual Machine Specification includes information about ClassLoaders .
* The JDK version 1.3 documentation has a list of core Java library classes that use
ClassLoaders.
* Echidna by Luke Gorrie is an example of a useful piece of software that depends on a
custom ClassLoader.
* " Create a Java 1.2-style custom ClassLoader " (JavaWorld, March 2000) provides
insight on building a ClassLoader under JDK 1.2.
* " Make classes from XML data " (developerWorks, August 2000) describes using a
custom ClassLoader to create new classes on the fly.
* If you are new to the Java platform, Java language essentials (developerWorks,
November 2000) provides a thorough guide to the platform fundamentals.
Your feedback
Please let us know whether this tutorial was helpful to you and how we could make it better.
We'd also like to hear about other tutorial topics you'd like to see covered. Thanks!
For questions about the content of this tutorial, contact the author, Greg Travis, at
mito@panix.com .
Colophon
This tutorial was written entirely in XML, using the developerWorks Toot-O-Matic tutorial
generator. The Toot-O-Matic tool is a short Java program that uses XSLT stylesheets to
convert the XML source into a number of HTML pages, a zip file, JPEG heading graphics, and
two PDF files. Our ability to generate multiple text and binary formats from a single source file
illustrates the power and flexibility of XML.