This four-part article series examines Java class loading to help application developers understand and debug problems they may encounter. In Part 2, authors Lakshmi Shankar and Simon Burns from the IBM Hursley Labs tackle some exceptions that, while fairly simple, often puzzle novice and experienced Java developers alike.

This article, the second in a series of four, looks at the various class loading exceptions typically thrown when running applications. These exceptions, though commonly seen, are often not well understood by Java developers. Taking each exception in turn, this article provides detailed examples that highlight their behavior, explain their causes, and show some possible resolution techniques. The article starts with the very common ClassNotFoundException and moves onto less well known exceptions, such as ExceptionInInitializerError.

Before you begin this article, you should be familiar with the class loader delegation model, along with the phases and stages of class linking.

ClassNotFoundException
ClassNotFoundException is the most common type of class loading exception. It occurs during the loading phase. The Java specification describes ClassNotFoundException as follows:

Thrown when an application tries to load in a class through its string name using:

• The forName() method in class Class.
• The findSystemClass method() in class ClassLoader.
• The loadClass() method in class ClassLoader.

So a ClassNotFoundException is thrown if an explicit attempt to load a class fails. The test case in Listing 1 provides example code that throws a ClassNotFoundException:

Listing 1. ClassNotFoundExceptionTest.java

import java.net.MalformedURLException;
import java.net.URL;
import java.net.URLClassLoader;
public class ClassNotFoundExceptionTest {

    public static void main(String args[]) {
      try {
        URLClassLoader loader = new URLClassLoader(new URL[] { new URL(
"file://C:/CL_Article/ClassNotFoundException/")});
        loader.loadClass("DoesNotExist");
      } catch (ClassNotFoundException e) {
        e.printStackTrace();
      } catch (MalformedURLException e) {
        e.printStackTrace();
      }
    }
}

This test case defines a class loader (MyClassLoader), which is used to load a non-existent class (DoesNotExist). When it is run, the following exception occurs:

java.lang.ClassNotFoundException: DoesNotExist
      at java.net.URLClassLoader.findClass(URLClassLoader.java:376)
      at java.lang.ClassLoader.loadClass(ClassLoader.java:572)
      at java.lang.ClassLoader.loadClass(ClassLoader.java:504)
      at
ClassNotFoundExceptionTest.main(ClassNotFoundExceptionTest.java:11)

A ClassNotFoundException is thrown because the test attempts the load using an explicit call to loadClass().

By throwing a ClassNotFoundException, the class loader informs you that the bytecode required to define the class is simply not present in the locations where the class loader is looking for it. These exceptions are usually simple to fix. You can ensure that the classpath being used is set as expected by checking it using the IBM verbose option. (For more on this option, see the first article in this series.) If the classpath is set correctly but you're still seeing the error, then the desired class is not present on the classpath. To fix this, either move the class into a directory or JAR file specified in the classpath, or add the location where the class is stored to the classpath.

NoClassDefFoundError
NoClassDefFoundError is another common exception thrown by the class loader during the loading phase. The JVM specification defines NoClassDefFoundError as follows:

Thrown if the Java virtual machine or a ClassLoader instance tries to load in the definition of a class (as part of a normal method call or as part of creating a new instance using the new expression) and no definition of the class could be found.

The searched-for class definition existed when the currently executing class was compiled, but the definition can no longer be found.

Essentially, this means that a NoClassDefFoundError is thrown as a result of a unsuccessful implicit class load. The test case in Listings 2 through 4 produce a NoClassDefFoundError because an implicit load of class B will fail:

Listing 2. NoClassDefFoundErrorTest.java

public class NoClassDefFoundErrorTest {
    public static void main(String[] args) {
       A a = new A();
    }
}

Listing 3. A.java

public class A extends B {
}

Listing 4. B.java

public class B {
}

Once you've compiled the code in these listings, remove the classfile for B. When the code is executed, the following error occurs:

Exception in thread "main" java.lang.NoClassDefFoundError: B
    at java.lang.ClassLoader.defineClass0(Native Method)
    at java.lang.ClassLoader.defineClass(ClassLoader.java:810)
    at
java.security.SecureClassLoader.defineClass(SecureClassLoader.java:147)
    at java.net.URLClassLoader.defineClass(URLClassLoader.java:475)
    at java.net.URLClassLoader.access$500(URLClassLoader.java:109)
    at java.net.URLClassLoader$ClassFinder.run(URLClassLoader.java:848)
    at java.security.AccessController.doPrivileged1(Native Method)
    at
java.security.AccessController.doPrivileged(AccessController.java:389)
    at java.net.URLClassLoader.findClass(URLClassLoader.java:371)
    at java.lang.ClassLoader.loadClass(ClassLoader.java:572)
    at sun.misc.Launcher$AppClassLoader.loadClass(Launcher.java:442)
    at java.lang.ClassLoader.loadClass(ClassLoader.java:504)
    at NoClassDefFoundErrorTest.main(NoClassDefFoundErrorTest.java:3)

Class A extends class B; so, when class A is being loaded, the class loader implicitly loads class B. Because class B is not present, a NoClassDefFoundError is thrown. If the class loader had been explicitly told to load class B (by a loadClass("B") call, for instance), a ClassNotFoundException would have been thrown instead.

Obviously, to fix the problem in this particular example, class B must be present on the classpath of a suitable class loader. This example may seem trivial and unrealistic; however, in complex, real-world systems with many classes, situations like this can happen when classes are missed during packaging or deployment.

In this example, A extends B; however, the same error would still occur if A referenced B in any other way -- as a method parameter, for example, or as an instance field. If the relationship between the two classes were one of reference rather than of inheritance, then the error would be thrown on the first active use of A, rather than during the loading of A.