Many frameworks support plugins for increasing flexibility. They need to be loaded during runtime making it possible to change the supported features used in application without recompiling the framework and application themselves. Loading a plug-in means loading java classes, which is done by a class loader. We want to load the plug-ins from jar files, without providing a name for every JAR. Unfortunately, the java standard API does not contain a class loader for loading classes from a list of jar files in a directory. We need to provide it ourselves. In addition, the standard class loading mechanism is designed with following idea in mind: in runtime the application accesses the known classname, that is searched for in class path and loaded if found. In our case, we want to force the framework load it extensions, without setting up the class path before applications starts, which is a little different use case.

Simple JAR class loader

The first step is loading classes from jar files. For this purpose we create a class named JarFileClassLoader which should be able to load a class from a jar file. It inherits from ClassLoader, the Java default implementation for a class loader. Loading a class from a jar file means scanning each jar file entries, decide if it is a class then load it. Because we want to be flexible about the criterion we use to select our classes, we introduce an interface ICriterion, which decides for a given class if the criterion is fulfilled or not. Using this, the JarFileClassLoader can now scan a single jar file and load every class fulfilling the injected criterion. Loading a class means scanning the caches of the parent class loaders, calling the loadClass(String) method of the parents if not found and scanning the jar file afterwards if the class was still not found. This beahviour is described in a previous post, introducing the basics of Java Class Loading.

JarFileClassLoader is capable of loading a class if it does not reference other classes. These references have to be resolved during class loading time. Let consider the example of classes A and B where A references B. If A is loaded by a class loader CL, CL is asked for loading B also. This is done by calling the loadClass(String) method of CL. If B is contained in the jar file CL loads classes from, CL will find it and return it to the JVM. If B is not contained in CL’s jar file, CL’s parents are asked to load it. Thus the class will be loaded if it is contained in the classpath where one of the java class loaders will find it. If the class is contained in another jar file in the list, but not in the class path it will not be found and the loading will end with a ClassNotFoundException.

Plugin class loader

To tackle this problem we introduce another class, the PluginLoader. It contains a collection of JarFileClassLoaders and inherits from ClassLoader, thus is a ClassLoader itself. The PluginLoader acts as a parent for all JarFileClassLoaders and is therefore asked every time a class has to be loaded. It will then iterate over all JarFileClassLoaders calling the loadClass(String) method on all of them to find the class it looks for. This way, classes contained in sibling class loaders are found also without violating the rule that a class loader can only see classes of itself or its parents.

Putting everything together

Now the structure of our plug-in loader component becomes clear. What we additionally need to do, is get rid of all the stack overflows we produce with the above classes. The problem here is that any JarFileClassLoader asks its parent, the PluginLoader, to load a class. This will ask all child JarFileClassLoaders to load the class including the CL which asked the PluginLoader before. The result is an infinite call stack loop – a stack overflow. Therefore we relax the concept of the java class loading. We introduce a method loadClassSimple(String) on the JarFileClassLoaders which looks just in its very own jar file. If it does not find the wanted class it just throws an Exception without asking a parent or cache-lookups. This method is called by the PluginLoader only, therefore the rest of the class loading is not affected.

Last but not least we consider some performance issues. If a class is searched in other jar files, those have to be scanned every time again resulting in poor performance. Therefore we introduce a cache in the JarFileClassLoader containing every class that was loaded before. Every request is served now by trying to find the class in the cache first.

Limitations

Due to the fact, that PluginLoader asks its child JarClassLoaders to load a class in particuliar order, and the first class found will be taken, the order in which JarClassLoaders are asked matters. This issue can cause problems if e.G. different versions of the same library are deployed on location scanned by the PluginLoader and should be handled with care.

References

• [2007,book] bibtex
  G. Krueger and T. Stark, Handbuch der Java-Programmierung, , 2007.
  @book{2007_KRUEGER,
  author = {Guido Krueger and Thomas Stark},
  title = {Handbuch der Java-Programmierung},
  month = Nov, year = {2007},
  url = {http://www.javabuch.de/} publisher = {Addison-Wesley} isbn = {3-8273-2373-8}
}
• [,techreport] bibtex
  "Java Class Loading: The Basics,".
  @techreport{CL_BASICS author = {Brandon E. Taylor},
  title = {Java Class Loading: The Basics},
  url = {http://www.developer.com/java/other/article.php/2248831}

Class loader delegation

The loading of Java classes is performed by class loaders (CL), they are responsible for loading classes into the JVM. Simple applications can use the Java platform’s built-in class loading facility to load their classes, more complex applications tend to define their own custom class loaders.

The class loaders in Java are organized in a tree. By request a class loader determines if the class has already been loaded in the past, looking up in its own cache. If the class is present in the cache the CL returns the class, if not, it delegates the request to the parent. If the parent is not set (is Null) or can not load the class and throws a ClassNotFoundException the classloader tries to load the class itself and searches its own path for the class file. If the class can be loaded it is returned, otherwise a ClassNotFoundException is thrown. The cache lookup goes on recursively from child to parent, until the tree root is reached or a class is found in cache. If the root is reached the class loaders try to load the class and unfold the recursion from parent to child. Summarizing that we have following order:

• Cache
• Parent
• Self

This mechanism ensures that classes tending to be loaded by class loaders nearest to the root. Remember, that parent class loader is always has the opportunity to load a class first. It is important to ensure that core Java classes are loaded by the bootstrap loader, which guarantees that the correct versions of classes such as java.lang.Object are loaded. Furthermore it ensures, that one class loader sees only classes loaded by itself or its parent (or further ancestors) and it cannot see classes loaded by its children or siblings!

The picture illustrates the hierarchy of class loaders. Root loader is bootstrap class loader which has native implementation and cannot be instantiated by Java code.

It is followed by extension class loader, which is primary responsibility to load classes from the extension directories and provides ability to simply drop in new JVM extensions, without requiring modification to the user’s classpath. The system or application class loader responsible for loading classes from the path specified by the CLASSPATH environment variable. This class loader will be returned by the ClassLoader.getSystemClassLoader() method.

Phases of class loading

The are three phases of concrete class loading: physical loading, linking, and initializing.

1. In in first phase of physical loading required class file will be searched in specified classpaths. If the file is found it is read and the bytecode is loaded. This process gives a basic memory structure to the class object, such concepts like methods, fields, and other referenced classes are not known at this stage.
2. Linking can be broken down into three main stages, because it is complex phase:
   1. Bytecode verification through class loader, which executes a number of checks on the bytecodes.
   2. Class preparation. This stage prepares the necessary data structures that represent fields, methods and implemented interfaces that are defined within the class.
   3. Resolving of all the other classes referenced by a particular class. The classes can be referenced in a number of ways:
      • Superclasses
      • Interfaces
      • Field types
      • Types in method signatures
      • Types of local variables used in methods
3. During the initializing phase any static initializers contained within a class are executed so that, static fields are initialized to their default values.

It is interesting, that class loading can be performed in a lazy manner and therefore some parts of the class loading process may be done on first use of the class rather than at load time.

Exceptions

The biggest challenge in dealing with class-loading problems is that problems rarely manifest themselves during the class-loading process but rather during the usage of a class later on. In following shown two class loading related exceptions, with potential causes

• ClassNotFoundException
  • An archive, directory, or other source for the classes was not added to the class loader asked to load the class, or to its parent.
  • A class loader’s parent is not set correctly.
  • The wrong class loader is used to load the class in question.
• NoClassDefFoundError
  • An archive, directory, or other source for the classes was not added to the class loader asked to load the class, or to its parent.
  • A class loader’s parent is not set correctly.
  • Symbolic links in a class are unaccessible by the containing class’s class loader, such as a child class loader.

References:

• [2005,techreport] bibtex
  L. Shankar and S. Burns, "Demystifying class loading problems, Part 1: An introduction to class loading and debugging tools," 2005.
  @techreport{DW_2005_CLASSLOADING,
  author = {Lakshmi Shankar and Simon Burns},
  title = {Demystifying class loading problems, Part 1: An introduction to class loading and debugging tools},
  month = Nov, year = {2005},
  url = {http://www.ibm.com/developerworks/java/library/j-dclp1/index.html}
}

• [2004,techreport] bibtex
  A. Schaefer, "Inside Class Loaders: Debugging," 2004.
  @techreport{ONJAVA_2004_CLASSLOADING,
  author = {Andreas Schaefer},
  title = {Inside Class Loaders: Debugging},
  month = Jun, year = {2004},
  url = {http://www.onjava.com/pub/a/onjava/2004/06/30/classloader2.html}
}

• [2003,techreport] bibtex
  A. Schaefer, "Inside Class Loaders," 2003.
  @techreport{ONJAVA_2003_CLASSLOADING,
  author = {Andreas Schaefer},
  title = {Inside Class Loaders},
  month = Nov, year = {2003},
  url = {http://www.onjava.com/pub/a/onjava/2003/11/12/classloader.html}
}