Making the Most of WebLogic Classloaders @ WEBLOGIC JOURNAL

Making the Most of WebLogic Classloaders

As a Java developer, have you ever found yourself running into what might be politely called 'issues' related to the CLASSPATH and class loading? If you haven't, you're one of the few. This is one of the most notorious sources of developer aggravation in Java development. Now J2EE has added a new set of wrinkles to this phenomenon.

This article dispels some of the mystery of what's going on behind the classloader curtain and provides insights into how you can use this knowledge to your advantage when designing, packaging, and deploying your WebLogic Server applications. Important items we'll cover include a refresher on class-loading fundamentals you need to be aware of; how WebLogic's own custom classloaders build on these basics; the often misunderstood relationship between classloader hierarchies and EARs, EJBs, and WARs; techniques for packaging and deploying utility classes; and a simple but handy tool for diagnosing how classes are loaded within your applications.

Quick Classloader Review
Let's begin with a short review of how classloaders work: Classes are loaded when new bytecode is executed for the first time, either via a new class instance as in "MyClass x = new MyClass();" or by a first reference made to a static class, "MyStatic.staticMethod();". When this occurs, the JVM relies on classloaders - either the standard Java classloaders that ship with the runtime or custom classloaders - to load the bytecode in memory (all classloaders are subclasses of java.lang.ClassLoader). While there's a standard format for how the class is loaded in memory, where a classloader loads the bytecode from, be it from the file system (your typical .class files), an archive (JARs), a network socket (think applets and RMI), or even generated on the fly, is left to each classloader.

Nonetheless, there are certain rules all classloaders follow, many of which can ultimately impact your WebLogic applications. In particular, they:

Are hierarchical: As of JDK 1.2 all classloaders exist in parent-child relationships. Each classloader, other than the initial loader, has a parent classloader. The root parent classloader, built into the virtual machine, is called the "bootstrap" (or "primordial") classloader.

Can have siblings: Given that any classloader may have multiple child classloaders, it's possible for these children to have sibling classloaders at their same level in the hierarchy.

Delegate load requests: Before attempting to load classes themselves, children delegate all load requests to their parent. And each parent will delegate to its parent until reaching the root of the hierarchy. Only if any parent does not first resolve a request does a child attempt to load the requested class.

Have visibility constraints: Child classloaders, and the classes loaded by these loaders, have access to (or can "see") classes loaded by their parents, but parents cannot access classes loaded by their children nor can children see classes loaded by sibling classloaders (as with delegation, this only goes up the hierarchy, not down).

Cannot unload classes: Classes cannot be unloaded directly by their classloader, but classloaders themselves can be unloaded. This effectively unloads any classes loaded by that classloader. More about this soon.

Classloaders in a WebLogic Application
In order to support the J2EE standard and useful features such as hot deployment, WebLogic Server defines and initializes a number of its own custom classloaders. These classloaders work under the covers within the application server to manage loading and unloading your classes, EARs, EJBs, and WARs (and if you're interested in writing your own specialized classloader, you might want to take a look at Philip Aston's excellent article on this in April's WLDJ [Vol. 1, issue 4]).

Always keep in mind that class loading and deployment are inseparable. When you deploy your modules to WebLogic, each is typically loaded in its own dynamic classloader. If you're deploying a single EJB JAR file, it will get its own classloader. When you deploy a single WAR file, it gets one too. And when deploying an EAR file, WebLogic will create, depending on what's in your EAR file, an entire hierarchy of classloaders.

How does this work? What rules does WebLogic follow? The principal concept is that of application deployment units such as an EAR, an EJB, or a WAR. When any of these are deployed separately they are loaded in separate sibling classloaders. If EJBs and WARs are grouped into an EAR, they get a hierarchy of classloaders: at the top is the application classloader, which loads the EJBs and JARs referenced in its manifest file's classpath (more on this later), and then classloaders for each WAR file.

Figure 1 illustrates a sample WebLogic Server deployment. Each shadowed box in the WebLogic section represents an independent classloader instance. At the top level we have two EARs, one EJB JAR, and one WAR. Each of these is loaded by a sibling classloader. Within the first EAR are three EJB JARs (each with potentially multiple EJBs) and manifest-referenced utility files that share a single classloader and two Web applications that each get another classloader. Because of the established classloader hierarchy, the JSPs, servlets, and utility classes in both WARs can directly use any of those EJBs. In the second EAR, a simpler hierarchy allows the same interactions as the first, but these components are isolated from those in the first EAR.

In this arrangement, if either of the independently deployed modules, the EJB or the WAR, needs to access the other, this must be done via remote interfaces. This means that the EJB home and remote interfaces must be packaged into the calling modules and all communication may require more overhead than if they were packaged together (in which case WebLogic can perform various call optimizations such as using call-by-reference as it does for new EJB 2.0 local interfaces).

Table 1 lists the primary classloaders in a typical WebLogic EAR application. These are listed in order of creation from the primordial bootstrap classloader through various child classloaders down to the Web classloader. A couple of notes here: each of these classloaders may or may not be a distinct ClassLoader subtype or may be multiple instances of the same class configured differently. WebLogic may internally use additional classloaders (the details of which don't matter to us here); the native JVM classloaders are not set up to be reloadable but WebLogic's are (thus the familiar problem of having to reboot the application server if classes loaded by the non-reloadable classloaders have changed).

What This Means
The consequences of this classloading scheme include:

Isolation: The positive, deliberate side effect of the lack of sibling classloader visibility is isolation - classes loaded by different classloaders at the same level do not, and cannot, directly access one another without explicitly including the other's remote interfaces. You can see an advantage of this sand boxing by looking at how WebLogic handles EAR files: each is run in its own classloader instance and can be deployed and redeployed independently. This means that when you and I both deploy our separate applications to Server A, we can do so in parallel without worrying about a host of issues that might occur if we shared the same classloader. As the old adage goes, fences make for good neighbors.

Visibility: A key benefit of the hierarchical approach to classloader visibility is that JSPs, servlets, and other Web application components have direct access to all EJBs within the larger application. This both simplifies deployment and gives the application server more opportunities to optimize the performance of calls between components (covered in more detail below).

Namespaces: Class instances within the JVM are identified by the combination of the full classname and the classloader that loaded it. This namespace identification can come into play in your WebLogic applications. For example, think about how common it is for a Web application to start from a JSP or servlet with a standard name like index.jsp. That's fine. But what happens when you have two Web apps (two WAR files) within the same EAR and both of those apps have that innocuously named JSP or servlet? Without the benefit of classloader isolation, after the compiler finishes turning those source files into compiled servlets, a namespace or class-loading issue occurs because they both resolve to the same name, resulting in only one being loaded. Regardless of what happens in that scenario, it won't happen in WebLogic because each WAR is loaded in its own classloader and even if the JSPs or servlets have the same name, each exists independently as far as the classloaders are concerned.

Performance: Keep in mind that class loading, or more generally, packaging, impacts performance. Components deployed together in an EAR allow the WebLogic Server to optimize performance by reducing RMI call overhead as well as allowing you to use the new EJB 2.0 local interfaces. And it's through the default class-loading behavior (whereby loading is first deferred to parents as opposed to having each classloader load its own copy of the same class) that overall memory consumption is reduced.

Singletons: If you use the singleton design pattern in your application you need to be aware that classloaders matter because singletons (at least the run-of-the-mill, GoF design pattern variety such as those accessed with a getInstance-type method) exist not just within a single JVM but within a single classloader. Thus, if the singleton is loaded at the EAR level (such as from a utility library included at that level and not at the system-wide classpath level) by EAR 1 and EAR 2, then each application will get a different copy of that singleton. And there are of course other caveats to be aware of with singletons: clustering can throw a monkey wrench into the works, and in a world of distributed objects other patterns may be necessary, such as using JNDI to manage a singleton EJB (see some active discussions on this topic at www.theserverside.com).

Deployment: Regardless of how you deploy your application module - by using the console, by WebLogic's automatic hot deployment mode (quite useful during development), or through command-line utilities - the server will create a new classloader instance for loading this application. If you choose to deploy EJBs and WARs separately and you want your Web application to use those EJBs, you'll need to include the EJB home and remote interfaces in your WAR file. These are loaded by sibling classloaders and you'll need to make remote calls across them. Similarly, if you want to reference EJBs across EAR files you'll need to package the home and remote interfaces from the one EAR into the other (or you could try the approach of generating client JARs for your EJBs by using the ejb-client-jar tag in ejb-jar.xml and add references to those JARs in the manifest classpath - see below for more about the manifest).

Handling Utility Classes
Nearly every application, large or small, needs utility classes, either your own or from one or more third parties. Given what we've seen in looking at classloaders and packaging, where can and should these go? Table 2 outlines some of the choices you have as well as their attendant pros and cons.

To elaborate a bit on the last item in Table 2: because they are JAR files, all J2EE modules have a MANIFEST.MF file in their META-INF folder. The J2EE specification allows classes in one JAR - such as an EJB or WAR archive - to access other JARs by explicitly adding their names to a special "Class-Path:" entry in the manifest file (this is built upon the "extensions mechanism" introduced in JDK 1.2). By using this entry you can tailor EAR class-loading behavior and can modularly deal with many of the classpath issues mentioned earlier.

In order to make this work, first create a text file specifying a list of JAR filenames as relative URLs separated by spaces and then include this file when building your deployment. Here's what a typical entry might look like:

Manifest-Version: 1.0
Class-Path: myparser.jar vendorlib.jar

And here's an example of how you might add it when creating an EJB JAR (presuming you have the above line in a file called mymanifest.txt):

jar cmd mymanifest.txt myejb.jar com META-INF

Now the classes in myejb.jar have access to myparser.jar and vendorlib.jar because they've been loaded with this EJB JAR into its same classloader. Within the context of an EAR file, the JARs referenced within EJBs and WARs are loaded at the same level as EJBs and are available to all beans and Web modules within the application. (Note what happens: WebLogic takes the transitive closure of all manifest classpath entries specified in the EJB and WAR archives for a given EAR and loads them at the same top level within that EAR.)

Regardless of which classloaders and packaging technique you use, there's one other caveat worth mentioning and that's the issue of classloading order. Based upon the interdependencies among your utilities, JARs, EJBs, etc., you may find yourself needing to tailor what's placed where solely to satisfy load-time ordering. For example, utility classes needed by WebLogic itself, such as JDBC drivers, must be specified on the system classpath so that they're available when it starts. Complications can also arise in the case of startup classes and their dependencies (this is covered in more detail on BEA's site at http://edocs.bea.com/wls/docs61/programming/packaging.html).

Overall, here are a few general guidelines on utility classes: packaging in JAR files is generally more manageable than using individual class files. If the utilities are needed only by a single Web module then put them in a jar in its WEB-INF/lib folder; if the utilities are to be shared by multiple components or modules within a single application then keep them as a JAR at the application level; and finally, if you need to use the utility classes across applications, first try to use the manifest classpath approach and if that's not feasible, then use the global classpath. You can find a good discussion of this as well as J2EE packaging in Tyler Jewell's articles on this topic at www.onjava.com/pub/a/onjava/2001/06/26/ejb.html.

Debugging Class-Loading Issues
As with any other development issue, class loading at times needs to be debugged. Here are a few suggestions:

Plan: Invest some up-front effort in considering how many JARs to build (or WARs, EJB JARs, and EARs as the case may be), their names, their location, and which classes go into which archives.

Refactor: The layout and structure of this runtime packaging, like all software, can be refactored. In this case, refactoring means modifying and refining your implementation of the aforementioned packaging plan. Yes, this can take some effort, but so does any sort of refactoring (and because debugging class-loading issues are inherently "not fun" this serves as a deterrent to treating this step too lightly).

Diagnose:
- Walk through your shell environment, startup scripts, and configuration files to get a handle on what's being set where. Often it makes sense to consolidate setting file locations and paths in a single place such as one startup script (which itself does not assume any environment variables have been set or explicitly overrides them).
- Given that some things won't be apparent until runtime, have your run script print out to the console all settings prior to server launch.
- Write a simple Java debug routine that displays relevant values (including system properties such as "sun.boot.class.path").
- Use a tool like the JSP page described below.

As an example, say you have a utility class, MyHandler, which for some reason (deliberate or accidental) appears more than once in your environment; it could be that the version loaded at runtime may not be the one you expect. If in this scenario your servlet (in a WAR file) instantiates MyHandler and the only physical location of MyHandler.class is under the WEB-INF/classes directory of that WAR, then this will be the one that gets loaded. But, if you have another version of MyHandler.class somewhere on the system classpath, it will be this one that gets loaded, regardless of the fact that there's one right there in the same archive as your program.

Why does this happen? Because of classloader delegation. As noted earlier, all classloaders first delegate load requests to their parent, recursively up the tree, allowing each parent the opportunity to handle the request. In this case, because the system classloader was able to resolve this class reference, the child WAR classloader never had the chance to resolve and load this class itself. The nuances of such behaviors can appear to be quite idiosyncratic even if they're not and certainly vary across application servers and server versions. If you have multiple versions of the same libraries (such as might happen with common utilities such as XML parsers), be prepared to do a little investigating.

Also keep in mind that because standard classloaders (including WebLogic's) delegate all load requests to their parents before their own searches, anything deployed on the system classpath can't be redeployed. As just shown, these classes will always be loaded by the JDK system classloader, which does not support reloading. Thus, anything you want to be redeployable without having to restart the server must only be contained within one of the dynamically loadable units such as EARs, EJB-JARs, and WARs.

One last debugging note: Classes with no visibility modifier before the class declaration are deemed to be "package level" or "package private". In order for another class to access these classes, they must be in the same package and loaded by the same classloader. If this isn't the case, the caller will get an IllegalAccessException.

J2EE Class-Loading Diagnostic Tool
In order to diagnose and debug the subtleties of class-loading issues, I've developed a small JSP utility page. Just drop this JSP into your default Web app directory or include it with a specific application to run some quick tests. It has two primary functions: the first is to allow you to specify a class to load (typically a utility class, but it could be any class that can be instantiated with a direct newInstance() call) and show you the classloader that loaded your class, the classloader hierarchy of ancestors to that classloader, and the file from which your class was loaded.

The second function is to outline in a table a number of the standard locations searched by the various classloaders. This includes the locations searched by the standard Java classloaders (such as the CLASSPATH or, more specifically, the locations identified in the system properties). If you are running the server on your local machine and can click on the names of any JARs, you might want to open them and view the contents.

You can get a sense of what this tool provides from Figure 2. In this example, the page has been reloaded after I specified that I wanted my utility class, MyHandler, to be loaded. At the top it shows how and where it found this class, and below it shows an outline of each set of files and directories searched by various Java and WebLogic classloaders. [Two notes: 1) the ClassLoader method getParent() will return null to represent the bootstrap classloader, which explains why a specific classname isn't given in this case; and 2) this utility doesn't try to dig into things like the manifest files or other bean references so it may not display all references in the lower table].

When the tool is unable to locate one of the standard locations (such as WEB-INF/lib), it will print a "not found" message. In this case, the missing directory is perfectly acceptable given that those locations are optional. On the other hand, for items derived from your CLASSPATH, this can indicate a problem such as a JAR file that's specified in the environment but doesn't really exist at that location. This happens as JARs are moved around and can be a handy way to catch these errors (in the example pictured, under Application Classes the file Weblogic_sp.jar is not found - the right location for this should be determined or it should be removed from the classpath).

Conclusion
Keep in mind that the class-loading mechanisms described here are applicable to WebLogic Server 6.1 (and likely the final 7.0 release). These behaviors have changed over time as both WebLogic and the J2EE specification have evolved. Additionally, each application server vendor may implement its class-loading mechanisms differently as long as it conforms to the requirements outlined in the J2EE 1.3 specification. This means that other servers, while they may conform to the behavioral requirements defined by the J2EE spec, employ class-loading schemes that vary from that used by WebLogic.

Related Links

About John Musser
John Musser is an industry veteran with over 15 years of distributed systems experience ranging from development of real-time Wall Street trading systems to games for Electronic Arts. He has written on development techniques for books and magazines (such as Dr. Dobbs Journal, The C++ Report, Wireless Reporter, and John Wiley & Sons), as well as speaking at industry events. He is currently lead architect on a large-scale J2EE e-logistics system for a global shipping company. Bernhard Lenz is a senior computer consultant with expertise in analysis, design, programming, and technical management in various information systems fields. His clients are major Wall Street firms in brokerage, banking and insurance, all operating on distributed, component oriented and multi-tiered systems. He is currently working together with John Musser on a large-scale J2EE e-logistics global shipping system. Publications Dr. Dobbs Journal, The C++ Report, Wireless Reporter, and John Wiley & Sons